node-opcua-address-space 2.180.0 → 2.181.0

package/impl/ua_variable_type_impl.ts

@@ -0,0 +1,390 @@
+/**
+ * @module node-opcua-address-space
+ */
+import type {
+    AddVariableOptions,
+    BaseNode,
+    BaseNodeEvents,
+    IAddressSpace,
+    INamespace,
+    InstantiateVariableOptions,
+    ModellingRuleType,
+    UAMethod,
+    UAObject,
+    UAObjectType,
+    UAVariable,
+    UAVariableType
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import type { UInt32 } from "node-opcua-basic-types";
+import {
+    AttributeIds,
+    BrowseDirection,
+    coerceQualifiedName,
+    type LocalizedTextLike,
+    NodeClass,
+    type QualifiedName
+} from "node-opcua-data-model";
+import { DataValue, type DataValueLike } from "node-opcua-data-value";
+import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
+import { coerceNodeId, NodeId, type NodeIdLike } from "node-opcua-nodeid";
+import { StatusCodes } from "node-opcua-status-code";
+import { isNullOrUndefined } from "node-opcua-utils";
+import { DataType, Variant, VariantArrayType, verifyRankAndDimensions } from "node-opcua-variant";
+import { SessionContext } from "../api/session_context.js";
+import { initialize_properties_and_components } from "./_instantiate_helpers.js";
+import type { AddressSpacePrivate } from "./address_space_private.js";
+import { BaseNodeImpl, type InternalBaseNodeOptions } from "./base_node_impl.js";
+import { ToStringBuilder, UAVariableType_toString } from "./base_node_private.js";
+import { checkValueRankCompatibility } from "./check_value_rank_compatibility.js";
+import { _getBasicDataType } from "./get_basic_datatype.js";
+import { construct_isSubtypeOf, get_subtypeOf, get_subtypeOfObj } from "./tool_isSubtypeOf.js";
+
+const debugLog = make_debugLog("ua_variable_type_impl");
+const doDebug = checkDebugFlag("ua_variable_type_impl");
+const warningLog = make_warningLog("ua_variable_type_impl");
+const errorLog = make_errorLog("ua_variable_type_impl");
+
+interface InstantiateS {
+    propertyOf?: NodeIdLike | UAObject | UAObjectType | UAVariable | UAVariableType | UAMethod;
+    componentOf?: NodeIdLike | BaseNode;
+    modellingRule?: ModellingRuleType;
+    copyAlsoModellingRules?: boolean;
+    copyAlsoAllOptionals?: boolean;
+}
+export function topMostParentIsObjectTypeOrVariableType(addressSpace: AddressSpacePrivate, options: InstantiateS): boolean {
+    if (options.copyAlsoModellingRules) {
+        return true;
+    }
+    if (options.modellingRule) {
+        return true;
+    }
+
+    const parent = options.propertyOf || options.componentOf;
+    if (!parent) {
+        return false;
+    }
+    const parentNode = addressSpace._coerceNode(parent as BaseNode | NodeIdLike);
+    if (!parentNode) {
+        return false;
+    }
+
+    let currentNode: BaseNode | null = parentNode;
+    while (currentNode) {
+        const nodeClass = parentNode.nodeClass;
+        if (nodeClass === NodeClass.ObjectType || nodeClass === NodeClass.VariableType) {
+            return true;
+        }
+        if (nodeClass === NodeClass.Object || nodeClass === NodeClass.Variable || nodeClass === NodeClass.Method) {
+            /** */
+        }
+        currentNode = currentNode.findReferencesEx("HasChild", BrowseDirection.Inverse)[0]?.node as BaseNode;
+    }
+    return false;
+}
+export interface UAVariableTypeOptions extends InternalBaseNodeOptions {
+    /**
+     * This attribute indicates whether the Value attribute of the Variable is an array and how many dimensions the array has.
+     * It may have the following values:
+     *   * n > 1: the Value is an array with the specified number of dimensions.
+     *   * OneDimension (1): The value is an array with one dimension.
+     *   * OneOrMoreDimensions (0): The value is an array with one or more dimensions.
+     *   * Scalar (−1): The value is not an array.
+     *   * Any (−2): The value can be a scalar or an array with any number of dimensions.
+     *   * ScalarOrOneDimension (−3): The value can be a scalar or a one dimensional array.
+     *   * All DataTypes are considered to be scalar, even if they have array-like semantics like ByteString and String.
+     */
+    valueRank?: number;
+    arrayDimensions?: number[] | null;
+    historizing?: boolean;
+    isAbstract?: boolean;
+    value?: unknown;
+    dataType: NodeIdLike;
+}
+
+function deprecate<T>(func: T): T {
+    return func;
+}
+export class UAVariableTypeImpl extends BaseNodeImpl<BaseNodeEvents> implements UAVariableType {
+    public readonly nodeClass = NodeClass.VariableType;
+
+    public get subtypeOf(): NodeId | null {
+        return get_subtypeOf.call(this);
+    }
+
+    public get subtypeOfObj(): UAVariableType | null {
+        return get_subtypeOfObj.call(this) as UAVariableType;
+    }
+
+    public isSubtypeOf = construct_isSubtypeOf<UAVariableType>(UAVariableTypeImpl);
+
+    /** @deprecated - use  isSubtypeOf instead */
+    public isSupertypeOf = deprecate(construct_isSubtypeOf<UAVariableType>(UAVariableTypeImpl));
+
+    public readonly isAbstract: boolean;
+    public dataType: NodeId;
+    public valueRank: number;
+    public arrayDimensions: UInt32[] | null;
+    public readonly minimumSamplingInterval: number;
+    // declare-only: an emitted field would hide, on a type without a default value, a child named Value
+    public declare readonly value: unknown;
+    public historizing: boolean;
+
+    constructor(options: UAVariableTypeOptions) {
+        super(options);
+
+        verifyRankAndDimensions(options);
+        this.valueRank = options.valueRank || -1;
+        this.arrayDimensions = options.arrayDimensions || null;
+
+        this.minimumSamplingInterval = 0;
+
+        this.historizing = isNullOrUndefined(options.historizing) ? false : (options.historizing as boolean);
+        this.isAbstract = isNullOrUndefined(options.isAbstract) ? false : (options.isAbstract as boolean);
+
+        // optional default value for instances of this UAVariableType; assigned only when given, so that
+        // a type without one does not hide a child named Value behind an own undefined field
+        if (options.value !== undefined) {
+            this.value = options.value;
+        }
+
+        this.dataType = coerceNodeId(options.dataType); // DataType (NodeId)
+
+        if (options.value) {
+            this.value = new Variant(options.value);
+        }
+    }
+
+    public readAttribute(context: SessionContext | null, attributeId: AttributeIds): DataValue {
+        assert(!context || context instanceof SessionContext);
+
+        const options: DataValueLike = {};
+        switch (attributeId) {
+            case AttributeIds.IsAbstract:
+                options.value = { dataType: DataType.Boolean, value: !!this.isAbstract };
+                options.statusCode = StatusCodes.Good;
+                break;
+            case AttributeIds.Value:
+                if (Object.hasOwn(this, "value") && this.value !== undefined) {
+                    assert((this.value as Variant).schema.name === "Variant");
+                    options.value = this.value as Variant;
+                    options.statusCode = StatusCodes.Good;
+                } else {
+                    // c8 ignore next
+                    doDebug && debugLog(" warning Value not implemented");
+                    options.value = { dataType: DataType.Null };
+                    options.statusCode = StatusCodes.BadAttributeIdInvalid;
+                }
+                break;
+            case AttributeIds.DataType:
+                assert(this.dataType instanceof NodeId);
+                options.value = { dataType: DataType.NodeId, value: this.dataType };
+                options.statusCode = StatusCodes.Good;
+                break;
+            case AttributeIds.ValueRank:
+                options.value = { dataType: DataType.Int32, value: this.valueRank };
+                options.statusCode = StatusCodes.Good;
+                break;
+            case AttributeIds.ArrayDimensions:
+                assert(Array.isArray(this.arrayDimensions) || this.arrayDimensions === null);
+                options.value = {
+                    arrayType: VariantArrayType.Array,
+                    dataType: DataType.UInt32,
+                    value: this.arrayDimensions
+                };
+                options.statusCode = StatusCodes.Good;
+                break;
+            default:
+                return super.readAttribute(context, attributeId);
+        }
+        return new DataValue(options);
+    }
+
+    public toString(): string {
+        const options = new ToStringBuilder();
+        UAVariableType_toString.call(this, options);
+        return options.toString();
+    }
+
+    /**
+     * instantiate an object of this UAVariableType
+     * The instantiation takes care of object type inheritance when constructing inner properties
+   
+     * Note : HasComponent usage scope
+     *
+     * ```text
+     *    Source          |     Destination
+     * -------------------+---------------------------
+     *  Object            | Object, Variable,Method
+     *  ObjectType        |
+     * -------------------+---------------------------
+     *  DataVariable      | Variable
+     *  DataVariableType  |
+     * ```
+     *
+     *  see : OPCUA 1.03 page 44 $6.4 Instances of ObjectTypes and VariableTypes
+     */
+    public instantiate(options: InstantiateVariableOptions): UAVariable {
+        const addressSpace = this.addressSpace as AddressSpacePrivate;
+        // xx assert(!this.isAbstract, "cannot instantiate abstract UAVariableType");
+
+        assert(options, "missing option object");
+        assert(
+            typeof options.browseName === "string" || (options.browseName !== null && typeof options.browseName === "object"),
+            "expecting a browse name"
+        );
+        assert(!Object.hasOwn(options, "propertyOf"), "Use addressSpace#addVariable({ propertyOf: xxx}); to add a property");
+
+        assertUnusedChildBrowseName(addressSpace, options);
+
+        const baseVariableType = addressSpace.findVariableType("BaseVariableType");
+        // c8 ignore next
+        if (!baseVariableType) {
+            throw new Error("BaseVariableType must be defined in the address space");
+        }
+
+        let dataType = options.dataType !== undefined ? options.dataType : this.dataType;
+        // may be required (i.e YArrayItemType )
+
+        dataType = this.resolveNodeId(dataType); // DataType (NodeId)
+        assert(dataType instanceof NodeId);
+
+        const valueRank = options.valueRank !== undefined ? options.valueRank : this.valueRank;
+
+        const { result, errorMessage } = checkValueRankCompatibility(valueRank, this.valueRank);
+        if (!result) {
+            errorLog(errorMessage);
+            throw new Error(errorMessage);
+        }
+
+        const arrayDimensions = options.arrayDimensions !== undefined ? options.arrayDimensions : this.arrayDimensions;
+
+        // c8 ignore next
+        if (!dataType || dataType.isEmpty()) {
+            warningLog(" options.dataType", options.dataType ? options.dataType.toString() : "<null>");
+            warningLog(" this.dataType", this.dataType ? this.dataType.toString() : "<null>");
+            throw new Error(" A valid dataType must be specified");
+        }
+
+        const copyAlsoModellingRules = topMostParentIsObjectTypeOrVariableType(addressSpace, options);
+
+        const defaultDataType = this.dataType;
+        // BadAttributeIdInvalid
+        const defaultDataValue = this.readAttribute(null, AttributeIds.Value);
+        const defaultValue =
+            (defaultDataType.namespace === 0 && defaultDataType.value === 0) || defaultDataValue.statusCode.isNotGood()
+                ? undefined
+                : defaultDataValue.value;
+
+        const opts: AddVariableOptions = {
+            arrayDimensions,
+            browseName: options.browseName,
+            componentOf: options.componentOf,
+            dataType,
+            description:
+                options.description === undefined
+                    ? (this.description?.clone() as LocalizedTextLike | undefined)
+                    : options.description,
+            displayName: options.displayName || "",
+            eventSourceOf: options.eventSourceOf,
+            minimumSamplingInterval: options.minimumSamplingInterval,
+            modellingRule: options.modellingRule,
+            nodeId: options.nodeId,
+            notifierOf: options.notifierOf,
+            organizedBy: options.organizedBy,
+            typeDefinition: this.nodeId,
+            value: options.value || defaultValue,
+            valueRank
+        };
+
+        const namespace: INamespace = options.namespace || addressSpace.getOwnNamespace();
+        const instance = namespace.addVariable(opts);
+
+        // xx assert(instance.minimumSamplingInterval === options.minimumSamplingInterval);
+        const copyAlsoAllOptionals = options.copyAlsoAllOptionals || false;
+
+        initialize_properties_and_components(
+            instance,
+            baseVariableType,
+            this,
+            copyAlsoModellingRules,
+            copyAlsoAllOptionals,
+            options.optionals
+        );
+
+        // if VariableType is a type of Structure DataType
+        // we need to instantiate a dataValue
+        // and create a bidirectional binding with the individual properties of this type
+        instance.bindExtensionObject(options.extensionObject, { createMissingProp: false });
+
+        assert(instance.typeDefinition.toString() === this.nodeId.toString());
+
+        instance.install_extra_properties();
+
+        if (this._postInstantiateFunc) {
+            this._postInstantiateFunc(instance as BaseNode, this);
+        }
+
+        return instance;
+    }
+    public getBasicDataType(): DataType {
+        return _getBasicDataType(this);
+    }
+}
+
+/**
+
+ * returns true if the parent object has a child  with the provided browseName
+ * @param parent
+ * @param childBrowseName
+ */
+function hasChildWithBrowseName(parent: BaseNode, childBrowseName: QualifiedName): boolean {
+    if (!parent) {
+        throw Error("Internal error");
+    }
+    // extract children
+    const children = parent.findReferencesAsObject("HasChild", true);
+
+    return (
+        children.filter((child: BaseNode) => {
+            return child.browseName.name?.toString() === childBrowseName.name?.toString();
+        }).length > 0
+    );
+}
+
+function getParent(addressSpace: IAddressSpace, options: InstantiateVariableOptions) {
+    const parent = options.componentOf || options.organizedBy;
+    if (parent instanceof NodeId) {
+        return addressSpace.findNode(parent as NodeId);
+    }
+    return parent;
+}
+
+export function assertUnusedChildBrowseName(addressSpace: AddressSpacePrivate, options: InstantiateVariableOptions): void {
+    const resolveOptionalObject = (node: BaseNode | NodeIdLike | undefined): BaseNode | undefined =>
+        node ? addressSpace._coerceNode(node) || undefined : undefined;
+
+    options.componentOf = resolveOptionalObject(options.componentOf);
+    options.organizedBy = resolveOptionalObject(options.organizedBy);
+
+    assert(!(options.componentOf && options.organizedBy));
+
+    const parent = getParent(addressSpace, options);
+    if (!parent) {
+        return;
+    }
+    assert(parent !== null && typeof parent === "object");
+    if (!(parent instanceof BaseNodeImpl)) {
+        throw new Error(`Invalid parent  parent is ${parent.constructor.name}`);
+    }
+    // c8 ignore next
+    // verify that no components already exists in parent
+    if (parent && hasChildWithBrowseName(parent as BaseNode, coerceQualifiedName(options.browseName))) {
+        throw new Error(
+            "object " +
+                parent.browseName.name?.toString() +
+                " have already a child with browseName " +
+                options.browseName.toString()
+        );
+    }
+}

package/impl/ua_view_impl.ts

@@ -0,0 +1,53 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import { EventNotifierFlags, type ISessionContext, type UAView } from "node-opcua-address-space-base";
+import { AttributeIds, NodeClass } from "node-opcua-data-model";
+import { DataValue, type DataValueLike } from "node-opcua-data-value";
+import { StatusCodes } from "node-opcua-status-code";
+import { DataType } from "node-opcua-variant";
+
+import { SessionContext } from "../api/session_context.js";
+import { BaseNodeImpl, type InternalBaseNodeOptions } from "./base_node_impl.js";
+
+export interface InternalViewOptions extends InternalBaseNodeOptions {
+    containsNoLoops?: boolean;
+}
+
+export class UAViewImpl extends BaseNodeImpl implements UAView {
+    public readonly nodeClass = NodeClass.View;
+    public readonly containsNoLoops: boolean;
+    private _eventNotifier: EventNotifierFlags;
+    public get eventNotifier(): EventNotifierFlags {
+        return this._eventNotifier;
+    }
+
+    constructor(options: InternalViewOptions) {
+        super(options);
+        this.containsNoLoops = !!options.containsNoLoops;
+        this._eventNotifier = EventNotifierFlags.None;
+    }
+
+    public readAttribute(context: ISessionContext | null, attributeId: AttributeIds): DataValue {
+        context = context || SessionContext.defaultContext;
+
+        const options: DataValueLike = {};
+
+        switch (attributeId) {
+            case AttributeIds.EventNotifier:
+                options.value = { dataType: DataType.Byte, value: this.eventNotifier };
+                options.statusCode = StatusCodes.Good;
+                break;
+
+            case AttributeIds.ContainsNoLoops:
+                options.value = { dataType: DataType.Boolean, value: this.containsNoLoops };
+                options.statusCode = StatusCodes.Good;
+                break;
+
+            default:
+                return super.readAttribute(context, attributeId);
+        }
+        return new DataValue(options);
+    }
+}

package/impl/validate_data_type_correctness.ts

@@ -0,0 +1,142 @@
+import chalk from "chalk";
+import type { IAddressSpace, UADataType } from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { DataType } from "node-opcua-basic-types";
+import { checkDebugFlag, make_debugLog } from "node-opcua-debug";
+import { makeNodeId, type NodeId } from "node-opcua-nodeid";
+
+const debugLog = make_debugLog("validate_data_type_correctness");
+const doDebug = checkDebugFlag("validate_data_type_correctness");
+
+function _dataType_toUADataType(addressSpace: IAddressSpace, dataType: DataType): UADataType {
+    assert(addressSpace);
+    assert(dataType !== DataType.Null);
+
+    // Resolved by NodeId rather than by name: a built-in type's enum value is its
+    // ns=0 identifier, whereas the DataType enum's names do not all match the
+    // nodeset's browse names. DataType[24] is "Variant" but node i=24 is
+    // "BaseDataType", and DataType[22] is "ExtensionObject" but node i=22 is
+    // "Structure" - so a by-name lookup threw for any Variant-encoded value, and
+    // the escaping exception surfaced to the client as BadInternalError. (The
+    // ExtensionObject case is caught by an earlier branch and never reached here.)
+    const dataTypeNode =
+        addressSpace.findDataType(makeNodeId(dataType as number, 0)) ?? addressSpace.findDataType(DataType[dataType]);
+    /* c8 ignore next */
+    if (!dataTypeNode) {
+        throw new Error(` Cannot find DataType ${DataType[dataType]} in address Space`);
+    }
+    return dataTypeNode as UADataType;
+}
+
+const validDataTypeForEnumValue = [DataType.Int32];
+// , DataType.UInt32, DataType.Int64, DataType.UInt64];
+
+/*=
+ *
+ * @param addressSpace
+ * @param dataTypeNodeId : the nodeId matching the dataType of the destination variable.
+ * @param variantDataType: the dataType of the variant to write to the destination variable
+ * @param nodeId
+ * @return {boolean} true if the variant dataType is compatible with the Variable DataType
+ */
+export function validateDataTypeCorrectness(
+    addressSpace: IAddressSpace,
+    dataTypeNodeId: NodeId,
+    variantDataType: DataType,
+    allowNulls: boolean,
+    context?: { toString(): string }
+): boolean {
+    if (variantDataType === DataType.Null && allowNulls) {
+        return true;
+    }
+    if (variantDataType === DataType.Null && !allowNulls) {
+        return false;
+    }
+    let builtInType: DataType;
+    let builtInUADataType: UADataType;
+
+    const destUADataType = addressSpace.findDataType(dataTypeNodeId);
+
+    // c8 ignore next
+    if (!destUADataType) {
+        throw new Error(`Cannot find UADataType ${dataTypeNodeId.toString()} in address Space`);
+    }
+
+    if (variantDataType === DataType.ExtensionObject) {
+        const structure = addressSpace.findDataType("Structure");
+        // c8 ignore next
+        if (!structure) {
+            throw new Error("Cannot find Structure DataType node in standard address space");
+        }
+        if (destUADataType.isSubtypeOf(structure)) {
+            return true;
+        }
+        return false;
+    }
+
+    if (destUADataType.isAbstract) {
+        builtInUADataType = destUADataType;
+    } else {
+        builtInType = addressSpace.findCorrespondingBasicDataType(destUADataType);
+        if (builtInType === DataType.ExtensionObject) {
+            // it should have been trapped earlier
+            return false;
+        }
+        const foundDataType = addressSpace.findDataType(builtInType);
+        /* c8 ignore next */
+        if (!foundDataType) {
+            throw new Error(`Cannot find DataType ${DataType[builtInType]} in address Space`);
+        }
+        builtInUADataType = foundDataType;
+    }
+
+    const enumerationUADataType = addressSpace.findDataType("Enumeration");
+    // c8 ignore next
+    if (!enumerationUADataType) {
+        throw new Error("cannot find Enumeration DataType node in standard address space");
+    }
+    if (destUADataType.isSubtypeOf(enumerationUADataType)) {
+        // c8 ignore next
+        if (doDebug) {
+            debugLog("destUADataType.", destUADataType.browseName.toString(), destUADataType.nodeId.toString());
+            debugLog(
+                "enumerationUADataType.",
+                enumerationUADataType.browseName.toString(),
+                enumerationUADataType.nodeId.toString()
+            );
+        }
+
+        return validDataTypeForEnumValue.indexOf(variantDataType) >= 0;
+    }
+
+    // The value supplied for the attribute is not of the same type as the  value.
+    const variantUADataType = _dataType_toUADataType(addressSpace, variantDataType);
+
+    let dest_isSubTypeOf_variant = variantUADataType.isSubtypeOf(builtInUADataType);
+
+    // A family such as Image (-> ImageBMP/ImageGIF/ImageJPG/ImagePNG) is abstract, so the
+    // check above compares against Image itself; but none of its members have their own
+    // built-in encoding, so a Variant for one of them is always stamped with Image's own
+    // built-in ancestor (ByteString) - a supertype of Image, not a subtype of it, and the
+    // check above always fails for it. Accept a variant that matches that resolved ancestor.
+    if (!dest_isSubTypeOf_variant && destUADataType.isAbstract) {
+        const resolvedBuiltInType = addressSpace.findCorrespondingBasicDataType(destUADataType);
+        dest_isSubTypeOf_variant = resolvedBuiltInType !== DataType.Null && resolvedBuiltInType === variantDataType;
+    }
+
+    // c8 ignore next
+    if (doDebug) {
+        if (dest_isSubTypeOf_variant) {
+            /* c8 ignore next*/
+            debugLog(chalk.green(" ---------- Type match !!! "), " on ", context?.toString());
+        } else {
+            /* c8 ignore next*/
+            debugLog(chalk.red(" ---------- Type mismatch "), " on ", context?.toString());
+        }
+        debugLog(chalk.cyan(" Variable data Type is    = "), destUADataType.browseName.toString());
+        debugLog(chalk.cyan(" which matches basic Type = "), builtInUADataType.browseName.toString());
+        debugLog(chalk.yellow("        Actual   dataType = "), variantUADataType.browseName.toString());
+    }
+
+    return dest_isSubTypeOf_variant;
+}