node-opcua-alias-name-server 2.176.0

package/dist/add_alias.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Creating and removing `AliasNameType` instances from code, for Servers whose
+ * address space is built programmatically rather than loaded from a NodeSet2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AliasNameError = void 0;
+exports.addAlias = addAlias;
+exports.removeAlias = removeAlias;
+exports.findAlias = findAlias;
+const node_opcua_data_model_1 = require("node-opcua-data-model");
+const node_opcua_nodeid_1 = require("node-opcua-nodeid");
+const alias_hierarchy_js_1 = require("./alias_hierarchy.js");
+const alias_index_js_1 = require("./alias_index.js");
+const bind_alias_category_js_1 = require("./bind_alias_category.js");
+const well_known_js_1 = require("./well_known.js");
+/** Raised when an alias would break a rule of OPC 10000-17. */
+class AliasNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AliasNameError";
+    }
+}
+exports.AliasNameError = AliasNameError;
+/**
+ * Add an `AliasNameType` instance under `category`, naming `target`.
+ *
+ * Enforces clause 6.2:
+ *
+ * - the string part of the BrowseName equals the DisplayName, with an empty
+ *   locale and no other locale;
+ * - the Object has at least one `AliasFor` Reference;
+ * - the BrowseName is immutable once created. There is deliberately no rename:
+ *   "If an AliasName is to be changed, it shall be a deletion of the old
+ *   AliasName and the addition of the new AliasName", which yields a new NodeId
+ *   and is what lets an aggregating Server notice the change.
+ *
+ * and the category restrictions of clauses 9.3 and 9.4, where the target is
+ * local and therefore checkable.
+ *
+ * Adding the same (name, target) twice returns the existing node rather than
+ * creating a duplicate.
+ */
+function addAlias(addressSpace, category, aliasName, target, options) {
+    const categoryNode = coerceCategory(addressSpace, category);
+    const referenceTypeId = coerceReferenceType(addressSpace, options?.referenceType);
+    if (!aliasName) {
+        throw new AliasNameError("addAlias: the alias name must not be empty");
+    }
+    // A target on another Server is not in this address space, so it can be
+    // neither resolved nor checked against the category restrictions.
+    let targetNodeId;
+    if (options?.allowUnresolvedTarget) {
+        targetNodeId = target instanceof node_opcua_nodeid_1.NodeId ? target : target.nodeId;
+    }
+    else {
+        const targetNode = coerceTarget(addressSpace, target);
+        targetNodeId = targetNode.nodeId;
+        assertTargetAllowedInCategory(addressSpace, categoryNode, targetNode);
+    }
+    const existing = findAlias(addressSpace, categoryNode, aliasName);
+    if (existing) {
+        // clause 6.3.1: multiple <Alias> instances may point at the same Node,
+        // and the same name may name several Nodes; adding a target that is
+        // already there is a no-op rather than an error
+        const alreadyLinked = existing
+            .findReferencesEx(well_known_js_1.ALIAS_FOR, node_opcua_data_model_1.BrowseDirection.Forward)
+            .some((reference) => reference.nodeId.toString() === targetNodeId.toString());
+        if (!alreadyLinked) {
+            existing.addReference({ referenceType: referenceTypeId, nodeId: targetNodeId });
+            // clause 6.3.1: "the referenced Nodes of an AliasName in the
+            // AliasNameCategory changed"
+            notifyAliasChanged(addressSpace, categoryNode.nodeId);
+        }
+        return existing;
+    }
+    const aliasNameType = (0, alias_hierarchy_js_1.findAliasNameType)(addressSpace);
+    if (!aliasNameType) {
+        throw new AliasNameError("addAlias: AliasNameType (i=23455) is not in the address space");
+    }
+    const namespace = addressSpace.getNamespace(options?.namespaceIndex ?? addressSpace.getOwnNamespace().index);
+    const alias = aliasNameType.instantiate({
+        browseName: { name: aliasName, namespaceIndex: namespace.index },
+        // clause 6.2: the DisplayName is the string part of the BrowseName, with
+        // an empty locale and no other locale - hence a single LocalizedText
+        // carrying a null locale, not a list
+        displayName: { locale: null, text: aliasName },
+        organizedBy: categoryNode,
+        namespace
+    });
+    alias.addReference({ referenceType: referenceTypeId, nodeId: targetNodeId });
+    (0, alias_index_js_1.noteAliasAdded)(addressSpace, categoryNode, aliasName, alias.nodeId);
+    // clause 6.3.1: "an AliasName was added to [...] the AliasNameCategory"
+    notifyAliasChanged(addressSpace, categoryNode.nodeId);
+    return alias;
+}
+/**
+ * Remove one target from an alias, or the whole alias when no target is given.
+ *
+ * Removing the last target deletes the `AliasNameType` node: clause 7.2 says the
+ * ReferencedNodes array always has at least one entry, so an alias naming
+ * nothing cannot be represented.
+ *
+ * @returns true when something was removed.
+ */
+function removeAlias(addressSpace, category, aliasName, target) {
+    const categoryNode = coerceCategory(addressSpace, category);
+    const alias = findAlias(addressSpace, categoryNode, aliasName);
+    if (!alias) {
+        return false;
+    }
+    if (!target) {
+        addressSpace.deleteNode(alias.nodeId);
+        (0, alias_index_js_1.noteAliasRemoved)(addressSpace, categoryNode, aliasName);
+        notifyAliasChanged(addressSpace, categoryNode.nodeId);
+        return true;
+    }
+    const targetNodeId = target instanceof node_opcua_nodeid_1.NodeId ? target : target.nodeId;
+    const references = alias.findReferencesEx(well_known_js_1.ALIAS_FOR, node_opcua_data_model_1.BrowseDirection.Forward);
+    const match = references.find((reference) => reference.nodeId.toString() === targetNodeId.toString());
+    if (!match) {
+        return false;
+    }
+    if (references.length === 1) {
+        // the last target: the alias itself goes (clause 7.2)
+        addressSpace.deleteNode(alias.nodeId);
+        (0, alias_index_js_1.noteAliasRemoved)(addressSpace, categoryNode, aliasName);
+        notifyAliasChanged(addressSpace, categoryNode.nodeId);
+        return true;
+    }
+    alias.removeReference({ referenceType: match.referenceType, nodeId: targetNodeId });
+    notifyAliasChanged(addressSpace, categoryNode.nodeId);
+    return true;
+}
+/**
+ * The `AliasNameType` instance with this name Organized by `category`, if any.
+ *
+ * Compares the string part only, ignoring the namespace, as clause 6.2 requires.
+ * Backed by a per-category index — see {@link lookupAlias} for why a plain scan
+ * was not good enough.
+ */
+function findAlias(addressSpace, category, aliasName) {
+    return (0, alias_index_js_1.lookupAlias)(addressSpace, category, aliasName);
+}
+/**
+ * Enforce the target restrictions of clauses 9.3 and 9.4.
+ *
+ * `TagVariables` restricts targets to Variables; `Topics` restricts them to
+ * `PublishedDataSetType` instances or subtypes. Both are checked only where the
+ * target is local — a Node on another Server cannot be inspected, which is the
+ * same reason clause 6.3.4 has `Uncertain_ReferenceOutOfServer`.
+ *
+ * The restriction applies to the whole subtree: an alias nested three levels
+ * below `TagVariables` is still "in the TagVariables hierarchy" (clause 9.3).
+ */
+function assertTargetAllowedInCategory(addressSpace, category, target) {
+    if (isWithin(addressSpace, category, well_known_js_1.WellKnownCategories.TagVariables)) {
+        if (target.nodeClass !== node_opcua_data_model_1.NodeClass.Variable) {
+            throw new AliasNameError(`addAlias: TagVariables restricts targets to Variables (OPC 10000-17 clause 9.3); ` +
+                `${target.browseName.toString()} is a ${node_opcua_data_model_1.NodeClass[target.nodeClass]}`);
+        }
+    }
+    if (isWithin(addressSpace, category, well_known_js_1.WellKnownCategories.Topics)) {
+        const publishedDataSetType = addressSpace.findObjectType(well_known_js_1.PUBLISHED_DATA_SET_TYPE);
+        const typeDefinition = target.nodeClass === node_opcua_data_model_1.NodeClass.Object ? target.typeDefinitionObj : null;
+        const ok = publishedDataSetType &&
+            typeDefinition &&
+            (typeDefinition.nodeId.value === publishedDataSetType.nodeId.value || typeDefinition.isSubtypeOf(publishedDataSetType));
+        if (!ok) {
+            throw new AliasNameError(`addAlias: Topics restricts targets to PublishedDataSetType or a subtype ` +
+                `(OPC 10000-17 clause 9.4); ${target.browseName.toString()} is not one`);
+        }
+    }
+}
+/** True when `category` is `ancestorNodeId` or nested anywhere below it. */
+function isWithin(addressSpace, category, ancestorNodeId) {
+    const ancestor = addressSpace.findNode(ancestorNodeId);
+    if (!ancestor) {
+        return false;
+    }
+    const seen = new Set();
+    const walkUp = (node) => {
+        const key = node.nodeId.toString();
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        if (key === ancestor.nodeId.toString()) {
+            return true;
+        }
+        for (const parent of node.findReferencesExAsObject("HierarchicalReferences", node_opcua_data_model_1.BrowseDirection.Inverse)) {
+            if (walkUp(parent)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    return walkUp(category);
+}
+/** Accept either a category node or its NodeId. */
+function coerceCategory(addressSpace, category) {
+    if (!(category instanceof node_opcua_nodeid_1.NodeId)) {
+        return category;
+    }
+    const node = addressSpace.findNode(category);
+    if (!node || node.nodeClass !== node_opcua_data_model_1.NodeClass.Object) {
+        throw new AliasNameError(`addAlias: ${category.toString()} is not an Object in this address space`);
+    }
+    const typeDefinition = node.typeDefinitionObj;
+    const categoryType = addressSpace.findObjectType(well_known_js_1.ALIAS_NAME_CATEGORY_TYPE);
+    if (categoryType &&
+        typeDefinition &&
+        typeDefinition.nodeId.value !== categoryType.nodeId.value &&
+        !typeDefinition.isSubtypeOf(categoryType)) {
+        throw new AliasNameError(`addAlias: ${category.toString()} is not an AliasNameCategoryType instance`);
+    }
+    return node;
+}
+/** Accept either a target node or its NodeId. */
+function coerceTarget(addressSpace, target) {
+    if (!(target instanceof node_opcua_nodeid_1.NodeId)) {
+        return target;
+    }
+    const node = addressSpace.findNode(target);
+    if (!node) {
+        throw new AliasNameError(`addAlias: target ${target.toString()} does not exist in this address space`);
+    }
+    return node;
+}
+/** Resolve the ReferenceType, defaulting to `AliasFor` (clause 8.2). */
+function coerceReferenceType(addressSpace, referenceType) {
+    if (!referenceType) {
+        return well_known_js_1.ALIAS_FOR;
+    }
+    const resolved = typeof referenceType === "string" ? addressSpace.findReferenceType(referenceType)?.nodeId : referenceType;
+    if (!resolved) {
+        throw new AliasNameError(`addAlias: unknown ReferenceType ${String(referenceType)}`);
+    }
+    const aliasFor = addressSpace.findReferenceType(well_known_js_1.ALIAS_FOR);
+    const candidate = addressSpace.findReferenceType(resolved);
+    if (aliasFor && candidate && candidate.nodeId.value !== aliasFor.nodeId.value && !candidate.isSubtypeOf(aliasFor)) {
+        throw new AliasNameError(`addAlias: ${candidate.browseName.toString()} is not AliasFor or a subtype of it (OPC 10000-17 clause 8.2)`);
+    }
+    return resolved;
+}
+/**
+ * Tell the installed `LastChange` tracker that a category changed
+ * (clause 6.3.1).
+ *
+ * Routed through whatever installation recorded on the address space rather
+ * than through a parameter, so `addAlias` keeps its simple signature and a
+ * Server that has not installed AliasNames is unaffected. Fire and forget: the
+ * Property is written synchronously, only the persistence write is async, and
+ * failing to persist must not fail the caller's add.
+ */
+function notifyAliasChanged(addressSpace, categoryNodeId) {
+    const installed = (0, bind_alias_category_js_1.getInstalledAliasNames)(addressSpace);
+    void installed?.lastChange?.touch(categoryNodeId);
+}
+//# sourceMappingURL=add_alias.js.map

package/dist/add_alias.js.map

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

package/dist/address_space_alias_store.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @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 } from "node-opcua-address-space-base";
+import { type AliasEntry, type AliasQuery, type IAliasStore, type LikeOptions } from "node-opcua-alias-name-common";
+import { type NodeId } from "node-opcua-nodeid";
+import { type StatusCode } from "node-opcua-status-code";
+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;
+}
+export declare class AddressSpaceAliasStore implements IAliasStore {
+    private readonly addressSpace;
+    private readonly likeOptions?;
+    /** Per-category `LastChange`, as a VersionTime (clause 6.3.1). */
+    private readonly lastChangeByCategory;
+    private readonly allowRemoteTargets;
+    constructor(addressSpace: IAddressSpace, options?: AddressSpaceAliasStoreOptions);
+    /**
+     * 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.
+     */
+    find(query: AliasQuery): Promise<AliasEntry[]>;
+    /** `LastChange` for a category, rolled up from its descendants (clause 6.3.1). */
+    lastChange(categoryNodeId: NodeId): number;
+    /**
+     * 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.
+     */
+    touch(categoryNodeId: NodeId, versionTime?: number): number;
+    /** Restore persisted `LastChange` values (clause 6.3.1: "shall be persisted"). */
+    restoreLastChange(values: Iterable<readonly [string, number]>): void;
+    /** Snapshot the per-category `LastChange` values for persistence. */
+    snapshotLastChange(): Array<[string, number]>;
+    /**
+     * 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.
+     */
+    add(categoryNodeId: NodeId, entries: AliasEntry[]): StatusCode[];
+    /**
+     * 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.
+     */
+    delete(categoryNodeId: NodeId, entries: Pick<AliasEntry, "aliasName" | "referencedNodes">[]): StatusCode[];
+    /** Add an alias whose target is on this Server. */
+    private addLocal;
+    /**
+     * 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;
+    /** True when none of the alias's targets are on this Server. */
+    private isForeign;
+    /** The URI of a namespace index, or undefined for namespace 0. */
+    private namespaceUriOf;
+    /**
+     * Resolve the `ReferenceTypeFilter` argument.
+     *
+     * A null or absent NodeId means any ReferenceType (clause 6.3.2 Table 3).
+     */
+    private resolveReferenceTypeFilter;
+    /**
+     * 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;
+}