fastify-auto-sqlapi 0.1.13 → 0.2.0

package/dist/lib/engine/rest/update.js

@@ -3,6 +3,28 @@ import { processSecondaries, processDeletions } from '../write-helpers.js';
 import { stripTenantColumn, assertTenantOwnership, buildTenantUpdateExtra, enforceTenantFKOnUpdate, } from '../../tenant.js';
 import { runValidation } from '../validate.js';
 import { httpError } from '../../errors.js';
+/**
+ * Confirm the row exists — and is visible to this tenant — when the request carries no
+ * updatable fields. Secondaries and deletions still need the main row to be there, and a
+ * missing one must be a 404 rather than a silent success.
+ */
+async function assertRecordExists(tx, tableName, pkCols, pkValues, extraCondition) {
+    const whereParts = pkCols.map((c, i) => `${tx.qi(tableName)}.${tx.qi(c)} = ${tx.ph(i + 1)}`);
+    let whereSql = whereParts.join(' AND ');
+    const whereValues = [...pkValues];
+    if (extraCondition) {
+        whereSql += ` AND ${extraCondition.build(pkCols.length + 1, tx.ph)}`;
+        whereValues.push(...extraCondition.getValues());
+    }
+    const rows = await tx.select({
+        tableName,
+        where: whereSql,
+        values: whereValues,
+        limit: '1',
+    });
+    if (rows.length === 0)
+        throw httpError(404, `Record not found`);
+}
 export async function updateEngine(params) {
     const { db, tableConf, dbTables, request, record, secondaries, deletions, tenant } = params;
     const schema = tableConf.Schema;
@@ -50,22 +72,7 @@ export async function updateEngine(params) {
                 throw httpError(404, `Record not found`);
         }
         else {
-            // No fields to update: verify the record exists (for secondaries/deletions)
-            const whereParts = pkCols.map((c, i) => `${tx.qi(schema.tableName)}.${tx.qi(c)} = ${tx.ph(i + 1)}`);
-            let whereSql = whereParts.join(' AND ');
-            const whereValues = [...pkValues];
-            if (extraCondition) {
-                whereSql += ` AND ${extraCondition.build(pkCols.length + 1, tx.ph)}`;
-                whereValues.push(...extraCondition.getValues());
-            }
-            const rows = await tx.select({
-                tableName: schema.tableName,
-                where: whereSql,
-                values: whereValues,
-                limit: '1',
-            });
-            if (rows.length === 0)
-                throw httpError(404, `Record not found`);
+            await assertRecordExists(tx, schema.tableName, pkCols, pkValues, extraCondition);
         }
         // Build the main response (PK-only — every PK field)
         const mainResult = Object.fromEntries(pkFields.map((f, i) => [f, pkValues[i]]));
@@ -73,13 +80,13 @@ export async function updateEngine(params) {
         let secondaryResults;
         if (secondaries && Object.keys(secondaries).length > 0) {
             const mainForFK = { ...inputRecord };
-            secondaryResults = await processSecondaries(tx, tableConf, dbTables, mainForFK, secondaries);
+            secondaryResults = await processSecondaries({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant }, secondaries);
         }
         // 9. Deletions (FK auto-fill from main like secondaries)
         let deletionResults;
         if (deletions && Object.keys(deletions).length > 0) {
             const mainForFK = { ...inputRecord };
-            deletionResults = await processDeletions(tx, tableConf, mainForFK, deletions);
+            deletionResults = await processDeletions({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant }, deletions);
         }
         // 10. afterUpdate hook (inside the transaction: throwing rolls everything back)
         if (tableConf.afterUpdate) {

package/dist/lib/engine/search/aggregations.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Correlated aggregate subqueries — the machinery behind `<alias>.<fn>.<field>` in both
+ * `orderBy` and `conditions` (HAVING-style).
+ *
+ * Kept separate from ./conditions.ts on purpose: an aggregate embeds a join-reference
+ * condition, while a dotted condition embeds an aggregate. Holding both in one module would
+ * be fine, but splitting them the other way round (aggregates with orderBy) would make
+ * order-by and conditions import each other.
+ */
+import { Expression } from 'node-condition-builder';
+import type { QueryClient } from '../../db.js';
+import type { QueryParams } from '../query-params.js';
+import type { DbTables, ITable, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
+export interface AggFn {
+    sql: string;
+    distinct: boolean;
+}
+export declare const AGG_FN: Record<string, AggFn>;
+export declare function aggExpr(fn: AggFn, qualifiedCol: string): string;
+/**
+ * Correlated aggregate subquery for `<alias>.<fn>.<field>`, as an Expression carrying the
+ * values of its optional filter. Markers are `?`, so whoever embeds it — a ConditionBuilder
+ * or an ORDER BY list — decides the placeholder positions.
+ *
+ * The subquery carries the join table's own tenant scope, exactly as `executeJoinGroup` does
+ * for the aggregations it returns. Without it, ordering and HAVING-style filtering would count
+ * child rows of other tenants, disagreeing with the scoped `result.joinGroup` for the same
+ * alias and leaking their existence.
+ */
+export declare function buildAggOrderExpr(db: QueryClient, dbTables: DbTables, tableConf: ITable, alias: string, fn: string, field: string, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext): Expression;
+/** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */
+export declare function appendAggConditions(params: QueryParams, conditions: SearchCondition[], db: QueryClient, dbTables: DbTables, tableConf: ITable, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext): string;
+//# sourceMappingURL=aggregations.d.ts.map

package/dist/lib/engine/search/aggregations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE;AAEzD,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAOxC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,UAAU,CAgEZ;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,eAAe,EAAE,EAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAyBR"}

package/dist/lib/engine/search/aggregations.js

@@ -0,0 +1,109 @@
+/**
+ * Correlated aggregate subqueries — the machinery behind `<alias>.<fn>.<field>` in both
+ * `orderBy` and `conditions` (HAVING-style).
+ *
+ * Kept separate from ./conditions.ts on purpose: an aggregate embeds a join-reference
+ * condition, while a dotted condition embeds an aggregate. Holding both in one module would
+ * be fine, but splitting them the other way round (aggregates with orderBy) would make
+ * order-by and conditions import each other.
+ */
+import { ConditionBuilder, Expression } from 'node-condition-builder';
+import { ALLOWED_SET } from '../../condition-methods.js';
+import { tenantForTable, buildTenantRowGuard } from '../../tenant.js';
+import { err400, validateSchemaField } from './fields.js';
+import { requireJoin, extractJoinRefs, subqueryAlias } from './joins.js';
+import { buildJoinRefCondition, dispatchConditionMethod } from './conditions.js';
+export const AGG_FN = {
+    sum: { sql: 'SUM', distinct: false },
+    min: { sql: 'MIN', distinct: false },
+    max: { sql: 'MAX', distinct: false },
+    avg: { sql: 'AVG', distinct: false },
+    count: { sql: 'COUNT', distinct: false },
+    distinctCount: { sql: 'COUNT', distinct: true },
+};
+export function aggExpr(fn, qualifiedCol) {
+    return fn.distinct ? `COUNT(DISTINCT ${qualifiedCol})` : `${fn.sql}(${qualifiedCol})`;
+}
+/**
+ * Correlated aggregate subquery for `<alias>.<fn>.<field>`, as an Expression carrying the
+ * values of its optional filter. Markers are `?`, so whoever embeds it — a ConditionBuilder
+ * or an ORDER BY list — decides the placeholder positions.
+ *
+ * The subquery carries the join table's own tenant scope, exactly as `executeJoinGroup` does
+ * for the aggregations it returns. Without it, ordering and HAVING-style filtering would count
+ * child rows of other tenants, disagreeing with the scoped `result.joinGroup` for the same
+ * alias and leaking their existence.
+ */
+export function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, tenant) {
+    const aggFn = AGG_FN[fn];
+    if (!aggFn)
+        err400(`Invalid aggregation function: ${fn}`);
+    const groupReq = joinGroup?.[alias];
+    if (!groupReq)
+        err400(`orderBy/conditions reference undeclared joinGroup: ${alias}`);
+    const declaredFields = groupReq.aggregations[fn];
+    if (!Array.isArray(declaredFields) || !declaredFields.includes(field)) {
+        err400(`orderBy/conditions reference undeclared aggregation: ${alias}.${fn}.${field}`);
+    }
+    const joinDef = requireJoin(tableConf, alias, false);
+    const { joinSchema, joinField } = joinDef;
+    if (groupReq.aggregations.by && groupReq.aggregations.by !== joinField) {
+        err400(`Cannot order by aggregation on joinGroup with 'by' clause on non-FK column: ${alias} (grouped by '${groupReq.aggregations.by}', correlation FK is '${joinField}')`);
+    }
+    // Pass the join table's conf: without it validateSchemaField skips the readExclude
+    // check, and a HAVING-style condition on a hidden field becomes a 400-vs-200 oracle
+    // (executeJoinGroup's own validation is skipped when the main result set is empty).
+    const fieldCol = validateSchemaField(field, joinSchema, dbTables[joinSchema.tableName]);
+    const refs = extractJoinRefs(db, tableConf, joinDef);
+    // The subquery FROM is aliased so the correlation to the outer table survives a
+    // self-referencing relation; everything inside references the alias.
+    const subAlias = subqueryAlias(alias, tableConf);
+    const subRef = db.qi(subAlias);
+    let filterWhere = '';
+    let filterVals = [];
+    const joinTableConf = dbTables[joinSchema.tableName];
+    // Tenant scope first: it is emitted before the request's own filter, so its values must be
+    // bound in that order too.
+    const guard = buildTenantRowGuard(db, tenantForTable(tenant, joinTableConf), subAlias);
+    let tenantWhere = '';
+    const tenantVals = [];
+    if (guard) {
+        const rendered = guard.toExpression();
+        tenantWhere = ` AND ${rendered.value}`;
+        tenantVals.push(...rendered.values);
+    }
+    if (groupReq.filters || groupReq.conditions?.length) {
+        const cb = buildJoinRefCondition(joinTableConf, joinSchema, { filters: groupReq.filters, conditions: groupReq.conditions }, db, subAlias);
+        const fragment = cb.toExpression();
+        if (fragment.value) {
+            filterWhere = ` AND ${fragment.value}`;
+            filterVals = [...fragment.values];
+        }
+    }
+    const qualifiedCol = `${subRef}.${db.qi(fieldCol)}`;
+    const expr = `COALESCE((SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere}), 0)`;
+    return new Expression(expr, [...tenantVals, ...filterVals]);
+}
+/** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */
+export function appendAggConditions(params, conditions, db, dbTables, tableConf, joinGroup, tenant) {
+    let where = '';
+    for (const c of conditions) {
+        if (!c.field.includes('.'))
+            continue;
+        if (!ALLOWED_SET.has(c.method)) {
+            err400(`Invalid condition method: ${c.method}`);
+        }
+        const parts = c.field.split('.');
+        if (parts.length !== 3) {
+            err400(`Invalid dotted field in condition: ${c.field} (expected <alias>.<fn>.<field>)`);
+        }
+        const [alias, fn, field] = parts;
+        // The aggregate carries the values of its own filter; passing it as the left-hand side
+        // lets the ConditionBuilder place those and the compared value in one step.
+        const expr = buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, tenant);
+        const tmpCb = new ConditionBuilder('AND', db.cbDialect);
+        dispatchConditionMethod(tmpCb, c.method, expr, c.params);
+        where += ` AND ${params.emitCondition(tmpCb, db)}`;
+    }
+    return where;
+}

package/dist/lib/engine/search/conditions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Turning a request's `filters` and `conditions` into ConditionBuilder clauses.
+ *
+ * The method vocabulary itself lives in lib/condition-methods.ts, which is a pure data
+ * module shared with the TypeBox schema builders — the dispatch below is kept out of it so
+ * that module keeps its zero dependencies.
+ */
+import { ConditionBuilder, Expression } from 'node-condition-builder';
+import type { QueryClient } from '../../db.js';
+import type { FilterRecord, ITable, JoinRefFilter, SchemaDefinition, SearchCondition } from '../../../types.js';
+/**
+ * Apply one condition method to a builder, after checking the request actually supplied the
+ * operands that method needs.
+ *
+ * `params` is optional in the request schema, so `{field, method}` with no params is a
+ * well-formed request that reaches here — reading `params[0]` off it throws a TypeError the
+ * error handler can only report as a 500. Arity is checked here rather than at the four call
+ * sites so no path can skip it.
+ */
+export declare function dispatchConditionMethod(cb: ConditionBuilder, method: string, colOrExpr: string | Expression, params: unknown[] | undefined): void;
+export declare function buildJoinRefCondition(joinTableConf: ITable | undefined, joinSchema: SchemaDefinition, ref: JoinRefFilter, db: QueryClient, qualifier?: string): ConditionBuilder;
+/**
+ * Apply non-dotted conditions to the main `condition` ConditionBuilder when
+ * possible. For schema fields → straight dispatch. For computed fields → return
+ * side-channel clauses to be appended to WHERE later (with correct placeholder
+ * offsets), since ConditionBuilder cannot bind values for an LHS expression.
+ */
+export declare function applyConditions(condition: ConditionBuilder, conditions: SearchCondition[], schema: SchemaDefinition, tableConf: ITable, db: QueryClient): void;
+/** Computed-field equality filters on the main table. */
+export declare function applyComputedFilters(condition: ConditionBuilder, filters: FilterRecord, tableConf: ITable, db: QueryClient): void;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/lib/engine/search/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/conditions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW/C,OAAO,KAAK,EAEV,YAAY,EACZ,MAAM,EACN,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAAG,UAAU,EAC9B,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,GAC5B,IAAI,CA4BN;AAuDD,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,UAAU,EAAE,gBAAgB,EAC5B,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,WAAW,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAuBlB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAC3B,UAAU,EAAE,eAAe,EAAE,EAC7B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,WAAW,GACd,IAAI,CAcN;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,WAAW,GACd,IAAI,CAIN"}

package/dist/lib/engine/search/conditions.js

@@ -0,0 +1,131 @@
+/**
+ * Turning a request's `filters` and `conditions` into ConditionBuilder clauses.
+ *
+ * The method vocabulary itself lives in lib/condition-methods.ts, which is a pure data
+ * module shared with the TypeBox schema builders — the dispatch below is kept out of it so
+ * that module keeps its zero dependencies.
+ */
+import { ConditionBuilder } from 'node-condition-builder';
+import { assertFiltersReadable, ownField } from '../../read-access.js';
+import { ALLOWED_SET, SINGLE_VALUE_SET, BETWEEN_SET, IN_SET, NULL_SET, } from '../../condition-methods.js';
+import { err400, validateSchemaField, evaluateComputedField, resolveFieldRef, } from './fields.js';
+/**
+ * Apply one condition method to a builder, after checking the request actually supplied the
+ * operands that method needs.
+ *
+ * `params` is optional in the request schema, so `{field, method}` with no params is a
+ * well-formed request that reaches here — reading `params[0]` off it throws a TypeError the
+ * error handler can only report as a 500. Arity is checked here rather than at the four call
+ * sites so no path can skip it.
+ */
+export function dispatchConditionMethod(cb, method, colOrExpr, params) {
+    if (params !== undefined && !Array.isArray(params)) {
+        err400(`Condition method '${method}': 'params' must be an array`);
+    }
+    const args = params ?? [];
+    const require = (n) => {
+        if (args.length < n) {
+            err400(`Condition method '${method}' requires ${n} param(s), got ${args.length}`);
+        }
+    };
+    if (SINGLE_VALUE_SET.has(method)) {
+        require(1);
+        cb[method](colOrExpr, args[0]);
+    }
+    else if (BETWEEN_SET.has(method)) {
+        require(2);
+        cb[method](colOrExpr, args[0], args[1]);
+    }
+    else if (IN_SET.has(method)) {
+        require(1);
+        // An explicit `undefined` stays a documented no-op; any other non-array would make the
+        // builder iterate a non-iterable.
+        if (args[0] !== undefined && !Array.isArray(args[0])) {
+            err400(`Condition method '${method}' requires an array as its first param`);
+        }
+        cb[method](colOrExpr, args[0]);
+    }
+    else if (NULL_SET.has(method)) {
+        cb[method](colOrExpr, true);
+    }
+}
+/**
+ * Equality filters targeting *computed* fields: `filters.<computedName>` becomes
+ * `<expr> = <value>` on the builder `tableConf.filters()` has already populated with the plain
+ * column filters. A name that is not a declared computed field is skipped — it was either
+ * handled there or rejected up front by `assertKnownFilterKeys`.
+ *
+ * `qualifier` prefixes the columns the computed expression references: the join's qualifier
+ * inside a side query, undefined on the main table (where the schema's own name is used).
+ */
+function applyComputedEqualityFilters(cb, filters, computed, schema, db, qualifier) {
+    if (!computed)
+        return;
+    for (const [name, value] of Object.entries(filters)) {
+        if (value === null || value === undefined)
+            continue;
+        const fn = ownField(computed, name);
+        if (!fn)
+            continue;
+        const expr = evaluateComputedField(name, fn, schema, db, qualifier, '', true);
+        cb.isEqual(expr, value);
+    }
+}
+/** Operator conditions on a join reference, against a schema or a computed field. */
+function applyJoinRefConditions(cb, conditions, joinTableConf, joinSchema, db, colQualifier) {
+    const computed = joinTableConf?.computedFields;
+    for (const c of conditions) {
+        if (!ALLOWED_SET.has(c.method)) {
+            err400(`Invalid condition method: ${c.method}`);
+        }
+        // Computed fields resolve to an Expression carrying their own bound values, which the
+        // ConditionBuilder places together with the compared value.
+        const fn = ownField(computed, c.field);
+        const operand = fn
+            ? evaluateComputedField(c.field, fn, joinSchema, db, colQualifier, '', true)
+            : `${db.qi(colQualifier)}.${db.qi(validateSchemaField(c.field, joinSchema, joinTableConf))}`;
+        dispatchConditionMethod(cb, c.method, operand, c.params ?? []);
+    }
+}
+export function buildJoinRefCondition(joinTableConf, joinSchema, ref, db, qualifier) {
+    assertFiltersReadable(ref.filters, joinTableConf);
+    // Filter keys are checked by assertJoinFilterKeys, up front in searchEngine — this side
+    // query may never run, so it is not a place a request can be rejected from.
+    // Bare table name for plain side-queries; the subquery alias when the condition lands
+    // inside an aliased, correlated FROM (there the table name would resolve to the outer query).
+    const colQualifier = qualifier ?? joinSchema.tableName;
+    const cb = (ref.filters && joinTableConf)
+        ? joinTableConf.filters(ref.filters, db.cbDialect, colQualifier)
+        : new ConditionBuilder('AND', db.cbDialect);
+    if (ref.filters) {
+        applyComputedEqualityFilters(cb, ref.filters, joinTableConf?.computedFields, joinSchema, db, colQualifier);
+    }
+    if (ref.conditions?.length) {
+        applyJoinRefConditions(cb, ref.conditions, joinTableConf, joinSchema, db, colQualifier);
+    }
+    return cb;
+}
+/**
+ * Apply non-dotted conditions to the main `condition` ConditionBuilder when
+ * possible. For schema fields → straight dispatch. For computed fields → return
+ * side-channel clauses to be appended to WHERE later (with correct placeholder
+ * offsets), since ConditionBuilder cannot bind values for an LHS expression.
+ */
+export function applyConditions(condition, conditions, schema, tableConf, db) {
+    for (const c of conditions) {
+        // Skip dot-notation fields — those become aggregation conditions processed later
+        if (c.field.includes('.'))
+            continue;
+        if (!ALLOWED_SET.has(c.method)) {
+            err400(`Invalid condition method: ${c.method}`);
+        }
+        // A computed field resolves to an Expression carrying its own bound values; the
+        // ConditionBuilder places them, so no placeholder offset is computed here.
+        const ref = resolveFieldRef(c.field, schema, tableConf, db);
+        dispatchConditionMethod(condition, c.method, ref.expr, c.params);
+    }
+}
+/** Computed-field equality filters on the main table. */
+export function applyComputedFilters(condition, filters, tableConf, db) {
+    applyComputedEqualityFilters(condition, filters, tableConf.computedFields, tableConf.Schema, db);
+}

package/dist/lib/engine/search/fields.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Field resolution for the search engine: turning a name in a request body into a SQL
+ * operand, and rows back into API records.
+ *
+ * This is the leaf of the search modules — it knows about schemas, computed fields and
+ * read access, and nothing about joins, ordering or query execution.
+ */
+import { Expression } from 'node-condition-builder';
+import type { QueryClient } from '../../db.js';
+import type { ITable, SchemaDefinition, ComputedFieldFn } from '../../../types.js';
+export declare function validateSchemaField(field: string, schema: SchemaDefinition, tableConf?: ITable): string;
+export declare function err400(msg: string): never;
+/**
+ * Resolve a field reference in a request body to a SQL operand. A schema column becomes
+ * the quoted column name; a computed field becomes an Expression carrying its own bound
+ * values, so it can be handed straight to a ConditionBuilder. Throws 400 if neither.
+ */
+export interface ResolvedFieldRef {
+    expr: string | Expression;
+    computed: boolean;
+}
+export declare function resolveFieldRef(field: string, schema: SchemaDefinition, tableConf: ITable | undefined, db: QueryClient, alias?: string): ResolvedFieldRef;
+/**
+ * Evaluate a computed field into an Expression carrying its own bound values.
+ *
+ * Inside a WHERE clause the ConditionBuilder assigns the placeholder indexes, so bound
+ * values are always safe there. `allowBoundValues=false` is for the positions that sit
+ * *before* the WHERE values in the parameter order (SELECT projections, aggregations),
+ * where they cannot be placed correctly; those still reject with 400.
+ */
+export declare function evaluateComputedField(name: string, fn: ComputedFieldFn, schema: SchemaDefinition, db: QueryClient, alias: string | undefined, message: string, allowBoundValues?: boolean): Expression;
+/** Bound values carried by a resolved field reference. */
+export declare function refValues(expr: string | Expression): unknown[];
+/** Render a resolved field reference to SQL, binding any values from `startIndex`. */
+export declare function renderRef(expr: string | Expression, startIndex: number, db: QueryClient): string;
+/** Map rows from snake_case columns to camelCase fields, preserving any computed-field columns
+ * that are projected by their declared name (skipped by camelcaseObject). */
+export declare function mapRowsToCamelCase(rows: Record<string, unknown>[], schema: SchemaDefinition, computedFieldNames?: Iterable<string>): Record<string, unknown>[];
+/**
+ * Build the SELECT columns list for a join fetch: '*' or comma-separated quoted columns.
+ * A default '*' selection narrows to the join table's readable columns when it declares
+ * `readExclude`; an explicit selection naming an excluded field is rejected with 400.
+ *
+ * On a relation narrowed by a `fields` allowlist the '*' is always spelled out. Emitting a
+ * real `SELECT *` there would fetch the excluded columns and leave them to be dropped by
+ * the response serializer — which does not run for a caller of `sqlApi.search()`.
+ */
+export declare function buildSelectionColumns(selection: string, joinSchema: SchemaDefinition, db: QueryClient, joinTableConf?: ITable, restricted?: boolean): string;
+//# sourceMappingURL=fields.d.ts.map

package/dist/lib/engine/search/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/fields.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS/C,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAGhB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAI3B,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,EACxB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAQR;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAIzC;AA6BD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,EAAE,EAAE,WAAW,EACf,KAAK,CAAC,EAAE,MAAM,GACb,gBAAgB,CAiBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,EACf,gBAAgB,UAAQ,GACvB,UAAU,CAMZ;AA0BD,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,EAAE,CAE9D;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,WAAW,GACd,MAAM,CAER;AAED;6EAC6E;AAC7E,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,MAAM,EAAE,gBAAgB,EACxB,kBAAkB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAW3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,gBAAgB,EAC5B,EAAE,EAAE,WAAW,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,UAAU,UAAQ,GACjB,MAAM,CAUR"}

package/dist/lib/engine/search/fields.js

@@ -0,0 +1,142 @@
+/**
+ * Field resolution for the search engine: turning a name in a request body into a SQL
+ * operand, and rows back into API records.
+ *
+ * This is the leaf of the search modules — it knows about schemas, computed fields and
+ * read access, and nothing about joins, ordering or query execution.
+ */
+import { Expression } from 'node-condition-builder';
+import { camelcaseObject } from '../../naming.js';
+import { assertReadable, readableSelectColumns, explicitSelectColumns, hasOwnField, ownField, } from '../../read-access.js';
+// ─── Schema field validation ────────────────────────────────
+export function validateSchemaField(field, schema, tableConf) {
+    if (!hasOwnField(schema.fields, field)) {
+        const err = new Error(`Unknown field: ${field}`);
+        err.statusCode = 400;
+        throw err;
+    }
+    assertReadable(tableConf, field);
+    return schema.col(field);
+}
+export function err400(msg) {
+    const e = new Error(msg);
+    e.statusCode = 400;
+    throw e;
+}
+// ─── Computed fields resolution ─────────────────────────────
+/**
+ * Build a ComputedFieldContext bound to a specific table/schema. `alias`
+ * (if provided) qualifies the columns produced by `qiCol` — needed when the
+ * computed is embedded in a `LEFT JOIN <table> AS <alias>` (joinLeft).
+ */
+function buildComputedContext(db, schema, alias) {
+    return {
+        db,
+        qiCol(field, opts) {
+            if (!hasOwnField(schema.fields, field)) {
+                err400(`Unknown field referenced by computed expression: ${field}`);
+            }
+            const col = db.qi(schema.col(field));
+            // Default to the owning table: the statement may carry joins, and a bare
+            // column shared with a joined table would be ambiguous.
+            const qualifier = opts?.qualifier ?? alias ?? schema.tableName;
+            return qualifier ? `${db.qi(qualifier)}.${col}` : col;
+        },
+    };
+}
+export function resolveFieldRef(field, schema, tableConf, db, alias) {
+    if (hasOwnField(schema.fields, field)) {
+        assertReadable(tableConf, field);
+        const col = db.qi(schema.col(field));
+        // Qualified with the alias or the owning table — never bare, so the reference
+        // stays unambiguous when the statement carries joins.
+        const expr = `${db.qi(alias ?? schema.tableName)}.${col}`;
+        return { expr, computed: false };
+    }
+    const fn = ownField(tableConf?.computedFields, field);
+    if (fn) {
+        const ctx = buildComputedContext(db, schema, alias);
+        return { expr: computedExpression(field, fn(ctx)), computed: true };
+    }
+    err400(`Unknown field: ${field}`);
+}
+/**
+ * Evaluate a computed field into an Expression carrying its own bound values.
+ *
+ * Inside a WHERE clause the ConditionBuilder assigns the placeholder indexes, so bound
+ * values are always safe there. `allowBoundValues=false` is for the positions that sit
+ * *before* the WHERE values in the parameter order (SELECT projections, aggregations),
+ * where they cannot be placed correctly; those still reject with 400.
+ */
+export function evaluateComputedField(name, fn, schema, db, alias, message, allowBoundValues = false) {
+    const ev = fn(buildComputedContext(db, schema, alias));
+    if (!allowBoundValues && (ev.values?.length ?? 0) > 0) {
+        err400(message);
+    }
+    return computedExpression(name, ev);
+}
+/**
+ * Build the Expression for a computed field, checking that it marks each bound value
+ * with a `?`.
+ *
+ * A mismatch is always a table-configuration bug and would otherwise produce a query that
+ * binds values nobody references — silently returning wrong rows. Expressions without
+ * bound values are exempt: they are emitted verbatim, so a `?` there is a literal operator
+ * (PostgreSQL jsonb) rather than a marker.
+ */
+function computedExpression(name, ev) {
+    const values = ev.values ?? [];
+    if (values.length > 0) {
+        const markers = (ev.expr.match(/\\\?|\?/g) ?? []).filter((m) => m === '?').length;
+        if (markers !== values.length) {
+            throw new Error(`Computed field '${name}' declares ${values.length} bound value(s) but its expression ` +
+                `contains ${markers} '?' marker(s). Mark each bound value with '?' (use '\\?' for a ` +
+                `literal question mark) so the engine can assign placeholder positions.`);
+        }
+    }
+    return new Expression(ev.expr, values);
+}
+/** Bound values carried by a resolved field reference. */
+export function refValues(expr) {
+    return expr instanceof Expression ? [...expr.values] : [];
+}
+/** Render a resolved field reference to SQL, binding any values from `startIndex`. */
+export function renderRef(expr, startIndex, db) {
+    return expr instanceof Expression ? expr.render(startIndex, db.ph) : expr;
+}
+/** Map rows from snake_case columns to camelCase fields, preserving any computed-field columns
+ * that are projected by their declared name (skipped by camelcaseObject). */
+export function mapRowsToCamelCase(rows, schema, computedFieldNames) {
+    const computed = computedFieldNames ? new Set(computedFieldNames) : null;
+    return rows.map((r) => {
+        const camel = camelcaseObject(r, schema);
+        if (computed) {
+            for (const name of computed) {
+                if (name in r)
+                    camel[name] = r[name];
+            }
+        }
+        return camel;
+    });
+}
+/**
+ * Build the SELECT columns list for a join fetch: '*' or comma-separated quoted columns.
+ * A default '*' selection narrows to the join table's readable columns when it declares
+ * `readExclude`; an explicit selection naming an excluded field is rejected with 400.
+ *
+ * On a relation narrowed by a `fields` allowlist the '*' is always spelled out. Emitting a
+ * real `SELECT *` there would fetch the excluded columns and leave them to be dropped by
+ * the response serializer — which does not run for a caller of `sqlApi.search()`.
+ */
+export function buildSelectionColumns(selection, joinSchema, db, joinTableConf, restricted = false) {
+    if (selection === '*') {
+        if (restricted)
+            return explicitSelectColumns(joinTableConf, joinSchema, db);
+        return readableSelectColumns(joinTableConf, joinSchema, db) ?? '*';
+    }
+    const table = db.qi(joinSchema.tableName);
+    return selection
+        .split(',')
+        .map((c) => `${table}.${db.qi(validateSchemaField(c.trim(), joinSchema, joinTableConf))}`)
+        .join(', ');
+}

package/dist/lib/engine/search/join-families.d.ts

@@ -0,0 +1,35 @@
+import type { QueryClient } from '../../db.js';
+import type { QueryParams } from '../query-params.js';
+import type { DbTables, ITable, JoinFetchRequest, JoinGroupRequest, JoinRefFilter, TenantContext } from '../../../types.js';
+interface LeftJoinOnBuild {
+    joinClauses: string[];
+    values: unknown[];
+}
+interface LeftJoinFilterBuild {
+    whereExtras: string[];
+    values: unknown[];
+}
+/**
+ * The LEFT JOIN clauses themselves, each carrying the joined table's own tenant scope.
+ *
+ * The scope belongs in the ON clause, not the WHERE. In the WHERE it would discard main rows
+ * whose parent belongs to another tenant, silently turning the LEFT JOIN into an INNER JOIN.
+ * In the ON clause a foreign parent simply fails to match and reads as NULL, which closes the
+ * oracle: the parent rows are already withheld from the response (`executeJoinLeft` scopes its
+ * own side query), so an unscoped join would let a caller filter on values it cannot see and
+ * recover them one predicate at a time.
+ *
+ * Emitted before the WHERE fragments because that is where it lands in the statement — MySQL
+ * binds `?` positionally.
+ */
+export declare function buildLeftJoinOnClauses(db: QueryClient, dbTables: DbTables, tableConf: ITable, aliasesNeedingJoin: Set<string>, startIdx: number, tenant?: TenantContext): LeftJoinOnBuild;
+/** The WHERE fragments a `joinLeft` request's own filters and conditions contribute. */
+export declare function buildLeftJoinFilters(db: QueryClient, dbTables: DbTables, tableConf: ITable, aliasesNeedingJoin: Set<string>, joinLeft: Record<string, JoinFetchRequest> | undefined, startIdx: number): LeftJoinFilterBuild;
+/** joinMultiple: 1:N children, returned as rows under `result.joinMultiple.<alias>`. */
+export declare function executeJoinMultiple(db: QueryClient, dbTables: DbTables, tableConf: ITable, mainResults: Record<string, unknown>[], joinMultiple: Record<string, JoinFetchRequest>, tenant?: TenantContext): Promise<Record<string, Record<string, unknown>[]>>;
+/** joinLeft: N:1 parents, returned as rows under `result.joinLeft.<alias>`. */
+export declare function executeJoinLeft(db: QueryClient, dbTables: DbTables, tableConf: ITable, mainResults: Record<string, unknown>[], joinLeft: Record<string, JoinFetchRequest>, tenant?: TenantContext): Promise<Record<string, Record<string, unknown>[]>>;
+export declare function executeJoinGroup(db: QueryClient, dbTables: DbTables, tableConf: ITable, mainResults: Record<string, unknown>[], joinGroup: Record<string, JoinGroupRequest>, tenant?: TenantContext): Promise<Record<string, Record<string, unknown>>>;
+export declare function buildJoinMustExistClauses(params: QueryParams, db: QueryClient, dbTables: DbTables, tableConf: ITable, joinMustExist: Record<string, JoinRefFilter>, tenant?: TenantContext): string;
+export {};
+//# sourceMappingURL=join-families.d.ts.map

package/dist/lib/engine/search/join-families.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-families.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/join-families.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAmBtD,OAAO,KAAK,EAEV,QAAQ,EAER,MAAM,EACN,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EAGb,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAI3B,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,UAAU,mBAAmB;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB;AAsED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,aAAa,GACrB,eAAe,CAgCjB;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACtD,QAAQ,EAAE,MAAM,GACf,mBAAmB,CA0CrB;AAmGD,wFAAwF;AACxF,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC9C,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAKpD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC1C,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAKpD;AAsGD,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC3C,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAqClD;AAyBD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,WAAW,EACnB,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC5C,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CA4BR"}