@distrohelena/canton-typescript-sdk 0.1.36 → 0.1.37

package/dist/cjs/query/canonical/public-identity.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalPublicNumericIdentity = canonicalPublicNumericIdentity;
+exports.canonicalPublicNumericIdentityParts = canonicalPublicNumericIdentityParts;
+exports.compileCanonicalPublicNumericIdentitySql = compileCanonicalPublicNumericIdentitySql;
+exports.compileCanonicalPublicNumericIdentityPartsSql = compileCanonicalPublicNumericIdentityPartsSql;
+const node_buffer_1 = require("node:buffer");
+const MAX_CANONICAL_PUBLIC_IDENTITY_BYTES = 43_690;
+/**
+ * Encodes an arbitrary UTF-8 semantic identity as a positive decimal integer.
+ *
+ * The leading decimal digit is a sentinel and each byte occupies three decimal
+ * digits, so leading NUL bytes and the empty string remain distinct. This is an
+ * injective encoding, not a hash.
+ */
+function canonicalPublicNumericIdentity(identity) {
+    const bytes = node_buffer_1.Buffer.from(identity, "utf8");
+    if (bytes.length > MAX_CANONICAL_PUBLIC_IDENTITY_BYTES) {
+        throw new RangeError(`Canonical public identity exceeds ${MAX_CANONICAL_PUBLIC_IDENTITY_BYTES} UTF-8 bytes`);
+    }
+    let value = "1";
+    for (const byte of bytes) {
+        value += byte.toString().padStart(3, "0");
+    }
+    return value;
+}
+/** Frames multiple semantic components without a delimiter ambiguity. */
+function canonicalPublicNumericIdentityParts(parts) {
+    return canonicalPublicNumericIdentity(parts.map((part) => `${node_buffer_1.Buffer.byteLength(part, "utf8")}:${part}`).join(""));
+}
+/** PostgreSQL expression exactly equivalent to {@link canonicalPublicNumericIdentity}. */
+function compileCanonicalPublicNumericIdentitySql(text) {
+    const bytes = `convert_to((${text})::text, 'UTF8')`;
+    const encoded = `('1' || coalesce((select string_agg(lpad(get_byte(canonical_identity_bytes, canonical_identity_byte)::text, 3, '0'), '' order by canonical_identity_byte) from generate_series(0, octet_length(canonical_identity_bytes) - 1) as canonical_identity_byte), ''))::numeric`;
+    const overflow = `('1' || repeat('0', octet_length(canonical_identity_bytes) * 3))::numeric`;
+    return `(select case when octet_length(canonical_identity_bytes) <= ${MAX_CANONICAL_PUBLIC_IDENTITY_BYTES} then ${encoded} else ${overflow} end from (select ${bytes} as canonical_identity_bytes) canonical_identity)`;
+}
+/** PostgreSQL framing equivalent to {@link canonicalPublicNumericIdentityParts}. */
+function compileCanonicalPublicNumericIdentityPartsSql(parts) {
+    return `concat(${parts.flatMap((part) => [`octet_length(convert_to((${part})::text, 'UTF8'))`, "':'", `(${part})::text`]).join(", ")})`;
+}

package/dist/cjs/query/canonical/query-ast.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/query/canonical/query-dataset.js

