fastify-auto-sqlapi 0.1.5 → 0.1.6

package/AGENTS_BACKEND.md

@@ -485,12 +485,22 @@ type ComputedFieldFn = (ctx: {
   db: QueryClient;                                 // dialect-aware (qi, ph, dialectName, dateTrunc, ...)
   qiCol(field: string, opts?: { qualifier?: string }): string;
 }) => {
-  expr: string;                                    // SQL fragment
-  values: unknown[];                               // bound values (see limitations below)
+  expr: string;                                    // SQL fragment; mark each bound value with `?`
+  values: unknown[];                               // one entry per `?` marker in expr
   type: TSchema;                                   // REQUIRED — used by Swagger and body validation
 };
 ```
 
+**Bound values use `?` markers.** The engine assigns the placeholder positions — never write `$1` or `db.ph(n)` yourself. Use `\?` for a literal question mark (PostgreSQL jsonb operator). A computed whose marker count does not match `values.length` is rejected with a descriptive error, because it would bind values the query never references:
+
+```typescript
+bonus: ({ qiCol }) => ({
+  expr: `CASE WHEN ${qiCol('role')} = ? THEN ${qiCol('salary')} ELSE 0 END`,
+  values: ['admin'],
+  type: Type.Number(),
+}),
+```
+
 `qiCol(field)` returns a properly-quoted column reference, optionally prefixed by an alias qualifier — the engine passes the alias automatically when the computed is invoked inside a `joinLeft` LEFT JOIN, so the same function works both inline on the main query and as a parent-side column.
 
 ### Validation & startup checks
@@ -505,8 +515,9 @@ For `joinLeft` specifically, the computed expr is automatically alias-prefixed b
 
 ### Limitations (first round, by design)
 
-- **Bound `values` in computed expressions** are supported only on `filters`/`conditions` (main and `joinMustExist`/`joinMultiple`/`joinGroup`). They are rejected with 400 on `selectComputed`, `computeMin/Max/Sum/Avg`, `orderBy`, and `joinLeft.filters`/`conditions` — those paths require placeholder coordination not done in the first round. Most use cases (JSON extraction, concat, dateTrunc, simple ops) need no placeholders.
-- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-parti aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
+- **Bound `values` in computed expressions** work anywhere the expression lands in the `WHERE` clause or in `ORDER BY`: `filters` and `conditions` (main, `joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`) and `orderBy`. The ConditionBuilder assigns the placeholder positions there, so no coordination is needed from the caller.
+- They are still rejected with 400 on `selectComputed`, `computeMin/Max/Sum/Avg`, `joinGroup.aggregations.by` and `defaultOrder`. Those expressions are emitted in the `SELECT` / `GROUP BY` list, which precedes the `WHERE` values in the parameter order — there is no correct position for them there. Most use cases (JSON extraction, concat, dateTrunc, simple ops) need no bound values at all.
+- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400 — it is emitted in the `SELECT`/`GROUP BY` list). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-parti aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
 - **Computed cannot be used as aggregation function** (`sum`/`min`/`max`/...). The values inside `aggregations.sum: ['<name>']` must be schema field names. To aggregate on a derived expression, declare the derivation as a computed and pass the computed name as the field, BUT only via `computeMin/Max/Sum/Avg` (top-level main aggregates), not the joinGroup ones.
 - **No chained computed** (a computed referencing another computed). Flat-only.
 - **Read-only**. Computed fields are not usable in insert/update bodies — the consumer's `expr` is for SELECT/WHERE/ORDER BY, never for writes.

package/README.md

@@ -4,6 +4,16 @@ Automatic CRUD API generation from PostgreSQL, MySQL, and MariaDB tables for [Fa
 
 Point it at your database, and get a full REST API with search, advanced conditions, pagination, joins, aggregations, bulk operations, multi-tenant isolation, validation, and hooks.
 
+## What LLMs Are Saying
+
+> API: 5 new read-only tables — and this is where your plugin really shined.
+
+> Yes, it genuinely saved me a lot of work, and the numbers make that obvious: I deleted about 350 lines of hand-written API repository and route code, replacing them with roughly 150 lines of declarative configuration. And it wasn't a one-for-one trade. In return, I gained features I simply didn't have before: complete Swagger documentation, the conditions DSL (previously I only had sorting and fixed filters), pagination with total counts, structured 400 errors, and consistent camelCase conversion. 
+
+> The moment I thought, "Okay, this is well designed," was when I used computedFields: the case of "attributes stored inside a jsonb column that still need to be sortable and filterable" is exactly the kind of problem that usually forces you to step outside the framework, yet it fit in cleanly. It worked end-to-end with the role-based CASE expression, remained sortable, could be projected with selectComputed, and required zero SQL in the routes.
+
+> The AGENTS files deserve a mention: I configured everything without ever opening the source code—CLI schema, defineTable, buildRelation, computed, extraFilters, and the frontend request/response shapes. As "documentation for agents," they genuinely work, and that's more than I can say for most libraries.
+
 ## Features
 
 - **Zero boilerplate** — define your tables, get 7 endpoints each

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

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AA+nC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA4IvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AAmkC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAkIvB"}

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

@@ -1,4 +1,4 @@
-import { ConditionBuilder } from 'node-condition-builder';
+import { ConditionBuilder, Expression } from 'node-condition-builder';
 import { camelcaseObject } from '../../naming.js';
 import { buildTenantCondition, buildTenantJoin } from '../../tenant.js';
 import { assertReadable, assertFiltersReadable, readableSelectColumns } from '../../read-access.js';
@@ -42,13 +42,12 @@ function resolveFieldRef(field, schema, tableConf, db, alias) {
         assertReadable(tableConf, field);
         const col = db.qi(schema.col(field));
         const expr = alias ? `${db.qi(alias)}.${col}` : col;
-        return { expr, values: [], computed: false };
+        return { expr, computed: false };
     }
     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 };
+        return { expr: computedExpression(field, fn(ctx)), computed: true };
     }
     err400(`Unknown field: ${field}`);
 }
@@ -98,16 +97,48 @@ function extractJoinRefs(db, tableConf, joinDef) {
     };
 }
 /**
- * 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).
+ * 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(fn, schema, db, alias, message, allowBoundValues = false) {
+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 ev;
+    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). */
@@ -243,9 +274,12 @@ function validateOrderBy(orderBy, tableConf, db, dbTables, joinGroup, startIdx)
         }
         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;
+        // A computed field binds its own values here: ORDER BY is emitted after the WHERE, so
+        // its placeholders continue from `currentIdx`.
+        const refVals = refValues(ref.expr);
+        outParts.push(`${renderRef(ref.expr, currentIdx, db)} ${(dir || 'ASC').toUpperCase()}`);
+        outValues.push(...refVals);
+        currentIdx += refVals.length;
     }
     return { sql: outParts.join(', '), values: outValues, leftJoinAliases };
 }
@@ -279,9 +313,10 @@ function buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingJoin, joinL
                         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);
+                        // 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);
                     }
                 }
             }
@@ -296,8 +331,8 @@ function buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingJoin, joinL
                         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 ?? []);
+                        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}`);
@@ -337,8 +372,8 @@ function convertConfiguredOrder(order, tableConf, db) {
             }
             const computed = tableConf.computedFields?.[field];
             if (computed) {
-                const ev = evaluateComputedField(computed, tableConf.Schema, db, undefined, `Computed field '${field}' with bound values cannot be used in defaultOrder`);
-                return `${ev.expr}${suffix}`;
+                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;
@@ -366,8 +401,8 @@ async function executeMainQuery(db, tableConf, where, values, orderBy, paginator
             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)}`);
+            const out = evaluateComputedField(name, fn, tableConf.Schema, db, undefined, `Computed field '${name}' with bound values cannot be used in selectComputed`);
+            projections.push(`${out.value} AS ${db.qi(name)}`);
         }
         columns = projections.join(', ');
     }
@@ -398,10 +433,12 @@ async function buildPagination(db, tableConf, where, values, paginator, extraJoi
     for (const { key, field, fn } of computations) {
         if (field) {
             const ref = resolveFieldRef(field, tableConf.Schema, tableConf, db);
-            if (ref.values.length > 0) {
+            // The aggregate sits in the SELECT list, before the WHERE values: a computed that
+            // binds parameters cannot be placed here.
+            if (refValues(ref.expr).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);
+            const result = await db.query(`SELECT ${fn}(${renderRef(ref.expr, 1, db)}) as value FROM ${db.qi(tableName)}${joinClause} WHERE ${where}`, values);
             computed[key] = { [field]: result.rows[0].value };
         }
     }
@@ -429,13 +466,8 @@ async function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMul
         cb.isIn(db.qi(fkCol), ids);
         const tenantJoins = [];
         appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
-        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 where = cb.build(1, db.ph);
+        const values = cb.getValues();
         const selection = ref?.selection ?? defaultSelection;
         const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf);
         const rows = await db.select({
@@ -499,7 +531,7 @@ function buildByExpression(by, joinSchema, joinTableConf, db) {
     }
     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;
+        return evaluateComputedField(by, fn, joinSchema, db, undefined, `Computed field '${by}' with bound values cannot be used in aggregations.by`).value;
     }
     err400(`Unknown field: ${by}`);
 }
@@ -548,13 +580,8 @@ async function executeJoinGroup(db, dbTables, tableConf, mainResults, joinGroup,
         cb.isIn(db.qi(fkCol), ids);
         const tenantJoins = [];
         appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
-        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 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}`;
@@ -618,60 +645,32 @@ function buildJoinRefCondition(joinTableConf, joinSchema, ref, db) {
     const cb = (ref.filters && joinTableConf)
         ? joinTableConf.filters(ref.filters, db.cbDialect)
         : new ConditionBuilder('AND', db.cbDialect);
-    if (ref.conditions?.length) {
-        for (const c of ref.conditions) {
-            if (!ALLOWED_SET.has(c.method)) {
-                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, joinTableConf));
-            dispatchConditionMethod(cb, c.method, col, c.params ?? []);
-        }
-    }
-    return cb;
-}
-/**
- * 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 = [];
+    // Equality filters targeting the join table's computed fields
     const computed = joinTableConf?.computedFields;
-    if (!computed)
-        return out;
-    // Equality filters on computed names
-    if (ref.filters) {
+    if (computed && 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] });
+            const expr = evaluateComputedField(name, computed[name], joinTableConf.Schema, db, undefined, '', true);
+            cb.isEqual(expr, 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))
+            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 ?? [],
-            });
+            }
+            // 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], joinTableConf.Schema, db, undefined, '', true)
+                : db.qi(validateSchemaField(c.field, joinSchema, joinTableConf));
+            dispatchConditionMethod(cb, c.method, operand, c.params ?? []);
         }
     }
-    return out;
+    return cb;
 }
 /**
  * Apply non-dotted conditions to the main `condition` ConditionBuilder when
@@ -680,7 +679,6 @@ function collectJoinRefComputedClauses(joinTableConf, ref, db) {
  * 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('.'))
@@ -688,63 +686,29 @@ function applyConditions(condition, conditions, schema, tableConf, db) {
         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);
-        if (!ref.computed) {
-            dispatchConditionMethod(condition, c.method, ref.expr, c.params);
-        }
-        else {
-            computedClauses.push({
-                method: c.method,
-                expr: ref.expr,
-                values: ref.values,
-                params: c.params ?? [],
-            });
-        }
+        dispatchConditionMethod(condition, c.method, ref.expr, 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()`.
+ * Equality filters targeting computed fields: `filters.<computedName>` becomes
+ * `<expr> = <value>` on the same ConditionBuilder used for schema fields, which
+ * `tableConf.filters()` has already populated.
  */
