node-opcua-alias-name-server 2.176.0

package/source/address_space_alias_store.ts

@@ -0,0 +1,417 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * An {@link IAliasStore} backed directly by the address space.
+ *
+ * This is the default store, and the reason `installAliasNames(server)` needs no
+ * application code: a Server whose NodeSet2.xml already models `AliasNameType`
+ * instances answers `FindAlias` correctly with nothing else configured. The
+ * address space *is* the database.
+ */
+
+import type { IAddressSpace, UAObject } from "node-opcua-address-space-base";
+import {
+    type AliasEntry,
+    type AliasQuery,
+    type IAliasStore,
+    type LikeOptions,
+    LikePattern,
+    maxVersionTime,
+    nowVersionTime
+} from "node-opcua-alias-name-common";
+import { BrowseDirection, NodeClass } from "node-opcua-data-model";
+import { ExpandedNodeId, type NodeId, NodeId as NodeIdClass, type NodeIdType } from "node-opcua-nodeid";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { addAlias, findAlias, removeAlias } from "./add_alias.js";
+import { aliasesOf, collectCategories } from "./alias_hierarchy.js";
+import { ALIAS_FOR } from "./well_known.js";
+
+/**
+ * An ExpandedNodeId as a NodeId on this Server, dropping the ServerIndex.
+ *
+ * Clause 6.3.4 Table 9: *"The ServerIndex in the ExpandedNodeId shall be ignored
+ * and the TargetServers Uri shall be used."*
+ *
+ * Built from the identifier's own parts rather than by re-parsing its string
+ * form, which would have to cope with `svr=`, `nsu=` and quoting. When the
+ * ExpandedNodeId carries a namespace URI, that URI decides the index — the
+ * numeric index travelling beside it belongs to the *sending* Server's namespace
+ * table, not ours.
+ */
+function toLocalNodeId(addressSpace: IAddressSpace, nodeId: ExpandedNodeId): NodeId | null {
+    let namespaceIndex = nodeId.namespace ?? 0;
+    if (nodeId.namespaceUri) {
+        const resolved = addressSpace.getNamespaceIndex(nodeId.namespaceUri);
+        if (resolved < 0) {
+            // a namespace this Server does not know: the Node cannot be here
+            return null;
+        }
+        namespaceIndex = resolved;
+    }
+    return new NodeIdClass(nodeId.identifierType, nodeId.value, namespaceIndex);
+}
+
+export interface AddressSpaceAliasStoreOptions {
+    /** Passed through to the OPC 10000-4 `Like` matcher. */
+    likeOptions?: LikeOptions;
+    /**
+     * Accept `AddAliasesToCategory` entries whose target is on another Server.
+     *
+     * Off by default. Clause 6.3.4 Table 10 makes `Bad_NotSupported` an
+     * explicitly allowed answer — *"Support for remote Server TargetNodes is
+     * optional"* — and storing a reference this Server can never resolve or
+     * verify is a poor default. When on, such entries are accepted and reported
+     * `Uncertain_ReferenceOutOfServer`, since this Server does not check Nodes
+     * on other Servers.
+     */
+    allowRemoteTargets?: boolean;
+}
+
+/** Turn a local NodeId into an ExpandedNodeId with the namespace URI filled in. */
+function toExpandedNodeId(addressSpace: IAddressSpace, nodeId: NodeId): ExpandedNodeId {
+    const namespaceUri = nodeId.namespace === 0 ? null : addressSpace.getNamespaceUri(nodeId.namespace);
+    return new ExpandedNodeId(
+        nodeId.identifierType as unknown as NodeIdType,
+        nodeId.value,
+        nodeId.namespace,
+        namespaceUri,
+        // clause 7.3: the ServerIndex is carried separately in ServerUris, and
+        // clause 6.3.4 Table 9 says an incoming ServerIndex is ignored anyway
+        0
+    );
+}
+
+export class AddressSpaceAliasStore implements IAliasStore {
+    private readonly addressSpace: IAddressSpace;
+    private readonly likeOptions?: LikeOptions;
+    /** Per-category `LastChange`, as a VersionTime (clause 6.3.1). */
+    private readonly lastChangeByCategory = new Map<string, number>();
+
+    private readonly allowRemoteTargets: boolean;
+
+    constructor(addressSpace: IAddressSpace, options?: AddressSpaceAliasStoreOptions) {
+        this.addressSpace = addressSpace;
+        this.likeOptions = options?.likeOptions;
+        this.allowRemoteTargets = options?.allowRemoteTargets ?? false;
+    }
+
+    /**
+     * Every alias at or below `query.categoryNodeId` matching the pattern.
+     *
+     * The search is recursive from the category the Method was called on
+     * (clause 6.3.1), so a call on `Aliases` also covers `TagVariables`,
+     * `Topics` and anything nested below them.
+     *
+     * One entry is produced per (AliasName, category) pair: `FindAliasVerbose`
+     * has to name the category that actually held the alias, which for a nested
+     * hit is the nested one, not the one that was called.
+     */
+    public async find(query: AliasQuery): Promise<AliasEntry[]> {
+        const root = this.addressSpace.findNode(query.categoryNodeId);
+        if (!root || root.nodeClass !== NodeClass.Object) {
+            return [];
+        }
+        // an invalid pattern throws InvalidLikePatternError, which the Method
+        // binding turns into Bad_InvalidArgument (clause 6.3.2 Table 4)
+        const pattern = new LikePattern(query.pattern, this.likeOptions);
+
+        const referenceTypeFilter = this.resolveReferenceTypeFilter(query.referenceTypeFilter);
+        const entries: AliasEntry[] = [];
+
+        // Stop one past the cap. The caller only needs to know that the cap was
+        // exceeded, so collecting the whole hierarchy first would be wasted work
+        // -- and on a Server with a large tag set, a `%` pattern would build the
+        // entire result set purely to throw it away with Bad_ResponseTooLarge.
+        const collectLimit = query.maxResults === undefined ? Number.POSITIVE_INFINITY : query.maxResults + 1;
+
+        for (const category of collectCategories(this.addressSpace, root as UAObject)) {
+            if (entries.length >= collectLimit) {
+                break;
+            }
+            // Skipped before its aliases are walked, so the cap is spent only on
+            // entries the caller may see - and the scan does less work. Only
+            // this category is skipped, not its descendants: the gate is
+            // per-category, and a denied parent does not imply a denied child.
+            if (query.isVisible && !(await query.isVisible(category.nodeId))) {
+                continue;
+            }
+            for (const alias of aliasesOf(this.addressSpace, category)) {
+                if (entries.length >= collectLimit) {
+                    break;
+                }
+                const aliasName = alias.browseName.name;
+                if (!aliasName || !pattern.test(aliasName)) {
+                    continue;
+                }
+                const targets = this.targetsOf(alias, referenceTypeFilter);
+                if (targets.length === 0) {
+                    // clause 6.3.2 Table 3: an alias with no Reference of the
+                    // requested type is simply not a match
+                    continue;
+                }
+                entries.push({
+                    aliasName,
+                    // the namespace the alias Object was actually published in,
+                    // not the category's - Aliases and friends live in
+                    // namespace 0, which clause 6.2 never intends for an alias
+                    aliasNameNamespaceUri: this.namespaceUriOf(alias.browseName.namespaceIndex),
+                    referencedNodes: targets.map((t) => t.expandedNodeId),
+                    // every target is on this Server; aggregating other Servers
+                    // is out of scope for this package (Annex B / Annex C)
+                    serverUris: targets.map(() => null),
+                    categoryNodeId: category.nodeId,
+                    referenceTypeIds: targets.map((t) => t.referenceTypeId)
+                });
+            }
+        }
+        return entries;
+    }
+
+    /** `LastChange` for a category, rolled up from its descendants (clause 6.3.1). */
+    public lastChange(categoryNodeId: NodeId): number {
+        const root = this.addressSpace.findNode(categoryNodeId);
+        if (!root || root.nodeClass !== NodeClass.Object) {
+            return this.lastChangeByCategory.get(categoryNodeId.toString()) ?? 0;
+        }
+        let latest = 0;
+        for (const category of collectCategories(this.addressSpace, root as UAObject)) {
+            latest = maxVersionTime(latest, this.lastChangeByCategory.get(category.nodeId.toString()) ?? 0);
+        }
+        return latest;
+    }
+
+    /**
+     * Record that a category changed, at `versionTime` (defaulting to now).
+     *
+     * Only the category itself is stored; the rollup to ancestors happens on
+     * read, so a category that is later re-parented reports correctly without
+     * anything having to be recomputed.
+     */
+    public touch(categoryNodeId: NodeId, versionTime?: number): number {
+        const value = versionTime ?? nowVersionTime();
+        const key = categoryNodeId.toString();
+        this.lastChangeByCategory.set(key, maxVersionTime(this.lastChangeByCategory.get(key) ?? 0, value));
+        return value;
+    }
+
+    /** Restore persisted `LastChange` values (clause 6.3.1: "shall be persisted"). */
+    public restoreLastChange(values: Iterable<readonly [string, number]>): void {
+        for (const [key, value] of values) {
+            this.lastChangeByCategory.set(key, value);
+        }
+    }
+
+    /** Snapshot the per-category `LastChange` values for persistence. */
+    public snapshotLastChange(): Array<[string, number]> {
+        return [...this.lastChangeByCategory.entries()];
+    }
+
+    /**
+     * Add aliases to a category (clause 6.3.4), one StatusCode per entry.
+     *
+     * The per-item codes of Table 10:
+     *
+     * - `Bad_NodeIdInvalid` — the NodeId is syntactically unusable.
+     * - `Bad_NodeIdUnknown` — the target is on this Server and does not exist.
+     * - `Uncertain_ReferenceOutOfServer` — the target is on another Server. The
+     *   clause is explicit that this is returned **whether or not** a check was
+     *   performed: *"If the Server does not check for the external Node's
+     *   existence, it shall return Uncertain_ReferenceOutOfServer."* This Server
+     *   does not check, because checking means being a Client of the other
+     *   Server, which is the aggregation these packages exclude by design.
+     * - `Bad_NotSupported` — when {@link AddressSpaceAliasStoreOptions.allowRemoteTargets}
+     *   is off, which Table 10 explicitly permits.
+     *
+     * An exact duplicate of (AliasName, target, target Server) is `Good` and
+     * ignored, whether it was already stored or repeated within this call.
+     */
+    public add(categoryNodeId: NodeId, entries: AliasEntry[]): StatusCode[] {
+        const category = this.addressSpace.findNode(categoryNodeId);
+        if (!category || category.nodeClass !== NodeClass.Object) {
+            return entries.map(() => StatusCodes.BadNodeIdUnknown);
+        }
+        const categoryNode = category as UAObject;
+
+        // duplicates repeated *within* this call are ignored too, so the set
+        // has to grow as we go rather than being a snapshot of the start state
+        const seenInThisCall = new Set<string>();
+
+        return entries.map((entry) => {
+            const target = entry.referencedNodes[0];
+            const serverUri = entry.serverUris[0] ?? null;
+
+            if (!target) {
+                return StatusCodes.BadNodeIdInvalid;
+            }
+            if (!entry.aliasName) {
+                return StatusCodes.BadNodeIdInvalid;
+            }
+
+            const key = `${entry.aliasName}${target.toString()}${serverUri ?? ""}`;
+            if (seenInThisCall.has(key)) {
+                return StatusCodes.Good;
+            }
+            seenInThisCall.add(key);
+
+            // Table 9: the ServerIndex inside the ExpandedNodeId is ignored;
+            // TargetServers is authoritative
+            if (serverUri !== null) {
+                if (!this.allowRemoteTargets) {
+                    return StatusCodes.BadNotSupported;
+                }
+                return this.addRemote(categoryNode, entry, target, serverUri);
+            }
+
+            return this.addLocal(categoryNode, entry, target);
+        });
+    }
+
+    /**
+     * Remove aliases from a category (clause 6.3.5), one StatusCode per entry.
+     *
+     * `Bad_NotFound` when the name is not in the category, `Bad_InvalidState`
+     * when it is there but not owned by this Server — clause 6.3.5 opens by
+     * saying a Server "shall only delete AliasName instances that are defined on
+     * the Server exposing this Method".
+     *
+     * An entry with no target removes every target of that name. Removal is
+     * all-or-nothing per name: if any target cannot go, none of that name's do.
+     */
+    public delete(categoryNodeId: NodeId, entries: Pick<AliasEntry, "aliasName" | "referencedNodes">[]): StatusCode[] {
+        const category = this.addressSpace.findNode(categoryNodeId);
+        if (!category || category.nodeClass !== NodeClass.Object) {
+            return entries.map(() => StatusCodes.BadNotFound);
+        }
+        const categoryNode = category as UAObject;
+
+        return entries.map((entry) => {
+            const alias = findAlias(this.addressSpace, categoryNode, entry.aliasName);
+            if (!alias) {
+                return StatusCodes.BadNotFound;
+            }
+            // an alias whose targets all live on other Servers was learned from
+            // elsewhere and is not ours to delete
+            if (this.isForeign(alias)) {
+                return StatusCodes.BadInvalidState;
+            }
+
+            const requested = entry.referencedNodes ?? [];
+            if (requested.length === 0) {
+                // "all AliasNames with the provided name are deleted"
+                removeAlias(this.addressSpace, categoryNode, entry.aliasName);
+                return StatusCodes.Good;
+            }
+
+            // all or nothing: check every requested target is present first
+            const references = alias.findReferencesEx(ALIAS_FOR, BrowseDirection.Forward);
+            const present = new Set(references.map((r) => r.nodeId.toString()));
+            const wanted: NodeId[] = [];
+            for (const target of requested) {
+                const local = toLocalNodeId(this.addressSpace, target);
+                if (!local || !present.has(local.toString())) {
+                    return StatusCodes.BadNotFound;
+                }
+                wanted.push(local);
+            }
+            for (const target of wanted) {
+                removeAlias(this.addressSpace, categoryNode, entry.aliasName, target);
+            }
+            return StatusCodes.Good;
+        });
+    }
+
+    /** Add an alias whose target is on this Server. */
+    private addLocal(category: UAObject, entry: AliasEntry, target: ExpandedNodeId): StatusCode {
+        const localNodeId = toLocalNodeId(this.addressSpace, target);
+        if (!localNodeId) {
+            return StatusCodes.BadNodeIdInvalid;
+        }
+        if (!this.addressSpace.findNode(localNodeId)) {
+            // Table 10: "The TargetNode does not exist in the AliasName Server
+            // and the TargetServer is the local server"
+            return StatusCodes.BadNodeIdUnknown;
+        }
+        try {
+            addAlias(this.addressSpace, category, entry.aliasName, localNodeId, {
+                referenceType: entry.referenceTypeIds[0]
+            });
+        } catch {
+            // a category restriction (clause 9.3 / 9.4) refused the target
+            return StatusCodes.BadNodeIdInvalid;
+        }
+        return StatusCodes.Good;
+    }
+
+    /**
+     * Add an alias whose target is on another Server.
+     *
+     * Always `Uncertain_ReferenceOutOfServer`: this Server does not verify
+     * Nodes on other Servers, and clause 6.3.4 says that case returns the
+     * uncertain code rather than success.
+     */
+    private addRemote(category: UAObject, entry: AliasEntry, target: ExpandedNodeId, _serverUri: string): StatusCode {
+        try {
+            addAlias(this.addressSpace, category, entry.aliasName, target, {
+                referenceType: entry.referenceTypeIds[0],
+                allowUnresolvedTarget: true
+            });
+        } catch {
+            return StatusCodes.BadNodeIdInvalid;
+        }
+        return StatusCodes.UncertainReferenceOutOfServer;
+    }
+
+    /** True when none of the alias's targets are on this Server. */
+    private isForeign(alias: UAObject): boolean {
+        const references = alias.findReferencesEx(ALIAS_FOR, BrowseDirection.Forward);
+        if (references.length === 0) {
+            return false;
+        }
+        return references.every((reference) => this.addressSpace.findNode(reference.nodeId) === null);
+    }
+
+    /** The URI of a namespace index, or undefined for namespace 0. */
+    private namespaceUriOf(namespaceIndex: number): string | undefined {
+        // namespace 0 is the OPC Foundation's and is never a legitimate alias
+        // namespace; reporting it would be worse than reporting nothing
+        return namespaceIndex === 0 ? undefined : this.addressSpace.getNamespaceUri(namespaceIndex);
+    }
+
+    /**
+     * Resolve the `ReferenceTypeFilter` argument.
+     *
+     * A null or absent NodeId means any ReferenceType (clause 6.3.2 Table 3).
+     */
+    private resolveReferenceTypeFilter(filter: NodeId | undefined): NodeId | null {
+        if (!filter || filter.isEmpty()) {
+            return null;
+        }
+        return filter;
+    }
+
+    /**
+     * The Nodes an alias points at.
+     *
+     * `findReferencesEx` already includes subtypes of the ReferenceType, which
+     * is what clause 6.3.2 Table 3 asks for: "Any ReferenceType includes all
+     * subtypes of that ReferenceType".
+     *
+     * An absent filter falls back to `AliasFor` rather than to *every*
+     * ReferenceType. Table 3 describes the filter as "AliasFor or one of its
+     * subtypes", and clause 8.2 makes `AliasFor` the ReferenceType that links an
+     * AliasName to what it names; taking "any" literally would return the
+     * alias's `HasTypeDefinition` target and its Organizes back-reference, which
+     * are not things the alias names.
+     */
+    private targetsOf(
+        alias: UAObject,
+        referenceTypeFilter: NodeId | null
+    ): Array<{ expandedNodeId: ExpandedNodeId; referenceTypeId: NodeId }> {
+        const referenceType = referenceTypeFilter ?? ALIAS_FOR;
+        const references = alias.findReferencesEx(referenceType, BrowseDirection.Forward);
+        return references.map((reference) => ({
+            expandedNodeId: toExpandedNodeId(this.addressSpace, reference.nodeId),
+            referenceTypeId: reference.referenceType
+        }));
+    }
+}

