@distrohelena/canton-typescript-sdk 0.1.36 → 0.1.38

package/dist/query/canonical/in-memory-query-evaluator.js

@@ -0,0 +1,287 @@
+import { createQueryDataset, immutableQueryValue, relatedQueryRows } from "./query-dataset.js";
+import { queryRelationEdges, queryRelationMetadata } from "./query-schema.js";
+/** Reference evaluator for normalized canonical plans; it intentionally has no transport concerns. */
+export class InMemoryQueryEvaluator {
+    execute(dataset, query) {
+        const compiled = createQueryDataset(dataset);
+        switch (query.kind) {
+            case "findMany": return freeze(this.findMany(compiled, query));
+            case "findUnique": return freeze(this.findMany(compiled, { kind: "findMany", relation: query.relation, predicate: query.predicate, select: query.select, includes: query.includes, orderBy: [], skip: 0, take: 1, activeOnly: false })[0]);
+            case "count": return this.filtered(compiled, query.relation, query.predicate, query.parties, query.activeOnly).length;
+            case "aggregate": return freeze(this.aggregate(this.filtered(compiled, query.relation, query.predicate), query));
+            case "groupBy": return freeze(this.groupBy(compiled, query));
+        }
+    }
+    findMany(dataset, query) {
+        const rows = this.order(this.filtered(dataset, query.relation, query.predicate, query.parties, query.activeOnly), query.orderBy)
+            .slice(query.skip, query.take === undefined ? undefined : query.skip + query.take);
+        return rows.map((row) => this.shape(dataset, query.relation, row, query.select, query.includes));
+    }
+    filtered(dataset, relation, predicate, parties, activeOnly = false) {
+        return dataset.rows[relation].filter((row) => (!activeOnly || row.active === true)
+            && (parties === undefined || (Array.isArray(row.witnesses) && row.witnesses.some((party) => parties.includes(String(party)))))
+            && (predicate === undefined || this.matches(dataset, relation, row, predicate)));
+    }
+    matches(dataset, relation, row, predicate) {
+        switch (predicate.kind) {
+            case "and": return predicate.children.every((child) => this.matches(dataset, relation, row, child));
+            case "or": return predicate.children.some((child) => this.matches(dataset, relation, row, child));
+            case "not": return !this.matches(dataset, relation, row, predicate.child);
+            case "relation": {
+                const edge = queryRelationEdges[relation]?.[predicate.edge];
+                if (edge === undefined) {
+                    throw new Error(`Unknown ${relation}.${predicate.edge} edge`);
+                }
+                const related = this.related(dataset, relation, row, predicate.edge);
+                const result = related.map((target) => this.matches(dataset, edge.target, target, predicate.predicate));
+                return predicate.quantifier === "one" ? result[0] === true : predicate.quantifier === "some" ? result.some(Boolean) : predicate.quantifier === "none" ? !result.some(Boolean) : result.every(Boolean);
+            }
+            case "scalar": {
+                const actual = at(row, predicate.path);
+                const expected = predicate.value;
+                switch (predicate.operator) {
+                    case "equals": return actual !== null && actual !== undefined && expected !== null && expected !== undefined && equal(actual, expected);
+                    case "in": return actual !== null && actual !== undefined && Array.isArray(expected) && expected.some((candidate) => candidate !== null && candidate !== undefined && equal(actual, candidate));
+                    case "is": return actual === null || actual === undefined;
+                    case "isNot": return actual !== null && actual !== undefined;
+                    case "lt": return compare(actual, expected) < 0;
+                    case "lte": return compare(actual, expected) <= 0;
+                    case "gt": return compare(actual, expected) > 0;
+                    case "gte": return compare(actual, expected) >= 0;
+                    case "like": return typeof actual === "string" && typeof expected === "string" && sqlLike(actual, expected, false);
+                    case "ilike": return typeof actual === "string" && typeof expected === "string" && sqlLike(actual, expected, true);
+                    case "has": return Array.isArray(actual) && actual.some((entry) => equal(entry, expected));
+                }
+                return false;
+            }
+        }
+    }
+    related(dataset, relation, row, edge) {
+        return [...relatedQueryRows(dataset, relation, row, edge)];
+    }
+    shape(dataset, relation, row, selection, includes) {
+        const fields = selection?.fields ?? Object.keys(row);
+        const result = Object.fromEntries(fields.filter((field) => Object.hasOwn(row, field)).map((field) => [field, clone(row[field])]));
+        for (const projection of selection?.json ?? []) {
+            result[projection.name] = project(at(row, [projection.field, ...projection.path]), projection.as);
+        }
+        for (const include of includes) {
+            const targets = this.related(dataset, relation, row, include.edge).filter((target) => include.predicate === undefined || this.matches(dataset, include.relation, target, include.predicate));
+            const bounded = this.order(targets, include.orderBy).slice(include.skip, include.take === undefined ? undefined : include.skip + include.take)
+                .map((target) => this.shape(dataset, include.relation, target, include.select, include.includes));
+            result[include.edge] = include.cardinality === "many" ? bounded : (bounded[0] ?? null);
+        }
+        return result;
+    }
+    order(rows, orderBy) {
+        return rows.map((row, index) => ({ row, index })).sort((left, right) => {
+            for (const order of orderBy) {
+                const compared = postgresCompare(at(left.row, order.path), at(right.row, order.path), order.direction);
+                if (compared !== 0) {
+                    return compared;
+                }
+            }
+            return left.index - right.index;
+        }).map(({ row }) => row);
+    }
+    aggregate(rows, query) {
+        const metadata = queryRelationMetadata[query.relation];
+        const result = {};
+        if (query.aggregates.count) {
+            result.count = rows.length;
+        }
+        for (const operation of ["min", "max", "sum"]) {
+            if (query.aggregates[operation].length > 0) {
+                for (const field of query.aggregates[operation]) {
+                    if (!metadata.numericFields.includes(field)) {
+                        throw new Error(`${field} is not a numeric aggregate field of ${query.relation}`);
+                    }
+                }
+                result[operation] = Object.fromEntries(query.aggregates[operation].map((field) => [field, aggregate(rows.map((row) => at(row, [field])), operation)]));
+            }
+        }
+        return result;
+    }
+    groupBy(dataset, query) {
+        const groups = new Map();
+        for (const row of this.filtered(dataset, query.relation, query.predicate)) {
+            const keyVariants = query.by.map((key) => this.groupValues(dataset, query.relation, row, key));
+            for (const keys of cartesian(keyVariants)) {
+                const identity = JSON.stringify(keys.map(keyIdentity));
+                const group = groups.get(identity) ?? { keys, rows: [] };
+                group.rows.push(row);
+                groups.set(identity, group);
+            }
+        }
+        return [...groups.values()].map(({ keys, rows }) => {
+            const result = Object.fromEntries(query.by.map((key, index) => [groupName(key), clone(keys[index])]));
+            if (query.aggregates.count) {
+                result.count = rows.length;
+            }
+            for (const operation of ["min", "max", "sum"]) {
+                for (const field of query.aggregates[operation]) {
+                    result[`${operation}_${field}`] = aggregate(rows.map((row) => at(row, [field])), operation);
+                }
+            }
+            return result;
+        });
+    }
+    groupValues(dataset, relation, row, key) {
+        if (key.kind === "field") {
+            const value = at(row, key.path);
+            return Array.isArray(value) ? value : [value];
+        }
+        else if (key.kind === "json") {
+            return [project(at(row, [key.field, ...key.path]), key.as)];
+        }
+        else if (key.kind !== "bucket") {
+            return [];
+        }
+        const value = key.path.length === 1 ? at(row, key.path) : this.related(dataset, relation, row, key.path[0])[0] && at(this.related(dataset, relation, row, key.path[0])[0], [key.path[1]]);
+        return [bucket(value, key.bucket)];
+    }
+}
+function at(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (current === null || current === undefined || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+function clone(value) {
+    return immutableQueryValue(value);
+}
+function freeze(value) {
+    if (value === null || typeof value !== "object" || value instanceof Date || value instanceof Uint8Array) {
+        return value;
+    }
+    else if (Object.isFrozen(value)) {
+        return value;
+    }
+    for (const child of Object.values(value)) {
+        freeze(child);
+    }
+    return Object.freeze(value);
+}
+function equal(left, right) {
+    if (left instanceof Date) {
+        return left.toISOString() === (right instanceof Date ? right.toISOString() : String(right));
+    }
+    else if (right instanceof Date) {
+        return String(left) === right.toISOString();
+    }
+    else if (left instanceof Uint8Array || right instanceof Uint8Array) {
+        return JSON.stringify(Array.from(left)) === JSON.stringify(Array.from(right));
+    }
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function compare(left, right) {
+    if (left === null || left === undefined || right === null || right === undefined) {
+        return Number.NaN;
+    }
+    else if (left instanceof Date || right instanceof Date) {
+        const leftTime = left instanceof Date ? left.getTime() : new Date(String(left)).getTime();
+        const rightTime = right instanceof Date ? right.getTime() : new Date(String(right)).getTime();
+        return !Number.isFinite(leftTime) || !Number.isFinite(rightTime) ? Number.NaN : leftTime < rightTime ? -1 : leftTime > rightTime ? 1 : 0;
+    }
+    const leftValue = numeric(left) ?? String(left);
+    const rightValue = numeric(right) ?? String(right);
+    return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}
+function numeric(value) {
+    return typeof value === "string" && /^-?\d+$/.test(value) ? BigInt(value) : typeof value === "number" && Number.isFinite(value) ? BigInt(value) : undefined;
+}
+function postgresCompare(left, right, direction) {
+    const leftNull = left === null || left === undefined;
+    const rightNull = right === null || right === undefined;
+    if (leftNull || rightNull) {
+        if (leftNull && rightNull) {
+            return 0;
+        }
+        return leftNull ? (direction === "asc" ? 1 : -1) : (direction === "asc" ? -1 : 1);
+    }
+    const result = compare(left, right);
+    return direction === "asc" ? result : -result;
+}
+function sqlLike(value, pattern, insensitive) {
+    let expression = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "\\" && index + 1 < pattern.length) {
+            expression += escapeRegex(pattern[++index]);
+        }
+        else if (character === "%") {
+            expression += ".*";
+        }
+        else if (character === "_") {
+            expression += ".";
+        }
+        else {
+            expression += escapeRegex(character);
+        }
+    }
+    return new RegExp(`${expression}$`, insensitive ? "isu" : "su").test(value);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function project(value, as) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    else if (as === "boolean") {
+        return value === true || value === "true";
+    }
+    else if (as === "timestamp") {
+        return immutableQueryValue(value instanceof Date ? value : new Date(String(value)));
+    }
+    return String(value);
+}
+function aggregate(values, operation) {
+    const present = values.filter((value) => value !== null && value !== undefined);
+    if (present.length === 0) {
+        return null;
+    }
+    const numbers = present.map((value) => BigInt(String(value)));
+    if (operation === "sum") {
+        return numbers.reduce((total, value) => total + value, 0n).toString();
+    }
+    return numbers.reduce((winner, value) => operation === "min" ? value < winner ? value : winner : value > winner ? value : winner).toString();
+}
+function cartesian(parts) {
+    return parts.reduce((all, part) => all.flatMap((prefix) => part.map((value) => [...prefix, value])), [[]]);
+}
+function keyIdentity(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+function groupName(key) {
+    return key.kind === "field" ? key.path.join("_") : key.kind === "json" ? key.name : key.path.join("_") + "_" + key.bucket;
+}
+function bucket(value, unit) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const date = value instanceof Date ? new Date(value.getTime()) : new Date(String(value));
+    if (Number.isNaN(date.getTime())) {
+        return null;
+    }
+    else if (unit === "hour") {
+        date.setUTCMinutes(0, 0, 0);
+    }
+    else if (unit === "day") {
+        date.setUTCHours(0, 0, 0, 0);
+    }
+    else if (unit === "month") {
+        date.setUTCDate(1);
+        date.setUTCHours(0, 0, 0, 0);
+    }
+    else {
+        const day = date.getUTCDay() || 7;
+        date.setUTCDate(date.getUTCDate() - day + 1);
+        date.setUTCHours(0, 0, 0, 0);
+    }
+    return date;
+}

package/dist/query/canonical/public-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare function canonicalPublicNumericIdentity(identity: string): string;
+/** Frames multiple semantic components without a delimiter ambiguity. */
+export declare function canonicalPublicNumericIdentityParts(parts: readonly string[]): string;
+/** PostgreSQL expression exactly equivalent to {@link canonicalPublicNumericIdentity}. */
+export declare function compileCanonicalPublicNumericIdentitySql(text: string): string;
+/** PostgreSQL framing equivalent to {@link canonicalPublicNumericIdentityParts}. */
+export declare function compileCanonicalPublicNumericIdentityPartsSql(parts: readonly string[]): string;

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

@@ -0,0 +1,35 @@
+import { Buffer } from "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.
+ */
+export function canonicalPublicNumericIdentity(identity) {
+    const bytes = 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. */
+export function canonicalPublicNumericIdentityParts(parts) {
+    return canonicalPublicNumericIdentity(parts.map((part) => `${Buffer.byteLength(part, "utf8")}:${part}`).join(""));
+}
+/** PostgreSQL expression exactly equivalent to {@link canonicalPublicNumericIdentity}. */
+export 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}. */
+export function compileCanonicalPublicNumericIdentityPartsSql(parts) {
+    return `concat(${parts.flatMap((part) => [`octet_length(convert_to((${part})::text, 'UTF8'))`, "':'", `(${part})::text`]).join(", ")})`;
+}

package/dist/query/canonical/query-ast.d.ts

@@ -0,0 +1,104 @@
+import type { QueryRelation } from "./query-schema.js";
+export type ScalarOperator = "equals" | "in" | "is" | "isNot" | "lt" | "lte" | "gt" | "gte" | "like" | "ilike" | "has";
+export type QueryOrderDirection = "asc" | "desc";
+export type QueryPredicate = {
+    readonly kind: "and" | "or";
+    readonly children: readonly QueryPredicate[];
+} | {
+    readonly kind: "not";
+    readonly child: QueryPredicate;
+} | {
+    readonly kind: "scalar";
+    readonly path: readonly string[];
+    readonly operator: ScalarOperator;
+    readonly value: unknown;
+} | {
+    readonly kind: "relation";
+    readonly edge: string;
+    readonly quantifier: "one" | "some" | "none" | "every";
+    readonly predicate: QueryPredicate;
+};
+export interface NormalizedOrder {
+    readonly path: readonly string[];
+    readonly direction: QueryOrderDirection;
+}
+export interface NormalizedJsonSelection {
+    readonly name: string;
+    readonly field: string;
+    readonly path: readonly string[];
+    readonly as: "text" | "numeric" | "boolean" | "timestamp";
+}
+export interface NormalizedSelection {
+    readonly fields: readonly string[];
+    readonly json: readonly NormalizedJsonSelection[];
+}
+export interface NormalizedInclude {
+    readonly edge: string;
+    readonly relation: QueryRelation;
+    readonly cardinality: "one" | "many";
+    readonly predicate?: QueryPredicate;
+    readonly select?: NormalizedSelection;
+    readonly includes: readonly NormalizedInclude[];
+    readonly orderBy: readonly NormalizedOrder[];
+    readonly skip: number;
+    readonly take?: number;
+}
+export interface NormalizedFindManyQuery {
+    readonly kind: "findMany";
+    readonly relation: QueryRelation;
+    readonly parties?: readonly string[];
+    readonly predicate?: QueryPredicate;
+    readonly select?: NormalizedSelection;
+    readonly includes: readonly NormalizedInclude[];
+    readonly orderBy: readonly NormalizedOrder[];
+    readonly skip: number;
+    readonly take?: number;
+    readonly activeOnly: boolean;
+}
+export interface NormalizedFindUniqueQuery {
+    readonly kind: "findUnique";
+    readonly relation: QueryRelation;
+    readonly predicate: QueryPredicate;
+    readonly select?: NormalizedSelection;
+    readonly includes: readonly NormalizedInclude[];
+}
+export interface NormalizedCountQuery {
+    readonly kind: "count";
+    readonly relation: QueryRelation;
+    readonly parties?: readonly string[];
+    readonly predicate?: QueryPredicate;
+    readonly activeOnly: boolean;
+}
+export interface NormalizedAggregateSelection {
+    readonly count: boolean;
+    readonly min: readonly string[];
+    readonly max: readonly string[];
+    readonly sum: readonly string[];
+}
+export interface NormalizedAggregateQuery {
+    readonly kind: "aggregate";
+    readonly relation: QueryRelation;
+    readonly predicate?: QueryPredicate;
+    readonly aggregates: NormalizedAggregateSelection;
+}
+export type NormalizedGroupKey = {
+    readonly kind: "field";
+    readonly path: readonly string[];
+} | {
+    readonly kind: "json";
+    readonly field: string;
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly as: "text" | "numeric" | "boolean" | "timestamp";
+} | {
+    readonly kind: "bucket";
+    readonly path: readonly string[];
+    readonly bucket: "hour" | "day" | "week" | "month";
+};
+export interface NormalizedGroupByQuery {
+    readonly kind: "groupBy";
+    readonly relation: QueryRelation;
+    readonly predicate?: QueryPredicate;
+    readonly by: readonly NormalizedGroupKey[];
+    readonly aggregates: NormalizedAggregateSelection;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/query/canonical/query-dataset.d.ts

@@ -0,0 +1,63 @@
+import { type QueryRelation } from "./query-schema.js";
+/** Canonical rows are deliberately source-neutral; public ids are semantic values. */
+export type QueryRow = Readonly<Record<string, unknown>>;
+export type QueryRowSets = Readonly<Record<QueryRelation, readonly QueryRow[]>>;
+/** A directional join from the owning row to a target relation row. */
+export interface QueryEdgeLookup {
+    /** Whether the snapshot contains every target needed to traverse this edge. Defaults to true. */
+    readonly complete?: boolean;
+    /** Public row paths, retained for legacy datasets. */
+    readonly from?: readonly string[];
+    readonly to?: readonly string[];
+    /**
+     * Snapshot-local join values aligned by source/target row position. They are
+     * deliberately stored beside the rows rather than attached to them so query
+     * results expose only schema fields.
+     */
+    readonly privateKeys?: Readonly<{
+        readonly source: readonly (readonly unknown[])[];
+        readonly target: readonly (readonly unknown[])[];
+    }>;
+}
+export type QueryEdgeLookups = Readonly<Partial<Record<QueryRelation, Readonly<Record<string, QueryEdgeLookup>>>>>;
+/**
+ * A deterministic, in-memory canonical data source. `uniqueKeys` documents
+ * public row uniqueness only; the evaluator never gives those fields special semantics.
+ */
+export interface QueryDataset {
+    readonly rows: QueryRowSets;
+    readonly edges: QueryEdgeLookups;
+    readonly uniqueKeys: Readonly<Record<QueryRelation, readonly (readonly string[])[]>>;
+}
+/** An edge is declared by the schema but its targets were unavailable in this snapshot. */
+export declare class IncompleteQueryEdgeError extends Error {
+    readonly relation: QueryRelation;
+    readonly edge: string;
+    constructor(relation: QueryRelation, edge: string);
+}
+/** Validates and freezes source-neutral rows, then builds deterministic edge indexes once. */
+export declare function createQueryDataset(input: QueryDataset): QueryDataset;
+/** Uses the factory index, compiling a legacy dataset on first use for compatibility. */
+export declare function relatedQueryRows(dataset: QueryDataset, relation: QueryRelation, row: QueryRow, edge: string): readonly QueryRow[];
+/** A Date which preserves Date's public read API but rejects mutation. */
+export declare class ImmutableQueryDate extends Date {
+    /** Legacy Date API, absent from newer TypeScript lib declarations. */
+    setYear(): never;
+    setTime(): never;
+    setMilliseconds(): never;
+    setSeconds(): never;
+    setMinutes(): never;
+    setHours(): never;
+    setDate(): never;
+    setMonth(): never;
+    setFullYear(): never;
+    setUTCMilliseconds(): never;
+    setUTCSeconds(): never;
+    setUTCMinutes(): never;
+    setUTCHours(): never;
+    setUTCDate(): never;
+    setUTCMonth(): never;
+    setUTCFullYear(): never;
+}
+/** Recursively clones and freezes query values without retaining mutable input references. */
+export declare function immutableQueryValue<T>(value: T): T;