node-opcua-address-space 2.181.1 → 2.182.0

package/api/loader/nodeset_image_codec.ts

@@ -13,15 +13,21 @@
  * - QualifiedName: `[namespaceIndex, name]`; LocalizedText: `{ locale, text }`
  * - DateTime: ISO-8601 string, or `{ iso, picoseconds }` when sub-millisecond precision is carried
  * - ByteString: base64; Guid, String, XmlElement: the string
- * - Int64 and UInt64: `[high, low]`; Float and Double: JSON numbers, `NaN`, `Infinity` and
+ * - Int64 and UInt64: a decimal string; Float and Double: JSON numbers, `NaN`, `Infinity` and
  *   `-Infinity` as strings; StatusCode: the numeric code
  * - the extension objects the XML reader decodes itself (Argument, EUInformation, Range,
  *   EnumValueType): `{ "$class": name, ...fields }` with the rules above; every other extension
  *   object is the XML fragment the reader captured: `{ "$xml": [typeId, body] }`
  *
  * A value is `{ dataType, arrayType?, dimensions?, value }`; `arrayType` is omitted for a scalar.
+ *
+ * Every key whose value is the one it would take anyway is left out; {@link NODE_DEFAULTS} is the
+ * table, and a reader that does not find a key applies the default from it. gzip already codes a
+ * key repeated verbatim in a couple of bits, so this is worth far less compressed than it looks
+ * on the raw text -- except for `displayName`, which repeats the browse name on 97% of the nodes
+ * of the published nodesets and is the one omission that carries real entropy away.
  */
