node-opcua-address-space 2.181.0 → 2.182.0

package/dist/api/loader/narrow_instance_datatypes.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.narrowInstanceDataTypes = narrowInstanceDataTypes;
+const node_opcua_data_model_1 = require("node-opcua-data-model");
+const node_opcua_debug_1 = require("node-opcua-debug");
+const node_opcua_nodeid_1 = require("node-opcua-nodeid");
+const node_opcua_variant_1 = require("node-opcua-variant");
+const doDebug = (0, node_opcua_debug_1.checkDebugFlag)("narrow_instance_datatypes");
+const debugLog = (0, node_opcua_debug_1.make_debugLog)("narrow_instance_datatypes");
+function isType(node) {
+    return node.nodeClass === node_opcua_data_model_1.NodeClass.ObjectType || node.nodeClass === node_opcua_data_model_1.NodeClass.VariableType;
+}
+function isInstance(node) {
+    return node.nodeClass === node_opcua_data_model_1.NodeClass.Object || node.nodeClass === node_opcua_data_model_1.NodeClass.Variable;
+}
+/**
+ * the type definition of an instance, resolved without the ObjectType/VariableType guards of the
+ * typed getters: a companion nodeset with a wrong type definition must not abort the sweep
+ */
+function typeDefinitionOf(addressSpace, node) {
+    const typeDefinition = node.typeDefinition;
+    if (!typeDefinition || typeDefinition.isEmpty()) {
+        return null;
+    }
+    const typeNode = addressSpace.findNode(typeDefinition);
+    return typeNode && isType(typeNode) ? typeNode : null;
+}
+/**
+ * the members a type declares, by browse name, looked up along its supertype chain and its
+ * interfaces the way `instantiate` collects them (see impl/_instantiate_helpers.ts); the answer
+ * is cached per (type, browse name) so a sweep over thousands of instances of the same type
+ * walks the chain once per member
+ */
+class DeclarationIndex {
+    addressSpace;
+    cache = new Map();
+    /** absent from a standard nodeset older than 1.04: then no type has interfaces to look into */
+    hasInterface;
+    hasModellingRule;
+    constructor(addressSpace, hasModellingRule) {
+        this.addressSpace = addressSpace;
+        this.hasInterface = addressSpace.findReferenceType("HasInterface") ?? null;
+        this.hasModellingRule = hasModellingRule;
+    }
+    /**
+     * whether `declared` is a member declaration a variable instance must honour: a variable with
+     * a modelling rule (Mandatory, Optional, ...). A type child without one is not instantiated by
+     * Part 3 and is left alone.
+     */
+    isVariableDeclaration(declared) {
+        return (declared.nodeClass === node_opcua_data_model_1.NodeClass.Variable &&
+            declared.findReferencesEx(this.hasModellingRule, node_opcua_data_model_1.BrowseDirection.Forward).length > 0);
+    }
+    find(type, browseName) {
+        const key = `${type.nodeId.toString()}|${browseName.toString()}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const found = this.walk(type, browseName, new Set());
+        this.cache.set(key, found);
+        return found;
+    }
+    walk(type, browseName, visited) {
+        const typeKey = type.nodeId.toString();
+        if (visited.has(typeKey)) {
+            return null;
+        }
+        visited.add(typeKey);
+        const child = type.getChildByName(browseName);
+        if (child) {
+            return child;
+        }
+        const interfaces = this.hasInterface ? type.findReferencesEx(this.hasInterface, node_opcua_data_model_1.BrowseDirection.Forward) : [];
+        for (const reference of interfaces) {
+            const interfaceType = reference.node ?? this.addressSpace.findNode(reference.nodeId);
+            if (interfaceType && isType(interfaceType)) {
+                const declared = this.walk(interfaceType, browseName, visited);
+                if (declared) {
+                    return declared;
+                }
+            }
+        }
+        const superType = type.subtypeOfObj;
+        return superType ? this.walk(superType, browseName, visited) : null;
+    }
+}
+// a parent chain deeper than this is a cycle in a broken nodeset, not a model
+const MAX_DEPTH = 64;
+/**
+ * the node of a type definition that declares this instance member, or null when no type in
+ * the instance's ancestry declares one under its browse name.
+ *
+ * The declaration is looked up in the type definition of the containing instance first; a
+ * member nested below a declared member (an object declared by the type with children of its
+ * own, whose own type definition says nothing about them) is found through the declaration of
+ * its container instead.
+ */
+function declarationOf(addressSpace, index, node, depth) {
+    if (depth > MAX_DEPTH) {
+        return null;
+    }
+    const parent = node.parent;
+    // a node under a type is a declaration itself, never an instance to narrow
+    if (!parent || isType(parent)) {
+        return null;
+    }
+    const parentIsInstance = isInstance(parent);
+    if (parentIsInstance) {
+        const parentType = typeDefinitionOf(addressSpace, parent);
+        if (parentType) {
+            const declared = index.find(parentType, node.browseName);
+            if (declared) {
+                return declared;
+            }
+        }
+    }
+    // the container may itself be a declared member (an instance, or a method) whose declaration
+    // carries the member; a method has no type definition and is resolved the same way
+    if (parentIsInstance || parent.nodeClass === node_opcua_data_model_1.NodeClass.Method) {
+        const parentDeclaration = declarationOf(addressSpace, index, parent, depth + 1);
+        if (parentDeclaration) {
+            return parentDeclaration.getChildByName(node.browseName);
+        }
+    }
+    return null;
+}
+function findDataTypeNode(addressSpace, nodeId) {
+    if (!nodeId || nodeId.isEmpty()) {
+        return null;
+    }
+    return addressSpace.findDataType(nodeId) ?? null;
+}
+/**
+ * make every instance variable's DataType at least as narrow as its declaration.
+ *
+ * OPC 10000-3 lets an instance use the DataType its type definition declares for the member, or
+ * a subtype of it; a supertype is not conformant. Companion nodesets that predate a narrowing
+ * of the standard types carry the supertype anyway (every NamespaceMetadata object written
+ * against UA 1.04 declares `ModelVersion` as String, which UA 1.05 narrowed to
+ * SemanticVersionString), so every server loading them fails the type-conformance check of
+ * the CTT (Base Info Core Structure) and no server can fix it per nodeset. The declared type is
+ * what the model means: an instance whose DataType is a strict supertype of the declared one is
+ * moved to the declared one.
+ *
+ * Nothing else moves: an instance whose DataType is the declared one, a subtype of it, or
+ * unrelated is left alone, values are never touched, and the children of types are declarations,
+ * not instances. A variable whose current value would not fit the declared built-in type is
+ * left alone as well, and reported: narrowing it would make the value lie about its type.
+ *
+ * @returns the variables that were narrowed
+ */
+function narrowInstanceDataTypes(addressSpace) {
+    const narrowed = [];
+    // a nodeset without these cannot declare a member, let alone the DataType of one: a
+    // minimal fixture, or a standard nodeset still to come. Nothing to narrow, and the lookups
+    // below would throw on the first missing reference type.
+    const hasModellingRule = addressSpace.findReferenceType("HasModellingRule");
+    if (!hasModellingRule ||
+        !addressSpace.findReferenceType("HasSubtype") ||
+        !addressSpace.findReferenceType("HasChild") ||
+        !addressSpace.findReferenceType("HierarchicalReferences")) {
+        return narrowed;
+    }
+    const index = new DeclarationIndex(addressSpace, hasModellingRule);
+    for (const namespace of addressSpace.getNamespaceArray()) {
+        for (const node of namespace.nodeIterator()) {
+            if (node.nodeClass !== node_opcua_data_model_1.NodeClass.Variable) {
+                continue;
+            }
+            const variable = node;
+            const declared = declarationOf(addressSpace, index, variable, 0);
+            if (!declared || !index.isVariableDeclaration(declared)) {
+                continue;
+            }
+            if ((0, node_opcua_nodeid_1.sameNodeId)(variable.dataType, declared.dataType)) {
+                continue;
+            }
+            const instanceDataType = findDataTypeNode(addressSpace, variable.dataType);
+            const declaredDataType = findDataTypeNode(addressSpace, declared.dataType);
+            if (!instanceDataType || !declaredDataType) {
+                continue;
+            }
+            // a subtype of the declaration, or an unrelated type: not this sweep's business
+            if (!declaredDataType.isSubtypeOf(instanceDataType)) {
+                continue;
+            }
+            const value = variable.readValue().value;
+            const declaredBuiltInType = declaredDataType.basicDataType;
+            const valueFits = value.dataType === node_opcua_variant_1.DataType.Null ||
+                declaredBuiltInType === node_opcua_variant_1.DataType.Variant ||
+                value.dataType === declaredBuiltInType;
+            if (!valueFits) {
+                debugLog(`not narrowing ${variable.nodeId.toString()} ${variable.browseName.toString()}: ` +
+                    `its value is a ${node_opcua_variant_1.DataType[value.dataType]}, the declared ${declaredDataType.browseName.toString()} ` +
+                    `is a ${node_opcua_variant_1.DataType[declaredBuiltInType]}`);
+                continue;
+            }
+            const from = variable.dataType;
+            variable.dataType = declaredDataType.nodeId;
+            variable._basicDataType = null;
+            narrowed.push({ node: variable, from, to: declaredDataType.nodeId });
+            // c8 ignore next
+            if (doDebug) {
+                debugLog(`narrowed the DataType of ${variable.nodeId.toString()} ${variable.browseName.toString()} ` +
+                    `from ${instanceDataType.browseName.toString()} (${from.toString()}) ` +
+                    `to the declared ${declaredDataType.browseName.toString()} (${declaredDataType.nodeId.toString()})`);
+            }
+        }
+    }
+    // c8 ignore next
+    if (doDebug && narrowed.length > 0) {
+        debugLog(`narrowed the DataType of ${narrowed.length} instance variable(s) to the one their type declares`);
+    }
+    return narrowed;
+}
+//# sourceMappingURL=narrow_instance_datatypes.js.map

package/dist/api/loader/narrow_instance_datatypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrow_instance_datatypes.js","sourceRoot":"","sources":["../../../api/loader/narrow_instance_datatypes.ts"],"names":[],"mappings":"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"}

package/dist/api/loader/nodeset_builtin_formats.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * The two serialisations the loader has always read, expressed as {@link NodesetFormat}s.
+ *
+ * Registering them here rather than branching on a boolean inside the loader is the whole point
+ * of the registry: the built-ins get no privilege a third-party format does not also get, so the
+ * contract cannot quietly grow a dependency on something only the built-ins can reach. If these
+ * two can be written against it, so can a fourth.
+ *
+ * Importing this module registers them. The loader does that once, at its own import.
+ */
+/** the name the NodeSet2 XML format is registered under */
+export declare const NODESET2_XML_FORMAT = "nodeset2-xml";
+/** the name the NDJSON image format is registered under */
+export declare const NDJSON_IMAGE_FORMAT = "ndjson";
+/**
+ * whether this line is the header record of an NDJSON image.
+ *
+ * Deliberately a string test before it is a parse: the discriminating fields are written first
+ * and the line can be hundreds of kilobytes, so there is no reason to build an object to answer
+ * a question the first thirty characters already settle. The parse is the confirmation, not the
+ * test, and it is only reached for a line that already looks like ours.
+ */
+export declare function isNdjsonHeaderLine(line: string): boolean;
+/** register the built-in formats; called by the loader, and safe to call more than once */
+export declare function registerBuiltinNodesetFormats(): void;

package/dist/api/loader/nodeset_builtin_formats.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * @module node-opcua-address-space
+ *
+ * The two serialisations the loader has always read, expressed as {@link NodesetFormat}s.
+ *
+ * Registering them here rather than branching on a boolean inside the loader is the whole point
+ * of the registry: the built-ins get no privilege a third-party format does not also get, so the
+ * contract cannot quietly grow a dependency on something only the built-ins can reach. If these
+ * two can be written against it, so can a fourth.
+ *
+ * Importing this module registers them. The loader does that once, at its own import.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NDJSON_IMAGE_FORMAT = exports.NODESET2_XML_FORMAT = void 0;
+exports.isNdjsonHeaderLine = isNdjsonHeaderLine;
+exports.registerBuiltinNodesetFormats = registerBuiltinNodesetFormats;
+const node_opcua_date_time_1 = require("node-opcua-date-time");
+const nodeset_format_js_1 = require("./nodeset_format.js");
+const nodeset_image_js_1 = require("./nodeset_image.js");
+const nodeset_xml_header_js_1 = require("./nodeset_xml_header.js");
+const nodeset_xml_producer_js_1 = require("./nodeset_xml_producer.js");
+/** the name the NodeSet2 XML format is registered under */
+exports.NODESET2_XML_FORMAT = "nodeset2-xml";
+/** the name the NDJSON image format is registered under */
+exports.NDJSON_IMAGE_FORMAT = "ndjson";
+/**
+ * NodeSet2 XML: the fallback.
+ *
+ * It claims every document no other format recognised, which is exactly what the loader did
+ * before there was a registry, and it is the right default for a reason that outlives this
+ * refactor: XML has no compact magic number worth sniffing. A document may open with a byte-order
+ * mark, an XML declaration, a comment, a doctype or whitespace before `<UANodeSet` ever appears,
+ * and a sniffer strict enough to be sure would reject documents the loader reads today. So it
+ * does not guess. It takes what is left, and reports a real parse error if it was wrong, which is
+ * a better diagnostic than "unrecognised format" ever was.
+ */
+const nodeset2XmlFormat = {
+    name: exports.NODESET2_XML_FORMAT,
+    extensions: [".xml"],
+    priority: -100,
+    sniff(_head) {
+        return true;
+    },
+    async readModels(document) {
+        const head = await document.readHead(nodeset_xml_header_js_1.headerComplete);
+        return await (0, nodeset_xml_header_js_1.parseDependencies)((0, nodeset_xml_header_js_1.sliceHeader)(head, document.name));
+    },
+    records(document, _options) {
+        return (0, nodeset_xml_producer_js_1.xmlNodesetRecords)(textChunks(document));
+    }
+};
+/** the chunks of a document as text: the XML producer takes text, and a source may deliver bytes */
+async function* textChunks(document) {
+    const decoder = new TextDecoder("utf-8");
+    for await (const chunk of document.chunks()) {
+        yield typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    }
+}
+/**
+ * The NDJSON image: node-opcua's own cache of a document it has already parsed.
+ *
+ * Its first line is a header record, so it is told from every other line-delimited nodeset format
+ * by the two fields that open it: `{"kind":"header","schema":<n>`. That is a stronger test than
+ * "begins with a brace", which is all the loader used to do, and it is what lets a foreign
+ * `.jsonl` sit in the same directory without being mistaken for one of ours.
+ */
+const ndjsonImageFormat = {
+    name: exports.NDJSON_IMAGE_FORMAT,
+    extensions: [".ndjson", ".ndjson.gz"],
+    priority: 100,
+    sniff(head) {
+        return isNdjsonHeaderLine(head.firstLine);
+    },
+    async readModels(document) {
+        // an image is small, a few hundred KB, and its header is line 1: reading it whole costs
+        // nothing that the load itself was not about to spend
+        const { header } = await (0, nodeset_image_js_1.readNodesetImageInfo)(await document.rawBytes());
+        const models = header.models.map((m) => ({
+            modelUri: m.modelUri,
+            version: m.version,
+            publicationDate: m.publicationDate ? new Date(m.publicationDate) : (0, node_opcua_date_time_1.getMinOPCUADate)(),
+            requiredModel: m.requiredModels.map((r) => ({
+                ...r,
+                publicationDate: new Date(r.publicationDate ?? Number.NaN)
+            }))
+        }));
+        if (models.length === 0 && header.namespaceUris.length >= 1) {
+            models.push({
+                modelUri: header.namespaceUris[0],
+                version: "1",
+                publicationDate: (0, node_opcua_date_time_1.getMinOPCUADate)(),
+                requiredModel: []
+            });
+        }
+        return { models, namespaceUris: header.namespaceUris };
+    },
+    async *records(document, _options) {
+        yield* (0, nodeset_image_js_1.imageLinesToRecords)(await document.lines());
+    }
+};
+/**
+ * whether this line is the header record of an NDJSON image.
+ *
+ * Deliberately a string test before it is a parse: the discriminating fields are written first
+ * and the line can be hundreds of kilobytes, so there is no reason to build an object to answer
+ * a question the first thirty characters already settle. The parse is the confirmation, not the
+ * test, and it is only reached for a line that already looks like ours.
+ */
+function isNdjsonHeaderLine(line) {
+    const start = line.slice(0, 200);
+    if (!start.startsWith("{") || !start.includes('"kind"') || !start.includes('"header"')) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(line);
+        return parsed?.kind === "header" && typeof parsed.schema === "number";
+    }
+    catch {
+        return false;
+    }
+}
+let registered = false;
+/** register the built-in formats; called by the loader, and safe to call more than once */
+function registerBuiltinNodesetFormats() {
+    if (registered)
+        return;
+    registered = true;
+    (0, nodeset_format_js_1.registerNodesetFormat)(nodeset2XmlFormat);
+    (0, nodeset_format_js_1.registerNodesetFormat)(ndjsonImageFormat);
+}
+registerBuiltinNodesetFormats();
+//# sourceMappingURL=nodeset_builtin_formats.js.map

package/dist/api/loader/nodeset_builtin_formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeset_builtin_formats.js","sourceRoot":"","sources":["../../../api/loader/nodeset_builtin_formats.ts"],"names":[],"mappings":"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"}

package/dist/api/loader/nodeset_format.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @module node-opcua-address-space
+ *
+ * Which serialisation a nodeset document is written in, and who can read it.
+ *
+ * The loader is built as `producer -> NodesetRecord -> consumer`: whatever a document is written
+ * in, it becomes a stream of records, and everything downstream of that -- the address space, the
+ * NodeSet2 XML writer, the image writer -- neither knows nor asks. What was missing is the other
+ * half of that seam. The *choice* of producer was a hard-coded pair, XML or image, decided on one
+ * byte, so a third serialisation had no way in short of editing the loader.
+ *
+ * A {@link NodesetFormat} is that way in. It answers three questions and nothing else: are these
+ * bytes mine, what does this document depend on, and what are its records. Formats are found by
+ * sniffing the document, never by its file name: an extension is a claim about a file, and the
+ * loader reads sources that are not files at all.
+ *
+ * Two formats are built in and registered by the loader itself, so the default behaviour is
+ * exactly what it always was: NodeSet2 XML, and the NDJSON image. Anything else is registered by
+ * the code that implements it, the way the Node.js entry point installs its zlib codecs.
+ */
+import type { RequiredModel } from "node-opcua-address-space-base";
+import type { NodeSetLoaderOptions } from "../interfaces/nodeset_loader_options.js";
+import type { NodesetRecord } from "./nodeset_record.js";
+import type { NodesetChunk } from "./nodeset_source.js";
+/** a model a document defines, together with the models it says it needs */
+export interface NodesetModel extends RequiredModel {
+    requiredModel: RequiredModel[];
+}
+/**
+ * what a document says about itself before its body is read: enough, and only enough, to sort a
+ * set of documents into the order they have to be loaded in.
+ */
+export interface NodesetModelInfo {
+    namespaceUris: string[];
+    models: NodesetModel[];
+}
+/**
+ * the beginning of a document, for {@link NodesetFormat.sniff}.
+ *
+ * `text` is inflated when the document arrived gzipped, so a sniffer never has to care whether it
+ * is looking at a compressed file: compression is a property of how a document was stored, never
+ * of what it says. It is decoded as UTF-8, which is lossless for the text formats and, for a
+ * binary container, faithful across the ASCII and NUL runs that container formats put their magic
+ * in (a tar header, for instance, is ASCII and NUL for its whole first block).
+ */
+export interface NodesetHead {
+    /** the first bytes of the document, decoded as UTF-8, inflated if the document was gzipped */
+    readonly text: string;
+    /** `text` up to the first line feed: what the line-delimited formats decide on */
+    readonly firstLine: string;
+    /** whether the document was gzip on the wire */
+    readonly gzip: boolean;
+    /** the source's name, for diagnostics only; never a basis for the decision */
+    readonly name: string;
+}
+/**
+ * a document handed to a format, in whichever shape that format finds convenient. Every accessor
+ * inflates first when the document was gzipped, and the results are computed once and shared, so
+ * a format that asks for both the lines and the bytes pays for one inflate.
+ */
+export interface NodesetDocument {
+    readonly name: string;
+    /** the whole document, inflated */
+    bytes(): Promise<Uint8Array>;
+    /** the whole document as text, inflated and decoded */
+    text(): Promise<string>;
+    /** the document's lines, for the line-delimited formats */
+    lines(): Promise<string[]>;
+    /** the bytes exactly as they arrived, still compressed if they were */
+    rawBytes(): Promise<Uint8Array>;
+    /** the document as it arrives, for a format that parses incrementally rather than whole */
+    chunks(): AsyncIterable<NodesetChunk>;
+    /**
+     * read from the start until `complete(text)` holds, or the document ends. What was read stays
+     * in the document and is delivered again, first, by {@link NodesetDocument.chunks}, so a
+     * format that reads a header this way has not spent the source.
+     *
+     * This is how a format avoids reading a body it does not need: the XML header pre-pass stops
+     * after a few hundred bytes of a four megabyte file.
+     */
+    readHead(complete: (text: string) => boolean): Promise<string>;
+    /** the SHA-256 of the bytes as they arrived, when the loader was asked to compute one */
+    digest(): string | undefined;
+}
+/** a serialisation the loader can read */
+export interface NodesetFormat {
+    /** how this format is named in diagnostics and in the tools; unique among registered formats */
+    readonly name: string;
+    /**
+     * the file extensions this format is usually written with, lowercase and dotted.
+     * Documentation and tooling only: the loader never decides on a name.
+     */
+    readonly extensions?: readonly string[];
+    /**
+     * which format wins when more than one claims a document. Higher is stronger; the default is
+     * 0. NodeSet2 XML registers at -100 because it is the fallback: it claims anything no other
+     * format recognised, which is the behaviour the loader has always had.
+     */
+    readonly priority?: number;
+    /** whether this format claims the document that begins like this */
+    sniff(head: NodesetHead): boolean;
+    /** what the document depends on, read without parsing its body */
+    readModels(document: NodesetDocument): Promise<NodesetModelInfo>;
+    /** the document's records, in document order */
+    records(document: NodesetDocument, options?: NodeSetLoaderOptions): AsyncIterable<NodesetRecord>;
+}
+/**
+ * make a format available to the loader. Returns a function that removes it again, which is what
+ * a test uses to put the registry back as it found it; production code registers once, at import.
+ *
+ * Registering a name twice replaces the earlier format, so a caller can override a built-in.
+ */
+export declare function registerNodesetFormat(format: NodesetFormat): () => void;
+/** every registered format, strongest claim first */
+export declare function nodesetFormats(): readonly NodesetFormat[];
+/** the registered format of that name, if any */
+export declare function nodesetFormatByName(name: string): NodesetFormat | undefined;
+/**
+ * which format claims a document that begins like this, or `undefined` when none does. Formats
+ * are asked strongest first, so a specific format is always given the chance to claim a document
+ * before the XML fallback sees it.
+ */
+export declare function findNodesetFormat(head: NodesetHead): NodesetFormat | undefined;

package/dist/api/loader/nodeset_format.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * @module node-opcua-address-space
+ *
+ * Which serialisation a nodeset document is written in, and who can read it.
+ *
+ * The loader is built as `producer -> NodesetRecord -> consumer`: whatever a document is written
+ * in, it becomes a stream of records, and everything downstream of that -- the address space, the
+ * NodeSet2 XML writer, the image writer -- neither knows nor asks. What was missing is the other
+ * half of that seam. The *choice* of producer was a hard-coded pair, XML or image, decided on one
+ * byte, so a third serialisation had no way in short of editing the loader.
+ *
+ * A {@link NodesetFormat} is that way in. It answers three questions and nothing else: are these
+ * bytes mine, what does this document depend on, and what are its records. Formats are found by
+ * sniffing the document, never by its file name: an extension is a claim about a file, and the
+ * loader reads sources that are not files at all.
+ *
+ * Two formats are built in and registered by the loader itself, so the default behaviour is
+ * exactly what it always was: NodeSet2 XML, and the NDJSON image. Anything else is registered by
+ * the code that implements it, the way the Node.js entry point installs its zlib codecs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerNodesetFormat = registerNodesetFormat;
+exports.nodesetFormats = nodesetFormats;
+exports.nodesetFormatByName = nodesetFormatByName;
+exports.findNodesetFormat = findNodesetFormat;
+const formats = new Map();
+/**
+ * make a format available to the loader. Returns a function that removes it again, which is what
+ * a test uses to put the registry back as it found it; production code registers once, at import.
+ *
+ * Registering a name twice replaces the earlier format, so a caller can override a built-in.
+ */
+function registerNodesetFormat(format) {
+    formats.set(format.name, format);
+    return () => {
+        if (formats.get(format.name) === format) {
+            formats.delete(format.name);
+        }
+    };
+}
+/** every registered format, strongest claim first */
+function nodesetFormats() {
+    return [...formats.values()].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
+/** the registered format of that name, if any */
+function nodesetFormatByName(name) {
+    return formats.get(name);
+}
+/**
+ * which format claims a document that begins like this, or `undefined` when none does. Formats
+ * are asked strongest first, so a specific format is always given the chance to claim a document
+ * before the XML fallback sees it.
+ */
+function findNodesetFormat(head) {
+    for (const format of nodesetFormats()) {
+        if (format.sniff(head)) {
+            return format;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=nodeset_format.js.map

package/dist/api/loader/nodeset_format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeset_format.js","sourceRoot":"","sources":["../../../api/loader/nodeset_format.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AAsGH,sDAOC;AAGD,wCAEC;AAGD,kDAEC;AAOD,8CAOC;AAvCD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEjD;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,MAAqB;IACvD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,GAAG,EAAE;QACR,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;YACtC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAED,qDAAqD;AACrD,SAAgB,cAAc;IAC1B,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,iDAAiD;AACjD,SAAgB,mBAAmB,CAAC,IAAY;IAC5C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,IAAiB;IAC/C,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,EAAE,CAAC;QACpC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,OAAO,MAAM,CAAC;QAClB,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/api/loader/nodeset_image.d.ts

@@ -10,8 +10,24 @@ import { type EncodeHeaderOptions, type NodesetImageHeader, type NodesetImageTra
 import { type NodesetRecord, type NodesetRecordConsumer } from "./nodeset_record.js";
 import type { NodesetChunkStream } from "./nodeset_source.js";
 export { NodesetImageError, type NodesetImageHeader, type NodesetImageTrailer } from "./nodeset_image_codec.js";
-/** the two bytes every gzip stream starts with: how an image is told from XML */
+/** whether these bytes are gzip, and so need inflating before they are text */
+export declare function isGzip(firstBytes: Uint8Array): boolean;
+/**
+ * a NodeSet-NDJSON document, compressed or not, told from NodeSet2 XML by its first byte: a gzip
+ * stream starts `1f 8b`, an XML document `<`, and an uncompressed document `{`. Compression is a
+ * property of how a document was stored, never of what it says, so a reader that took only the
+ * compressed form would be refusing the same document written plainly.
+ */
 export declare function isNodesetImage(firstBytes: Uint8Array): boolean;
+/** how the text of an image is compressed; see {@link setImageDeflater} */
+export type ImageDeflater = (text: string) => Promise<Uint8Array>;
+/**
+ * how an image is compressed: CompressionStream everywhere by default, which offers no way to ask
+ * for a compression level and so writes at the default one; the Node.js entry point installs zlib
+ * at level 9, four percent smaller on the published nodesets for no change to the reader -- every
+ * gzip stream inflates the same whatever level wrote it. Returns the deflater installed before.
+ */
+export declare function setImageDeflater(deflater: ImageDeflater): ImageDeflater;
 /** forget the inflated lines of `image`; the next reader inflates again */
 export declare function releaseInflatedImageLines(image: Uint8Array): void;
 /** whether the inflated lines of `image` are being kept, for the tests */