node-opcua-factory 2.51.0

package/source/factories_basic_type.ts

@@ -0,0 +1,168 @@
+/**
+ * @module node-opcua-factory
+ */
+import { assert } from "node-opcua-assert";
+import { decodeLocaleId, encodeLocaleId, validateLocaleId } from "node-opcua-basic-types";
+import { BinaryStream, OutputBinaryStream } from "node-opcua-binary-stream";
+
+import { findSimpleType, hasBuiltInType, registerType } from "./factories_builtin_types";
+import { BasicTypeDefinition, BasicTypeDefinitionOptions } from "./types";
+
+export interface BasicTypeOptions {
+    name: string;
+    subType: string;
+    encode?: (value: any, stream: OutputBinaryStream) => void;
+    decode?: (stream: BinaryStream) => void;
+    validate?: (value: any) => boolean;
+    coerce?: (value: any) => any;
+    toJSON?: (value: any) => any;
+    random?: () => any;
+    defaultValue?: any;
+}
+/**
+ * register a Basic Type ,
+ * A basic type is new entity type that resolved to  a SubType
+ * @example:
+ *
+ *
+ *   registerBasicType({name:"Duration"   ,subType:"Double"});
+ *
+ * @method registerBasicType
+ * @param schema
+ * @param schema.name {String}
+ * @param schema.subType {String} mandatory, the basic type from which the new type derives.
+ *
+ * @param [schema.encode] {Function} optional,a specific encoder function to encode an instance of this type.
+ * @param schema.encode.value  {*}
+ * @param schema.encode.stream {BinaryStream}
+ *
+ * @param [schema.decode] optional,a specific decoder function that returns  the decode value out of the stream.
+ * @param [schema.decode.stream] {BinaryStream}
+ *
+ * @param [schema.coerce]  optional, a method to convert a value into the request type.
+ * @param schema.coerce.value {*} the value to coerce.
+ *
+ * @param [schema.random] optional, a method to construct a random object of this type
+ *
+ * @param [schema.toJSON]optional, a method to convert a value into the request type.
+ */
+export function registerBasicType(schema: BasicTypeOptions) {
+    const exists: boolean = hasBuiltInType(schema.name);
+
+    /* istanbul ignore next */
+    if (exists) {
+        // tslint:disable-next-line: no-console
+        console.log("registerBasicType:", schema);
+        throw new Error(`Basic Type ${schema.name} already registered`);
+    }
+
+    const name = schema.name;
+
+    const t: BasicTypeDefinition = findSimpleType(schema.subType);
+
+    /* istanbul ignore next */
+    if (!t) {
+        // tslint:disable-next-line:no-console
+        throw new Error(" cannot find subtype " + schema.subType);
+    }
+    assert(typeof t.decode === "function");
+
+    const encodeFunc = schema.encode || t.encode;
+    assert(typeof encodeFunc === "function");
+
+    const decodeFunc = schema.decode || t.decode;
+    assert(typeof decodeFunc === "function");
+
+    const defaultValue = schema.defaultValue === undefined ? t.defaultValue : schema.defaultValue;
+    // assert(typeof defaultValue === "function");
+
+    const coerceFunc = schema.coerce || t.coerce;
+    const toJSONFunc = schema.toJSON || t.toJSON;
+    const random = schema.random || defaultValue;
+
+    const newSchema = {
+        name,
+
+        subType: schema.subType,
+
+        coerce: coerceFunc,
+        decode: decodeFunc,
+        encode: encodeFunc,
+
+        random,
+
+        defaultValue,
+
+        toJSON: toJSONFunc
+    };
+    registerType(newSchema);
+}
+
+// =============================================================================================
+// Registering the Basic Type already defined int the OPC-UA Specification
+// =============================================================================================
+
+registerBasicType({ name: "Counter", subType: "UInt32" });
+// OPC Unified Architecture, part 3.0 $8.13 page 65
+registerBasicType({ name: "Duration", subType: "Double" });
+registerBasicType({ name: "UAString", subType: "String" });
+registerBasicType({ name: "UABoolean", subType: "Boolean" });
+registerBasicType({ name: "UtcTime", subType: "DateTime" });
+// already ? registerBasicType({name: "Int8",     subType: "SByte"});
+// already ? registerBasicType({name: "UInt8",    subType: "Byte"});
+registerBasicType({ name: "Char", subType: "Byte" });
+// xx registerBasicType({name:"XmlElement" ,subType:"String"  });
+// xx registerBasicType({ name: "Time", subType: "String" });
+// string in the form "en-US" or "de-DE" or "fr" etc...
+
+registerBasicType({
+    name: "LocaleId",
+    subType: "String",
+
+    defaultValue: null,
+
+    decode: decodeLocaleId,
+    encode: encodeLocaleId,
+    validate: validateLocaleId
+});
+
+registerBasicType({ name: "ContinuationPoint", subType: "ByteString" });
+registerBasicType({ name: "Image", subType: "ByteString" });
+registerBasicType({ name: "NodeIdType", subType: "NodeId" });
+
+registerBasicType({ name: "ImageBMP", subType: "Image" });
+registerBasicType({ name: "ImageGIF", subType: "Image" });
+registerBasicType({ name: "ImageJPG", subType: "Image" });
+registerBasicType({ name: "ImagePNG", subType: "Image" });
+registerBasicType({ name: "AudioDataType", subType: "ByteString" });
+registerBasicType({ name: "BitFieldMaskDataType", subType: "UInt64" });
+registerBasicType({ name: "DataSetFieldFlags", subType: "UInt16" });
+registerBasicType({ name: "DataSetFieldContentMask", subType: "UInt32" });
+registerBasicType({ name: "UadpNetworkMessageContentMask", subType: "UInt32" });
+registerBasicType({ name: "UadpDataSetMessageContentMask", subType: "UInt32" });
+registerBasicType({ name: "JsonNetworkMessageContentMask", subType: "UInt32" });
+registerBasicType({ name: "JsonDataSetMessageContentMask", subType: "UInt32" });
+registerBasicType({ name: "PermissionType", subType: "UInt32" });
+registerBasicType({ name: "AccessLevelType", subType: "Byte" });
+registerBasicType({ name: "AccessLevelExType", subType: "UInt32" });
+registerBasicType({ name: "EventNotifierType", subType: "Byte" });
+registerBasicType({ name: "AccessRestrictionType", subType: "UInt32" });
+registerBasicType({ name: "NormalizedString", subType: "String" });
+registerBasicType({ name: "DecimalString", subType: "String" });
+registerBasicType({ name: "DurationString", subType: "String" });
+registerBasicType({ name: "TimeString", subType: "String" });
+registerBasicType({ name: "DateString", subType: "String" });
+registerBasicType({ name: "Index", subType: "UInt32" });
+registerBasicType({ name: "VersionTime", subType: "UInt32" });
+registerBasicType({ name: "ApplicationInstanceCertificate", subType: "ByteString" });
+registerBasicType({ name: "AttributeWriteMask", subType: "UInt32" });
+registerBasicType({ name: "Date", subType: "DateTime" });
+
+// registerBasicType({ name: "Counter", subType: "UInt32" });
+// registerBasicType({ name: "IntegerId", subType: "UInt32" });
+// registerBasicType({ name: "UtcTime", subType: "DateTime" });
+// registerBasicType({ name: "Duration", subType: "Double" });
+// registerBasicType({ name: "LocaleId", subType: "String" });
+// registerBasicType({ name: "NumericRange", subType: "String" });
+// registerBasicType({ name: "Time", subType: "String" });
+// registerBasicType({ name: "SessionAuthenticationToken", subType: "NodeId" });

