@distrohelena/canton-typescript-sdk 0.1.28 → 0.1.30

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

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compilePqsRelationFindMany = compilePqsRelationFindMany;
+exports.compilePqsRelationGroupBy = compilePqsRelationGroupBy;
+const pqs_schema_profile_js_1 = require("./pqs-schema-profile.js");
+const pqs_schema_profile_js_2 = require("./pqs-schema-profile.js");
+function compilePqsRelationFindMany(relation, args, profile) {
+    assertPage(args);
+    const metadata = pqs_schema_profile_js_1.pqsRelationMetadata[relation];
+    const values = [];
+    const add = (value) => {
+        values.push(value);
+        return `$${values.length}`;
+    };
+    const fields = selectedFields(relation, metadata, args.select);
+    const where = compileWhere(relation, metadata, args.where, add);
+    const orderBy = compileOrderBy(relation, metadata, args.orderBy);
+    const limit = args.take === undefined ? "" : ` limit ${add(args.take)}`;
+    const offset = args.skip === undefined ? "" : ` offset ${add(args.skip)}`;
+    return {
+        text: `select ${fields.map(([field, column]) => `"${column}" as "${field}"`).join(", ")} from ${profile.relation(relation)}${where}${orderBy}${limit}${offset}`,
+        values,
+    };
+}
+function compilePqsRelationGroupBy(relation, args, profile, parameterOffset = 0) {
+    if (args.by.length === 0 || (!args.aggregate.count && !args.aggregate.min && !args.aggregate.max && !args.aggregate.sum))
+        throw new Error("groupBy requires a key and aggregate");
+    const metadata = pqs_schema_profile_js_1.pqsRelationMetadata[relation];
+    const root = relation === "__events" ? "event" : "root";
+    const joins = [];
+    const expressions = [];
+    const selected = [];
+    const values = [];
+    const add = (value) => { values.push(value); return `$${parameterOffset + values.length}`; };
+    for (const key of args.by) {
+        if (typeof key === "string") {
+            const column = field(relation, metadata, key);
+            const expression = metadata.arrayFields.includes(key)
+                ? `"${key}".value`
+                : `"${root}"."${column}"`;
+            if (metadata.arrayFields.includes(key))
+                joins.push(`cross join lateral unnest("${root}"."${column}") as "${key}"(value)`);
+            expressions.push(expression);
+            selected.push(`${expression} as "${key}"`);
+            continue;
+        }
+        if (key === null || typeof key !== "object")
+            throw new Error("invalid group key");
+        const [edgeName, nested] = Object.entries(key)[0] ?? [];
+        if (nested !== null && typeof nested === "object" && "name" in nested && "path" in nested && "as" in nested) {
+            const projection = nested;
+            if (typeof projection.name !== "string" || !Array.isArray(projection.path) || !projection.path.every((segment) => typeof segment === "string" && segment.length > 0) || !["text", "numeric", "boolean", "timestamp"].includes(String(projection.as)) || !pqs_schema_profile_js_1.PqsSchemaProfileV1.jsonField(relation, edgeName))
+                throw new Error("invalid profiled JSON group key");
+            const column = field(relation, metadata, edgeName);
+            const text = `"${root}"."${column}" #>> ${add(projection.path)}::text[]`;
+            const expression = projection.as === "text" ? text : projection.as === "numeric" ? `(${text})::numeric` : projection.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
+            expressions.push(expression);
+            selected.push(`${expression} as "${projection.name}"`);
+            continue;
+        }
+        if (nested !== null && typeof nested === "object" && "bucket" in nested && pqs_schema_profile_js_1.PqsSchemaProfileV1.bucketField(relation, edgeName)) {
+            const bucket = nested.bucket;
+            if (typeof bucket !== "string" || !["hour", "day", "week", "month"].includes(bucket))
+                throw new Error("invalid profiled time bucket");
+            const column = field(relation, metadata, edgeName);
+            const expression = `date_trunc('${bucket}', "${root}"."${column}")`;
+            expressions.push(expression);
+            selected.push(`${expression} as "${edgeName}_${bucket}"`);
+            continue;
+        }
+        const edge = pqs_schema_profile_js_2.pqsRelationEdges[relation]?.[edgeName];
+        if (edge === undefined || edge.cardinality !== "one" || nested === null || typeof nested !== "object")
+            throw new Error("group key must follow a profiled to-one edge");
+        const [fieldName, bucketValue] = Object.entries(nested)[0] ?? [];
+        const bucket = bucketValue !== null && typeof bucketValue === "object" ? bucketValue.bucket : undefined;
+        if (typeof bucket !== "string" || !["hour", "day", "week", "month"].includes(bucket) || !pqs_schema_profile_js_1.PqsSchemaProfileV1.bucketField(edge.target, fieldName))
+            throw new Error("invalid profiled time bucket");
+        const targetColumn = field(edge.target, pqs_schema_profile_js_1.pqsRelationMetadata[edge.target], fieldName);
+        joins.push(`join ${profile.relation(edge.target)} "${edgeName}" on "${edgeName}"."${edge.targetColumn}" = "${root}"."${edge.sourceColumn}"`);
+        const expression = `date_trunc('${bucket}', "${edgeName}"."${targetColumn}")`;
+        expressions.push(expression);
+        selected.push(`${expression} as "${edgeName}_${fieldName}_${bucket}"`);
+    }
+    if (args.aggregate.count)
+        selected.push("count(*)::text as count");
+    for (const [operation, fields] of [["min", args.aggregate.min], ["max", args.aggregate.max], ["sum", args.aggregate.sum]])
+        for (const name of fields ?? []) {
+            if (!metadata.numericFields.includes(name))
+                throw new Error(`${name} is not a numeric aggregate field of ${relation}`);
+            selected.push(`${operation}("${root}"."${field(relation, metadata, name)}")::text as "${operation}_${name}"`);
+        }
+    return { text: `select ${selected.join(", ")} from ${profile.relation(relation)} "${root}" ${joins.join(" ")} group by ${expressions.join(", ")}`, values };
+}
+function selectedFields(relation, metadata, select) {
+    const fields = select === undefined
+        ? Object.entries(metadata.fields)
+        : Object.entries(select).filter(([, enabled]) => enabled).map(([name]) => [name, field(relation, metadata, name)]);
+    if (fields.length === 0)
+        throw new Error("select must include at least one field");
+    return fields;
+}
+function compileWhere(relation, metadata, where, add) {
+    const conditions = [];
+    for (const [name, value] of Object.entries(where ?? {})) {
+        const column = field(relation, metadata, name);
+        if (value === null || Array.isArray(value) || typeof value !== "object")
+            throw new Error(`${name} must be a filter`);
+        const filter = value;
+        for (const [operator, operand] of Object.entries(filter)) {
+            if (operator === "equals")
+                conditions.push(`"${column}" = ${add(operand)}`);
+            else if (operator === "in" && Array.isArray(operand))
+                conditions.push(operand.length === 0 ? "false" : `"${column}" = any(${add(operand)})`);
+            else if (operator === "is" && operand === null)
+                conditions.push(`"${column}" is null`);
+            else if (operator === "isNot" && operand === null)
+                conditions.push(`"${column}" is not null`);
+            else if (["lt", "lte", "gt", "gte", "like", "ilike"].includes(operator)) {
+                const sql = { lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[operator];
+                conditions.push(`"${column}" ${sql} ${add(operand)}`);
+            }
+            else
+                throw new Error(`${operator} is not supported for ${name}`);
+        }
+    }
+    return conditions.length === 0 ? "" : ` where ${conditions.join(" and ")}`;
+}
+function compileOrderBy(relation, metadata, orderBy) {
+    if (orderBy === undefined)
+        return "";
+    const requested = orderBy.flatMap((entry) => Object.entries(entry));
+    if (requested.length === 0 || requested.some(([, direction]) => direction !== "asc" && direction !== "desc"))
+        throw new Error("orderBy must be a non-empty list of one-field entries");
+    const ordered = requested.map(([name, direction]) => [field(relation, metadata, name), direction]);
+    const stableKey = metadata.uniqueKeys[0]?.[0];
+    if (stableKey !== undefined && !ordered.some(([column]) => column === metadata.fields[stableKey]))
+        ordered.push([metadata.fields[stableKey], "asc"]);
+    return ` order by ${ordered.map(([column, direction]) => `"${column}" ${direction}`).join(", ")}`;
+}
+function field(relation, metadata, name) {
+    const column = metadata.fields[name];
+    if (column === undefined)
+        throw new Error(`${name} is not a field of ${relation}`);
+    return column;
+}
+function 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`);
+}

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

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PqsSchemaProfileV1 = exports.requiredPqsColumns = exports.pqsRelationMetadata = exports.pqsRelationEdges = exports.requiredPqsRelations = void 0;
+exports.validatePqsSchemaAsync = validatePqsSchemaAsync;
+exports.assertPqsSchemaIdentifier = assertPqsSchemaIdentifier;
+const pqs_schema_profile_error_js_1 = require("../errors/pqs-schema-profile-error.js");
+const schemaIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
+exports.requiredPqsRelations = [
+    "__contracts",
+    "__contract_tpe",
+    "__events",
+    "__exercises",
+    "__exercise_tpe",
+    "__packages",
+    "__transactions",
+    "__watermark",
+];
+exports.pqsRelationEdges = {
+    __contracts: {
+        contractType: { target: "__contract_tpe", sourceColumn: "tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
+        createdTransaction: { target: "__transactions", sourceColumn: "created_at_ix", targetColumn: "ix", cardinality: "one", nullable: false },
+        archivedTransaction: { target: "__transactions", sourceColumn: "archived_at_ix", targetColumn: "ix", cardinality: "one", nullable: true },
+        exercises: { target: "__exercises", sourceColumn: "contract_id", targetColumn: "contract_id", cardinality: "many", nullable: false },
+    },
+    __contract_tpe: {
+        contracts: { target: "__contracts", sourceColumn: "pk", targetColumn: "tpe_pk", cardinality: "many", nullable: false },
+        exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "contract_tpe_pk", cardinality: "many", nullable: false },
+    },
+    __events: {
+        transaction: { target: "__transactions", sourceColumn: "tx_ix", targetColumn: "ix", cardinality: "one", nullable: false },
+        exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "exercise_event_pk", cardinality: "many", nullable: false },
+    },
+    __exercises: {
+        exerciseType: { target: "__exercise_tpe", sourceColumn: "tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
+        contractType: { target: "__contract_tpe", sourceColumn: "contract_tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
+        event: { target: "__events", sourceColumn: "exercise_event_pk", targetColumn: "pk", cardinality: "one", nullable: true },
+        transaction: { target: "__transactions", sourceColumn: "exercised_at_ix", targetColumn: "ix", cardinality: "one", nullable: true },
+        package: { target: "__packages", sourceColumn: "package_pk", targetColumn: "pk", cardinality: "one", nullable: false },
+        contract: { target: "__contracts", sourceColumn: "contract_id", targetColumn: "contract_id", cardinality: "one", nullable: false },
+    },
+    __exercise_tpe: { exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "tpe_pk", cardinality: "many", nullable: false } },
+    __packages: { exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "package_pk", cardinality: "many", nullable: false } },
+    __transactions: {
+        events: { target: "__events", sourceColumn: "ix", targetColumn: "tx_ix", cardinality: "many", nullable: false },
+        createdContracts: { target: "__contracts", sourceColumn: "ix", targetColumn: "created_at_ix", cardinality: "many", nullable: false },
+        archivedContracts: { target: "__contracts", sourceColumn: "ix", targetColumn: "archived_at_ix", cardinality: "many", nullable: false },
+        exercises: { target: "__exercises", sourceColumn: "ix", targetColumn: "exercised_at_ix", cardinality: "many", nullable: false },
+    },
+};
+const pqsJsonFields = {
+    __contracts: ["payload"],
+    __exercises: ["argument", "result"],
+    __transactions: ["traceContext"],
+};
+const pqsBucketFields = {
+    __transactions: ["effectiveAt"],
+};
+exports.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: [] },
+};
+exports.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"],
+};
+class PqsSchemaProfileV1 {
+    schema;
+    constructor(schema = "public") {
+        assertPqsSchemaIdentifier(schema);
+        this.schema = schema;
+    }
+    relation(relation) {
+        return `${quoteIdentifier(this.schema)}.${quoteIdentifier(relation)}`;
+    }
+    static jsonField(relation, field) {
+        return pqsJsonFields[relation]?.includes(field) ?? false;
+    }
+    static bucketField(relation, field) {
+        return pqsBucketFields[relation]?.includes(field) ?? false;
+    }
+}
+exports.PqsSchemaProfileV1 = PqsSchemaProfileV1;
+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, exports.requiredPqsRelations]);
+    const actual = new Set(result.rows.map((row) => `${String(row.table_name)}.${String(row.column_name)}`));
+    const missing = exports.requiredPqsRelations.flatMap((relation) => exports.requiredPqsColumns[relation]
+        .filter((column) => !actual.has(`${relation}.${column}`))
+        .map((column) => `${relation}.${column}`));
+    if (missing.length > 0) {
+        throw new pqs_schema_profile_error_js_1.PqsSchemaProfileError(`PQS schema does not match v1 profile; missing: ${missing.join(", ")}`);
+    }
+}
+function assertPqsSchemaIdentifier(schema) {
+    if (!schemaIdentifier.test(schema)) {
+        throw new pqs_schema_profile_error_js_1.PqsSchemaProfileError(`Invalid PQS schema identifier: ${schema}`);
+    }
+}
+function quoteIdentifier(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+}