fastify-auto-sqlapi 0.5.0 → 1.0.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.
Files changed (212) hide show
  1. package/AGENTS.md +5 -5
  2. package/AGENTS_BACKEND.md +166 -130
  3. package/AGENTS_FRONTEND.md +60 -38
  4. package/BREAKING_CHANGES.md +9 -893
  5. package/CHANGELOG.md +258 -15
  6. package/README.md +71 -45
  7. package/dist/bin/generate-schema.js +12 -12
  8. package/dist/bin/generate-tables.js +1 -2
  9. package/dist/bin/utils.d.ts +2 -6
  10. package/dist/bin/utils.d.ts.map +1 -1
  11. package/dist/bin/utils.js +13 -33
  12. package/dist/index.d.ts +13 -33
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +6 -37
  15. package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
  16. package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
  17. package/dist/lib/adapters/pg-adapter.d.ts +5 -2
  18. package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
  19. package/dist/lib/agent/manifest.d.ts +27 -10
  20. package/dist/lib/agent/manifest.d.ts.map +1 -1
  21. package/dist/lib/agent/manifest.js +43 -26
  22. package/dist/lib/agent/tool-schemas.d.ts +5 -4
  23. package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
  24. package/dist/lib/agent/tool-schemas.js +5 -5
  25. package/dist/lib/cli/config.d.ts +37 -2
  26. package/dist/lib/cli/config.d.ts.map +1 -1
  27. package/dist/lib/cli/config.js +106 -16
  28. package/dist/lib/cli/mysql-introspect.d.ts +6 -1
  29. package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
  30. package/dist/lib/cli/mysql-introspect.js +15 -15
  31. package/dist/lib/cli/pg-introspect.d.ts +0 -1
  32. package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
  33. package/dist/lib/cli/pg-introspect.js +2 -13
  34. package/dist/lib/cli/tables-codegen.d.ts +0 -4
  35. package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
  36. package/dist/lib/cli/tables-codegen.js +24 -87
  37. package/dist/lib/db.d.ts +42 -17
  38. package/dist/lib/db.d.ts.map +1 -1
  39. package/dist/lib/db.js +114 -40
  40. package/dist/lib/dialect.d.ts +5 -0
  41. package/dist/lib/dialect.d.ts.map +1 -1
  42. package/dist/lib/dialect.js +3 -0
  43. package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
  44. package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
  45. package/dist/lib/engine/bulk/bulk-delete.js +66 -30
  46. package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
  47. package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
  48. package/dist/lib/engine/read-hooks.d.ts +3 -3
  49. package/dist/lib/engine/read-hooks.d.ts.map +1 -1
  50. package/dist/lib/engine/read-hooks.js +3 -3
  51. package/dist/lib/engine/rest/delete.d.ts.map +1 -1
  52. package/dist/lib/engine/rest/delete.js +12 -18
  53. package/dist/lib/engine/rest/get.js +8 -8
  54. package/dist/lib/engine/rest/insert.d.ts.map +1 -1
  55. package/dist/lib/engine/rest/insert.js +31 -18
  56. package/dist/lib/engine/rest/update.d.ts.map +1 -1
  57. package/dist/lib/engine/rest/update.js +34 -17
  58. package/dist/lib/engine/search/aggregations.d.ts +3 -3
  59. package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
  60. package/dist/lib/engine/search/aggregations.js +20 -16
  61. package/dist/lib/engine/search/conditions.d.ts +9 -5
  62. package/dist/lib/engine/search/conditions.d.ts.map +1 -1
  63. package/dist/lib/engine/search/conditions.js +31 -20
  64. package/dist/lib/engine/search/fields.d.ts +44 -11
  65. package/dist/lib/engine/search/fields.d.ts.map +1 -1
  66. package/dist/lib/engine/search/fields.js +94 -28
  67. package/dist/lib/engine/search/join-families.d.ts +7 -7
  68. package/dist/lib/engine/search/join-families.d.ts.map +1 -1
  69. package/dist/lib/engine/search/join-families.js +84 -75
  70. package/dist/lib/engine/search/joins.d.ts +15 -7
  71. package/dist/lib/engine/search/joins.d.ts.map +1 -1
  72. package/dist/lib/engine/search/joins.js +23 -13
  73. package/dist/lib/engine/search/order-by.d.ts +11 -12
  74. package/dist/lib/engine/search/order-by.d.ts.map +1 -1
  75. package/dist/lib/engine/search/order-by.js +24 -28
  76. package/dist/lib/engine/search/search.d.ts.map +1 -1
  77. package/dist/lib/engine/search/search.js +111 -62
  78. package/dist/lib/engine/validate.d.ts +21 -3
  79. package/dist/lib/engine/validate.d.ts.map +1 -1
  80. package/dist/lib/engine/validate.js +106 -16
  81. package/dist/lib/engine/write-helpers.d.ts +69 -16
  82. package/dist/lib/engine/write-helpers.d.ts.map +1 -1
  83. package/dist/lib/engine/write-helpers.js +257 -105
  84. package/dist/lib/errors.d.ts +42 -10
  85. package/dist/lib/errors.d.ts.map +1 -1
  86. package/dist/lib/errors.js +69 -15
  87. package/dist/lib/nullable.d.ts +3 -2
  88. package/dist/lib/nullable.d.ts.map +1 -1
  89. package/dist/lib/nullable.js +14 -5
  90. package/dist/lib/read-access.d.ts +33 -21
  91. package/dist/lib/read-access.d.ts.map +1 -1
  92. package/dist/lib/read-access.js +42 -23
  93. package/dist/lib/schema/bulk-delete.d.ts +13 -7
  94. package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
  95. package/dist/lib/schema/bulk-delete.js +18 -8
  96. package/dist/lib/schema/bulk-upsert.d.ts +3 -3
  97. package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
  98. package/dist/lib/schema/bulk-upsert.js +9 -14
  99. package/dist/lib/schema/get.d.ts +1 -1
  100. package/dist/lib/schema/get.d.ts.map +1 -1
  101. package/dist/lib/schema/get.js +2 -2
  102. package/dist/lib/schema/helpers.d.ts +41 -23
  103. package/dist/lib/schema/helpers.d.ts.map +1 -1
  104. package/dist/lib/schema/helpers.js +80 -33
  105. package/dist/lib/schema/insert.d.ts +1 -1
  106. package/dist/lib/schema/insert.d.ts.map +1 -1
  107. package/dist/lib/schema/insert.js +12 -20
  108. package/dist/lib/schema/search.d.ts +2 -13
  109. package/dist/lib/schema/search.d.ts.map +1 -1
  110. package/dist/lib/schema/search.js +64 -61
  111. package/dist/lib/schema/update.d.ts +1 -1
  112. package/dist/lib/schema/update.d.ts.map +1 -1
  113. package/dist/lib/schema/update.js +6 -13
  114. package/dist/lib/sql-api.d.ts +47 -25
  115. package/dist/lib/sql-api.d.ts.map +1 -1
  116. package/dist/lib/sql-api.js +70 -27
  117. package/dist/lib/table-helpers.d.ts +92 -14
  118. package/dist/lib/table-helpers.d.ts.map +1 -1
  119. package/dist/lib/table-helpers.js +367 -128
  120. package/dist/lib/tenant.d.ts +16 -22
  121. package/dist/lib/tenant.d.ts.map +1 -1
  122. package/dist/lib/tenant.js +38 -54
  123. package/dist/lib/write-access.d.ts +15 -9
  124. package/dist/lib/write-access.d.ts.map +1 -1
  125. package/dist/lib/write-access.js +12 -4
  126. package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
  127. package/dist/routes/auto/agent-manifest.routes.js +2 -2
  128. package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
  129. package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
  130. package/dist/routes/auto/bulk-delete.routes.js +1 -7
  131. package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
  132. package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
  133. package/dist/routes/auto/bulk-upsert.routes.js +2 -2
  134. package/dist/routes/auto/delete.routes.d.ts +2 -2
  135. package/dist/routes/auto/delete.routes.d.ts.map +1 -1
  136. package/dist/routes/auto/delete.routes.js +8 -10
  137. package/dist/routes/auto/get.routes.d.ts +2 -2
  138. package/dist/routes/auto/get.routes.d.ts.map +1 -1
  139. package/dist/routes/auto/get.routes.js +5 -5
  140. package/dist/routes/auto/insert.routes.d.ts +2 -2
  141. package/dist/routes/auto/insert.routes.d.ts.map +1 -1
  142. package/dist/routes/auto/insert.routes.js +1 -7
  143. package/dist/routes/auto/plugin.d.ts +6 -0
  144. package/dist/routes/auto/plugin.d.ts.map +1 -1
  145. package/dist/routes/auto/plugin.js +60 -36
  146. package/dist/routes/auto/route-helpers.d.ts +26 -12
  147. package/dist/routes/auto/route-helpers.d.ts.map +1 -1
  148. package/dist/routes/auto/route-helpers.js +50 -19
  149. package/dist/routes/auto/search.routes.d.ts +2 -2
  150. package/dist/routes/auto/search.routes.d.ts.map +1 -1
  151. package/dist/routes/auto/search.routes.js +36 -24
  152. package/dist/routes/auto/update.routes.d.ts +2 -2
  153. package/dist/routes/auto/update.routes.d.ts.map +1 -1
  154. package/dist/routes/auto/update.routes.js +1 -8
  155. package/dist/routes/sql-api-decorator.d.ts +30 -12
  156. package/dist/routes/sql-api-decorator.d.ts.map +1 -1
  157. package/dist/routes/sql-api-decorator.js +44 -27
  158. package/dist/types/cli.d.ts +17 -6
  159. package/dist/types/cli.d.ts.map +1 -1
  160. package/dist/types/computed.d.ts +1 -1
  161. package/dist/types/computed.d.ts.map +1 -1
  162. package/dist/types/conditions.d.ts +3 -1
  163. package/dist/types/conditions.d.ts.map +1 -1
  164. package/dist/types/db.d.ts +44 -4
  165. package/dist/types/db.d.ts.map +1 -1
  166. package/dist/types/dml.d.ts +26 -17
  167. package/dist/types/dml.d.ts.map +1 -1
  168. package/dist/types/hooks.d.ts +62 -0
  169. package/dist/types/hooks.d.ts.map +1 -0
  170. package/dist/types/hooks.js +1 -0
  171. package/dist/types/join.d.ts +25 -8
  172. package/dist/types/join.d.ts.map +1 -1
  173. package/dist/types/plugin.d.ts +58 -19
  174. package/dist/types/plugin.d.ts.map +1 -1
  175. package/dist/types/plugin.js +2 -0
  176. package/dist/types/request.d.ts +2 -2
  177. package/dist/types/schema.d.ts +3 -3
  178. package/dist/types/schema.d.ts.map +1 -1
  179. package/dist/types/search.d.ts +28 -13
  180. package/dist/types/search.d.ts.map +1 -1
  181. package/dist/types/search.js +2 -1
  182. package/dist/types/table.d.ts +109 -94
  183. package/dist/types/table.d.ts.map +1 -1
  184. package/dist/types/table.js +7 -2
  185. package/dist/types/tenant.d.ts +28 -2
  186. package/dist/types/tenant.d.ts.map +1 -1
  187. package/dist/types/tenant.js +7 -1
  188. package/dist/types/validation.d.ts +69 -13
  189. package/dist/types/validation.d.ts.map +1 -1
  190. package/dist/types.d.ts +1 -0
  191. package/dist/types.d.ts.map +1 -1
  192. package/dist/types.js +1 -0
  193. package/docs/GLOSSARY.md +11 -5
  194. package/docs/adr/0003-bulk-not-transactional.md +2 -1
  195. package/docs/adr/0006-raw-db-errors.md +2 -1
  196. package/docs/adr/0013-sanitized-db-errors.md +2 -1
  197. package/docs/adr/0014-what-follows-a-write-join.md +1 -1
  198. package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
  199. package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
  200. package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
  201. package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
  202. package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
  203. package/docs/adr/0027-the-1-0-contract.md +74 -0
  204. package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
  205. package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
  206. package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
  207. package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
  208. package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
  209. package/docs/adr/README.md +12 -1
  210. package/docs/upgrading/0.x.md +906 -0
  211. package/docs/upgrading/1.0.md +628 -0
  212. package/package.json +4 -5
