fastify-auto-sqlapi 0.1.14 → 0.2.0

package/dist/lib/engine/search/join-families.js

@@ -0,0 +1,345 @@
+/**
+ * The four join families, each executed against the rows the main query returned.
+ *
+ *   joinMustExist  child -> main, 1:N   EXISTS filter on the main query (returns no rows)
+ *   joinMultiple   child -> main, 1:N   side query, rows under result.joinMultiple.<alias>
+ *   joinGroup      child -> main, 1:N   aggregations under result.joinGroup.<alias>
+ *   joinLeft       parent -> main, N:1  real LEFT JOIN on demand + side query for the rows
+ */
+import { ConditionBuilder, Expression } from 'node-condition-builder';
+import { assertReadable, assertFiltersReadable, hasOwnField, ownField } from '../../read-access.js';
+import { ALLOWED_SET } from '../../condition-methods.js';
+import { err400, validateSchemaField, evaluateComputedField, mapRowsToCamelCase, buildSelectionColumns, } from './fields.js';
+import { appendJoinTenantScope, subqueryAlias, requireJoin, extractJoinRefs, } from './joins.js';
+import { tenantForTable, buildTenantRowGuard } from '../../tenant.js';
+import { dispatchConditionMethod, buildJoinRefCondition } from './conditions.js';
+import { AGG_FN, aggExpr } from './aggregations.js';
+/**
+ * Resolve a joinLeft field to an alias-qualified SQL reference: a schema column, or a
+ * computed field's expression. Returns null when the field is neither — the caller decides
+ * whether that is a silent skip (filters) or a 400 (conditions).
+ *
+ * References go through the alias, not the table name, so they hit the LEFT JOIN'd row.
+ */
+function resolveJoinLeftField(field, scope) {
+    const { db, alias, aliasIdent, joinSchema, computed } = scope;
+    if (hasOwnField(joinSchema.fields, field)) {
+        // Wrapped so this helper has a single return type. A value-less Expression renders
+        // verbatim (see renderField), so the emitted SQL is identical to the raw identifier.
+        return new Expression(`${aliasIdent}.${db.qi(joinSchema.col(field))}`);
+    }
+    const fn = ownField(computed, field);
+    if (fn) {
+        // Bound values are allowed: this ConditionBuilder's SQL lands in the WHERE clause.
+        return evaluateComputedField(field, fn, joinSchema, db, alias, '', true);
+    }
+    return null;
+}
+/** `joinLeft.filters` — equality only. Unknown keys are ignored, as they always were. */
+function applyJoinLeftFilters(cb, filters, scope) {
+    for (const [field, value] of Object.entries(filters)) {
+        if (value === null || value === undefined)
+            continue;
+        const ref = resolveJoinLeftField(field, scope);
+        if (ref !== null)
+            cb.isEqual(ref, value);
+    }
+}
+/** `joinLeft.conditions` — operator methods. An unknown field is a 400, not a no-op. */
+function applyJoinLeftConditions(cb, conditions, scope, dbTables) {
+    for (const c of conditions) {
+        if (!ALLOWED_SET.has(c.method)) {
+            err400(`Invalid condition method: ${c.method}`);
+        }
+        if (hasOwnField(scope.joinSchema.fields, c.field)) {
+            assertReadable(dbTables[scope.joinSchema.tableName], c.field);
+        }
+        else if (!ownField(scope.computed, c.field)) {
+            err400(`Unknown field: ${c.field}`);
+        }
+        const ref = resolveJoinLeftField(c.field, scope);
+        if (ref !== null)
+            dispatchConditionMethod(cb, c.method, ref, c.params ?? []);
+    }
+}
+/**
+ * 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 function buildLeftJoinOnClauses(db, dbTables, tableConf, aliasesNeedingJoin, startIdx, tenant) {
+    const joinClauses = [];
+    const values = [];
+    let currentIdx = startIdx;
+    for (const alias of aliasesNeedingJoin) {
+        const joinDef = requireJoin(tableConf, alias, true);
+        const refs = extractJoinRefs(db, tableConf, joinDef);
+        const aliasIdent = db.qi(alias);
+        // The guard references the join through its ALIAS: one table may be joined under several
+        // aliases, and each predicate must bind to the row this clause produced.
+        const guard = buildTenantRowGuard(db, tenantForTable(tenant, dbTables[joinDef.joinSchema.tableName]), alias);
+        let scoped = '';
+        if (guard) {
+            scoped = ` AND ${guard.build(currentIdx, db.ph)}`;
+            const guardValues = guard.getValues();
+            values.push(...guardValues);
+            currentIdx += guardValues.length;
+        }
+        joinClauses.push(`LEFT JOIN ${refs.joinTable} AS ${aliasIdent} ON ${aliasIdent}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${scoped}`);
+    }
+    return { joinClauses, values };
+}
+/** The WHERE fragments a `joinLeft` request's own filters and conditions contribute. */
+export function buildLeftJoinFilters(db, dbTables, tableConf, aliasesNeedingJoin, joinLeft, startIdx) {
+    const whereExtras = [];
+    const values = [];
+    let currentIdx = startIdx;
+    for (const alias of aliasesNeedingJoin) {
+        const joinDef = requireJoin(tableConf, alias, true);
+        const { joinSchema } = joinDef;
+        const aliasIdent = db.qi(alias);
+        const ref = joinLeft?.[alias];
+        if (!ref || !(ref.filters || ref.conditions?.length))
+            continue;
+        // extraFilters declared on joinTableConf are not supported for joinLeft (they would
+        // require alias-aware handlers); only schema and computed fields apply.
+        // `assertJoinFilterKeys` rejects them up front rather than letting them through as a
+        // silent no-op, and the generated body schema does not advertise them for unique:true
+        // relations.
+        const joinTableConf = dbTables[joinSchema.tableName];
+        const scope = {
+            db,
+            alias,
+            aliasIdent,
+            joinSchema,
+            computed: joinTableConf?.computedFields,
+        };
+        const cb = new ConditionBuilder('AND', db.cbDialect);
+        assertFiltersReadable(ref.filters, joinTableConf);
+        if (ref.filters)
+            applyJoinLeftFilters(cb, ref.filters, scope);
+        if (ref.conditions?.length)
+            applyJoinLeftConditions(cb, ref.conditions, scope, dbTables);
+        const sql = cb.build(currentIdx, db.ph);
+        const vals = cb.getValues();
+        if (sql) {
+            whereExtras.push(sql);
+            values.push(...vals);
+            currentIdx += vals.length;
+        }
+    }
+    return { whereExtras, values };
+}
+// ─── Row-returning join families (side query per alias) ─────
+/**
+ * Correlate a join side query to the rows the main query returned (`fk IN (ids)`) and apply
+ * the tenant scope, then freeze it into SQL.
+ *
+ * Placeholders start at 1 because every side query is a statement of its own.
+ */
+function scopeJoinSideQuery(cb, db, joinSchema, joinField, ids, joinTableConf, tenant) {
+    cb.isIn(`${db.qi(joinSchema.tableName)}.${db.qi(joinSchema.col(joinField))}`, ids);
+    const tenantJoins = [];
+    appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
+    const where = cb.build(1, db.ph);
+    return { where, values: cb.getValues(), tenantJoins };
+}
+async function fetchJoinRows(db, dbTables, tableConf, mainResults, requests, mode, tenant) {
+    const result = {};
+    for (const [alias, ref] of Object.entries(requests)) {
+        const joinDef = requireJoin(tableConf, alias, mode.requireUnique);
+        const { joinSchema, joinField, mainField, selection: defaultSelection } = joinDef;
+        const joinTableConf = dbTables[joinSchema.tableName];
+        // The selection is resolved before the empty-result bail-out: it is validated against
+        // the join schema, and that rejection must not depend on whether the main query
+        // matched rows.
+        const selection = ref?.selection ?? defaultSelection;
+        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf, joinDef.fields !== undefined);
+        // For joinLeft, mainField on the main table is the FK pointing at joinField (the
+        // parent's PK), so the same collect-then-look-up works for both directions.
+        const ids = collectIds(mainResults, mainField);
+        if (ids.length === 0) {
+            result[alias] = [];
+            continue;
+        }
+        const cb = mode.applyRefCondition
+            ? buildJoinRefCondition(joinTableConf, joinSchema, ref || {}, db)
+            : new ConditionBuilder('AND', db.cbDialect);
+        const { where, values, tenantJoins } = scopeJoinSideQuery(cb, db, joinSchema, joinField, ids, joinTableConf, tenant);
+        const rows = await db.select({
+            tableName: joinSchema.tableName,
+            columns,
+            where,
+            values,
+            joins: tenantJoins.length > 0 ? tenantJoins : undefined,
+        });
+        result[alias] = mapRowsToCamelCase(rows, joinSchema);
+    }
+    return result;
+}
+/** joinMultiple: 1:N children, returned as rows under `result.joinMultiple.<alias>`. */
+export function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMultiple, tenant) {
+    return fetchJoinRows(db, dbTables, tableConf, mainResults, joinMultiple, {
+        requireUnique: false,
+        applyRefCondition: true,
+    }, tenant);
+}
+/** joinLeft: N:1 parents, returned as rows under `result.joinLeft.<alias>`. */
+export function executeJoinLeft(db, dbTables, tableConf, mainResults, joinLeft, tenant) {
+    return fetchJoinRows(db, dbTables, tableConf, mainResults, joinLeft, {
+        requireUnique: true,
+        applyRefCondition: false,
+    }, tenant);
+}
+/**
+ * Resolve `aggregations.by` to a SQL expression. Accepts:
+ *  - a schema field name → quoted column reference
+ *  - a computed-field name declared on the join table → its expr (no bound
+ *    values supported in this position; reject with 400 if the computed
+ *    returns values)
+ */
+function buildByExpression(by, joinSchema, joinTableConf, db) {
+    if (typeof by !== 'string') {
+        err400(`Invalid 'by' specification: expected a field or computed name`);
+    }
+    if (hasOwnField(joinSchema.fields, by)) {
+        // validateSchemaField also enforces readExclude: GROUP BY on a hidden field
+        // would return its distinct values verbatim in `rows[].by`.
+        const col = validateSchemaField(by, joinSchema, joinTableConf);
+        return `${db.qi(joinSchema.tableName)}.${db.qi(col)}`;
+    }
+    const fn = ownField(joinTableConf?.computedFields, by);
+    if (fn) {
+        return evaluateComputedField(by, fn, joinSchema, db, undefined, `Computed field '${by}' with bound values cannot be used in aggregations.by`).value;
+    }
+    err400(`Unknown field: ${by}`);
+}
+// ─── joinGroup (aggregations) ───────────────────────────────
+/**
+ * SELECT and GROUP BY fragments for one joinGroup alias.
+ *
+ * Every field is validated against the join schema here, so an unknown or unreachable one
+ * is a 400 regardless of what the data happens to contain.
+ */
+function buildJoinGroupSelect(aggregations, joinSchema, joinTableConf, db) {
+    const selectParts = [];
+    const groupByParts = [];
+    if (aggregations.by) {
+        const byExpr = buildByExpression(aggregations.by, joinSchema, joinTableConf, db);
+        selectParts.push(`${byExpr} as "by"`);
+        groupByParts.push(byExpr);
+    }
+    const addAgg = (kind, fields) => {
+        if (!fields)
+            return;
+        const fn = AGG_FN[kind];
+        for (const f of fields) {
+            const col = validateSchemaField(f, joinSchema, joinTableConf);
+            const colRef = `${db.qi(joinSchema.tableName)}.${db.qi(col)}`;
+            selectParts.push(`${aggExpr(fn, colRef)} as "${kind}_${f}"`);
+        }
+    };
+    addAgg('distinctCount', aggregations.distinctCount);
+    addAgg('min', aggregations.min);
+    addAgg('max', aggregations.max);
+    addAgg('sum', aggregations.sum);
+    addAgg('avg', aggregations.avg);
+    addAgg('count', aggregations.count);
+    return { selectParts, groupByParts };
+}
+/**
+ * Shape aggregation rows into the response: a single row without `by` collapses to
+ * `{ fn: { field: value } }`; anything else stays a list under `rows`.
+ */
+function formatJoinGroupRows(rows, hasBy) {
+    const formatted = {};
+    if (rows.length === 0)
+        return formatted;
+    const row = rows.length === 1 && !hasBy ? rows[0] : rows;
+    if (Array.isArray(row)) {
+        formatted.rows = row;
+        return formatted;
+    }
+    for (const [key, value] of Object.entries(row)) {
+        if (key === 'by')
+            continue;
+        const [fn, field] = key.split('_');
+        if (!formatted[fn])
+            formatted[fn] = {};
+        formatted[fn][field] = value;
+    }
+    return formatted;
+}
+export async function executeJoinGroup(db, dbTables, tableConf, mainResults, joinGroup, tenant) {
+    const result = {};
+    for (const [alias, groupReq] of Object.entries(joinGroup)) {
+        const joinDef = requireJoin(tableConf, alias, false);
+        const { joinSchema, joinField, mainField } = joinDef;
+        const joinTableConf = dbTables[joinSchema.tableName];
+        const ids = collectIds(mainResults, mainField);
+        const { aggregations, filters: groupFilters, conditions: groupConditions } = groupReq;
+        const { selectParts, groupByParts } = buildJoinGroupSelect(aggregations, joinSchema, joinTableConf, db);
+        // Bail out only here: `by` and every aggregation field have now been validated.
+        if (selectParts.length === 0 || ids.length === 0) {
+            result[alias] = {};
+            continue;
+        }
+        const groupRef = { filters: groupFilters, conditions: groupConditions };
+        const cb = buildJoinRefCondition(joinTableConf, joinSchema, groupRef, db);
+        const { where, values, tenantJoins } = scopeJoinSideQuery(cb, db, joinSchema, joinField, ids, joinTableConf, tenant);
+        const groupBy = groupByParts.length > 0 ? `GROUP BY ${groupByParts.join(', ')}` : '';
+        const fromJoins = tenantJoins.length > 0 ? ` ${tenantJoins.join(' ')}` : '';
+        const sql = `SELECT ${selectParts.join(', ')} FROM ${db.qi(joinSchema.tableName)}${fromJoins} WHERE ${where} ${groupBy}`;
+        const queryResult = await db.query(sql, values);
+        result[alias] = formatJoinGroupRows(queryResult.rows, Boolean(aggregations.by));
+    }
+    return result;
+}
+// ─── ID collection ──────────────────────────────────────────
+function collectIds(mainResults, mainField) {
+    if (Array.isArray(mainField)) {
+        const seen = new Set();
+        const ids = [];
+        for (const r of mainResults) {
+            const key = mainField.map((f) => r[f]).join('|');
+            if (!seen.has(key) && mainField.every((f) => r[f] != null)) {
+                seen.add(key);
+                ids.push(...mainField.map((f) => r[f]));
+            }
+        }
+        return ids;
+    }
+    return [...new Set(mainResults.map((r) => r[mainField]).filter((v) => v != null))];
+}
+// ─── joinMustExist (EXISTS subquery filter on main) ─────────
+export function buildJoinMustExistClauses(params, db, dbTables, tableConf, joinMustExist, tenant) {
+    let where = '';
+    for (const [alias, ref] of Object.entries(joinMustExist)) {
+        const joinDef = requireJoin(tableConf, alias, false);
+        const { joinSchema } = joinDef;
+        const joinTableConf = dbTables[joinSchema.tableName];
+        const refs = extractJoinRefs(db, tableConf, joinDef);
+        // The EXISTS 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);
+        const filterCondition = buildJoinRefCondition(joinTableConf, joinSchema, ref, db, subAlias);
+        const tenantJoins = [];
+        appendJoinTenantScope(db, joinTableConf, tenant, subAlias, filterCondition, tenantJoins);
+        const filterWhere = params.emitCondition(filterCondition, db);
+        const innerWhere = filterWhere
+            ? `${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol} AND ${filterWhere}`
+            : `${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}`;
+        const existsJoins = tenantJoins.length > 0 ? ` ${tenantJoins.join(' ')}` : '';
+        where += ` AND EXISTS (SELECT 1 FROM ${refs.joinTable} AS ${subRef}${existsJoins} WHERE ${innerWhere})`;
+    }
+    return where;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Join resolution for the search engine: finding the relation an alias refers to,
+ * validating what a request may ask of it, and quoting its identifiers.
+ *
+ * Relations are *declared* at config time by `buildRelation` (see lib/table-helpers.ts);
+ * this module resolves them per request.
+ */
+import { ConditionBuilder } from 'node-condition-builder';
+import type { QueryClient } from '../../db.js';
+import type { DbTables, FilterRecord, ITable, JoinDefinition, TenantContext } from '../../../types.js';
+/**
+ * Tenant-scope a join side-query. When the joined table declares its own `tenantScope`,
+ * appends the tenant condition to `cb` (direct: `col IN ids`; indirect: condition on the
+ * through table) and, for indirect scopes, pushes the INNER JOIN clause into `joins`.
+ * No-op without a tenant context (admin) or when the join table is not tenant-scoped.
+ *
+ * `joinTableRef` is the raw name the join table goes by in the statement: its table name
+ * in plain side-queries, or the subquery alias inside an aliased, correlated EXISTS.
+ */
+export declare function appendJoinTenantScope(db: QueryClient, joinTableConf: ITable | undefined, tenant: TenantContext | undefined, joinTableRef: string, cb: ConditionBuilder, joins?: string[]): void;
+/**
+ * Alias for the FROM of a correlated subquery (EXISTS, aggregate). The subquery must not
+ * say `FROM <table>` bare: on a self-referencing relation the inner table would shadow the
+ * outer one and the correlation would silently compare each row with itself. The request
+ * alias is used, suffixed when it would itself collide with the outer table's name.
+ */
+export declare function subqueryAlias(alias: string, tableConf: ITable): string;
+/**
+ * Validate the filter keys of every join reference in a request map.
+ *
+ * Runs up front, before any query: the executors skip their side-query entirely when the
+ * main result set is empty (`ids.length === 0`), so validating there alone would make the
+ * same request answer 400 or 200 depending on the data it happens to match.
+ *
+ * Unknown aliases are left to `requireJoin`, which reports them with its own message.
+ */
+export declare function assertJoinFilterKeys(dbTables: DbTables, tableConf: ITable, refs: Record<string, {
+    filters?: FilterRecord;
+}> | undefined, allowExtraFilters: boolean): void;
+export declare function requireJoin(tableConf: ITable, alias: string, requireUnique: boolean): JoinDefinition;
+export interface JoinRefs {
+    mainColName: string;
+    /** db.qi'd column reference on main side (FK or PK) */
+    mainCol: string;
+    /** db.qi'd table name on main side */
+    mainTable: string;
+    /** db.qi'd table name on join side */
+    joinTable: string;
+    /** db.qi'd column reference on join side (FK or PK) */
+    fkCol: string;
+}
+/** Extract quoted identifiers for a join reference. Used by joinMustExist, joinLeft and joinGroup
+ * SQL builders to avoid the 4-line FK/PK destructuring boilerplate at every call site. */
+export declare function extractJoinRefs(db: QueryClient, tableConf: ITable, joinDef: JoinDefinition): JoinRefs;
+//# sourceMappingURL=joins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"joins.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/joins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,cAAc,EACd,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,WAAW,EACf,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,gBAAgB,EACpB,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,GAAG,SAAS,EAC5D,iBAAiB,EAAE,OAAO,GACzB,IAAI,CAUN;AAED,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,OAAO,GACrB,cAAc,CAYhB;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;0FAC0F;AAC1F,wBAAgB,eAAe,CAC7B,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,GACtB,QAAQ,CAUV"}

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

@@ -0,0 +1,81 @@
+import { buildTenantCondition, buildTenantJoin } from '../../tenant.js';
+import { assertFiltersReadable, assertKnownFilterKeys } from '../../read-access.js';
+import { err400 } from './fields.js';
+/**
+ * Tenant-scope a join side-query. When the joined table declares its own `tenantScope`,
+ * appends the tenant condition to `cb` (direct: `col IN ids`; indirect: condition on the
+ * through table) and, for indirect scopes, pushes the INNER JOIN clause into `joins`.
+ * No-op without a tenant context (admin) or when the join table is not tenant-scoped.
+ *
+ * `joinTableRef` is the raw name the join table goes by in the statement: its table name
+ * in plain side-queries, or the subquery alias inside an aliased, correlated EXISTS.
+ */
+export function appendJoinTenantScope(db, joinTableConf, tenant, joinTableRef, cb, joins) {
+    const scope = joinTableConf?.tenantScope;
+    if (!tenant || !scope)
+        return;
+    cb.append(buildTenantCondition(db, scope, tenant.ids, joinTableRef));
+    if ('through' in scope) {
+        joins?.push(buildTenantJoin(db, scope, joinTableRef));
+    }
+}
+/**
+ * Alias for the FROM of a correlated subquery (EXISTS, aggregate). The subquery must not
+ * say `FROM <table>` bare: on a self-referencing relation the inner table would shadow the
+ * outer one and the correlation would silently compare each row with itself. The request
+ * alias is used, suffixed when it would itself collide with the outer table's name.
+ */
+export function subqueryAlias(alias, tableConf) {
+    return alias === tableConf.Schema.tableName ? `${alias}_sub` : alias;
+}
+function findJoinByAlias(tableConf, alias) {
+    return tableConf.allowedReadJoins?.find((j) => j.alias === alias);
+}
+/**
+ * Validate the filter keys of every join reference in a request map.
+ *
+ * Runs up front, before any query: the executors skip their side-query entirely when the
+ * main result set is empty (`ids.length === 0`), so validating there alone would make the
+ * same request answer 400 or 200 depending on the data it happens to match.
+ *
+ * Unknown aliases are left to `requireJoin`, which reports them with its own message.
+ */
+export function assertJoinFilterKeys(dbTables, tableConf, refs, allowExtraFilters) {
+    if (!refs)
+        return;
+    for (const [alias, ref] of Object.entries(refs)) {
+        const joinDef = findJoinByAlias(tableConf, alias);
+        if (!joinDef)
+            continue;
+        const joinTableConf = dbTables[joinDef.joinSchema.tableName];
+        const filters = ref?.filters;
+        assertFiltersReadable(filters, joinTableConf);
+        assertKnownFilterKeys(filters, joinDef.joinSchema, joinTableConf, allowExtraFilters);
+    }
+}
+export function requireJoin(tableConf, alias, requireUnique) {
+    const joinDef = findJoinByAlias(tableConf, alias);
+    if (!joinDef) {
+        err400(`Unknown join alias: ${alias}`);
+    }
+    if (requireUnique && !joinDef.unique) {
+        err400(`Join alias '${alias}' is not declared with unique:true; use joinMultiple/joinMustExist/joinGroup instead`);
+    }
+    if (!requireUnique && joinDef.unique) {
+        err400(`Join alias '${alias}' is declared with unique:true; use joinLeft instead`);
+    }
+    return joinDef;
+}
+/** Extract quoted identifiers for a join reference. Used by joinMustExist, joinLeft and joinGroup
+ * SQL builders to avoid the 4-line FK/PK destructuring boilerplate at every call site. */
+export function extractJoinRefs(db, tableConf, joinDef) {
+    const { joinSchema, joinField, mainField } = joinDef;
+    const mainColName = Array.isArray(mainField) ? mainField[0] : mainField;
+    return {
+        mainColName,
+        mainCol: db.qi(tableConf.Schema.col(mainColName)),
+        mainTable: db.qi(tableConf.Schema.tableName),
+        joinTable: db.qi(joinSchema.tableName),
+        fkCol: db.qi(joinSchema.col(joinField)),
+    };
+}

package/dist/lib/engine/search/order-by.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Parsing and validation of ordering, in its three dotted forms:
+ *   1-part  `field`              schema field or computed
+ *   2-part  `alias.field`        a joinLeft parent field, via a real LEFT JOIN
+ *   3-part  `alias.fn.field`     a joinGroup aggregation, via a correlated subquery
+ *
+ * The request `orderBy` is validated strictly; `defaultOrder` from the table config is
+ * deliberately lenient — see `convertConfiguredOrder`.
+ */
+import type { QueryClient } from '../../db.js';
+import type { DbTables, ITable, JoinGroupRequest, TenantContext } from '../../../types.js';
+export interface OrderByResult {
+    sql: string;
+    values: unknown[];
+    /** Aliases referenced in 2-part notation (joinLeft) — need a LEFT JOIN. */
+    leftJoinAliases: Set<string>;
+}
+/**
+ * Pre-scan `orderBy` for the joinLeft aliases referenced in 2-part notation (`<alias>.<field>`).
+ * Needed BEFORE building the LEFT JOIN clauses (which must know their aliases) while the actual
+ * orderBy SQL — with its parameter placeholders — is only baked later, once the LEFT JOIN value
+ * count is known. Validates each alias against `allowedReadJoins` (throws 400), mirroring
+ * `validateOrderBy`; 3-part aggregation entries are ignored (they use joinGroup, not a LEFT JOIN).
+ */
+export declare function collectOrderByLeftAliases(orderBy: string, tableConf: ITable): Set<string>;
+export declare function validateOrderBy(orderBy: string, tableConf: ITable, db: QueryClient, dbTables: DbTables, joinGroup: Record<string, JoinGroupRequest> | undefined, startIdx: number, tenant?: TenantContext): OrderByResult;
+/**
+ * Converts a configured order (`defaultOrder` or the primary-key fallback) to SQL.
+ * Unlike the request `orderBy` (strictly validated by `validateOrderBy`), this is
+ * lenient for backward compatibility: tokens matching a camelCase schema field are
+ * mapped to their quoted DB column, computed fields (without bound values) expand
+ * to their expression, and anything else passes through unchanged as raw SQL.
+ */
+export declare function convertConfiguredOrder(order: string, tableConf: ITable, db: QueryClient): string;
+//# sourceMappingURL=order-by.d.ts.map

package/dist/lib/engine/search/order-by.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-by.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/order-by.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAY/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE3F,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAazF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,aAAa,GACrB,aAAa,CAuDf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,WAAW,GACd,MAAM,CAwBR"}

package/dist/lib/engine/search/order-by.js

@@ -0,0 +1,104 @@
+import { err400, validateSchemaField, resolveFieldRef, refValues, renderRef, evaluateComputedField, } from './fields.js';
+import { requireJoin } from './joins.js';
+import { hasOwnField, ownField } from '../../read-access.js';
+import { buildAggOrderExpr } from './aggregations.js';
+/**
+ * Pre-scan `orderBy` for the joinLeft aliases referenced in 2-part notation (`<alias>.<field>`).
+ * Needed BEFORE building the LEFT JOIN clauses (which must know their aliases) while the actual
+ * orderBy SQL — with its parameter placeholders — is only baked later, once the LEFT JOIN value
+ * count is known. Validates each alias against `allowedReadJoins` (throws 400), mirroring
+ * `validateOrderBy`; 3-part aggregation entries are ignored (they use joinGroup, not a LEFT JOIN).
+ */
+export function collectOrderByLeftAliases(orderBy, tableConf) {
+    const aliases = new Set();
+    for (const part of orderBy.split(',')) {
+        const trimmed = part.trim();
+        if (/^(\w+)\.(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i.test(trimmed))
+            continue; // 3-part aggregation
+        const m = /^(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i.exec(trimmed);
+        if (m) {
+            const alias = m[1];
+            requireJoin(tableConf, alias, true);
+            aliases.add(alias);
+        }
+    }
+    return aliases;
+}
+export function validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, startIdx, tenant) {
+    const parts = orderBy.split(',');
+    const outParts = [];
+    const outValues = [];
+    const leftJoinAliases = new Set();
+    let currentIdx = startIdx;
+    for (const part of parts) {
+        const trimmed = part.trim();
+        // 3-part: <alias>.<fn>.<field> [ASC|DESC] (aggregation via joinGroup)
+        const dotted3 = /^(\w+)\.(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i.exec(trimmed);
+        if (dotted3) {
+            if (tableConf.distinctResults) {
+                err400('Cannot combine distinctResults with aggregation orderBy');
+            }
+            const [, alias, fn, field, dir] = dotted3;
+            const expr = buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, tenant);
+            const aggVals = [...expr.values];
+            outParts.push(`${renderRef(expr, currentIdx, db)} ${(dir || 'ASC').toUpperCase()}`);
+            outValues.push(...aggVals);
+            currentIdx += aggVals.length;
+            continue;
+        }
+        // 2-part: <alias>.<field> [ASC|DESC] (joinLeft inline ordering)
+        const dotted2 = /^(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i.exec(trimmed);
+        if (dotted2) {
+            const [, alias, field, dir] = dotted2;
+            const joinDef = requireJoin(tableConf, alias, true);
+            const col = validateSchemaField(field, joinDef.joinSchema, dbTables[joinDef.joinSchema.tableName]);
+            // Reference the LEFT JOIN'd table via its alias (SQL identifier).
+            outParts.push(`${db.qi(alias)}.${db.qi(col)} ${(dir || 'ASC').toUpperCase()}`);
+            leftJoinAliases.add(alias);
+            continue;
+        }
+        // 1-part: <field> [ASC|DESC] — schema field or computed
+        const plain = /^(\w+)(?:\s+(ASC|DESC))?$/i.exec(trimmed);
+        if (!plain) {
+            err400(`Invalid orderBy: ${trimmed}`);
+        }
+        const [, field, dir] = plain;
+        const ref = resolveFieldRef(field, tableConf.Schema, tableConf, db);
+        // A computed field binds its own values here: ORDER BY is emitted after the WHERE, so
+        // its placeholders continue from `currentIdx`.
+        const refVals = refValues(ref.expr);
+        outParts.push(`${renderRef(ref.expr, currentIdx, db)} ${(dir || 'ASC').toUpperCase()}`);
+        outValues.push(...refVals);
+        currentIdx += refVals.length;
+    }
+    return { sql: outParts.join(', '), values: outValues, leftJoinAliases };
+}
+/**
+ * Converts a configured order (`defaultOrder` or the primary-key fallback) to SQL.
+ * Unlike the request `orderBy` (strictly validated by `validateOrderBy`), this is
+ * lenient for backward compatibility: tokens matching a camelCase schema field are
+ * mapped to their quoted DB column, computed fields (without bound values) expand
+ * to their expression, and anything else passes through unchanged as raw SQL.
+ */
+export function convertConfiguredOrder(order, tableConf, db) {
+    return order
+        .split(',')
+        .map((part) => {
+        const trimmed = part.trim();
+        const match = /^(\w+)(?:\s+(ASC|DESC))?$/i.exec(trimmed);
+        if (match) {
+            const [, field, dir] = match;
+            const suffix = dir ? ` ${dir.toUpperCase()}` : '';
+            if (hasOwnField(tableConf.Schema.fields, field)) {
+                return `${db.qi(tableConf.Schema.tableName)}.${db.qi(tableConf.Schema.col(field))}${suffix}`;
+            }
+            const computed = ownField(tableConf.computedFields, field);
+            if (computed) {
+                const ev = evaluateComputedField(field, computed, tableConf.Schema, db, undefined, `Computed field '${field}' with bound values cannot be used in defaultOrder`);
+                return `${ev.value}${suffix}`;
+            }
+        }
+        return trimmed;
+    })
+        .join(', ');
+}

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

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAeb,MAAM,mBAAmB,CAAC;AAqoC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAqIvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAwP3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAsFvB"}