package/source/alias_hierarchy.ts

@@ -0,0 +1,141 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Walking the AliasName hierarchy in the address space (OPC 10000-17
+ * clause 6.3.1).
+ */
+
+import type { BaseNode, IAddressSpace, UAObject, UAObjectType } from "node-opcua-address-space-base";
+import { BrowseDirection, NodeClass } from "node-opcua-data-model";
+import type { NodeId } from "node-opcua-nodeid";
+import { ALIAS_NAME_CATEGORY_TYPE, ALIAS_NAME_TYPE, WellKnownCategories } from "./well_known.js";
+
+/** True when `node` is an Object whose TypeDefinition is `type` or a subtype. */
+function isInstanceOf(node: BaseNode, type: UAObjectType | null): boolean {
+    if (!type || node.nodeClass !== NodeClass.Object) {
+        return false;
+    }
+    const typeDefinition = (node as UAObject).typeDefinitionObj;
+    if (!typeDefinition) {
+        return false;
+    }
+    return typeDefinition.nodeId.value === type.nodeId.value || typeDefinition.isSubtypeOf(type);
+}
+
+/** Resolve `AliasNameCategoryType`, or null on an address space without Part 17. */
+export function findAliasNameCategoryType(addressSpace: IAddressSpace): UAObjectType | null {
+    return addressSpace.findObjectType(ALIAS_NAME_CATEGORY_TYPE);
+}
+
+/** Resolve `AliasNameType`, or null on an address space without Part 17. */
+export function findAliasNameType(addressSpace: IAddressSpace): UAObjectType | null {
+    return addressSpace.findObjectType(ALIAS_NAME_TYPE);
+}
+
+/** True when `node` is an instance of `AliasNameCategoryType` (or a subtype). */
+export function isAliasNameCategory(addressSpace: IAddressSpace, node: BaseNode): boolean {
+    return isInstanceOf(node, findAliasNameCategoryType(addressSpace));
+}
+
+/** True when `node` is an instance of `AliasNameType` (or a subtype). */
+export function isAliasName(addressSpace: IAddressSpace, node: BaseNode): boolean {
+    return isInstanceOf(node, findAliasNameType(addressSpace));
+}
+
+/**
+ * The Organized children of a category.
+ *
+ * `findReferencesExAsObject` follows subtypes of the ReferenceType, so a vendor
+ * subtype of `Organizes` is included, and `HierarchicalReferences` is used as
+ * the base so a Server that nests categories with `HasComponent` is not missed.
+ */
+function organizedChildren(category: UAObject): BaseNode[] {
+    return category.findReferencesExAsObject("HierarchicalReferences", BrowseDirection.Forward);
+}
+
+/**
+ * Every `AliasNameCategoryType` instance at or below `root`, depth first.
+ *
+ * A category may legitimately be reached more than once — clause 6.3.1 allows an
+ * `<Alias>` (and by extension a subtree) to appear in more than one place — so
+ * `seen` both de-duplicates and makes a cyclic hierarchy terminate rather than
+ * hang the Method call.
+ */
+export function collectCategories(addressSpace: IAddressSpace, root: UAObject): UAObject[] {
+    const result: UAObject[] = [];
+    const seen = new Set<string>();
+
+    const visit = (category: UAObject): void => {
+        const key = category.nodeId.toString();
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        result.push(category);
+        for (const child of organizedChildren(category)) {
+            if (isAliasNameCategory(addressSpace, child)) {
+                visit(child as UAObject);
+            }
+        }
+    };
+
+    visit(root);
+    return result;
+}
+
+/** The `AliasNameType` instances Organized directly by `category`. */
+export function aliasesOf(addressSpace: IAddressSpace, category: UAObject): UAObject[] {
+    const result: UAObject[] = [];
+    for (const child of organizedChildren(category)) {
+        if (isAliasName(addressSpace, child)) {
+            result.push(child as UAObject);
+        }
+    }
+    return result;
+}
+
+/**
+ * Every `AliasNameCategoryType` instance reachable from `Aliases`, plus any
+ * roots named explicitly.
+ *
+ * Discovery walks the hierarchy below `Aliases` rather than sweeping the whole
+ * address space, because that is where clause 9.1 puts categories: vendors "are
+ * free to add additional instances of AliasNameCategoryType under this
+ * hierarchy". There is also no way to sweep — the address space keeps no inverse
+ * `HasTypeDefinition` reference from an ObjectType to its instances, so a type
+ * cannot be asked for them.
+ *
+ * `additionalRoots` is the escape hatch for a Server that models a category
+ * somewhere else: without it that category's MANDATORY `FindAlias` would stay
+ * unbound, which is the very defect this package exists to fix.
+ */
+export function collectAllCategories(addressSpace: IAddressSpace, additionalRoots?: Array<NodeId | UAObject>): UAObject[] {
+    const byId = new Map<string, UAObject>();
+
+    const roots: BaseNode[] = [];
+    const aliasesRoot = addressSpace.findNode(WellKnownCategories.Aliases);
+    if (aliasesRoot) {
+        roots.push(aliasesRoot);
+    }
+    for (const extra of additionalRoots ?? []) {
+        const node = "nodeClass" in extra ? extra : addressSpace.findNode(extra);
+        if (node) {
+            roots.push(node);
+        }
+    }
+
+    for (const root of roots) {
+        if (root.nodeClass !== NodeClass.Object) {
+            continue;
+        }
+        for (const category of collectCategories(addressSpace, root as UAObject)) {
+            byId.set(category.nodeId.toString(), category);
+        }
+    }
+    return [...byId.values()];
+}
+
+/** The NodeIds of the well-known categories present in this address space. */
+export function presentWellKnownCategories(addressSpace: IAddressSpace): NodeId[] {
+    return Object.values(WellKnownCategories).filter((nodeId) => addressSpace.findNode(nodeId) !== null);
+}

