@distrohelena/canton-typescript-sdk 0.1.4 → 0.1.6

package/dist/query/pqs/pqs-query-client.js

@@ -0,0 +1,324 @@
+import { QuerySource } from "../query-source.js";
+import { PqsQueryError } from "../errors/pqs-query-error.js";
+import { compileContractFindMany } from "./pqs-sql-compiler.js";
+import { pqsRelationMetadata, } from "./pqs-schema-profile.js";
+import { assertReadOnlySql } from "./read-only-sql.js";
+export class PqsQueryClient {
+    executor;
+    profile;
+    ready;
+    source = QuerySource.pqs;
+    contracts = {
+        findMany: (args = {}) => this.findContractsAsync(args),
+        findUnique: (args) => this.findContractsAsync({
+            where: { contractId: { equals: args.where.contractId } },
+            select: args.select,
+            take: 1,
+        }).then((rows) => rows[0]),
+        count: async (args = {}) => (await this.findContractsAsync(args)).length,
+        aggregate: async (args) => this.aggregateContractsAsync(args),
+    };
+    contractTypes = this.createPhysicalDelegate("__contract_tpe");
+    events = this.createPhysicalDelegate("__events");
+    exercises = this.createPhysicalDelegate("__exercises", false);
+    exerciseTypes = this.createPhysicalDelegate("__exercise_tpe");
+    packages = this.createPhysicalDelegate("__packages");
+    transactions = this.createPhysicalDelegate("__transactions");
+    watermark = this.createPhysicalDelegate("__watermark");
+    constructor(executor, profile, ready = Promise.resolve()) {
+        this.executor = executor;
+        this.profile = profile;
+        this.ready = ready;
+    }
+    async $queryRaw(sql, values = []) {
+        assertReadOnlySql(sql);
+        try {
+            await this.ready;
+            return (await this.executor.query(sql, values)).rows;
+        }
+        catch (cause) {
+            throw this.wrap("$queryRaw", cause);
+        }
+    }
+    createPhysicalDelegate(relation, hasUnique = true) {
+        const metadata = pqsRelationMetadata[relation];
+        const findMany = async (args = {}) => this.readPhysicalAsync(relation, metadata, args);
+        const delegate = {
+            findMany,
+            count: async (args = {}) => {
+                const { where, values } = this.compileWhere(relation, metadata, args.where);
+                try {
+                    await this.ready;
+                    const result = await this.executor.query(`select count(*)::text as count from ${this.profile.relation(relation)}${where}`, values);
+                    return Number(result.rows[0]?.count ?? 0);
+                }
+                catch (cause) {
+                    throw this.wrap(`${relation}.count`, cause);
+                }
+            },
+            aggregate: async (args) => this.aggregatePhysicalAsync(relation, metadata, args),
+        };
+        if (!hasUnique) {
+            return delegate;
+        }
+        return {
+            ...delegate,
+            findUnique: async (args) => {
+                this.assertUniqueWhere(relation, metadata, args.where);
+                return findMany({
+                    where: Object.fromEntries(Object.entries(args.where).map(([field, value]) => [field, { equals: value }])),
+                    select: args.select,
+                    take: 1,
+                }).then((rows) => rows[0]);
+            },
+        };
+    }
+    async readPhysicalAsync(relation, metadata, args) {
+        this.assertPage(args);
+        const selected = this.selectedFields(relation, metadata, args.select);
+        const { where, values } = this.compileWhere(relation, metadata, args.where);
+        const orderBy = this.compileOrderBy(relation, metadata, args.orderBy);
+        const parameters = [...values];
+        const add = (value) => {
+            parameters.push(value);
+            return `$${parameters.length}`;
+        };
+        const limit = args.take === undefined ? "" : ` limit ${add(args.take)}`;
+        const offset = args.skip === undefined ? "" : ` offset ${add(args.skip)}`;
+        const selection = selected.map(([field, column]) => `"${column}" as "${field}"`).join(", ");
+        try {
+            await this.ready;
+            const result = await this.executor.query(`select ${selection} from ${this.profile.relation(relation)}${where}${orderBy}${limit}${offset}`, parameters);
+            return result.rows.map((row) => this.mapPhysicalRow(row, metadata, selected));
+        }
+        catch (cause) {
+            throw this.wrap(`${relation}.findMany`, cause);
+        }
+    }
+    async aggregatePhysicalAsync(relation, metadata, args) {
+        const { where, values } = this.compileWhere(relation, metadata, args.where);
+        const selected = [];
+        if (args.count) {
+            selected.push("count(*)::text as count");
+        }
+        for (const [operation, fields] of [["min", args.min], ["max", args.max], ["sum", args.sum]]) {
+            for (const field of fields ?? []) {
+                this.assertNumericField(relation, metadata, field);
+                selected.push(`${operation}("${metadata.fields[field]}")::text as "${operation}_${field}"`);
+            }
+        }
+        if (selected.length === 0) {
+            throw new Error("aggregate must request at least one result");
+        }
+        try {
+            await this.ready;
+            const row = (await this.executor.query(`select ${selected.join(", ")} from ${this.profile.relation(relation)}${where}`, values)).rows[0] ?? {};
+            const result = {};
+            if (args.count) {
+                result.count = Number(row.count ?? 0);
+            }
+            for (const [operation, fields] of [["min", args.min], ["max", args.max], ["sum", args.sum]]) {
+                if (fields !== undefined) {
+                    result[operation] = Object.fromEntries(fields.map((field) => [field, nullableString(row[`${operation}_${field}`])]));
+                }
+            }
+            return result;
+        }
+        catch (cause) {
+            throw this.wrap(`${relation}.aggregate`, cause);
+        }
+    }
+    compileWhere(relation, metadata, filters) {
+        const values = [];
+        const add = (value) => {
+            values.push(value);
+            return `$${values.length}`;
+        };
+        const compile = (expression) => {
+            const conditions = [];
+            for (const [field, filter] of Object.entries(expression ?? {})) {
+                if (field === "and" || field === "or") {
+                    if (!Array.isArray(filter))
+                        throw new Error(`${field} must be an array`);
+                    conditions.push(filter.length ? `(${filter.map((child) => compile(child)).join(` ${field} `)})` : field === "and" ? "true" : "false");
+                    continue;
+                }
+                if (field === "not") {
+                    if (filter === null || Array.isArray(filter) || typeof filter !== "object")
+                        throw new Error("not must be an expression");
+                    conditions.push(`not (${compile(filter)})`);
+                    continue;
+                }
+                const column = this.field(relation, metadata, field);
+                if (filter === null || Array.isArray(filter) || typeof filter !== "object")
+                    throw new Error(`${field} must be a filter`);
+                const scalar = filter;
+                if (scalar.is === null) {
+                    conditions.push(`"${column}" is null`);
+                }
+                if (scalar.isNot === null) {
+                    conditions.push(`"${column}" is not null`);
+                }
+                if (scalar.equals !== undefined) {
+                    conditions.push(`"${column}" = ${add(scalar.equals)}`);
+                }
+                if (scalar.in !== undefined) {
+                    conditions.push(scalar.in.length === 0 ? "false" : `"${column}" = any(${add(scalar.in)})`);
+                }
+                if (scalar.has !== undefined) {
+                    if (!metadata.arrayFields.includes(field)) {
+                        throw new Error(`${field} is not an array field of ${relation}`);
+                    }
+                    conditions.push(`${add(scalar.has)} = any("${column}")`);
+                }
+                for (const [operator, value] of [["lt", scalar.lt], ["lte", scalar.lte], ["gt", scalar.gt], ["gte", scalar.gte], ["like", scalar.like], ["ilike", scalar.ilike]]) {
+                    if (value === undefined)
+                        continue;
+                    if ((operator === "like" || operator === "ilike") && !metadata.stringFields?.includes(field))
+                        throw new Error(`${field} does not support ${operator}`);
+                    if ((operator !== "like" && operator !== "ilike") && !metadata.numericFields.includes(field) && !metadata.dateFields.includes(field) && !metadata.stringFields?.includes(field))
+                        throw new Error(`${field} does not support ${operator}`);
+                    conditions.push(`"${column}" ${operator === "lte" ? "<=" : operator === "gte" ? ">=" : operator} ${add(value)}`);
+                }
+            }
+            return conditions.length ? conditions.join(" and ") : "true";
+        };
+        const where = compile(filters);
+        return { where: where === "true" ? "" : ` where ${where}`, values };
+    }
+    selectedFields(relation, metadata, select) {
+        if (select === undefined) {
+            return Object.entries(metadata.fields);
+        }
+        const selected = Object.entries(select).filter(([, enabled]) => enabled).map(([field]) => [field, this.field(relation, metadata, field)]);
+        if (selected.length === 0) {
+            throw new Error("select must include at least one field");
+        }
+        return selected;
+    }
+    compileOrderBy(relation, metadata, orderBy) {
+        if (orderBy === undefined) {
+            return "";
+        }
+        const entries = Object.entries(orderBy);
+        if (entries.length !== 1) {
+            throw new Error("orderBy must specify exactly one field");
+        }
+        const [field, direction] = entries[0];
+        if (direction !== "asc" && direction !== "desc") {
+            throw new Error("orderBy direction must be asc or desc");
+        }
+        return ` order by "${this.field(relation, metadata, field)}" ${direction}`;
+    }
+    assertUniqueWhere(relation, metadata, where) {
+        const fields = Object.keys(where).sort();
+        const matches = metadata.uniqueKeys.some((key) => [...key].sort().join("\0") === fields.join("\0"));
+        if (!matches) {
+            throw new Error(`where is not a stable unique key of ${relation}`);
+        }
+    }
+    assertNumericField(relation, metadata, field) {
+        if (!metadata.numericFields.includes(field)) {
+            throw new Error(`${field} is not a numeric aggregate field of ${relation}`);
+        }
+    }
+    field(relation, metadata, field) {
+        const column = metadata.fields[field];
+        if (column === undefined) {
+            throw new Error(`${field} is not a field of ${relation}`);
+        }
+        return column;
+    }
+    assertPage(args) {
+        for (const [name, value] of [["take", args.take], ["skip", args.skip]]) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+                throw new Error(`${name} must be a non-negative integer`);
+            }
+        }
+    }
+    mapPhysicalRow(row, metadata, fields) {
+        return Object.fromEntries(fields
+            .filter(([field]) => Object.hasOwn(row, field))
+            .map(([field]) => [field, mapPhysicalValue(row[field], metadata, field)]));
+    }
+    async findContractsAsync(args) {
+        const compiled = compileContractFindMany(args, this.profile);
+        try {
+            const rows = (await this.executor.query(compiled.text, compiled.values)).rows.map(mapContractRow);
+            const select = "select" in args ? args.select : undefined;
+            if (select === undefined) {
+                return rows;
+            }
+            const fields = Object.entries(select).filter(([, enabled]) => enabled).map(([field]) => field);
+            if (fields.length === 0) {
+                throw new Error("select must include at least one field");
+            }
+            return rows.map((row) => Object.fromEntries(fields.map((field) => [field, row[field]])));
+        }
+        catch (cause) {
+            throw this.wrap("contracts.findMany", cause);
+        }
+    }
+    async aggregateContractsAsync(args) {
+        if (!args.count && args.min === undefined && args.max === undefined && args.sum === undefined) {
+            throw new Error("aggregate must request at least one result");
+        }
+        const rows = await this.findContractsAsync({ where: args.where });
+        const result = {};
+        if (args.count) {
+            result.count = rows.length;
+        }
+        for (const [operation, fields] of [["min", args.min], ["max", args.max], ["sum", args.sum]]) {
+            if (fields !== undefined) {
+                result[operation] = Object.fromEntries(fields.map((field) => [field, aggregateNumeric(rows.map((row) => row[field]), operation)]));
+            }
+        }
+        return result;
+    }
+    wrap(operation, cause) {
+        return new PqsQueryError({ operation, code: getPqsCode(cause), cause });
+    }
+}
+function mapPhysicalValue(value, metadata, field) {
+    if (value === null || value === undefined) {
+        return value ?? null;
+    }
+    else if (metadata.numericFields.includes(field)) {
+        return String(value);
+    }
+    else if (metadata.dateFields.includes(field)) {
+        return value instanceof Date ? value : new Date(String(value));
+    }
+    else if (metadata.binaryFields.includes(field)) {
+        return value instanceof Uint8Array ? value : new Uint8Array(value);
+    }
+    else if (metadata.arrayFields.includes(field)) {
+        return Array.isArray(value) ? value.map(String) : [];
+    }
+    return value;
+}
+function mapContractRow(row) {
+    return { contractId: String(row.contract_id), templateId: { packageId: String(row.template_package_id), moduleName: String(row.template_module_name), entityName: String(row.template_entity_name) }, packageId: nullableString(row.package_id), payload: row.payload, witnesses: stringArray(row.witnesses), createdEventOffset: String(row.created_event_offset), createdAt: nullableDate(row.created_at), archivedEventOffset: nullableString(row.archived_event_offset), archivedAt: nullableDate(row.archived_at), active: row.active === true };
+}
+function nullableString(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function nullableDate(value) {
+    return value === null || value === undefined ? null : value instanceof Date ? value : new Date(String(value));
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.map(String) : [];
+}
+function getPqsCode(cause) {
+    return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+}
+function aggregateNumeric(values, operation) {
+    const numbers = values.filter((value) => value !== null).map(BigInt);
+    if (numbers.length === 0) {
+        return null;
+    }
+    else if (operation === "sum") {
+        return numbers.reduce((total, value) => total + value, 0n).toString();
+    }
+    return numbers.reduce((result, value) => operation === "min" ? value < result ? value : result : value > result ? value : result).toString();
+}

package/dist/query/pqs/pqs-schema-profile.d.ts

@@ -0,0 +1,25 @@
+export declare const requiredPqsRelations: readonly ["__contracts", "__contract_tpe", "__events", "__exercises", "__exercise_tpe", "__packages", "__transactions", "__watermark"];
+export type PqsRelation = (typeof requiredPqsRelations)[number];
+export interface PqsRelationMetadata {
+    readonly fields: Readonly<Record<string, string>>;
+    readonly uniqueKeys: readonly (readonly string[])[];
+    readonly numericFields: readonly string[];
+    readonly arrayFields: readonly string[];
+    readonly dateFields: readonly string[];
+    readonly binaryFields: readonly string[];
+    readonly stringFields?: readonly string[];
+}
+export declare const pqsRelationMetadata: Readonly<Record<PqsRelation, PqsRelationMetadata>>;
+export declare const requiredPqsColumns: Readonly<Record<PqsRelation, readonly string[]>>;
+export declare class PqsSchemaProfileV1 {
+    readonly schema: string;
+    constructor(schema?: string);
+    relation(relation: PqsRelation): string;
+}
+export interface PqsSchemaClient {
+    query(query: string, values: readonly unknown[]): Promise<{
+        readonly rows: readonly Record<string, unknown>[];
+    }>;
+}
+export declare function validatePqsSchemaAsync(client: PqsSchemaClient, profile: PqsSchemaProfileV1): Promise<void>;
+export declare function assertPqsSchemaIdentifier(schema: string): void;

package/dist/query/pqs/pqs-schema-profile.js

@@ -0,0 +1,120 @@
+import { PqsSchemaProfileError } from "../errors/pqs-schema-profile-error.js";
+const schemaIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const requiredPqsRelations = [
+    "__contracts",
+    "__contract_tpe",
+    "__events",
+    "__exercises",
+    "__exercise_tpe",
+    "__packages",
+    "__transactions",
+    "__watermark",
+];
+export const pqsRelationMetadata = {
+    __contracts: { fields: {}, uniqueKeys: [["contractId"]], numericFields: ["createdEventOffset", "archivedEventOffset"], arrayFields: ["witnesses"], dateFields: ["createdAt", "archivedAt"], binaryFields: [] },
+    __contract_tpe: { fields: { pk: "pk", payloadType: "payload_type", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn" }, uniqueKeys: [["pk"]], numericFields: ["pk"], arrayFields: ["aliases"], dateFields: [], binaryFields: [] },
+    __events: { fields: { pk: "pk", txIx: "tx_ix", eventId: "event_id", type: "type" }, uniqueKeys: [["pk"]], numericFields: ["pk", "txIx"], arrayFields: [], dateFields: [], binaryFields: [], stringFields: ["eventId", "type"] },
+    __exercises: { fields: { tpePk: "tpe_pk", contractTpePk: "contract_tpe_pk", exerciseEventPk: "exercise_event_pk", exercisedAtIx: "exercised_at_ix", contractId: "contract_id", argument: "argument", result: "result", redactionId: "redaction_id", packagePk: "package_pk", controllers: "controllers", lastDescendantNodeId: "last_descendant_node_id", witnesses: "witnesses" }, uniqueKeys: [], numericFields: ["tpePk", "contractTpePk", "exerciseEventPk", "exercisedAtIx", "packagePk", "lastDescendantNodeId"], arrayFields: ["controllers", "witnesses"], dateFields: [], binaryFields: [] },
+    __exercise_tpe: { fields: { pk: "pk", choice: "choice", consuming: "consuming", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn", choiceFqn: "choice_fqn" }, uniqueKeys: [["pk"]], numericFields: ["pk"], arrayFields: ["aliases"], dateFields: [], binaryFields: [] },
+    __packages: { fields: { pk: "pk", name: "name", version: "version", id: "id" }, uniqueKeys: [["pk"], ["id"]], numericFields: ["pk"], arrayFields: [], dateFields: [], binaryFields: [], stringFields: ["name", "version", "id"] },
+    __transactions: { fields: { ix: "ix", offset: "offset", transactionId: "transaction_id", effectiveAt: "effective_at", workflowId: "workflow_id", domainId: "domain_id", traceContext: "trace_context", externalTransactionHash: "external_transaction_hash", paidTrafficCost: "paid_traffic_cost" }, uniqueKeys: [["ix"], ["offset"]], numericFields: ["ix", "offset", "paidTrafficCost"], arrayFields: [], dateFields: ["effectiveAt"], binaryFields: ["externalTransactionHash"] },
+    __watermark: { fields: { singleton: "singleton", ix: "ix", offset: "offset", instanceId: "instance_id" }, uniqueKeys: [["singleton"]], numericFields: ["ix", "offset"], arrayFields: [], dateFields: [], binaryFields: [] },
+};
+export const requiredPqsColumns = {
+    __contracts: [
+        "tpe_pk",
+        "create_event_pk",
+        "created_at_ix",
+        "archive_event_pk",
+        "archived_at_ix",
+        "life_ix",
+        "contract_id",
+        "payload",
+        "contract_key",
+        "metadata",
+        "redaction_id",
+        "package_pk",
+        "signatories",
+        "observers",
+        "witnesses",
+        "divulged_only",
+        "creation_package_id",
+        "contract_key_hash",
+    ],
+    __contract_tpe: [
+        "pk",
+        "payload_type",
+        "aliases",
+        "package_name",
+        "module_name",
+        "entity_name",
+        "template_fqn",
+    ],
+    __events: ["pk", "tx_ix", "event_id", "type"],
+    __exercises: [
+        "tpe_pk",
+        "contract_tpe_pk",
+        "exercise_event_pk",
+        "exercised_at_ix",
+        "contract_id",
+        "argument",
+        "result",
+        "redaction_id",
+        "package_pk",
+        "controllers",
+        "last_descendant_node_id",
+        "witnesses",
+    ],
+    __exercise_tpe: [
+        "pk",
+        "choice",
+        "consuming",
+        "aliases",
+        "package_name",
+        "module_name",
+        "entity_name",
+        "template_fqn",
+        "choice_fqn",
+    ],
+    __packages: ["pk", "name", "version", "id"],
+    __transactions: [
+        "ix",
+        "offset",
+        "transaction_id",
+        "effective_at",
+        "workflow_id",
+        "domain_id",
+        "trace_context",
+        "external_transaction_hash",
+        "paid_traffic_cost",
+    ],
+    __watermark: ["singleton", "ix", "offset", "instance_id"],
+};
+export class PqsSchemaProfileV1 {
+    schema;
+    constructor(schema = "public") {
+        assertPqsSchemaIdentifier(schema);
+        this.schema = schema;
+    }
+    relation(relation) {
+        return `${quoteIdentifier(this.schema)}.${quoteIdentifier(relation)}`;
+    }
+}
+export async function validatePqsSchemaAsync(client, profile) {
+    const result = await client.query("select table_name, column_name from information_schema.columns where table_schema = $1 and table_name = any($2::text[])", [profile.schema, requiredPqsRelations]);
+    const actual = new Set(result.rows.map((row) => `${String(row.table_name)}.${String(row.column_name)}`));
+    const missing = requiredPqsRelations.flatMap((relation) => requiredPqsColumns[relation]
+        .filter((column) => !actual.has(`${relation}.${column}`))
+        .map((column) => `${relation}.${column}`));
+    if (missing.length > 0) {
+        throw new PqsSchemaProfileError(`PQS schema does not match v1 profile; missing: ${missing.join(", ")}`);
+    }
+}
+export function assertPqsSchemaIdentifier(schema) {
+    if (!schemaIdentifier.test(schema)) {
+        throw new PqsSchemaProfileError(`Invalid PQS schema identifier: ${schema}`);
+    }
+}
+function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}

package/dist/query/pqs/pqs-sql-compiler.d.ts

@@ -0,0 +1,7 @@
+import { ContractFindManyArgs } from "../model-types.js";
+import { PqsSchemaProfileV1 } from "./pqs-schema-profile.js";
+export interface CompiledPqsQuery {
+    readonly text: string;
+    readonly values: readonly unknown[];
+}
+export declare function compileContractFindMany(args: ContractFindManyArgs, profile: PqsSchemaProfileV1): CompiledPqsQuery;

package/dist/query/pqs/pqs-sql-compiler.js

@@ -0,0 +1,132 @@
+import { assertQueryPageArgs, } from "../model-types.js";
+export function compileContractFindMany(args, profile) {
+    assertQueryPageArgs(args);
+    const values = [];
+    const addValue = (value) => {
+        values.push(value);
+        return `$${values.length}`;
+    };
+    const conditions = [];
+    const where = args.where === undefined ? undefined : compileWhere(args.where, addValue);
+    if (where !== undefined)
+        conditions.push(where);
+    if (args.parties !== undefined) {
+        conditions.push(`contract_row.witnesses && ${addValue(args.parties)}::text[]`);
+    }
+    const orderBy = compileOrderBy(args.orderBy);
+    const whereSql = conditions.length === 0 ? "" : `where ${conditions.join(" and ")}`;
+    const limitSql = args.take === undefined ? "" : `limit ${addValue(args.take)}`;
+    const offsetSql = args.skip === undefined ? "" : `offset ${addValue(args.skip)}`;
+    return {
+        text: `select
+  contract_row.contract_id as contract_id,
+  contract_row.creation_package_id as package_id,
+  contract_row.payload,
+  contract_row.witnesses,
+  contract_row.created_at_ix::text as created_event_offset,
+  created_tx.effective_at as created_at,
+  contract_row.archived_at_ix::text as archived_event_offset,
+  archived_tx.effective_at as archived_at,
+  contract_row.archived_at_ix is null as active,
+  contract_row.creation_package_id as template_package_id,
+  contract_tpe_row.module_name as template_module_name,
+  contract_tpe_row.entity_name as template_entity_name
+from ${profile.relation("__contracts")} contract_row
+join ${profile.relation("__contract_tpe")} contract_tpe_row on contract_tpe_row.pk = contract_row.tpe_pk
+left join ${profile.relation("__transactions")} created_tx on created_tx.ix = contract_row.created_at_ix
+left join ${profile.relation("__transactions")} archived_tx on archived_tx.ix = contract_row.archived_at_ix
+${whereSql}
+${orderBy}
+${limitSql}
+${offsetSql}`,
+        values,
+    };
+}
+function compileWhere(where, addValue) {
+    const columns = { contractId: "contract_row.contract_id", packageId: "contract_row.creation_package_id", createdEventOffset: "contract_row.created_at_ix", createdAt: "created_tx.effective_at", archivedEventOffset: "contract_row.archived_at_ix", archivedAt: "archived_tx.effective_at" };
+    const parts = [];
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "and" || key === "or") {
+            if (!Array.isArray(value))
+                throw new Error(`${key} must be an array`);
+            parts.push(value.length === 0 ? key === "and" ? "true" : "false" : `(${value.map((child) => compileWhere(child, addValue)).join(` ${key} `)})`);
+            continue;
+        }
+        if (key === "not") {
+            parts.push(`not (${compileWhere(value, addValue)})`);
+            continue;
+        }
+        if (key === "active") {
+            const active = typeof value === "boolean" ? value : value.equals;
+            if (typeof active !== "boolean")
+                throw new Error("active supports only equals");
+            parts.push(active ? "contract_row.archived_at_ix is null" : "contract_row.archived_at_ix is not null");
+            continue;
+        }
+        if (key === "witnesses") {
+            const has = value.has;
+            if (has === undefined)
+                throw new Error("witnesses supports only has");
+            parts.push(`${addValue(has)} = any(contract_row.witnesses)`);
+            continue;
+        }
+        if (key === "payload") {
+            const payload = value;
+            const path = payload.path;
+            if (typeof path !== "string" || path.split(".").some((x) => x.length === 0))
+                throw new Error("payload path must contain non-empty segments");
+            const ops = ["equals", "lt", "lte", "gt", "gte", "like", "ilike"].filter((op) => payload[op] !== undefined);
+            if (ops.length !== 1 || typeof payload[ops[0]] !== "string")
+                throw new Error("payload requires exactly one string predicate");
+            const op = { equals: "=", lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[ops[0]];
+            parts.push(`contract_row.payload #>> ${addValue(path.split("."))}::text[] ${op} ${addValue(payload[ops[0]])}`);
+            continue;
+        }
+        if (key === "templateId") {
+            const fields = { packageId: "contract_row.creation_package_id", moduleName: "contract_tpe_row.module_name", entityName: "contract_tpe_row.entity_name" };
+            for (const [name, filter] of Object.entries(value))
+                for (const [op, operand] of Object.entries(filter)) {
+                    const sql = { equals: "=", lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[op];
+                    if (fields[name] === undefined || sql === undefined)
+                        throw new Error("invalid templateId filter");
+                    parts.push(`${fields[name]} ${sql} ${addValue(operand)}`);
+                }
+            continue;
+        }
+        const column = columns[key];
+        if (column === undefined || value === null || typeof value !== "object")
+            throw new Error(`${key} is not a supported contract filter`);
+        for (const [op, operand] of Object.entries(value)) {
+            const sql = { equals: "=", lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[op];
+            if (sql !== undefined)
+                parts.push(`${column} ${sql} ${addValue(operand)}`);
+            else if (op === "is" && operand === null)
+                parts.push(`${column} is null`);
+            else if (op === "isNot" && operand === null)
+                parts.push(`${column} is not null`);
+            else if (op === "in" && Array.isArray(operand))
+                parts.push(operand.length ? `${column} = any(${addValue(operand)})` : "false");
+            else
+                throw new Error(`${op} is not supported for ${key}`);
+        }
+    }
+    return parts.length === 0 ? "true" : parts.join(" and ");
+}
+function compileOrderBy(orderBy) {
+    if (orderBy === undefined) {
+        return "order by contract_row.contract_id asc";
+    }
+    const fields = {
+        contractId: "contract_row.contract_id",
+        createdEventOffset: "contract_row.created_at_ix",
+        createdAt: "created_tx.effective_at",
+        archivedEventOffset: "contract_row.archived_at_ix",
+        archivedAt: "archived_tx.effective_at",
+    };
+    const entries = Object.entries(orderBy);
+    if (entries.length !== 1) {
+        throw new Error("orderBy must specify exactly one field");
+    }
+    const [field, direction] = entries[0];
+    return `order by ${fields[field]} ${direction}`;
+}

package/dist/query/pqs/read-only-sql.d.ts

@@ -0,0 +1 @@
+export declare function assertReadOnlySql(sql: string): void;

package/dist/query/pqs/read-only-sql.js

@@ -0,0 +1,35 @@
+const allowedStarts = new Set(["select", "with", "explain", "show"]);
+const mutationTokens = new Set([
+    "insert",
+    "update",
+    "delete",
+    "merge",
+    "create",
+    "alter",
+    "drop",
+    "truncate",
+    "grant",
+    "revoke",
+    "copy",
+]);
+export function assertReadOnlySql(sql) {
+    const normalized = stripLiteralsAndComments(sql).trim().toLowerCase();
+    const tokens = normalized.match(/[a-z_]+|;/g) ?? [];
+    const firstToken = tokens[0];
+    if (firstToken === undefined || !allowedStarts.has(firstToken)) {
+        throw new Error("PQS raw queries must be read-only statements.");
+    }
+    else if (tokens.some((token) => token === ";")) {
+        throw new Error("PQS raw queries must contain one read-only statement.");
+    }
+    else if (tokens.some((token) => mutationTokens.has(token))) {
+        throw new Error("PQS raw queries must be read-only statements.");
+    }
+}
+function stripLiteralsAndComments(sql) {
+    return sql
+        .replace(/--[^\n]*/g, "")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/'(?:''|[^'])*'/g, "''")
+        .replace(/"(?:""|[^"])*"/g, '""');
+}