node-opcua-alias-name-client 2.176.0

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Client-side OPC 10000-17 (AliasNames).
+ *
+ * Resolves the AliasNames **a Server publishes about itself**. Aggregating
+ * AliasNames collected from other Servers (Annexes B and C) and the Annex D
+ * PubSub change notification are out of scope; {@link ServerIndexResolver}
+ * covers the one cross-Server step a Client still has to make, turning the
+ * `ServerIndex` of a returned `ExpandedNodeId` into a URI (Annex A).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerIndexResolver = exports.LOCAL_SERVER_INDEX = exports.AliasNameMethodNotSupportedError = exports.AliasNameCallError = exports.TOPICS = exports.TAG_VARIABLES = exports.ClientAliasSet = exports.ALIASES_ROOT = void 0;
+var client_alias_set_js_1 = require("./client_alias_set.js");
+Object.defineProperty(exports, "ALIASES_ROOT", { enumerable: true, get: function () { return client_alias_set_js_1.ALIASES_ROOT; } });
+Object.defineProperty(exports, "ClientAliasSet", { enumerable: true, get: function () { return client_alias_set_js_1.ClientAliasSet; } });
+Object.defineProperty(exports, "TAG_VARIABLES", { enumerable: true, get: function () { return client_alias_set_js_1.TAG_VARIABLES; } });
+Object.defineProperty(exports, "TOPICS", { enumerable: true, get: function () { return client_alias_set_js_1.TOPICS; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AliasNameCallError", { enumerable: true, get: function () { return errors_js_1.AliasNameCallError; } });
+Object.defineProperty(exports, "AliasNameMethodNotSupportedError", { enumerable: true, get: function () { return errors_js_1.AliasNameMethodNotSupportedError; } });
+var server_index_resolver_js_1 = require("./server_index_resolver.js");
+Object.defineProperty(exports, "LOCAL_SERVER_INDEX", { enumerable: true, get: function () { return server_index_resolver_js_1.LOCAL_SERVER_INDEX; } });
+Object.defineProperty(exports, "ServerIndexResolver", { enumerable: true, get: function () { return server_index_resolver_js_1.ServerIndexResolver; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,6DAQ+B;AAP3B,mHAAA,YAAY,OAAA;AAEZ,qHAAA,cAAc,OAAA;AAGd,oHAAA,aAAa,OAAA;AACb,6GAAA,MAAM,OAAA;AAEV,yCAAmF;AAA1E,+GAAA,kBAAkB,OAAA;AAAE,6HAAA,gCAAgC,OAAA;AAC7D,uEAAqF;AAA5E,8HAAA,kBAAkB,OAAA;AAAE,+HAAA,mBAAmB,OAAA"}

package/dist/server_index_resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Turning the `ServerIndex` of a returned `ExpandedNodeId` into something a
+ * Client can act on.
+ */
+import { type ExpandedNodeId } from "node-opcua-nodeid";
+import type { IBasicSessionAsync } from "node-opcua-pseudo-session";
+/** The Server's own entry in the ServerArray is always index 0 (OPC 10000-5). */
+export declare const LOCAL_SERVER_INDEX = 0;
+/**
+ * Resolves `ServerIndex` values against a Server's `ServerArray`, caching it.
+ *
+ * `FindAlias` may return an `ExpandedNodeId` whose `serverIndex` is not 0, which
+ * says only "this Node is on a different Server" — the index is meaningless
+ * without the `ServerArray` that gives it a URI (OPC 10000-17 Annex A walks
+ * through exactly this). Every Client consuming AliasNames from a Server that
+ * aggregates has to do this step, so it lives here rather than in each caller.
+ *
+ * The `ServerArray` is read once and cached. It is not expected to change during
+ * a session; call {@link invalidate} if the Client has reason to believe it has.
+ */
+export declare class ServerIndexResolver {
+    private readonly session;
+    private serverArray?;
+    constructor(session: IBasicSessionAsync);
+    /** The Server's `ServerArray`, read once and cached. */
+    getServerArray(): Promise<string[]>;
+    /** Forget the cached `ServerArray`. */
+    invalidate(): void;
+    /**
+     * The URI for a `ServerIndex`, or `null` when the index is not in the
+     * `ServerArray`.
+     *
+     * An index the array does not cover is a Server defect, but a Client has to
+     * survive it, so it is reported as `null` rather than thrown.
+     */
+    resolveServerIndex(serverIndex: number): Promise<string | null>;
+    /** True when the ExpandedNodeId names a Node on the Server that answered. */
+    isLocal(expandedNodeId: ExpandedNodeId): boolean;
+    /**
+     * Describe where a returned Node lives.
+     *
+     * `serverUri` is `null` for a Node on the Server that answered the call —
+     * which is every Node these packages publish, since aggregating other
+     * Servers is out of scope. It is non-null only when talking to a Server that
+     * does aggregate.
+     */
+    locate(expandedNodeId: ExpandedNodeId): Promise<{
+        local: boolean;
+        serverIndex: number;
+        serverUri: string | null;
+    }>;
+}

package/dist/server_index_resolver.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Turning the `ServerIndex` of a returned `ExpandedNodeId` into something a
+ * Client can act on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerIndexResolver = exports.LOCAL_SERVER_INDEX = void 0;
+const node_opcua_constants_1 = require("node-opcua-constants");
+const node_opcua_data_model_1 = require("node-opcua-data-model");
+const node_opcua_nodeid_1 = require("node-opcua-nodeid");
+/** The Server's own entry in the ServerArray is always index 0 (OPC 10000-5). */
+exports.LOCAL_SERVER_INDEX = 0;
+/**
+ * Resolves `ServerIndex` values against a Server's `ServerArray`, caching it.
+ *
+ * `FindAlias` may return an `ExpandedNodeId` whose `serverIndex` is not 0, which
+ * says only "this Node is on a different Server" — the index is meaningless
+ * without the `ServerArray` that gives it a URI (OPC 10000-17 Annex A walks
+ * through exactly this). Every Client consuming AliasNames from a Server that
+ * aggregates has to do this step, so it lives here rather than in each caller.
+ *
+ * The `ServerArray` is read once and cached. It is not expected to change during
+ * a session; call {@link invalidate} if the Client has reason to believe it has.
+ */
+class ServerIndexResolver {
+    session;
+    serverArray;
+    constructor(session) {
+        this.session = session;
+    }
+    /** The Server's `ServerArray`, read once and cached. */
+    async getServerArray() {
+        if (this.serverArray) {
+            return this.serverArray;
+        }
+        const dataValue = await this.session.read({
+            nodeId: (0, node_opcua_nodeid_1.resolveNodeId)(node_opcua_constants_1.VariableIds.Server_ServerArray),
+            attributeId: node_opcua_data_model_1.AttributeIds.Value
+        });
+        const value = dataValue.value?.value;
+        this.serverArray = Array.isArray(value) ? value : [];
+        return this.serverArray;
+    }
+    /** Forget the cached `ServerArray`. */
+    invalidate() {
+        this.serverArray = undefined;
+    }
+    /**
+     * The URI for a `ServerIndex`, or `null` when the index is not in the
+     * `ServerArray`.
+     *
+     * An index the array does not cover is a Server defect, but a Client has to
+     * survive it, so it is reported as `null` rather than thrown.
+     */
+    async resolveServerIndex(serverIndex) {
+        const serverArray = await this.getServerArray();
+        return serverArray[serverIndex] ?? null;
+    }
+    /** True when the ExpandedNodeId names a Node on the Server that answered. */
+    isLocal(expandedNodeId) {
+        return (expandedNodeId.serverIndex ?? exports.LOCAL_SERVER_INDEX) === exports.LOCAL_SERVER_INDEX;
+    }
+    /**
+     * Describe where a returned Node lives.
+     *
+     * `serverUri` is `null` for a Node on the Server that answered the call —
+     * which is every Node these packages publish, since aggregating other
+     * Servers is out of scope. It is non-null only when talking to a Server that
+     * does aggregate.
+     */
+    async locate(expandedNodeId) {
+        const serverIndex = expandedNodeId.serverIndex ?? exports.LOCAL_SERVER_INDEX;
+        if (serverIndex === exports.LOCAL_SERVER_INDEX) {
+            return { local: true, serverIndex, serverUri: null };
+        }
+        return { local: false, serverIndex, serverUri: await this.resolveServerIndex(serverIndex) };
+    }
+}
+exports.ServerIndexResolver = ServerIndexResolver;
+//# sourceMappingURL=server_index_resolver.js.map

package/dist/server_index_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_index_resolver.js","sourceRoot":"","sources":["../source/server_index_resolver.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,+DAAmD;AACnD,iEAAqD;AACrD,yDAAuE;AAGvE,iFAAiF;AACpE,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,MAAa,mBAAmB;IACX,OAAO,CAAqB;IACrC,WAAW,CAAY;IAE/B,YAAY,OAA2B;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,wDAAwD;IACjD,KAAK,CAAC,cAAc;QACvB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,WAAW,CAAC;QAC5B,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YACtC,MAAM,EAAE,IAAA,iCAAa,EAAC,kCAAW,CAAC,kBAAkB,CAAC;YACrD,WAAW,EAAE,oCAAY,CAAC,KAAK;SAClC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,uCAAuC;IAChC,UAAU;QACb,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,kBAAkB,CAAC,WAAmB;QAC/C,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAChD,OAAO,WAAW,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED,6EAA6E;IACtE,OAAO,CAAC,cAA8B;QACzC,OAAO,CAAC,cAAc,CAAC,WAAW,IAAI,0BAAkB,CAAC,KAAK,0BAAkB,CAAC;IACrF,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,MAAM,CACf,cAA8B;QAE9B,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,IAAI,0BAAkB,CAAC;QACrE,IAAI,WAAW,KAAK,0BAAkB,EAAE,CAAC;YACrC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACzD,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;IAChG,CAAC;CACJ;AA7DD,kDA6DC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "node-opcua-alias-name-client",
+    "version": "2.176.0",
+    "description": "pure nodejs OPCUA SDK - client-side alias names (OPC 10000-17)",
+    "scripts": {
+        "build": "tsc -b",
+        "lint": "biome check .",
+        "format": "biome check --write .",
+        "clean": "npx rimraf -g node_modules dist *.tsbuildinfo",
+        "test": "mocha",
+        "test:check": "tsc --noEmit -p test/tsconfig.json"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "devEngines": {
+        "node": ">=18.x",
+        "npm": ">=10.x"
+    },
+    "dependencies": {
+        "node-opcua-constants": "2.176.0",
+        "node-opcua-data-model": "2.176.0",
+        "node-opcua-nodeid": "2.176.0",
+        "node-opcua-pseudo-session": "2.176.0",
+        "node-opcua-service-translate-browse-path": "2.176.0",
+        "node-opcua-status-code": "2.176.0",
+        "node-opcua-types": "2.176.0",
+        "node-opcua-variant": "2.176.0"
+    },
+    "devDependencies": {
+        "node-opcua-address-space": "2.176.0",
+        "node-opcua-alias-name-server": "2.176.0",
+        "node-opcua-leak-detector": "2.175.6",
+        "node-opcua-nodesets": "2.175.3"
+    },
+    "author": "Etienne Rossignon",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/node-opcua/node-opcua.git"
+    },
+    "keywords": [
+        "OPCUA",
+        "opcua",
+        "m2m",
+        "iot",
+        "opc ua",
+        "internet of things"
+    ],
+    "homepage": "http://node-opcua.github.io/",
+    "files": [
+        "dist",
+        "source"
+    ]
+}

package/source/client_alias_set.ts

@@ -0,0 +1,312 @@
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Client-side API for OPC UA AliasNames (OPC 10000-17).
+ *
+ * All navigation goes through {@link IBasicSessionAsync2} — browse, read, call,
+ * translateBrowsePath — so the same code drives a remote `ClientSession` and an
+ * in-process `PseudoSession`. That is what lets these be tested without a
+ * transport, and what lets a Server-side tool resolve its own aliases through
+ * the same API a Client uses.
+ */
+
+import { ObjectIds } from "node-opcua-constants";
+import { BrowseDirection, NodeClass, type QualifiedName } from "node-opcua-data-model";
+import { type ExpandedNodeId, type NodeId, NodeId as NodeIdClass, resolveNodeId } from "node-opcua-nodeid";
+import type { IBasicSessionAsync2 } from "node-opcua-pseudo-session";
+import { makeBrowsePath } from "node-opcua-service-translate-browse-path";
+import type { AliasNameDataType, AliasNameVerboseDataType } from "node-opcua-types";
+import { DataType } from "node-opcua-variant";
+import { AliasNameCallError, AliasNameMethodNotSupportedError } from "./errors.js";
+import { ServerIndexResolver } from "./server_index_resolver.js";
+
+/** `Aliases`, the root of the hierarchy (OPC 10000-17 clause 9.2). */
+export const ALIASES_ROOT: NodeId = resolveNodeId(ObjectIds.Aliases);
+/** `TagVariables` (clause 9.3). */
+export const TAG_VARIABLES: NodeId = resolveNodeId(ObjectIds.TagVariables);
+/** `Topics` (clause 9.4). */
+export const TOPICS: NodeId = resolveNodeId(ObjectIds.Topics);
+
+/** One resolved AliasName, as `FindAlias` reports it (clause 7.2). */
+export interface ClientAliasEntry {
+    /** The string part of the AliasName. */
+    aliasName: string;
+    /**
+     * The namespace the AliasName was published in.
+     *
+     * Clause 6.2 requires a Client to **ignore this when comparing** AliasNames.
+     * It is reported for completeness, not for matching.
+     */
+    namespaceIndex: number;
+    /** The Nodes the alias names, best match first (clause 6.3.2). */
+    referencedNodes: ExpandedNodeId[];
+}
+
+/** One resolved AliasName, as `FindAliasVerbose` reports it (clause 7.3). */
+export interface ClientAliasVerboseEntry extends ClientAliasEntry {
+    /**
+     * Parallel to {@link referencedNodes}: the ServerUri of each Node, `null`
+     * for one on the Server that answered.
+     */
+    serverUris: (string | null)[];
+    /**
+     * The category that actually held the alias, which for a recursive search is
+     * the nested one rather than the one that was called.
+     */
+    aliasNameCategoryId: NodeId;
+}
+
+export interface FindAliasOptions {
+    /**
+     * The category to search, recursively. Defaults to {@link ALIASES_ROOT},
+     * which covers everything the Server publishes.
+     */
+    categoryNodeId?: NodeId;
+    /**
+     * Restrict to this ReferenceType and its subtypes (clause 6.3.2 Table 3).
+     * Omit for any.
+     */
+    referenceTypeFilter?: NodeId;
+}
+
+/** The Methods a category may carry. */
+interface CategoryMethods {
+    findAlias: NodeId | null;
+    findAliasVerbose: NodeId | null;
+    addAliasesToCategory: NodeId | null;
+    deleteAliasesFromCategory: NodeId | null;
+}
+
+/** Read a QualifiedName's parts defensively — a Server may send a bare string. */
+function qualifiedName(value: QualifiedName | undefined): { name: string; namespaceIndex: number } {
+    return { name: value?.name ?? "", namespaceIndex: value?.namespaceIndex ?? 0 };
+}
+
+/**
+ * Client-side entry point for a Server's AliasNames.
+ *
+ * ```ts
+ * const aliases = new ClientAliasSet(session);
+ * const [entry] = await aliases.findAlias("TI101");
+ * const nodeId = entry.referencedNodes[0];
+ * ```
+ *
+ * Construct one per session: Method NodeIds are resolved lazily, in a single
+ * `translateBrowsePath` round trip per category, and cached for the lifetime of
+ * the instance.
+ *
+ * This resolves the aliases **a Server publishes about itself**. Aggregating
+ * across Servers (OPC 10000-17 Annexes B and C) is out of scope; where a Server
+ * does aggregate, {@link serverIndexResolver} turns the `ServerIndex` of a
+ * returned `ExpandedNodeId` into a URI.
+ */
+export class ClientAliasSet {
+    public readonly session: IBasicSessionAsync2;
+    /** Resolves the `ServerIndex` of a returned Node (Annex A). */
+    public readonly serverIndexResolver: ServerIndexResolver;
+
+    private readonly methodCache = new Map<string, CategoryMethods>();
+
+    constructor(session: IBasicSessionAsync2) {
+        this.session = session;
+        this.serverIndexResolver = new ServerIndexResolver(session);
+    }
+
+    /**
+     * Resolve an AliasName, or a `Like` pattern, to the Nodes it names.
+     *
+     * The pattern is an OPC 10000-4 `Like` pattern: `%` is any run of
+     * characters, `_` is exactly one, `[abc]` and `[^abc]` are lists, and `\`
+     * escapes. An exact name is simply a pattern with no wildcards.
+     *
+     * @throws {@link AliasNameCallError} when the Server answers a bad
+     * StatusCode — `Bad_InvalidArgument` for a malformed pattern,
+     * `Bad_ResponseTooLarge` when a narrower filter is needed,
+     * `Bad_UserAccessDenied` when the session may not read the category.
+     */
+    public async findAlias(pattern: string, options?: FindAliasOptions): Promise<ClientAliasEntry[]> {
+        const categoryNodeId = options?.categoryNodeId ?? ALIASES_ROOT;
+        const methods = await this.resolveMethods(categoryNodeId);
+        if (!methods.findAlias) {
+            // FindAlias is MANDATORY, so this means the Node is not an
+            // AliasNameCategoryType instance, or the Server is non-conformant
+            throw new AliasNameMethodNotSupportedError("FindAlias", categoryNodeId);
+        }
+
+        const extensionObjects = await this.callFind(
+            "FindAlias",
+            categoryNodeId,
+            methods.findAlias,
+            pattern,
+            options?.referenceTypeFilter
+        );
+
+        return extensionObjects.map((raw) => {
+            const value = raw as AliasNameDataType;
+            const { name, namespaceIndex } = qualifiedName(value.aliasName);
+            return {
+                aliasName: name,
+                namespaceIndex,
+                referencedNodes: value.referencedNodes ?? []
+            };
+        });
+    }
+
+    /**
+     * Resolve an AliasName and learn which category held it and which Server
+     * each Node is on (clause 6.3.3).
+     *
+     * @throws {@link AliasNameMethodNotSupportedError} when the Server exposes
+     * only the mandatory `FindAlias`. That is a conformant Server, so this is
+     * an expected outcome to handle, not a fault — use {@link supportsVerbose}
+     * to check first.
+     */
+    public async findAliasVerbose(pattern: string, options?: FindAliasOptions): Promise<ClientAliasVerboseEntry[]> {
+        const categoryNodeId = options?.categoryNodeId ?? ALIASES_ROOT;
+        const methods = await this.resolveMethods(categoryNodeId);
+        if (!methods.findAliasVerbose) {
+            throw new AliasNameMethodNotSupportedError("FindAliasVerbose", categoryNodeId);
+        }
+
+        const extensionObjects = await this.callFind(
+            "FindAliasVerbose",
+            categoryNodeId,
+            methods.findAliasVerbose,
+            pattern,
+            options?.referenceTypeFilter
+        );
+
+        return extensionObjects.map((raw) => {
+            const value = raw as AliasNameVerboseDataType;
+            const { name, namespaceIndex } = qualifiedName(value.aliasName);
+            return {
+                aliasName: name,
+                namespaceIndex,
+                referencedNodes: value.referencedNodes ?? [],
+                serverUris: value.serverUris ?? [],
+                aliasNameCategoryId: value.aliasNameCategoryId
+            };
+        });
+    }
+
+    /**
+     * True when the Server exposes `FindAliasVerbose` on this category.
+     *
+     * Cheaper than catching {@link AliasNameMethodNotSupportedError}, and reads
+     * better when the Client has a fallback path.
+     */
+    public async supportsVerbose(categoryNodeId: NodeId = ALIASES_ROOT): Promise<boolean> {
+        return (await this.resolveMethods(categoryNodeId)).findAliasVerbose !== null;
+    }
+
+    /**
+     * True when the Server exposes the configuration Methods on this category
+     * (clauses 6.3.4 and 6.3.5). They are optional and off by default in most
+     * Servers.
+     */
+    public async supportsConfiguration(categoryNodeId: NodeId = ALIASES_ROOT): Promise<boolean> {
+        const methods = await this.resolveMethods(categoryNodeId);
+        return methods.addAliasesToCategory !== null && methods.deleteAliasesFromCategory !== null;
+    }
+
+    /**
+     * The `AliasNameCategoryType` instances Organized directly by a category.
+     *
+     * Browsing is not needed to *resolve* an alias — `FindAlias` on the root
+     * searches recursively — but a Client that wants to show the hierarchy, or
+     * to search one branch, needs it.
+     */
+    public async browseSubCategories(
+        categoryNodeId: NodeId = ALIASES_ROOT
+    ): Promise<Array<{ nodeId: NodeId; browseName: string }>> {
+        const result = await this.session.browse({
+            nodeId: categoryNodeId,
+            browseDirection: BrowseDirection.Forward,
+            referenceTypeId: resolveNodeId("Organizes"),
+            includeSubtypes: true,
+            nodeClassMask: NodeClass.Object,
+            resultMask: 0x3f
+        });
+        const references = result.references ?? [];
+        const out: Array<{ nodeId: NodeId; browseName: string }> = [];
+        for (const reference of references) {
+            // an AliasNameCategoryType instance carries FindAlias; an
+            // AliasNameType instance does not, which is how they are told apart
+            // without reading TypeDefinition for each
+            const methods = await this.resolveMethods(reference.nodeId);
+            if (methods.findAlias) {
+                out.push({ nodeId: reference.nodeId, browseName: reference.browseName.name ?? "" });
+            }
+        }
+        return out;
+    }
+
+    /** Forget every cached Method NodeId. */
+    public invalidate(): void {
+        this.methodCache.clear();
+        this.serverIndexResolver.invalidate();
+    }
+
+    /**
+     * Resolve every Method of a category in **one** `translateBrowsePath` round
+     * trip, and cache the result.
+     *
+     * Asking for all four at once costs no more than asking for one, and means a
+     * Client that later calls `findAliasVerbose` after `findAlias` makes no
+     * further round trip.
+     */
+    private async resolveMethods(categoryNodeId: NodeId): Promise<CategoryMethods> {
+        const key = categoryNodeId.toString();
+        const cached = this.methodCache.get(key);
+        if (cached) {
+            return cached;
+        }
+
+        const names = ["FindAlias", "FindAliasVerbose", "AddAliasesToCategory", "DeleteAliasesFromCategory"] as const;
+        const results = await this.session.translateBrowsePath(names.map((name) => makeBrowsePath(categoryNodeId, `/${name}`)));
+
+        const pick = (index: number): NodeId | null => {
+            const result = results[index];
+            return result?.statusCode.isGood() && result.targets?.length ? result.targets[0].targetId : null;
+        };
+        const methods: CategoryMethods = {
+            findAlias: pick(0),
+            findAliasVerbose: pick(1),
+            addAliasesToCategory: pick(2),
+            deleteAliasesFromCategory: pick(3)
+        };
+        this.methodCache.set(key, methods);
+        return methods;
+    }
+
+    /** Call one of the two find Methods and return its ExtensionObject array. */
+    private async callFind(
+        methodName: string,
+        categoryNodeId: NodeId,
+        methodId: NodeId,
+        pattern: string,
+        referenceTypeFilter?: NodeId
+    ): Promise<unknown[]> {
+        const result = await this.session.call({
+            objectId: categoryNodeId,
+            methodId,
+            inputArguments: [
+                { dataType: DataType.String, value: pattern },
+                // an omitted filter is the null NodeId, not a null value
+                { dataType: DataType.NodeId, value: referenceTypeFilter ?? NodeIdClass.nullNodeId }
+            ]
+        });
+
+        if (!result.statusCode.isGood()) {
+            throw new AliasNameCallError(methodName, categoryNodeId, result.statusCode);
+        }
+
+        const output = result.outputArguments?.[0];
+        const value = output?.value;
+        // no match is Good with an empty list (clause 6.3.2 Table 3)
+        if (value === null || value === undefined) {
+            return [];
+        }
+        return Array.isArray(value) ? value : [value];
+    }
+}

package/source/errors.ts

@@ -0,0 +1,57 @@
+/**
+ * @module node-opcua-alias-name-client
+ */
+
+import type { NodeId } from "node-opcua-nodeid";
+import type { StatusCode } from "node-opcua-status-code";
+
+/**
+ * The Server does not expose the Method that was asked for.
+ *
+ * `FindAlias` is MANDATORY on every `AliasNameCategoryType` instance, but
+ * `FindAliasVerbose`, `AddAliasesToCategory` and `DeleteAliasesFromCategory` are
+ * all optional (OPC 10000-17 clause 6.3). A Server that implements only the
+ * mandatory Method is perfectly conformant, so a Client that wants the verbose
+ * form must be able to tell "this Server does not offer it" apart from "the call
+ * failed".
+ *
+ * Raised before any call is made — the Method's absence is discovered while
+ * resolving NodeIds — so it never surfaces as an unhandled `Bad_NotImplemented`
+ * from the wire.
+ */
+export class AliasNameMethodNotSupportedError extends Error {
+    /** The Method that is missing, by BrowseName. */
+    public readonly methodName: string;
+    /** The category it was looked for on. */
+    public readonly categoryNodeId: NodeId;
+
+    constructor(methodName: string, categoryNodeId: NodeId) {
+        super(
+            `the Server does not expose ${methodName} on ${categoryNodeId.toString()}. ` +
+                "Only FindAlias is mandatory in OPC 10000-17 clause 6.3; the rest are optional."
+        );
+        this.name = "AliasNameMethodNotSupportedError";
+        this.methodName = methodName;
+        this.categoryNodeId = categoryNodeId;
+    }
+}
+
+/**
+ * The Server answered a `FindAlias` call with a bad StatusCode.
+ *
+ * Carries the code so a caller can distinguish the cases clause 6.3.2 Table 4
+ * defines — `Bad_InvalidArgument` for a malformed search pattern,
+ * `Bad_ResponseTooLarge` for a result set that needs a narrower filter,
+ * `Bad_UserAccessDenied` for a category the session may not read.
+ */
+export class AliasNameCallError extends Error {
+    public readonly statusCode: StatusCode;
+    public readonly categoryNodeId: NodeId;
+
+    constructor(methodName: string, categoryNodeId: NodeId, statusCode: StatusCode) {
+        super(`${methodName} on ${categoryNodeId.toString()} failed with ${statusCode.toString()}`);
+        this.name = "AliasNameCallError";
+        this.statusCode = statusCode;
+        this.categoryNodeId = categoryNodeId;
+    }
+}

package/source/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Client-side OPC 10000-17 (AliasNames).
+ *
+ * Resolves the AliasNames **a Server publishes about itself**. Aggregating
+ * AliasNames collected from other Servers (Annexes B and C) and the Annex D
+ * PubSub change notification are out of scope; {@link ServerIndexResolver}
+ * covers the one cross-Server step a Client still has to make, turning the
+ * `ServerIndex` of a returned `ExpandedNodeId` into a URI (Annex A).
+ */
+
+export {
+    ALIASES_ROOT,
+    type ClientAliasEntry,
+    ClientAliasSet,
+    type ClientAliasVerboseEntry,
+    type FindAliasOptions,
+    TAG_VARIABLES,
+    TOPICS
+} from "./client_alias_set.js";
+export { AliasNameCallError, AliasNameMethodNotSupportedError } from "./errors.js";
+export { LOCAL_SERVER_INDEX, ServerIndexResolver } from "./server_index_resolver.js";