node-opcua-address-space 2.179.0 → 2.181.0

package/dist/api/loader/nodeset_image_store.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryNodesetImageStore = void 0;
+exports.nodesetImageKey = nodesetImageKey;
+exports.sharedMemoryNodesetImageStore = sharedMemoryNodesetImageStore;
+/**
+ * @module node-opcua-address-space
+ *
+ * Where precompiled images are kept between loads. The loader keys an image by the record
+ * schema and the SHA-256 of the source bytes: an edited file gets a fresh image, a schema bump
+ * invalidates every image, and nothing else does. The package version is deliberately not part
+ * of the key, so that an image built by one release stays valid for the next while the record
+ * shape holds.
+ */
+const nodeset_record_js_1 = require("./nodeset_record.js");
+/** the key of the image of a source whose bytes hash to `sourceDigest` */
+function nodesetImageKey(sourceDigest) {
+    return `${nodeset_record_js_1.NODESET_RECORD_SCHEMA}-${sourceDigest}`;
+}
+/**
+ * an in-memory store: for browsers, tests, and a process that loads the same files repeatedly.
+ * The size cap counts the compressed bytes, which is all the store retains per entry: the loader
+ * inflates an image for one load and lets the lines go afterwards
+ */
+class MemoryNodesetImageStore {
+    maxBytes;
+    images = new Map();
+    constructor(maxBytes = 64 * 1024 * 1024) {
+        this.maxBytes = maxBytes;
+    }
+    async get(key) {
+        const image = this.images.get(key);
+        if (image) {
+            // most recently used last: what eviction keeps
+            this.images.delete(key);
+            this.images.set(key, image);
+        }
+        return image;
+    }
+    async put(key, image) {
+        this.images.delete(key);
+        this.images.set(key, image);
+        let total = 0;
+        for (const stored of this.images.values()) {
+            total += stored.length;
+        }
+        for (const [oldest, stored] of this.images) {
+            if (total <= this.maxBytes || oldest === key) {
+                break;
+            }
+            this.images.delete(oldest);
+            total -= stored.length;
+        }
+    }
+    get size() {
+        return this.images.size;
+    }
+    keys() {
+        return [...this.images.keys()];
+    }
+}
+exports.MemoryNodesetImageStore = MemoryNodesetImageStore;
+let sharedStore;
+/**
+ * the store a plain `imageStore: true` selects where no file system store is available (the
+ * browser, `generateAddressSpaceRaw`): one memory store for the process
+ */
+function sharedMemoryNodesetImageStore() {
+    sharedStore = sharedStore || new MemoryNodesetImageStore();
+    return sharedStore;
+}
+//# sourceMappingURL=nodeset_image_store.js.map

package/dist/api/loader/nodeset_image_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeset_image_store.js","sourceRoot":"","sources":["../../../api/loader/nodeset_image_store.ts"],"names":[],"mappings":";;;AAmBA,0CAEC;AAqDD,sEAGC;AA7ED;;;;;;;;GAQG;AACH,2DAA4D;AAS5D,0EAA0E;AAC1E,SAAgB,eAAe,CAAC,YAAoB;IAChD,OAAO,GAAG,yCAAqB,IAAI,YAAY,EAAE,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAa,uBAAuB;IAGH;IAFZ,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAExD,YAA6B,WAAW,EAAE,GAAG,IAAI,GAAG,IAAI;QAA3B,aAAQ,GAAR,QAAQ,CAAmB;IAAG,CAAC;IAErD,KAAK,CAAC,GAAG,CAAC,GAAW;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,EAAE,CAAC;YACR,+CAA+C;YAC/C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAEM,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAiB;QAC3C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACxC,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACzC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBAC3C,MAAM;YACV,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC;QAC3B,CAAC;IACL,CAAC;IAED,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC5B,CAAC;IAEM,IAAI;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC;CACJ;AAtCD,0DAsCC;AAED,IAAI,WAAgD,CAAC;AAErD;;;GAGG;AACH,SAAgB,6BAA6B;IACzC,WAAW,GAAG,WAAW,IAAI,IAAI,uBAAuB,EAAE,CAAC;IAC3D,OAAO,WAAW,CAAC;AACvB,CAAC"}

