fastify-auto-sqlapi 0.0.5 → 0.1.2

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

@@ -2,6 +2,7 @@ import { ConditionBuilder } from 'node-condition-builder';
 import { camelcaseObject } from '../../naming.js';
 import { buildTenantCondition, buildTenantJoin } from '../../tenant.js';
 import { primaryAsString } from '../../../types.js';
+// ─── Schema field validation ────────────────────────────────
 function validateSchemaField(field, schema) {
     if (!(field in schema.fields)) {
         const err = new Error(`Unknown field: ${field}`);
@@ -10,59 +11,140 @@ function validateSchemaField(field, schema) {
     }
     return schema.col(field);
 }
-const AGG_FN_SQL = {
-    sum: 'SUM',
-    min: 'MIN',
-    max: 'MAX',
-    avg: 'AVG',
-    count: 'COUNT',
-    distinctCount: 'COUNT DISTINCT', // marker, handled specially
-};
-function buildAggOrderExpr(db, dbTables, tableConf, joinTableName, fn, field, joinGroups, startIdx) {
-    const err400 = (msg) => {
-        const e = new Error(msg);
-        e.statusCode = 400;
-        throw e;
+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));
+            const qualifier = opts?.qualifier ?? alias;
+            return qualifier ? `${db.qi(qualifier)}.${col}` : col;
+        },
     };
-    // Whitelist fn
-    if (!(fn in AGG_FN_SQL)) {
-        err400(`Invalid aggregation function: ${fn}`);
+}
+function resolveFieldRef(field, schema, tableConf, db, alias) {
+    if (field in schema.fields) {
+        const col = db.qi(schema.col(field));
+        const expr = alias ? `${db.qi(alias)}.${col}` : col;
+        return { expr, values: [], computed: false };
     }
-    // Require joinGroups declaration for the referenced table + fn + field
-    const groupReq = joinGroups?.[joinTableName];
-    if (!groupReq) {
-        err400(`orderBy references undeclared joinGroup: ${joinTableName}`);
+    const fn = tableConf?.computedFields?.[field];
+    if (fn) {
+        const ctx = buildComputedContext(db, schema, alias);
+        const out = fn(ctx);
+        return { expr: out.expr, values: out.values ?? [], computed: true };
     }
+    err400(`Unknown field: ${field}`);
+}
+// ─── Join lookup ────────────────────────────────────────────
+function findJoinByAlias(tableConf, alias) {
+    return tableConf.allowedReadJoins?.find((j) => j.alias === alias);
+}
+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. When `allowBoundValues=false`, throws 400 if the computed binds
+ * any parameters — used in positions where parameter binding cannot be coordinated (orderBy,
+ * compute*, joinLeft.filters, etc).
+ */
+function evaluateComputedField(fn, schema, db, alias, message, allowBoundValues = false) {
+    const ev = fn(buildComputedContext(db, schema, alias));
+    if (!allowBoundValues && (ev.values?.length ?? 0) > 0) {
+        err400(message);
+    }
+    return ev;
+}
+/** 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];
+            }
+        }
+        return camel;
+    });
+}
+/** Build the SELECT columns list for a join fetch: '*' or comma-separated quoted columns. */
+function buildSelectionColumns(selection, joinSchema, db) {
+    if (selection === '*')
+        return '*';
+    return selection.split(',').map((c) => db.qi(joinSchema.col(c.trim()))).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})`;
+}
+function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, startIdx) {
+    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 references undeclared aggregation: ${joinTableName}.${fn}.${field}`);
-    }
-    // Resolve join definition
-    const joinDef = tableConf.allowedReadJoins?.find(([js]) => js.tableName === joinTableName);
-    if (!joinDef) {
-        err400(`Unknown join table in orderBy: ${joinTableName}`);
+        err400(`orderBy/conditions reference undeclared aggregation: ${alias}.${fn}.${field}`);
     }
