node-opcua-address-space 2.180.0 → 2.181.0

package/impl/state_machine/ua_two_state_variable.ts

@@ -0,0 +1,421 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import type {
+    BaseNode,
+    BindVariableOptions,
+    INamespace,
+    ISessionContext,
+    UAReference,
+    UAVariable
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { VariableTypeIds } from "node-opcua-constants";
+import {
+    BrowseDirection,
+    coerceLocalizedText,
+    coerceLocalizedTextStrict,
+    type LocalizedText,
+    type LocalizedTextLike,
+    type QualifiedNameLike
+} from "node-opcua-data-model";
+import type { DataValueT } from "node-opcua-data-value";
+import { type NodeId, resolveNodeId, sameNodeId } from "node-opcua-nodeid";
+import type { NumericRange } from "node-opcua-numeric-range";
+import { type StatusCode, type StatusCodeCallback, StatusCodes } from "node-opcua-status-code";
+import { DataType, Variant, type VariantLike, type VariantT } from "node-opcua-variant";
+import type { AddTwoStateVariableOptions } from "../../api/address_space_ts.js";
+import type { ISetStateOptions } from "../../api/interfaces/i_set_state_options.js";
+// public interfaces
+import { registerNodePromoter } from "../../api/loader/register_node_promoter.js";
+import type { UATwoStateVariableEx } from "../../api/ua_two_state_variable_ex.js";
+// private types
+import { UAVariableImpl, UAVariableImplT } from "../ua_variable_impl.js";
+
+const hasTrueSubState_ReferenceTypeNodeId = resolveNodeId("HasTrueSubState");
+const hasFalseSubState_ReferenceTypeNodeId = resolveNodeId("HasFalseSubState");
+
+// Release 1.03 12 OPC Unified Architecture, Part 9
+// Two-state state machines
+// Most states defined in this standard are simple – i.e. they are either TRUE or FALSE. The
+// TwoStateVariableType is introduced specifically for this use case. More complex states are
+// modelled by using a StateMachineType defined in Part 5.
+// The TwoStateVariableType is derived from the StateVariableType.
+//
+// Attribute        Value
+// BrowseName       TwoStateVariableType
+// DataType         LocalizedText
+// ValueRank        -1 (-1 = Scalar)
+// IsAbstract       False
+//
+// Subtype of the StateVariableType defined in Part 5.
+// Note that a Reference to this subtype is not shown in the definition of the StateVariableType
+//
+// References      NodeClass BrowseName              DataType      TypeDefinition Modelling Rule
+// HasProperty     Variable  Id                      Boolean       PropertyType   Mandatory
+// HasProperty     Variable  TransitionTime          UtcTime       PropertyType   Optional
+// HasProperty     Variable  EffectiveTransitionTime UtcTime       PropertyType   Optional
+// HasProperty     Variable  TrueState               LocalizedText PropertyType   Optional
+// HasProperty     Variable  FalseState              LocalizedText PropertyType   Optional
+// HasTrueSubState StateMachine or
+//                 TwoStateVariableType
+//                                                  <StateIdentifier> Defined in Clause 5.4.2 Optional
+// HasFalseSubState StateMachine or
+//                  TwoStateVariableType
+//                                                  <StateIdentifier> Defined in Clause 5.4.3 Optional
+
+function _updateTransitionTime(node: UATwoStateVariableEx, _subState?: UAVariable, options?: ISetStateOptions) {
+    // TransitionTime specifies the time when the current state was entered.
+    if (node.transitionTime) {
+        const transitionTime = options?.transitionTime || new Date();
+        node.transitionTime.setValueFromSource({ dataType: DataType.DateTime, value: transitionTime });
+    }
+}
+
+function _updateEffectiveTransitionTime(node: UATwoStateVariableImpl, options?: ISetStateOptions) {
+    if (node.effectiveTransitionTime) {
+        const effectiveTransitionTime = options?.effectiveTransitionTime || new Date();
+
+        // because subStateNode ",subStateNode.browseName.toString());
+        node.effectiveTransitionTime.setValueFromSource({
+            dataType: DataType.DateTime,
+            value: effectiveTransitionTime
+        });
+    }
+}
+
+function _getEffectiveDisplayName<_T, _DT extends DataType>(
+    node: UATwoStateVariableImpl
+): DataValueT<LocalizedText, DataType.LocalizedText> {
+    const humanReadableString = _getHumanReadableString(node);
+    if (humanReadableString.statusCode.isNotGood()) {
+        return humanReadableString;
+    }
+    const boolValue = node.getValue();
+
+    let subStateNodes: BaseNode[];
+    if (boolValue) {
+        subStateNodes = node.findReferencesExAsObject("HasTrueSubState", BrowseDirection.Forward);
+    } else {
+        subStateNodes = node.findReferencesExAsObject("HasFalseSubState", BrowseDirection.Forward);
+    }
+    const _states = subStateNodes.forEach((_n: BaseNode) => {
+        // todo happen
+    });
+
+    return humanReadableString;
+}
+
+function _getHumanReadableString(node: UATwoStateVariableImpl): DataValueT<LocalizedText, DataType.LocalizedText> {
+    const dataValue = node.id.readValue();
+
+    if (dataValue.statusCode.isNotGood()) {
+        const _c = dataValue.clone() as DataValueT<LocalizedText, DataType.LocalizedText>;
+        _c.value = new Variant({
+            dataType: DataType.LocalizedText,
+            value: coerceLocalizedTextStrict("")
+        }) as VariantT<LocalizedText, DataType.LocalizedText>;
+
+        return _c;
+    }
+    assert(dataValue.value.dataType === DataType.Boolean);
+    const boolValue = dataValue.value.value;
+
+    // The Value Attribute of a TwoStateVariable contains the current state as a human readable name.
+    // The EnabledState for example, might contain the name “Enabled” when TRUE and “Disabled” when FALSE.
+
+    const dataValue2 = dataValue.clone();
+    dataValue2.value = new Variant({
+        dataType: DataType.LocalizedText,
+        value: boolValue ? node.getTrueState() : node.getFalseState()
+    });
+    return dataValue2 as DataValueT<LocalizedText, DataType.LocalizedText>;
+}
+
+export function _install_TwoStateVariable_machinery(
+    node: UAVariable,
+    options: TwoStateVariableInitializeOptions
+): UATwoStateVariableEx {
+    assert(node.dataTypeObj.browseName.toString() === "LocalizedText");
+    assert(node.minimumSamplingInterval === 0);
+    assert(node.typeDefinitionObj.browseName.toString() === "TwoStateVariableType");
+    assert(node.dataTypeObj.browseName.toString() === "LocalizedText");
+    assert(Object.hasOwn(node, "valueRank") && (node.valueRank === -1 || node.valueRank === 0));
+
+    // promote node into a UATwoStateVariable
+    const _node = promoteToTwoStateVariable(node);
+    (node as UATwoStateVariableImpl).initialize(options);
+    return _node;
+}
+
+export function promoteToTwoStateVariable(node: UAVariable): UATwoStateVariableEx {
+    if (node instanceof UATwoStateVariableImpl) {
+        return node;
+    }
+    // c8 ignore next
+    if (!(node instanceof UAVariableImpl)) {
+        throw new Error("Trying to promote a invalid object");
+    }
+    Object.setPrototypeOf(node, UATwoStateVariableImpl.prototype);
+    return node as UATwoStateVariableImpl;
+}
+registerNodePromoter(VariableTypeIds.TwoStateVariableType, promoteToTwoStateVariable);
+
+export interface TwoStateVariableInitializeOptions {
+    trueState?: LocalizedTextLike;
+    falseState?: LocalizedTextLike;
+    isFalseSubStateOf?: NodeId | string | BaseNode;
+    isTrueSubStateOf?: NodeId | string | BaseNode;
+
+    value?: boolean | BindVariableOptions;
+}
+
+export declare interface UATwoStateVariableImpl extends UATwoStateVariableEx {
+    on(): this;
+    once(): this;
+    readValue(
+        context?: ISessionContext | null,
+        indexRange?: NumericRange,
+        dataEncoding?: QualifiedNameLike | null
+    ): DataValueT<LocalizedText, DataType.LocalizedText>;
+    writeValue(
+        context: ISessionContext,
+        dataValue: DataValueT<LocalizedText, DataType.LocalizedText>,
+        indexRange: NumericRange | null,
+        callback: StatusCodeCallback
+    ): void;
+
+    writeValue(
+        context: ISessionContext,
+        dataValue: DataValueT<LocalizedText, DataType.LocalizedText>,
+        callback: StatusCodeCallback
+    ): void;
+    writeValue(
+        context: ISessionContext,
+        dataValue: DataValueT<LocalizedText, DataType.LocalizedText>,
+        indexRange?: NumericRange | null
+    ): Promise<StatusCode>;
+}
+/***
+ * @class UATwoStateVariable
+ */
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: interface adds typed members/overloads for this class
+export class UATwoStateVariableImpl extends UAVariableImplT<LocalizedText, DataType.LocalizedText> implements UATwoStateVariableEx {
+    private _trueState?: string;
+    private _falseState?: string;
+
+    get isFalseSubStateOf(): UATwoStateVariableEx {
+        return super.isFalseSubStateOf as UATwoStateVariableEx;
+    }
+    get isTrueSubStateOf(): UATwoStateVariableEx {
+        return super.isTrueSubStateOf as UATwoStateVariableEx;
+    }
+
+    public initialize(options: TwoStateVariableInitializeOptions): void {
+        if (options.trueState) {
+            assert(!!options.falseState);
+            assert(typeof options.trueState === "string");
+            assert(typeof options.falseState === "string");
+
+            if (this.trueState) {
+                this.trueState.setValueFromSource({
+                    dataType: DataType.LocalizedText,
+                    value: coerceLocalizedText(options.trueState)
+                });
+            } else {
+                this._trueState = coerceLocalizedTextStrict(options.trueState).text ?? undefined;
+            }
+            if (this.falseState) {
+                this.falseState.setValueFromSource({
+                    dataType: DataType.LocalizedText,
+                    value: coerceLocalizedText(options.falseState)
+                });
+            } else {
+                this._falseState = coerceLocalizedTextStrict(options.falseState).text ?? undefined;
+            }
+        }
+
+        // handle isTrueSubStateOf
+        if (options.isTrueSubStateOf) {
+            this.addReference({
+                isForward: false,
+                nodeId: options.isTrueSubStateOf,
+                referenceType: "HasTrueSubState"
+            });
+        }
+
+        if (options.isFalseSubStateOf) {
+            this.addReference({
+                isForward: false,
+                nodeId: options.isFalseSubStateOf,
+                referenceType: "HasFalseSubState"
+            });
+        }
+
+        if (options.value === undefined) {
+            this.id.setValueFromSource(
+                {
+                    dataType: "Boolean",
+                    value: false
+                },
+                StatusCodes.UncertainInitialValue
+            );
+        } else if (typeof options.value === "boolean") {
+            this.id.setValueFromSource(
+                {
+                    dataType: "Boolean",
+                    value: options.value
+                },
+                StatusCodes.Good
+            );
+        } else if (Object.hasOwn(options.value, "dataType")) {
+            assert((options.value as VariantLike).dataType === DataType.Boolean);
+            this.id.setValueFromSource(options.value as VariantLike, StatusCodes.Good);
+        } else {
+            this.id.bindVariable(options.value);
+        }
+        this._postInitialize();
+    }
+
+    public _postInitialize(): void {
+        if (this.effectiveTransitionTime) {
+            // install "value_changed" event handler on SubState that are already defined
+            const subStates = this.getTrueSubStates().concat(this.getFalseSubStates());
+            for (const subState of subStates) {
+                subState.on("value_changed", () => _updateEffectiveTransitionTime(this));
+            }
+        }
+
+        // it should be possible to define a trueState and falseState LocalizedText even if
+        // the trueState or FalseState node is not exposed. Therefore we need to store their value
+        // into dedicated variables.
+        this.id.on("value_changed", () => {
+            this._internal_set_dataValue(_getHumanReadableString(this));
+        });
+        this._internal_set_dataValue(_getHumanReadableString(this));
+
+        // todo : also set the effectiveDisplayName if present
+
+        // from spec Part 5
+        // Release 1.03 OPC Unified Architecture, Part 5
+        // EffectiveDisplayName contains a human readable name for the current state of the state
+        // machine after taking the state of any SubStateMachines in account. There is no rule specified
+        // for which state or sub-state should be used. It is up to the Server and will depend on the
+        // semantics of the StateMachineType
+        //
+        // EffectiveDisplayName will be constructed by adding the EnabledState
+        // and the State of the addTrue state
+        if (this.effectiveDisplayName) {
+            const effectiveDisplayName = this.effectiveDisplayName as UAVariableImpl;
+            this.id.on("value_changed", () => {
+                effectiveDisplayName._internal_set_dataValue(_getEffectiveDisplayName(this));
+            });
+            effectiveDisplayName._internal_set_dataValue(_getEffectiveDisplayName(this));
+        }
+    }
+    /**
+     */
+    public setValue(boolValue: boolean, options?: ISetStateOptions): void {
+        assert(typeof boolValue === "boolean");
+        const dataValue = this.id?.readValue();
+        const oldValue = dataValue.value.value;
+        if (dataValue.statusCode.isGood() && boolValue === oldValue) {
+            return; // nothing to do
+        }
+        //
+        this.id.setValueFromSource(new Variant({ dataType: DataType.Boolean, value: boolValue }));
+        _updateTransitionTime(this, undefined, options);
+        _updateEffectiveTransitionTime(this, options);
+    }
+
+    /**
+     */
+    public getValue(): boolean {
+        const dataValue = this.id?.readValue();
+        assert(dataValue.statusCode.isGood());
+        assert(dataValue.value.dataType === DataType.Boolean);
+        return dataValue.value.value;
+    }
+
+    /**
+     */
+    public getValueAsString(): string {
+        const dataValue = this.readValue();
+        assert(dataValue.statusCode.isGood());
+        assert(dataValue.value.dataType === DataType.LocalizedText);
+        return dataValue.value.value.text?.toString() || "";
+    }
+    public getTrueState(): LocalizedText {
+        return this.trueState ? this.trueState.readValue().value.value : coerceLocalizedTextStrict(this._trueState || "TRUE");
+    }
+    public getFalseState(): LocalizedText {
+        return this.falseState ? this.falseState.readValue().value.value : coerceLocalizedTextStrict(this._falseState || "FALSE");
+    }
+    // TODO : shall we care about overloading the remove_backward_reference method ?
+    // some TrueSubState and FalseSubState relationship may be added later
+    // so we need a mechanism to keep adding the "value_changed" event handle on subStates that
+    // will be defined later.
+    // install change detection on sub State
+    // this is useful to change the effective transitionTime
+    // EffectiveTransitionTime specifies the time when the current state or one of its sub states was entered.
+    // If, for example, a LevelAlarm is active and – while active – switches several times between High and
+    // HighHigh, then the TransitionTime stays at the point in time where the Alarm became active whereas the
+    // EffectiveTransitionTime changes with each shift of a sub state.
+    public _add_backward_reference(reference: UAReference): void {
+        super._add_backward_reference(reference);
+
+        if (
+            reference.isForward &&
+            (sameNodeId(reference.referenceType, hasTrueSubState_ReferenceTypeNodeId) ||
+                sameNodeId(reference.referenceType, hasFalseSubState_ReferenceTypeNodeId))
+        ) {
+            const addressSpace = this.addressSpace;
+            // add event handle
+            const subState = addressSpace.findNode(reference.nodeId) as UAVariable;
+            subState.on("value_changed", _updateEffectiveTransitionTime.bind(null, this, undefined));
+        }
+    }
+}
+
+export function _addTwoStateVariable(namespace: INamespace, options: AddTwoStateVariableOptions): UATwoStateVariableEx {
+    const addressSpace = namespace.addressSpace;
+
+    const twoStateVariableType = addressSpace.findVariableType("TwoStateVariableType");
+    if (!twoStateVariableType) {
+        throw new Error("cannot find TwoStateVariableType");
+    }
+
+    options.optionals = options.optionals || [];
+    if (options.trueState) {
+        options.optionals.push("TrueState");
+    }
+    if (options.falseState) {
+        options.optionals.push("FalseState");
+    }
+
+    // we want event based changes...
+    options.minimumSamplingInterval = 0;
+
+    const node = twoStateVariableType.instantiate({
+        browseName: options.browseName,
+
+        nodeId: options.nodeId,
+
+        description: options.description,
+
+        componentOf: options.componentOf,
+        organizedBy: options.organizedBy,
+
+        modellingRule: options.modellingRule,
+
+        dataType: resolveNodeId(DataType.LocalizedText),
+
+        minimumSamplingInterval: options.minimumSamplingInterval,
+
+        optionals: options.optionals
+    });
+
+    const _node = _install_TwoStateVariable_machinery(node, options);
+    return _node;
+}

package/impl/tool_isSubtypeOf.ts

@@ -0,0 +1,168 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import type {
+    BaseNode,
+    UADataType,
+    UAObjectType,
+    UAReference,
+    UAReferenceType,
+    UAVariableType
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { NodeClass } from "node-opcua-data-model";
+import { type NodeId, type NodeIdLike, resolveNodeId, sameNodeId } from "node-opcua-nodeid";
+import type { BaseNodeImpl } from "./base_node_impl.js";
+import { BaseNode_getCache } from "./base_node_private.js";
+import { nodeIdKey, ReferenceImpl } from "./reference_impl.js";
+import { typeHierarchyVersion } from "./reference_type_version.js";
+
+const HasSubTypeNodeId = resolveNodeId("HasSubtype");
+
+function _filterSubType(reference: UAReference) {
+    return sameNodeId(reference.referenceType, HasSubTypeNodeId) && !reference.isForward;
+}
+
+export type BaseNodeConstructor<T extends BaseNode> = new () => T;
+
+function _slow_isSubtypeOf<T extends UAType>(this: T, Class: typeof BaseNodeImpl, baseType: T | NodeIdLike): boolean {
+    if (!(baseType instanceof Class)) {
+        const node = this.addressSpace.findNode(baseType as NodeIdLike);
+        if (!node || !(node instanceof Class)) {
+            throw new Error("Invalid argument");
+        }
+        return _slow_isSubtypeOf.call(this, Class, node as unknown as T);
+    }
+    assert(this instanceof Class);
+    assert(baseType instanceof Class, " Object must have same type");
+    assert(this.addressSpace);
+
+    if (sameNodeId(this.nodeId, baseType.nodeId)) {
+        return true;
+    }
+    const references = this.allReferences();
+
+    const subTypes = references.filter(_filterSubType);
+    assert(subTypes.length <= 1, "should have zero or one subtype no more");
+
+    for (const subType1 of subTypes) {
+        const subTypeId = subType1.nodeId;
+        const subTypeNode = this.addressSpace.findNode(subTypeId) as unknown as T;
+        // c8 ignore next
+        if (!subTypeNode) {
+            throw new Error(`Cannot find object with nodeId ${subTypeId.toString()}`);
+        }
+        if (sameNodeId(subTypeNode.nodeId, baseType.nodeId)) {
+            return true;
+        } else {
+            if (_slow_isSubtypeOf.call(subTypeNode, Class, baseType)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+export type MemberFuncValue<T, P, R> = (this: T, param: P) => R;
+
+// per node, the memo of its isSubtypeOf answers, keyed by the argument's NodeId (a number for a
+// numeric id, so that the common call builds no string): a memo keyed by the node itself would
+// keep every type ever asked about alive, deleted or not
+const g_WeakMap = new WeakMap<object, Map<string | number, unknown>>();
+/** the typeHierarchyVersion each memo was built against */
+const g_memoVersion = new WeakMap<object, number>();
+
+export function wipeMemorizedStuff(node: object) {
+    if (g_WeakMap.has(node)) {
+        g_WeakMap.delete(node);
+    }
+}
+
+//  http://jsperf.com/underscore-js-memoize-refactor-test
+//  http://addyosmani.com/blog/faster-javascript-memoization/
+function wrap_memoize<T extends object, P, R>(
+    func: MemberFuncValue<T, P, R>,
+    hashFunc?: (this: T, param: P) => string | number
+): MemberFuncValue<T, P, R> {
+    const effectiveHashFunc: (this: T, param: P) => string | number =
+        hashFunc ??
+        function (this: T, param: P) {
+            return (param as unknown as object).toString();
+        };
+    return function memoize(this: T, param: P): R {
+        let memoMap = g_WeakMap.get(this) as Map<string | number, R> | undefined;
+        if (!memoMap || g_memoVersion.get(this) !== typeHierarchyVersion.count) {
+            // no memo yet, or a HasSubtype reference moved somewhere since it was built
+            memoMap = new Map<string | number, R>();
+            g_WeakMap.set(this, memoMap as Map<string | number, unknown>);
+            g_memoVersion.set(this, typeHierarchyVersion.count);
+        }
+
+        const hash = effectiveHashFunc.call(this, param);
+        if (memoMap.has(hash)) {
+            return memoMap.get(hash) as R;
+        }
+        const cache_value = func.call(this, param);
+        memoMap.set(hash, cache_value);
+        return cache_value;
+    };
+}
+
+function hashBaseNode(e: BaseNode | NodeIdLike): string | number {
+    if (e && typeof e === "object" && "nodeId" in e) {
+        return nodeIdKey((e as BaseNode).nodeId);
+    }
+    return nodeIdKey(resolveNodeId(e as NodeIdLike));
+}
+
+export type IsSubtypeOfFunc<T extends UAType> = (this: T, baseType: T) => boolean;
+
+export type UAType = UAReferenceType | UADataType | UAObjectType | UAVariableType;
+
+export function construct_isSubtypeOf<T extends UAType>(Class: typeof BaseNodeImpl): IsSubtypeOfFunc<T> {
+    return wrap_memoize(function (this: T, baseType: T | NodeIdLike): boolean {
+        if (!(baseType instanceof Class)) {
+            throw new Error(
+                "expecting baseType to be " +
+                    Class.name +
+                    " but got " +
+                    baseType.toString() +
+                    " " +
+                    NodeClass[(baseType as BaseNode).nodeClass]
+            );
+        }
+        if (!(this instanceof Class)) {
+            throw new Error(`expecting this to be ${Class.name} but got ${baseType.toString()}`);
+        }
+        return _slow_isSubtypeOf.call(this, Class, baseType as T);
+    }, hashBaseNode);
+}
+
+export function construct_slow_isSubtypeOf<T extends UAType>(Class: typeof BaseNodeImpl) {
+    return function (this: T, baseType: T | NodeIdLike): boolean {
+        return _slow_isSubtypeOf.call(this, Class, baseType);
+    };
+}
+
+/**
+ * returns the nodeId of the Type which is the super type of this
+ */
+export function get_subtypeOf<T extends BaseNode>(this: T): NodeId | null {
+    const s = get_subtypeOfObj.call(this);
+    return s ? s.nodeId : null;
+}
+
+export function get_subtypeOfObj<T extends BaseNode>(this: T): T | null {
+    const _cache = BaseNode_getCache(this);
+
+    if (_cache._subtypeOfObj === undefined) {
+        const is_subtype_of_ref = this.findReference("HasSubtype", false);
+        if (is_subtype_of_ref) {
+            _cache._subtypeOfObj = ReferenceImpl.resolveReferenceNode(this.addressSpace, is_subtype_of_ref);
+        } else {
+            _cache._subtypeOfObj = null;
+        }
+    }
+    return (_cache._subtypeOfObj as T) || null;
+}