-function collectComputedFilterClauses(filters, tableConf, db) {
-    const out = [];
+function applyComputedFilters(condition, filters, tableConf, db) {
     const computed = tableConf.computedFields;
     if (!computed)
-        return out;
+        return;
     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] });
+        const expr = evaluateComputedField(name, computed[name], tableConf.Schema, db, undefined, '', true);
+        condition.isEqual(expr, value);
     }
-    return out;
-}
-/**
- * Append computed-field condition clauses (side-channel from applyConditions)
- * to the current WHERE, coordinating placeholder indices with the running
- * `values` array.
- */
-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', db.cbDialect);
-        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;
@@ -783,20 +747,11 @@ function buildJoinMustExistClauses(db, dbTables, tableConf, joinMustExist, curre
         const filterCondition = buildJoinRefCondition(joinTableConf, joinSchema, ref, db);
         const tenantJoins = [];
         appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, filterCondition, tenantJoins);
+        // The sub-condition (computed fields included) is built by the ConditionBuilder, which
+        // numbers its placeholders from where the outer values end.
         const startIdx = values.length + 1;
-        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 filterWhere = filterCondition.build(startIdx, db.ph);
+        const filterVals = [...filterCondition.getValues()];
         // Qualify the FK with the join table: the EXISTS FROM may include the tenant
         // through-join, so a bare column could become ambiguous.
         const innerWhere = filterWhere