-    const [joinSchema, joinField, mainField] = joinDef;
-    // If joinGroup has `by`, only accept it when `by` is the correlation FK (joinField).
-    // In that case each main row corresponds to exactly one group, so the scalar
-    // subquery is semantically equivalent to no-by. Any other `by` produces multiple
-    // groups per main row → not a single scalar, reject.
+    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: ${joinTableName} (grouped by '${groupReq.aggregations.by}', correlation FK is '${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}')`);
     }
-    // Validate field exists on join schema
     const fieldCol = validateSchemaField(field, joinSchema);
-    // Build correlation: joinTable.fk = mainTable.main_pk
-    const mainColName = Array.isArray(mainField) ? mainField[0] : mainField;
-    const mainCol = db.qi(tableConf.Schema.col(mainColName));
-    const mainTable = db.qi(tableConf.Schema.tableName);
-    const joinTable = db.qi(joinSchema.tableName);
-    const fkCol = db.qi(joinSchema.col(joinField));
-    // Rebuild joinGroup filters + conditions with correct placeholder offset
+    const refs = extractJoinRefs(db, tableConf, joinDef);
     let filterWhere = '';
     let filterVals = [];
-    const joinTableConf = dbTables[joinTableName];
-    if ((groupReq.filters || groupReq.conditions?.length) && joinSchema) {
+    const joinTableConf = dbTables[joinSchema.tableName];
+    if (groupReq.filters || groupReq.conditions?.length) {
         const cb = buildJoinRefCondition(joinTableConf, joinSchema, { filters: groupReq.filters, conditions: groupReq.conditions }, db);
         const built = cb.build(startIdx, db.ph);
         if (built) {
@@ -70,61 +152,143 @@ function buildAggOrderExpr(db, dbTables, tableConf, joinTableName, fn, field, jo
             filterVals = cb.getValues();
         }
     }
-    // Generate SQL expression
-    const qField = db.qi(fieldCol);
-    const fnSql = AGG_FN_SQL[fn];
-    const aggExpr = fnSql === 'COUNT DISTINCT'
-        ? `COUNT(DISTINCT ${joinTable}.${qField})`
-        : `${fnSql}(${joinTable}.${qField})`;
-    // COALESCE with 0 so main rows without matching joined records get a sortable
-    // numeric value instead of NULL. Works on all dialects (PG/MySQL/MariaDB) and
-    // keeps "no data" at the bottom on DESC (top-N queries), and at the top on ASC.
-    const expr = `COALESCE((SELECT ${aggExpr} FROM ${joinTable} WHERE ${joinTable}.${fkCol} = ${mainTable}.${mainCol}${filterWhere}), 0)`;
+    const qualifiedCol = `${refs.joinTable}.${db.qi(fieldCol)}`;
+    const expr = `COALESCE((SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} WHERE ${refs.joinTable}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${filterWhere}), 0)`;
     return { expr, values: filterVals };
 }
-function validateOrderBy(orderBy, tableConf, db, dbTables, joinGroups, startIdx) {
+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();
-        // Dotted notation: <joinTable>.<fn>.<field> [ASC|DESC]
-        const dottedMatch = trimmed.match(/^(\w+)\.(\w+)\.(\w+)(?:\s+(ASC|DESC))?$/i);
-        if (dottedMatch) {
+        // 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) {
-                const err = new Error('Cannot combine distinctResults with aggregation orderBy');
-                err.statusCode = 400;
-                throw err;
+                err400('Cannot combine distinctResults with aggregation orderBy');
             }
-            const [, joinTableName, fn, field, dir] = dottedMatch;
-            const { expr, values } = buildAggOrderExpr(db, dbTables, tableConf, joinTableName, fn, field, joinGroups, currentIdx);
+            const [, alias, fn, field, dir] = dotted3;
+            const { expr, values } = buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, currentIdx);
             outParts.push(`${expr} ${(dir || 'ASC').toUpperCase()}`);
             outValues.push(...values);
             currentIdx += values.length;
             continue;
         }
-        // Plain field: <field> [ASC|DESC]
-        const plainMatch = trimmed.match(/^(\w+)(?:\s+(ASC|DESC))?$/i);
-        if (!plainMatch) {
-            const err = new Error(`Invalid orderBy: ${trimmed}`);
-            err.statusCode = 400;
-            throw err;
+        // 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);
+            // 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);
+        outParts.push(`${ref.expr} ${(dir || 'ASC').toUpperCase()}`);
+        outValues.push(...ref.values);
+        currentIdx += ref.values.length;
+    }
+    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.
+            const cb = new ConditionBuilder('AND');
+            const joinTableConf = dbTables[joinSchema.tableName];
+            const computed = joinTableConf?.computedFields;
+            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: build expr with alias-qualified columns.
+                        const ev = evaluateComputedField(computed[field], joinSchema, db, alias, `Computed field '${field}' with bound values is not supported in joinLeft.filters`);
+                        cb.isEqual(ev.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) {
+                        const col = `${aliasIdent}.${db.qi(joinSchema.col(c.field))}`;
+                        dispatchConditionMethod(cb, c.method, col, c.params ?? []);
+                    }
+                    else if (computed?.[c.field]) {
+                        const ev = evaluateComputedField(computed[c.field], joinSchema, db, alias, `Computed field '${c.field}' with bound values is not supported in joinLeft.conditions`);
+                        dispatchConditionMethod(cb, c.method, ev.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;
+            }
         }
-        const [, field, dir] = plainMatch;
-        const col = validateSchemaField(field, tableConf.Schema);
-        outParts.push(`${db.qi(col)} ${(dir || 'ASC').toUpperCase()}`);
     }
-    return { sql: outParts.join(', '), values: outValues };
+    return { joinClauses, whereExtras, values };
 }
-async function executeMainQuery(db, tableConf, where, values, orderBy, paginator, extraJoins = []) {
+// ─── Main query execution ───────────────────────────────────
+async function executeMainQuery(db, tableConf, where, values, orderBy, paginator, extraJoins = [], selectComputed) {
     const tableName = tableConf.Schema.tableName;
     const order = orderBy || tableConf.defaultOrder || primaryAsString(tableConf.primary);
     const limit = paginator
         ? `${paginator.itemsPerPage} OFFSET ${(paginator.page - 1) * paginator.itemsPerPage}`
         : null;
+    // Optional computed projections — bound values, if any, are NOT yet supported
+    // here (would require placeholder-aware composition with WHERE values).
+    let columns;
+    if (selectComputed?.length) {
+        const projections = ['*'];
+        for (const name of selectComputed) {
+            const fn = tableConf.computedFields?.[name];
+            if (!fn)
+                err400(`Unknown computed field in selectComputed: '${name}'`);
+            const out = evaluateComputedField(fn, tableConf.Schema, db, undefined, `Computed field '${name}' with bound values cannot be used in selectComputed`);
+            projections.push(`${out.expr} AS ${db.qi(name)}`);
+        }
+        columns = projections.join(', ');
+    }
     const rows = await db.select({
         tableName,
+        columns,
         where,
         values,
         orderBy: order,
@@ -132,7 +296,7 @@ async function executeMainQuery(db, tableConf, where, values, orderBy, paginator
         distinct: tableConf.distinctResults,
         joins: extraJoins.length > 0 ? extraJoins : undefined,
     });
-    return rows.map((r) => camelcaseObject(r, tableConf.Schema));
+    return mapRowsToCamelCase(rows, tableConf.Schema, selectComputed);
 }
 async function buildPagination(db, tableConf, where, values, paginator, extraJoins = [], computeMin, computeMax, computeSum, computeAvg) {
     const tableName = tableConf.Schema.tableName;
@@ -148,8 +312,11 @@ async function buildPagination(db, tableConf, where, values, paginator, extraJoi
     ];
     for (const { key, field, fn } of computations) {
         if (field) {
-            const col = validateSchemaField(field, tableConf.Schema);
-            const result = await db.query(`SELECT ${fn}(${db.qi(col)}) as value FROM ${db.qi(tableName)}${joinClause} WHERE ${where}`, values);
+            const ref = resolveFieldRef(field, tableConf.Schema, tableConf, db);
+            if (ref.values.length > 0) {
+                err400(`Computed field '${field}' with bound values cannot be used in compute${key.charAt(0).toUpperCase() + key.slice(1)}`);
+            }
+            const result = await db.query(`SELECT ${fn}(${ref.expr}) as value FROM ${db.qi(tableName)}${joinClause} WHERE ${where}`, values);
             computed[key] = { [field]: result.rows[0].value };
         }
     }
@@ -160,119 +327,144 @@ async function buildPagination(db, tableConf, where, values, paginator, extraJoi
         paginator,
     };
 }
-function findJoinDefinition(tableConf, joinTableName) {
-    return tableConf.allowedReadJoins?.find(([joinSchema]) => joinSchema.tableName === joinTableName);
-}
-async function executeVirtualJoins(db, dbTables, tableConf, mainResults, joins) {
+// ─── joinMultiple (virtual fetch, child rows in side query) ─
+async function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMultiple) {
     const result = {};
-    for (const [joinTableName, joinRef] of Object.entries(joins)) {
-        const joinDef = findJoinDefinition(tableConf, joinTableName);
-        if (!joinDef)
+    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];
+        const ids = collectIds(mainResults, mainField);
+        if (ids.length === 0) {
+            result[alias] = [];
             continue;
-        const [joinSchema, joinField, mainField, selection] = joinDef;
-        const joinTableConf = dbTables[joinTableName];
-        // Collect IDs from main results
+        }
+        const cb = buildJoinRefCondition(joinTableConf, joinSchema, ref || {}, db);
+        const fkCol = joinSchema.col(joinField);
+        cb.isIn(db.qi(fkCol), ids);
+        let where = cb.build(1, db.ph);
+        let values = cb.getValues();
+        // Side-channel: computed-field clauses on the join table
+        const computedClauses = collectJoinRefComputedClauses(joinTableConf, ref || {}, db);
+        if (computedClauses.length > 0) {
+            ({ where, values } = appendComputedConditions(where, values, computedClauses, db));
+        }
+        const selection = ref?.selection ?? defaultSelection;
+        const columns = buildSelectionColumns(selection, joinSchema, db);
+        const rows = await db.select({
+            tableName: joinSchema.tableName,
+            columns,
+            where,
+            values,
+        });
+        result[alias] = mapRowsToCamelCase(rows, joinSchema);
+    }
+    return result;
+}
+// ─── joinLeft (parent fetch via PK IN side query) ───────────
+async function executeJoinLeft(db, tableConf, mainResults, joinLeft) {
+    const result = {};
+    for (const [alias, ref] of Object.entries(joinLeft)) {
+        const joinDef = requireJoin(tableConf, alias, true);
+        const { joinSchema, joinField, mainField, selection: defaultSelection } = joinDef;
+        // 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[joinTableName] = [];
+            result[alias] = [];
             continue;
         }
-        // Build join filters (equality) + rich conditions
-        const cb = buildJoinRefCondition(joinTableConf, joinSchema, joinRef || {}, db);
         const fkCol = joinSchema.col(joinField);
+        const cb = new ConditionBuilder('AND');
         cb.isIn(db.qi(fkCol), ids);
         const where = cb.build(1, db.ph);
         const values = cb.getValues();
-        // selection is a comma-separated list of field names (camelCase API names).
-        // Resolve each to its DB column via schema.col() and quote it.
-        const columns = selection === '*'
-            ? '*'
-            : selection.split(',').map((c) => {
-                const field = c.trim();
-                return db.qi(joinSchema.col(field));
-            }).join(', ');
+        const selection = ref?.selection ?? defaultSelection;
+        const columns = buildSelectionColumns(selection, joinSchema, db);
         const rows = await db.select({
             tableName: joinSchema.tableName,
             columns,
             where,
             values,
         });
-        result[joinTableName] = rows.map((r) => camelcaseObject(r, joinSchema));
+        result[alias] = mapRowsToCamelCase(rows, joinSchema);
     }
     return result;
 }
-async function executeJoinGroups(db, dbTables, tableConf, mainResults, joinGroups) {
+/**
+ * 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) {
+        return db.qi(joinSchema.col(by));
+    }
+    const fn = joinTableConf?.computedFields?.[by];
+    if (fn) {
+        return evaluateComputedField(fn, joinSchema, db, undefined, `Computed field '${by}' with bound values cannot be used in aggregations.by`).expr;
+    }
+    err400(`Unknown field: ${by}`);
+}
+// ─── joinGroup (aggregations) ───────────────────────────────
+async function executeJoinGroup(db, dbTables, tableConf, mainResults, joinGroup) {
     const result = {};
-    for (const [joinTableName, groupReq] of Object.entries(joinGroups)) {
-        const joinDef = findJoinDefinition(tableConf, joinTableName);
-        if (!joinDef)
-            continue;
-        const [joinSchema, joinField, mainField] = joinDef;
+    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);
         if (ids.length === 0) {
-            result[joinTableName] = {};
+            result[alias] = {};
             continue;
         }
         const { aggregations, filters: groupFilters, conditions: groupConditions } = groupReq;
         const selectParts = [];
         const groupByParts = [];
         if (aggregations.by) {
-            const byCol = validateSchemaField(aggregations.by, joinSchema);
-            selectParts.push(`${db.qi(byCol)} as "by"`);
-            groupByParts.push(db.qi(byCol));
-        }
-        if (aggregations.distinctCount) {
-            for (const f of aggregations.distinctCount) {
-                const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`COUNT(DISTINCT ${db.qi(col)}) as "distinctCount_${f}"`);
-            }
-        }
-        if (aggregations.min) {
-            for (const f of aggregations.min) {
-                const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`MIN(${db.qi(col)}) as "min_${f}"`);
-            }
-        }
-        if (aggregations.max) {
-            for (const f of aggregations.max) {
-                const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`MAX(${db.qi(col)}) as "max_${f}"`);
-            }
+            const byExpr = buildByExpression(aggregations.by, joinSchema, joinTableConf, db);
+            selectParts.push(`${byExpr} as "by"`);
+            groupByParts.push(byExpr);
         }
-        if (aggregations.sum) {
-            for (const f of aggregations.sum) {
+        const addAgg = (kind, fields) => {
+            if (!fields)
+                return;
+            const fn = AGG_FN[kind];
+            for (const f of fields) {
                 const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`SUM(${db.qi(col)}) as "sum_${f}"`);
+                selectParts.push(`${aggExpr(fn, db.qi(col))} as "${kind}_${f}"`);
             }
-        }
-        if (aggregations.avg) {
-            for (const f of aggregations.avg) {
-                const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`AVG(${db.qi(col)}) as "avg_${f}"`);
-            }
-        }
-        if (aggregations.count) {
-            for (const f of aggregations.count) {
-                const col = validateSchemaField(f, joinSchema);
-                selectParts.push(`COUNT(${db.qi(col)}) as "count_${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);
         if (selectParts.length === 0) {
-            result[joinTableName] = {};
+            result[alias] = {};
             continue;
         }
