Direction Utilities API

Direction constants and utility methods for parsing and manipulation.

Direction Constants

Built-in direction constants for spatial navigation.

import { Direction } from '@motioneffector/spatial'

// Compass directions
Direction.NORTH      // 'NORTH'
Direction.NORTHEAST  // 'NORTHEAST'
Direction.EAST       // 'EAST'
Direction.SOUTHEAST  // 'SOUTHEAST'
Direction.SOUTH      // 'SOUTH'
Direction.SOUTHWEST  // 'SOUTHWEST'
Direction.WEST       // 'WEST'
Direction.NORTHWEST  // 'NORTHWEST'

// Vertical directions
Direction.UP         // 'UP'
Direction.DOWN       // 'DOWN'

// Special directions
Direction.IN         // 'IN'
Direction.OUT        // 'OUT'

Direction.opposite()

Returns the opposite direction.

Signature:

Direction.opposite(direction: Direction): Direction | null

Parameters:

Returns: Direction | null — Opposite direction, or null for custom directions without opposite

Example:

Direction.opposite('NORTH')      // 'SOUTH'
Direction.opposite('SOUTH')      // 'NORTH'
Direction.opposite('EAST')       // 'WEST'
Direction.opposite('WEST')       // 'EAST'
Direction.opposite('NORTHEAST')  // 'SOUTHWEST'
Direction.opposite('UP')         // 'DOWN'
Direction.opposite('IN')         // 'OUT'

// Custom direction without opposite
Direction.opposite('WARP')       // null

Direction.parse()

Parses a string into a Direction constant.

Signature:

Direction.parse(input: string): Direction | null

Parameters:

Returns: Direction | null — Parsed direction, or null if invalid

Example:

// Full names
Direction.parse('north')      // 'NORTH'
Direction.parse('NORTH')      // 'NORTH'
Direction.parse('North')      // 'NORTH'

// Abbreviations
Direction.parse('n')          // 'NORTH'
Direction.parse('ne')         // 'NORTHEAST'
Direction.parse('e')          // 'EAST'
Direction.parse('se')         // 'SOUTHEAST'
Direction.parse('s')          // 'SOUTH'
Direction.parse('sw')         // 'SOUTHWEST'
Direction.parse('w')          // 'WEST'
Direction.parse('nw')         // 'NORTHWEST'
Direction.parse('u')          // 'UP'
Direction.parse('d')          // 'DOWN'

// Special
Direction.parse('in')         // 'IN'
Direction.parse('out')        // 'OUT'

// Invalid
Direction.parse('invalid')    // null
Direction.parse('')           // null

registerDirection()

Registers a custom direction with its opposite mapping.

Signature:

graph.registerDirection(direction: string, options: RegisterDirectionOptions): void

Parameters:

Returns: void

Example:

// Self-opposite (portal)
graph.registerDirection('PORTAL', { opposite: 'PORTAL' })

// Paired opposites
graph.registerDirection('CLIMB', { opposite: 'DESCEND' })
// Also registers DESCEND → CLIMB

// No opposite (one-way)
graph.registerDirection('WARP', { opposite: null })

// Use in connections
graph.connect('a', 'PORTAL' as any, 'b')

Types

Direction

Union type of all direction string literals.

type Direction =
  | 'NORTH' | 'NORTHEAST' | 'EAST' | 'SOUTHEAST'
  | 'SOUTH' | 'SOUTHWEST' | 'WEST' | 'NORTHWEST'
  | 'UP' | 'DOWN'
  | 'IN' | 'OUT'

RegisterDirectionOptions

Options for registering custom directions.

interface RegisterDirectionOptions {
  opposite?: Direction | null
}

Opposite Mappings

Built-in direction opposite pairs:

Parse Mappings

Supported input strings for parsing:

All parsing is case-insensitive.