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
@@ -6,27 +6,31 @@ This is the request GRAMMAR. The vocabulary (this deployment's tables, fields, j
6
6
  - `{p}` = deployment prefix (e.g. `/api`). `{table}` = the table's key in the manifest, which may differ from the DB table name (one table can be exposed under several keys, each with its own rules).
7
7
  - Join keys are backend-declared ALIASES (default: the joined table name).
8
8
  - Write responses return PKs only. Send only real schema fields in write bodies: unknown ones are dropped or rejected (400), depending on the server.
9
- - Composite-PK tables have no get/delete/bulk-delete routes (404): use search / update.
9
+ - Composite-PK tables have no get/delete-by-`:id` routes (404): read with search, write with update, delete with bulk delete, one object per key.
10
10
 
11
11
  ## Endpoints
12
12
 
13
13
  ```
14
14
  POST {p}/search/{table} body=search request → {table, main:[...], ...}
15
15
  GET {p}/rest/{table}/:id → {main:{...}} | 404
16
- POST {p}/rest/{table} body={main, secondaries?} → 201 {main:{id}, secondaries?}
17
- PUT {p}/rest/{table} body={main(+PK), secondaries?, deletions?} → {main:{id}, secondaries?, deletions?}
16
+ POST {p}/rest/{table} body={main, upsert?, replace?} → 201 {main:{id}, action, secondaries?, deletions?} // action: "inserted" | "updated" (upsert tables); deletions: only from a replace
17
+ PUT {p}/rest/{table} body={main(+PK), upsert?, delete?, replace?} → {main:{id}, secondaries?, deletions?}
18
18
  DELETE {p}/rest/{table}/:id → {main:{id}} | 404
19
- PUT {p}/bulk/{table} body=[{main, secondaries?, deletions?}, ...] → [{main:{id}}, ...]
20
- POST {p}/bulk/{table}/delete body=[{id:1}, {id:2}] → [{main:{id:1}}, ...] // key = the table's PK field
19
+ PUT {p}/bulk/{table} body=[{main, upsert?, delete?, replace?}, ...] → [{main:{id}, action, secondaries?, deletions?}, ...]
20
+ POST {p}/bulk/{table}/delete body={ids:[1, 2]} → [{main:{id:1}}, ...] // only the rows actually deleted; main key = the table's PK field
21
+ // composite PK: one object per key, every key field: body={ids:[{postId:1, tagId:2}]} → [{main:{postId:1, tagId:2}}, ...]
21
22
  ```
22
23
 
23
24
  ## Search
24
25
 
25
- Querystring, all optional: `orderBy`, `page`, `itemsPerPage`, `computeMin|Max|Sum|Avg=<field>`. Body, all optional and combinable; `{}` returns the first N rows.
26
+ Everything travels in the body, and only there; all keys are optional and combinable, `{}` returns the first N rows. `orderBy`, `page`, `itemsPerPage` or `computeMin|Max|Sum|Avg` in the querystring → 400 `retired_key` at that key.
26
27
 
27
28
  ```jsonc
28
- // POST {p}/search/customer?orderBy=orders.sum.total DESC, creator.name ASC, id&page=1&itemsPerPage=20&computeSum=total
29
+ // POST {p}/search/customer
29
30
  {
31
+ "orderBy": "orders.sum.total DESC, creator.name ASC, id", // see orderBy below
32
+ "paginator": { "page": 1, "itemsPerPage": 20 }, // see Pagination
33
+ "compute": { "sum": ["total"], "count": ["id"] }, // min|max|sum|avg|count|distinctCount over ALL matching rows, not the page → computed; paginator not needed
30
34
  "filters": { "status": "active", "deletedById": null }, // equality, AND; null → IS NULL; also computed fields and backend extra filters (see manifest). Unknown key → 400
31
35
  "conditions": [ // AND; the same field may repeat
32
36
  { "field": "total", "method": "isBetween", "params": [100, 500] },
@@ -34,21 +38,22 @@ Querystring, all optional: `orderBy`, `page`, `itemsPerPage`, `computeMin|Max|Su
34
38
  { "field": "status", "method": "isIn", "params": [["active", "pending"]] },
35
39
  { "field": "orders.count.id", "method": "isGreaterOrEqual", "params": [4] } // alias.fn.field, HAVING-style: needs the matching joinGroup below
36
40
  ],
