node-opcua-address-space 2.180.0 → 2.181.0

package/api/interfaces/state_machine/ua_state_machine_type.ts

@@ -0,0 +1,288 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import type {
+    InstantiateObjectOptions,
+    UAObject,
+    UAObjectType,
+    UAProperty,
+    UAReferenceType,
+    UAVariableTypeT
+} from "node-opcua-address-space-base";
+import type { DateTime, UInt32 } from "node-opcua-basic-types";
+import type { LocalizedText } from "node-opcua-data-model";
+import type {
+    UAInitialState,
+    UAInitialState_Base,
+    UAState,
+    UAState_Base,
+    UAStateMachine_Base,
+    UATransition_Base,
+    UATransitionEvent_Base
+} from "node-opcua-nodeset-ua";
+import type { DataType } from "node-opcua-variant";
+
+import type { UATransitionEx } from "./ua_transition_ex.js";
+
+export type UtcTime = DateTime;
+
+export interface NonHierarchicalReferences extends UAReferenceType {
+    /** empty interface */
+}
+
+export interface UAStateVariableType extends UAVariableTypeT<LocalizedText, DataType.LocalizedText> {
+    // attributes
+    isAbstract: false;
+}
+// ----------------
+export interface StateB {
+    stateNumber: UAProperty<UInt32, DataType.UInt32>;
+}
+
+export interface UAStateType extends UAState_Base, UAObjectType {
+    /** empty interface */
+}
+
+/** empty interface */
+export interface UATransitionType extends UATransition_Base, UAObjectType {
+    /** empty interface */
+}
+
+/**
+ * Initial State Type
+ *
+ * The InitialStateType is a subtype of the StateType and is formally defined in Table B.8.
+ * An Object of the InitialStateType represents the State that a FiniteStateMachine enters
+ * when it is activated.
+ *
+ * Each FiniteStateMachine can have at most one State of type InitialStateType, but
+ * a FiniteStateMachine does not have to have a State of this type.
+ *
+ * A SubStateMachine goes into its initial state whenever the parent state is entered. However, a
+ * state machine may define a transition that goes directly to a state of the SubStateMachine. In
+ * this case the SubStateMachine goes into that State instead of the initial State. The two
+ * scenarios are illustrated in Figure B.4. The transition from State5 to State6 causes the
+ * SubStateMachine to go into the initial State (State7), however, the transition from State4 to
+ * State8 causes the parent machine to go to State6 and the SubStateMachine will go to State8.
+ *
+ * If no initial state for a SubStateMachine exists and the State having the SubStateMachine is
+ * entered directly, then the State of the SubStateMachine is server-specific.
+ */
+
+export interface UAInitialStateType extends UAInitialState_Base, UAStateType {
+    /** empty interface */
+}
+
+// export interface UAInitialState extends InitialStateB, UAState {     /** empty interface */}
+
+/**
+ * ToState Reference Type
+ *
+ * The ToState ReferenceType is a concrete ReferenceType and can be used directly. It is a
+ * subtype of NonHierarchicalReferences.
+ *
+ * The semantic of this ReferenceType is to point form a Transition to the ending State the
+ * Transition connects.
+ *
+ * The SourceNode of this ReferenceType shall be an Object of the ObjectType TransitionType or
+ * one of its subtypes. The TargetNode of this ReferenceType shall be an Object of the ObjectType
+ * StateType or one of its subtypes.
+ *
+ * References of this ReferenceType may be only exposed uni-directional. Sometimes this is
+ * required, for example, if a Transition points to a State of a sub-machine.
+ */
+export interface ToStateReferenceType extends NonHierarchicalReferences {}
+
+/**
+ *
+ * FromState Reference Type
+ *
+ * The FromState ReferenceType is a concrete ReferenceType and can be used directly. It is a
+ * subtype of NonHierarchicalReferences.
+ *
+ * The semantic of this ReferenceType is to point form a Transition to the starting State the
+ * Transition connects.
+ *
+ * The SourceNode of this ReferenceType shall be an Object of the ObjectType TransitionType or
+ * one of its subtypes. The TargetNode of this ReferenceType shall be an Object of the ObjectType
+ * StateType or one of its subtypes.
+ */
+export interface FromStateReferenceType extends NonHierarchicalReferences {}
+
+/**
+ * HasCause
+ * The HasCause ReferenceType is a concrete ReferenceType and can be used directly. It is a
+ * subtype of NonHierarchicalReferences.
+ *
+ * The semantic of this ReferenceType is to point form a Transition to something that causes the
+ * Transition. In this annex we only define Methods as Causes. However, the ReferenceType is
+ * not restricted to point to Methods. The referenced Methods can, but do not have to point to a
+ * Method of the StateMachineType. For example, it is allowed to point to a server-wide restart
+ * Method leading the state machine to go into its initial state.
+ *
+ * The SourceNode of this ReferenceType shall be an Object of the ObjectType TransitionType or
+ * one of its subtypes. The TargetNode can be of any NodeClass
+ */
+export interface HasCauseReferenceType extends NonHierarchicalReferences {
+    // inverseName: LocalizedTextT<"MayBeCausedBy">;
+}
+
+/**
+ * HasEffect ReferenceType
+ *
+ * The HasEffect ReferenceType is a concrete ReferenceType and can be used directly. It is a
+ * subtype of NonHierarchicalReferences.
+ * The semantic of this ReferenceType is to point form a Transition to something that will be
+ * effected when the Transition is triggered. In this annex we only define EventTypes as Effects.
+ *
+ * However, the ReferenceType is not restricted to point to EventTypes.
+ *
+ * The SourceNode of this ReferenceType shall be an Object of the ObjectType TransitionType or
+ * one of its subtypes. The TargetNode can be of any NodeClass.
+ */
+export interface HasEffectReferenceType extends NonHierarchicalReferences {}
+
+/**
+ * The HasSubStateMachine ReferenceType is a concrete ReferenceType and can be used
+ * directly. It is a subtype of NonHierarchicalReferences.
+ *
+ * The semantic of this ReferenceType is to point from a State to an instance of
+ * StateMachineType which represents the sub-states for the State.
+ *
+ * The SourceNode of this ReferenceType shall be an Object of the ObjectType StateType.
+ *
+ * The TargetNode shall be an Object of the ObjectType StateMachineType or one of its subtypes.
+ *
+ * Each Object can be the TargetNode of at most one HasSubStateMachine Reference.
+ *
+ * The SourceNode (the state) and the TargetNode (the SubStateMachine) shall belong to the
+ * same StateMachine, that is, both shall be referenced from the same Object of type
+ * StateMachineType using a HasComponent Reference or a subtype of HasComponent.
+ */
+export interface HasSubStateMachine extends NonHierarchicalReferences {}
+
+/**
+ * The TransitionEventType is a subtype of the BaseEventType. It can be used to generate an
+ * Event identifying that a Transition of a StateMachine was triggered.
+ *
+ * The TransitionEventType inherits the Properties of the BaseEventType.
+ *
+ * The inherited Property SourceNode shall be filled with the NodeId of the StateMachine instance
+ * where the Transition occurs. If the Transition occurs in a SubStateMachine, then the NodeId of
+ * the SubStateMachine has to be used. If the Transition occurs between a StateMachine and a
+ * SubStateMachine, then the NodeId of the StateMachine has to be used, independent of the
+ * direction of the Transition.
+ */
+export interface UATransitionEventType extends UATransitionEvent_Base, UAObjectType {}
+
+export type TransitionSelector = (transitions: UATransitionEx[], fromState: UAState, toState: UAState) => UATransitionEx | null;
+
+/**
+ * State Machine type
+ *
+ * StateMachines produce Events which may include the current state of a StateMachine. In that
+ * case Servers shall provide all the optional Properties of the StateVariableType in the Event,
+ * even if they are not provided on the instances in the address space.
+ */
+
+/**
+ * StateMachineType
+ *
+ * The StateMachineType is the base ObjectType for all StateMachineTypes. It defines a single
+ * Variable which represents the current state of the machine.
+ * An instance of this ObjectType shall generate an Event whenever a significant state change occurs.
+ * The Server decides which state changes are significant. Servers shall use the GeneratesEvent
+ * ReferenceType to indicate which Event(s) could be produced by the StateMachine.
+ *
+ * Subtypes may add Methods which affect the state of the machine. The Executable Attribute is
+ * used to indicate whether the Method is valid given the current state of the machine. The
+ * generation of AuditEvents for Methods is defined in Part 4. A StateMachine may not be active.
+ *
+ * In this case, the CurrentState and LastTransition Variables shall have a status equal to
+ * BadStateNotActive (see Table B.17).
+ *
+ * Subtypes may add components which are instances of StateMachineTypes. These components
+ * are considered to be sub-states of the StateMachine. SubStateMachines are only active when
+ * the parent machine is in an appropriate state.
+ * Events produced by SubStateMachines may be suppressed by the parent machine. In some
+ * cases, the parent machine will produce a single Event that reflects changes in multiple
+ * SubStateMachines
+ */
+
+export interface UAStateMachineHelper {
+    // extra stuff
+    readonly initialState: UAInitialState | null;
+    readonly states: UAState[];
+    readonly transitions: UATransitionEx[];
+    currentStateNode: UAState | null;
+
+    /**
+     * return all state nodes associated with this state machine
+     */
+    getStates(): UAState[];
+
+    /**
+     * return all state to state transition node associated with this state machine
+     */
+    getTransitions(): UATransitionEx[];
+
+    /**
+     * return the state Node by Name
+     * @param name
+     */
+    getStateByName(name: string): UAState | null;
+
+    /**
+     * returns true if there is a valid transition from currentStateNode to toStateNode
+     * @param toStateNode
+     */
+    isValidTransition(toStateNode: UAState | string, predicate?: TransitionSelector): boolean;
+
+    /**
+     * try to find the valid transition between fromState Node to toState Node
+     * @param fromStateNode
+     * @param toStateNode
+     */
+    findTransitionNode(fromStateNode: UAState, toStateNode: UAState, predicate?: TransitionSelector): UATransitionEx | null;
+
+    /**
+     * return the current state as string
+     */
+    getCurrentState(): string | null;
+
+    /**
+     * change the current state
+     *
+     * note:
+     *  - a transition from currentState to toState node must exists
+     * - a TransitionEventType event will be raised
+     * @param toStateNode
+     */
+    setState(toStateNode: UAState | string | null, predicate?: TransitionSelector): void;
+}
+
+export interface UAStateMachineEx extends UAObject, UAStateMachineHelper, UAStateMachine_Base {
+    _currentStateNode: UAState | null;
+}
+
+export interface UAStateMachineTypeHelper extends UAObjectType {
+    /**
+     * return all state nodes associated with this state machine
+     */
+    getStates(): UAState[];
+
+    /**
+     * return all state to state transition node associated with this state machine
+     */
+    getTransitions(): UATransitionEx[];
+
+    getStateByName(name: string): UAState | null;
+}
+
+export interface UAStateMachineType extends UAObjectType, UAStateMachineTypeHelper, UAStateMachine_Base {
+    instantiate(options: InstantiateObjectOptions): UAStateMachineEx;
+}
+export declare function promoteToStateMachineType(node: UAObjectType): UAStateMachineType;
+
+export declare function promoteToStateMachine(node: UAObject): UAStateMachineEx;

