fastify-auto-sqlapi 0.4.0 → 0.4.1

package/AGENTS_FRONTEND.md

@@ -81,10 +81,12 @@ Pagination:
 `orderBy` is a comma-separated list, each part one of:
 - `field [ASC|DESC]`, including computed fields.
 - `alias.parentField`: joinLeft alias; adds the LEFT JOIN.
-- `alias.fn.field`, with fn one of `sum|min|max|avg|count|distinctCount`. The joinGroup with that fn and field must be in the body; mains without children sort as 0.
+- `alias.fn.field`, with fn one of `sum|min|max|avg|count|distinctCount`. The joinGroup with that fn and field must be in the body.
 
 For `alias.fn.field`, in both `orderBy` and conditions, the joinGroup `by` must be absent or equal to the FK (else 400). In `orderBy` it is also a 400 on tables with distinct results.
 
+A main without children (or none left after the joinGroup filters) has `count`, `distinctCount` and `sum` = 0, but `min`, `max` and `avg` = null. Null sorts where the database puts it (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC) and fails every comparison: `max < 5` excludes such mains; `isNull` selects them.
+
 Condition methods and `params` arity:
 - `[v]`: `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual`
 - `["%p%"]`: `isLike|isNotLike|isILike|isNotILike`

package/BREAKING_CHANGES.md