package/dist/api/loader/nodeset_record.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * The loader's intermediate form. A NodeSet2 document, whatever it comes from (XML, an image),
+ * is a stream of records: one header, then one record per node. A producer makes records, a
+ * consumer applies them; the parse of the XML and the mutation of the address space are no
+ * longer one and the same pass.
+ *
+ * Ids are untranslated: a `NodeId` or `QualifiedName` in a record carries the namespace index
+ * of the **file's own namespace table** (0 = `http://opcfoundation.org/UA/`, then the
+ * `<NamespaceUris>` entries in order), never the target address space's. The consumer that
+ * applies the records owns the translation. Ids also sit inside values (NodeId and
+ * QualifiedName variants, the `dataType` of an `Argument`), hence objects rather than tuples in
+ * memory; the tuple form is the serialization of the precompiled image.
+ */
+import type { RequiredModel } from "node-opcua-address-space-base";
+import type { NodeClass, QualifiedName } from "node-opcua-data-model";
+import type { NodeId } from "node-opcua-nodeid";
+import type { VariantOptions } from "node-opcua-variant";
+import type { EnumFieldOptions, StructureFieldOptions } from "node-opcua-xml2json";
+/** bumped whenever the record shape changes; the precompiled image carries it */
+export declare const NODESET_RECORD_SCHEMA = 2;
+export interface NodesetModelRecord {
+    modelUri: string;
+    version: string;
+    publicationDate?: Date;
+    requiredModels: RequiredModel[];
+    symbolicName?: string;
+    accessRestrictions?: string;
+}
+/** the first record of a document: what the loader needs before any node */
+export interface NodesetHeaderRecord {
+    kind: "header";
+    namespaceUris: string[];
+    models: NodesetModelRecord[];
+    /** alias name to the id it stands for, file-local; no record refers to an alias by name */
+    aliases: Record<string, NodeId>;
+}
+export interface NodesetReferenceRecord {
+    isForward: boolean;
+    referenceType: NodeId;
+    nodeId: NodeId;
+    /**
+     * whether the target's own record, in the same document, declares the inverse of this
+     * reference. A NodeSet2 file declares most references from both ends, and a back reference is
+     * only needed where it does not; a producer that has seen the whole document (the image) sets
+     * this so the loader propagates the few that need it instead of checking every one. Left
+     * undefined by a streaming producer: the loader then checks at the end of the load.
+     */
+    inverseDeclared?: boolean;
+}
+export interface NodesetRolePermissionRecord {
+    roleId: NodeId;
+    permissions: number;
+}
+export type NodesetDefinitionField = Omit<StructureFieldOptions, "dataType"> & EnumFieldOptions & {
+    dataType?: NodeId | null;
+};
+export interface NodesetDataTypeDefinitionRecord {
+    name?: string;
+    isUnion?: boolean;
+    fields: NodesetDefinitionField[];
+}
+/**
+ * an extension object the reader could not decode on the spot: its XML body waits in the value
+ * until the data types are known, then a consumer decodes it
+ */
+export declare class XmlExtensionObjectFragment {
+    /** the "Default XML" encoding id of the type, file-local */
+    readonly typeId: NodeId;
+    readonly bodyXML: string;
+    constructor(
+    /** the "Default XML" encoding id of the type, file-local */
+    typeId: NodeId, bodyXML: string);
+}
+/** one node of the document; every attribute the XML reader reads, none applied */
+export interface NodesetNodeRecord {
+    kind: "node";
+    nodeClass: NodeClass;
+    nodeId: NodeId;
+    browseName: QualifiedName;
+    displayName?: string;
+    description?: string;
+    references: NodesetReferenceRecord[];
+    releaseStatus?: "Draft" | "Deprecated";
+    symbolicName?: string;
+    /** the access policy as declared, whatever the loader options; the consumer applies its options */
+    accessRestrictions?: string;
+    hasNoPermissions?: boolean;
+    rolePermissions?: NodesetRolePermissionRecord[];
+    isAbstract?: boolean;
+    eventNotifier?: number;
+    inverseName?: string;
+    symmetric?: boolean;
+    containsNoLoops?: boolean;
+    parentNodeId?: NodeId | null;
+    dataType?: NodeId | null;
+    valueRank?: number;
+    arrayDimensions?: number[] | null;
+    minimumSamplingInterval?: number;
+    historizing?: boolean;
+    accessLevel?: string;
+    userAccessLevel?: string;
+    /**
+     * the value as the reader produced it, ids file-local; an ExtensionObject value may hold
+     * {@link XmlExtensionObjectFragment} placeholders, scalar or as array elements
+     */
+    value?: VariantOptions;
+    methodDeclarationId?: NodeId | null;
+    definition?: NodesetDataTypeDefinitionRecord;
+}
+export type NodesetRecord = NodesetHeaderRecord | NodesetNodeRecord;
+/**
+ * the bytes of source a producer consumed to emit a record, stamped on the record under a
+ * symbol so that it is never serialized; a consumer sums them to pace its yields
+ */
+export declare const recordBytes: unique symbol;
+export type NodesetRecordWithBytes = NodesetRecord & {
+    [recordBytes]?: number;
+};
+export type NodesetRecordProducer = AsyncIterable<NodesetRecord>;
+export interface NodesetRecordConsumer {
+    /** one record, in document order, the header first */
+    apply(record: NodesetRecord): void;
+}