package/CHANGELOG.md CHANGED
@@ -2,12 +2,253 @@
2
2
 
3
3
  All notable changes to this project are documented here. This project follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to
5
- [Semantic Versioning](https://semver.org/) — with the caveat that while the version is
6
- `0.x`, breaking changes may land in a minor release.
5
+ [Semantic Versioning](https://semver.org/): from 1.0, a breaking change bumps the major
6
+ ([ADR 0027](./docs/adr/0027-the-1-0-contract.md)). Through 0.x, a breaking change bumped the
7
+ minor and never the patch ([ADR 0022](./docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md)).
7
8
 
8
- Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)**.
9
+ Migration instructions, one guide per release line, indexed in
10
+ [BREAKING_CHANGES.md](./BREAKING_CHANGES.md): **[docs/upgrading/1.0.md](./docs/upgrading/1.0.md)**
11
+ from 0.5 to 1.0, [docs/upgrading/0.x.md](./docs/upgrading/0.x.md) for the 0.x releases.
9
12
 
10
- ## [Unreleased]
13
+ ## [1.0.0] - 2026-11-18
14
+
15
+ The API made coherent in one breaking release: one name and one place for each concept, one
16
+ shape for each result, every retired key refused rather than ignored. **Upgrading from 0.5:
17
+ [docs/upgrading/1.0.md](./docs/upgrading/1.0.md)**, one guide for the whole release. The contract
18
+ of 1.0 — what is public, how it changes — is [ADR 0027](./docs/adr/0027-the-1-0-contract.md),
19
+ which supersedes ADR 0022.
20
+
21
+ 1.0.0 follows 0.5.1. The 0.6.0 prepared after it, TypeBox 1.x and a first cleanup of the public
22
+ names, was never published: its changes are listed here and covered by the same guide.
23
+
24
+ ### Added
25
+
26
+ - **`extendedCondition` receives `{ col }`**, its third argument: `col(field)` is the column
27
+ quoted for the dialect and qualified for the statement the condition lands in — the table in
28
+ the main search and in a side query, the alias inside a join's correlated subquery. A bare
29
+ `Schema.col()` was unquoted (a camelCase column failed on PostgreSQL) and a table-name prefix
30
+ bound to the outer row inside a self-relation's subquery. Typed by the schema's fields; a
31
+ name that is not one throws. Type `ExtendedConditionContext`.
32
+ - **`replace` in a write request** ([ADR 0029](./docs/adr/0029-a-write-names-its-child-rows-by-action.md)):
33
+ the complete set of child rows of an alias — the rows sent are upserted, every other child
34
+ row of the main row is deleted and reported under `deletions`, in the response and to
35
+ `afterInsert`/`afterUpdate`. `[]` removes them all. Needs the relation's `upsertKey`, which
36
+ the manifest now reports on each write join. In a bulk upsert, an item with a `replace` runs
37
+ its child rows in a transaction of its own.
38
+ - **The agent manifest reports a table's own `upsertKey`** (JSON and markdown, with its rule in
39
+ the legend): what every row of an insert or bulk upsert must carry, and that a
40
+ `serverGenerated` key only names an existing row. It already reported a write join's.
41
+ - **Every type a public signature names is exported**: `ApiReply`, `BuildRelationOptions`,
42
+ `JoinFetchRequest`, `JoinRefFilter`, `BulkUpsertOptions`, `ManifestField`, `ManifestJoin`,
43
+ `ValidatorResult` (what `validate` returns), `PrimaryKeyValue`, `WriteJoinSections`, and the
44
+ adapters' parameter types `PgQueryable` and `MysqlQueryable`, which a consumer could only
45
+ reach through another type before. The dependency types the public signatures name are
46
+ re-exported too, so a consumer needs no direct dependency on them: `TSchema`, `TObject`,
47
+ `TUnsafe` (TypeBox) and `ConditionValueOrUndefined` (node-condition-builder).
48
+ - **A secondary's `beforeInsert` sees the FK to the main row** already filled in, over the
49
+ client's value; the engine still fills it again after the hook, which cannot move it.
50
+ - **Bulk delete on a composite primary key.** `POST /bulk/:table/delete` and
51
+ `sqlApi.bulkDelete()` take one object per key, `{ ids: [{ postId: 1, tagId: 2 }] }`, matched
52
+ on every key column; the hooks receive the same objects, typed `PrimaryKeyValue`. A link
53
+ table (M:N) no longer needs a custom route. `get` and `delete` by `:id` stay unavailable on
54
+ such a table.
55
+ - **`dbErrors`**: driver error codes the consumer answers with an HTTP status and a code of
56
+ its own instead of the sanitized 500, keyed by `err.code` as the driver raises it:
57
+ `dbErrors: { '23505': { status: 409, code: 'duplicate' } }` (`'ER_DUP_ENTRY'` on
58
+ MySQL/MariaDB). The answer keeps the error envelope with `fields: [{ path: '', code }]`, and
59
+ no driver detail. The plugin ships no mapping (ADR 0024). An invalid entry fails
60
+ registration. Exported type `DbErrorMapping`.
61
+ - **One error envelope**, `{ statusCode, error, message, requestId, fields? }`, for every error
62
+ the routes return. `error` is the reason phrase, `requestId` the log's `reqId`, and every 400
63
+ carries `fields: [{ path, code, message }]` — the engine's rejections included, with a stable
64
+ code and the request path of the offending value. Codes and the path grammar are listed in
65
+ AGENTS_FRONTEND.md. `httpError(400, msg, { code, path })` is exported, for hooks.
66
+ - **Plugin option `operations`**: the operations a registration exposes, intersected with each
67
+ table's own. The agent manifest of the registration and `agentToolSchemas(…, { operations })`
68
+ follow it.
69
+ - **Plugin option `decorate`** (default `true`): `false` for every registration but the one
70
+ owning `app.sqlApi`.
71
+ - **`select` in search**: the fields to project, schema and computed alike, over HTTP and in
72
+ `sqlApi.search()`. The primary key, the keys the requested joins correlate on and, with
73
+ `distinctResults`, the ORDER BY fields are always projected. `'*'` stands for every readable
74
+ field: `['*', 'fullName']` adds a computed field without listing the others.
75
+ - **`compute` in search**: `{ min, max, sum, avg, count, distinctCount }`, several fields per
76
+ function, answered in a top-level `computed` over every matching row, with or without a
77
+ paginator.
78
+ - **`action: 'inserted' | 'updated'`** on the single insert response and on every item of the
79
+ bulk upsert response. Exported types `WriteAction`, `WrittenRow`.
80
+ - **`upsertKey`** on the table (main rows) and on `buildRelation` (the secondaries of a write
81
+ join), verified at startup (ADR 0021).
82
+ - **`target` on `buildRelation`**: the `dbTables` key whose config governs the joined table,
83
+ required when that table sits under several keys.
84
+ - **`TENANT_ADMIN`**: what `getTenantId` returns for unrestricted access. Exported types
85
+ `TenantAdmin`, `TenantResolution`, `GetTenantId`.
86
+ - **Hook context types**: `HookContext`, `WriteRecord`, `WriteHookContext`,
87
+ `AfterInsertContext`, `AfterUpdateContext`, `AfterReadContext`, `ReadSource`,
88
+ `DeleteHookContext`, `BulkDeleteHookContext`, `ValidateContext`, `BulkValidateContext`.
89
+ - **`QueryClient.supportsTransactions`**, and `Date` as a QueryClient value.
90
+ - **`createSqlApi` infers the table names** of the `dbTables` it is given: a misspelled one
91
+ fails at compile time.
92
+ - **Types** `TableDefinition` (what `defineTable` takes), `ValidationField`, `ComputeFn`,
93
+ `ComputeRequest`, `ComputedResult`, `RowsByAlias`, `SqlApiBulkDeleteParams`, `CliConfig`.
94
+ - **ADRs 0023–0032**: a write runs in a transaction or not at all; `dbErrors`; `validateBulk`
95
+ replaces `validate` in a bulk upsert; an update carries its primary key in `main`; the 1.0
96
+ contract; `*` is the default projection
97
+ ([0028](./docs/adr/0028-select-star-is-the-default-projection.md)); a write names its child
98
+ rows by action; a child row is validated by its own table; an insert-excluded upsert key
99
+ addresses an existing row; tenant scope names schema fields.
100
+ - **`tenantScope` names schema fields**, like every other key of a table config
101
+ ([ADR 0032](./docs/adr/0032-tenant-scope-names-schema-fields.md)): `column`, `anyOf` and
102
+ `through.localField` resolve through the table's schema, the indirect `column` and
103
+ `through.foreignField` through `through.schema`. The column of a field is accepted as written,
104
+ so a scope naming columns keeps working; any other name fails `defineTable` at startup, where a
105
+ misspelling used to fail as a 500 on the first query. The startup error for a field name is gone,
106
+ and the CLI `tables` template, which already wrote `localField` as a field, is now correct.
107
+
108
+ ### Changed
109
+
110
+ Every entry below is breaking; [docs/upgrading/1.0.md](./docs/upgrading/1.0.md) has the migration for each.
111
+
112
+ - **TypeBox 1.x** ([`typebox`](https://www.npmjs.com/package/typebox)) replaces
113
+ `@sinclair/typebox` 0.34. `Type` and `Static` re-exported by this package now come from it.
114
+ Code that imports `Type` from `fastify-auto-sqlapi`, as the generated schema files do, needs
115
+ no change. Schemas built with `@sinclair/typebox` directly must move to `typebox` 1.x, or
116
+ their `Type.Optional` fields silently become required. Schemas from any `typebox` 1.x copy,
117
+ such as the one `@fastify/type-provider-typebox` 6 brings in, now mix freely with this
118
+ package's.
119
+ - **Plugin and `createSqlApi`**
120
+ - The plugin option `DbTables` is `dbTables`.
121
+ - `getTenantId` returning `null`/`undefined` is a 401 on every table with a tenant scope in
122
+ reach; unrestricted access is `TENANT_ADMIN`.
123
+ - A second registration in the same scope, or one over an application `sqlApi`, fails
124
+ unless it passes `decorate: false`.
125
+ - The plugin is the one way to mount the routes: the route plugins and `setupSwagger` are no
126
+ longer exported.
127
+ - `createSqlApi` takes the dialect from a QueryClient; a `dialect` option beside one throws.
128
+ - A write needs a `Queryable` with `connect()`: without it, inserts and updates throw instead
129
+ of running unprotected (ADR 0023).
130
+ - **Table configuration**
131
+ - `defineTable({ primary, schema, extraFilters, extendedCondition, … })` replaces the spread
132
+ of `exportTableInfo()`; the config carries `schema`, not `Schema`.
133
+ - `allowedReadJoins` / `allowedWriteJoins` are `readJoins` / `writeJoins`.
134
+ - `excludeFromCreation` is `insertExclude`, aligned with `readExclude` / `writeExclude`. Same
135
+ behaviour; the table generator writes the new name.
136
+ - The type `ITable` is `TableConfig`, as the glossary calls the concept.
137
+ - `upsertMap` and `buildUpsertRule(s)` are replaced by `upsertKey`.
138
+ - `defaultOrder` has the 1-part `orderBy` grammar, checked at startup; no raw SQL.
139
+ - `buildRelation({ selection })` is `{ select: [...] }`, checked against the joined schema.
140
+ - A relation over a table exposed under several keys must name its `target`.
141
+ - A `tenantScope` name that is neither a field of its schema nor the column of one fails at
142
+ startup; it was taken as a column (ADR 0032).
143
+ - Every pre-1.0 key throws at startup, naming its replacement.
144
+ - **Hooks**
145
+ - Every hook and validator receives one context object, `{ db, req, …data }`; `req` may be
146
+ `undefined`.
147
+ - `validate` and `validateBulk` return `{ path, code }` objects; tuples, a `message`, or a
148
+ result that is not an array are a programming error. `ValidationError` is gone.
149
+ - `ValidationField.message` is optional: absent on the fields a validator returned and on a
150
+ `dbErrors` answer, where it only repeated the code or the reason phrase.
151
+ - `beforeInsert` and `afterInsert` may return `void`, like every other hook; the secondaries
152
+ and deletions given to `afterInsert` and `afterUpdate` are typed `RowsByAlias`, not
153
+ `unknown`. Type-level only.
154
+ - **`sqlApi` and the QueryClient**
155
+ - `sqlApi.insert` / `update` take `{ main, … }`, the HTTP body; `record` throws.
156
+ - `sqlApi.bulkDelete` takes `{ ids }`.
157
+ - An unknown table in `sqlApi` throws an `Error`; it was a 400 `unknown_table`.
158
+ - The QueryClient upserts with `upsert` and `bulkUpsert`, both answering `{ pk, action }`;
159
+ `bulkUpsert` takes `{ chunkSize, immutableCols }`. `insertOrUpdate`,
160
+ `bulkInsertOrUpdate` and their `*WithAction` versions are gone.
161
+ - **Exports**: the package entry exports the public API only. Gone: the engines, the schema
162
+ builders, `SearchTableQuery` and `SearchTableQueryString`, the naming helpers,
163
+ `getDialect`/`SqlDialect`, `resolveTenant`/`TenantContext`, the engine parameter types,
164
+ `ColumnInfo`, `TableMap`, and `escapeIdent`, which escaped PostgreSQL identifiers only and was
165
+ wrong on MySQL (`db.qi()` replaces it). `SqlApiConfig` is `CliConfig`.
166
+ - **CLI**
167
+ - `sqlapi-generate-schema` connects through one URL whose scheme names the dialect, from
168
+ `--url`, `connection` in `sqlapi.config`, or `DATABASE_URL`, in this order; the `.env` of
169
+ the current directory is loaded before the config. `POSTGRES_*` / `MYSQL_*` are no longer
170
+ read, and with no URL the run fails: it used to fall back to the library's test database.
171
+ - `dialect` and `envFile` in the config and `--dialect` are refused, as is any unknown key or
172
+ option; a config that fails to load fails the run instead of falling back to the defaults.
173
+ - The schema CLI prints the database it introspects, password masked; MySQL credentials in
174
+ the URL are percent-decoded.
175
+ - **HTTP**
176
+ - The search request travels in the body only: `orderBy`, `page`, `itemsPerPage` and
177
+ `computeMin|Max|Sum|Avg` in the querystring are a 400 `retired_key`.
178
+ - `select` replaces `selectComputed` and a join's `selection`, both a 400 `retired_key`.
179
+ - `compute` answers in a top-level `computed`, not `pagination.computed`.
180
+ - `joinGroup` takes `by` and the functions directly, and always answers `{ rows: [...] }`
181
+ with `{ by, sum: { total } }` rows.
182
+ - `POST /bulk/:table/delete` takes `{ ids: [...] }`.
183
+ - A write names its child rows by action: `secondaries` is `upsert`, `deletions` is `delete`,
184
+ and the old keys are a 400 `retired_key`; the response keeps `secondaries` and `deletions`
185
+ for what was written and removed. `validate` receives `{ main, upsert, replace }` (ADR 0029).
186
+ - A child row written through a write join is validated by its own table: the child's
187
+ `validate` (or `validateBulk`, once per alias) runs before any SQL, with
188
+ `parent: { alias, main }`, and its errors answer at `upsert.<alias>.<i>.<field>`. A
189
+ required-FK rule guards on `!parent`: the FK is known only when the request names the
190
+ parent's key (ADR 0030).
191
+ - An alias under `upsert`, `delete` or `replace` not declared in `writeJoins` is a 400
192
+ `unknown_field`, and nothing is written: it was dropped in silence.
193
+ - `error` in an error response is the HTTP reason phrase for every status.
194
+
195
+ ### Fixed
196
+
197
+ - **A response the Schema could not serialize leaked the stored value**: a column changed in the
198
+ database after its Schema was generated made the serializer refuse a row, and its message —
199
+ quoting the value — reached the client as the 500's `message`, unlogged. The error is raised
200
+ after the route handler, outside its sanitization; it is now the fixed 500 like any other
201
+ (ADR 0013), with the original in the log under the request's id and, under
202
+ `exposeDebugInfo`, in `debugInfo`.
203
+ - **An upsert by a key under `insertExclude` duplicated the rows it meant to update**
204
+ ([ADR 0031](./docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md)):
205
+ `upsertKey: ['id']` with the `insertExclude: ['id']` the CLI generates stripped the key, so
206
+ every row sent with an id was inserted again under a new one — main rows and the child rows
207
+ of a write join alike. The key now updates the row it names; a key naming no row is a 400
208
+ `not_found` at its path, and a row without the key is inserted as before.
209
+ - **`pgQueryable(new pg.Pool())` and `pgQueryable(fastify.pg)` did not compile** (TS2345): the
210
+ type of `connect()` required the checked-out client to have a `connect()` of the same type,
211
+ which pg's `PoolClient` does not. The checked-out client now needs only `query` and
212
+ `release`; `mysqlQueryable` is aligned. A `pg.Client` stays refused: its `connect()` opens
213
+ the connection, it does not check one out.
214
+ - **`app.sqlApi` was untyped for a consumer** (TS2339): the `FastifyInstance` augmentation sat
215
+ in a module the package's declarations reached only through a type-only import, which the
216
+ emitted `.d.ts` drops. It is now declared in the plugin module itself.
217
+ - **The 400 for an aggregation grouped by a non-FK column said "Cannot order by" in a condition
218
+ too**: its message now names the clause it was found in (path and code were already right).
219
+ - **A delete under an indirect tenant scope failed on MySQL and MariaDB** (error 1093): the
220
+ DELETE named its rows through a subquery reading the same table. It now tests the parent
221
+ with a correlated `EXISTS`, as the deletions of a write join already did;
222
+ `DELETE /rest/:table/:id` and bulk delete both work.
223
+ - **A search without a paginator was paginated.** The querystring schema declared a default
224
+ `itemsPerPage`, which Ajv injected before the handler: every search ran a `COUNT(*)` and
225
+ answered page 1 of 500 rows. It now returns up to `maxItemsPerPage` rows, without
226
+ `pagination`.
227
+ - **A second registration of the plugin ran its routes with the first one's configuration**:
228
+ its `dbTables`, `getTenantId` and table rules — a tenant scope declared only on the second
229
+ surface was not applied. Each registration's routes run through its own SqlApi.
230
+ - **A join target's config applied only when its `dbTables` key was the table name.**
231
+ Otherwise its `readExclude` fields were returned through `joinMultiple` and `joinLeft`.
232
+ - **An update on a table whose tenant column is camelCase failed with a 500** on PostgreSQL:
233
+ the tenant predicate named the column unquoted.
234
+ - **A search with computed fields and a JOIN on the main query returned the joined table's
235
+ columns in the main rows** (also fixed in 0.5.1).
236
+ - **`GET|DELETE /rest/:table/:id` validate `:id` against the primary key's type**: a 400 on
237
+ `id` instead of a 500, and the value reaches SQL with the key's type.
238
+
239
+ ## [0.5.1]
240
+
241
+ ### Fixed
242
+
243
+ - **A search with `selectComputed` and a JOIN on the main query returned the joined table's
244
+ columns in the main rows.** A filtered or ordered `joinLeft`, or a tenant scope with
245
+ `through`, adds a JOIN to the main statement; the `selectComputed` path built its
246
+ projection as a bare `*, <expr> AS "x"`, which bypassed the qualification `db.select`
247
+ applies to a plain `*`. On a column name shared with the joined table (`id`, `name`,
248
+ `createdAt`…) the driver keeps the last value read, so every main row carried the parent's
249
+ id and its extra columns. The main projection is now always `"table".*` or the table's
250
+ readable columns, qualified, whatever else is projected. Searches without `selectComputed`
251
+ were not affected.
11
252
 
12
253
  ## [0.5.0]
13
254
 
@@ -16,7 +257,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
16
257
  - **BREAKING: Node.js 22 or newer is required** (`engines.node` is now `>=22`, was `>=18`).
17
258
  Node 18 and 20 are end-of-life, and Fastify 5 never supported Node 18. CI now runs the
18
259
  full gate on Node 22, 24 and 26. See
19
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--nodejs-22-or-newer-is-required).
260
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--nodejs-22-or-newer-is-required).
20
261
 
