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.
- package/AGENTS.md +5 -5
- package/AGENTS_BACKEND.md +166 -130
- package/AGENTS_FRONTEND.md +60 -38
- package/BREAKING_CHANGES.md +9 -893
- package/CHANGELOG.md +258 -15
- package/README.md +71 -45
- package/dist/bin/generate-schema.js +12 -12
- package/dist/bin/generate-tables.js +1 -2
- package/dist/bin/utils.d.ts +2 -6
- package/dist/bin/utils.d.ts.map +1 -1
- package/dist/bin/utils.js +13 -33
- package/dist/index.d.ts +13 -33
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -37
- package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
- package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
- package/dist/lib/adapters/pg-adapter.d.ts +5 -2
- package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
- package/dist/lib/agent/manifest.d.ts +27 -10
- package/dist/lib/agent/manifest.d.ts.map +1 -1
- package/dist/lib/agent/manifest.js +43 -26
- package/dist/lib/agent/tool-schemas.d.ts +5 -4
- package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
- package/dist/lib/agent/tool-schemas.js +5 -5
- package/dist/lib/cli/config.d.ts +37 -2
- package/dist/lib/cli/config.d.ts.map +1 -1
- package/dist/lib/cli/config.js +106 -16
- package/dist/lib/cli/mysql-introspect.d.ts +6 -1
- package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
- package/dist/lib/cli/mysql-introspect.js +15 -15
- package/dist/lib/cli/pg-introspect.d.ts +0 -1
- package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
- package/dist/lib/cli/pg-introspect.js +2 -13
- package/dist/lib/cli/tables-codegen.d.ts +0 -4
- package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
- package/dist/lib/cli/tables-codegen.js +24 -87
- package/dist/lib/db.d.ts +42 -17
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +114 -40
- package/dist/lib/dialect.d.ts +5 -0
- package/dist/lib/dialect.d.ts.map +1 -1
- package/dist/lib/dialect.js +3 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-delete.js +66 -30
- package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
- package/dist/lib/engine/read-hooks.d.ts +3 -3
- package/dist/lib/engine/read-hooks.d.ts.map +1 -1
- package/dist/lib/engine/read-hooks.js +3 -3
- package/dist/lib/engine/rest/delete.d.ts.map +1 -1
- package/dist/lib/engine/rest/delete.js +12 -18
- package/dist/lib/engine/rest/get.js +8 -8
- package/dist/lib/engine/rest/insert.d.ts.map +1 -1
- package/dist/lib/engine/rest/insert.js +31 -18
- package/dist/lib/engine/rest/update.d.ts.map +1 -1
- package/dist/lib/engine/rest/update.js +34 -17
- package/dist/lib/engine/search/aggregations.d.ts +3 -3
- package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
- package/dist/lib/engine/search/aggregations.js +20 -16
- package/dist/lib/engine/search/conditions.d.ts +9 -5
- package/dist/lib/engine/search/conditions.d.ts.map +1 -1
- package/dist/lib/engine/search/conditions.js +31 -20
- package/dist/lib/engine/search/fields.d.ts +44 -11
- package/dist/lib/engine/search/fields.d.ts.map +1 -1
- package/dist/lib/engine/search/fields.js +94 -28
- package/dist/lib/engine/search/join-families.d.ts +7 -7
- package/dist/lib/engine/search/join-families.d.ts.map +1 -1
- package/dist/lib/engine/search/join-families.js +84 -75
- package/dist/lib/engine/search/joins.d.ts +15 -7
- package/dist/lib/engine/search/joins.d.ts.map +1 -1
- package/dist/lib/engine/search/joins.js +23 -13
- package/dist/lib/engine/search/order-by.d.ts +11 -12
- package/dist/lib/engine/search/order-by.d.ts.map +1 -1
- package/dist/lib/engine/search/order-by.js +24 -28
- package/dist/lib/engine/search/search.d.ts.map +1 -1
- package/dist/lib/engine/search/search.js +111 -62
- package/dist/lib/engine/validate.d.ts +21 -3
- package/dist/lib/engine/validate.d.ts.map +1 -1
- package/dist/lib/engine/validate.js +106 -16
- package/dist/lib/engine/write-helpers.d.ts +69 -16
- package/dist/lib/engine/write-helpers.d.ts.map +1 -1
- package/dist/lib/engine/write-helpers.js +257 -105
- package/dist/lib/errors.d.ts +42 -10
- package/dist/lib/errors.d.ts.map +1 -1
- package/dist/lib/errors.js +69 -15
- package/dist/lib/nullable.d.ts +3 -2
- package/dist/lib/nullable.d.ts.map +1 -1
- package/dist/lib/nullable.js +14 -5
- package/dist/lib/read-access.d.ts +33 -21
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +42 -23
- package/dist/lib/schema/bulk-delete.d.ts +13 -7
- package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
- package/dist/lib/schema/bulk-delete.js +18 -8
- package/dist/lib/schema/bulk-upsert.d.ts +3 -3
- package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/schema/bulk-upsert.js +9 -14
- package/dist/lib/schema/get.d.ts +1 -1
- package/dist/lib/schema/get.d.ts.map +1 -1
- package/dist/lib/schema/get.js +2 -2
- package/dist/lib/schema/helpers.d.ts +41 -23
- package/dist/lib/schema/helpers.d.ts.map +1 -1
- package/dist/lib/schema/helpers.js +80 -33
- package/dist/lib/schema/insert.d.ts +1 -1
- package/dist/lib/schema/insert.d.ts.map +1 -1
- package/dist/lib/schema/insert.js +12 -20
- package/dist/lib/schema/search.d.ts +2 -13
- package/dist/lib/schema/search.d.ts.map +1 -1
- package/dist/lib/schema/search.js +64 -61
- package/dist/lib/schema/update.d.ts +1 -1
- package/dist/lib/schema/update.d.ts.map +1 -1
- package/dist/lib/schema/update.js +6 -13
- package/dist/lib/sql-api.d.ts +47 -25
- package/dist/lib/sql-api.d.ts.map +1 -1
- package/dist/lib/sql-api.js +70 -27
- package/dist/lib/table-helpers.d.ts +92 -14
- package/dist/lib/table-helpers.d.ts.map +1 -1
- package/dist/lib/table-helpers.js +367 -128
- package/dist/lib/tenant.d.ts +16 -22
- package/dist/lib/tenant.d.ts.map +1 -1
- package/dist/lib/tenant.js +38 -54
- package/dist/lib/write-access.d.ts +15 -9
- package/dist/lib/write-access.d.ts.map +1 -1
- package/dist/lib/write-access.js +12 -4
- package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
- package/dist/routes/auto/agent-manifest.routes.js +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-delete.routes.js +1 -7
- package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-upsert.routes.js +2 -2
- package/dist/routes/auto/delete.routes.d.ts +2 -2
- package/dist/routes/auto/delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/delete.routes.js +8 -10
- package/dist/routes/auto/get.routes.d.ts +2 -2
- package/dist/routes/auto/get.routes.d.ts.map +1 -1
- package/dist/routes/auto/get.routes.js +5 -5
- package/dist/routes/auto/insert.routes.d.ts +2 -2
- package/dist/routes/auto/insert.routes.d.ts.map +1 -1
- package/dist/routes/auto/insert.routes.js +1 -7
- package/dist/routes/auto/plugin.d.ts +6 -0
- package/dist/routes/auto/plugin.d.ts.map +1 -1
- package/dist/routes/auto/plugin.js +60 -36
- package/dist/routes/auto/route-helpers.d.ts +26 -12
- package/dist/routes/auto/route-helpers.d.ts.map +1 -1
- package/dist/routes/auto/route-helpers.js +50 -19
- package/dist/routes/auto/search.routes.d.ts +2 -2
- package/dist/routes/auto/search.routes.d.ts.map +1 -1
- package/dist/routes/auto/search.routes.js +36 -24
- package/dist/routes/auto/update.routes.d.ts +2 -2
- package/dist/routes/auto/update.routes.d.ts.map +1 -1
- package/dist/routes/auto/update.routes.js +1 -8
- package/dist/routes/sql-api-decorator.d.ts +30 -12
- package/dist/routes/sql-api-decorator.d.ts.map +1 -1
- package/dist/routes/sql-api-decorator.js +44 -27
- package/dist/types/cli.d.ts +17 -6
- package/dist/types/cli.d.ts.map +1 -1
- package/dist/types/computed.d.ts +1 -1
- package/dist/types/computed.d.ts.map +1 -1
- package/dist/types/conditions.d.ts +3 -1
- package/dist/types/conditions.d.ts.map +1 -1
- package/dist/types/db.d.ts +44 -4
- package/dist/types/db.d.ts.map +1 -1
- package/dist/types/dml.d.ts +26 -17
- package/dist/types/dml.d.ts.map +1 -1
- package/dist/types/hooks.d.ts +62 -0
- package/dist/types/hooks.d.ts.map +1 -0
- package/dist/types/hooks.js +1 -0
- package/dist/types/join.d.ts +25 -8
- package/dist/types/join.d.ts.map +1 -1
- package/dist/types/plugin.d.ts +58 -19
- package/dist/types/plugin.d.ts.map +1 -1
- package/dist/types/plugin.js +2 -0
- package/dist/types/request.d.ts +2 -2
- package/dist/types/schema.d.ts +3 -3
- package/dist/types/schema.d.ts.map +1 -1
- package/dist/types/search.d.ts +28 -13
- package/dist/types/search.d.ts.map +1 -1
- package/dist/types/search.js +2 -1
- package/dist/types/table.d.ts +109 -94
- package/dist/types/table.d.ts.map +1 -1
- package/dist/types/table.js +7 -2
- package/dist/types/tenant.d.ts +28 -2
- package/dist/types/tenant.d.ts.map +1 -1
- package/dist/types/tenant.js +7 -1
- package/dist/types/validation.d.ts +69 -13
- package/dist/types/validation.d.ts.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/docs/GLOSSARY.md +11 -5
- package/docs/adr/0003-bulk-not-transactional.md +2 -1
- package/docs/adr/0006-raw-db-errors.md +2 -1
- package/docs/adr/0013-sanitized-db-errors.md +2 -1
- package/docs/adr/0014-what-follows-a-write-join.md +1 -1
- package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
- package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
- package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
- package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
- package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
- package/docs/adr/0027-the-1-0-contract.md +74 -0
- package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
- package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
- package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
- package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
- package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
- package/docs/adr/README.md +12 -1
- package/docs/upgrading/0.x.md +906 -0
- package/docs/upgrading/1.0.md +628 -0
- package/package.json +4 -5
package/dist/types.d.ts
CHANGED
|
@@ -7,6 +7,7 @@ export * from './types/tenant.js';
|
|
|
7
7
|
export * from './types/computed.js';
|
|
8
8
|
export * from './types/conditions.js';
|
|
9
9
|
export * from './types/join.js';
|
|
10
|
+
export * from './types/hooks.js';
|
|
10
11
|
export * from './types/validation.js';
|
|
11
12
|
export * from './types/table.js';
|
|
12
13
|
export * from './types/plugin.js';
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}
|
package/dist/types.js
CHANGED
|
@@ -6,6 +6,7 @@ export * from './types/tenant.js';
|
|
|
6
6
|
export * from './types/computed.js';
|
|
7
7
|
export * from './types/conditions.js';
|
|
8
8
|
export * from './types/join.js';
|
|
9
|
+
export * from './types/hooks.js';
|
|
9
10
|
export * from './types/validation.js';
|
|
10
11
|
export * from './types/table.js';
|
|
11
12
|
export * from './types/plugin.js';
|
package/docs/GLOSSARY.md
CHANGED
|
@@ -5,17 +5,23 @@ existing concept makes search fail and the concept get built twice.
|
|
|
5
5
|
|
|
6
6
|
| Term | Meaning |
|
|
7
7
|
|---|---|
|
|
8
|
-
| Table config | `defineTable()` result describing one table's routes, guards and joins
|
|
8
|
+
| Table config | `defineTable()` result describing one table's routes, guards and joins; type `TableConfig`. (not: model, entity; `ITable` before 1.0) |
|
|
9
9
|
| Schema | TypeBox definition of a table's columns, generated from the DB. (not: model) |
|
|
10
10
|
| Relation | `buildRelation()` link between two schemas, identified by an alias. (not: association) |
|
|
11
11
|
| Alias | Request/response key naming one relation; defaults to the joined table name. |
|
|
12
|
+
| Target | The `dbTables` key whose table config governs a relation's joined table; required when that table sits under several keys. (not: joinConf, childConf in config) |
|
|
12
13
|
| `joinMustExist` | Child→main 1:N filter via EXISTS; never returns child rows. |
|
|
13
14
|
| `joinMultiple` | Child→main 1:N side query; child rows land in `result.joinMultiple.<alias>`. |
|
|
14
|
-
| `joinGroup` | Child→main 1:N aggregations in `result.joinGroup.<alias
|
|
15
|
+
| `joinGroup` | Child→main 1:N aggregations: `by` and the functions in the request, `result.joinGroup.<alias>.rows` (`{ by?, <fn>: { <field> } }`) in the response. |
|
|
15
16
|
| `joinLeft` | Parent→main N:1 real LEFT JOIN; needs `unique: true` on the relation. |
|
|
16
|
-
|
|
|
17
|
-
|
|
|
17
|
+
| Main | The principal row of a write request: `main` in the HTTP body, in `sqlApi.insert`/`update` and in `validate`. (not: record, in a request) |
|
|
18
|
+
| Record | One row a hook is writing: `record` in `beforeInsert`/`beforeUpdate`/`afterInsert`/`afterUpdate`. A main row or a secondary of another table alike. (not: main, in a hook) |
|
|
19
|
+
| Secondaries | Child rows written in the same request as the main row; `secondaries` in a write response and in `afterInsert`/`afterUpdate`. (not: nested, children) |
|
|
20
|
+
| Deletions | Child rows removed in the same request as the main row; `deletions` in a write response and in `afterUpdate`. |
|
|
21
|
+
| Parent | The main row a child row is written with, as the child table's `validate` sees it: `parent: { alias, main }`; absent on the table's own routes. (not: host, owner, in a hook) |
|
|
22
|
+
| `upsert` / `delete` / `replace` | The request sections naming child rows, by write alias: write these, delete these, these are all of them (the others are deleted). (not: secondaries, deletions — those are the outcome) |
|
|
18
23
|
| Computed field | Server-side derived value resolved during search. (not: virtual, derived) |
|
|
24
|
+
| Hook context | The single object every hook and validator receives: `db`, `req` (may be undefined) and the operation's data under the names above (`record`, `secondaries`, `deletions`, `rows`, `id`, `ids`, `main`, `upsert`, `replace`, `parent`, `items`). (not: positional args) |
|
|
19
25
|
| Extra filter | Non-column search filter declared per table. (not: custom filter) |
|
|
20
26
|
| Extended condition | Consumer-supplied SQL fragment merged into a search WHERE. |
|
|
21
27
|
| Dotted notation | `orderBy`/condition key counted in parts: 1-part `field`, 2-part `alias.field`, 3-part `alias.fn.field`. (not: parti) |
|
|
@@ -24,7 +30,7 @@ existing concept makes search fail and the concept get built twice.
|
|
|
24
30
|
| Anchor | The owner column an `anyOf` write names to tie a new row to the caller. |
|
|
25
31
|
| Engine | Dialect-agnostic function performing one operation. (not: service, handler) |
|
|
26
32
|
| Route | Fastify plugin exposing an engine over HTTP. (not: controller) |
|
|
27
|
-
| Dialect | Per-DB SQL differences (`postgres` \| `mysql`). |
|
|
33
|
+
| Dialect | Per-DB SQL differences (`postgres` \| `mysql` \| `mariadb`). |
|
|
28
34
|
| QueryClient | Connection wrapper the engines run SQL through. (not: db, connection) |
|
|
29
35
|
| Paginator | Request object carrying page and items-per-page. (not: pagination, pager) |
|
|
30
36
|
| Manifest | Runtime description of a deployment's tables, for agent clients. |
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# 0003. Bulk operations are not transactional
|
|
2
2
|
|
|
3
|
-
- **Status**: accepted
|
|
3
|
+
- **Status**: accepted; the context's "degrading gracefully" sentence superseded by
|
|
4
|
+
[0023](./0023-a-write-runs-in-a-transaction-or-not-at-all.md)
|
|
4
5
|
- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
|
|
5
6
|
|
|
6
7
|
## Context
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
|
|
2
2
|
|
|
3
3
|
- **Status**: accepted on the mapping; message exposure narrowed by
|
|
4
|
-
[0013](./0013-sanitized-db-errors.md)
|
|
4
|
+
[0013](./0013-sanitized-db-errors.md); the consumer's remedy narrowed by
|
|
5
|
+
[0024](./0024-the-consumer-maps-driver-codes-through-dberrors.md)
|
|
5
6
|
- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
|
|
6
7
|
|
|
7
8
|
## Context
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# 0013. Database error messages are sanitized on the wire by default
|
|
2
2
|
|
|
3
|
-
- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md)
|
|
3
|
+
- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md); the consumer's remedy
|
|
4
|
+
narrowed by [0024](./0024-the-consumer-maps-driver-codes-through-dberrors.md)
|
|
4
5
|
- **Date**: 2026-08-05
|
|
5
6
|
|
|
6
7
|
## Context
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# 0022. Stay on 0.x while every consumer is first-party — a breaking change bumps the minor, never the patch
|
|
2
|
+
|
|
3
|
+
- **Status**: superseded by [0027](./0027-the-1-0-contract.md)
|
|
4
|
+
- **Date**: 2026-11-08
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
The TypeBox 1.x migration raised the question of releasing it as 1.0.0 instead of 0.6.0,
|
|
9
|
+
lining the package up with its dependency's own 1.0.
|
|
10
|
+
|
|
11
|
+
The history argues both ways. Twelve breaking changes landed between 0.1.3 and 0.6.0, at
|
|
12
|
+
least one in every release since 0.2.0, on a two-to-four-week cadence. Grouped by kind:
|
|
13
|
+
|
|
14
|
+
| Kind | Breaking changes | Last one |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| API shape (names, request/response, URLs) | join redesign, route URL = `DbTables` key | 0.3.0 |
|
|
17
|
+
| Stricter defaults, security | `?` placeholders, composite PKs, unknown filter keys, request limits, tenant per request, `beforeInsert` on secondaries, verified upsert key | 0.4.0 |
|
|
18
|
+
| Correctness | NULL `min`/`max`/`avg` without children | 0.4.1 |
|
|
19
|
+
| Platform | Node.js 22, TypeBox 1.x | 0.6.0 |
|
|
20
|
+
|
|
21
|
+
The shape of the API has not moved since 0.3.0; its behaviour still tightens, mostly on
|
|
22
|
+
tenant isolation and mass assignment, where each new finding is likely to break someone.
|
|
23
|
+
Platform floors (Node.js, TypeBox, Fastify) will keep moving whatever the version number.
|
|
24
|
+
|
|
25
|
+
Every consumer today is a project of the maintainer, some of them applications run for
|
|
26
|
+
clients in production. Nobody outside picks the package by reading its version, and every
|
|
27
|
+
upgrade across a breaking change is done by the same person who wrote the change.
|
|
28
|
+
|
|
29
|
+
One release did not hold the line that makes `^0.x` ranges safe: **0.4.1 shipped a breaking
|
|
30
|
+
change in a patch** (the NULL aggregates). An `npm update` on a client application pinned to
|
|
31
|
+
`^0.4.0` would have taken it without anyone choosing to.
|
|
32
|
+
|
|
33
|
+
## Decision
|
|
34
|
+
|
|
35
|
+
**1. The package stays on 0.x** while every consumer is first-party.
|
|
36
|
+
|
|
37
|
+
**2. A release with a breaking change bumps the minor; a release without one bumps the
|
|
38
|
+
patch.** No exception for "small" breaks, correctness fixes that change results, or security
|
|
39
|
+
tightenings: if it needs a `BREAKING_CHANGES.md` entry, it is a minor. This makes a `^0.N.0`
|
|
40
|
+
range mean exactly "no breaking change", which is what an application in production needs
|
|
41
|
+
from `npm update`.
|
|
42
|
+
|
|
43
|
+
**3. A line still in use gets its security fixes as patches.** When a fix must reach an
|
|
44
|
+
application that has not moved to the newest minor, it is released as `0.N.x` from a
|
|
45
|
+
`release/0.N` branch cut at the `v0.N.*` tag, instead of forcing the upgrade.
|
|
46
|
+
|
|
47
|
+
**4. 1.0.0 is released when either of these happens first:**
|
|
48
|
+
|
|
49
|
+
- a consumer the maintainer does not control appears, or the package is promoted publicly;
|
|
50
|
+
- three consecutive releases, spanning at least two months, add no entry to
|
|
51
|
+
`BREAKING_CHANGES.md`.
|
|
52
|
+
|
|
53
|
+
**5. 1.0.0 ships with its contract written down**, in an ADR that supersedes this one:
|
|
54
|
+
|
|
55
|
+
- what is public: the exports of `src/index.ts`, the HTTP request and response shapes, the
|
|
56
|
+
manifest format; everything else is internal;
|
|
57
|
+
- a deprecation policy: a change to the API shape is announced (deprecated and warned about)
|
|
58
|
+
at least one major before it is removed;
|
|
59
|
+
- security tightenings ship as a major with a migration guide, without waiting for a
|
|
60
|
+
deprecation cycle;
|
|
61
|
+
- platform floors (Node.js, TypeBox, Fastify) move only in a major.
|
|
62
|
+
|
|
63
|
+
## Alternatives considered
|
|
64
|
+
|
|
65
|
+
- **1.0.0 now, with the TypeBox migration.** The version would promise stability nobody is
|
|
66
|
+
there to rely on, and at the current pace of breaking changes the major would climb every
|
|
67
|
+
few weeks until it stopped carrying information.
|
|
68
|
+
- **1.0.0 now, with frequent majors as Fastify does.** Viable mechanically, since every break
|
|
69
|
+
already has a migration guide. It buys nothing while the maintainer upgrades every consumer
|
|
70
|
+
personally, and it commits early to a deprecation discipline designed for consumers who do
|
|
71
|
+
not exist yet.
|
|
72
|
+
- **Stay on 0.x with no exit criterion.** The 0.x signal would outlive the reason for it; when
|
|
73
|
+
the first external user arrives, the decision would be taken under pressure instead of by a
|
|
74
|
+
rule written in advance.
|
|
75
|
+
- **Keep allowing breaking changes in patches when they are fixes.** That is what 0.4.1 did.
|
|
76
|
+
It makes every `npm update` a potential break for client applications, which is the one
|
|
77
|
+
guarantee they need.
|
|
78
|
+
|
|
79
|
+
## Consequences
|
|
80
|
+
|
|
81
|
+
- Every breaking change still costs a manual bump in each project (`^0.6.0` → `^0.7.0`) and a
|
|
82
|
+
read of `BREAKING_CHANGES.md`. Accepted: that review is the point.
|
|
83
|
+
- A fix that changes results, however small, waits for the next minor or becomes one. The
|
|
84
|
+
release cadence makes that cheap.
|
|
85
|
+
- Client applications should commit their lockfile and use a `^0.N.0` range (or an exact
|
|
86
|
+
version): with rule 2 both mean "no surprise breaks".
|
|
87
|
+
- The package keeps the 0.x signal, which discourages adoption. Accepted while adoption is
|
|
88
|
+
not a goal; rule 4 says when it becomes one.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# 0023. A write runs in a transaction or not at all — `withTransaction` requires `connect()`
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Date**: 2026-11-09
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
A single insert or update is several statements: the main row, its secondaries, its
|
|
9
|
+
deletions, and the `afterInsert`/`afterUpdate` hook, which the docs promise can roll
|
|
10
|
+
everything back by throwing. They run inside `QueryClient.withTransaction`, which needs a
|
|
11
|
+
dedicated connection and therefore a `Queryable` with `connect()`. The two built-in adapters
|
|
12
|
+
provide it from a pool.
|
|
13
|
+
|
|
14
|
+
`connect()` is optional in the `Queryable` type, so that a custom adapter — a single query
|
|
15
|
+
function over some driver — keeps working. `withTransaction` honoured that by *degrading*:
|
|
16
|
+
without `connect()` it ran its callback directly on the pooled client, with no BEGIN and no
|
|
17
|
+
ROLLBACK. The write pipeline did not know. A secondary failing after the main row was
|
|
18
|
+
inserted left the main row behind; an `afterUpdate` throwing to "roll back" rolled back
|
|
19
|
+
nothing. Every part of the API still answered as if the guarantee held, and the one hint was a
|
|
20
|
+
sentence in a doc comment. ADR 0003 even cited the degrade as graceful.
|
|
21
|
+
|
|
22
|
+
## Decision
|
|
23
|
+
|
|
24
|
+
**`withTransaction` runs its callback inside a transaction or throws.** Without `connect()`
|
|
25
|
+
on the `Queryable` it fails before running anything, with a message naming the fix. The only
|
|
26
|
+
exception is the client it hands its own callback: that one wraps the transaction's
|
|
27
|
+
connection, has no `connect()` either, and an inner `withTransaction` joins the outer one.
|
|
28
|
+
|
|
29
|
+
`connect()` stays optional in the type: a read-only client — a custom adapter behind
|
|
30
|
+
`searchRoutes` and `getRoutes` only — needs no transactions and must not be forced to fake
|
|
31
|
+
one. Reads never call `withTransaction`. The plugin logs a warning once when the client it was
|
|
32
|
+
given cannot do transactions, so the misconfiguration is seen before the first write.
|
|
33
|
+
|
|
34
|
+
## Alternatives considered
|
|
35
|
+
|
|
36
|
+
- **Keep degrading, document it louder** — rejected: a guarantee the consumer cannot observe
|
|
37
|
+
being dropped is not a guarantee. `afterUpdate` is documented as "throw = rollback"; a
|
|
38
|
+
configuration that silently makes that false is a correctness bug, not a compatibility
|
|
39
|
+
feature.
|
|
40
|
+
- **Degrade only when the write is a single statement** (no secondaries, deletions or
|
|
41
|
+
after-hooks) — rejected: it is correct, but it makes "does this adapter work?" depend on
|
|
42
|
+
the request body. A deployment would pass every test with plain rows and fail on the first
|
|
43
|
+
real one. One rule is easier to hold: a write needs transactions, full stop.
|
|
44
|
+
- **Fail at startup when the client has no `connect()`** — rejected as the only mechanism: a
|
|
45
|
+
read-only surface over a custom adapter is a supported setup, and refusing to start would
|
|
46
|
+
outlaw it. Kept as a warning, because in every other setup it is a misconfiguration worth
|
|
47
|
+
seeing early.
|
|
48
|
+
- **Synthesise `connect()` from a single connection** — rejected: a driver client that is
|
|
49
|
+
not a pool cannot hand out a dedicated connection; faking one by running BEGIN on the shared
|
|
50
|
+
client would serialise every request of the process through one transaction.
|
|
51
|
+
|
|
52
|
+
## Consequences
|
|
53
|
+
|
|
54
|
+
- A custom `Queryable` without `connect()` can serve reads, and gets a 500 with an explicit
|
|
55
|
+
message on the first insert or update (and a startup warning). Adding `connect()` to the
|
|
56
|
+
adapter is the migration; the built-in adapters are unaffected.
|
|
57
|
+
- The sentence in ADR 0003's context describing the degrade as graceful is superseded by
|
|
58
|
+
this decision; ADR 0003's own decision — bulk operations stay non-transactional — stands.
|
|
59
|
+
- Test doubles for the database must offer `connect()` to exercise writes, as the real
|
|
60
|
+
adapters do; the shared harness mock does.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# 0024. The consumer maps driver error codes through `dbErrors` — the plugin ships no mapping
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md) and
|
|
4
|
+
[0013](./0013-sanitized-db-errors.md)
|
|
5
|
+
- **Date**: 2026-11-15
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
[ADR 0006](./0006-raw-db-errors.md) kept SQLSTATE→HTTP mapping out of the plugin and left it
|
|
10
|
+
to the consumer: "set a Fastify `setErrorHandler` — one place, their policy, their status
|
|
11
|
+
codes". [ADR 0013](./0013-sanitized-db-errors.md) kept that remedy, promising the original
|
|
12
|
+
error as the `cause` of "the error the consumer's `setErrorHandler` receives, so
|
|
13
|
+
unique-violation → `409` remains implementable".
|
|
14
|
+
|
|
15
|
+
With the main plugin it is not implementable. The plugin renders its envelope from an error
|
|
16
|
+
handler installed in the routes' child scope, and Fastify hands an error to the nearest
|
|
17
|
+
handler only: one the consumer sets on the application is never called for an auto route.
|
|
18
|
+
0013's own Context notes this ("a consumer handler registered on the parent scope never sees
|
|
19
|
+
these errors") and then relies on the opposite. The documented `err.cause.code === '23505'`
|
|
20
|
+
recipe silently did nothing, and a duplicate email could only ever be a `500`.
|
|
21
|
+
|
|
22
|
+
What 0006 rejected still holds: a mapping the plugin ships would be dialect-specific, partial
|
|
23
|
+
by nature — codes depend on the database and its version — and would encode product
|
|
24
|
+
decisions (is a foreign-key violation a `409`, a `422`, a `400`?) that are not the library's.
|
|
25
|
+
|
|
26
|
+
## Decision
|
|
27
|
+
|
|
28
|
+
The consumer declares the driver codes it cares about in a plugin option:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
dbErrors: { '23505': { status: 409, code: 'duplicate' }, 'ER_DUP_ENTRY': { status: 409, code: 'duplicate' } }
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
- The key is the driver's `err.code` exactly as it arrives. The plugin interprets nothing and
|
|
35
|
+
ships no entry.
|
|
36
|
+
- The value is `{ status, code }`: a status between 400 and 599 and a non-empty code of the
|
|
37
|
+
consumer's choosing. Anything else fails registration.
|
|
38
|
+
- A mapped error is answered in the plugin's envelope: the status, its reason phrase as
|
|
39
|
+
`message`, `requestId`, and `fields: [{ path: '', code }]` whatever the status. The client
|
|
40
|
+
translates the code; the API carries no prose. This widens the envelope rule "`fields` on
|
|
41
|
+
every 400" to "and on any answer whose cause carries a code", so machine codes have one
|
|
42
|
+
place.
|
|
43
|
+
- No driver detail reaches the client (0013 unchanged). `exposeDebugInfo` stays additive.
|
|
44
|
+
- An unmapped error is the sanitized `500`, as before. The driver error is logged either way:
|
|
45
|
+
at `error` when unmapped, at `info` when mapped, since a mapped code is an expected outcome.
|
|
46
|
+
- The mapping sits in the same choke point as the sanitizer, so a route plugin registered
|
|
47
|
+
standalone hands the mapped error, `cause` attached, to the consumer's own handler.
|
|
48
|
+
|
|
49
|
+
## Alternatives considered
|
|
50
|
+
|
|
51
|
+
- **Rethrow unmapped errors to the parent scope's handler** — rejected: the consumer handler
|
|
52
|
+
would see them, but an application without one would answer with Fastify's default body,
|
|
53
|
+
outside the envelope and without `requestId`. The response shape would depend on code the
|
|
54
|
+
plugin cannot see.
|
|
55
|
+
- **A function, `mapError(err, req)`** — rejected: the need is a lookup on a handful of codes,
|
|
56
|
+
and a function makes the policy invisible to anyone reading the registration. A predicate
|
|
57
|
+
the lookup cannot express belongs in a custom route.
|
|
58
|
+
- **A consumer-written `message`** — rejected: prose in the API cannot be translated, and a
|
|
59
|
+
client would have to parse it. The client gets a code and owns the wording.
|
|
60
|
+
- **A bare status, `{ '23505': 409 }`** — rejected: the client could not tell two mapped
|
|
61
|
+
errors with the same status apart, and a code defaulting to the driver's would make the
|
|
62
|
+
client's translations depend on the database.
|
|
63
|
+
- **The code at the top level of the envelope** — rejected: `fields[].code` is already where a
|
|
64
|
+
client reads machine codes. A second location would make every client check two places.
|
|
65
|
+
- **Shipping default mappings for common codes** — rejected for the reasons in 0006.
|
|
66
|
+
|
|
67
|
+
## Consequences
|
|
68
|
+
|
|
69
|
+
- Unique violation → `409` is one line of configuration, per database: `'23505'` on
|
|
70
|
+
PostgreSQL, `'ER_DUP_ENTRY'` on MySQL and MariaDB. Mapping both to the same code keeps the
|
|
71
|
+
client independent of the database.
|
|
72
|
+
- `fields` may now appear on a status other than 400, only on a `dbErrors` answer.
|
|
73
|
+
- The driver code alone cannot name the column (`23505` covers every unique constraint), so
|
|
74
|
+
`path` is always `''`. A field-level message needs `validate`, which knows the field.
|
|
75
|
+
- `sqlApi.*` is not affected: application code calling it receives the driver error as is and
|
|
76
|
+
decides there.
|
|
77
|
+
- The `setErrorHandler` recipe in AGENTS_BACKEND.md is replaced by `dbErrors`. It still
|
|
78
|
+
applies to route plugins registered standalone, which leave rendering to the consumer.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# 0025. `validateBulk` replaces `validate` in a bulk upsert — one call for the batch, not one per item
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Date**: 2026-11-16
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
A table can declare two validators. `validate` checks one write: `{ main, secondaries }` of an
|
|
9
|
+
insert or an update. `validateBulk` checks a bulk upsert as a whole: `{ items }`, every item at
|
|
10
|
+
once, with paths starting at `items.<i>`.
|
|
11
|
+
|
|
12
|
+
Without `validateBulk`, a bulk upsert runs `validate` once per item. With it, the bulk upsert
|
|
13
|
+
calls `validateBulk` once, and `validate` does not run for any of its items. A reader who
|
|
14
|
+
declares both, and expects both to run, takes the second behavior for a bug: a rule written
|
|
15
|
+
only in `validate` is not enforced on `PUT /bulk/:table`.
|
|
16
|
+
|
|
17
|
+
The rules worth a validator are mostly the ones that ask the database: a code already taken, a
|
|
18
|
+
period overlapping an existing one, a parent in the wrong state. Run per item, each costs one
|
|
19
|
+
query per item: a thousand-item batch becomes a thousand round trips before anything is
|
|
20
|
+
written. Run over the batch, the same rule is one query (`WHERE code IN (…)`), and it can also
|
|
21
|
+
see what a per-item check cannot: two items of the same batch colliding with each other.
|
|
22
|
+
|
|
23
|
+
## Decision
|
|
24
|
+
|
|
25
|
+
**When a table declares `validateBulk`, a bulk upsert calls it once with every item, and does
|
|
26
|
+
not call `validate`.** When it does not, `validate` runs once per item, as for single writes.
|
|
27
|
+
|
|
28
|
+
`validateBulk` is the bulk counterpart of `validate`, not an addition to it: a rule that must
|
|
29
|
+
hold in bulk is written there too, in its batch form.
|
|
30
|
+
|
|
31
|
+
## Alternatives considered
|
|
32
|
+
|
|
33
|
+
- **Run both: `validateBulk` once, then `validate` per item.** Brings back the N+1 queries the
|
|
34
|
+
batch validator exists to avoid, and reports the same problem twice when a rule is in both.
|
|
35
|
+
- **Warn at `defineTable` when both are declared.** Declaring both is the normal case — one for
|
|
36
|
+
single writes, one for batches — so the warning would fire on every correct config.
|
|
37
|
+
- **Derive one from the other.** A batch rule is not a loop over the per-item rule (it sees
|
|
38
|
+
collisions inside the batch, it queries once); a per-item rule cannot be lifted to a batch
|
|
39
|
+
without knowing what it queries.
|
|
40
|
+
|
|
41
|
+
## Consequences
|
|
42
|
+
|
|
43
|
+
- A rule enforced on single writes but missing from `validateBulk` is not enforced on bulk
|
|
44
|
+
upserts. AGENTS_BACKEND.md says so next to the declaration of `validateBulk`.
|
|
45
|
+
- A table without `validateBulk` keeps the simple behavior — `validate` per item — and its cost.
|
|
46
|
+
- Both return the same `{ path, code }` objects, so a client handles a bulk 400 as any other.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# 0026. An update carries its primary key in `main` — `PUT /rest/:table` has no `:id`
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Date**: 2026-11-16
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
`GET /rest/:table/:id` and `DELETE /rest/:table/:id` name the row in the path. `PUT
|
|
9
|
+
/rest/:table` does not: the row is named by the primary key inside `main`, in the body. Read
|
|
10
|
+
next to each other, the routes look inconsistent, and the obvious fix is `PUT
|
|
11
|
+
/rest/:table/:id`.
|
|
12
|
+
|
|
13
|
+
The update body is not a bag of fields. It is `{ main, secondaries?, deletions? }`: the row,
|
|
14
|
+
the child rows written with it and the child rows removed with it, as one request (ADR 0014).
|
|
15
|
+
`sqlApi.update(table, { main, … })` takes the same body, and so does each item of a bulk upsert.
|
|
16
|
+
|
|
17
|
+
A primary key can be composite. `GET` and `DELETE` address a row by one value, so they do not
|
|
18
|
+
exist for a composite-PK table; an update does, matching every primary key column.
|
|
19
|
+
|
|
20
|
+
## Decision
|
|
21
|
+
|
|
22
|
+
**An update names its row by the primary key fields in `main`.** The route is `PUT
|
|
23
|
+
/rest/:table`; a missing key field is a 400 at `main.<field>`. The update matches all of them,
|
|
24
|
+
single or composite.
|
|
25
|
+
|
|
26
|
+
## Alternatives considered
|
|
27
|
+
|
|
28
|
+
- **`PUT /rest/:table/:id`, key in the path only.** Breaks composite keys, which do not fit one
|
|
29
|
+
segment, and makes the HTTP body differ from `sqlApi.update` and from a bulk upsert item,
|
|
30
|
+
which have no path.
|
|
31
|
+
- **Key in both the path and `main`.** Two places for one value: a request whose path and body
|
|
32
|
+
disagree needs a rule for which one wins, and every client must keep them in sync.
|
|
33
|
+
- **Key in the path, with `main.id` refused.** Same composite-key problem, and `main` would no
|
|
34
|
+
longer be the row it is everywhere else.
|
|
35
|
+
|
|
36
|
+
## Consequences
|
|
37
|
+
|
|
38
|
+
- The routes are asymmetric: `GET` and `DELETE` take `:id`, `PUT` does not. The route
|
|
39
|
+
reference in AGENTS_FRONTEND.md says so (`main(+PK)`).
|
|
40
|
+
- One body shape for an update, whether it arrives over HTTP, through `sqlApi`, or as a bulk
|
|
41
|
+
upsert item.
|
|
42
|
+
- An update never touches more than the row its full key names: there is no update by
|
|
43
|
+
predicate (ADR 0020).
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# 0027. The 1.0 contract — what is public, how it changes, and the rules the API keeps
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted — supersedes [0022](./0022-stay-on-0x-while-every-consumer-is-first-party.md)
|
|
4
|
+
- **Date**: 2026-11-16
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
ADR 0022 kept the package on 0.x while every consumer was first-party, named two conditions
|
|
9
|
+
for 1.0, and required 1.0 to ship with its contract written down in an ADR superseding it.
|
|
10
|
+
|
|
11
|
+
On 2026-11-15 the maintainer chose to release 1.0 instead of 0.7, before either condition was
|
|
12
|
+
met. The reason was the API itself: a review found the same concept under several names
|
|
13
|
+
(`selection` and `select`, `allowedReadJoins` and `operations`), the same request in two
|
|
14
|
+
places (the search querystring and its body), two shapes for one result (`joinGroup` with and
|
|
15
|
+
without `by`, tuples and objects for a validation error), and internals exported as if they
|
|
16
|
+
were API. Fixing them one minor at a time would have broken every consumer once per minor;
|
|
17
|
+
fixing them together breaks them once, with one migration guide.
|
|
18
|
+
|
|
19
|
+
## Decision
|
|
20
|
+
|
|
21
|
+
**1. What is public.** Everything else is internal and may change in any release:
|
|
22
|
+
|
|
23
|
+
- the runtime exports of `src/index.ts`, pinned by `test/unit/public-exports.test.js`, and
|
|
24
|
+
the types it exports;
|
|
25
|
+
- the HTTP routes, their request and response shapes, the error envelope and its `fields`
|
|
26
|
+
codes, as AGENTS_FRONTEND.md describes them;
|
|
27
|
+
- the agent manifest format;
|
|
28
|
+
- the CLI: its commands, `sqlapi.config.ts` (`CliConfig`) and the shape of the files it
|
|
29
|
+
generates.
|
|
30
|
+
|
|
31
|
+
**2. Semantic versioning.** A breaking change to the public surface is a major; a backward
|
|
32
|
+
compatible addition is a minor; a fix is a patch. A fix that changes results someone may rely
|
|
33
|
+
on is breaking (the 0.4.1 lesson of ADR 0022).
|
|
34
|
+
|
|
35
|
+
**3. How the public surface changes:**
|
|
36
|
+
|
|
37
|
+
- a change to the API shape is announced — deprecated, and warned about at runtime — at least
|
|
38
|
+
one major before it is removed;
|
|
39
|
+
- a security tightening ships as a major with a migration guide, without waiting for a
|
|
40
|
+
deprecation cycle;
|
|
41
|
+
- platform floors (Node.js, TypeBox, Fastify) move only in a major;
|
|
42
|
+
- a major line still in use gets its security fixes as patches, from a `release/N.x` branch.
|
|
43
|
+
|
|
44
|
+
**4. The rules 1.0 applied, which later changes keep:**
|
|
45
|
+
|
|
46
|
+
- **One name, one place.** A concept has one name (docs/GLOSSARY.md) and a value one place in
|
|
47
|
+
a request: no alias, no second form of the same key.
|
|
48
|
+
- **Refused, not ignored.** A key the API no longer reads is rejected naming its replacement —
|
|
49
|
+
a 400 `retired_key` in a request, an error at startup in a config — never dropped in silence.
|
|
50
|
+
- **Codes, not prose.** An error carries stable codes the client translates; the server writes
|
|
51
|
+
no user-facing text, and a hook returns `{ path, code }`.
|
|
52
|
+
- **One way to mount the routes.** The plugin is registered, narrowed with `operations` when
|
|
53
|
+
needed; route plugins, engines and schema builders are internals.
|
|
54
|
+
- **Configuration fails at startup.** A config the routes could not honour — an unverifiable
|
|
55
|
+
upsert key, an unknown `defaultOrder` field, an ambiguous relation target — throws when the
|
|
56
|
+
plugin is registered, not on the first request.
|
|
57
|
+
|
|
58
|
+
## Alternatives considered
|
|
59
|
+
|
|
60
|
+
- **Stay on 0.x and ship the cleanup across several minors**, as ADR 0022 prescribed. Each
|
|
61
|
+
minor would break every consumer again, and the API would stay incoherent between them.
|
|
62
|
+
- **1.0 with the old names kept as deprecated aliases.** The aliases are the ambiguity 1.0
|
|
63
|
+
removes; a deprecation cycle protects consumers the maintainer does not reach, and at the
|
|
64
|
+
time of the release there were none.
|
|
65
|
+
- **1.0 without a written contract.** The version would promise stability without saying what
|
|
66
|
+
is stable; the first change after 1.0 would be decided case by case.
|
|
67
|
+
|
|
68
|
+
## Consequences
|
|
69
|
+
|
|
70
|
+
- Every consumer migrates once, with BREAKING_CHANGES.md.
|
|
71
|
+
- After 1.0, a change to the API shape costs a major and a deprecation cycle; the cleanup it
|
|
72
|
+
would have done must be worth that.
|
|
73
|
+
- The rules in point 4 bound future features: a new option that adds a second name for a
|
|
74
|
+
concept, or a key that is silently ignored, contradicts this ADR and needs a new one.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# 0028. `'*'` in `select` is the default projection — a computed field is asked for without copying the readable set
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Date**: 2026-11-16
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
A search without `select` returns every readable field of the main table — the schema minus
|
|
9
|
+
`readExclude` — and no computed field: a computed field is a SQL expression, evaluated only
|
|
10
|
+
when asked for. With `select`, the response carries the listed fields only.
|
|
11
|
+
|
|
12
|
+
Before 1.0, `selectComputed` alone meant "every column plus these computed fields". 1.0 folded
|
|
13
|
+
it into `select` (ADR 0027, one name, one place), and that meaning went with it: to get one
|
|
14
|
+
computed field, a client had to list every other field it reads.
|
|
15
|
+
|
|
16
|
+
A consumer migrating to 1.0 did exactly that: it generated the table's readable fields into a
|
|
17
|
+
constant and sent it with every search. That list is a client-side copy of server
|
|
18
|
+
configuration, and it drifts from it:
|
|
19
|
+
|
|
20
|
+
- a column moved into `readExclude` turns every search listing it into a 400 `not_readable`;
|
|
21
|
+
- a column added to the schema reaches the clients that send no `select`, and not the ones
|
|
22
|
+
that list fields to get a computed one.
|
|
23
|
+
|
|
24
|
+
So "everything, plus `fullName`" and "everything" stopped meaning the same "everything" as
|
|
25
|
+
soon as the schema or `readExclude` changed — the opposite of what `readExclude` is for: the
|
|
26
|
+
server decides what is readable, once.
|
|
27
|
+
|
|
28
|
+
## Decision
|
|
29
|
+
|
|
30
|
+
**In the main `select`, `'*'` stands for the default projection: every readable field, as a
|
|
31
|
+
search without `select` returns.** `['*', 'fullName']` is every readable field plus the
|
|
32
|
+
computed field `fullName`.
|
|
33
|
+
|
|
34
|
+
- `'*'` may stand anywhere in the list: the list is a set of fields, not an ordered one. A
|
|
35
|
+
schema field listed next to it adds nothing.
|
|
36
|
+
- The other names are validated as without it: an unknown name is a 400 `unknown_field`, a
|
|
37
|
+
`readExclude`d one a 400 `not_readable`, at `select.<i>`.
|
|
38
|
+
- It is the main projection only. A join's `select` admits no computed field, so `'*'` there
|
|
39
|
+
would mean what an absent `select` already means: it is a 400 `unknown_field`.
|
|
40
|
+
- The same holds in `sqlApi.search()`, which takes the HTTP body.
|
|
41
|
+
|
|
42
|
+
## Alternatives considered
|
|
43
|
+
|
|
44
|
+
- **Keep the explicit list** (the 1.0 rule). Every client that wants one computed field
|
|
45
|
+
maintains a copy of the readable set, and breaks or silently lags when the server changes
|
|
46
|
+
it. The cost falls on every consumer, permanently, to spare the server one token.
|
|
47
|
+
- **A second key for computed fields** (`computed: ['fullName']`, or bringing back
|
|
48
|
+
`selectComputed`). Two keys for one projection, and two ways to name a computed field — the
|
|
49
|
+
ambiguity ADR 0027 removed. `'*'` keeps one key: `select` still lists what the row carries.
|
|
50
|
+
- **Project every computed field by default.** A computed field is an expression the database
|
|
51
|
+
evaluates per row, possibly a subquery; paying for all of them on every search to save a
|
|
52
|
+
client one name inverts the cost. And the response of a plain search would change each time
|
|
53
|
+
a computed field is declared.
|
|
54
|
+
- **Allow `'*'` as the first element only.** One more rule and one more error code for no
|
|
55
|
+
gain: the position of `'*'` changes nothing in the result.
|
|
56
|
+
|
|
57
|
+
## Consequences
|
|
58
|
+
|
|
59
|
+
- A client asks for computed fields with `['*', …]` and keeps no list of the readable fields;
|
|
60
|
+
`readExclude` is the one place that decides them, for every client.
|
|
61
|
+
- `'*'` is the only name in `select` that is not a field. A tool reading `select` as a list of
|
|
62
|
+
field names must skip it. A column literally named `*` (possible only as a quoted
|
|
63
|
+
identifier) can no longer be selected by name; it is still in the default projection.
|
|
64
|
+
- Adding it is backward compatible: before, `'*'` was a 400 `unknown_field`.
|