37
- "selectComputed": ["displayName"], // computed fields are projected into main rows only when listed
38
- "joinMustExist": { // EXISTS on children: decides WHICH main rows return; fetches nothing
41
+ "select": ["id", "name", "displayName"], // main fields to return, computed ones included; default: every readable field and no computed one. "*" = that default: ["*", "fullName"] adds a computed field without listing the rest (main select only). The PK and the keys of the requested joins are always included. Unknown or hidden name → 400
42
+ "joinMustExist": { // EXISTS on child rows: decides WHICH main rows return; fetches nothing
39
43
  "labels": { "filters": { "labelId": 1 }, "conditions": [] }
40
44
  },
41
45
  "joinMultiple": { // side query: child rows of the returned main rows
42
- "orders": { "filters": { "status": "pending" }, "conditions": [], "selection": "id,total,status" }
46
+ "orders": { "filters": { "status": "pending" }, "conditions": [], "select": ["customerId", "id", "total", "status"] } // default set by the backend; a select returns only what it lists — include the FK (customerId) to tell which main row a child belongs to
43
47
  },
44
48
  "joinGroup": { // aggregates child rows of the returned main rows
45
49
  "orders": {
46
- "aggregations": { "by": "status", "sum": ["total"], "min": ["total"], "max": ["total"], "avg": ["total"], "count": ["id"], "distinctCount": ["status"] }, // by: optional GROUP BY (field or computed)
47
- "filters": { "status": "active" }, "conditions": [] // narrow children before aggregating
50
+ "by": "customerId", // optional GROUP BY (field or computed); absent or the FK when alias.fn.field is in orderBy or conditions
51
+ "sum": ["total"], "min": ["total"], "max": ["total"], "avg": ["total"], "count": ["id"], "distinctCount": ["status"], // at least one
52
+ "filters": { "status": "active" }, "conditions": [] // narrow the child rows before aggregating
48
53
  }
49
54
  },
50
55
  "joinLeft": { // N:1 parent (alias declared unique by the backend)
51
- "creator": { "selection": "id,name", "filters": {}, "conditions": [] } // filters here EXCLUDE mains whose parent does not match; no extra filters here
56
+ "creator": { "select": ["id", "name"], "filters": {}, "conditions": [] } // filters here EXCLUDE mains whose parent does not match; no extra filters here
52
57
  }
53
58
  }
54
59
  ```
@@ -60,22 +65,21 @@ Response; each section is present only if requested:
60
65
  "table": "customer",
61
66
  "main": [{ "id": 1, "name": "Mario", "creatorId": 7, "displayName": "..." }],
62
67
  "joinMultiple": { "orders": [{ "id": 10, "customerId": 1, "total": 50 }] }, // flat list for all mains: group client-side by FK
63
- "joinGroup": { "orders": {
64
- "sum": { "total": 150 }, // no "by": ONE total over the children of ALL returned mains
65
- "rows": [{ "by": "pending", "sum_total": 100 }] // with "by": one row per group; by = FK field gives per-main values
66
- }},
68
+ "joinGroup": { "orders": { "rows": [ // always rows, [] when no main matched
69
+ { "by": 1, "sum": { "total": "100.00" }, "count": { "id": "2" } } // with "by": one row per group; by = FK field gives per-main values. Aggregates come as the database returns them: often strings, exact — parse them
70
+ ]}}, // without "by": ONE row, no "by", over the child rows of ALL returned mains
67
71
  "joinLeft": { "creator": [{ "id": 7, "name": "Alice" }] }, // deduplicated: match main.creatorId === creator.id
68
- "pagination": { // only when page or itemsPerPage is sent
72
+ "computed": { "sum": { "total": "999.00" }, "count": { "id": "25" } }, // only when compute is sent: one entry per function and field; values as in joinGroup
73
+ "pagination": { // only when paginator is sent, even {}
69
74
  "total": 25, "pages": 3,
70
- "computed": { "sum": { "total": 999 } }, // computeMin/Max/Sum/Avg over all matching rows; require pagination
71
75
  "paginator": { "page": 1, "itemsPerPage": 20 }
72
76
  }
73
77
  }
74
78
  ```
75
79
 
76
80
  Pagination:
