fastify-auto-sqlapi 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -81,10 +81,12 @@ Pagination:
81
81
  `orderBy` is a comma-separated list, each part one of:
82
82
  - `field [ASC|DESC]`, including computed fields.
83
83
  - `alias.parentField`: joinLeft alias; adds the LEFT JOIN.
84
- - `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.
84
+ - `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.
85
85
 
86
86
  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.
87
87
 
88
+ 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.
89
+
88
90
  Condition methods and `params` arity:
89
91
  - `[v]`: `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual`
90
92
  - `["%p%"]`: `isLike|isNotLike|isILike|isNotILike`
@@ -823,3 +823,75 @@ dialect.upsertSql(quotedKeys, dialect.upsertUpdateSet(fields, conflictKeys));
823
823
  const { onConflict } = getDialect('postgres');
824
824
  onConflict!.sql(quotedKeys, onConflict!.updateSet(fields, conflictKeys));
825
825
  ```
826
+
827
+ ---
828
+
829
+ # Breaking Change — `min`, `max` and `avg` of a main row without children are NULL
830
+
831
+ *Landed in **0.4.1**.*
832
+
833
+ ## Why this changed
834
+
835
+ `orderBy` and HAVING-style conditions on `<alias>.<fn>.<field>` run a correlated subquery per
836
+ main row, and every aggregate was wrapped in `COALESCE(…, 0)`. Over no child rows, that 0 is
837
+ the right answer for `count`, `distinctCount` and `sum`, but `min`, `max` and `avg` have no
838
+ value at all:
839
+
840
+ - **PostgreSQL**: on a text, char, date or timestamp column the request failed with a 500,
841
+ `COALESCE types … and integer cannot be matched`.
842
+ - **MySQL/MariaDB**: no error, but those mains were compared as `0` — `max(orderDate) <
843
+ '2026-03-01'` matched every main without children.
844
+ - **Both, numeric columns**: a 0 that no child row holds decided the ordering and conditions.
845
+
846
+ ## What changed
847
+
848
+ - `count`, `distinctCount` and `sum` over no rows are still 0.
849
+ - `min`, `max` and `avg` over no rows are NULL. In `orderBy` they sort where the database puts
850
+ NULL (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC). In
851
+ conditions they fail every comparison; `isNull` / `isNotNull` select them.
852
+ - "Without children" includes children all excluded by the joinGroup's own `filters` /
853
+ `conditions`.
854
+ - `result.joinGroup` is unchanged: it was never coalesced.
855
+
856
+ ## Who is affected
857
+
858
+ Clients that order or filter by `min`, `max` or `avg` of a **numeric** column on tables where
859
+ some main rows have no children:
860
+
861
+ - `orderBy=orders.min.total ASC` on PostgreSQL: those mains move from first to last.
862
+ `… DESC`: from last to first. On MySQL/MariaDB the order is unchanged (NULL sorts as the
863
+ smallest value, where the 0 was for non-negative columns).
864
+ - `conditions: [{ field: 'orders.max.total', method: 'isLess', params: [5] }]`: those mains
865
+ no longer match. `isGreater` with a negative value, `isEqual` with 0 and similar change the
866
+ same way.
867
+
868
+ ## Migration
869
+
870
+ - To drop mains without children from a result, add `{ field: 'orders.count.id', method:
871
+ 'isGreater', params: [0] }` (or `isNotNull` on the aggregate).
872
+ - To list only them, use `isNull` on the aggregate, or `isEqual 0` on `count`.
873
+ - Conditions are ANDed, so "below 5 **or** no children" is no longer one request: run the
874
+ `isNull` search separately, or compare against a `count` instead where that expresses the
875
+ same thing.
876
+
877
+ # Breaking Change — Node.js 22 or newer is required
878
+
879
+ *Landed in **0.5.0**.*
880
+
881
+ ## Why this changed
882
+
883
+ `engines.node` said `>=18`, but no Node version other than 24 was tested, and the promise
884
+ was already wrong: Fastify 5, a required peer dependency, supports Node 20 and later only.
885
+ Node 18 and Node 20 are both end-of-life, so the floor now starts at the oldest maintained
886
+ LTS line, and CI runs the full gate on Node 22, 24 and 26 to keep that promise checked.
887
+
888
+ ## Who is affected
889
+
890
+ Deployments still running Node 18 or 20. Nothing in the API, the request/response shapes
891
+ or the table configuration changes.
892
+
893
+ ## Migration
894
+
895
+ Upgrade the runtime to Node 22 or newer. npm only warns on an `engines` mismatch (it fails
896
+ with `engine-strict=true`), so a deployment on an older Node may keep installing, but it is
897
+ no longer supported or tested.
package/CHANGELOG.md CHANGED
@@ -9,6 +9,44 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [0.5.0]
13
+
14
+ ### Changed
15
+
16
+ - **BREAKING: Node.js 22 or newer is required** (`engines.node` is now `>=22`, was `>=18`).
17
+ Node 18 and 20 are end-of-life, and Fastify 5 never supported Node 18. CI now runs the
18
+ full gate on Node 22, 24 and 26. See
19
+ [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--nodejs-22-or-newer-is-required).
20
+
21
+ ### Security
22
+
23
+ - Development dependencies only, nothing shipped in the package: `fastify` 5.12.8
24
+ (GHSA-4mh8-r7rc-xpvc, GHSA-389g-gv7q-r4x8) and `minimatch` forced to `^11.0.5` through
25
+ `overrides` (GHSA-g3hv-75wg-m249) until eslint, typescript-eslint, eslint-plugin-sonarjs
26
+ and ts-morph move off minimatch 10.
27
+
28
+ ## [0.4.1]
29
+
30
+ ### Changed
31
+
32
+ - **BREAKING: `min`, `max` and `avg` of a main row without children are NULL, not 0, in
33
+ `orderBy` and HAVING-style conditions.** The correlated subquery behind `alias.fn.field`
34
+ wrapped every aggregate in `COALESCE(…, 0)`. That 0 is right for `count`, `distinctCount` and
35
+ `sum`, which keep it; for `min`/`max`/`avg` it invented a value the children do not have. On
36
+ numeric columns, such mains now sort where the database puts NULL (PostgreSQL: last in ASC,
37
+ first in DESC; MySQL/MariaDB: first in ASC, last in DESC) instead of as 0, and a condition
38
+ like `max < 5` no longer matches them (`isNull` does). See
39
+ [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--min-max-and-avg-of-a-main-row-without-children-are-null).
40
+
41
+ ### Fixed
42
+
43
+ - **PostgreSQL: `orderBy` or a condition on `min`/`max`/`avg` of a non-numeric column no longer
44
+ fails.** `orderBy=charge.max.monthYear` over a `character(7)` column (or any text, date or
45
+ timestamp one) was a 500, `COALESCE types character and integer cannot be matched`, whenever
46
+ the request reached the database. MySQL/MariaDB did not fail but compared those mains as `0`:
47
+ `max(orderDate) < '2026-03-01'` matched every main without children. Both now compare the
48
+ aggregate as NULL, as above.
49
+
12
50
  ## [0.4.0]
13
51
 
14
52
  ### Changed
@@ -746,7 +784,9 @@ the join API redesign (documented in [BREAKING_CHANGES.md](./BREAKING_CHANGES.md
746
784
  primary key support in updates, transactional insert/update with secondaries, the hook matrix,
747
785
  and bulk operations.
748
786
 
749
- [Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.4.0...HEAD
787
+ [Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.5.0...HEAD
788
+ [0.5.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.5.0
789
+ [0.4.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.1
750
790
  [0.4.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.0
751
791
  [0.3.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.3.0
752
792
  [0.2.4]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.4
package/README.md CHANGED
@@ -325,7 +325,7 @@ request says exactly what to fix.
325
325
 
326
326
  ## Requirements
327
327
 
328
- - Node.js >= 18, Fastify >= 5 (peer dependency)
328
+ - Node.js >= 22, Fastify >= 5 (peer dependency)
329
329
  - **PostgreSQL** + `pg` + `@fastify/postgres`, or **MySQL** / **MariaDB** + `mysql2`
330
330
  - Optional: `@fastify/swagger` + `@fastify/swagger-ui` for Swagger UI
331
331
 
@@ -11,9 +11,16 @@ import { Expression } from 'node-condition-builder';
11
11
  import type { QueryClient } from '../../db.js';
12
12
  import type { QueryParams } from '../query-params.js';
13
13
  import type { DbTables, ITable, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
14
+ /**
15
+ * One aggregation function, as SQL. `zeroWhenEmpty`: over no rows it means 0 (nothing counted,
16
+ * nothing summed), so the correlated subquery coalesces its NULL to 0. min/max/avg over no rows
17
+ * have no value and stay NULL — a 0 would be invented data on numeric columns and a type error
18
+ * on text/date ones.
19
+ */
14
20
  export interface AggFn {
15
21
  sql: string;
16
22
  distinct: boolean;
23
+ zeroWhenEmpty: boolean;
17
24
  }
18
25
  export declare const AGG_FN: Record<string, AggFn>;
19
26
  export declare function aggExpr(fn: AggFn, qualifiedCol: string): string;
@@ -1 +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"}
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;;;;;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"}
@@ -14,12 +14,12 @@ import { err400, validateSchemaField } from './fields.js';
14
14
  import { requireJoin, extractJoinRefs, subqueryAlias } from './joins.js';
15
15
  import { buildJoinRefCondition, dispatchConditionMethod } from './conditions.js';
16
16
  export const AGG_FN = {
17
- sum: { sql: 'SUM', distinct: false },
18
- min: { sql: 'MIN', distinct: false },
19
- max: { sql: 'MAX', distinct: false },
20
- avg: { sql: 'AVG', distinct: false },
21
- count: { sql: 'COUNT', distinct: false },
22
- distinctCount: { sql: 'COUNT', distinct: true },
17
+ sum: { sql: 'SUM', distinct: false, zeroWhenEmpty: true },
18
+ min: { sql: 'MIN', distinct: false, zeroWhenEmpty: false },
19
+ max: { sql: 'MAX', distinct: false, zeroWhenEmpty: false },
20
+ avg: { sql: 'AVG', distinct: false, zeroWhenEmpty: false },
21
+ count: { sql: 'COUNT', distinct: false, zeroWhenEmpty: true },
22
+ distinctCount: { sql: 'COUNT', distinct: true, zeroWhenEmpty: true },
23
23
  };
24
24
  export function aggExpr(fn, qualifiedCol) {
25
25
  return fn.distinct ? `COUNT(DISTINCT ${qualifiedCol})` : `${fn.sql}(${qualifiedCol})`;
@@ -81,7 +81,8 @@ export function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joi
81
81
  }
82
82
  }
83
83
  const qualifiedCol = `${subRef}.${db.qi(fieldCol)}`;
84
- const expr = `COALESCE((SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere}), 0)`;
84
+ const subquery = `(SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere})`;
85
+ const expr = aggFn.zeroWhenEmpty ? `COALESCE(${subquery}, 0)` : subquery;
85
86
  return new Expression(expr, [...tenantVals, ...filterVals]);
86
87
  }
87
88
  /** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fastify-auto-sqlapi",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -69,7 +69,7 @@
69
69
  "typebox"
70
70
  ],
71
71
  "engines": {
72
- "node": ">=18"
72
+ "node": ">=22"
73
73
  },
74
74
  "author": "Luca Rainone",
75
75
  "license": "MIT",
@@ -96,7 +96,7 @@
96
96
  "dependency-cruiser": "^18.1.0",
97
97
  "eslint": "^10.8.0",
98
98
  "eslint-plugin-sonarjs": "^4.2.0",
99
- "fastify": "5.12.4",
99
+ "fastify": "5.12.8",
100
100
  "fuse.js": "^7.5.0",
101
101
  "jscpd": "^5.0.14",
102
102
  "knip": "^6.31.0",
@@ -135,5 +135,8 @@
135
135
  "@fastify/swagger-ui": {
136
136
  "optional": true
137
137
  }
138
+ },
139
+ "overrides": {
140
+ "minimatch": "^11.0.5"
138
141
  }
139
142
  }