LocationService

Overview

LocationService provides CRUD operations for the location hierarchy tree, including automatic path generation, alias resolution, subtree moves, and ancestor chain queries. Locations form a tree structure (e.g., Campus > Building > Floor > Room) used for scoping availability searches and configuration inheritance.

import { LocationService } from '@roomkit/nestjs';

Methods

createNode

Create a new location node. The path is auto-generated from the parent node's path combined with a slugified version of the displayName. Validates that the generated path is unique.

async createNode(dto: CreateLocationNodeDto): Promise<LocationNode>

Parameter	Type	Description
`dto`	`CreateLocationNodeDto`	Location node creation data

const building = await locationService.createNode({
    displayName: 'Engineering Building',
    parentId: 'campus-north',
    type: 'building',
    alias: 'eng-building',
    metadata: { address: '123 University Ave' },
});
// building.path → "campus-north/engineering-building"

Throws LocationNotFoundError if the parentId does not reference an existing node.

Throws LocationPathConflictError if the generated path already exists.

getById

Retrieve a single location node by ID.

async getById(id: string): Promise<LocationNode | null>

Parameter	Type	Description
`id`	`string`	Location node ID

Returns the location node or null if not found.

const node = await locationService.getById('building-eng');

getTree

Build the location hierarchy tree from flat nodes. If a rootId is provided, the tree is scoped to that subtree. Otherwise, the full tree from all root nodes is returned.

async getTree(rootId?: string): Promise<LocationTreeNode[]>

Parameter	Type	Description
`rootId`	`string`	Optional root node ID to scope the tree

Returns an array of LocationTreeNode objects, each containing nested children.

// Full tree
const fullTree = await locationService.getTree();

// Subtree from a specific building
const subtree = await locationService.getTree('building-eng');

// Traverse the tree
function printTree(nodes: LocationTreeNode[], depth = 0) {
    for (const node of nodes) {
        console.log(`${'  '.repeat(depth)}${node.displayName}`);
        printTree(node.children, depth + 1);
    }
}
printTree(fullTree);

resolveAlias

Find a location node by its alias. Aliases provide human-friendly identifiers for frequently referenced locations.

async resolveAlias(alias: string): Promise<LocationNode | null>

Parameter	Type	Description
`alias`	`string`	The alias to resolve

Returns the location node or null if no node has the given alias.

const node = await locationService.resolveAlias('eng-building');
if (node) {
    console.log(node.id, node.displayName);
}

moveNode

Move a location node (and all its descendants) under a new parent. Recomputes the path for the moved node and all descendants to reflect the new position in the tree.

async moveNode(id: string, newParentId: string): Promise<LocationNode>

Parameter	Type	Description
`id`	`string`	ID of the node to move
`newParentId`	`string`	ID of the new parent node

const moved = await locationService.moveNode('floor-3', 'building-science');
console.log('New path:', moved.path);
// e.g., "campus-north/building-science/floor-3"

Throws LocationNotFoundError if either id or newParentId does not reference an existing node.

Throws LocationPathConflictError if the new path conflicts with an existing node.

getAncestors

Retrieve the ancestor chain for a node, from its immediate parent up to the root.

async getAncestors(nodeId: string): Promise<LocationNode[]>

Parameter	Type	Description
`nodeId`	`string`	ID of the node to get ancestors for

Returns an array of LocationNode objects ordered from the immediate parent to the root.

const ancestors = await locationService.getAncestors('room-301');
// Returns: [floor-3, building-eng, campus-north]

for (const ancestor of ancestors) {
    console.log(ancestor.displayName);
}

Throws LocationNotFoundError if the node does not exist.

LocationTreeNode

type LocationTreeNode = LocationNode & {
    children: LocationTreeNode[];
};

LocationNode

interface LocationNode {
    id: string;
    displayName: string;
    path: string;
    parentId: string | null;
    type: string;
    alias: string | null;
    metadata: Record<string, unknown> | null;
}

LocationService

On this page