77
- - Without `page`/`itemsPerPage`, the server caps rows at its maximum (default 1000) and returns no `pagination` block.
78
- - With `page` only, `itemsPerPage` defaults to 500 (or the server maximum if lower).
81
+ - Without `paginator`, the server caps rows at its maximum (default 1000) and returns no `pagination` block.
82
+ - With `page` only, `itemsPerPage` defaults to 500 (or the server maximum if lower); with `itemsPerPage` only, `page` defaults to 1.
79
83
  - Both are integers ≥ 1. `itemsPerPage` above the server maximum → 400.
80
84
 
81
85
  `orderBy` is a comma-separated list, each part one of:
@@ -85,7 +89,7 @@ Pagination:
85
89
 
86
90
  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
91
 
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.
92
+ A main without child rows (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
93
 
90
94
  Condition methods and `params` arity:
91
95
  - `[v]`: `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual`
@@ -101,36 +105,54 @@ An unknown field or method, or `params` that is not an array or is too short →
101
105
  ```jsonc
102
106
  // POST {p}/rest/customer — insert; omit auto-generated PKs
103
107
  { "main": { "name": "Mario", "email": "m@t.it" },
104
- "secondaries": { "orders": [{ "total": 50, "status": "pending" }] } } // child FK auto-filled from the new main PK
105
- // → 201 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 10 }] } }
108
+ "upsert": { "orders": [{ "total": 50, "status": "pending" }] } } // child FK auto-filled from the new main PK
109
+ // → 201 { "main": { "id": 1 }, "action": "inserted", "secondaries": { "orders": [{ "id": 10 }] } }
106
110
 
107
111
  // PUT {p}/rest/customer — update; main MUST include the PK; send only the fields to change; null sets NULL
108
112
  { "main": { "id": 1, "email": "new@t.it" },
109
- "secondaries": { "orders": [{ "total": 75 }] }, // insert (or upsert) children, FK auto-filled
110
- "deletions": { "orders": [{ "id": 10 }] } } // delete children by PK, only children of this main
111
- // → 200 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 20 }] }, "deletions": { "orders": [{ "id": 10 }] } }
113
+ "upsert": { "orders": [{ "total": 75 }] }, // insert (or upsert) child rows, FK auto-filled; the others stay
114
+ "delete": { "orders": [{ "id": 10 }] } } // delete child rows by PK, only those of this main
115
+ // → 200 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 20 }] }, "deletions": { "orders": [{ "id": 10, "customerId": 1 }] } }
112
116
 
113
117
  // PUT {p}/bulk/customer — bulk upsert; items need not share keys: an omitted field keeps the stored value (update) or takes the column default (insert)
114
- [ { "main": { "name": "Mario" }, "secondaries": { "orders": [{ "total": 50 }] } },
118
+ [ { "main": { "id": 1, "name": "Mario" }, "upsert": { "orders": [{ "total": 50 }] } }, // customer has upsertKey [id] in the manifest
115
119
  { "main": { "name": "Luigi" } } ]
116
- // → 200 [ { "main": { "id": 1 }, "secondaries": {...} }, { "main": { "id": 2 } } ]
120
+ // → 200 [ { "main": { "id": 1 }, "action": "updated", "secondaries": {...} }, { "main": { "id": 2 }, "action": "inserted" } ]
121
+ // action: what the statement did to the main row. "updated" when an upsert rule matched an existing row (also with nothing left to change), "inserted" otherwise; tables without a rule always say "inserted".
122
+ // The request says what to do with child rows (upsert, delete, replace); the response says what happened: secondaries = rows written (PKs only), deletions = rows removed.
117
123
  ```
118
124
 
119
- Upsert tables (see manifest):
125
+ Child rows go in one section per action, by write alias (manifest):
126
+ - `upsert`: write these rows; the other child rows stay.
127
+ - `delete` (update and bulk): delete these rows, named by their key; only child rows of this main.
128
+ - `replace`: these are all the child rows — the rows sent are upserted, every other child row of the main row is deleted. `[]` deletes them all. Only for a write alias with an `upsertKey` in the manifest.
129
+
130
+ ```jsonc
131
+ // post 1 has tags 1 and 2
132
+ PUT {p}/rest/post { "main": { "id": 1 }, "replace": { "tags": [{ "tagId": 2 }, { "tagId": 3 }] } }
133
+ // → 200 { "main": { "id": 1 }, "secondaries": { "tags": [...] }, "deletions": { "tags": [{ "postId": 1, "tagId": 1 }] } }
134
+ ```
135
+
136
+ 400, and nothing is written: an alias the table does not write (including one only readable), or `replace` on an alias without `upsertKey` → `unknown_field` at `<section>.<alias>` (`<i>.<section>.<alias>` in a bulk); one alias in `replace` and in `upsert` or `delete` too → `conflicting_alias` at `replace.<alias>`; the pre-1.0 `secondaries` / `deletions` keys → `retired_key`.
137
+
138
+ Upsert tables (`upsertKey` on the table in the manifest; on a write alias, it is the child rows' key):
120
139
  - Every row, main or child, carries its conflict key: missing, null, or shared by two rows of one request → 400.
121
- - When the key is the id, rows without an id are inserted.
140
+ - When the key is the id, rows without an id are inserted. If the server generates ids (`serverGenerated` in the manifest), an id must name an existing row: none → 400 `not_found` at its path, nothing written.
122
141
  - Bulk arrays are capped (default 1000): chunk client-side.
123
142
 
124
143
  ## Errors
125
144
 
126
- 400 (schema or business validation): map `fields[].path` to form fields.
145
+ Every error the plugin's routes raise has one shape (a route the backend did not register, e.g. get/delete on a composite-PK table, is the framework's plain 404, without `requestId`). `error` is the HTTP reason phrase; `requestId` is the server log's `reqId`, quote it when reporting a problem.
127
146
 
128
147
  ```json
129
- { "statusCode": 400, "error": "Bad Request", "message": "Validation failed",
130
- "fields": [ { "path": "body.main.name", "code": "required", "message": "must have required property 'name'" } ] }
148
+ { "statusCode": 400, "error": "Bad Request", "message": "Validation failed", "requestId": "req-1",
149
+ "fields": [ { "path": "main.name", "code": "required", "message": "must have required property 'name'" } ] }
131
150
  ```
132
151
 
133
- - 403: tenant violation.
134
- - 404: record not found, or outside your tenant.
135
- - 500: DB errors (e.g. constraint violations), unmapped, with a `requestId` to report.
136
- - Per search, max 100 `conditions` per section (top level and each join) and max 20 `orderBy` parts (≤ 1024 chars); over either → 400. Collapse many equality conditions into one `isIn`.
152
+ - 400 always carries `fields`, whether the request failed the schema, the backend's business validation or the engine. Map `fields[].path` to form fields; when `fields` is empty, show `message`.
153
+ - `path` is the dot path of the offending value in the request: body keys from the root (`main.name`, `upsert.orders.0.total`, `filters.status`, `conditions.2.params`, `joinGroup.orders.by`, `joinMultiple.orders.select.1`), path parameters and retired querystring keys by name (`id`, `orderBy`). `""` when the error is not attributable to one input.
154
+ - `code` is stable: an Ajv keyword (`required`, `type`, `maximum`, `additionalProperties`, `enum`…), a code the backend chose in its own validation, or an engine code: `unknown_field`, `not_readable`, `unknown_alias`, `wrong_join_family`, `invalid_method`, `invalid_params`, `invalid_order_by`, `invalid_paginator`, `invalid_aggregation`, `undeclared_aggregation`, `bound_values_not_allowed`, `extra_filter_not_allowed`, `limit_exceeded`, `retired_key` (a key the API no longer reads, e.g. `selectComputed`, a join's `selection`, the search querystring, `secondaries`/`deletions` in a write), `conflicting_alias`, `missing_key`, `duplicate_key`, `not_found`, `ambiguous_tenant`. The engine's `message` repeats the field's.
155
+ - `message`, when present, is a low-level description for the developer (Ajv's or the engine's, in English). A backend validation and a mapped DB error carry none: the code is the whole answer. Show the user a translation of `code`, never `message`.
156
+ - 401: on a table with tenant scope, the request carries no tenant (the backend's auth resolved none). 403: tenant violation. 404: row not found, or outside your tenant. No `fields`, except a mapped DB error (below).
157
+ - 500: DB errors (e.g. constraint violations): `message` is fixed, the detail is in the server log under `requestId`. The backend may answer some of them with another status instead (typically 409 on a duplicate): same envelope, plus `fields: [{ path: "", code }]` with a backend-chosen code to translate.
158
+ - Per search, max 100 `conditions` per section (top level and each join): over it → 400 `maxItems` at that `conditions`. `orderBy` takes max 20 `orderBy` parts (→ 400 `limit_exceeded`) in ≤ 1024 chars (→ 400 `maxLength`). Collapse many equality conditions into one `isIn`.