fastify-auto-sqlapi 0.1.14 → 0.2.0

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

@@ -1,446 +1,42 @@
-import { ConditionBuilder, Expression } from 'node-condition-builder';
-import { camelcaseObject } from '../../naming.js';
 import { QueryParams } from '../query-params.js';
 import { buildTenantCondition, buildTenantJoin } from '../../tenant.js';
-import { assertReadable, assertFiltersReadable, assertKnownFilterKeys, readableSelectColumns, explicitSelectColumns, } from '../../read-access.js';
+import { assertFiltersReadable, assertKnownFilterKeys, readableSelectColumns, ownField, } from '../../read-access.js';
+import { MAX_CONDITIONS, MAX_ORDER_BY_PARTS } from '../../condition-methods.js';
 import { primaryAsString } from '../../../types.js';
-// ─── Schema field validation ────────────────────────────────
-function validateSchemaField(field, schema, tableConf) {
-    if (!(field in schema.fields)) {
-        const err = new Error(`Unknown field: ${field}`);
-        err.statusCode = 400;
-        throw err;
-    }
-    assertReadable(tableConf, field);
-    return schema.col(field);
-}
-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 (!(field in schema.fields)) {
-                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;
-        },
-    };
-}
-function resolveFieldRef(field, schema, tableConf, db, alias) {
-    if (field in schema.fields) {
-        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 = tableConf?.computedFields?.[field];
-    if (fn) {
-        const ctx = buildComputedContext(db, schema, alias);
-        return { expr: computedExpression(field, fn(ctx)), computed: true };
-    }
-    err400(`Unknown field: ${field}`);
-}
-// ─── Join lookup ────────────────────────────────────────────
+import { err400, resolveFieldRef, evaluateComputedField, refValues, renderRef, mapRowsToCamelCase, } from './fields.js';
+import { assertJoinFilterKeys, requireJoin } from './joins.js';
+import { collectOrderByLeftAliases, validateOrderBy, convertConfiguredOrder } from './order-by.js';
+import { applyConditions, applyComputedFilters } from './conditions.js';
+import { appendAggConditions } from './aggregations.js';
+import { buildLeftJoinOnClauses, buildLeftJoinFilters, executeJoinMultiple, executeJoinLeft, executeJoinGroup, buildJoinMustExistClauses, } from './join-families.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.
+ * Guard the request shapes that reach SQL as text rather than as bound values.
  *
- * `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.
- */
-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.
- */
-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.
+ * `paginator` is rendered straight into LIMIT/OFFSET: `Paginator` is a compile-time type only,
+ * and `sqlApi.search()` is a documented public API a consumer may hand an unvalidated
+ * querystring, so the integer check has to exist at runtime.
  *
- * Unknown aliases are left to `requireJoin`, which reports them with its own message.
+ * The complexity caps are also declared by the request schemas; these are the backstop that
+ * covers programmatic callers, which no schema validates.
  */
-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);
-    }
-}
-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. */
-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)),
-    };
-}
-/**
- * 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.
- */
-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. */
-function refValues(expr) {
-    return expr instanceof Expression ? [...expr.values] : [];
-}
-/** Render a resolved field reference to SQL, binding any values from `startIndex`. */
-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). */
-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];
+function assertRequestWithinLimits(params) {
+    const { paginator, conditions, orderBy } = params;
+    if (paginator) {
+        for (const key of ['page', 'itemsPerPage']) {
+            const value = paginator[key];
+            if (!Number.isInteger(value) || value < 1) {
+                err400(`Invalid paginator: '${key}' must be an integer >= 1`);
             }
         }
-        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()`.
- */
-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(', ');
-}
-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 },
-};
-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.
- */
-function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup) {
-    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];
-    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}${filterWhere}), 0)`;
-    return new Expression(expr, filterVals);
-}
-/**
- * Pre-scan `orderBy` for the joinLeft aliases referenced in 2-parti 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-parti aggregation entries are ignored (they use joinGroup, not a LEFT JOIN).
- */
-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-parti aggregation
-        const m = trimmed.match(/^(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i);
-        if (m) {
-            const alias = m[1];
-            requireJoin(tableConf, alias, true);
-            aliases.add(alias);
-        }
+    if (conditions && conditions.length > MAX_CONDITIONS) {
+        err400(`Too many conditions: ${conditions.length} (max ${MAX_CONDITIONS})`);
     }
-    return aliases;
-}
-function validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, startIdx) {
-    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-parti: <alias>.<fn>.<field> [ASC|DESC] (aggregation via joinGroup)
-        const dotted3 = trimmed.match(/^(\w+)\.(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i);
-        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);
-            const aggVals = [...expr.values];
-            outParts.push(`${renderRef(expr, currentIdx, db)} ${(dir || 'ASC').toUpperCase()}`);
-            outValues.push(...aggVals);
-            currentIdx += aggVals.length;
-            continue;
-        }
-        // 2-parti: <alias>.<field> [ASC|DESC] (joinLeft inline ordering)
-        const dotted2 = trimmed.match(/^(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i);
-        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-parte: <field> [ASC|DESC] — schema field or computed
-        const plain = trimmed.match(/^(\w+)(?:\s+(ASC|DESC))?$/i);
-        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;
+    if (orderBy && orderBy.split(',').length > MAX_ORDER_BY_PARTS) {
+        err400(`Too many orderBy parts: max ${MAX_ORDER_BY_PARTS}`);
     }
-    return { sql: outParts.join(', '), values: outValues, leftJoinAliases };
-}
-function buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingJoin, joinLeft, startIdx) {
-    const joinClauses = [];
-    const whereExtras = [];
-    const values = [];
-    let currentIdx = startIdx;
-    for (const alias of aliasesNeedingJoin) {
-        const joinDef = requireJoin(tableConf, alias, true);
-        const { joinSchema } = joinDef;
-        const refs = extractJoinRefs(db, tableConf, joinDef);
-        const aliasIdent = db.qi(alias);
-        joinClauses.push(`LEFT JOIN ${refs.joinTable} AS ${aliasIdent} ON ${aliasIdent}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}`);
-        const ref = joinLeft?.[alias];
-        if (ref && (ref.filters || ref.conditions?.length)) {
-            // Build a ConditionBuilder where each column is prefixed with the alias
-            // (so SQL references the LEFT JOIN'd table, not a bare table name).
-            // Note: extraFilters declared on joinTableConf are not supported here for
-            // joinLeft (they would require alias-aware handlers); only schema fields
-            // 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 cb = new ConditionBuilder('AND', db.cbDialect);
-            const joinTableConf = dbTables[joinSchema.tableName];
-            const computed = joinTableConf?.computedFields;
-            assertFiltersReadable(ref.filters, joinTableConf);
-            if (ref.filters) {
-                for (const [field, value] of Object.entries(ref.filters)) {
-                    if (value === null || value === undefined)
-                        continue;
-                    if (field in joinSchema.fields) {
-                        cb.isEqual(`${aliasIdent}.${db.qi(joinSchema.col(field))}`, value);
-                    }
-                    else if (computed?.[field]) {
-                        // Computed field on the parent table: expr with alias-qualified columns. Bound
-                        // values are placed by this ConditionBuilder, whose SQL lands in the WHERE.
-                        const expr = evaluateComputedField(field, computed[field], joinSchema, db, alias, '', true);
-                        cb.isEqual(expr, value);
-                    }
-                }
-            }
-            if (ref.conditions?.length) {
-                for (const c of ref.conditions) {
-                    if (!ALLOWED_SET.has(c.method)) {
-                        err400(`Invalid condition method: ${c.method}`);
-                    }
-                    if (c.field in joinSchema.fields) {
-                        assertReadable(dbTables[joinSchema.tableName], c.field);
-                        const col = `${aliasIdent}.${db.qi(joinSchema.col(c.field))}`;
-                        dispatchConditionMethod(cb, c.method, col, c.params ?? []);
-                    }
-                    else if (computed?.[c.field]) {
-                        const expr = evaluateComputedField(c.field, computed[c.field], joinSchema, db, alias, '', true);
-                        dispatchConditionMethod(cb, c.method, expr, c.params ?? []);
-                    }
-                    else {
-                        err400(`Unknown field: ${c.field}`);
-                    }
-                }
-            }
-            const sql = cb.build(currentIdx, db.ph);
-            const vals = cb.getValues();
-            if (sql) {
-                whereExtras.push(sql);
-                values.push(...vals);
-                currentIdx += vals.length;
-            }
-        }
-    }
-    return { joinClauses, whereExtras, values };
 }
 // ─── Main query execution ───────────────────────────────────
-/**
- * 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.
- */
-function convertConfiguredOrder(order, tableConf, db) {
-    return order
-        .split(',')
-        .map((part) => {
-        const trimmed = part.trim();
-        const match = trimmed.match(/^(\w+)(?:\s+(ASC|DESC))?$/i);
-        if (match) {
-            const [, field, dir] = match;
-            const suffix = dir ? ` ${dir.toUpperCase()}` : '';
-            if (field in tableConf.Schema.fields) {
-                return `${db.qi(tableConf.Schema.tableName)}.${db.qi(tableConf.Schema.col(field))}${suffix}`;
-            }
-            const computed = 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(', ');
-}
 async function executeMainQuery(db, tableConf, where, values, orderBy, paginator, extraJoins = [], selectComputed, maxRows) {
     const tableName = tableConf.Schema.tableName;
     // Request orderBy arrives already validated and mapped by validateOrderBy;
@@ -459,7 +55,7 @@ async function executeMainQuery(db, tableConf, where, values, orderBy, paginator
     if (selectComputed?.length) {
         const projections = [readableColumns ?? '*'];
         for (const name of selectComputed) {
-            const fn = tableConf.computedFields?.[name];
+            const fn = ownField(tableConf.computedFields, name);
             if (!fn)
                 err400(`Unknown computed field in selectComputed: '${name}'`);
             const out = evaluateComputedField(name, fn, tableConf.Schema, db, undefined, `Computed field '${name}' with bound values cannot be used in selectComputed`);
@@ -510,328 +106,17 @@ async function buildPagination(db, tableConf, where, values, paginator, extraJoi
         paginator,
     };
 }
-// ─── joinMultiple (virtual fetch, child rows in side query) ─
-async function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMultiple, tenant) {
-    const result = {};
-    for (const [alias, ref] of Object.entries(joinMultiple)) {
-        const joinDef = requireJoin(tableConf, alias, false);
-        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);
-        const ids = collectIds(mainResults, mainField);
-        if (ids.length === 0) {
-            result[alias] = [];
-            continue;
-        }
-        const cb = buildJoinRefCondition(joinTableConf, joinSchema, ref || {}, db);
-        const fkCol = joinSchema.col(joinField);
-        cb.isIn(`${db.qi(joinSchema.tableName)}.${db.qi(fkCol)}`, ids);
-        const tenantJoins = [];
-        appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
-        const where = cb.build(1, db.ph);
-        const values = cb.getValues();
-        const rows = await db.select({
-            tableName: joinSchema.tableName,
-            columns,
-            where,
-            values,
-            joins: tenantJoins.length > 0 ? tenantJoins : undefined,
-        });
-        result[alias] = mapRowsToCamelCase(rows, joinSchema);
-    }
-    return result;
-}
-// ─── joinLeft (parent fetch via PK IN side query) ───────────
-async function executeJoinLeft(db, dbTables, tableConf, mainResults, joinLeft, tenant) {
-    const result = {};
-    for (const [alias, ref] of Object.entries(joinLeft)) {
-        const joinDef = requireJoin(tableConf, alias, true);
-        const { joinSchema, joinField, mainField, selection: defaultSelection } = joinDef;
-        const joinTableConf = dbTables[joinSchema.tableName];
-        // Resolved before the bail-out, for the same reason as joinMultiple: an invalid
-        // selection is a 400 whether or not the main query matched anything.
-        const selection = ref?.selection ?? defaultSelection;
-        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf, joinDef.fields !== undefined);
-        // For joinLeft (N:1), mainField on main is the FK pointing to joinField (PK) on parent.
-        // We collect the FK values from the main results and look up parents by their PK.
-        const ids = collectIds(mainResults, mainField);
-        if (ids.length === 0) {
-            result[alias] = [];
-            continue;
-        }
-        const fkCol = joinSchema.col(joinField);
-        const cb = new ConditionBuilder('AND', db.cbDialect);
-        cb.isIn(`${db.qi(joinSchema.tableName)}.${db.qi(fkCol)}`, ids);
-        const tenantJoins = [];
-        appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
-        const where = cb.build(1, db.ph);
-        const values = cb.getValues();
-        const rows = await db.select({
-            tableName: joinSchema.tableName,
-            columns,
-            where,
-            values,
-            joins: tenantJoins.length > 0 ? tenantJoins : undefined,
-        });
-        result[alias] = mapRowsToCamelCase(rows, joinSchema);
-    }
-    return result;
-}
-/**
- * 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 (by in joinSchema.fields) {
-        // 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 = 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) ───────────────────────────────
-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 = [];
-        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);
-                selectParts.push(`${aggExpr(fn, `${db.qi(joinSchema.tableName)}.${db.qi(col)}`)} 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);
-        // Bail out only here: `by` and every aggregation field have now been validated against
-        // the join schema, so an unknown or unreachable field is a 400 regardless of the data.
-        if (selectParts.length === 0 || ids.length === 0) {
-            result[alias] = {};
-            continue;
-        }
-        const groupRef = { filters: groupFilters, conditions: groupConditions };
-        const cb = buildJoinRefCondition(joinTableConf, joinSchema, groupRef, db);
-        const fkCol = joinSchema.col(joinField);
-        cb.isIn(`${db.qi(joinSchema.tableName)}.${db.qi(fkCol)}`, ids);
-        const tenantJoins = [];
-        appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
-        const where = cb.build(1, db.ph);
-        const values = cb.getValues();
-        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);
-        const rows = queryResult.rows;
-        const formatted = {};
-        if (rows.length > 0) {
-            const row = rows.length === 1 && !aggregations.by ? rows[0] : rows;
-            if (Array.isArray(row)) {
-                formatted.rows = row;
-            }
-            else {
-                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;
-                }
-            }
-        }
-        result[alias] = formatted;
-    }
-    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))];
-}
-// ─── Conditions (advanced filters) ──────────────────────────
-import { ALLOWED_SET, SINGLE_VALUE_SET, BETWEEN_SET, IN_SET, NULL_SET, } from '../../condition-methods.js';
-function dispatchConditionMethod(cb, method, colOrExpr, params) {
-    if (SINGLE_VALUE_SET.has(method)) {
-        cb[method](colOrExpr, params[0]);
-    }
-    else if (BETWEEN_SET.has(method)) {
-        cb[method](colOrExpr, params[0], params[1]);
-    }
-    else if (IN_SET.has(method)) {
-        cb[method](colOrExpr, params[0]);
-    }
-    else if (NULL_SET.has(method)) {
-        cb[method](colOrExpr, true);
-    }
-}
-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);
-    // Equality filters targeting the join table's computed fields
-    const computed = joinTableConf?.computedFields;
-    if (computed && ref.filters) {
-        for (const [name, value] of Object.entries(ref.filters)) {
-            if (value === null || value === undefined)
-                continue;
-            if (!computed[name])
-                continue;
-            const expr = evaluateComputedField(name, computed[name], joinSchema, db, colQualifier, '', true);
-            cb.isEqual(expr, value);
-        }
-    }
-    if (ref.conditions?.length) {
-        for (const c of ref.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 operand = computed?.[c.field]
-                ? evaluateComputedField(c.field, computed[c.field], joinSchema, db, colQualifier, '', true)
-                : `${db.qi(colQualifier)}.${db.qi(validateSchemaField(c.field, joinSchema, joinTableConf))}`;
-            dispatchConditionMethod(cb, c.method, operand, c.params ?? []);
-        }
-    }
-    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.
- */
-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);
-    }
-}
+// ─── searchEngine entrypoint ────────────────────────────────
 /**
- * Equality filters targeting computed fields: `filters.<computedName>` becomes
- * `<expr> = <value>` on the same ConditionBuilder used for schema fields, which
- * `tableConf.filters()` has already populated.
+ * Reject unknown aliases, non-unique aliases used as `joinLeft`, and unsupported join
+ * filter keys — all before any query runs, so a 400 never depends on whether the main
+ * query happened to return rows.
+ *
+ * `joinLeft` is the odd one out: its condition is built inline and never runs the target's
+ * `extendedCondition`, so `extraFilters` are not accepted there.
  */