package/source/alias_index.ts

@@ -0,0 +1,127 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * A per-category index from AliasName to the `AliasNameType` Object that carries
+ * it.
+ *
+ * ## Why this exists
+ *
+ * Looking an alias up by name means finding a child of the category with a given
+ * BrowseName. The address space has an O(1) index for exactly that — but
+ * `getChildByName` only consults it for `HasChild` subtypes, and an alias is an
+ * `Organizes` child of its category (clause 6.3 Table 2). `getFolderElementByName`
+ * does cover `Organizes`, but scans. So neither route is both correct and fast.
+ *
+ * That matters because `addAlias` has to look for an existing alias of the same
+ * name before creating one, so a Server building N aliases performed N linear
+ * scans of a growing category — quadratic. Measured on a category holding 1500
+ * aliases, 200 lookups cost 97 ms by scanning and 0 ms through this index, and
+ * building 1500 aliases went from 2545 ms to 1686 ms.
+ *
+ * That is not the whole story: the larger remaining cost is inside
+ * `UAObjectType.instantiate`, which is itself superlinear in the number of
+ * children the parent already has. That is an address-space concern rather than
+ * an AliasName one, and is tracked separately.
+ *
+ * ## How it stays correct
+ *
+ * The index is built lazily, from one full scan, so aliases modelled in a
+ * NodeSet2.xml are picked up. After that it is maintained incrementally by
+ * {@link noteAliasAdded} and {@link noteAliasRemoved}, which `addAlias` and
+ * `removeAlias` call.
+ *
+ * A hit is verified against the address space before being returned, so an alias
+ * deleted by other means degrades to a miss rather than a dangling Object. A
+ * miss is trusted: an alias created behind this package's back after the index
+ * was built would not be found, and `addAlias` would then fail loudly on the
+ * duplicate BrowseName rather than corrupting anything. Call
+ * {@link invalidateAliasIndex} if a Server mutates a category by other means.
+ *
+ * Keyed by the node itself in a `WeakMap`, so a disposed address space takes its
+ * indexes with it.
+ */
+
+import type { IAddressSpace, UAObject } from "node-opcua-address-space-base";
+import { BrowseDirection, NodeClass } from "node-opcua-data-model";
+import type { NodeId } from "node-opcua-nodeid";
+import { findAliasNameType } from "./alias_hierarchy.js";
+
+/** AliasName (string part only, per clause 6.2) to the Object's NodeId. */
+type AliasIndex = Map<string, NodeId>;
+
+const indexes = new WeakMap<UAObject, AliasIndex>();
+
+/** Build the index for a category by scanning it once. */
+function buildIndex(addressSpace: IAddressSpace, category: UAObject): AliasIndex {
+    const index: AliasIndex = new Map();
+    const aliasNameType = findAliasNameType(addressSpace);
+    if (!aliasNameType) {
+        return index;
+    }
+    for (const child of category.findReferencesExAsObject("HierarchicalReferences", BrowseDirection.Forward)) {
+        if (child.nodeClass !== NodeClass.Object) {
+            continue;
+        }
+        const name = child.browseName.name;
+        if (!name || index.has(name)) {
+            continue;
+        }
+        const typeDefinition = (child as UAObject).typeDefinitionObj;
+        if (
+            typeDefinition &&
+            (typeDefinition.nodeId.value === aliasNameType.nodeId.value || typeDefinition.isSubtypeOf(aliasNameType))
+        ) {
+            index.set(name, child.nodeId);
+        }
+    }
+    return index;
+}
+
+/** The index for a category, built on first use. */
+function indexOf(addressSpace: IAddressSpace, category: UAObject): AliasIndex {
+    let index = indexes.get(category);
+    if (!index) {
+        index = buildIndex(addressSpace, category);
+        indexes.set(category, index);
+    }
+    return index;
+}
+
+/**
+ * The `AliasNameType` instance with this name in `category`, or null.
+ *
+ * O(1) after the first call on a given category.
+ */
+export function lookupAlias(addressSpace: IAddressSpace, category: UAObject, aliasName: string): UAObject | null {
+    const index = indexOf(addressSpace, category);
+    const nodeId = index.get(aliasName);
+    if (!nodeId) {
+        return null;
+    }
+    const node = addressSpace.findNode(nodeId);
+    if (!node || node.nodeClass !== NodeClass.Object) {
+        // deleted behind our back; forget it rather than hand back a ghost
+        index.delete(aliasName);
+        return null;
+    }
+    return node as UAObject;
+}
+
+/** Record a newly created alias. */
+export function noteAliasAdded(addressSpace: IAddressSpace, category: UAObject, aliasName: string, nodeId: NodeId): void {
+    indexOf(addressSpace, category).set(aliasName, nodeId);
+}
+
+/** Record a removed alias. */
+export function noteAliasRemoved(addressSpace: IAddressSpace, category: UAObject, aliasName: string): void {
+    indexOf(addressSpace, category).delete(aliasName);
+}
+
+/**
+ * Forget a category's index, so it is rebuilt from the address space on next
+ * use. Needed only if a Server adds or removes aliases without going through
+ * {@link addAlias} / {@link removeAlias}.
+ */
+export function invalidateAliasIndex(category: UAObject): void {
+    indexes.delete(category);
+}