@distrohelena/canton-typescript-sdk 0.1.16 → 0.1.17

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

@@ -0,0 +1,146 @@
+import { PqsSchemaProfileV1, pqsRelationMetadata } from "./pqs-schema-profile.js";
+import { pqsRelationEdges } from "./pqs-schema-profile.js";
+export function compilePqsRelationFindMany(relation, args, profile) {
+    assertPage(args);
+    const metadata = 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,
+    };
+}
+export 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 = 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)) || !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 && 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 = 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) || !PqsSchemaProfileV1.bucketField(edge.target, fieldName))
+            throw new Error("invalid profiled time bucket");
+        const targetColumn = field(edge.target, 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/query/pqs/pqs-schema-profile.d.ts

@@ -1,5 +1,13 @@
 export declare const requiredPqsRelations: readonly ["__contracts", "__contract_tpe", "__events", "__exercises", "__exercise_tpe", "__packages", "__transactions", "__watermark"];
 export type PqsRelation = (typeof requiredPqsRelations)[number];
+export interface PqsRelationEdge {
+    readonly target: PqsRelation;
+    readonly sourceColumn: string;
+    readonly targetColumn: string;
+    readonly cardinality: "one" | "many";
+    readonly nullable: boolean;
+}
+export declare const pqsRelationEdges: Readonly<Partial<Record<PqsRelation, Readonly<Record<string, PqsRelationEdge>>>>>;
 export interface PqsRelationMetadata {
     readonly fields: Readonly<Record<string, string>>;
     readonly uniqueKeys: readonly (readonly string[])[];
@@ -15,6 +23,8 @@ export declare class PqsSchemaProfileV1 {
     readonly schema: string;
     constructor(schema?: string);
     relation(relation: PqsRelation): string;
+    static jsonField(relation: PqsRelation, field: string): boolean;
+    static bucketField(relation: PqsRelation, field: string): boolean;
 }
 export interface PqsSchemaClient {
     query(query: string, values: readonly unknown[]): Promise<{

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

@@ -10,6 +10,46 @@ export const requiredPqsRelations = [
     "__transactions",
     "__watermark",
 ];
+export const 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"],
+};
 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: [] },
@@ -99,6 +139,12 @@ export class PqsSchemaProfileV1 {
     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;
+    }
 }
 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]);

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

@@ -1,7 +1,8 @@
-import { ContractFindManyArgs } from "../model-types.js";
+import { ContractFindManyArgs, ContractGroupByArgs } 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;
+export declare function compileContractGroupBy(args: ContractGroupByArgs, profile: PqsSchemaProfileV1): CompiledPqsQuery;

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

@@ -1,4 +1,6 @@
 import { assertQueryPageArgs, } from "../model-types.js";
+import { PqsSchemaProfileV1 } from "./pqs-schema-profile.js";
+import { pqsRelationEdges, pqsRelationMetadata } from "./pqs-schema-profile.js";
 export function compileContractFindMany(args, profile) {
     assertQueryPageArgs(args);
     const values = [];
@@ -7,7 +9,7 @@ export function compileContractFindMany(args, profile) {
         return `$${values.length}`;
     };
     const conditions = [];
-    const where = args.where === undefined ? undefined : compileWhere(args.where, addValue);
+    const where = args.where === undefined ? undefined : compileWhere(args.where, addValue, profile);
     if (where !== undefined)
         conditions.push(where);
     if (args.parties !== undefined) {
@@ -17,6 +19,16 @@ export function compileContractFindMany(args, profile) {
     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)}`;
+    const included = compileProfileIncludes("__contracts", "contract_row", args.include, profile, addValue);
+    const jsonProjection = Object.entries(args.select?.json ?? {}).map(([name, projection]) => {
+        if (projection.field !== "payload")
+            throw new Error(`${projection.field} is not a JSON field of contracts`);
+        if (projection.path.length === 0 || projection.path.some((segment) => segment.length === 0))
+            throw new Error(`${name}.path must be a non-empty JSON path`);
+        const text = `contract_row.payload #>> ${addValue(projection.path)}::text[]`;
+        const expression = projection.as === "text" ? text : projection.as === "numeric" ? `(${text})::numeric::text` : projection.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
+        return `${expression} as "${name}"`;
+    });
     return {
         text: `select
   contract_row.contract_id as contract_id,
@@ -30,7 +42,7 @@ export function compileContractFindMany(args, profile) {
   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
+  contract_tpe_row.entity_name as template_entity_name${[...included, ...jsonProjection].length === 0 ? "" : `,\n  ${[...included, ...jsonProjection].join(",\n  ")}`}
 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
@@ -42,18 +54,135 @@ ${offsetSql}`,
         values,
     };
 }
