Gate Management API

Methods for adding, updating, removing, and querying gates on connections.

setGate()

Adds or replaces a gate on a connection.

Signature:

setGate(from: string, direction: Direction, gate: Gate): void

Parameters:

Returns: void

Example:

// Locked door with key
graph.setGate('hallway', Direction.NORTH, {
  id: 'vault-door',
  locked: true,
  keyId: 'vault-key',
  description: 'A heavy steel door.'
})

// Hidden passage
graph.setGate('library', Direction.EAST, {
  id: 'secret-door',
  hidden: true
})

// Conditional gate
graph.setGate('bridge', Direction.EAST, {
  id: 'drawbridge',
  condition: { check: ['bridge_lowered', '==', true] },
  blockedMessage: 'The drawbridge is raised.'
})

Throws:

• ValidationError — When connection does not exist

updateGate()

Updates specific properties of an existing gate.

Signature:

updateGate(from: string, direction: Direction, updates: Partial<Gate>): void

Parameters:

Returns: void

Example:

// Unlock a door
graph.updateGate('hallway', Direction.NORTH, { locked: false })

// Change key requirement
graph.updateGate('hallway', Direction.NORTH, { keyId: 'master-key' })

// Multiple updates
graph.updateGate('hallway', Direction.NORTH, {
  locked: false,
  description: 'The door stands open.'
})

Throws:

• ValidationError — When gate does not exist on connection

removeGate()

Removes a gate from a connection, leaving the connection open.

Signature:

removeGate(from: string, direction: Direction): void

Parameters:

Returns: void

Example:

// Remove the gate entirely
graph.removeGate('hallway', Direction.NORTH)

// Connection remains, but no access control
const result = graph.canTraverse('hallway', Direction.NORTH)
console.log(result.allowed)  // true

getGate()

Retrieves gate data for a connection.

Signature:

getGate(from: string, direction: Direction): Gate | null

Parameters:

Returns: Gate | null — Gate data, or null if no gate exists

Example:

const gate = graph.getGate('hallway', Direction.NORTH)
if (gate) {
  console.log('Gate ID:', gate.id)
  console.log('Locked:', gate.locked)
  console.log('Key needed:', gate.keyId)
}

canTraverse()

Checks if traversal through a connection is allowed.

Signature:

canTraverse(
  from: string,
  direction: Direction,
  context?: TraversalContext
): TraversalResult

Parameters:

Returns: TraversalResult — Result indicating if traversal is allowed

Example:

// Check without context
const result1 = graph.canTraverse('hallway', Direction.NORTH)
console.log(result1.allowed)  // false (locked)
console.log(result1.reason)   // 'locked'
console.log(result1.gateId)   // 'vault-door'

// Check with key
const result2 = graph.canTraverse('hallway', Direction.NORTH, {
  inventory: ['vault-key']
})
console.log(result2.allowed)  // true

// Check hidden passage
const result3 = graph.canTraverse('library', Direction.EAST, {
  discovered: ['secret-door']
})
console.log(result3.allowed)  // true

Types

Gate

Gate configuration.

interface Gate {
  id: string
  locked?: boolean
  keyId?: string
  condition?: Condition
  hidden?: boolean
  oneWay?: boolean
  description?: string
  blockedMessage?: string
  metadata?: Record<string, unknown>
}

TraversalContext

Context for traversal checks.

interface TraversalContext {
  inventory?: string[]
  flagStore?: {
    check: (condition: Condition) => boolean
  }
  discovered?: string[]
  [key: string]: unknown
}

TraversalResult

Result of a traversal check.

interface TraversalResult {
  allowed: boolean
  reason?: string
  gateId?: string
}