package/source/factories_builtin_types.ts

@@ -0,0 +1,381 @@
+/**
+ * @module node-opcua-factory
+ */
+import { assert } from "node-opcua-assert";
+import {
+    coerceBoolean,
+    coerceByte,
+    coerceByteString,
+    coerceDateTime,
+    coerceDouble,
+    coerceExpandedNodeId,
+    coerceFloat,
+    coerceInt16,
+    coerceInt32,
+    coerceInt64,
+    coerceInt8,
+    coerceNodeId,
+    coerceSByte,
+    coerceUInt16,
+    coerceUInt32,
+    coerceUInt64,
+    coerceUInt8,
+    decodeBoolean,
+    decodeByte,
+    decodeByteString,
+    decodeDateTime,
+    decodeDouble,
+    decodeExpandedNodeId,
+    decodeFloat,
+    decodeGuid,
+    decodeInt16,
+    decodeInt32,
+    decodeInt64,
+    decodeInt8,
+    decodeNodeId,
+    decodeSByte,
+    decodeString,
+    decodeUInt16,
+    decodeUInt32,
+    decodeUInt64,
+    decodeUInt8,
+    encodeBoolean,
+    encodeByte,
+    encodeByteString,
+    encodeDateTime,
+    encodeDouble,
+    encodeExpandedNodeId,
+    encodeFloat,
+    encodeGuid,
+    encodeInt16,
+    encodeInt32,
+    encodeInt64,
+    encodeInt8,
+    encodeNodeId,
+    encodeSByte,
+    encodeString,
+    encodeUInt16,
+    encodeUInt32,
+    encodeUInt64,
+    encodeUInt8
+} from "node-opcua-basic-types";
+import { BinaryStream, OutputBinaryStream } from "node-opcua-binary-stream";
+import { emptyGuid } from "node-opcua-guid";
+import { makeExpandedNodeId, makeNodeId } from "node-opcua-nodeid";
+import { coerceStatusCode, decodeStatusCode, encodeStatusCode, StatusCodes } from "node-opcua-status-code";
+import { BasicTypeDefinition, BasicTypeDefinitionOptions, FieldCategory, TypeSchemaBase } from "./types";
+
+// tslint:disable:no-empty
+// tslint:enable:no-unused-variable
+function defaultEncode(value: any, stream: OutputBinaryStream): void {}
+
+function defaultDecode(stream: BinaryStream): any {
+    return null;
+}
+
+export class BasicTypeSchema extends TypeSchemaBase implements BasicTypeDefinition {
+    public subType: string;
+
+    public encode: (value: any, stream: OutputBinaryStream) => void;
+    public decode: (stream: BinaryStream) => any;
+
+    constructor(options: BasicTypeDefinitionOptions) {
+        super(options);
+        this.subType = options.subType;
+        this.encode = options.encode || defaultEncode;
+        this.decode = options.decode || defaultDecode;
+    }
+}
+
+export const minDate = new Date(Date.UTC(1601, 0, 1, 0, 0, 0));
+
+function defaultGuidValue(): any {
+    return Buffer.alloc(0);
+}
+
+function toJSONGuid(value: any): any {
+    if (typeof value === "string") {
+        return value;
+    }
+    assert(value instanceof Buffer);
+    return value.toString("base64");
+}
+
+function encodeAny(value: any, stream: OutputBinaryStream) {
+    assert(false, "type 'Any' cannot be encoded");
+}
+
+function decodeAny(stream: BinaryStream) {
+    assert(false, "type 'Any' cannot be decoded");
+}
+
+function encodeNull(value: any, stream: OutputBinaryStream): void {}
+
+function decodeNull(stream: BinaryStream): any {
+    return null;
+}
+
+// there are 4 types of DataTypes in opcua:
+//   Built-In DataType
+//   Simple DataType
+//   Complex DataType
+//   Enumeration
+
+const defaultXmlElement = "";
+
+interface T {
+    subType?: any;
+    name: string;
+    encode: (value: any, stream: OutputBinaryStream) => void;
+    decode: (stream: BinaryStream) => any;
+    coerce?: any;
+    defaultValue?: any;
+    toJSON?: any;
+}
+// Built-In Type
+const _defaultType: any[] = [
+    // Built-in DataTypes ( see OPCUA Part III v1.02 - $5.8.2 )
+    {
+        name: "Null",
+
+        decode: decodeNull,
+        encode: encodeNull,
+
+        defaultValue: null
+    },
+    {
+        name: "Any",
+
+        decode: decodeAny,
+        encode: encodeAny
+    },
+    {
+        name: "Boolean",
+
+        decode: decodeBoolean,
+        encode: encodeBoolean,
+
+        coerce: coerceBoolean,
+        defaultValue: false
+    },
+    { name: "Int8", encode: encodeInt8, decode: decodeInt8, defaultValue: 0, coerce: coerceInt8 },
+    { name: "UInt8", encode: encodeUInt8, decode: decodeUInt8, defaultValue: 0, coerce: coerceUInt8 },
+    { name: "SByte", encode: encodeSByte, decode: decodeSByte, defaultValue: 0, coerce: coerceSByte },
+    { name: "Byte", encode: encodeByte, decode: decodeByte, defaultValue: 0, coerce: coerceByte },
+    { name: "Int16", encode: encodeInt16, decode: decodeInt16, defaultValue: 0, coerce: coerceInt16 },
+    { name: "UInt16", encode: encodeUInt16, decode: decodeUInt16, defaultValue: 0, coerce: coerceUInt16 },
+    { name: "Int32", encode: encodeInt32, decode: decodeInt32, defaultValue: 0, coerce: coerceInt32 },
+    { name: "UInt32", encode: encodeUInt32, decode: decodeUInt32, defaultValue: 0, coerce: coerceUInt32 },
+    {
+        name: "Int64",
+
+        decode: decodeInt64,
+        encode: encodeInt64,
+
+        coerce: coerceInt64,
+        defaultValue: coerceInt64(0)
+    },
+    {
+        name: "UInt64",
+
+        decode: decodeUInt64,
+        encode: encodeUInt64,
+
+        coerce: coerceUInt64,
+        defaultValue: coerceUInt64(0)
+    },
+    {
+        name: "Float",
+
+        decode: decodeFloat,
+        encode: encodeFloat,
+
+        coerce: coerceFloat,
+        defaultValue: 0.0
+    },
+    {
+        name: "Double",
+
+        decode: decodeDouble,
+        encode: encodeDouble,
+
+        coerce: coerceDouble,
+        defaultValue: 0.0
+    },
+    {
+        name: "String",
+
+        decode: decodeString,
+        encode: encodeString,
+
+        defaultValue: ""
+    },
+    // OPC Unified Architecture, part 3.0 $8.26 page 67
+    {
+        name: "DateTime",
+
+        decode: decodeDateTime,
+        encode: encodeDateTime,
+
+        coerce: coerceDateTime,
+        defaultValue: exports.minDate
+    },
+    {
+        name: "Guid",
+
+        decode: decodeGuid,
+        encode: encodeGuid,
+
+        defaultValue: emptyGuid
+    },
+
+    {
+        name: "ByteString",
+
+        decode: decodeByteString,
+        encode: encodeByteString,
+
+        coerce: coerceByteString,
+        defaultValue: null,
+        toJSON: toJSONGuid
+    },
+    {
+        name: "XmlElement",
+
+        decode: decodeString,
+        encode: encodeString,
+
+        defaultValue: defaultXmlElement
+    },
+
+    // see OPCUA Part 3 - V1.02 $8.2.1
+    {
+        name: "NodeId",
+
+        decode: decodeNodeId,
+        encode: encodeNodeId,
+
+        coerce: coerceNodeId,
+        defaultValue: makeNodeId
+    },
+    {
+        name: "ExpandedNodeId",
+
+        decode: decodeExpandedNodeId,
+        encode: encodeExpandedNodeId,
+
+        coerce: coerceExpandedNodeId,
+        defaultValue: makeExpandedNodeId
+    },
+
+    // ----------------------------------------------------------------------------------------
+    // Simple  DataTypes
+    // ( see OPCUA Part III v1.02 - $5.8.2 )
+    // Simple DataTypes are subtypes of the Built-in DataTypes. They are handled on the wire like the
+    // Built-in   DataType, i.e. they cannot be distinguished on the wire from their  Built-in supertypes.
+    // Since they are handled like  Built-in   DataTypes  regarding the encoding they cannot have encodings
+    // defined  in the  AddressSpace.  Clients  can read the  DataType  Attribute  of a  Variable  or  VariableType  to
+    // identify the  Simple  DataType  of the  Value  Attribute. An example of a  Simple  DataType  is  Duration. It
+    // is handled on the wire as a  Double   but the Client can read the  DataType  Attribute  and thus interpret
+    // the value as defined by  Duration
+    //
+
+    // OPC Unified Architecture, part 4.0 $7.13
+    // IntegerID: This primitive data type is an UInt32 that is used as an identifier, such as a handle. All values,
+    // except for 0, are valid.
+    {
+        name: "IntegerId",
+
+        decode: decodeUInt32,
+        encode: encodeUInt32,
+
+        defaultValue: 0xffffffff
+    },
+
+    // The StatusCode is a 32-bit unsigned integer. The top 16 bits represent the numeric value of the
+    // code that shall be used for detecting specific errors or conditions. The bottom 16 bits are bit flags
+    // that contain additional information but do not affect the meaning of the StatusCode.
+    // 7.33 Part 4 - P 143
+    {
+        name: "StatusCode",
+
+        decode: decodeStatusCode,
+        encode: encodeStatusCode,
+
+        coerce: coerceStatusCode,
+        defaultValue: StatusCodes.Good
+    }
+];
+
+/**
+ * @method registerType
+ * @param schema {TypeSchemaBase}
+ */
+export function registerType(schema: BasicTypeDefinitionOptions): void {
+    assert(typeof schema.name === "string");
+    if (typeof schema.encode !== "function") {
+        throw new Error("schema " + schema.name + " has no encode function");
+    }
+    if (typeof schema.decode !== "function") {
+        throw new Error("schema " + schema.name + " has no decode function");
+    }
+
+    schema.category = FieldCategory.basic;
+
+    const definition = new BasicTypeSchema(schema);
+    _defaultTypeMap.set(schema.name, definition);
+}
+
+export const registerBuiltInType = registerType;
+
+export function unregisterType(typeName: string): void {
+    _defaultTypeMap.delete(typeName);
+}
+
+/**
+ * @method findSimpleType
+ * @param name
+ * @return {TypeSchemaBase|null}
+ */
+export function findSimpleType(name: string): BasicTypeDefinition {
+    const typeSchema = _defaultTypeMap.get(name);
+    if (!typeSchema) {
+        throw new Error("Cannot find schema for simple type " + name);
+    }
+    assert(typeSchema instanceof TypeSchemaBase);
+    return typeSchema as BasicTypeDefinition;
+}
+
+// populate the default type map
+const _defaultTypeMap: Map<string, BasicTypeSchema> = new Map<string, BasicTypeSchema>();
+_defaultType.forEach(registerType);
+
+export function hasBuiltInType(name: string): boolean {
+    return _defaultTypeMap.has(name);
+}
+
+export function getBuildInType(name: string): BasicTypeDefinition {
+    return _defaultTypeMap.get(name) as BasicTypeDefinition;
+}
+
+/**
+ * @method findBuiltInType
+ * find the Builtin Type that this
+ * @param dataTypeName
+ * @return {*}
+ */
+export function findBuiltInType(dataTypeName: string): BasicTypeDefinition {
+    assert(typeof dataTypeName === "string", "findBuiltInType : expecting a string " + dataTypeName);
+    const t = _defaultTypeMap.get(dataTypeName) as BasicTypeDefinition;
+    if (!t) {
+        throw new Error("datatype " + dataTypeName + " must be registered");
+    }
+    if (t.subType && t.subType !== t.name /* avoid infinite recursion */) {
+        return findBuiltInType(t.subType);
+    }
+    return t;
+}
+
+export function getTypeMap() {
+    return _defaultTypeMap;
+}

