node-opcua-address-space 2.181.1 → 2.182.0

package/api/loader/nodeset_source.ts

@@ -7,7 +7,8 @@
  * first bytes.
  */
 
-import { isNodesetImage } from "./nodeset_image.js";
+import { findNodesetFormat, type NodesetDocument, type NodesetHead } from "./nodeset_format.js";
+import { inflatedImageLines, isGzip, isNodesetImage } from "./nodeset_image.js";
 
 /** one piece of a NodeSet2 document: text, or UTF-8 bytes */
 export type NodesetChunk = string | Uint8Array;
@@ -57,8 +58,26 @@ export interface NamedNodesetSource {
 
 const BOM = 0xfeff;
 
-/** what a source turned out to hold */
-export type NodesetSourceKind = "xml" | "image";
+/** how many characters of a document a format sniffer is shown */
+const HEAD_CHARS = 4096;
+
+/**
+ * how a document arrived, before anything has been decided about what it says: as text, or as
+ * bytes that are not text until something inflates or decodes them.
+ *
+ * This is not the format. It is the one thing that can be settled synchronously on a first
+ * chunk, and it decides only whether the reader decodes as it goes or keeps the bytes intact.
+ */
+export type NodesetContainer = "text" | "bytes";
+
+/**
+ * the name of the format a source turned out to be written in.
+ *
+ * This used to be a closed pair, XML or image. It is now whatever is registered, so that a
+ * format the loader has never heard of can identify itself; the two built-ins go on reading the
+ * documents they always did.
+ */
+export type NodesetSourceKind = string;
 
 export interface NodesetReaderOptions {
     /** keep the bytes read so that {@link NodesetReader.digest} can be computed */
@@ -82,7 +101,9 @@ export class NodesetReader {
     private bodyStarted = false;
     private decoder: TextDecoder | null = null;
     private atStart = true;
-    private kind: NodesetSourceKind | undefined;
+    private container: NodesetContainer | undefined;
+    private formatName: NodesetSourceKind | undefined;
+    private allBytesValue: Uint8Array | undefined;
     private readonly hashed: Uint8Array[] | null;
     private bytesRead = 0;
     private readonly encoder = new TextEncoder();
@@ -103,12 +124,66 @@ export class NodesetReader {
         return this.options.imageKey;
     }
 
-    /** XML or image: decided on the first bytes */
-    public async probe(): Promise<NodesetSourceKind> {
-        if (this.kind === undefined) {
+    /**
+     * how this document arrived: as text, or as bytes. Settled on the first chunk, and never a
+     * statement about which format the document is written in.
+     */
+    public async probeContainer(): Promise<NodesetContainer> {
+        if (this.container === undefined) {
             await this.pull();
         }
-        return this.kind ?? "xml";
+        return this.container ?? "text";
+    }
+
+    /**
+     * which registered format claims this document.
+     *
+     * Two stages, because one is not enough. The container is decided synchronously on the first
+     * chunk; the format is decided from the head of the document *after* it has been inflated,
+     * which is the only way to tell one gzipped serialisation from another. The loader used to
+     * skip that second stage and take any gzip stream for one of its own images, so a foreign
+     * compressed nodeset was not rejected but misread.
+     */
+    public async probe(): Promise<NodesetSourceKind> {
+        if (this.formatName !== undefined) {
+            return this.formatName;
+        }
+        const head = await this.sniffHead();
+        const format = findNodesetFormat(head);
+        if (!format) {
+            throw new Error(`nodeset source ${this.name}: no registered format recognises this document`);
+        }
+        this.formatName = format.name;
+        return this.formatName;
+    }
+
+    /**
+     * the beginning of the document as a sniffer sees it: inflated when it arrived gzipped, so
+     * that no format has to know how a document happened to be stored.
+     *
+     * A byte document is read whole. That is not a concession: every format that arrives as bytes
+     * is line-delimited or an archive, and reads whole anyway, and the bytes are kept so the read
+     * is not repeated. Text streams on, and is sniffed on as much of the head as has arrived.
+     */
+    private async sniffHead(): Promise<NodesetHead> {
+        if ((await this.probeContainer()) === "bytes") {
+            const all = await this.allBytes();
+            const gzip = isGzip(all);
+            const text = gzip
+                ? ((await inflatedImageLines(all))[0] ?? "")
+                : new TextDecoder("utf-8").decode(all.subarray(0, HEAD_CHARS));
+            return makeHead(this.name, text, gzip);
+        }
+        while (this.headTextLength() < HEAD_CHARS) {
+            if ((await this.pull()) === undefined) break;
+        }
+        return makeHead(this.name, (this.head as string[]).join("").slice(0, HEAD_CHARS), false);
+    }
+
+    private headTextLength(): number {
+        let total = 0;
+        for (const chunk of this.head as string[]) total += chunk.length;
+        return total;
     }
 
     /**
@@ -119,8 +194,8 @@ export class NodesetReader {
         if (this.bodyStarted) {
             throw new Error(`nodeset source ${this.name}: the head cannot be read once the body has been`);
         }
-        if ((await this.probe()) !== "xml") {
-            throw new Error(`nodeset source ${this.name}: not XML`);
+        if ((await this.probeContainer()) !== "text") {
+            throw new Error(`nodeset source ${this.name}: the head of a byte document is not text`);
         }
         let text = (this.head as string[]).join("");
         while (!complete(text)) {
@@ -133,13 +208,14 @@ export class NodesetReader {
         return text;
     }
 
-    /** the whole document as text chunks, from the start; usable once */
-    public async *chunks(): AsyncGenerator<string> {
+    /**
+     * the whole document from the start, usable once: text chunks for a document that arrived as
+     * text, byte chunks for one that did not. A caller that wants text either way decodes.
+     */
+    public async *chunks(): AsyncGenerator<NodesetChunk> {
         this.startBody();
-        if ((await this.probe()) !== "xml") {
-            throw new Error(`nodeset source ${this.name}: not XML`);
-        }
-        const head = this.head as string[];
+        await this.probeContainer();
+        const head = this.head as NodesetChunk[];
         this.head = [];
         for (const chunk of head) {
             yield chunk;
@@ -149,15 +225,15 @@ export class NodesetReader {
             if (chunk === undefined) {
                 return;
             }
-            yield chunk as string;
+            yield chunk;
         }
     }
 
-    /** the whole document as raw bytes, from the start, for a source holding an image; usable once */
+    /** the whole document as raw bytes, from the start, for a source holding bytes; usable once */
     public async *bytes(): AsyncGenerator<Uint8Array> {
         this.startBody();
-        if ((await this.probe()) !== "image") {
-            throw new Error(`nodeset source ${this.name}: not an image`);
+        if ((await this.probeContainer()) !== "bytes") {
+            throw new Error(`nodeset source ${this.name}: not a byte document`);
         }
         const head = this.head as Uint8Array[];
         this.head = [];
@@ -175,6 +251,9 @@ export class NodesetReader {
 
     /** the whole document as one byte array; reads the source to its end and keeps it */
     public async allBytes(): Promise<Uint8Array> {
+        if (this.allBytesValue !== undefined) {
+            return this.allBytesValue;
+        }
         if (this.bodyStarted) {
             throw new Error(`nodeset source ${this.name}: a source is read once`);
         }
@@ -182,7 +261,10 @@ export class NodesetReader {
             /* read to the end */
         }
         const parts = this.head.map((chunk) => (typeof chunk === "string" ? this.encoder.encode(chunk) : chunk));
-        return concat(parts);
+        // kept, so that the sniff and the format that follows it share one array: the inflated
+        // lines are cached against the identity of these bytes, and a second concat would miss
+        this.allBytesValue = concat(parts);
+        return this.allBytesValue;
     }
 
     /** the bytes read so far; the whole document once it has been read */
@@ -214,6 +296,16 @@ export class NodesetReader {
         return this.digestValue;
     }
 
+    /**
+     * the digest if it has already been computed, without computing one.
+     *
+     * A format may want to record what it read from, but must never be the thing that forces a
+     * stream to be drained to find out.
+     */
+    public digestIfKnown(): string | undefined {
+        return this.digestValue;
+    }
+
     private startBody(): void {
         if (this.bodyStarted) {
             throw new Error(`nodeset source ${this.name}: a source is read once`);
@@ -236,8 +328,8 @@ export class NodesetReader {
                 const result = await this.iterator.next();
                 if (result.done) {
                     this.exhausted = true;
-                    if (this.kind === undefined) {
-                        this.kind = "xml";
+                    if (this.container === undefined) {
+                        this.container = "text";
                     }
                     const tail = this.decoder ? this.decoder.decode() : "";
                     if (tail.length > 0) {
@@ -266,15 +358,16 @@ export class NodesetReader {
         if (chunk.length === 0) {
             return undefined;
         }
-        if (this.kind === undefined) {
-            this.kind = typeof chunk !== "string" && isNodesetImage(chunk) ? "image" : "xml";
+        if (this.container === undefined) {
+            // text unless the bytes say otherwise; a string chunk is text by construction
+            this.container = typeof chunk !== "string" && isNodesetImage(chunk) ? "bytes" : "text";
         }
         const raw = typeof chunk === "string" ? this.encoder.encode(chunk) : chunk;
         this.bytesRead += raw.length;
         if (this.hashed) {
             this.hashed.push(raw);
         }
-        if (this.kind === "image") {
+        if (this.container === "bytes") {
             const bytes = typeof chunk === "string" ? raw : chunk;
             if (!this.bodyStarted) this.head.push(bytes);
             return bytes;
@@ -365,3 +458,69 @@ export function openNodesetSource(
     };
     return new NodesetReader(name, open, whole, { hash: options.hash, imageKey });
 }
+
+/** the head a sniffer is shown, with its first line split out for the line-delimited formats */
+function makeHead(name: string, text: string, gzip: boolean): NodesetHead {
+    const newline = text.indexOf("\n");
+    const firstLine = newline < 0 ? text : text.slice(0, newline);
+    return { name, text, gzip, firstLine: firstLine.endsWith("\r") ? firstLine.slice(0, -1) : firstLine };
+}
+
+/**
+ * a {@link NodesetDocument} over a reader: what a format is handed.
+ *
+ * The point of the facade is that a format never touches the reader. It asks for the document in
+ * the shape it wants -- lines, text, bytes, a stream -- and the reader answers each of those once
+ * and shares the answer, so a format that wants both the lines and the raw bytes pays for one
+ * read and one inflate rather than two.
+ *
+ * @internal
+ */
+export function nodesetDocumentOf(reader: NodesetReader): NodesetDocument {
+    let inflatedBytes: Promise<Uint8Array> | undefined;
+    let textValue: Promise<string> | undefined;
+    let linesValue: Promise<string[]> | undefined;
+
+    const rawBytes = () => reader.allBytes();
+
+    const bytes = () => {
+        if (!inflatedBytes) {
+            inflatedBytes = (async () => {
+                const raw = await rawBytes();
+                if (!isGzip(raw)) return raw;
+                // one inflate, shared with lines(): both go through the cache keyed on these bytes
+                return new TextEncoder().encode((await inflatedImageLines(raw)).join("\n"));
+            })();
+        }
+        return inflatedBytes;
+    };
+
+    const lines = () => {
+        if (!linesValue) {
+            linesValue = (async () => {
+                const raw = await rawBytes();
+                if (isGzip(raw)) return await inflatedImageLines(raw);
+                return new TextDecoder("utf-8").decode(raw).split("\n");
+            })();
+        }
+        return linesValue;
+    };
+
+    const text = () => {
+        if (!textValue) {
+            textValue = (async () => (await lines()).join("\n"))();
+        }
+        return textValue;
+    };
+
+    return {
+        name: reader.name,
+        bytes,
+        text,
+        lines,
+        rawBytes,
+        chunks: () => reader.chunks(),
+        readHead: (complete: (t: string) => boolean) => reader.readHead(complete),
+        digest: () => reader.digestIfKnown()
+    };
+}

package/api/loader/nodeset_to_image.ts

@@ -1,28 +1,39 @@
 /**
  * @module node-opcua-address-space
  */
+import { NDJSON_IMAGE_FORMAT, registerBuiltinNodesetFormats } from "./nodeset_builtin_formats.js";
+import { nodesetFormatByName } from "./nodeset_format.js";
 import { imageNodesetRecords, NodesetImageWriter, type NodesetImageWriterOptions } from "./nodeset_image.js";
-import { type NodesetSource, openNodesetSource } from "./nodeset_source.js";
-import { xmlNodesetRecords } from "./nodeset_xml_producer.js";
+import { type NodesetSource, nodesetDocumentOf, openNodesetSource } from "./nodeset_source.js";
+
+registerBuiltinNodesetFormats();
 
 export interface NodesetToImageOptions extends Pick<NodesetImageWriterOptions, "addressSpaceVersion" | "createdAt"> {}
 
 /**
- * the precompiled image of a NodeSet2 document, built from the source alone: converting a file
+ * the precompiled image of a nodeset document, built from the source alone: converting a file
  * needs neither its dependencies nor an address space. A source that already holds an image is
  * returned as it is, once read through to check it.
+ *
+ * Any registered format can be the input, not only NodeSet2 XML: an image is a cache of records,
+ * and records are what every format produces.
  */
 export async function nodesetToImage(source: NodesetSource, options: NodesetToImageOptions = {}): Promise<Uint8Array> {
     const reader = openNodesetSource(source, 0, { hash: true });
-    if ((await reader.probe()) === "image") {
+    const formatName = await reader.probe();
+    if (formatName === NDJSON_IMAGE_FORMAT) {
         const bytes = await reader.allBytes();
         for await (const _record of imageNodesetRecords(bytes)) {
             /* a corrupt image is refused here rather than at load time */
         }
         return bytes;
     }
+    const format = nodesetFormatByName(formatName);
+    if (!format) {
+        throw new Error(`nodeset source ${reader.name}: its format is no longer registered`);
+    }
     const writer = new NodesetImageWriter({ ...options });
-    for await (const record of xmlNodesetRecords(reader.chunks())) {
+    for await (const record of format.records(nodesetDocumentOf(reader))) {
         writer.apply(record);
     }
     return writer.finish(await reader.digest(), reader.length);

package/api/loader/nodeset_xml_header.ts

@@ -0,0 +1,119 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * Reading the header of a NodeSet2 XML document: its `NamespaceUris` and its `Models`, and
+ * nothing else.
+ *
+ * This is the dependency pre-pass. Before any document is loaded the loader has to know what each
+ * one defines and what each one needs, so that it can sort them; it does that by reading every
+ * source no further than the end of its header, which on the standard nodeset is a few hundred
+ * bytes of a four megabyte file.
+ *
+ * It lives apart from the loader because the built-in XML format needs it too, and a format
+ * cannot import the loader that drives it.
+ */
+
+import { getMinOPCUADate } from "node-opcua-date-time";
+import { checkDebugFlag } from "node-opcua-debug";
+import { type ReaderStateParser, type ReaderStateParserLike, Xml2Json, type XmlAttributes } from "node-opcua-xml2json";
+import type { NodesetModel, NodesetModelInfo } from "./nodeset_format.js";
+
+const doDebug = checkDebugFlag("generateAddressSpaceRaw");
+
+type Model = NodesetModel;
+type NodesetInfo = NodesetModelInfo;
+
+/** the `NamespaceUris` and `Models` a NodeSet2 header declares */
+export async function parseDependencies(xmlData: string): Promise<NodesetInfo> {
+    const namespaceUris: string[] = [];
+
+    const models: Model[] = [];
+    let currentModel: Model | undefined;
+    const state0: ReaderStateParser = {
+        parser: {
+            UANodeSet: {
+                parser: {
+                    NamespaceUris: {
+                        parser: {
+                            Uri: <ReaderStateParserLike & { text: string }>{
+                                finish(this: ReaderStateParserLike & { text: string }) {
+                                    namespaceUris.push(this.text);
+                                }
+                            }
+                        }
+                    },
+                    Models: {
+                        parser: {
+                            Model: {
+                                init(_elementName: string, attrs: XmlAttributes) {
+                                    const modelUri = attrs.ModelUri;
+                                    const version = attrs.Version;
+                                    const publicationDate = new Date(Date.parse(attrs.PublicationDate));
+                                    currentModel = {
+                                        modelUri,
+                                        version,
+                                        publicationDate,
+                                        requiredModel: []
+                                    };
+                                    doDebug && console.log(`currentModel = ${JSON.stringify(currentModel)}`);
+                                    models.push(currentModel);
+                                },
+                                parser: {
+                                    RequiredModel: {
+                                        init(_elementName: string, attrs: XmlAttributes) {
+                                            const modelUri = attrs.ModelUri;
+                                            const version = attrs.Version;
+                                            const publicationDate = new Date(Date.parse(attrs.PublicationDate));
+
+                                            if (!currentModel) {
+                                                throw new Error("Internal Error");
+                                            }
+                                            currentModel.requiredModel.push({
+                                                modelUri,
+                                                version,
+                                                publicationDate
+                                            });
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+    const parser = new Xml2Json(state0);
+    parser.parseString(xmlData);
+    if (models.length === 0 && namespaceUris.length >= 1) {
+        models.push({
+            modelUri: namespaceUris[0],
+            version: "1",
+            publicationDate: getMinOPCUADate(),
+            requiredModel: []
+        });
+    }
+    return { models, namespaceUris: namespaceUris };
+}
+
+/**
+ * the header of a NodeSet2 file (`NamespaceUris`, `Models`) precedes the aliases and the nodes: the
+ * dependency pre-pass has read enough once both closers were seen, or once the body has begun
+ */
+const BODY_START =
+    /<(Aliases|Extensions|UAObject|UAVariable|UADataType|UAReferenceType|UAObjectType|UAVariableType|UAMethod|UAView)[\s/>]/;
+export function headerComplete(text: string): boolean {
+    return (text.includes("</Models>") && text.includes("</NamespaceUris>")) || BODY_START.test(text);
+}
+
+/** the `<UANodeSet ...>` opener up to the end of `</Models>` or `</NamespaceUris>`, whichever comes last */
+export function sliceHeader(xmlData: string, name: string): string {
+    const indexStart = xmlData.match(/<UANodeSet/m)?.index;
+    const i1 = (xmlData.match(/<\/Models>/m)?.index || 0) + "</Models>".length;
+    const i2 = (xmlData.match(/<\/NamespaceUris>/m)?.index || 0) + "</NamespaceUris>".length;
+    const indexEnd = Math.max(i1, i2);
+    if (indexStart === undefined) {
+        throw new Error(`nodeset source ${name}: no <UANodeSet> element found`);
+    }
+    return xmlData.substring(indexStart, indexEnd);
+}

package/api/loader/nodeset_xml_primitives.ts

@@ -0,0 +1,209 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * The parts of writing a NodeSet2 document that are about XML and nothing else: the namespace
+ * prefix bookkeeping an `XmlWriter` carries around, the id and browse-name spellings, and the few
+ * `uax:` elements a value is built from.
+ *
+ * They live here, below the address space, because there are two writers and neither should own
+ * them: `impl/nodeset_tools/nodeset_to_xml.ts` writes a live namespace, and
+ * `nodeset_records_to_xml.ts` writes a record stream with no address space anywhere in sight. A
+ * helper that reached for a node would be usable by only one of them.
+ */
+import { assert } from "node-opcua-assert";
+import type { Int64, UInt64 } from "node-opcua-basic-types";
+import { type LocalizedText, QualifiedName } from "node-opcua-data-model";
+import { make_warningLog } from "node-opcua-debug";
+import { NodeId } from "node-opcua-nodeid";
+import type { XmlWriter } from "../xml_writer.js";
+
+const warningLog = make_warningLog("nodeset_xml_primitives");
+
+export type XmlNamespaceUri = string;
+export type NamespaceUri = string;
+export type XmlNs = string;
+
+export const UAX_TYPES_XSD = "http://opcfoundation.org/UA/2008/02/Types.xsd";
+
+/** the `<xmlns:nsN>` a namespace's own types are declared under, derived from its uri */
+export function makeTypeXsd(namespaceUri: string): string {
+    return `${namespaceUri.replace(/\/$/, "")}/Type.xsd`;
+}
+
+interface XmlWriterEx extends XmlWriter {
+    map: Record<XmlNamespaceUri, XmlNs>;
+    stackMap: Record<XmlNamespaceUri, XmlNs>[];
+    namespaceArray: NamespaceUri[];
+}
+
+export function initXmlWriterEx(xw: XmlWriter, map: Record<XmlNamespaceUri, XmlNs>, namespaceArray: NamespaceUri[]): void {
+    const xwe = xw as XmlWriterEx;
+    xwe.map = map;
+    xwe.stackMap = [];
+    xwe.namespaceArray = namespaceArray;
+}
+
+export function findXsdNamespaceUri(xw: XmlWriter, nodeId: NodeId): string {
+    const xwe = xw as XmlWriterEx;
+    if (!xwe.namespaceArray) {
+        return "";
+    }
+    const namespace = xwe.namespaceArray[nodeId.namespace];
+    if (namespace === "http://opcfoundation.org/UA/") {
+        return UAX_TYPES_XSD;
+    }
+    // c8 ignore next
+    if (!namespace) {
+        return "";
+    }
+    return `${namespace.replace(/\/$/, "")}/Types.xsd`;
+}
+
+export function getPrefix(xw: XmlWriter, namespace: XmlNamespaceUri): XmlNs {
+    const xwe = xw as XmlWriterEx;
+    if (!xwe.map) return "";
+    const p = xwe.map[namespace] || "";
+    return p ? `${p}:` : "";
+}
+
+export function restoreDefaultNamespace(xw: XmlWriter): void {
+    const xwe = xw as XmlWriterEx;
+    if (!xwe.map) return;
+    const previousMap = xwe.stackMap.pop();
+    if (previousMap) {
+        xwe.map = previousMap;
+    }
+}
+
+export function setDefaultNamespace(xw: XmlWriter, namespace: XmlNamespaceUri): void {
+    const xwe = xw as XmlWriterEx;
+    if (!xwe.map) return;
+    if (xwe.map[namespace] !== "") {
+        xw.writeAttribute("xmlns", namespace);
+    }
+
+    xwe.stackMap.push({
+        ...xwe.map
+    });
+    xwe.map[namespace] = "";
+}
+
+export function startElementEx(xw: XmlWriter, _ns: XmlNs, name: string, defaultNamespace: XmlNamespaceUri): void {
+    xw.startElement(name);
+    setDefaultNamespace(xw, defaultNamespace);
+}
+
+// #region ids and names
+//
+// every id written goes through the writer's translationTable, which maps the index a node carries
+// to the index the document being written declares. A writer whose document keeps the indices it
+// was given -- the record writer -- installs the identity and these are then spelling functions.
+
+export function translateNodeId(xw: XmlWriter, nodeId: NodeId): NodeId {
+    assert(nodeId instanceof NodeId);
+    const nn = xw.translationTable.get(nodeId.namespace);
+    return new NodeId(nodeId.identifierType, nodeId.value, nn);
+}
+
+/** an id as a document spells it: translated, and with the `ns=0;` that every document leaves out */
+export function n(xw: XmlWriter, nodeId: NodeId): string {
+    return translateNodeId(xw, nodeId).toString().replace("ns=0;", "");
+}
+
+export function translateBrowseName(xw: XmlWriter, browseName: QualifiedName): QualifiedName {
+    assert(browseName instanceof QualifiedName);
+    const nn = xw.translationTable.get(browseName.namespaceIndex);
+    return new QualifiedName({ namespaceIndex: nn, name: browseName.name });
+}
+
+export function b(xw: XmlWriter, browseName: QualifiedName): string {
+    return translateBrowseName(xw, browseName).toString().replace("ns=0;", "");
+}
+
+/** the identity table, for a writer that keeps the namespace indices its input already carries */
+export function identityTranslationTable(size: number): Map<number, number> {
+    const table = new Map<number, number>();
+    for (let i = 0; i < size; i++) {
+        table.set(i, i);
+    }
+    return table;
+}
+
+// #endregion
+
+const TWO_64 = 1n << 64n;
+const TWO_63 = 1n << 63n;
+
+/**
+ * a 64-bit integer as one decimal number, the only spelling that says what it means.
+ *
+ * In memory node-opcua holds one as `[high, low]` with unsigned halves, so Int64 -1 and UInt64
+ * 18446744073709551615 are the very same pair and only `signed` tells them apart. Writing the low
+ * half alone -- which both XML writers used to do -- silently truncates anything past 2^32 and
+ * turns -1 into 4294967295.
+ */
+export function int64ToDecimalString(value: Int64 | UInt64 | number | string, signed: boolean): string {
+    if (typeof value === "number" || typeof value === "string") {
+        return value.toString();
+    }
+    const [high, low] = value as [number, number];
+    const unsigned = (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
+    return (signed && unsigned >= TWO_63 ? unsigned - TWO_64 : unsigned).toString();
+}
+
+export function coerceInt64ToInt32(int64: Int64): number {
+    if (typeof int64 === "number") {
+        return int64;
+    }
+    if (int64[0] === 0xffffffff && int64[1] === 0xffffffff) {
+        return 0xffffffff;
+    }
+    if (int64[0] !== 0) {
+        warningLog("coerceInt64ToInt32 , loosing high word in conversion");
+    }
+    return int64[1];
+}
+
+// #region the `uax:` elements a value is built from
+
+export function _dumpLocalizedText(xw: XmlWriter, v: LocalizedText): void {
+    const uax = getPrefix(xw, UAX_TYPES_XSD);
+    if (v.locale?.length) {
+        xw.startElement(`${uax}Locale`);
+        xw.text(v.locale);
+        xw.endElement();
+    }
+    xw.startElement(`${uax}Text`);
+    if (v.text) {
+        xw.text(v.text);
+    }
+    xw.endElement();
+}
+
+export function _dumpQualifiedName(xw: XmlWriter, v: QualifiedName): void {
+    const uax = getPrefix(xw, UAX_TYPES_XSD);
+    const t = translateBrowseName(xw, v);
+    if (t.name) {
+        xw.startElement(`${uax}Name`);
+        xw.text(t.name);
+        xw.endElement();
+    }
+    if (t.namespaceIndex) {
+        xw.startElement(`${uax}NamespaceIndex`);
+        xw.text(t.namespaceIndex.toString());
+        xw.endElement();
+    }
+}
+
+export function _dumpXmlElement(xw: XmlWriter, v: string): void {
+    xw.text(v);
+}
+
+export function _dumpNodeId(xw: XmlWriter, v: NodeId): void {
+    const xmlns = getPrefix(xw, UAX_TYPES_XSD);
+    xw.startElement(`${xmlns}Identifier`);
+    xw.text(n(xw, v));
+    xw.endElement();
+}
+
+// #endregion