-import { coerceInt64, coerceUInt64, type Int64, type UInt64 } from "node-opcua-basic-types";
+import type { Int64, UInt64 } from "node-opcua-basic-types";
 import { Range } from "node-opcua-data-access";
 import {
     coerceLocalizedText,
@@ -47,6 +53,7 @@ import {
     type NodesetReferenceRecord,
     XmlExtensionObjectFragment
 } from "./nodeset_record.js";
+import { int64ToDecimalString } from "./nodeset_xml_primitives.js";
 
 /**
  * a NodeId: the number alone when numeric in namespace 0 (nearly every id of a nodeset),
@@ -146,39 +153,113 @@ function decodeFloat(json: Json): number {
     return json as number;
 }
 
+// #region defaults
+/**
+ * what a key of a node record means when the image leaves it out: the value the reader would have
+ * produced anyway. A writer omits a key whose encoded value is its default here; a reader that
+ * does not find a key applies the default. The XML reader synthesizes every one of these from an
+ * absent attribute (see `nodeset_xml_producer`) and the address space export already omitted most
+ * of them, so this table is also what makes the two record producers agree.
+ *
+ * `displayName` is not in the table: its default is the node's own browse name rather than a
+ * constant, and it is the only key a reader must put back rather than infer, since a consumer
+ * reads it directly. It is also the only omission worth much once gzipped -- a constant repeated
+ * verbatim on every line costs a couple of bits, a browse name repeated does not.
+ */
+const NODE_DEFAULTS: Readonly<Record<string, unknown>> = {
+    valueRank: -1,
+    arrayDimensions: null,
+    minimumSamplingInterval: 0,
+    historizing: false,
+    isAbstract: false,
+    symmetric: false,
+    containsNoLoops: false,
+    hasNoPermissions: false,
+    eventNotifier: 0,
+    parentNodeId: null,
+    dataType: null,
+    methodDeclarationId: null
+};
+
+/** the same, for one field of a DataType definition; an absent DataType attribute is BaseDataType */
+const FIELD_DEFAULT_VALUE_RANK = -1;
+const FIELD_DEFAULT_ALLOW_SUBTYPES = false;
+const FIELD_DEFAULT_DATA_TYPE: JsonNodeId = 24; // i=24, BaseDataType
+
+/** an absent ValueRank on an Argument, as on any other node */
+const ARGUMENT_DEFAULT_VALUE_RANK = -1;
+
+/** drop from `out` every key whose value is the one a reader would assume anyway */
+function omitDefaults(out: Record<string, unknown>): void {
+    for (const [key, fallback] of Object.entries(NODE_DEFAULTS)) {
+        if (key in out && out[key] === fallback) {
+            delete out[key];
+        }
+    }
+}
+
+/** whether a localized text carries nothing: the reader's `{}` for an absent Description */
+const isEmptyText = (text: JsonLocalizedText | null | undefined): boolean =>
+    text === null || text === undefined || (text.locale === undefined && text.text === undefined);
+
+// #endregion
+
+// #region 64-bit integers
+//
+// on the wire a 64-bit integer is a decimal string, the spelling Part 6 uses and the only one that
+// says what it means. In memory it stays node-opcua's `[high, low]` pair, whose halves are
+// unsigned: Int64 -1 and UInt64 18446744073709551615 are the *same* pair, so the pair cannot be
+// read without knowing the signedness from somewhere else, and Int64 min has two equally defensible
+// spellings ([2147483648,0] and [-2147483648,0]) which would give one value two documents.
+
+const TWO_64 = 1n << 64n;
+
+const encodeInt64 = int64ToDecimalString;
+
+function decodeInt64(json: Json): Int64 {
+    let unsigned = BigInt(json as string);
+    if (unsigned < 0n) unsigned += TWO_64;
+    return [Number(unsigned >> 32n), Number(unsigned & 0xffffffffn)] as Int64;
+}
+
+// #endregion
+
 function encodeExtensionObject(value: unknown): Json {
     if (value instanceof XmlExtensionObjectFragment) {
         return { $xml: [encodeNodeId(value.typeId), value.bodyXML] };
     }
     if (value instanceof Argument) {
-        return {
-            $class: "Argument",
-            name: value.name,
-            dataType: encodeNodeId(value.dataType),
-            valueRank: value.valueRank,
-            arrayDimensions: value.arrayDimensions,
-            description: encodeLocalizedText(value.description)
-        };
+        const out: Record<string, Json> = { $class: "Argument", name: value.name, dataType: encodeNodeId(value.dataType) };
+        if (value.valueRank !== ARGUMENT_DEFAULT_VALUE_RANK) out.valueRank = value.valueRank;
+        // an empty arrayDimensions is what a scalar argument carries and is left out; a `null` one
+        // is not the same thing to the reader that put it there, and is written
+        if (value.arrayDimensions === null || value.arrayDimensions.length > 0) out.arrayDimensions = value.arrayDimensions;
+        const description = encodeLocalizedText(value.description);
+        if (!isEmptyText(description)) out.description = description;
+        return out;
     }
     if (value instanceof EUInformation) {
-        return {
+        const out: Record<string, Json> = {
             $class: "EUInformation",
             namespaceUri: value.namespaceUri,
-            unitId: value.unitId,
-            displayName: encodeLocalizedText(value.displayName),
-            description: encodeLocalizedText(value.description)
+            unitId: value.unitId
         };
+        const displayName = encodeLocalizedText(value.displayName);
+        const description = encodeLocalizedText(value.description);
+        if (!isEmptyText(displayName)) out.displayName = displayName;
+        if (!isEmptyText(description)) out.description = description;
+        return out;
     }
     if (value instanceof Range) {
         return { $class: "Range", low: encodeFloat(value.low), high: encodeFloat(value.high) };
     }
     if (value instanceof EnumValueType) {
-        return {
-            $class: "EnumValueType",
-            value: value.value,
-            displayName: encodeLocalizedText(value.displayName),
-            description: encodeLocalizedText(value.description)
-        };
+        const out: Record<string, Json> = { $class: "EnumValueType", value: encodeInt64(value.value, true) };
+        const displayName = encodeLocalizedText(value.displayName);
+        const description = encodeLocalizedText(value.description);
+        if (!isEmptyText(displayName)) out.displayName = displayName;
+        if (!isEmptyText(description)) out.description = description;
+        return out;
     }
     const name = (value as ExtensionObject).constructor?.name ?? typeof value;
     throw new NodesetImageError(
@@ -197,8 +278,10 @@ function decodeExtensionObject(json: Json): ExtensionObject | XmlExtensionObject
             const argument = new Argument({});
             argument.name = j.name as string;
             argument.dataType = decodeNodeId(j.dataType);
-            argument.valueRank = j.valueRank as number;
-            argument.arrayDimensions = (j.arrayDimensions as number[] | null) ?? null;
+            argument.valueRank = (j.valueRank as number | undefined) ?? ARGUMENT_DEFAULT_VALUE_RANK;
+            // an absent arrayDimensions is the empty one the reader leaves on a scalar argument;
+            // an explicit `null` is the one the address space export writes, and is kept apart
+            argument.arrayDimensions = j.arrayDimensions === undefined ? [] : (j.arrayDimensions as number[] | null);
             argument.description = decodeLocalizedText(j.description);
             return argument;
         }
@@ -217,7 +300,7 @@ function decodeExtensionObject(json: Json): ExtensionObject | XmlExtensionObject
         }
         case "EnumValueType":
             return new EnumValueType({
-                value: coerceInt64(j.value as Int64),
+                value: decodeInt64(j.value as Json),
                 displayName: decodeLocalizedText(j.displayName),
                 description: decodeLocalizedText(j.description)
             });
@@ -258,8 +341,12 @@ function encodeElement(dataType: DataType, value: unknown): Json {
         case DataType.DataValue:
         case DataType.DiagnosticInfo:
             throw new NodesetImageError(`an image cannot carry a ${DataType[dataType]} value`);
+        case DataType.Int64:
+            return encodeInt64(value as Int64, true);
+        case DataType.UInt64:
+            return encodeInt64(value as UInt64, false);
         default:
-            // Boolean, the integer families (Int64 and UInt64 are already [high, low]), String, Guid, XmlElement
+            // Boolean, the 32-bit-and-under integer families, String, Guid, XmlElement
             return value;
     }
 }
@@ -293,9 +380,8 @@ function decodeElement(dataType: DataType, json: Json): unknown {
         case DataType.Variant:
             return new Variant(decodeValue(json as JsonValue));
         case DataType.Int64:
-            return coerceInt64(json as Int64);
         case DataType.UInt64:
-            return coerceUInt64(json as UInt64);
+            return decodeInt64(json);
         default:
             return json;
     }
@@ -362,6 +448,7 @@ export interface NodesetImageHeader {
         accessRestrictions?: string;
     }>;
     aliases: Record<string, JsonNodeId>;
+    extensions?: string[];
 }
 
 export interface NodesetImageTrailer {
@@ -409,6 +496,7 @@ export function encodeHeader(record: NodesetHeaderRecord, options: EncodeHeaderO
         }),
         aliases
     };