package/api/loader/decode_xml_extension_object.ts

@@ -0,0 +1,80 @@
+import type { IAddressSpace, UADataType } from "node-opcua-address-space-base";
+import { checkDebugFlag, make_debugLog, make_errorLog } from "node-opcua-debug";
+import type { ExtensionObject } from "node-opcua-extension-object";
+import type { NodeId } from "node-opcua-nodeid";
+import { NodeClass } from "node-opcua-types";
+import { Xml2Json } from "node-opcua-xml2json";
+
+import { type DefinitionMap2, makeXmlExtensionObjectReader, type TypeInfo } from "./make_xml_extension_object_parser.js";
+
+const doDebug = checkDebugFlag("decode_xml_extension_object");
+const debugLog = make_debugLog("decode_xml_extension_object");
+const _errorLog = make_errorLog("decode_xml_extension_object");
+
+function encodingNodeIdToDataTypeNode(addressSpace: IAddressSpace, encodingNodeId: NodeId): UADataType {
+    const encodingNode = addressSpace.findNode(encodingNodeId);
+
+    // c8 ignore next
+    if (!encodingNode) {
+        throw new Error(`findDataTypeNode:  Cannot find encoding NodeId${encodingNodeId.toString()}`);
+    }
+    const refs = encodingNode.findReferences("HasEncoding", false);
+    const dataTypes = refs.map((ref) => addressSpace.findNode(ref.nodeId)).filter((obj) => obj !== null);
+    // c8 ignore next
+    if (dataTypes.length !== 1) {
+        throw new Error("Internal Error");
+    }
+    const dataTypeNode = dataTypes[0] as UADataType;
+    return dataTypeNode;
+}
+
+export function makeDefinitionMap(addressSpace: IAddressSpace): DefinitionMap2 {
+    return {
+        findDefinition(dataTypeNodeId: NodeId): TypeInfo {
+            const dataTypeNode = addressSpace.findDataType(dataTypeNodeId);
+            if (!dataTypeNode) {
+                throw new Error(`findDefinition: cannot find dataType ${dataTypeNodeId.toString()}`);
+            }
+            if (dataTypeNode.nodeClass !== NodeClass.DataType) {
+                throw new Error("Expecting a DataType node here");
+            }
+            const name = dataTypeNode.browseName.name || "";
+            if (dataTypeNode.isStructure()) {
+                const definition = dataTypeNode.getStructureDefinition();
+                return { name, definition };
+            } else if (dataTypeNode.isEnumeration()) {
+                const definition = dataTypeNode.getEnumDefinition();
+                return { name, definition };
+            } else {
+                const dataType = dataTypeNode.getBasicDataType();
+                return { name, definition: { dataType } };
+            }
+        }
+    };
+}
+export function decodeXmlExtensionObject(
+    addressSpace: IAddressSpace,
+    encodingNodeId: NodeId,
+    xmlBody: string,
+    translateNodeId: (nodeId: string) => NodeId
+): ExtensionObject | null {
+    const definitionMap = makeDefinitionMap(addressSpace);
+
+    const dataType = encodingNodeIdToDataTypeNode(addressSpace, encodingNodeId);
+
+    //  const { name, definition } = definitionMap.findDefinition(dataType.nodeId);
+    // const hasOptionalFields = definition.fields!.some((field) => field.isOptional);
+
+    const reader = makeXmlExtensionObjectReader(dataType.nodeId, definitionMap, new Map(), translateNodeId);
+    const parser2 = new Xml2Json(reader);
+    const pojo = parser2.parseString(xmlBody);
+
+    const userDefinedExtensionObject = addressSpace.constructExtensionObject(dataType, pojo);
+
+    // c8 ignore next
+    if (doDebug) {
+        debugLog("userDefinedExtensionObject", userDefinedExtensionObject.toString());
+    }
+    //
+    return userDefinedExtensionObject;
+}

