node-opcua-address-space 2.180.0 → 2.181.0

package/impl/child_accessors.ts

@@ -0,0 +1,239 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * Hierarchical children exposed as JavaScript properties: `server.serverStatus.currentTime`,
+ * `alarm.enabledState.id`, `dataType.enumStrings`.
+ *
+ * Every child used to be installed as an own accessor on its parent, one `Object.defineProperty`
+ * per child, in a sweep at the end of every nodeset load and again each time a node was created.
+ * That sweep was 12% of a load, gave every node its own hidden class, and let a child shadow an
+ * attribute or a method of the same name (`eventNotifier`, `namespaceUri`).
+ *
+ * A name seen while a nodeset loads now gets ONE getter, on `BaseNodeImpl.prototype`, shared by
+ * every node; the getter resolves the child at access time through the node's child index. Names
+ * first seen at runtime never touch the prototype: adding a property to a prototype invalidates
+ * the V8 inline caches of everything inheriting from it, which must not happen inside a loop that
+ * creates a hundred thousand uniquely named variables. Those names keep the per-parent own
+ * accessor installed by `install_extra_properties`, as before.
+ *
+ * This module knows nothing about nodes: the prototype to extend and the resolver are handed in,
+ * so it takes part in no import cycle.
+ */
+import { lowerFirstLetter } from "node-opcua-utils";
+
+/**
+ * names that would break the node object itself if a child could claim them, on top of
+ * whatever the prototype chain already defines (attributes, methods, EventEmitter members)
+ */
+const forbiddenNames = new Set(["then", "catch", "finally", "toJSON", "length", "prototype", "constructor", "__proto__"]);
+
+/**
+ * accessor name -> the browse names mapping to it that cannot be derived back from it.
+ * `enabledState` needs no entry (`EnabledState` is the accessor name capitalised, and a name that
+ * is already lower case maps to itself); `euRange` does (`EURange`), and so does a name with an
+ * underscore. Only the shared getters read this map, so it holds the names a nodeset declared
+ * and the runtime names those getters resolve: a model with a hundred thousand runtime names
+ * costs nothing here.
+ */
+const irregularBrowseNames = new Map<string, string[]>();
+
+function upperFirstLetter(name: string): string {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/** accessor names carried by a shared getter on the prototype */
+const sharedAccessors = new Set<string>();
+
+/**
+ * accessor names waiting for their shared getter. Defining a property on a prototype invalidates
+ * the inline caches of every object inheriting from it, so the getters of a nodeset are not
+ * defined one at a time while its nodes are being created but in one batch once the load is done.
+ */
+const pendingSharedAccessors = new Set<string>();
+
+export type ChildAccessorResolver<Node> = (node: Node, accessorName: string) => unknown;
+
+/**
+ * the property name a child is exposed as: `EnabledState` -> `enabledState`, `EURange` -> `euRange`.
+ * The mapping is not invertible, hence the registry kept by {@link registerChildName}.
+ */
+export function childAccessorName(browseName: string): string {
+    // lowerFirstLetter splits on underscores and lower-cases every part, several passes and a
+    // join for a name it then returns unchanged; a name without an upper-case letter is its own
+    // accessor name, and that is what a model built at runtime mostly carries (tag_0001)
+    for (let i = 0; i < browseName.length; i++) {
+        const code = browseName.charCodeAt(i);
+        if (code >= 65 && code <= 90) {
+            return lowerFirstLetter(browseName);
+        }
+    }
+    return browseName;
+}
+
+export function hasSharedChildAccessor(accessorName: string): boolean {
+    return sharedAccessors.has(accessorName);
+}
+
+/** the names no child may claim on any node, see {@link isReservedChildAccessorName} */
+export function reservedChildAccessorNames(): readonly string[] {
+    return [...forbiddenNames];
+}
+
+/**
+ * true for the names no child may claim on any node, shared getter or own accessor alike:
+ * `then` would turn every node into a thenable, `__proto__` would corrupt it
+ */
+export function isReservedChildAccessorName(accessorName: string): boolean {
+    return !accessorName || accessorName.startsWith("$") || forbiddenNames.has(accessorName);
+}
+
+/**
+ * Record that a node named `browseName` exists, so that `resolveChildInIndex` can map the accessor
+ * name back to it; with `requestShared`, also queue a shared getter for it, to be defined by the
+ * next {@link defineSharedChildAccessors}.
+ */
+/**
+ * browse name to accessor name, computed once for the names a nodeset declares: a nodeset repeats
+ * a few hundred names over thousands of nodes. A name first seen at runtime is computed and not
+ * remembered: it is seen once, and a server naming its nodes per job must leave no trace here.
+ */
+const accessorNameOf = new Map<string, string>();
+
+export function registerChildName(browseName: string | null | undefined, requestShared: boolean): string | undefined {
+    if (!browseName) {
+        return undefined;
+    }
+    let accessorName = accessorNameOf.get(browseName);
+    if (accessorName !== undefined) {
+        return accessorName;
+    }
+    accessorName = childAccessorName(browseName);
+    // a shared getter resolves the child by browse name through the index: it must know the
+    // irregular spellings of the names it serves, whether a nodeset or the runtime brought them.
+    // A runtime name with no shared getter is served by an own accessor that holds its child
+    const shared = requestShared || sharedAccessors.has(accessorName);
+    if (shared && browseName !== accessorName && browseName !== upperFirstLetter(accessorName)) {
+        const known = irregularBrowseNames.get(accessorName);
+        if (!known) {
+            irregularBrowseNames.set(accessorName, [browseName]);
+        } else if (!known.includes(browseName)) {
+            known.push(browseName);
+        }
+    }
+    if (requestShared) {
+        accessorNameOf.set(browseName, accessorName);
+        if (!sharedAccessors.has(accessorName)) {
+            pendingSharedAccessors.add(accessorName);
+        }
+    }
+    return accessorName;
+}
+
+/** how much the registries hold, for the tests that check they stay bounded by the nodeset vocabulary */
+export function childAccessorRegistrySizes(): { accessorNames: number; irregularNames: number; shared: number; pending: number } {
+    let irregularNames = 0;
+    for (const names of irregularBrowseNames.values()) {
+        irregularNames += names.length;
+    }
+    return {
+        accessorNames: accessorNameOf.size,
+        irregularNames,
+        shared: sharedAccessors.size,
+        pending: pendingSharedAccessors.size
+    };
+}
+
+/**
+ * Define the shared getter of every accessor name queued by {@link registerChildName}.
+ *
+ * @returns the number of getters defined
+ */
+export function defineSharedChildAccessors<Node extends object>(prototype: Node, resolve: ChildAccessorResolver<Node>): number {
+    let defined = 0;
+    for (const accessorName of pendingSharedAccessors) {
+        if (defineSharedChildAccessor(prototype, resolve, accessorName)) {
+            defined += 1;
+        }
+    }
+    pendingSharedAccessors.clear();
+    return defined;
+}
+
+function defineSharedChildAccessor<Node extends object>(
+    prototype: Node,
+    resolve: ChildAccessorResolver<Node>,
+    accessorName: string
+): boolean {
+    if (sharedAccessors.has(accessorName)) {
+        return false;
+    }
+    // a child never shadows what the node already has: attributes, methods, fields, and
+    // the names that would turn a node into a thenable or corrupt its prototype chain
+    if (isReservedChildAccessorName(accessorName) || accessorName in prototype) {
+        return false;
+    }
+    Object.defineProperty(prototype, accessorName, {
+        configurable: true,
+        enumerable: false,
+        get(this: Node) {
+            return resolve(this, accessorName);
+        },
+        // assigning to the name keeps its old meaning, an own property of that node, rather than
+        // being swallowed by the prototype accessor (a stub built with Object.create relies on it)
+        set(this: Node, value: unknown) {
+            Object.defineProperty(this, accessorName, { value, writable: true, configurable: true, enumerable: true });
+        }
+    });
+    sharedAccessors.add(accessorName);
+    return true;
+}
+
+export interface IndexedChild {
+    node?: unknown;
+}
+
+/**
+ * The child that `parent.<accessorName>` designates, given the parent's child index
+ * (browse name -> reference, or references when several children share a browse name) and
+ * which references count: the index holds every hierarchical reference, while a dotted child
+ * is one reached through a structural reference (a component, a property, a subtype, an
+ * organized node), not through an event reference such as HasNotifier.
+ *
+ * The capitalised name is tried first, then the accessor name itself, then the irregular
+ * browse names on record; among children sharing a browse name the first one indexed wins,
+ * which is what the own-accessor installation did too.
+ */
+export function resolveChildInIndex<Child extends IndexedChild>(
+    index: Map<string, Child | Child[]>,
+    accessorName: string,
+    accept: (reference: Child) => boolean
+): Child["node"] | undefined {
+    const lookup = (browseName: string): Child["node"] | undefined => {
+        const entry = index.get(browseName);
+        if (!entry) {
+            return undefined;
+        }
+        const references = Array.isArray(entry) ? entry : [entry];
+        for (const reference of references) {
+            if (reference.node && accept(reference)) {
+                return reference.node;
+            }
+        }
+        return undefined;
+    };
+    const capitalised = upperFirstLetter(accessorName);
+    const found = lookup(capitalised) ?? (capitalised === accessorName ? undefined : lookup(accessorName));
+    if (found) {
+        return found;
+    }
+    const irregular = irregularBrowseNames.get(accessorName);
+    if (irregular) {
+        for (const browseName of irregular) {
+            const node = lookup(browseName);
+            if (node) {
+                return node;
+            }
+        }
+    }
+    return undefined;
+}

package/impl/data_access/adjust_datavalue_status_code.ts

@@ -0,0 +1,36 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+
+import type { UAVariable } from "node-opcua-address-space-base";
+import { NodeClass } from "node-opcua-data-model";
+import type { DataValue } from "node-opcua-data-value";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import type { Range } from "node-opcua-types";
+import type { Variant } from "node-opcua-variant";
+import type { UAVariableImpl } from "../ua_variable_impl.js";
+
+function validate_value_range(range: Range, variant: Variant) {
+    if (variant.value < range.low || variant.value > range.high) {
+        return false;
+    }
+    return true;
+}
+
+export function adjustDataValueStatusCode(
+    variable: UAVariableImpl,
+    dataValue: DataValue,
+    acceptValueOutOfRange: boolean
+): StatusCode {
+    const instrumentRange = variable.getChildByName("InstrumentRange") as UAVariable | null;
+    if (instrumentRange && instrumentRange.nodeClass === NodeClass.Variable) {
+        if (!validate_value_range(instrumentRange.readValue().value.value as Range, dataValue.value)) {
+            if (!acceptValueOutOfRange) {
+                return StatusCodes.BadOutOfRange;
+            } else {
+                dataValue.statusCode = StatusCodes.BadOutOfRange;
+            }
+        }
+    }
+    return StatusCodes.Good;
+}

package/impl/data_access/ua_multistate_discrete_impl.ts

@@ -0,0 +1,198 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+
+import type {
+    BindVariableOptions,
+    CloneExtraInfo,
+    CloneFilter,
+    CloneOptions,
+    INamespace,
+    UAProperty,
+    UAVariable
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { VariableTypeIds } from "node-opcua-constants";
+import { coerceLocalizedText, type LocalizedText } from "node-opcua-data-model";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { DataType, Variant, VariantArrayType } from "node-opcua-variant";
+import type { AddMultiStateDiscreteOptions } from "../../api/address_space_ts.js";
+import type { ISetStateOptions } from "../../api/interfaces/i_set_state_options.js";
+import { registerNodePromoter } from "../../api/loader/register_node_promoter.js";
+import { UAVariableImpl, UAVariableImplT } from "../ua_variable_impl.js";
+import { add_dataItem_stuff } from "./add_dataItem_stuff.js";
+
+export { UAMultiStateDiscrete } from "node-opcua-nodeset-ua";
+
+// One declaration, in the api tree, rather than a lesser copy here: this file used to
+// declare its own UAMultiStateDiscreteEx without the UAVariableT half, so the two drifted
+// on what readValue returns.
+import type { UAMultiStateDiscreteEx } from "../../api/interfaces/data_access/ua_multistate_discrete_ex.js";
+
+export type { UAMultiStateDiscreteEx };
+
+/**
+ * @class UAMultiStateDiscrete
+ * @internal
+ */
+export class UAMultiStateDiscreteImplBase<T, DT extends DataType>
+    extends UAVariableImplT<T, DT>
+    implements UAMultiStateDiscreteEx<T, DT>
+{
+    /**
+     * The EnumStrings property, installed as a child node by the address space rather than
+     * assigned by this constructor - hence `declare`, which emits nothing.
+     */
+    public declare readonly enumStrings: UAProperty<LocalizedText[], DataType.LocalizedText>;
+
+    public getValue(): number {
+        // MultiStateDiscrete fixes its value to UInt32 (OPC 10000-8), whatever T says
+        return this.readValue().value.value as number;
+    }
+
+    public getValueAsString(): string {
+        const index = this.getValue();
+        const arr = this.enumStrings.readValue().value.value;
+        assert(Array.isArray(arr));
+        return arr[index].text ? arr[index].text?.toString() : "????";
+    }
+
+    public getIndex(value: string): number {
+        const arr = this.enumStrings.readValue().value.value;
+        assert(Array.isArray(arr));
+        const index = arr.findIndex((a: LocalizedText) => a.text === value);
+        return index;
+    }
+
+    public setValue(value: string | number, options?: ISetStateOptions): void {
+        if (typeof value === "string") {
+            const index = this.getIndex(value);
+            if (index < 0) {
+                throw new Error(`UAMultiStateDiscrete#setValue invalid multi state value provided : ${value}`);
+            }
+            this.setValue(index, options);
+            return;
+        }
+        const arrayEnumStrings = this.enumStrings.readValue().value.value;
+        if (value >= arrayEnumStrings.length) {
+            throw new Error(`UAMultiStateDiscrete#setValue BadOutOfRange ${value}`);
+        }
+        assert(Number.isFinite(value));
+        this.setValueFromSource(new Variant({ dataType: DataType.UInt32, value }));
+    }
+
+    public checkVariantCompatibility(value: Variant): StatusCode {
+        if (!this._validate_DataType(value.dataType)) {
+            return StatusCodes.BadTypeMismatch;
+        }
+        if (this.enumStrings) {
+            const arrayEnumStrings = this.enumStrings.readValue().value.value;
+            // MultiStateDiscreteType
+            assert(value.dataType === DataType.UInt32);
+            if (value.value >= arrayEnumStrings.length) {
+                return StatusCodes.BadOutOfRange;
+            }
+        }
+        return StatusCodes.Good;
+    }
+
+    public _post_initialize(): void {
+        /* empty */
+    }
+
+    public clone(
+        options1: CloneOptions,
+        optionalFilter?: CloneFilter,
+        extraInfo?: CloneExtraInfo
+    ): UAMultiStateDiscreteImpl<T, DT> {
+        const variable1 = UAVariableImpl.prototype.clone.call(this, options1, optionalFilter, extraInfo);
+        return promoteToMultiStateDiscrete(variable1);
+    }
+}
+// The class states that it implements the published interface, so the name is just the
+// class. It used to be an intersection with a cast behind it, because the class could not
+// satisfy the interface while its child nodes were reachable only through a cast.
+/** @internal */
+export type UAMultiStateDiscreteImpl<T, DT extends DataType> = UAMultiStateDiscreteImplBase<T, DT>;
+/** @internal */
+export const UAMultiStateDiscreteImpl = UAMultiStateDiscreteImplBase;
+
+export function promoteToMultiStateDiscrete<T, DT extends DataType>(node: UAVariable): UAMultiStateDiscreteImpl<T, DT> {
+    if (node instanceof UAMultiStateDiscreteImpl) {
+        return node; // already promoted
+    }
+    Object.setPrototypeOf(node, UAMultiStateDiscreteImpl.prototype);
+    assert(node instanceof UAMultiStateDiscreteImpl, "should now  be a State Machine");
+    const _node = node as UAMultiStateDiscreteImpl<T, DT>;
+
+    _node._post_initialize();
+
+    assert(_node.enumStrings.browseName.toString() === "EnumStrings");
+    const handler = _node.handle_semantic_changed.bind(_node);
+    _node.enumStrings.on("value_changed", handler);
+    _node.install_extra_properties();
+    return node as UAMultiStateDiscreteImpl<T, DT>;
+}
+registerNodePromoter(VariableTypeIds.MultiStateDiscreteType, promoteToMultiStateDiscrete);
+
+/** @internal */
+export function _addMultiStateDiscrete<T, DT extends DataType>(
+    namespace: INamespace,
+    options: AddMultiStateDiscreteOptions
+): UAMultiStateDiscreteImpl<T, DT> {
+    const addressSpace = namespace.addressSpace;
+    assert(Object.hasOwn(options, "enumStrings"));
+    assert(!Object.hasOwn(options, "ValuePrecision"));
+
+    const multiStateDiscreteType = addressSpace.findVariableType("MultiStateDiscreteType");
+    if (!multiStateDiscreteType) {
+        throw new Error("Cannot find MultiStateDiscreteType");
+    }
+    // todo : if options.typeDefinition is specified, check that type is SubTypeOf MultiStateDiscreteType
+
+    options.value = options.value === undefined ? 0 : options.value;
+
+    let value: undefined | BindVariableOptions;
+    if (typeof options.value === "number") {
+        value = new Variant({
+            dataType: DataType.UInt32,
+            value: options.value
+        });
+    } else {
+        value = options.value;
+    }
+
+    const variable = namespace.addVariable({
+        ...options,
+
+        dataType: "Number",
+        typeDefinition: multiStateDiscreteType.nodeId,
+        value,
+
+        valueRank: -2
+    });
+
+    add_dataItem_stuff(variable, options);
+
+    const enumStrings = options.enumStrings.map((value: string) => {
+        return coerceLocalizedText(value);
+    });
+
+    const _enumStringsNode = namespace.addVariable({
+        accessLevel: "CurrentRead", // | CurrentWrite",
+        browseName: { name: "EnumStrings", namespaceIndex: 0 },
+        dataType: "LocalizedText",
+        minimumSamplingInterval: 0,
+        modellingRule: options.modellingRule ? "Mandatory" : undefined,
+        propertyOf: variable,
+        typeDefinition: "PropertyType",
+        userAccessLevel: "CurrentRead", // CurrentWrite",
+        value: new Variant({
+            arrayType: VariantArrayType.Array,
+            dataType: DataType.LocalizedText,
+            value: enumStrings
+        })
+    });
+
+    return promoteToMultiStateDiscrete(variable);
+}