-function compileWhere(where, addValue) {
+function compileProfileIncludes(source, parentAlias, include, profile, addValue) {
+    const selected = [];
+    for (const [name, option] of Object.entries(include ?? {})) {
+        const edge = pqsRelationEdges[source]?.[name];
+        if (edge === undefined)
+            throw new Error(`${name} is not a relation of ${source}`);
+        const settings = option === true ? {} : option;
+        if (settings === null || typeof settings !== "object" || Array.isArray(settings))
+            throw new Error(`${name} must be an include option`);
+        const options = settings;
+        if (edge.cardinality === "many" && (typeof options.take !== "number" || !Number.isInteger(options.take) || options.take < 0))
+            throw new Error(`${name} is a to-many relation and requires a non-negative take`);
+        const alias = `"${name}"`;
+        const nested = compileProfileIncludes(edge.target, alias, options.include, profile, addValue);
+        const metadata = pqsRelationMetadata[edge.target];
+        const requested = options.select === undefined
+            ? Object.entries(metadata.fields)
+            : Object.entries(options.select).filter(([field, enabled]) => field !== "json" && enabled === true).map(([field]) => [field, metadata.fields[field]]);
+        const json = options.select?.json ?? {};
+        const jsonSelections = Object.entries(json).map(([projectionName, projection]) => {
+            if (!PqsSchemaProfileV1.jsonField(edge.target, projection.field))
+                throw new Error(`${projection.field} is not a JSON field of ${edge.target}`);
+            if (projection.path.length === 0 || projection.path.some((segment) => segment.length === 0))
+                throw new Error(`${projectionName}.path must be a non-empty JSON path`);
+            const column = metadata.fields[projection.field];
+            if (column === undefined)
+                throw new Error(`${projection.field} is not a field of ${edge.target}`);
+            const text = `${alias}."${column}" #>> ${addValue(projection.path)}::text[]`;
+            const expression = projection.as === "text" ? text : projection.as === "numeric" ? `(${text})::numeric::text` : projection.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
+            return [`'${projectionName}'`, expression];
+        });
+        if (requested.length === 0 && jsonSelections.length === 0)
+            throw new Error(`Nested ${name}.select must include at least one field`);
+        if (requested.some(([, column]) => column === undefined))
+            throw new Error(`Nested ${name}.select references an unknown field`);
+        const fields = requested.flatMap(([field, column]) => [`'${field}'`, `${alias}."${column}"`]);
+        const nestedFields = nested.flatMap((selection) => {
+            const match = /^(.*) as "([^"]+)"$/.exec(selection);
+            return match === null ? [] : [`'${match[2]}'`, match[1]];
+        });
+        const object = `jsonb_build_object(${[...fields, ...jsonSelections.flat(), ...nestedFields].join(", ")})`;
+        const relationFilter = options.where === undefined ? "true" : compilePhysicalWhere(edge.target, options.where, alias, profile, addValue);
+        const condition = `${alias}."${edge.targetColumn}" = ${parentAlias}."${edge.sourceColumn}" and (${relationFilter})`;
+        const orderBy = compilePhysicalOrderBy(edge.target, options.orderBy, alias);
+        const expression = edge.cardinality === "one"
+            ? `(select ${object} from ${profile.relation(edge.target)} ${alias} where ${condition})`
+            : `(select coalesce(jsonb_agg("${name}_limited".value), '[]'::jsonb) from (select ${object} as value from ${profile.relation(edge.target)} ${alias} where ${condition}${orderBy} limit ${addValue(options.take)}) "${name}_limited")`;
+        selected.push(`${expression} as "${name}"`);
+    }
+    return selected;
+}
+function compilePhysicalOrderBy(relation, orderBy, alias) {
+    if (orderBy === undefined)
+        return "";
+    if (!Array.isArray(orderBy) || orderBy.length === 0)
+        throw new Error("Nested orderBy must be a non-empty list");
+    const metadata = pqsRelationMetadata[relation];
+    const entries = orderBy.flatMap((entry) => entry !== null && typeof entry === "object" ? Object.entries(entry) : []);
+    if (entries.length !== orderBy.length || entries.some(([, direction]) => direction !== "asc" && direction !== "desc"))
+        throw new Error("Nested orderBy entries must have one valid direction");
+    return ` order by ${entries.map(([field, direction]) => {
+        const column = metadata.fields[field];
+        if (column === undefined)
+            throw new Error(`${field} is not a field of ${relation}`);
+        return `${alias}."${column}" ${direction}`;
+    }).join(", ")}`;
+}
+export function compileContractGroupBy(args, profile) {
+    if (args.by.length === 0 || (!args.aggregate.count && !args.aggregate.min && !args.aggregate.max && !args.aggregate.sum))
+        throw new Error("groupBy requires keys and an aggregate");
+    const values = [];
+    const add = (value) => { values.push(value); return `$${values.length}`; };
+    const where = args.where === undefined ? undefined : compileWhere(args.where, add, profile);
+    const fields = {
+        contractId: "contract_row.contract_id",
+        createdEventOffset: "contract_row.created_at_ix",
+        archivedEventOffset: "contract_row.archived_at_ix",
+    };
+    const expressions = [];
+    const select = [];
+    let unnestWitnesses = false;
+    for (const key of args.by) {
+        if (key === "witnesses") {
+            unnestWitnesses = true;
+            expressions.push("witness.value");
+            select.push("witness.value as \"witnesses\"");
+        }
+        else if (typeof key === "string") {
+            const expression = fields[key];
+            if (expression === undefined)
+                throw new Error(`${key} is not a contract group key`);
+            expressions.push(expression);
+            select.push(`${expression} as "${key}"`);
+        }
+        else {
+            const payload = key.payload;
+            if (payload.path.length === 0 || payload.path.some((segment) => segment.length === 0))
+                throw new Error("payload group path must be non-empty");
+            const base = `contract_row.payload #>> ${add(payload.path)}::text[]`;
+            const cast = payload.as === "text" ? base : `(${base})::${payload.as === "numeric" ? "numeric" : payload.as === "boolean" ? "boolean" : "timestamptz"}`;
+            expressions.push(cast);
+            select.push(`${cast} as "${payload.name}"`);
+        }
+    }
+    if (args.aggregate.count)
+        select.push("count(*)::text as count");
+    for (const [operation, requested] of [["min", args.aggregate.min], ["max", args.aggregate.max], ["sum", args.aggregate.sum]]) {
+        for (const name of requested ?? []) {
+            const expression = fields[name];
+            select.push(`${operation}(${expression})::text as "${operation}_${name}"`);
+        }
+    }
+    return {
+        text: `select ${select.join(", ")} from ${profile.relation("__contracts")} contract_row${unnestWitnesses ? " cross join lateral unnest(contract_row.witnesses) as witness(value)" : ""}${where === undefined ? "" : ` where ${where}`} group by ${expressions.join(", ")}`,
+        values,
+    };
+}
+function compileWhere(where, addValue, profile) {
     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} `)})`);