package/dist/api/loader/nodeset_record.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordBytes = exports.XmlExtensionObjectFragment = exports.NODESET_RECORD_SCHEMA = void 0;
+/** bumped whenever the record shape changes; the precompiled image carries it */
+exports.NODESET_RECORD_SCHEMA = 2;
+/**
+ * an extension object the reader could not decode on the spot: its XML body waits in the value
+ * until the data types are known, then a consumer decodes it
+ */
+class XmlExtensionObjectFragment {
+    typeId;
+    bodyXML;
+    constructor(
+    /** the "Default XML" encoding id of the type, file-local */
+    typeId, bodyXML) {
+        this.typeId = typeId;
+        this.bodyXML = bodyXML;
+    }
+}
+exports.XmlExtensionObjectFragment = XmlExtensionObjectFragment;
+/**
+ * the bytes of source a producer consumed to emit a record, stamped on the record under a
+ * symbol so that it is never serialized; a consumer sums them to pace its yields
+ */
+exports.recordBytes = Symbol("recordBytes");
+//# sourceMappingURL=nodeset_record.js.map

package/dist/api/loader/nodeset_record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeset_record.js","sourceRoot":"","sources":["../../../api/loader/nodeset_record.ts"],"names":[],"mappings":";;;AAqBA,iFAAiF;AACpE,QAAA,qBAAqB,GAAG,CAAC,CAAC;AA+CvC;;;GAGG;AACH,MAAa,0BAA0B;IAGf;IACA;IAHpB;IACI,4DAA4D;IAC5C,MAAc,EACd,OAAe;QADf,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAQ;IAChC,CAAC;CACP;AAND,gEAMC;AAiDD;;;GAGG;AACU,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC"}