package/source/factories_builtin_types_special.ts

@@ -0,0 +1,55 @@
+/**
+ * @module node-opcua-factory
+ */
+
+import { assert } from "node-opcua-assert";
+import { BinaryStream, OutputBinaryStream } from "node-opcua-binary-stream";
+
+import { registerType } from "./factories_builtin_types";
+import { ConstructorFunc } from "./constructor_type";
+
+function _self_encode(constructor: any) {
+    assert(typeof constructor === "function");
+    return (value: any, stream: OutputBinaryStream) => {
+        if (!value || !value.encode) {
+            value = new constructor(value);
+        }
+        value.encode(stream);
+    };
+}
+
+function _self_decode(constructor: any) {
+    assert(typeof constructor === "function");
+    return (stream: BinaryStream) => {
+        const value = new constructor();
+        value.decode(stream);
+        return value;
+    };
+}
+
+function _self_coerce(constructor: any) {
+    assert(typeof constructor === "function");
+    return (value: any) => {
+        const obj = new constructor(value);
+        return obj;
+    };
+}
+
+export function registerSpecialVariantEncoder(constructor: ConstructorFunc) {
+    assert(typeof constructor === "function");
+
+    const name = constructor.prototype.schema.name;
+
+    registerType({
+        name,
+        subType: name,
+
+        encode: _self_encode(constructor),
+
+        decode: _self_decode(constructor),
+
+        coerce: _self_coerce(constructor),
+
+        defaultValue: () => new constructor()
+    });
+}