+            parts.push(value.length === 0 ? key === "and" ? "true" : "false" : `(${value.map((child) => compileWhere(child, addValue, profile)).join(` ${key} `)})`);
             continue;
         }
         if (key === "not") {
-            parts.push(`not (${compileWhere(value, addValue)})`);
+            parts.push(`not (${compileWhere(value, addValue, profile)})`);
             continue;
         }
         if (key === "active") {
@@ -94,6 +223,11 @@ function compileWhere(where, addValue) {
                 }
             continue;
         }
+        const edge = pqsRelationEdges.__contracts?.[key];
+        if (edge !== undefined) {
+            parts.push(compilePhysicalRelationPredicate(edge.target, key, edge.targetColumn, edge.sourceColumn, edge.cardinality, value, "contract_row", profile, addValue));
+            continue;
+        }
         const column = columns[key];
         if (column === undefined || value === null || typeof value !== "object")
             throw new Error(`${key} is not a supported contract filter`);
@@ -113,6 +247,75 @@ function compileWhere(where, addValue) {
     }
     return parts.length === 0 ? "true" : parts.join(" and ");
 }
+function compilePhysicalRelationPredicate(target, edgeName, targetColumn, sourceColumn, cardinality, value, parentAlias, profile, addValue) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${edgeName} must be a relation filter`);
+    const relation = value;
+    const alias = `"${edgeName}"`;
+    const join = `${alias}."${targetColumn}" = ${parentAlias}."${sourceColumn}"`;
+    if (cardinality === "one") {
+        const predicate = compilePhysicalWhere(target, relation, alias, profile, addValue);
+        return `exists (select 1 from ${profile.relation(target)} ${alias} where ${join} and (${predicate}))`;
+    }
+    const operators = ["some", "none", "every"].filter((name) => relation[name] !== undefined);
+    if (operators.length !== 1)
+        throw new Error(`${edgeName} requires exactly one of some, none, or every`);
+    const predicate = compilePhysicalWhere(target, relation[operators[0]], alias, profile, addValue);
+    const base = `select 1 from ${profile.relation(target)} ${alias} where ${join} and (${predicate})`;
+    return operators[0] === "some" ? `exists (${base})` : operators[0] === "none" ? `not exists (${base})` : `not exists (select 1 from ${profile.relation(target)} ${alias} where ${join} and not (${predicate}))`;
+}
+function compilePhysicalWhere(relation, expression, alias, profile, addValue) {
+    if (expression === null || typeof expression !== "object" || Array.isArray(expression))
+        throw new Error(`${relation} relation predicate must be an expression`);
+    const metadata = pqsRelationMetadata[relation];
+    const conditions = [];
+    for (const [field, value] of Object.entries(expression)) {
+        if (field === "and" || field === "or") {
+            if (!Array.isArray(value))
+                throw new Error(`${field} must be an array`);
+            conditions.push(value.length === 0 ? field === "and" ? "true" : "false" : `(${value.map((child) => compilePhysicalWhere(relation, child, alias, profile, addValue)).join(` ${field} `)})`);
+            continue;
+        }
+        if (field === "not") {
+            conditions.push(`not (${compilePhysicalWhere(relation, value, alias, profile, addValue)})`);
+            continue;
+        }
+        const edge = pqsRelationEdges[relation]?.[field];
+        if (edge !== undefined) {
+            conditions.push(compilePhysicalRelationPredicate(edge.target, field, edge.targetColumn, edge.sourceColumn, edge.cardinality, value, alias, profile, addValue));
+            continue;
+        }
+        const column = metadata.fields[field];
+        if (column === undefined || value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`${field} is not a field of ${relation}`);
+        const filter = value;
+        const text = PqsSchemaProfileV1.jsonField(relation, field) && Array.isArray(filter.path) ? `${alias}."${column}" #>> ${addValue(filter.path)}::text[]` : `${alias}."${column}"`;
+        if (Array.isArray(filter.path) && (filter.path.length === 0 || filter.path.some((segment) => typeof segment !== "string" || segment.length === 0)))
+            throw new Error(`${field}.path must be a non-empty JSON path`);
+        if (filter.is === null)
+            conditions.push(`${text} is null`);
+        if (filter.isNot === null)
+            conditions.push(`${text} is not null`);
+        if (filter.equals !== undefined)
+            conditions.push(`${text} = ${addValue(filter.equals)}`);
+        if (filter.in !== undefined) {
+            if (!Array.isArray(filter.in))
+                throw new Error(`${field}.in must be an array`);
+            conditions.push(filter.in.length === 0 ? "false" : `${text} = any(${addValue(filter.in)})`);
+        }
+        if (filter.has !== undefined) {
+            if (!metadata.arrayFields.includes(field))
+                throw new Error(`${field} is not an array field of ${relation}`);
+            conditions.push(`${addValue(filter.has)} = any(${alias}."${column}")`);
+        }
+        for (const [operator, operand] of Object.entries(filter)) {
+            const sql = { lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[operator];
+            if (sql !== undefined)
+                conditions.push(`${text} ${sql} ${addValue(operand)}`);
+        }
+    }
+    return conditions.length === 0 ? "true" : conditions.join(" and ");
+}
 function compileOrderBy(orderBy) {
     if (orderBy === undefined) {
         return "order by contract_row.contract_id asc";
@@ -124,10 +327,9 @@ function compileOrderBy(orderBy) {
         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 entries = orderBy.flatMap((entry) => Object.entries(entry));
+    if (entries.some(([field, direction]) => fields[field] === undefined || (direction !== "asc" && direction !== "desc"))) {
+        throw new Error("orderBy must contain valid one-field entries");
     }
-    const [field, direction] = entries[0];
-    return `order by ${fields[field]} ${direction}`;
+    return `order by ${entries.map(([field, direction]) => `${fields[field]} ${direction}`).join(", ")}`;
 }

package/dist/query/query-client.d.ts

@@ -1,18 +1,20 @@
 import { QuerySource } from "./query-source.js";
-import { ContractTypeOrderBy, ContractTypeRow, ContractTypeSelect, ContractTypeUnique, ContractTypeWhere, ContractCountArgs, ContractFindManyArgs, ContractFindUniqueArgs, ContractRow, EventOrderBy, EventRow, EventSelect, EventUnique, EventWhere, ExerciseOrderBy, ExerciseRow, ExerciseSelect, ExerciseTypeOrderBy, ExerciseTypeRow, ExerciseTypeSelect, ExerciseTypeUnique, ExerciseTypeWhere, ExerciseWhere, PackageOrderBy, PackageRow, PackageSelect, PackageUnique, PackageWhere, TransactionOrderBy, TransactionRow, TransactionSelect, TransactionUnique, TransactionWhere, WatermarkOrderBy, WatermarkRow, WatermarkSelect, WatermarkUnique, WatermarkWhere } from "./model-types.js";
-export interface FindManyArgs<TWhere, TSelect, TOrderBy> {
+import { ContractTypeOrderBy, ContractTypeResult, ContractTypeSelect, ContractTypeUnique, ContractTypeWhere, ContractTypeGroupByArgs, ContractTypeGroupRow, ContractCountArgs, ContractFindManyArgs, ContractFindUniqueArgs, ContractGroupByArgs, ContractGroupRow, ContractResult, EventOrderBy, EventResult, EventGroupByArgs, EventGroupRow, EventSelect, EventUnique, EventWhere, ExerciseOrderBy, ExerciseResult, ExerciseSelect, ExerciseTypeOrderBy, ExerciseTypeResult, ExerciseTypeSelect, ExerciseTypeUnique, ExerciseTypeWhere, ExerciseTypeGroupByArgs, ExerciseTypeGroupRow, ExerciseWhere, ExerciseGroupByArgs, ExerciseGroupRow, PackageOrderBy, PackageResult, PackageSelect, PackageUnique, PackageWhere, PackageGroupByArgs, PackageGroupRow, TransactionOrderBy, TransactionResult, TransactionSelect, TransactionUnique, TransactionWhere, TransactionGroupByArgs, TransactionGroupRow, WatermarkOrderBy, WatermarkRow, WatermarkSelect, WatermarkUnique, WatermarkWhere, WatermarkGroupByArgs, WatermarkGroupRow, ContractTypeInclude, EventInclude, ExerciseInclude, ExerciseTypeInclude, PackageInclude, TransactionInclude, JsonProjectionResult } from "./model-types.js";
+export interface FindManyArgs<TWhere, TSelect, TOrderBy, TInclude = never> {
     readonly where?: TWhere;
     readonly select?: TSelect;
     readonly orderBy?: TOrderBy;
     readonly skip?: number;
     readonly take?: number;
+    readonly include?: TInclude;
 }
-export interface QueryDelegate<TRow, TWhere, TSelect, TOrderBy, TUnique> {
-    findMany(args?: FindManyArgs<TWhere, TSelect, TOrderBy>): Promise<readonly TRow[]>;
-    findUnique(args: {
+export interface QueryDelegate<TRow, TWhere, TSelect, TOrderBy, TUnique, TInclude = never, TGroupBy = never, TGroupRow = never> {
+    findMany<TArgs extends FindManyArgs<TWhere, TSelect, TOrderBy, TInclude>>(args?: TArgs): Promise<readonly (TRow & JsonProjectionResult<TArgs>)[]>;
+    findUnique<TArgs extends {
         readonly where: TUnique;
         readonly select?: TSelect;
-    }): Promise<TRow | undefined>;
+        readonly include?: TInclude;
+    }>(args: TArgs): Promise<(TRow & JsonProjectionResult<TArgs>) | undefined>;
     count(args?: {
         readonly where?: TWhere;
     }): Promise<number>;
@@ -28,14 +30,15 @@ export interface QueryDelegate<TRow, TWhere, TSelect, TOrderBy, TUnique> {
         readonly max?: Readonly<Record<string, string | null>>;
         readonly sum?: Readonly<Record<string, string | null>>;
     }>;
+    groupBy(args: TGroupBy): Promise<readonly TGroupRow[]>;
 }
-export type QueryCollectionDelegate<TRow, TWhere, TSelect, TOrderBy> = Omit<QueryDelegate<TRow, TWhere, TSelect, TOrderBy, never>, "findUnique">;
+export type QueryCollectionDelegate<TRow, TWhere, TSelect, TOrderBy, TInclude = never, TGroupBy = never, TGroupRow = never> = Omit<QueryDelegate<TRow, TWhere, TSelect, TOrderBy, never, TInclude, TGroupBy, TGroupRow>, "findUnique">;
 export interface QueryClient {
     readonly source: QuerySource;
     $queryRaw<TRow>(sql: string, values?: readonly unknown[]): Promise<readonly TRow[]>;
     readonly contracts: {
-        findMany(args?: ContractFindManyArgs): Promise<readonly ContractRow[]>;
-        findUnique(args: ContractFindUniqueArgs): Promise<ContractRow | undefined>;
+        findMany<TArgs extends ContractFindManyArgs>(args?: TArgs): Promise<readonly (ContractResult & JsonProjectionResult<TArgs>)[]>;
+        findUnique<TArgs extends ContractFindUniqueArgs>(args: TArgs): Promise<(ContractResult & JsonProjectionResult<TArgs>) | undefined>;
         count(args?: ContractCountArgs): Promise<number>;
         aggregate(args: {
             readonly where?: ContractCountArgs["where"];
@@ -49,13 +52,14 @@ export interface QueryClient {
             readonly max?: Readonly<Partial<Record<ContractNumericField, string | null>>>;
             readonly sum?: Readonly<Partial<Record<ContractNumericField, string | null>>>;
         }>;
+        groupBy(args: ContractGroupByArgs): Promise<readonly ContractGroupRow[]>;
     };
-    readonly contractTypes: QueryDelegate<ContractTypeRow, ContractTypeWhere, ContractTypeSelect, ContractTypeOrderBy, ContractTypeUnique>;
-    readonly events: QueryDelegate<EventRow, EventWhere, EventSelect, EventOrderBy, EventUnique>;
-    readonly exercises: QueryCollectionDelegate<ExerciseRow, ExerciseWhere, ExerciseSelect, ExerciseOrderBy>;
-    readonly exerciseTypes: QueryDelegate<ExerciseTypeRow, ExerciseTypeWhere, ExerciseTypeSelect, ExerciseTypeOrderBy, ExerciseTypeUnique>;
-    readonly packages: QueryDelegate<PackageRow, PackageWhere, PackageSelect, PackageOrderBy, PackageUnique>;
-    readonly transactions: QueryDelegate<TransactionRow, TransactionWhere, TransactionSelect, TransactionOrderBy, TransactionUnique>;
-    readonly watermark: QueryDelegate<WatermarkRow, WatermarkWhere, WatermarkSelect, WatermarkOrderBy, WatermarkUnique>;
+    readonly contractTypes: QueryDelegate<ContractTypeResult, ContractTypeWhere, ContractTypeSelect, ContractTypeOrderBy, ContractTypeUnique, ContractTypeInclude, ContractTypeGroupByArgs, ContractTypeGroupRow>;
+    readonly events: QueryDelegate<EventResult, EventWhere, EventSelect, EventOrderBy, EventUnique, EventInclude, EventGroupByArgs, EventGroupRow>;
+    readonly exercises: QueryCollectionDelegate<ExerciseResult, ExerciseWhere, ExerciseSelect, ExerciseOrderBy, ExerciseInclude, ExerciseGroupByArgs, ExerciseGroupRow>;
+    readonly exerciseTypes: QueryDelegate<ExerciseTypeResult, ExerciseTypeWhere, ExerciseTypeSelect, ExerciseTypeOrderBy, ExerciseTypeUnique, ExerciseTypeInclude, ExerciseTypeGroupByArgs, ExerciseTypeGroupRow>;
+    readonly packages: QueryDelegate<PackageResult, PackageWhere, PackageSelect, PackageOrderBy, PackageUnique, PackageInclude, PackageGroupByArgs, PackageGroupRow>;
+    readonly transactions: QueryDelegate<TransactionResult, TransactionWhere, TransactionSelect, TransactionOrderBy, TransactionUnique, TransactionInclude, TransactionGroupByArgs, TransactionGroupRow>;
+    readonly watermark: QueryDelegate<WatermarkRow, WatermarkWhere, WatermarkSelect, WatermarkOrderBy, WatermarkUnique, never, WatermarkGroupByArgs, WatermarkGroupRow>;
 }
 export type ContractNumericField = "createdEventOffset" | "archivedEventOffset";