-        // Build WHERE clause: equality filters + rich conditions
-        const joinTableConf = dbTables[joinTableName];
-        const cb = buildJoinRefCondition(joinTableConf, joinSchema, { filters: groupFilters, conditions: groupConditions }, db);
+        const groupRef = { filters: groupFilters, conditions: groupConditions };
+        const cb = buildJoinRefCondition(joinTableConf, joinSchema, groupRef, db);
         const fkCol = joinSchema.col(joinField);
         cb.isIn(db.qi(fkCol), ids);
-        const where = cb.build(1, db.ph);
-        const values = cb.getValues();
+        let where = cb.build(1, db.ph);
+        let values = cb.getValues();
+        // Side-channel: computed-field clauses on the join table
+        const computedClauses = collectJoinRefComputedClauses(joinTableConf, groupRef, db);
+        if (computedClauses.length > 0) {
+            ({ where, values } = appendComputedConditions(where, values, computedClauses, db));
+        }
         const groupBy = groupByParts.length > 0 ? `GROUP BY ${groupByParts.join(', ')}` : '';
         const sql = `SELECT ${selectParts.join(', ')} FROM ${db.qi(joinSchema.tableName)} WHERE ${where} ${groupBy}`;
         const queryResult = await db.query(sql, values);
         const rows = queryResult.rows;