-function applyComputedFilters(condition, filters, tableConf, db) {
-    const computed = tableConf.computedFields;
-    if (!computed)
-        return;
-    for (const [name, value] of Object.entries(filters)) {
-        if (value === null || value === undefined)
-            continue;
-        if (!computed[name])
-            continue;
-        const expr = evaluateComputedField(name, computed[name], tableConf.Schema, db, undefined, '', true);
-        condition.isEqual(expr, value);
-    }
-}
-function appendAggConditions(params, conditions, db, dbTables, tableConf, joinGroup) {
-    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);
-        const tmpCb = new ConditionBuilder('AND', db.cbDialect);
-        dispatchConditionMethod(tmpCb, c.method, expr, c.params);
-        where += ` AND ${params.emitCondition(tmpCb, db)}`;
-    }
-    return where;
-}
-// ─── joinMustExist (EXISTS subquery filter on main) ─────────
-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;
-}
-// ─── searchEngine entrypoint ────────────────────────────────
-export async function searchEngine(dbTables, params) {
-    const { db, tableConf, filters, conditions, joinMustExist, joinMultiple, joinGroup, joinLeft, orderBy, paginator, computeMin, computeMax, computeSum, computeAvg, tenant, } = params;
-    // Validate aliases used as keys against allowedReadJoins + unique flag (early 400s)
+function assertJoinRequestsAllowed(dbTables, params) {
+    const { tableConf, joinMustExist, joinMultiple, joinGroup, joinLeft } = params;
     if (joinMustExist)
         for (const a of Object.keys(joinMustExist))
             requireJoin(tableConf, a, false);
@@ -844,27 +129,29 @@ export async function searchEngine(dbTables, params) {
     if (joinLeft)
         for (const a of Object.keys(joinLeft))
             requireJoin(tableConf, a, true);
-    // Join filter keys, validated before any query so the outcome never depends on whether
-    // the main query returned rows. joinLeft is the odd one: its condition is built inline
-    // and never runs the target's extendedCondition, so extraFilters are not accepted there.
     assertJoinFilterKeys(dbTables, tableConf, joinMustExist, true);
     assertJoinFilterKeys(dbTables, tableConf, joinMultiple, true);
     assertJoinFilterKeys(dbTables, tableConf, joinGroup, true);
     assertJoinFilterKeys(dbTables, tableConf, joinLeft, false);
-    // Build main condition
+}
+/**
+ * The main table's WHERE builder, plus any JOIN the tenant scope needs.
+ *
+ * Filters and conditions on computed fields go on the same ConditionBuilder: a computed
+ * resolves to an Expression carrying its own values, and the builder is what assigns
+ * every placeholder index.
+ */
+function buildMainCondition(params) {
+    const { db, tableConf, filters, conditions, tenant } = params;
     assertFiltersReadable(filters, tableConf);
     assertKnownFilterKeys(filters, tableConf.Schema, tableConf);
     const condition = tableConf.filters(filters || {}, db.cbDialect);
-    // Filters and conditions targeting computed fields go on the same ConditionBuilder:
-    // a computed resolves to an Expression carrying its own values, and the builder is
-    // what assigns every placeholder index.
     if (filters && tableConf.computedFields) {
         applyComputedFilters(condition, filters, tableConf, db);
     }
     if (conditions?.length) {
         applyConditions(condition, conditions, tableConf.Schema, tableConf, db);
     }
-    // Tenant
     const tenantJoins = [];
     if (tenant) {
         condition.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableConf.Schema.tableName));
@@ -872,11 +159,62 @@ export async function searchEngine(dbTables, params) {
             tenantJoins.push(buildTenantJoin(db, tenant.scope, tableConf.Schema.tableName));
         }
     }
+    return { condition, tenantJoins };
+}
+/**
+ * joinLeft aliases that need a real LEFT JOIN on the main query: those referenced by a
+ * 2-part `orderBy`, plus those the request filters or puts conditions on.
+ */
+function collectLeftJoinAliases(params) {
+    const { orderBy, joinLeft, tableConf } = params;
+    const aliases = new Set();
+    if (orderBy) {
+        for (const a of collectOrderByLeftAliases(orderBy, tableConf))
+            aliases.add(a);
+    }
+    if (joinLeft) {
+        for (const [alias, ref] of Object.entries(joinLeft)) {
+            if (ref?.filters || ref?.conditions?.length)
+                aliases.add(alias);
+        }
+    }
+    return aliases;
+}
+/**
+ * Run the side queries for the join families that return rows of their own, and hang each
+ * one off `result`. These run after the main query because they are correlated to the rows
+ * it returned.
+ */
+async function attachJoinResults(result, dbTables, params, main) {
+    const { db, tableConf, joinMultiple, joinLeft, joinGroup, tenant } = params;
+    if (joinMultiple && Object.keys(joinMultiple).length > 0) {
+        result.joinMultiple = await executeJoinMultiple(db, dbTables, tableConf, main, joinMultiple, tenant);
+    }
+    if (joinLeft && Object.keys(joinLeft).length > 0) {
+        result.joinLeft = await executeJoinLeft(db, dbTables, tableConf, main, joinLeft, tenant);
+    }
+    if (joinGroup && Object.keys(joinGroup).length > 0) {
+        result.joinGroup = await executeJoinGroup(db, dbTables, tableConf, main, joinGroup, tenant);
+    }
+}
+export async function searchEngine(dbTables, params) {
+    const { db, tableConf, conditions, joinMustExist, joinGroup, joinLeft, orderBy, paginator, computeMin, computeMax, computeSum, computeAvg, tenant, } = params;
+    assertRequestWithinLimits(params);
+    assertJoinRequestsAllowed(dbTables, params);
+    const { condition, tenantJoins } = buildMainCondition(params);
+    const aliasesNeedingLeftJoin = collectLeftJoinAliases(params);
     // From here the statement is assembled fragment by fragment. `bound` owns the values and
     // hands each fragment the placeholder index it must start from, so no offset is computed
     // at any call site. Fragments must be emitted in the order their placeholders appear in
     // the final SQL — MySQL binds `?` positionally.
     const bound = new QueryParams();
+    // LEFT JOIN clauses come first: they sit before the WHERE in the statement, and their ON
+    // clause carries the joined table's tenant scope.
+    const extraJoinClauses = [...tenantJoins];
+    if (aliasesNeedingLeftJoin.size > 0) {
+        const on = bound.emit((startIndex) => buildLeftJoinOnClauses(db, dbTables, tableConf, aliasesNeedingLeftJoin, startIndex, tenant));
+        extraJoinClauses.push(...on.joinClauses);
+    }
     let where = bound.emitCondition(condition, db);
     // joinMustExist (EXISTS)
     if (joinMustExist && Object.keys(joinMustExist).length > 0) {
@@ -884,27 +222,11 @@ export async function searchEngine(dbTables, params) {
     }
     // Aggregation conditions (HAVING-style)
     if (conditions?.length && conditions.some((c) => c.field.includes('.'))) {
-        where += appendAggConditions(bound, conditions, db, dbTables, tableConf, joinGroup);
-    }
-    // Determine which joinLeft aliases need a LEFT JOIN on the main query:
-    // - any alias used in 2-parti orderBy
-    // - any alias in joinLeft body that has filters or conditions on the parent
-    const aliasesNeedingLeftJoin = new Set();
-    if (orderBy) {
-        for (const a of collectOrderByLeftAliases(orderBy, tableConf))
-            aliasesNeedingLeftJoin.add(a);
+        where += appendAggConditions(bound, conditions, db, dbTables, tableConf, joinGroup, tenant);
     }
-    if (joinLeft) {
-        for (const [alias, ref] of Object.entries(joinLeft)) {
-            if (ref?.filters || ref?.conditions?.length)
-                aliasesNeedingLeftJoin.add(alias);
-        }
-    }
-    // LEFT JOIN clauses + extra WHERE for filtered parents.
-    const extraJoinClauses = [...tenantJoins];
+    // Extra WHERE for the parents the request filters on.
     if (aliasesNeedingLeftJoin.size > 0) {
-        const lj = bound.emit((startIndex) => buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingLeftJoin, joinLeft, startIndex));
-        extraJoinClauses.push(...lj.joinClauses);
+        const lj = bound.emit((startIndex) => buildLeftJoinFilters(db, dbTables, tableConf, aliasesNeedingLeftJoin, joinLeft, startIndex));
         for (const w of lj.whereExtras)
             where += ` AND ${w}`;
     }
@@ -915,7 +237,7 @@ export async function searchEngine(dbTables, params) {
     // WHERE and LEFT JOIN values.
     let safeOrderBy;
     if (orderBy) {
-        safeOrderBy = bound.emit((startIndex) => validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, startIndex)).sql;
+        safeOrderBy = bound.emit((startIndex) => validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, startIndex, tenant)).sql;
     }
     const mainValues = bound.snapshot();
     const main = await executeMainQuery(db, tableConf, where, mainValues, safeOrderBy, paginator, extraJoinClauses, params.selectComputed, params.maxRows);
@@ -924,15 +246,7 @@ export async function searchEngine(dbTables, params) {
         pagination = await buildPagination(db, tableConf, where, whereAndJoinValues, paginator, extraJoinClauses, computeMin, computeMax, computeSum, computeAvg);
     }
     const result = { main };
-    if (joinMultiple && Object.keys(joinMultiple).length > 0) {
-        result.joinMultiple = await executeJoinMultiple(db, dbTables, tableConf, main, joinMultiple, tenant);
-    }
-    if (joinLeft && Object.keys(joinLeft).length > 0) {
-        result.joinLeft = await executeJoinLeft(db, dbTables, tableConf, main, joinLeft, tenant);
-    }
-    if (joinGroup && Object.keys(joinGroup).length > 0) {
-        result.joinGroup = await executeJoinGroup(db, dbTables, tableConf, main, joinGroup, tenant);
-    }
+    await attachJoinResults(result, dbTables, params, main);
     if (pagination) {
         result.pagination = pagination;
     }