package/dist/api/loader/nodeset_record_applier.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * The consumer that turns {@link NodesetRecord}s into nodes of an address space: it registers
+ * the namespaces the header declares, translates every id from the file's namespace table to
+ * the address space's, applies the loader options, creates the node and queues the post-load
+ * tasks (values, extension objects, data-type registration) that run once every document is in.
+ */
+import type { BaseNode, IAddressSpace, UAReference } from "node-opcua-address-space-base";
+import { NodeId } from "node-opcua-nodeid";
+import type { NodeSetLoaderOptions } from "../interfaces/nodeset_loader_options.js";
+import { type NodesetRecord, type NodesetRecordConsumer } from "./nodeset_record.js";
+export type Task = (addressSpace: IAddressSpace) => Promise<void>;
+/** the work deferred until every document is loaded, in the order it runs */
+export interface LoaderTaskQueues {
+    postTasks: Task[];
+    postTasks0_InitializeVariable: Task[];
+    postTasks0_DecodePojoString: Task[];
+    postTasks1_InitializeVariable: Task[];
+    postTasks2_AssignedExtensionObjectToDataValue: Task[];
+    pendingSimpleTypeToRegister: {
+        name: string;
+        dataTypeNodeId: NodeId;
+    }[];
+}
+export declare function makeLoaderTaskQueues(): LoaderTaskQueues;
+/** see NodesetRecordApplier.takePendingBackReferences */
+export interface PendingBackReferences {
+    /** nodes whose document said which of their references are one-sided: nothing else to propagate */
+    settled: Set<BaseNode>;
+    /** the one-sided references, with the node holding each */
+    references: Array<[BaseNode, UAReference]>;
+}
+export declare class NodesetRecordApplier implements NodesetRecordConsumer {
+    private readonly options;
+    private readonly queues;
+    /** the back references the load owes, and the nodes it owes nothing else for; see takePendingBackReferences */
+    private pending;
+    private readonly addressSpace;
+    private readonly applyRolePermissions;
+    private readonly applyAccessRestrictions;
+    private table;
+    private aliasMap;
+    private translatedStrings;
+    private translatedIds;
+    private headerSeen;
+    constructor(addressSpace: IAddressSpace, options: NodeSetLoaderOptions, queues: LoaderTaskQueues);
+    apply(record: NodesetRecord): void;
+    private applyHeader;
+    private addNamespace;
+    private translateNamespaceIndex;
+    /** a file-local id to the address space's, built once per distinct id */
+    private translate;
+    private translateOrNull;
+    private translateQualifiedName;
+    /**
+     * an id given as text, the way the XML body of a deferred extension object carries them:
+     * an alias, or `ns=<file index>;...`
+     */
+    private readonly translateString;
+    /**
+     * the ids a value may hold, by data type; everything else passes through. A record is not
+     * the applier's to change: another consumer may read it after this one, so what is
+     * translated is a copy
+     */
+    private translateValue;
+    private canIgnore;
+    private permissions;
+    private common;
+    /** the node's references as the node will hold them, one per reference of the record, in its order */
+    private references;
+    /**
+     * what the end of the load must do about the inverses of a node's references: a reference the
+     * document marks as not declared from the other end is kept for one propagation, and the node
+     * is settled; a node whose references carry no such information is left to the end-of-load
+     * sweep, which propagates it whole. `references` are those built by {@link references} from
+     * the same record, in the same order.
+     */
+    private settle;
+    /**
+     * what the end of the load must do about back references: the one-sided references of the
+     * settled nodes, to propagate one by one, and the settled nodes themselves, which the sweep
+     * over every node skips. Taken once by the loader's terminate step and dropped after it: the
+     * set lives for the load, not on the nodes
+     */
+    takePendingBackReferences(): PendingBackReferences;
+    private createNode;
+    private applyNode;
+    private applyDataType;
+    /**
+     * the value of a record, translated, with the extension objects still waiting as XML replaced
+     * by null and their decode queued; the deferred getter yields them once decoded
+     */
+    private prepareValue;
+    private assignExtensionObjectLater;
+    private variableCommon;
+    private applyVariable;
+    /** a data type node whose basic type resolves: what an initial value needs to be checked against */
+    private isDataTypeReady;
+    /**
+     * what the "initializing simple variables" post task does, done at creation; a value the
+     * variable refuses is logged and skipped, as the post task would
+     */
+    private setInitialValueNow;
+    private applyVariableType;
+}