package/api/loader/ensure_datatype_extracted.ts

@@ -0,0 +1,122 @@
+import type { IAddressSpace, INamespace, UADataType } from "node-opcua-address-space-base";
+import {
+    convertStructureTypeSchemaToStructureDefinition,
+    DataTypeExtractStrategy,
+    ExtraDataTypeManager,
+    populateDataTypeManager
+} from "node-opcua-client-dynamic-extension-object";
+import { checkDebugFlag, make_debugLog } from "node-opcua-debug";
+import { DataTypeFactory, getStandardDataTypeFactory } from "node-opcua-factory";
+import type { CallbackT } from "node-opcua-status-code";
+import type { StructureField } from "node-opcua-types";
+import type { AddressSpacePrivate } from "../../impl/address_space_private.js";
+import {
+    constructNamespaceDependency,
+    constructNamespacePriorityTable
+} from "../../impl/nodeset_tools/construct_namespace_dependency.js";
+import { PseudoSession } from "../pseudo_session.js";
+
+const debugLog = make_debugLog("ensure_datatype_extracted");
+const doDebug = checkDebugFlag("ensure_datatype_extracted");
+
+interface UADataTypePriv extends UADataType {
+    $partialDefinition?: StructureField[];
+}
+
+interface AddressSpacePrivateWithDataTypeManager extends AddressSpacePrivate {
+    $$extraDataTypeManager?: ExtraDataTypeManager;
+}
+
+function fixDefinition103(addressSpace: IAddressSpace, namespaceArray: string[], dataTypeManager: ExtraDataTypeManager): void {
+    // fix datatype _getDefinition();
+    for (let namespaceIndex = 1; namespaceIndex < namespaceArray.length; namespaceIndex++) {
+        const df = dataTypeManager.getDataTypeFactory(namespaceIndex);
+        for (const s of df.getStructureIterator()) {
+            const dataType = addressSpace.findDataType(s.schema.dataTypeNodeId) as UADataTypePriv;
+            if (!s.constructor) {
+                continue;
+            }
+            if (!dataType) {
+                continue;
+            }
+            if (dataType.$partialDefinition?.length) {
+                continue;
+            }
+            // debugLog(" Exploration", dataType.browseName.toString());
+            if (!dataType.$partialDefinition || (dataType.$partialDefinition.length === 0 && s.schema.fields?.length > 0)) {
+                const sd = convertStructureTypeSchemaToStructureDefinition(s.schema);
+                dataType.$partialDefinition = sd.fields || undefined;
+            }
+        }
+    }
+}
+
+export async function ensureDatatypeExtracted(addressSpace: IAddressSpace): Promise<ExtraDataTypeManager> {
+    const addressSpacePriv = addressSpace as AddressSpacePrivateWithDataTypeManager;
+
+    if (!addressSpacePriv.$$extraDataTypeManager) {
+        const dataTypeManager = new ExtraDataTypeManager();
+
+        const namespaceArray = addressSpace.getNamespaceArray().map((n: INamespace) => n.namespaceUri);
+
+        doDebug && debugLog("INamespace Array = ", namespaceArray.join("\n                   "));
+
+        dataTypeManager.setNamespaceArray(namespaceArray);
+
+        addressSpacePriv.$$extraDataTypeManager = dataTypeManager;
+
+        const factories: DataTypeFactory[] = [getStandardDataTypeFactory()];
+
+        const priorityTable = constructNamespacePriorityTable(addressSpace).priorityTable;
+
+        for (let namespaceIndex = 1; namespaceIndex < namespaceArray.length; namespaceIndex++) {
+            const namespace = addressSpace.getNamespace(namespaceIndex);
+
+            if (doDebug) {
+                debugLog("namespaceIndex = ", namespaceIndex);
+                debugLog("namespace = ", namespace.namespaceUri);
+                debugLog("factories = ", factories.map((f) => f.targetNamespace).join(" "));
+                // find dependent namespaces
+                let dependency = constructNamespaceDependency(namespace);
+                // remove last element that is my namespace
+                dependency = dependency.filter((ns) => ns.index !== namespaceIndex);
+                const dependFactories = dependency.map((ns) => {
+                    const df = factories[ns.index];
+                    if (!df) {
+                        debugLog("namespaceIndex = ", namespaceIndex);
+                        debugLog("namespace = ", namespace.namespaceUri);
+                        debugLog("priorityTable", priorityTable);
+                        debugLog(dependency.map((ns) => `${ns.index} ${ns.namespaceUri}`).join("\n"));
+                        throw new Error(`Cannot find factory for namespace ${ns.namespaceUri}`);
+                    }
+                    return df;
+                });
+                //            getStandardDataTypeFactory()
+
+                const _dataTypeFactory1 = new DataTypeFactory(dependFactories);
+            }
+            const dataTypeFactory1 = new DataTypeFactory([...factories]);
+            dataTypeFactory1.targetNamespace = namespace.namespaceUri;
+
+            factories.push(dataTypeFactory1);
+
+            dataTypeManager.registerDataTypeFactory(namespaceIndex, dataTypeFactory1);
+        }
+        // inject simple types
+
+        // now extract structure and enumeration from old form
+        const session = new PseudoSession(addressSpace);
+
+        await populateDataTypeManager(session, dataTypeManager, DataTypeExtractStrategy.Auto);
+
+        // turn old <=103 structure to have valid DataTypeDefinition
+        fixDefinition103(addressSpace, namespaceArray, dataTypeManager);
+    }
+    return addressSpacePriv.$$extraDataTypeManager as ExtraDataTypeManager;
+}
+
+export function ensureDatatypeExtractedWithCallback(addressSpace: IAddressSpace, callback: CallbackT<ExtraDataTypeManager>): void {
+    ensureDatatypeExtracted(addressSpace)
+        .then((result: ExtraDataTypeManager) => callback(null, result))
+        .catch((err) => callback(err));
+}