directions

Direction labels and symbols are locale-aware — they depend on the current locale set via setLocale. Each direction has a label (full name) and a symbol (abbreviated form), and comparisons are case-insensitive.

Two behaviours differ across this module:

• Display helpers (getDirections, getNorth, getSouth, getEast, getWest) use the current locale only.
• Validation predicates (isValidDirection, isNorth, isSouth, isEast, isWest, getDirectionAxis) accept the current locale plus the fallback (en). A hard-coded 'W' is therefore a valid direction even under the fr locale (where West is displayed as 'O'). See getActiveLocales for the exact set considered.

getDirections

Signature

getDirections (axis = null)

Description

Returns the list of cardinal directions for a given axis, or all four directions if no axis is provided. Uses the current locale.

Parameters

Name	Type	Required	Description
axis	string	no	An axis value from AXES. If provided, filters directions to that axis

Returns

Type	Description
object[]	Array of direction objects, each with label and symbol properties

Throws

Throws if axis is provided but is not a valid axis.

Examples

// All directions
getDirections()
// [{ label: 'South', symbol: 'S' }, { label: 'North', symbol: 'N' }, { label: 'East', symbol: 'E' }, { label: 'West', symbol: 'W' }]

// Latitude directions only
getDirections(AXES.LATITUDE)
// [{ label: 'South', symbol: 'S' }, { label: 'North', symbol: 'N' }]

// Longitude directions only
getDirections(AXES.LONGITUDE)
// [{ label: 'East', symbol: 'E' }, { label: 'West', symbol: 'W' }]

getNorth / getSouth / getEast / getWest

Signature

getNorth ()
getSouth ()
getEast ()
getWest ()

Description

Returns the direction object for the corresponding cardinal direction in the current locale.

Returns

Type	Description
object	Direction object with label and symbol properties

Examples

getNorth()   // { label: 'North', symbol: 'N' }
getSouth()   // { label: 'South', symbol: 'S' }
getEast()    // { label: 'East', symbol: 'E' }
getWest()    // { label: 'West', symbol: 'W' }

setLocale('fr')
getWest()    // { label: 'Ouest', symbol: 'O' }

isValidDirection

Signature

isValidDirection (dir)

Description

Returns true if dir matches any cardinal direction (North, South, East, or West), either by label or symbol, in the current locale or the fallback (en). The comparison is case-insensitive.

Parameters

Name	Type	Required	Description
dir	string	yes	Value to check

Returns

Type	Description
boolean	true if the value is a recognized direction

Throws

Throws if dir is not a string.

Examples

isValidDirection('N')      // true
isValidDirection('North')  // true
isValidDirection('north')  // true
isValidDirection('X')      // false

setLocale('fr')
isValidDirection('O')      // true — current locale (Ouest)
isValidDirection('W')      // true — en fallback

isNorth / isSouth / isEast / isWest

Signature

isNorth (dir)
isSouth (dir)
isEast (dir)
isWest (dir)

Description

Returns true if dir matches the corresponding cardinal direction, either by label or symbol, in the current locale or the fallback (en). The comparison is case-insensitive.

Parameters

Name	Type	Required	Description
dir	string	yes	Value to check

Returns

Type	Description
boolean	true if the value matches the direction

Throws

Throws if dir is not a string.

Examples

isNorth('N')       // true
isNorth('North')   // true
isNorth('north')   // true
isNorth('S')       // false

isSouth('S')       // true
isEast('E')        // true
isWest('W')        // true

setLocale('fr')
isWest('O')        // true — current locale (Ouest)
isWest('W')        // true — en fallback

getDirectionAxis

Signature

getDirectionAxis (dir)

Description

Returns the axis associated with a cardinal direction. East and West map to AXES.LONGITUDE, North and South map to AXES.LATITUDE. Recognizes directions from the current locale or the fallback (en).

Parameters

Name	Type	Required	Description
dir	string	yes	A recognized cardinal direction label or symbol

Returns

Type	Description
string	An axis value from AXES

Throws

Throws if dir is not a valid direction.

Examples

getDirectionAxis('N')   // 'LAT'
getDirectionAxis('S')   // 'LAT'
getDirectionAxis('E')   // 'LON'
getDirectionAxis('W')   // 'LON'

setLocale('fr')
getDirectionAxis('O')   // 'LON' — Ouest

getDirectionSymbols

Signature

getDirectionSymbols(axis = null)

Description

Returns the direction symbols recognized for the specified axis across all active locales.

When no axis is specified, symbols for all directions are returned.

Parameters

Name	Type	Required	Description
axis	string | null	no	Axis used to filter direction symbols (longitude or latitude), or null for all directions

Returns

Type	Description
string[]	The recognized direction symbols

Examples

getDirectionSymbols('longitude')
// ['E', 'W', ...]

getDirectionSymbols('latitude')
// ['N', 'S', ...]

getDirectionSymbols()
// ['N', 'S', 'E', 'W', ...]