21
262
  ### Security
22
263
 
@@ -36,7 +277,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
36
277
  numeric columns, such mains now sort where the database puts NULL (PostgreSQL: last in ASC,
37
278
  first in DESC; MySQL/MariaDB: first in ASC, last in DESC) instead of as 0, and a condition
38
279
  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).
280
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--min-max-and-avg-of-a-main-row-without-children-are-null).
40
281
 
41
282
  ### Fixed
42
283
 
@@ -66,7 +307,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
66
307
  - the exported `SqlDialect` type loses `upsertSql()` and `upsertUpdateSet()`, replaced by
67
308
  `onConflict?: { sql(), updateSet() }`, present on PostgreSQL only.
68
309
  Regenerate the schemas; see
69
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--an-upsert-targets-a-unique-key-verified-at-startup).
310
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--an-upsert-targets-a-unique-key-verified-at-startup).
70
311
 
71
312
  ### Fixed
72
313
 
@@ -120,7 +361,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
120
361
  manifest advertised a URL that did not exist. Routes are now `/search/<key>`,
121
362
  `/rest/<key>`, `/bulk/<key>`, and the search response's `table` names the key too. Configs
122
363
  generated by `sqlapi-generate-tables` use the table name as key and are unaffected. See
123
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--the-route-url-is-the-dbtables-key).
364
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--the-route-url-is-the-dbtables-key).
124
365
  - **`fastify-plugin` 5 → 6.** The only runtime dependency bump: v6 renames its entry files and