-        // Format: { distinctCount: {field: value}, min: {field: value}, ... }
         const formatted = {};
         if (rows.length > 0) {
             const row = rows.length === 1 && !aggregations.by ? rows[0] : rows;
@@ -290,13 +482,13 @@ async function executeJoinGroups(db, dbTables, tableConf, mainResults, joinGroup
                 }
             }
         }
-        result[joinTableName] = formatted;
+        result[alias] = formatted;
     }
     return result;
 }
+// ─── ID collection ──────────────────────────────────────────
 function collectIds(mainResults, mainField) {
     if (Array.isArray(mainField)) {
-        // Composite key: collect tuples
         const seen = new Set();
         const ids = [];
         for (const r of mainResults) {
@@ -308,8 +500,7 @@ function collectIds(mainResults, mainField) {
         }
         return ids;
     }
-    const unique = [...new Set(mainResults.map((r) => r[mainField]).filter((v) => v != null))];
-    return unique;
+    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';
@@ -327,11 +518,6 @@ function dispatchConditionMethod(cb, method, colOrExpr, params) {
         cb[method](colOrExpr, true);
     }
 }
-/**
- * Build a ConditionBuilder that applies both equality filters and rich conditions
- * to a join schema. Used by joinFilters (EXISTS), virtual joins data fetching,
- * and joinGroups (aggregation WHERE + orderBy scalar subquery).
- */
 function buildJoinRefCondition(joinTableConf, joinSchema, ref, db) {
     const cb = (ref.filters && joinTableConf)
         ? joinTableConf.filters(ref.filters)
@@ -339,63 +525,147 @@ function buildJoinRefCondition(joinTableConf, joinSchema, ref, db) {
     if (ref.conditions?.length) {
         for (const c of ref.conditions) {
             if (!ALLOWED_SET.has(c.method)) {
-                const err = new Error(`Invalid condition method: ${c.method}`);
-                err.statusCode = 400;
-                throw err;
+                err400(`Invalid condition method: ${c.method}`);
             }
+            // Skip computed-field conditions here — they are processed via side-channel
+            // by `collectJoinRefComputedClauses` since ConditionBuilder cannot bind values
+            // for an LHS expression.
+            if (joinTableConf?.computedFields?.[c.field])
+                continue;
             const col = db.qi(validateSchemaField(c.field, joinSchema));
             dispatchConditionMethod(cb, c.method, col, c.params ?? []);
         }
     }
     return cb;
 }
-function applyConditions(condition, conditions, schema, db) {
+/**
+ * Side-channel: gather equality + operator clauses targeting computed fields
+ * declared on the join table's `computedFields`. To be appended to a WHERE
+ * after the main `cb.build()` with correct placeholder offsets.
+ */
+function collectJoinRefComputedClauses(joinTableConf, ref, db) {
+    const out = [];
+    const computed = joinTableConf?.computedFields;
+    if (!computed)
+        return out;
+    // Equality filters on computed names
+    if (ref.filters) {
+        for (const [name, value] of Object.entries(ref.filters)) {
+            if (value === null || value === undefined)
+                continue;
+            if (!computed[name])
+                continue;
+            const ev = evaluateComputedField(computed[name], joinTableConf.Schema, db, undefined, '', true);
+            out.push({ method: 'isEqual', expr: ev.expr, values: ev.values ?? [], params: [value] });
+        }
+    }
+    // Operator conditions on computed names
+    if (ref.conditions?.length) {
+        for (const c of ref.conditions) {
+            if (!computed[c.field])
+                continue;
+            if (!ALLOWED_SET.has(c.method))
+                err400(`Invalid condition method: ${c.method}`);
+            const ev = evaluateComputedField(computed[c.field], joinTableConf.Schema, db, undefined, '', true);
+            out.push({
+                method: c.method,
+                expr: ev.expr,
+                values: ev.values ?? [],
+                params: c.params ?? [],
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 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) {
+    const computedClauses = [];
     for (const c of conditions) {
         // Skip dot-notation fields — those become aggregation conditions processed later
         if (c.field.includes('.'))
             continue;
-        // Validate method — whitelist only, blocks prototype poisoning
         if (!ALLOWED_SET.has(c.method)) {
-            const err = new Error(`Invalid condition method: ${c.method}`);
-            err.statusCode = 400;
-            throw err;
+            err400(`Invalid condition method: ${c.method}`);
+        }
+        const ref = resolveFieldRef(c.field, schema, tableConf, db);
+        if (!ref.computed) {
+            dispatchConditionMethod(condition, c.method, ref.expr, c.params);
         }
-        const col = db.qi(validateSchemaField(c.field, schema));
-        dispatchConditionMethod(condition, c.method, col, c.params);
+        else {
+            computedClauses.push({
+                method: c.method,
+                expr: ref.expr,
+                values: ref.values,
+                params: c.params ?? [],
+            });
+        }
+    }
+    return computedClauses;
+}
+/**
+ * Equality filters targeting computed fields: when `filters.<computedName>` is
+ * set on the request body and the computed exists on `tableConf.computedFields`,
+ * generate a side-channel clause `<expr> = ?` with the user value as parameter.
+ * This complements the auto-generated equality on schema fields done by
+ * `tableConf.filters()`.
+ */
+function collectComputedFilterClauses(filters, tableConf, db) {
+    const out = [];
+    const computed = tableConf.computedFields;
+    if (!computed)
+        return out;
+    for (const [name, value] of Object.entries(filters)) {
+        if (value === null || value === undefined)
+            continue;
+        if (!computed[name])
+            continue;
+        const ref = evaluateComputedField(computed[name], tableConf.Schema, db, undefined, '', true);
+        out.push({ method: 'isEqual', expr: ref.expr, values: ref.values ?? [], params: [value] });
     }
+    return out;
 }
 /**
- * Append aggregation-based conditions (HAVING-style) to the main WHERE clause.
- * For each condition with a dotted field like `session.count.id`, builds a
- * correlated scalar subquery (reusing buildAggOrderExpr) and uses it as the
- * left-hand side of a ConditionBuilder method.
- *
- * Runs after the base WHERE / joinFilters are built so placeholder offsets
- * are correct.
+ * Append computed-field condition clauses (side-channel from applyConditions)
+ * to the current WHERE, coordinating placeholder indices with the running
+ * `values` array.
  */
-function appendAggConditions(currentWhere, currentValues, conditions, db, dbTables, tableConf, joinGroups) {
+function appendComputedConditions(currentWhere, currentValues, clauses, db) {
+    let where = currentWhere;
+    let values = [...currentValues];
+    for (const c of clauses) {
+        // Append the computed's own bound values first; the expr placeholders
+        // (if any) reference them via stable indices set by the consumer.
+        values = [...values, ...c.values];
+        const tmpCb = new ConditionBuilder('AND');
+        dispatchConditionMethod(tmpCb, c.method, c.expr, c.params);
+        const startIdx = values.length + 1;
+        const clauseSql = tmpCb.build(startIdx, db.ph);
+        where += ` AND ${clauseSql}`;
+        values.push(...tmpCb.getValues());
+    }
+    return { where, values };
+}
+function appendAggConditions(currentWhere, currentValues, conditions, db, dbTables, tableConf, joinGroup) {
     let where = currentWhere;
     let values = [...currentValues];
     for (const c of conditions) {
         if (!c.field.includes('.'))
             continue;
         if (!ALLOWED_SET.has(c.method)) {
-            const err = new Error(`Invalid condition method: ${c.method}`);
-            err.statusCode = 400;
-            throw err;
+            err400(`Invalid condition method: ${c.method}`);
         }
         const parts = c.field.split('.');
         if (parts.length !== 3) {
-            const err = new Error(`Invalid dotted field in condition: ${c.field} (expected <joinTable>.<fn>.<field>)`);
-            err.statusCode = 400;
-            throw err;
+            err400(`Invalid dotted field in condition: ${c.field} (expected <alias>.<fn>.<field>)`);
         }
-        const [joinTableName, fn, field] = parts;
-        // Build the scalar subquery; values for its filters are appended to the main values array.
-        const { expr, values: exprValues } = buildAggOrderExpr(db, dbTables, tableConf, joinTableName, fn, field, joinGroups, values.length + 1);
+        const [alias, fn, field] = parts;
+        const { expr, values: exprValues } = buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup, values.length + 1);
         values = [...values, ...exprValues];
-        // Use a temporary ConditionBuilder to generate "<expr> <op> <placeholder>" with
-        // the correct placeholder offset, then merge it back into the main values.
         const tmpCb = new ConditionBuilder('AND');
         dispatchConditionMethod(tmpCb, c.method, expr, c.params);
         const startIdx = values.length + 1;
@@ -405,42 +675,67 @@ function appendAggConditions(currentWhere, currentValues, conditions, db, dbTabl
     }
     return { where, values };
 }
-// ─── Join filters (EXISTS subquery) ─────────────────────────
-function buildJoinFiltersExists(db, dbTables, tableConf, joinFilters, currentWhere, currentValues) {
+// ─── joinMustExist (EXISTS subquery filter on main) ─────────
+function buildJoinMustExistClauses(db, dbTables, tableConf, joinMustExist, currentWhere, currentValues) {
     let where = currentWhere;
     const values = [...currentValues];
-    for (const [joinTableName, ref] of Object.entries(joinFilters)) {
-        const joinDef = findJoinDefinition(tableConf, joinTableName);
-        if (!joinDef)
-            continue;
-        const [joinSchema, joinField, mainField] = joinDef;
-        const joinTableConf = dbTables[joinTableName];
+    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);
         const filterCondition = buildJoinRefCondition(joinTableConf, joinSchema, ref, db);
         const startIdx = values.length + 1;
-        const filterWhere = filterCondition.build(startIdx, db.ph);
-        const filterVals = filterCondition.getValues();
-        const fkCol = db.qi(joinSchema.col(joinField));
-        const mainColName = Array.isArray(mainField) ? mainField[0] : mainField;
-        const mainCol = db.qi(tableConf.Schema.col(mainColName));
-        const mainTable = db.qi(tableConf.Schema.tableName);
-        // If there are no inner conditions, just the correlation suffices.
+        let filterWhere = filterCondition.build(startIdx, db.ph);
+        let filterVals = [...filterCondition.getValues()];
+        // Side-channel: computed-field clauses
+        const computedClauses = collectJoinRefComputedClauses(joinTableConf, ref, db);
+        if (computedClauses.length > 0) {
+            let cwhere = filterWhere;
+            let cvalues = filterVals;
+            ({ where: cwhere, values: cvalues } = appendComputedConditions(cwhere, [...values, ...cvalues], computedClauses, db));
+            // appendComputedConditions starts with currentValues; we need just the
+            // delta belonging to this EXISTS subquery to update filterVals.
+            filterVals = cvalues.slice(values.length);
+            filterWhere = cwhere;
+        }
         const innerWhere = filterWhere
-            ? `${fkCol} = ${mainTable}.${mainCol} AND ${filterWhere}`
-            : `${fkCol} = ${mainTable}.${mainCol}`;
-        where += ` AND EXISTS (SELECT 1 FROM ${db.qi(joinSchema.tableName)} WHERE ${innerWhere})`;
+            ? `${refs.fkCol} = ${refs.mainTable}.${refs.mainCol} AND ${filterWhere}`
+            : `${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}`;
+        where += ` AND EXISTS (SELECT 1 FROM ${refs.joinTable} WHERE ${innerWhere})`;
         values.push(...filterVals);
     }
     return { where, values };
 }
+// ─── searchEngine entrypoint ────────────────────────────────
 export async function searchEngine(dbTables, params) {
-    const { db, tableConf, filters, conditions, joinFilters, joins, joinGroups, orderBy, paginator, computeMin, computeMax, computeSum, computeAvg, tenant } = 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)
+    if (joinMustExist)
+        for (const a of Object.keys(joinMustExist))
+            requireJoin(tableConf, a, false);
+    if (joinMultiple)
+        for (const a of Object.keys(joinMultiple))
+            requireJoin(tableConf, a, false);
+    if (joinGroup)
+        for (const a of Object.keys(joinGroup))
+            requireJoin(tableConf, a, false);
+    if (joinLeft)
+        for (const a of Object.keys(joinLeft))
+            requireJoin(tableConf, a, true);
     // Build main condition
     const condition = tableConf.filters(filters || {});
-    // Advanced conditions
+    // Filters that target computed fields (declared on tableConf.computedFields)
+    // are applied via the side-channel pattern further down.
+    let computedFilterClauses = [];
+    if (filters && tableConf.computedFields) {
+        computedFilterClauses = collectComputedFilterClauses(filters, tableConf, db);
+    }
+    let computedConditionClauses = [];
     if (conditions?.length) {
-        applyConditions(condition, conditions, tableConf.Schema, db);
+        computedConditionClauses = applyConditions(condition, conditions, tableConf.Schema, tableConf, db);
     }
-    // Tenant filtering
+    // Tenant
     const tenantJoins = [];
     if (tenant) {
         condition.append(buildTenantCondition(db, tenant.scope, tenant.ids));
@@ -450,44 +745,73 @@ export async function searchEngine(dbTables, params) {
     }
     let where = condition.build(1, db.ph);
     let values = [...condition.getValues()];
-    // Join filters: add EXISTS subqueries
-    if (joinFilters && Object.keys(joinFilters).length > 0) {
-        ({ where, values } = buildJoinFiltersExists(db, dbTables, tableConf, joinFilters, where, values));
+    // Append computed filter (equality) and condition (operator) clauses with
+    // correct placeholder offsets.
+    if (computedFilterClauses.length > 0) {
+        ({ where, values } = appendComputedConditions(where, values, computedFilterClauses, db));
+    }
+    if (computedConditionClauses.length > 0) {
+        ({ where, values } = appendComputedConditions(where, values, computedConditionClauses, db));
+    }
+    // joinMustExist (EXISTS)
+    if (joinMustExist && Object.keys(joinMustExist).length > 0) {
+        ({ where, values } = buildJoinMustExistClauses(db, dbTables, tableConf, joinMustExist, where, values));
     }
-    // Aggregation conditions (HAVING-style): dotted fields in `conditions` are
-    // translated into scalar subqueries using the joinGroup aggregation.
+    // Aggregation conditions (HAVING-style)
     if (conditions?.length) {
         const hasAggConditions = conditions.some((c) => c.field.includes('.'));
         if (hasAggConditions) {
-            ({ where, values } = appendAggConditions(where, values, conditions, db, dbTables, tableConf, joinGroups));
+            ({ where, values } = appendAggConditions(where, values, conditions, db, dbTables, tableConf, joinGroup));
         }
     }
-    // Validate and sanitize orderBy (user input -> SQL identifier)
-    // Note: orderBy aggregation values are kept separate from WHERE values,
-    // so that buildPagination (which doesn't use ORDER BY) only binds WHERE params.
+    // orderBy parsing — collects 2-parti aliases that need LEFT JOIN on the main query
     let safeOrderBy;
     let orderByValues = [];
+    let orderByLeftAliases = new Set();
     if (orderBy) {
-        const obResult = validateOrderBy(orderBy, tableConf, db, dbTables, joinGroups, values.length + 1);
+        const obResult = validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, values.length + 1);
         safeOrderBy = obResult.sql;
         orderByValues = obResult.values;
+        orderByLeftAliases = obResult.leftJoinAliases;
     }
-    // Main query: bind WHERE values + orderBy aggregation values
-    const mainValues = [...values, ...orderByValues];
-    const main = await executeMainQuery(db, tableConf, where, mainValues, safeOrderBy, paginator, tenantJoins);
-    // Pagination: bind only WHERE values (COUNT/compute queries don't use ORDER BY)
+    // 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(orderByLeftAliases);
+    if (joinLeft) {
+        for (const [alias, ref] of Object.entries(joinLeft)) {
+            if (ref?.filters || ref?.conditions?.length)
+                aliasesNeedingLeftJoin.add(alias);
+        }
+    }
+    // Build LEFT JOIN clauses + extra WHERE for filtered parents
+    const extraJoinClauses = [...tenantJoins];
+    let leftJoinValues = [];
+    if (aliasesNeedingLeftJoin.size > 0) {
+        const lj = buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingLeftJoin, joinLeft, values.length + 1);
+        extraJoinClauses.push(...lj.joinClauses);
+        leftJoinValues = lj.values;
+        for (const w of lj.whereExtras)
+            where += ` AND ${w}`;
+    }
+    // Bind WHERE values + LEFT JOIN values + orderBy aggregation values for main query.
+    // Pagination COUNT/compute include WHERE + LEFT JOIN values (no orderBy).
+    const whereAndJoinValues = [...values, ...leftJoinValues];
+    const mainValues = [...whereAndJoinValues, ...orderByValues];
+    const main = await executeMainQuery(db, tableConf, where, mainValues, safeOrderBy, paginator, extraJoinClauses, params.selectComputed);
     let pagination;
     if (paginator) {
-        pagination = await buildPagination(db, tableConf, where, values, paginator, tenantJoins, computeMin, computeMax, computeSum, computeAvg);
+        pagination = await buildPagination(db, tableConf, where, whereAndJoinValues, paginator, extraJoinClauses, computeMin, computeMax, computeSum, computeAvg);
     }
-    // Virtual joins (only if requested)
     const result = { main };
-    if (joins && Object.keys(joins).length > 0) {
-        result.joins = await executeVirtualJoins(db, dbTables, tableConf, main, joins);
+    if (joinMultiple && Object.keys(joinMultiple).length > 0) {
+        result.joinMultiple = await executeJoinMultiple(db, dbTables, tableConf, main, joinMultiple);
+    }
+    if (joinLeft && Object.keys(joinLeft).length > 0) {
+        result.joinLeft = await executeJoinLeft(db, tableConf, main, joinLeft);
     }
-    // Join groups (only if requested)
-    if (joinGroups && Object.keys(joinGroups).length > 0) {
-        result.joinGroups = await executeJoinGroups(db, dbTables, tableConf, main, joinGroups);
+    if (joinGroup && Object.keys(joinGroup).length > 0) {
+        result.joinGroup = await executeJoinGroup(db, dbTables, tableConf, main, joinGroup);
     }
     if (pagination) {
         result.pagination = pagination;