node-opcua-alias-name-client 2.176.0 → 2.178.0

package/README.md

@@ -101,6 +101,43 @@ for one, so a later `findAliasVerbose` after a `findAlias` makes no further roun
 Construct one `ClientAliasSet` per session; call `invalidate()` if the Server's address
 space changes underneath it.
 
+## Recovering the ReferenceType of each target
+
+`AliasNameDataType` and `AliasNameVerboseDataType` (clauses 7.2 and 7.3) carry the
+referenced Nodes but **not** the ReferenceType of each Reference: a target linked with a
+vendor subtype of `AliasFor` (clause 8.2) comes back indistinguishable from one linked
+with `AliasFor` itself. That is a limitation of the DataTypes, not of any Server.
+
+Most Clients never care — they want the NodeId. An **aggregator** re-publishing pulled
+aliases does: recorded as plain `AliasFor`, a downstream `FindAlias` whose
+`ReferenceTypeFilter` names the subtype can no longer be answered faithfully across the
+aggregation hop. `readAliasReferenceTypes` recovers the actual ReferenceType per
+(alias, target) by browsing the `AliasNameType` instance Nodes:
+
+```ts
+import { readAliasReferenceTypes } from "node-opcua-alias-name-client";
+
+const entries = await aliases.findAliasVerbose("%", { categoryNodeId });
+const referenceTypes = await readAliasReferenceTypes(session, entries);
+for (const entry of entries) {
+    for (const { targetNodeId, referenceTypeId } of referenceTypes.get(entry) ?? []) {
+        republish(entry.aliasName, targetNodeId, referenceTypeId);
+    }
+}
+```
+
+The map is keyed by the very elements passed in; an entry the Server could not resolve
+(deleted since the find, for instance) is absent rather than guessed at. Callers that
+already know the `AliasNameType` instance NodeIds can pass those instead of verbose
+entries and skip the lookup step.
+
+**Cost.** One `TranslateBrowsePaths` request per 1000 aliases to locate the instance
+Nodes (skipped when NodeIds are passed), one `Browse` request per 1000, plus a
+`BrowseNext` round trip per continuation the Server imposes — batched precisely so a
+large category is a handful of round trips, never one per alias. Lower `maxNodesPerCall`
+when a Server advertises tighter `OperationLimits` (OPC 10000-5 clause 6.3.11). If you
+only resolve names to NodeIds, skip all of it.
+
 ## Nodes on another Server (Annex A)
 
 A returned `ExpandedNodeId` may carry a non-zero `ServerIndex`, which says only "this Node

package/dist/index.d.ts

@@ -11,4 +11,5 @@
  */
 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 { type AliasReferenceTypeEntry, type ReadAliasReferenceTypesOptions, readAliasReferenceTypes } from "./read_alias_reference_types.js";
 export { LOCAL_SERVER_INDEX, ServerIndexResolver } from "./server_index_resolver.js";

package/dist/index.js