125
366
  drops the long-deprecated `PluginOptions` type (now `PluginMetadata`), neither of which this
126
367
  library uses. No change for consumers; still Fastify 5.
@@ -409,7 +650,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
409
650
  one; it is still never called when nothing scoped is in reach. Tables that already declared
410
651
  their own scope emit unchanged SQL. Migration — including the `getTenantId` body that now needs
411
652
  to tolerate an unauthenticated request — in
412
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--the-tenant-follows-the-request-not-the-table-it-addresses).
653
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--the-tenant-follows-the-request-not-the-table-it-addresses).
413
654
 
414
655
  - **Database errors no longer reach clients verbatim.** Any error escaping an auto-generated
415
656
  route that the plugin did not raise itself now answers `{"statusCode":500,"error":"Internal
@@ -450,7 +691,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
450
691
  1024-character cap on the `orderBy` string), so Swagger advertises exactly what the engine
451
692
  enforces. Both are exported as `MAX_CONDITIONS` and `MAX_ORDER_BY_PARTS`, and both are checked
452
693
  **in the engine**, which is what covers `sqlApi.search()` — no schema validates a programmatic
453
- caller. See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--request-limits-condition-arity-and-tenant-scope-inside-subqueries).
694
+ caller. See [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--request-limits-condition-arity-and-tenant-scope-inside-subqueries).
454
695
 
455
696
  - **BREAKING: `paginator` is validated at runtime.** `page` and `itemsPerPage` are rendered
456
697
  straight into `LIMIT`/`OFFSET`, and `Paginator` is a compile-time type only: nothing stopped a
@@ -526,7 +767,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
526
767
  and aggregations, which have always answered 400. The check lives in the engine, so it
527
768
  covers `sqlApi.search()` as well as the HTTP routes. `undefined` values still mean "filter
528
769
  not supplied" and are ignored; an explicit `null` still filters by `IS NULL`. See
529
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--unknown-filter-keys-are-rejected).
770
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--unknown-filter-keys-are-rejected).
530
771
 
531
772
  - **`joinLeft.<alias>.filters` no longer advertises the parent's `extraFilters`.** They were
532
773
  present in the generated body schema and in Swagger, but `buildLeftJoinClauses` never runs
@@ -594,7 +835,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
594
835
  bulk upsert are unaffected — they already handled every PK column. If your composite table's
595
836
  first PK column happens to be unique, these endpoints previously worked for you and are now
596
837
  gone — see
597
- [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--by-single-id-operations-disabled-for-composite-primary-keys)
838
+ [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--by-single-id-operations-disabled-for-composite-primary-keys)
598
839
  for the migration paths.
599
840
 
600
841
  ### Fixed
@@ -729,7 +970,7 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
729
970
  error. Computed fields that declare **no** bound values are unaffected — the majority case
730
971
  (JSON extraction, `CONCAT`, `dateTrunc`, arithmetic) needs no change, and a literal `?` such
731
972
  as the PostgreSQL jsonb operator keeps working.
732
- See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--computed-field-placeholders-use--markers).
973
+ See [docs/upgrading/0.x.md](./docs/upgrading/0.x.md#breaking-change--computed-field-placeholders-use--markers).
733
974
 
734
975
  ### Added
735
976
 
@@ -780,11 +1021,13 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
780
1021
  ## [0.1.3] and earlier
781
1022
 
782
1023
  Released before this changelog was kept. See the git history for details: notable entries are
783
- the join API redesign (documented in [BREAKING_CHANGES.md](./BREAKING_CHANGES.md)), composite
1024
+ the join API redesign (documented in [docs/upgrading/0.x.md](./docs/upgrading/0.x.md)), composite
784
1025
  primary key support in updates, transactional insert/update with secondaries, the hook matrix,
785
1026
  and bulk operations.
786
1027
 
787
- [Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.5.0...HEAD
1028
+ [Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v1.0.0...HEAD
1029
+ [1.0.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.5.1...v1.0.0
1030
+ [0.5.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.5.1
788
1031
  [0.5.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.5.0
789
1032
  [0.4.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.1
790
1033
  [0.4.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.0