+    if (record.extensions?.length) header.extensions = record.extensions;
     if (options.sourceLength !== undefined) header.sourceLength = options.sourceLength;
     return header;
 }
@@ -439,7 +527,9 @@ export function decodeHeader(json: NodesetImageHeader): NodesetHeaderRecord {
         if (m.accessRestrictions !== undefined) model.accessRestrictions = m.accessRestrictions;
         return model;
     });
-    return { kind: "header", namespaceUris: json.namespaceUris || [], models, aliases };
+    const header: NodesetHeaderRecord = { kind: "header", namespaceUris: json.namespaceUris || [], models, aliases };
+    if (json.extensions?.length) header.extensions = json.extensions;
+    return header;
 }
 
 interface JsonField extends Omit<NodesetDefinitionField, "dataType"> {
@@ -451,6 +541,8 @@ export interface NodesetImageNode {
     browseName: JsonQualifiedName;
     displayName?: string;
     description?: string;
+    category?: string[];
+    documentation?: string;
     references: JsonReference[];
     releaseStatus?: "Draft" | "Deprecated";
     symbolicName?: string;
@@ -472,12 +564,14 @@ export interface NodesetImageNode {
     userAccessLevel?: string;
     value?: JsonValue;
     methodDeclarationId?: JsonNodeId | null;
-    definition?: { name?: string; isUnion?: boolean; fields: JsonField[] };
+    definition?: { name?: string; isUnion?: boolean; isOptionSet?: boolean; fields: JsonField[] };
 }
 
 const OPTIONAL_PLAIN: Array<keyof NodesetNodeRecord & keyof NodesetImageNode> = [
     "displayName",
     "description",
+    "category",
+    "documentation",
     "releaseStatus",
     "symbolicName",
     "accessRestrictions",
@@ -521,15 +615,37 @@ export function encodeNode(record: NodesetNodeRecord): NodesetImageNode {
     if (record.methodDeclarationId !== undefined) out.methodDeclarationId = encodeNodeIdOrNull(record.methodDeclarationId);
     if (record.value !== undefined) out.value = encodeValue(record.value);
     if (record.definition) {
-        out.definition = {
-            fields: record.definition.fields.map((f) => ({ ...f, dataType: encodeNodeIdOrNull(f.dataType) }))
-        };
+        out.definition = { fields: record.definition.fields.map(encodeDefinitionField) };
         if (record.definition.name !== undefined) out.definition.name = record.definition.name;
         if (record.definition.isUnion !== undefined) out.definition.isUnion = record.definition.isUnion;
+        if (record.definition.isOptionSet !== undefined) out.definition.isOptionSet = record.definition.isOptionSet;
+    }
+    if (out.displayName !== undefined && out.displayName === out.browseName[1]) {
+        // the browse name over again on nearly every node of a published nodeset; a reader puts it back
+        delete out.displayName;
     }
+    omitDefaults(out as unknown as Record<string, unknown>);
+    return out;
+}
+
+function encodeDefinitionField(field: NodesetDefinitionField): JsonField {
+    const out = { ...field, dataType: encodeNodeIdOrNull(field.dataType) } as JsonField & Record<string, unknown>;
+    if (out.valueRank === FIELD_DEFAULT_VALUE_RANK) delete out.valueRank;
+    if (out.allowSubTypes === FIELD_DEFAULT_ALLOW_SUBTYPES) delete out.allowSubTypes;
+    if (out.dataType === FIELD_DEFAULT_DATA_TYPE) delete out.dataType;
     return out;
 }
 
+function decodeDefinitionField(json: JsonField): NodesetDefinitionField {
+    const field = {
+        ...json,
+        valueRank: json.valueRank ?? FIELD_DEFAULT_VALUE_RANK,
+        allowSubTypes: json.allowSubTypes ?? FIELD_DEFAULT_ALLOW_SUBTYPES,
+        dataType: decodeNodeIdOrNull(json.dataType ?? FIELD_DEFAULT_DATA_TYPE)
+    };
+    return field as unknown as NodesetDefinitionField;
+}
+
 export function decodeNode(json: NodesetImageNode): NodesetNodeRecord {
     if (typeof json.nodeClass !== "number" || !(json.nodeClass in NodeClass)) {
         throw new NodesetImageError(`not a node record: ${JSON.stringify(json).slice(0, 80)}`);
@@ -554,6 +670,10 @@ export function decodeNode(json: NodesetImageNode): NodesetNodeRecord {
             (record as unknown as Record<string, unknown>)[key] = v;
         }
     }
+    // an absent displayName is the browse name: what the writer left out because it was the same
+    if (record.displayName === undefined) {
+        record.displayName = record.browseName.name ?? "";
+    }
     if (json.rolePermissions) {
         record.rolePermissions = json.rolePermissions.map((p) => ({ roleId: decodeNodeId(p.roleId), permissions: p.permissions }));
     }
@@ -563,12 +683,11 @@ export function decodeNode(json: NodesetImageNode): NodesetNodeRecord {
     if (json.value !== undefined) record.value = decodeValue(json.value);
     if (json.definition) {
         const definition: NodesetDataTypeDefinitionRecord = {
-            fields: json.definition.fields.map(
-                (f) => ({ ...f, dataType: decodeNodeIdOrNull(f.dataType) }) as NodesetDefinitionField
-            )
+            fields: json.definition.fields.map(decodeDefinitionField)
         };
         if (json.definition.name !== undefined) definition.name = json.definition.name;
         if (json.definition.isUnion !== undefined) definition.isUnion = json.definition.isUnion;
+        if (json.definition.isOptionSet !== undefined) definition.isOptionSet = json.definition.isOptionSet;
         record.definition = definition;
     }
     return record;

package/api/loader/nodeset_record.ts

@@ -19,8 +19,17 @@ import type { NodeId } from "node-opcua-nodeid";
 import type { VariantOptions } from "node-opcua-variant";
 import type { EnumFieldOptions, StructureFieldOptions } from "node-opcua-xml2json";
 
-/** bumped whenever the record shape changes; the precompiled image carries it */
-export const NODESET_RECORD_SCHEMA = 2;
+/**
+ * bumped whenever the record shape changes; the precompiled image carries it, and it is part of
+ * the key an image is cached under, so a bump invalidates every stored image.
+ *
+ * It is bumped for a change in what the records *contain* as well as for a change in their shape:
+ * when the reader learns to read something it used to drop -- a DateTime value, say -- every image
+ * built before is still valid schema-N and still parses, but it is less faithful than the file it
+ * was built from, and nothing else would ever invalidate it. The source digest cannot: the source
+ * did not change. This number is the only lever.
+ */
+export const NODESET_RECORD_SCHEMA = 3;
 
 export interface NodesetModelRecord {
     modelUri: string;
@@ -38,6 +47,12 @@ export interface NodesetHeaderRecord {
     models: NodesetModelRecord[];
     /** alias name to the id it stands for, file-local; no record refers to an alias by name */
     aliases: Record<string, NodeId>;
+    /**
+     * the `<Extension>` elements of the document's own `<Extensions>`, each as the XML it is.
+     * Their content is foreign to this schema by design -- a tool stamps whatever it likes there,
+     * such as UaModeler's `ModelInfo` -- so there is nothing to model and only the bytes to keep.
+     */
+    extensions?: string[];
 }
 
 export interface NodesetReferenceRecord {
@@ -64,6 +79,11 @@ export type NodesetDefinitionField = Omit<StructureFieldOptions, "dataType"> & E
 export interface NodesetDataTypeDefinitionRecord {
     name?: string;
     isUnion?: boolean;
+    /**
+     * the DataType is a bit mask: its fields are bit positions, not enumeration values. An
+     * OptionSet whose flag is lost is indistinguishable from an ordinary enumeration.
+     */
+    isOptionSet?: boolean;
     fields: NodesetDefinitionField[];
 }
 
@@ -87,6 +107,10 @@ export interface NodesetNodeRecord {
     browseName: QualifiedName;
     displayName?: string;
     description?: string;
+    /** the `<Category>` elements, in order; a node may declare several */
+    category?: string[];
+    /** the `<Documentation>` element: a URL into the specification text, at most one */
+    documentation?: string;
     references: NodesetReferenceRecord[];
     releaseStatus?: "Draft" | "Deprecated";
     symbolicName?: string;

package/api/loader/nodeset_record_applier.ts

@@ -119,8 +119,16 @@ function makeDefaultVariant(
     if (nodeDataType?.basicDataType) {
         const basicDataType = nodeDataType.basicDataType;
         if (basicDataType === DataType.Variant) {
-            /// we don't now what is the variant
-            return undefined;
+            // the DataType is BaseDataType, or an abstract type that resolves to it, so there is
+            // no concrete default to synthesise. That is the same situation as a Variable whose
+            // DataType the document never stated, and it now gets the same answer: a null value
+            // waiting for its first update.
+            //
+            // Returning undefined here left the variable on the constructor's
+            // UncertainInitialValue, so two documents that say the same thing disagreed about the
+            // status code of a value neither of them carries -- an omitted DataType against an
+            // explicit i=24, which is the XSD default for that very attribute.
+            return { dataType: DataType.Null };
         }
 
         if (basicDataType === DataType.ExtensionObject) {
@@ -185,11 +193,23 @@ function isUninitializedMatrix(value: VariantOptions): boolean {
     return product > 0;
 }
 
+/**
+ * a <Definition> Name worth keeping on the node: one the document spelled bare. A "<n>:Name" is a
+ * namespace index into the writing document's own table, which means nothing in any other document,
+ * so it is dropped here and rebuilt from the browse name when a document is written back out.
+ */
+function definitionNameToKeep(name: string | undefined): string | undefined {
+    if (!name || /^[0-9]+:/.test(name)) return undefined;
+    return name;
+}
+
 const UA_NAMESPACE_URI = "http://opcfoundation.org/UA/";
 const reg = /ns=([0-9]+);(.*)/;
 
 interface INodePermissions {
     accessRestrictions?: AccessRestrictionsFlag;
+    /** what the document declared, whatever this loader enforces; see BaseNode */
+    declaredAccessRestrictions?: string;
     rolePermissions?: RolePermissionTypeOptions[];
 }
 
@@ -491,6 +511,9 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
         }
         return {
             accessRestrictions: this.applyAccessRestrictions ? convertAccessRestrictions(record.accessRestrictions) : undefined,
+            // kept whatever the option says: the option governs what is enforced, not what the
+            // document declared, and an exporter needs the latter
+            declaredAccessRestrictions: record.accessRestrictions,
             rolePermissions
         };
     }
@@ -501,6 +524,8 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
             nodeId: record.nodeId.isEmpty() ? null : this.translate(record.nodeId),
             browseName: this.translateQualifiedName(record.browseName),
             references: this.references(record),
+            // documentation, not behaviour, but the document said it and it must survive the trip
+            releaseStatus: record.releaseStatus,
             ...this.permissions(record)
         };
     }
@@ -560,6 +585,15 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
         } // already translated
         const namespace = this.addressSpace.getNamespace(params.nodeId.namespace);
         const node = namespace.internalCreateNode(params) as BaseNode;
+        // Whether the document declared ArrayDimensions at all. node-opcua synthesizes [0] on the
+        // variables it generates itself -- EnumStrings, the variables it materializes from a
+        // structure's fields -- so [0] on a node means either "the document said 0" or "nobody
+        // said anything", and an exporter that cannot tell them apart must either invent the
+        // attribute everywhere or drop it everywhere. Recorded here, where the document is still
+        // in hand, rather than guessed at afterwards
+        if (record.arrayDimensions !== undefined && record.arrayDimensions !== null) {
+            (node as { arrayDimensionsWereDeclared?: boolean }).arrayDimensionsWereDeclared = true;
+        }
         this.settle(node, record, params.references as UAReference[]);
         return node;
     }
@@ -659,7 +693,16 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
             displayName: record.displayName ?? "",
             description: record.description ?? "",
             symbolicName: record.symbolicName,
-            partialDefinition: fields
+            partialDefinition: fields,
+            // the address space models no OptionSet, so the flag and the fields above are all that
+            // is left of the declaration; without them the DataType cannot be written back out
+            isOptionSet: record.definition?.isOptionSet,
+            isUnion: record.definition?.isUnion,
+            // the <Definition> Name, but only when the document spelled it bare. The catalogue uses
+            // both spellings, and a "<n>:Name" prefix is an index into the table of the document
+            // that wrote it -- carrying it into another document would name a different namespace,
+            // so a prefixed name is left to be recomputed from the browse name on the way out
+            definitionName: definitionNameToKeep(record.definition?.name)
         } as unknown as CreateNodeOptions;
 
         let capturedDataTypeNode: UADataType | undefined = this.createNode(params, record) as UADataType;
@@ -817,6 +860,12 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
                     } else {
                         (cv as UAVariableImpl)._setInitialDataValue(defaultValue, StatusCodes.Good);
                     }
+                    // this value was made up here, not read from the document: the document said
+                    // nothing, and a usable default is served rather than a Bad status. An exporter
+                    // must not write it back out as though the document had declared it, and the
+                    // status code cannot tell it apart from a value the document really did declare
+                    // -- a declared empty string is Good too. So the fact is recorded on the node
+                    (cv as { valueWasSynthesized?: boolean }).valueWasSynthesized = true;
                 }
                 capturedVariable = undefined;
             };
@@ -860,6 +909,8 @@ export class NodesetRecordApplier implements NodesetRecordConsumer {
                 } else {
                     (variable as UAVariableImpl)._setInitialDataValue(defaultValue, StatusCodes.Good);
                 }
+                // made up here, not read from the document: see the note on the other synthesis site
+                (variable as { valueWasSynthesized?: boolean }).valueWasSynthesized = true;
             }
         } catch (err) {
             errorLog(