package/source/factories_enumerations.ts

@@ -0,0 +1,97 @@
+/**
+ * @module node-opcua-factory
+ */
+import { assert } from "node-opcua-assert";
+
+import { BinaryStream, OutputBinaryStream } from "node-opcua-binary-stream";
+import { Enum, EnumItem } from "node-opcua-enum";
+import { EnumerationDefinition, TypeSchemaBase, TypeSchemaConstructorOptions } from "./types";
+
+function _encode_enumeration(typedEnum: Enum, value: number, stream: OutputBinaryStream): void {
+    assert(typeof value === "number", "Expecting a number here");
+    assert(typedEnum.get(value) !== undefined, "expecting a valid value");
+    stream.writeInteger(value);
+}
+
+function _decode_enumeration(typedEnum: Enum, stream: BinaryStream): number {
+    const value = stream.readInteger();
+    const e = (typedEnum.get(value) as any) as string;
+    // istanbul ignore next
+    if (!e) {
+        throw new Error("cannot  coerce value=" + value + " to " + typedEnum.constructor.name);
+    }
+    return value;
+}
+
+export interface EnumerationDefinitionOptions extends TypeSchemaConstructorOptions {
+    enumValues: any;
+    typedEnum?: any;
+    lengthInBits?: number;
+
+    // specialized methods
+    defaultValue?: EnumItem;
+    encode?: (value: EnumItem, stream: OutputBinaryStream) => void;
+    decode?: (stream: BinaryStream) => EnumItem;
+}
+
+export class EnumerationDefinitionSchema extends TypeSchemaBase implements EnumerationDefinition {
+    public enumValues: any;
+    public typedEnum: Enum;
+    public lengthInBits: number;
+    // xx encode: (value: EnumItem, stream: OutputBinaryStream) => void;
+    // xx decode: (stream: BinaryStream) => EnumItem;
+
+    constructor(options: EnumerationDefinitionOptions) {
+        super(options);
+        // create a new Enum
+        const typedEnum = new Enum(options.enumValues);
+        options.typedEnum = typedEnum;
+
+        assert(!options.encode || typeof options.encode === "function");
+        assert(!options.decode || typeof options.decode === "function");
+        this.encode = options.encode || _encode_enumeration.bind(null, typedEnum);
+        this.decode = options.decode || _decode_enumeration.bind(null, typedEnum);
+
+        this.typedEnum = options.typedEnum;
+        this.defaultValue = this.typedEnum.getDefaultValue().value;
+        this.lengthInBits = options.lengthInBits || 32;
+    }
+}
+
+const _enumerations: Map<string, EnumerationDefinitionSchema> = new Map<string, EnumerationDefinitionSchema>();
+
+/**
+ * @method registerEnumeration
+ * @param options
+ * @param options.name {string}
+ * @param options.enumValues [{key:Name, value:values}]
+ * @param options.encode
+ * @param options.decode
+ * @param options.typedEnum
+ * @param options.defaultValue
+ * @return {Enum}
+ */
+export function registerEnumeration(options: EnumerationDefinitionOptions): Enum {
+    assert(Object.prototype.hasOwnProperty.call(options,"name"));
+    assert(Object.prototype.hasOwnProperty.call(options,"enumValues"));
+    const name = options.name;
+
+    if (_enumerations.hasOwnProperty(name)) {
+        throw new Error("factories.registerEnumeration : Enumeration " + options.name + " has been already inserted");
+    }
+    const enumerationDefinition = new EnumerationDefinitionSchema(options);
+    _enumerations.set(name, enumerationDefinition);
+
+    return enumerationDefinition.typedEnum;
+}
+
+export function hasEnumeration(enumerationName: string): boolean {
+    return _enumerations.has(enumerationName);
+}
+
+export function getEnumeration(enumerationName: string): EnumerationDefinitionSchema {
+    if (!exports.hasEnumeration(enumerationName)) {
+        throw new Error("Cannot find enumeration with type " + enumerationName);
+    }
+    return _enumerations.get(enumerationName) as EnumerationDefinitionSchema;
+}