@@ -823,3 +823,53 @@ dialect.upsertSql(quotedKeys, dialect.upsertUpdateSet(fields, conflictKeys));
 const { onConflict } = getDialect('postgres');
 onConflict!.sql(quotedKeys, onConflict!.updateSet(fields, conflictKeys));
 ```
+
+---
+
+# Breaking Change — `min`, `max` and `avg` of a main row without children are NULL
+
+*Landed in **0.4.1**.*
+
+## Why this changed
+
+`orderBy` and HAVING-style conditions on `<alias>.<fn>.<field>` run a correlated subquery per
+main row, and every aggregate was wrapped in `COALESCE(…, 0)`. Over no child rows, that 0 is
+the right answer for `count`, `distinctCount` and `sum`, but `min`, `max` and `avg` have no
+value at all:
+
+- **PostgreSQL**: on a text, char, date or timestamp column the request failed with a 500,
+  `COALESCE types … and integer cannot be matched`.
+- **MySQL/MariaDB**: no error, but those mains were compared as `0` — `max(orderDate) <
+  '2026-03-01'` matched every main without children.
+- **Both, numeric columns**: a 0 that no child row holds decided the ordering and conditions.
+
+## What changed
+
+- `count`, `distinctCount` and `sum` over no rows are still 0.
+- `min`, `max` and `avg` over no rows are NULL. In `orderBy` they sort where the database puts
+  NULL (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC). In
+  conditions they fail every comparison; `isNull` / `isNotNull` select them.
+- "Without children" includes children all excluded by the joinGroup's own `filters` /
+  `conditions`.
+- `result.joinGroup` is unchanged: it was never coalesced.
+
+## Who is affected
+
+Clients that order or filter by `min`, `max` or `avg` of a **numeric** column on tables where
+some main rows have no children:
+
+- `orderBy=orders.min.total ASC` on PostgreSQL: those mains move from first to last.
+  `… DESC`: from last to first. On MySQL/MariaDB the order is unchanged (NULL sorts as the
+  smallest value, where the 0 was for non-negative columns).
+- `conditions: [{ field: 'orders.max.total', method: 'isLess', params: [5] }]`: those mains
+  no longer match. `isGreater` with a negative value, `isEqual` with 0 and similar change the
+  same way.
+
+## Migration
+
+- To drop mains without children from a result, add `{ field: 'orders.count.id', method:
+  'isGreater', params: [0] }` (or `isNotNull` on the aggregate).
+- To list only them, use `isNull` on the aggregate, or `isEqual 0` on `count`.
+- Conditions are ANDed, so "below 5 **or** no children" is no longer one request: run the
+  `isNull` search separately, or compare against a `count` instead where that expresses the
+  same thing.

package/CHANGELOG.md

@@ -9,6 +9,28 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ## [Unreleased]
 
+## [0.4.1]
+
+### Changed
+
+- **BREAKING: `min`, `max` and `avg` of a main row without children are NULL, not 0, in
+  `orderBy` and HAVING-style conditions.** The correlated subquery behind `alias.fn.field`
+  wrapped every aggregate in `COALESCE(…, 0)`. That 0 is right for `count`, `distinctCount` and
+  `sum`, which keep it; for `min`/`max`/`avg` it invented a value the children do not have. On
+  numeric columns, such mains now sort where the database puts NULL (PostgreSQL: last in ASC,
+  first in DESC; MySQL/MariaDB: first in ASC, last in DESC) instead of as 0, and a condition
+  like `max < 5` no longer matches them (`isNull` does). See
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--min-max-and-avg-of-a-main-row-without-children-are-null).
+
+### Fixed
+
+- **PostgreSQL: `orderBy` or a condition on `min`/`max`/`avg` of a non-numeric column no longer
+  fails.** `orderBy=charge.max.monthYear` over a `character(7)` column (or any text, date or
+  timestamp one) was a 500, `COALESCE types character and integer cannot be matched`, whenever
+  the request reached the database. MySQL/MariaDB did not fail but compared those mains as `0`:
+  `max(orderDate) < '2026-03-01'` matched every main without children. Both now compare the
+  aggregate as NULL, as above.
+
 ## [0.4.0]
 
 ### Changed
@@ -746,7 +768,8 @@ the join API redesign (documented in [BREAKING_CHANGES.md](./BREAKING_CHANGES.md
 primary key support in updates, transactional insert/update with secondaries, the hook matrix,
 and bulk operations.
 
-[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.1
 [0.4.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.0
 [0.3.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.3.0
 [0.2.4]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.4

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

@@ -11,9 +11,16 @@ import { Expression } from 'node-condition-builder';
 import type { QueryClient } from '../../db.js';
 import type { QueryParams } from '../query-params.js';
 import type { DbTables, ITable, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
+/**
+ * One aggregation function, as SQL. `zeroWhenEmpty`: over no rows it means 0 (nothing counted,
+ * nothing summed), so the correlated subquery coalesces its NULL to 0. min/max/avg over no rows
+ * have no value and stay NULL — a 0 would be invented data on numeric columns and a type error
+ * on text/date ones.
+ */
 export interface AggFn {
     sql: string;
     distinct: boolean;
+    zeroWhenEmpty: boolean;
 }
 export declare const AGG_FN: Record<string, AggFn>;
 export declare function aggExpr(fn: AggFn, qualifiedCol: string): string;

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

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

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

@@ -14,12 +14,12 @@ import { err400, validateSchemaField } from './fields.js';
 import { requireJoin, extractJoinRefs, subqueryAlias } from './joins.js';
 import { buildJoinRefCondition, dispatchConditionMethod } from './conditions.js';
 export const AGG_FN = {
-    sum: { sql: 'SUM', distinct: false },
-    min: { sql: 'MIN', distinct: false },
-    max: { sql: 'MAX', distinct: false },
-    avg: { sql: 'AVG', distinct: false },
-    count: { sql: 'COUNT', distinct: false },
-    distinctCount: { sql: 'COUNT', distinct: true },
+    sum: { sql: 'SUM', distinct: false, zeroWhenEmpty: true },
+    min: { sql: 'MIN', distinct: false, zeroWhenEmpty: false },
+    max: { sql: 'MAX', distinct: false, zeroWhenEmpty: false },
+    avg: { sql: 'AVG', distinct: false, zeroWhenEmpty: false },
+    count: { sql: 'COUNT', distinct: false, zeroWhenEmpty: true },
+    distinctCount: { sql: 'COUNT', distinct: true, zeroWhenEmpty: true },
 };
 export function aggExpr(fn, qualifiedCol) {
     return fn.distinct ? `COUNT(DISTINCT ${qualifiedCol})` : `${fn.sql}(${qualifiedCol})`;
@@ -81,7 +81,8 @@ export function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joi
         }
     }
     const qualifiedCol = `${subRef}.${db.qi(fieldCol)}`;
-    const expr = `COALESCE((SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere}), 0)`;
+    const subquery = `(SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere})`;
+    const expr = aggFn.zeroWhenEmpty ? `COALESCE(${subquery}, 0)` : subquery;
     return new Expression(expr, [...tenantVals, ...filterVals]);
 }
 /** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",