@@ -11,7 +11,7 @@
  * `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;
+exports.ServerIndexResolver = exports.LOCAL_SERVER_INDEX = exports.readAliasReferenceTypes = 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; } });
@@ -20,6 +20,8 @@ Object.defineProperty(exports, "TOPICS", { enumerable: true, get: function () {
 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 read_alias_reference_types_js_1 = require("./read_alias_reference_types.js");
+Object.defineProperty(exports, "readAliasReferenceTypes", { enumerable: true, get: function () { return read_alias_reference_types_js_1.readAliasReferenceTypes; } });
 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; } });

package/dist/index.js.map

@@ -1 +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"}
+{"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,iFAIyC;AADrC,wIAAA,uBAAuB,OAAA;AAE3B,uEAAqF;AAA5E,8HAAA,kBAAkB,OAAA;AAAE,+HAAA,mBAAmB,OAAA"}

package/dist/read_alias_reference_types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Recover the ReferenceType linking each AliasName to each of its targets.
+ *
+ * `AliasNameDataType` and `AliasNameVerboseDataType` (OPC 10000-17 clauses 7.2
+ * and 7.3) carry the referenced Nodes, but **not** the ReferenceType of each
+ * Reference: a target linked with a vendor subtype of `AliasFor` (clause 8.2)
+ * comes back from `FindAlias` / `FindAliasVerbose` indistinguishable from one
+ * linked with `AliasFor` itself. That is a limitation of the DataTypes, not of
+ * any particular Server.
+ *
+ * Most Clients never notice — they want the NodeId and the subtype carries no
+ * extra meaning for them. An **aggregating** Server does: re-published as plain
+ * `AliasFor`, a downstream `FindAlias` whose `ReferenceTypeFilter` names the
+ * subtype (clause 6.3.2 Table 3) cannot be answered faithfully across the
+ * aggregation hop. {@link readAliasReferenceTypes} closes that gap by going
+ * back to the address space: the `AliasNameType` instances are Nodes, and
+ * Browse reports the ReferenceType of every Reference they hold.
+ */
+import { type ExpandedNodeId, type NodeId } from "node-opcua-nodeid";
+import type { IBasicSessionAsync2 } from "node-opcua-pseudo-session";
+import type { ClientAliasVerboseEntry } from "./client_alias_set.js";
+/** One (alias, target) link, with the ReferenceType the find Methods cannot report. */
+export interface AliasReferenceTypeEntry {
+    /** The Node the alias names — matches one element of `referencedNodes`. */
+    targetNodeId: ExpandedNodeId;
+    /** `AliasFor` (i=23469) or the subtype the publisher actually used. */
+    referenceTypeId: NodeId;
+}
+export interface ReadAliasReferenceTypesOptions {
+    /**
+     * Upper bound on the operations packed into one `TranslateBrowsePaths` or
+     * `Browse` request. The default of 1000 fits most Servers; lower it when a
+     * Server advertises tighter `OperationLimits` (OPC 10000-5 clause 6.3.11) —
+     * `Bad_TooManyOperations` is the symptom of exceeding them.
+     */
+    maxNodesPerCall?: number;
+}
+/**
+ * Read the ReferenceType of every `AliasFor` Reference (and subtype) each alias
+ * holds, which is the one thing `FindAliasVerbose` cannot report.
+ *
+ * ```ts
+ * const entries = await aliases.findAliasVerbose("%", { categoryNodeId });
+ * const referenceTypes = await readAliasReferenceTypes(session, entries);
+ * for (const entry of entries) {
+ *     for (const { targetNodeId, referenceTypeId } of referenceTypes.get(entry) ?? []) {
+ *         republish(entry.aliasName, targetNodeId, referenceTypeId);
+ *     }
+ * }
+ * ```
+ *
+ * **When to use it.** Only when the ReferenceType itself matters — typically an
+ * aggregator that must re-publish pulled aliases with reference-type fidelity,
+ * so a downstream `ReferenceTypeFilter` naming an `AliasFor` subtype keeps
+ * working across the hop. A Client that only resolves names to NodeIds gets
+ * nothing from it and should not pay for it.
+ *
+ * **What it costs.** On top of the find call already made: one
+ * `TranslateBrowsePaths` request per {@link ReadAliasReferenceTypesOptions.maxNodesPerCall}
+ * aliases to locate the `AliasNameType` instance Nodes (skipped when NodeIds
+ * are passed directly), then one `Browse` request per batch, plus one
+ * `BrowseNext` round trip per continuation the Server imposes. The requests are
+ * batched precisely so a large category does **not** become one round trip per
+ * alias: 1000 aliases resolve in two or three round trips, not 1000.
+ *
+ * The result is keyed by the **very elements passed in** — look entries up with
+ * the objects from the input array, not with reconstructed equals. An input the
+ * Server could not resolve (the alias was deleted since the find, a NodeId that
+ * no longer browses) is absent from the map rather than present with a guess.
+ *
+ * @param session any `IBasicSessionAsync2` — a remote `ClientSession` or an
+ *   in-process `PseudoSession`, as everywhere in this package
+ * @param aliases either the entries of a `findAliasVerbose` call, or the
+ *   NodeIds of `AliasNameType` instance Nodes when the caller already knows
+ *   them (from browsing a category, or from its own bookkeeping)
+ */
+export declare function readAliasReferenceTypes(session: IBasicSessionAsync2, aliases: NodeId[], options?: ReadAliasReferenceTypesOptions): Promise<Map<NodeId, AliasReferenceTypeEntry[]>>;
+export declare function readAliasReferenceTypes(session: IBasicSessionAsync2, aliases: ClientAliasVerboseEntry[], options?: ReadAliasReferenceTypesOptions): Promise<Map<ClientAliasVerboseEntry, AliasReferenceTypeEntry[]>>;

package/dist/read_alias_reference_types.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Recover the ReferenceType linking each AliasName to each of its targets.
+ *
+ * `AliasNameDataType` and `AliasNameVerboseDataType` (OPC 10000-17 clauses 7.2
+ * and 7.3) carry the referenced Nodes, but **not** the ReferenceType of each
+ * Reference: a target linked with a vendor subtype of `AliasFor` (clause 8.2)
+ * comes back from `FindAlias` / `FindAliasVerbose` indistinguishable from one
+ * linked with `AliasFor` itself. That is a limitation of the DataTypes, not of
+ * any particular Server.
+ *
+ * Most Clients never notice — they want the NodeId and the subtype carries no
+ * extra meaning for them. An **aggregating** Server does: re-published as plain
+ * `AliasFor`, a downstream `FindAlias` whose `ReferenceTypeFilter` names the
+ * subtype (clause 6.3.2 Table 3) cannot be answered faithfully across the
+ * aggregation hop. {@link readAliasReferenceTypes} closes that gap by going
+ * back to the address space: the `AliasNameType` instances are Nodes, and
+ * Browse reports the ReferenceType of every Reference they hold.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAliasReferenceTypes = readAliasReferenceTypes;
+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");
+const node_opcua_service_translate_browse_path_1 = require("node-opcua-service-translate-browse-path");
+/** `AliasFor` (i=23469), the base ReferenceType of every alias link (clause 8.2). */
+const ALIAS_FOR = (0, node_opcua_nodeid_1.resolveNodeId)(node_opcua_constants_1.ReferenceTypeIds.AliasFor);
+const HIERARCHICAL_REFERENCES = (0, node_opcua_nodeid_1.resolveNodeId)(node_opcua_constants_1.ReferenceTypeIds.HierarchicalReferences);
+const REFERENCE_TYPE_RESULT_MASK = (0, node_opcua_data_model_1.makeResultMask)("ReferenceType");
+const DEFAULT_MAX_NODES_PER_CALL = 1000;
+async function readAliasReferenceTypes(session, aliases, options) {
+    const maxNodesPerCall = Math.max(1, options?.maxNodesPerCall ?? DEFAULT_MAX_NODES_PER_CALL);
+    const result = new Map();
+    if (aliases.length === 0) {
+        return result;
+    }
+    const aliasNodeIds = aliases[0] instanceof node_opcua_nodeid_1.NodeId
+        ? aliases
+        : await resolveAliasNodeIds(session, aliases, maxNodesPerCall);
+    const targets = await browseAliasTargets(session, aliasNodeIds, maxNodesPerCall);
+    aliases.forEach((key, index) => {
+        const entries = targets[index];
+        if (entries) {
+            result.set(key, entries);
+        }
+    });
+    return result;
+}
+/**
+ * Locate the `AliasNameType` instance Node behind each verbose entry.
+ *
+ * `FindAliasVerbose` names the category that held the alias
+ * (`aliasNameCategoryId`, clause 7.3) but not the alias Node itself, so the
+ * Node is found by translating one browse path below the category. The
+ * `RelativePath` is built element by element rather than parsed from a string,
+ * so an alias name containing `/`, `&` or the other OPC 10000-4 Annex A
+ * reserved characters needs no escaping. The QualifiedName match is exact —
+ * the entry's `namespaceIndex` is the one the Server reported, so this is the
+ * one place the namespace of an AliasName is **not** ignored.
+ *
+ * Unresolvable entries yield `null`, keeping positions aligned with the input.
+ */
+async function resolveAliasNodeIds(session, entries, maxNodesPerCall) {
+    const aliasNodeIds = new Array(entries.length).fill(null);
+    for (let offset = 0; offset < entries.length; offset += maxNodesPerCall) {
+        const chunk = entries.slice(offset, offset + maxNodesPerCall);
+        const results = await session.translateBrowsePath(chunk.map((entry) => new node_opcua_service_translate_browse_path_1.BrowsePath({
+            startingNode: entry.aliasNameCategoryId,
+            relativePath: {
+                elements: [
+                    {
+                        referenceTypeId: HIERARCHICAL_REFERENCES,
+                        isInverse: false,
+                        includeSubtypes: true,
+                        targetName: { namespaceIndex: entry.namespaceIndex, name: entry.aliasName }
+                    }
+                ]
+            }
+        })));
+        results.forEach((browsePathResult, index) => {
+            if (browsePathResult.statusCode.isGood() && browsePathResult.targets?.length) {
+                // the targetId of a local Node is an ExpandedNodeId with
+                // serverIndex 0, usable as a NodeId as-is
+                aliasNodeIds[offset + index] = browsePathResult.targets[0].targetId;
+            }
+        });
+    }
+    return aliasNodeIds;
+}
+/**
+ * Browse the forward `AliasFor` References (subtypes included) of many alias
+ * Nodes in as few requests as possible, following every continuation point.
+ *
+ * Positions align with the input; `null` marks a Node that could not be
+ * resolved upstream or whose Browse did not complete — for the fidelity use
+ * case, an absent answer beats a truncated one presented as complete.
+ */
+async function browseAliasTargets(session, aliasNodeIds, maxNodesPerCall) {
+    const targets = new Array(aliasNodeIds.length).fill(null);
+    const toBrowse = [];
+    aliasNodeIds.forEach((nodeId, index) => {
+        if (nodeId) {
+            toBrowse.push({ index, nodeId });
+        }
+    });
+    const toEntry = (reference) => ({
+        targetNodeId: reference.nodeId,
+        referenceTypeId: reference.referenceTypeId
+    });
+    for (let offset = 0; offset < toBrowse.length; offset += maxNodesPerCall) {
+        const chunk = toBrowse.slice(offset, offset + maxNodesPerCall);
+        const browseResults = await session.browse(chunk.map(({ nodeId }) => ({
+            nodeId,
+            browseDirection: node_opcua_data_model_1.BrowseDirection.Forward,
+            referenceTypeId: ALIAS_FOR,
+            includeSubtypes: true,
+            nodeClassMask: 0,
+            resultMask: REFERENCE_TYPE_RESULT_MASK
+        })));
+        // continuations, batched too: one BrowseNext round trip serves every
+        // Node of the chunk that was truncated, however many there are
+        let pending = [];
+        browseResults.forEach((browseResult, chunkIndex) => {
+            const { index } = chunk[chunkIndex];
+            if (!browseResult.statusCode.isGood()) {
+                return;
+            }
+            targets[index] = (browseResult.references ?? []).map(toEntry);
+            if (browseResult.continuationPoint?.length) {
+                pending.push({ index, continuationPoint: browseResult.continuationPoint });
+            }
+        });
+        while (pending.length > 0) {
+            const nextResults = await session.browseNext(pending.map(({ continuationPoint }) => continuationPoint), false);
+            const stillPending = [];
+            nextResults.forEach((browseResult, pendingIndex) => {
+                const { index } = pending[pendingIndex];
+                if (!browseResult.statusCode.isGood()) {
+                    // incomplete: withdraw the partial answer rather than let it
+                    // pass for the whole truth
+                    targets[index] = null;
+                    return;
+                }
+                targets[index]?.push(...(browseResult.references ?? []).map(toEntry));
+                if (browseResult.continuationPoint?.length) {
+                    stillPending.push({ index, continuationPoint: browseResult.continuationPoint });
+                }
+            });
+            pending = stillPending;
+        }
+    }
+    return targets;
+}
+//# sourceMappingURL=read_alias_reference_types.js.map

package/dist/read_alias_reference_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_alias_reference_types.js","sourceRoot":"","sources":["../source/read_alias_reference_types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-opcua-alias-name-client",
-    "version": "2.176.0",
+    "version": "2.178.0",
     "description": "pure nodejs OPCUA SDK - client-side alias names (OPC 10000-17)",
     "scripts": {
         "build": "tsc -b",
@@ -18,17 +18,17 @@
     },
     "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-data-model": "2.177.0",
+        "node-opcua-nodeid": "2.177.0",
+        "node-opcua-pseudo-session": "2.178.0",
+        "node-opcua-service-translate-browse-path": "2.177.0",
         "node-opcua-status-code": "2.176.0",
-        "node-opcua-types": "2.176.0",
-        "node-opcua-variant": "2.176.0"
+        "node-opcua-types": "2.177.0",
+        "node-opcua-variant": "2.177.0"
     },
     "devDependencies": {
-        "node-opcua-address-space": "2.176.0",
-        "node-opcua-alias-name-server": "2.176.0",
+        "node-opcua-address-space": "2.178.0",
+        "node-opcua-alias-name-server": "2.178.0",
         "node-opcua-leak-detector": "2.175.6",
         "node-opcua-nodesets": "2.175.3"
     },
@@ -50,5 +50,6 @@
     "files": [
         "dist",
         "source"
-    ]
+    ],
+    "gitHead": "d0e850e5f7df80e14ceb6d8e092e793472965301"
 }

package/source/index.ts

@@ -20,4 +20,9 @@ export {
     TOPICS
 } from "./client_alias_set.js";
 export { AliasNameCallError, AliasNameMethodNotSupportedError } from "./errors.js";
+export {
+    type AliasReferenceTypeEntry,
+    type ReadAliasReferenceTypesOptions,
+    readAliasReferenceTypes
+} from "./read_alias_reference_types.js";
 export { LOCAL_SERVER_INDEX, ServerIndexResolver } from "./server_index_resolver.js";

package/source/read_alias_reference_types.ts

@@ -0,0 +1,257 @@
+/**
+ * @module node-opcua-alias-name-client
+ *
+ * Recover the ReferenceType linking each AliasName to each of its targets.
+ *
+ * `AliasNameDataType` and `AliasNameVerboseDataType` (OPC 10000-17 clauses 7.2
+ * and 7.3) carry the referenced Nodes, but **not** the ReferenceType of each
+ * Reference: a target linked with a vendor subtype of `AliasFor` (clause 8.2)
+ * comes back from `FindAlias` / `FindAliasVerbose` indistinguishable from one
+ * linked with `AliasFor` itself. That is a limitation of the DataTypes, not of
+ * any particular Server.
+ *
+ * Most Clients never notice — they want the NodeId and the subtype carries no
+ * extra meaning for them. An **aggregating** Server does: re-published as plain
+ * `AliasFor`, a downstream `FindAlias` whose `ReferenceTypeFilter` names the
+ * subtype (clause 6.3.2 Table 3) cannot be answered faithfully across the
+ * aggregation hop. {@link readAliasReferenceTypes} closes that gap by going
+ * back to the address space: the `AliasNameType` instances are Nodes, and
+ * Browse reports the ReferenceType of every Reference they hold.
+ */
+
+import { ReferenceTypeIds } from "node-opcua-constants";
+import { BrowseDirection, makeResultMask } 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 { BrowsePath } from "node-opcua-service-translate-browse-path";
+import type { ReferenceDescription } from "node-opcua-types";
+import type { ClientAliasVerboseEntry } from "./client_alias_set.js";
+
+/** `AliasFor` (i=23469), the base ReferenceType of every alias link (clause 8.2). */
+const ALIAS_FOR: NodeId = resolveNodeId(ReferenceTypeIds.AliasFor);
+const HIERARCHICAL_REFERENCES: NodeId = resolveNodeId(ReferenceTypeIds.HierarchicalReferences);
+const REFERENCE_TYPE_RESULT_MASK = makeResultMask("ReferenceType");
+const DEFAULT_MAX_NODES_PER_CALL = 1000;
+
+/** One (alias, target) link, with the ReferenceType the find Methods cannot report. */
+export interface AliasReferenceTypeEntry {
+    /** The Node the alias names — matches one element of `referencedNodes`. */
+    targetNodeId: ExpandedNodeId;
+    /** `AliasFor` (i=23469) or the subtype the publisher actually used. */
+    referenceTypeId: NodeId;
+}
+
+export interface ReadAliasReferenceTypesOptions {
+    /**
+     * Upper bound on the operations packed into one `TranslateBrowsePaths` or
+     * `Browse` request. The default of 1000 fits most Servers; lower it when a
+     * Server advertises tighter `OperationLimits` (OPC 10000-5 clause 6.3.11) —
+     * `Bad_TooManyOperations` is the symptom of exceeding them.
+     */
+    maxNodesPerCall?: number;
+}
+
+/**
+ * Read the ReferenceType of every `AliasFor` Reference (and subtype) each alias
+ * holds, which is the one thing `FindAliasVerbose` cannot report.
+ *
+ * ```ts
+ * const entries = await aliases.findAliasVerbose("%", { categoryNodeId });
+ * const referenceTypes = await readAliasReferenceTypes(session, entries);
+ * for (const entry of entries) {
+ *     for (const { targetNodeId, referenceTypeId } of referenceTypes.get(entry) ?? []) {
+ *         republish(entry.aliasName, targetNodeId, referenceTypeId);
+ *     }
+ * }
+ * ```
+ *
+ * **When to use it.** Only when the ReferenceType itself matters — typically an
+ * aggregator that must re-publish pulled aliases with reference-type fidelity,
+ * so a downstream `ReferenceTypeFilter` naming an `AliasFor` subtype keeps
+ * working across the hop. A Client that only resolves names to NodeIds gets
+ * nothing from it and should not pay for it.
+ *
+ * **What it costs.** On top of the find call already made: one
+ * `TranslateBrowsePaths` request per {@link ReadAliasReferenceTypesOptions.maxNodesPerCall}
+ * aliases to locate the `AliasNameType` instance Nodes (skipped when NodeIds
+ * are passed directly), then one `Browse` request per batch, plus one
+ * `BrowseNext` round trip per continuation the Server imposes. The requests are
+ * batched precisely so a large category does **not** become one round trip per
+ * alias: 1000 aliases resolve in two or three round trips, not 1000.
+ *
+ * The result is keyed by the **very elements passed in** — look entries up with
+ * the objects from the input array, not with reconstructed equals. An input the
+ * Server could not resolve (the alias was deleted since the find, a NodeId that
+ * no longer browses) is absent from the map rather than present with a guess.
+ *
+ * @param session any `IBasicSessionAsync2` — a remote `ClientSession` or an
+ *   in-process `PseudoSession`, as everywhere in this package
+ * @param aliases either the entries of a `findAliasVerbose` call, or the
+ *   NodeIds of `AliasNameType` instance Nodes when the caller already knows
+ *   them (from browsing a category, or from its own bookkeeping)
+ */
+export async function readAliasReferenceTypes(
+    session: IBasicSessionAsync2,
+    aliases: NodeId[],
+    options?: ReadAliasReferenceTypesOptions
+): Promise<Map<NodeId, AliasReferenceTypeEntry[]>>;
+export async function readAliasReferenceTypes(
+    session: IBasicSessionAsync2,
+    aliases: ClientAliasVerboseEntry[],
+    options?: ReadAliasReferenceTypesOptions
+): Promise<Map<ClientAliasVerboseEntry, AliasReferenceTypeEntry[]>>;
+export async function readAliasReferenceTypes(
+    session: IBasicSessionAsync2,
+    aliases: NodeId[] | ClientAliasVerboseEntry[],
+    options?: ReadAliasReferenceTypesOptions
+): Promise<Map<NodeId | ClientAliasVerboseEntry, AliasReferenceTypeEntry[]>> {
+    const maxNodesPerCall = Math.max(1, options?.maxNodesPerCall ?? DEFAULT_MAX_NODES_PER_CALL);
+    const result = new Map<NodeId | ClientAliasVerboseEntry, AliasReferenceTypeEntry[]>();
+    if (aliases.length === 0) {
+        return result;
+    }
+
+    const aliasNodeIds: (NodeId | null)[] =
+        aliases[0] instanceof NodeIdClass
+            ? (aliases as NodeId[])
+            : await resolveAliasNodeIds(session, aliases as ClientAliasVerboseEntry[], maxNodesPerCall);
+
+    const targets = await browseAliasTargets(session, aliasNodeIds, maxNodesPerCall);
+    aliases.forEach((key: NodeId | ClientAliasVerboseEntry, index: number) => {
+        const entries = targets[index];
+        if (entries) {
+            result.set(key, entries);
+        }
+    });
+    return result;
+}
+
+/**
+ * Locate the `AliasNameType` instance Node behind each verbose entry.
+ *
+ * `FindAliasVerbose` names the category that held the alias
+ * (`aliasNameCategoryId`, clause 7.3) but not the alias Node itself, so the
+ * Node is found by translating one browse path below the category. The
+ * `RelativePath` is built element by element rather than parsed from a string,
+ * so an alias name containing `/`, `&` or the other OPC 10000-4 Annex A
+ * reserved characters needs no escaping. The QualifiedName match is exact —
+ * the entry's `namespaceIndex` is the one the Server reported, so this is the
+ * one place the namespace of an AliasName is **not** ignored.
+ *
+ * Unresolvable entries yield `null`, keeping positions aligned with the input.
+ */
+async function resolveAliasNodeIds(
+    session: IBasicSessionAsync2,
+    entries: ClientAliasVerboseEntry[],
+    maxNodesPerCall: number
+): Promise<(NodeId | null)[]> {
+    const aliasNodeIds: (NodeId | null)[] = new Array(entries.length).fill(null);
+    for (let offset = 0; offset < entries.length; offset += maxNodesPerCall) {
+        const chunk = entries.slice(offset, offset + maxNodesPerCall);
+        const results = await session.translateBrowsePath(
+            chunk.map(
+                (entry) =>
+                    new BrowsePath({
+                        startingNode: entry.aliasNameCategoryId,
+                        relativePath: {
+                            elements: [
+                                {
+                                    referenceTypeId: HIERARCHICAL_REFERENCES,
+                                    isInverse: false,
+                                    includeSubtypes: true,
+                                    targetName: { namespaceIndex: entry.namespaceIndex, name: entry.aliasName }
+                                }
+                            ]
+                        }
+                    })
+            )
+        );
+        results.forEach((browsePathResult, index) => {
+            if (browsePathResult.statusCode.isGood() && browsePathResult.targets?.length) {
+                // the targetId of a local Node is an ExpandedNodeId with
+                // serverIndex 0, usable as a NodeId as-is
+                aliasNodeIds[offset + index] = browsePathResult.targets[0].targetId;
+            }
+        });
+    }
+    return aliasNodeIds;
+}
+
+/**
+ * Browse the forward `AliasFor` References (subtypes included) of many alias
+ * Nodes in as few requests as possible, following every continuation point.
+ *
+ * Positions align with the input; `null` marks a Node that could not be
+ * resolved upstream or whose Browse did not complete — for the fidelity use
+ * case, an absent answer beats a truncated one presented as complete.
+ */
+async function browseAliasTargets(
+    session: IBasicSessionAsync2,
+    aliasNodeIds: (NodeId | null)[],
+    maxNodesPerCall: number
+): Promise<(AliasReferenceTypeEntry[] | null)[]> {
+    const targets: (AliasReferenceTypeEntry[] | null)[] = new Array(aliasNodeIds.length).fill(null);
+
+    const toBrowse: { index: number; nodeId: NodeId }[] = [];
+    aliasNodeIds.forEach((nodeId, index) => {
+        if (nodeId) {
+            toBrowse.push({ index, nodeId });
+        }
+    });
+
+    const toEntry = (reference: ReferenceDescription): AliasReferenceTypeEntry => ({
+        targetNodeId: reference.nodeId,
+        referenceTypeId: reference.referenceTypeId
+    });
+
+    for (let offset = 0; offset < toBrowse.length; offset += maxNodesPerCall) {
+        const chunk = toBrowse.slice(offset, offset + maxNodesPerCall);
+        const browseResults = await session.browse(
+            chunk.map(({ nodeId }) => ({
+                nodeId,
+                browseDirection: BrowseDirection.Forward,
+                referenceTypeId: ALIAS_FOR,
+                includeSubtypes: true,
+                nodeClassMask: 0,
+                resultMask: REFERENCE_TYPE_RESULT_MASK
+            }))
+        );
+
+        // continuations, batched too: one BrowseNext round trip serves every
+        // Node of the chunk that was truncated, however many there are
+        let pending: { index: number; continuationPoint: Buffer }[] = [];
+        browseResults.forEach((browseResult, chunkIndex) => {
+            const { index } = chunk[chunkIndex];
+            if (!browseResult.statusCode.isGood()) {
+                return;
+            }
+            targets[index] = (browseResult.references ?? []).map(toEntry);
+            if (browseResult.continuationPoint?.length) {
+                pending.push({ index, continuationPoint: browseResult.continuationPoint });
+            }
+        });
+
+        while (pending.length > 0) {
+            const nextResults = await session.browseNext(
+                pending.map(({ continuationPoint }) => continuationPoint),
+                false
+            );
+            const stillPending: typeof pending = [];
+            nextResults.forEach((browseResult, pendingIndex) => {
+                const { index } = pending[pendingIndex];
+                if (!browseResult.statusCode.isGood()) {
+                    // incomplete: withdraw the partial answer rather than let it
+                    // pass for the whole truth
+                    targets[index] = null;
+                    return;
+                }
+                targets[index]?.push(...(browseResult.references ?? []).map(toEntry));
+                if (browseResult.continuationPoint?.length) {
+                    stillPending.push({ index, continuationPoint: browseResult.continuationPoint });
+                }
+            });
+            pending = stillPending;
+        }
+    }
+    return targets;
+}