Node Management API

Methods for creating, reading, updating, and deleting nodes in the graph.

createNode()

Creates a new node with the given ID and optional metadata.

Signature:

createNode(id: string, options?: CreateNodeOptions): void

Parameters:

Returns: void

Example:

// Simple node
graph.createNode('entrance')

// Node with metadata
graph.createNode('library', {
  name: 'Ancient Library',
  description: 'Dusty tomes line the walls.',
  customProp: 'any value'
})

// Node with tiles and layer
graph.createNode('great-hall', {
  name: 'Great Hall',
  tiles: [{ x: 0, y: 0 }, { x: 1, y: 0 }],
  layer: 2
})

Throws:

• ValidationError — When node ID is empty or already exists

getNode()

Retrieves node data by ID.

Signature:

getNode(id: string): NodeData | null

Parameters:

Returns: NodeData | null — The node data, or null if not found

Example:

const node = graph.getNode('library')
if (node) {
  console.log(node.id)              // 'library'
  console.log(node.metadata.name)   // 'Ancient Library'
  console.log(node.layer)           // 1 (default)
}

hasNode()

Checks if a node exists.

Signature:

hasNode(id: string): boolean

Parameters:

Returns: boolean — True if node exists

Example:

if (graph.hasNode('secret-room')) {
  console.log('Secret room exists!')
}

removeNode()

Removes a node and all its connections.

Signature:

removeNode(id: string): NodeData

Parameters:

Returns: NodeData — The removed node's data

Example:

const removed = graph.removeNode('old-room')
console.log('Removed:', removed.metadata.name)

// All connections to/from this node are also removed

Throws:

• ValidationError — When node does not exist

getAllNodes()

Returns all node IDs in the graph.

Signature:

getAllNodes(): string[]

Returns: string[] — Array of all node IDs

Example:

const nodes = graph.getAllNodes()
console.log(`Graph has ${nodes.length} nodes`)
nodes.forEach(id => console.log(`  - ${id}`))

Types

CreateNodeOptions

Options for creating a node.

interface CreateNodeOptions {
  name?: string
  description?: string
  tiles?: TilePosition[]
  layer?: number
  [key: string]: unknown
}

NodeData

Data structure for a node.

interface NodeData {
  id: string
  metadata: NodeMetadata
  tiles?: TilePosition[]
  layer: number
  zone?: string
}

TilePosition

Grid coordinates for a tile.

interface TilePosition {
  x: number
  y: number
  layer?: number
}

NodeMetadata

Flexible metadata container.

type NodeMetadata = Record<string, unknown>