@@ -827,15 +782,14 @@ export async function searchEngine(dbTables, params) {
     // Build main condition
     assertFiltersReadable(filters, tableConf);
     const condition = tableConf.filters(filters || {}, db.cbDialect);
-    // Filters that target computed fields (declared on tableConf.computedFields)
-    // are applied via the side-channel pattern further down.
-    let computedFilterClauses = [];
+    // 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) {
-        computedFilterClauses = collectComputedFilterClauses(filters, tableConf, db);
+        applyComputedFilters(condition, filters, tableConf, db);
     }
-    let computedConditionClauses = [];
     if (conditions?.length) {
-        computedConditionClauses = applyConditions(condition, conditions, tableConf.Schema, tableConf, db);
+        applyConditions(condition, conditions, tableConf.Schema, tableConf, db);
     }
     // Tenant
     const tenantJoins = [];
@@ -847,14 +801,6 @@ export async function searchEngine(dbTables, params) {
     }
     let where = condition.build(1, db.ph);
     let values = [...condition.getValues()];
-    // 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, tenant));

package/dist/types/computed.d.ts

@@ -15,10 +15,20 @@ export interface ComputedFieldContext {
 }
 /**
  * Result returned by a ComputedFieldFn.
- *  - `expr`: SQL fragment usable as a scalar expression.
- *  - `values`: bound parameter values (always parameterized — never interpolate
- *    user-derived data into `expr`).
+ *  - `expr`: SQL fragment usable as a scalar expression. Mark each bound value with `?`
+ *    (use `\?` for a literal question mark, e.g. the PostgreSQL jsonb operator). The engine
+ *    assigns the placeholder positions — never write `$1` / `db.ph(n)` yourself, and never
+ *    interpolate user-derived data into the SQL.
+ *  - `values`: bound parameter values, one per `?` marker in `expr`. A mismatch between
+ *    markers and values is rejected: it would bind values the query never references.
  *  - `type`: TypeBox schema for Swagger filters and main response (REQUIRED).
+ *
+ * Example:
+ *   ({ qiCol }) => ({
+ *     expr: `CASE WHEN ${qiCol('role')} = ? THEN ${qiCol('salary')} ELSE 0 END`,
+ *     values: ['admin'],
+ *     type: Type.Number(),
+ *   })
  */
 export interface ComputedFieldExpr {
     expr: string;

package/dist/types/computed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/types/computed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAC7D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,iBAAiB,CAAC"}
+{"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/types/computed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,7 +64,7 @@
   "homepage": "https://github.com/LucaRainone/fastify-auto-sqlapi#readme",
   "dependencies": {
     "@sinclair/typebox": "^0.34.14",
-    "node-condition-builder": "^1.0.6"
+    "node-condition-builder": "^1.2.0"
   },
   "devDependencies": {
     "@fastify/postgres": "^6.0.2",