@@ -0,0 +1,351 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImmutableQueryDate = exports.IncompleteQueryEdgeError = void 0;
+exports.createQueryDataset = createQueryDataset;
+exports.relatedQueryRows = relatedQueryRows;
+exports.immutableQueryValue = immutableQueryValue;
+const query_schema_js_1 = require("./query-schema.js");
+/** An edge is declared by the schema but its targets were unavailable in this snapshot. */
+class IncompleteQueryEdgeError extends Error {
+    relation;
+    edge;
+    constructor(relation, edge) {
+        super(`Dataset edge ${relation}.${edge} is incomplete`);
+        this.relation = relation;
+        this.edge = edge;
+        this.name = "IncompleteQueryEdgeError";
+        Object.freeze(this);
+    }
+}
+exports.IncompleteQueryEdgeError = IncompleteQueryEdgeError;
+const datasetIndexes = new WeakMap();
+const compiledSnapshots = new WeakMap();
+const rawRowSnapshots = new WeakMap();
+const compiledRowMembership = new WeakMap();
+const emptyRows = Object.freeze([]);
+const datasetPaths = Object.fromEntries(Object.keys(query_schema_js_1.queryRelationMetadata).map((relation) => [relation, [
+        ...query_schema_js_1.queryRelationMetadata[relation].fields,
+        ...(relation === "contracts" ? ["templateId.packageId", "templateId.moduleName", "templateId.entityName"] : []),
+    ]]));
+/** Validates and freezes source-neutral rows, then builds deterministic edge indexes once. */
+function createQueryDataset(input) {
+    if (datasetIndexes.has(input)) {
+        return input;
+    }
+    const cached = compiledSnapshots.get(input);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const dataset = immutableQueryValue(input);
+    const rowSnapshots = new Map();
+    const rowMembership = new Map();
+    for (const relation of Object.keys(query_schema_js_1.queryRelationMetadata)) {
+        if (!Array.isArray(input.rows[relation])) {
+            throw new Error(`Dataset is missing ${relation} rows`);
+        }
+        const snapshots = new WeakMap();
+        for (const [index, row] of input.rows[relation].entries()) {
+            snapshots.set(row, dataset.rows[relation][index]);
+        }
+        rowSnapshots.set(relation, snapshots);
+        rowMembership.set(relation, new WeakSet(dataset.rows[relation].map((row) => row)));
+    }
+    const relations = Object.keys(query_schema_js_1.queryRelationMetadata);
+    const indexes = new Map();
+    for (const relation of relations) {
+        const rows = dataset.rows[relation];
+        if (!Array.isArray(rows)) {
+            throw new Error(`Dataset is missing ${relation} rows`);
+        }
+        const localKeys = dataset.uniqueKeys[relation];
+        if (!Array.isArray(localKeys)) {
+            throw new Error(`Dataset is missing ${relation} unique keys`);
+        }
+        for (const key of localKeys) {
+            validateUniquePaths(relation, rows, key, `${relation} unique key`);
+        }
+    }
+    for (const relation of relations) {
+        const rows = dataset.rows[relation];
+        if (!Array.isArray(rows)) {
+            throw new Error(`Dataset is missing ${relation} rows`);
+        }
+        const edgeDefinitions = query_schema_js_1.queryRelationEdges[relation] ?? {};
+        const lookups = dataset.edges[relation];
+        if (lookups === undefined) {
+            throw new Error(`Dataset is missing ${relation} edges`);
+        }
+        const relationIndexes = new Map();
+        for (const [edge, definition] of Object.entries(edgeDefinitions)) {
+            const lookup = lookups[edge];
+            if (lookup === undefined) {
+                throw new Error(`Dataset is missing ${relation}.${edge} edge`);
+            }
+            else if (lookup.complete !== undefined && typeof lookup.complete !== "boolean") {
+                throw new Error(`Dataset ${relation}.${edge} completeness marker is invalid`);
+            }
+            const targetRows = dataset.rows[definition.target];
+            const buckets = new Map();
+            let sourcePrivateKeys;
+            if (lookup.privateKeys !== undefined) {
+                if (lookup.from !== undefined || lookup.to !== undefined) {
+                    throw new Error(`Dataset ${relation}.${edge} cannot mix public and private lookup keys`);
+                }
+                validatePrivateKeys(relation, edge, lookup.privateKeys, rows, targetRows);
+                sourcePrivateKeys = new Map(rows.map((row, index) => [row, lookup.privateKeys.source[index]]));
+                for (const [index, target] of targetRows.entries()) {
+                    const key = compositeKey(lookup.privateKeys.target[index]);
+                    buckets.set(key, [...(buckets.get(key) ?? []), target]);
+                }
+            }
+            else {
+                if (lookup.from === undefined || lookup.to === undefined) {
+                    throw new Error(`Dataset ${relation}.${edge} lookup is missing public paths`);
+                }
+                else if (lookup.from.length !== lookup.to.length) {
+                    throw new Error(`Dataset ${relation}.${edge} lookup arity differs`);
+                }
+                validatePaths(relation, rows, lookup.from, `${relation}.${edge} source`);
+                validatePaths(definition.target, targetRows, lookup.to, `${relation}.${edge} target`);
+                for (const target of targetRows) {
+                    const key = compositeKey(lookup.to.map((path) => atPath(target, path)));
+                    buckets.set(key, [...(buckets.get(key) ?? []), target]);
+                }
+            }
+            if (definition.cardinality === "one" && [...buckets.values()].some((targets) => targets.length > 1)) {
+                throw new Error(`Dataset ${relation}.${edge} has multiple to-one targets`);
+            }
+            else if (definition.cardinality === "one" && !definition.nullable && lookup.complete !== false) {
+                for (const [index, source] of rows.entries()) {
+                    const values = lookup.privateKeys === undefined
+                        ? lookup.from.map((path) => atPath(source, path))
+                        : lookup.privateKeys.source[index];
+                    if (values.some((value) => value === null || value === undefined) || !buckets.has(compositeKey(values))) {
+                        throw new Error(`Dataset ${relation}.${edge} has no target`);
+                    }
+                }
+            }
+            relationIndexes.set(edge, { targets: new Map([...buckets.entries()].map(([key, targets]) => [key, Object.freeze(targets)])), ...(sourcePrivateKeys === undefined ? {} : { sourcePrivateKeys }) });
+        }
+        if (Object.keys(lookups).some((edge) => edgeDefinitions[edge] === undefined)) {
+            throw new Error(`Dataset ${relation} declares an unknown edge`);
+        }
+        indexes.set(relation, relationIndexes);
+    }
+    datasetIndexes.set(dataset, indexes);
+    compiledSnapshots.set(input, dataset);
+    rawRowSnapshots.set(input, rowSnapshots);
+    compiledRowMembership.set(dataset, rowMembership);
+    return dataset;
+}
+/** Uses the factory index, compiling a legacy dataset on first use for compatibility. */
+function relatedQueryRows(dataset, relation, row, edge) {
+    const compiled = createQueryDataset(dataset);
+    const lookup = compiled.edges[relation]?.[edge];
+    const index = datasetIndexes.get(compiled)?.get(relation)?.get(edge);
+    if (lookup === undefined || index === undefined) {
+        throw new Error(`Missing deterministic lookup for ${relation}.${edge}`);
+    }
+    const snapshotRow = dataset === compiled
+        ? compiledRowMembership.get(compiled)?.get(relation)?.has(row) ? row : undefined
+        : rawRowSnapshots.get(dataset)?.get(relation)?.get(row);
+    if (snapshotRow === undefined) {
+        throw new Error(`Query row does not belong to ${relation} dataset`);
+    }
+    else if (lookup.complete === false) {
+        throw new IncompleteQueryEdgeError(relation, edge);
+    }
+    const values = lookup.privateKeys === undefined
+        ? lookup.from.map((path) => atPath(snapshotRow, path))
+        : index.sourcePrivateKeys?.get(snapshotRow);
+    return values === undefined || values.some((value) => value === null || value === undefined) ? emptyRows : index.targets.get(compositeKey(values)) ?? emptyRows;
+}
+function validatePrivateKeys(relation, edge, keys, sourceRows, targetRows) {
+    if (!Array.isArray(keys.source) || keys.source.length !== sourceRows.length) {
+        throw new Error(`Dataset ${relation}.${edge} private source length differs`);
+    }
+    else if (!Array.isArray(keys.target) || keys.target.length !== targetRows.length) {
+        throw new Error(`Dataset ${relation}.${edge} private target length differs`);
+    }
+    if (keys.source.length === 0 && keys.target.length === 0) {
+        return;
+    }
+    const arity = keys.source[0]?.length ?? keys.target[0]?.length;
+    if (arity === undefined || arity === 0 || !keys.source.every((key) => Array.isArray(key) && key.length === arity) || !keys.target.every((key) => Array.isArray(key) && key.length === arity)) {
+        throw new Error(`Dataset ${relation}.${edge} private lookup arity differs`);
+    }
+}
+function validateUniquePaths(relation, rows, paths, label) {
+    if (paths.length === 0) {
+        throw new Error(`Dataset ${label} is empty`);
+    }
+    validatePaths(relation, rows, paths, label);
+    const seen = new Set();
+    for (const row of rows) {
+        const key = compositeKey(paths.map((path) => atPath(row, path)));
+        if (seen.has(key)) {
+            throw new Error(`Dataset ${label} is not unique`);
+        }
+        seen.add(key);
+    }
+}
+function validatePaths(relation, rows, paths, label) {
+    for (const path of paths) {
+        if (!datasetPaths[relation].includes(path)) {
+            throw new Error(`Dataset ${label} path ${path} is invalid`);
+        }
+    }
+    for (const row of rows) {
+        for (const path of paths) {
+            if (!hasPath(row, path)) {
+                throw new Error(`Dataset ${label} path ${path} is invalid`);
+            }
+        }
+    }
+}
+function hasPath(value, path) {
+    let current = value;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || !Object.hasOwn(current, segment)) {
+            return false;
+        }
+        current = current[segment];
+    }
+    return true;
+}
+function atPath(value, path) {
+    return path.split(".").reduce((current, segment) => current !== null && typeof current === "object" ? current[segment] : undefined, value);
+}
+function compositeKey(values) {
+    return JSON.stringify(values.map((value) => value instanceof Date ? value.toISOString() : value instanceof Uint8Array ? Array.from(value) : value));
+}
+/** A Date which preserves Date's public read API but rejects mutation. */
+class ImmutableQueryDate extends Date {
+    /** Legacy Date API, absent from newer TypeScript lib declarations. */
+    setYear() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setTime() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setMilliseconds() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setSeconds() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setMinutes() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setHours() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setDate() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setMonth() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setFullYear() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCMilliseconds() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCSeconds() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCMinutes() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCHours() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCDate() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCMonth() {
+        throw new TypeError("Query dates are immutable");
+    }
+    setUTCFullYear() {
+        throw new TypeError("Query dates are immutable");
+    }
+}
+exports.ImmutableQueryDate = ImmutableQueryDate;
+/** Recursively clones and freezes query values without retaining mutable input references. */
+function immutableQueryValue(value) {
+    if (value instanceof Date) {
+        return immutableQueryDate(value);
+    }
+    else if (value instanceof Uint8Array) {
+        return immutableQueryBytes(value);
+    }
+    else if (Array.isArray(value)) {
+        return Object.freeze(value.map((entry) => immutableQueryValue(entry)));
+    }
+    else if (value !== null && typeof value === "object") {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, immutableQueryValue(entry)])));
+    }
+    return value;
+}
+/** A proxy has no [[DateValue]], so Date.prototype mutators cannot bypass this wrapper. */
+function immutableQueryDate(value) {
+    const target = new Date(value.getTime());
+    const mutation = () => {
+        throw new TypeError("Query dates are immutable");
+    };
+    const setters = new Set([
+        "setDate", "setFullYear", "setHours", "setMilliseconds", "setMinutes", "setMonth", "setSeconds", "setTime", "setUTCDate",
+        "setUTCFullYear", "setUTCHours", "setUTCMilliseconds", "setUTCMinutes", "setUTCMonth", "setUTCSeconds", "setYear",
+    ]);
+    return Object.freeze(new Proxy(target, {
+        set: mutation,
+        defineProperty: mutation,
+        deleteProperty: mutation,
+        setPrototypeOf: mutation,
+        get(inner, property) {
+            if (setters.has(String(property))) {
+                return mutation;
+            }
+            else if (property === Symbol.toStringTag) {
+                return "Date";
+            }
+            const member = Reflect.get(inner, property, inner);
+            return typeof member === "function" ? member.bind(inner) : member;
+        },
+    }));
+}
+/** Typed arrays cannot be frozen by JavaScript engines, so guard every write path. */
+function immutableQueryBytes(value) {
+    const bytes = new Uint8Array(value);
+    const mutation = () => {
+        throw new TypeError("Query bytes are immutable");
+    };
+    let proxy;
+    proxy = new Proxy(bytes, {
+        set: mutation,
+        defineProperty: mutation,
+        deleteProperty: mutation,
+        setPrototypeOf: mutation,
+        get(target, property) {
+            if (["copyWithin", "fill", "reverse", "set", "sort"].includes(String(property))) {
+                return mutation;
+            }
+            else if (property === "buffer") {
+                return target.buffer.slice(0);
+            }
+            else if (property === "subarray") {
+                return (...args) => immutableQueryBytes(target.subarray(...args));
+            }
+            else if (property === "slice") {
+                return (...args) => immutableQueryBytes(target.slice(...args));
+            }
+            else if (property === "valueOf") {
+                return () => proxy;
+            }
+            const member = Reflect.get(target, property, target);
+            return typeof member === "function" ? member.bind(target) : member;
+        },
+    });
+    return proxy;
+}