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
@@ -1,57 +1,93 @@
1
1
  import { ConditionBuilder } from 'node-condition-builder';
2
- import { buildTenantDeleteWhere, assertTenantOwnsAll } from '../../tenant.js';
3
- import { primaryAsString, isCompositePrimary } from '../../../types.js';
2
+ import { buildTenantRowGuard, assertTenantOwnsAll } from '../../tenant.js';
3
+ import { buildKeyMatch } from '../../db.js';
4
4
  import { httpError } from '../../errors.js';
5
+ /**
6
+ * Delete rows by primary key. A single-column key takes the values themselves; a composite key
7
+ * takes one object per row naming every key field, and each row is matched on all of its key
8
+ * columns together — never on one column alone, which would reach every row sharing it.
9
+ */
5
10
  export async function bulkDeleteEngine(params) {
6
11
  const { db, tableConf, ids, tenant, request } = params;
7
- if (isCompositePrimary(tableConf.primary)) {
8
- throw httpError(400, `Table "${tableConf.Schema.tableName}" has a composite primary key: bulk delete matches on "${primaryAsString(tableConf.primary)}" alone and could remove multiple rows per id. Use a custom query.`);
9
- }
10
- if (!ids.length)
12
+ const pkFields = Array.isArray(tableConf.primary) ? tableConf.primary : [tableConf.primary];
13
+ const keys = keyValues(ids, pkFields);
14
+ if (!keys.length)
11
15
  return [];
12
- const pk = primaryAsString(tableConf.primary);
13
- const pkCol = tableConf.Schema.col(pk);
14
- const tableName = tableConf.Schema.tableName;
16
+ const pkCols = pkFields.map((f) => tableConf.schema.col(f));
17
+ const tableName = tableConf.schema.tableName;
18
+ const single = pkFields.length === 1;
19
+ /** A deleted row's key, as the response and `afterBulkDelete` name it. */
20
+ const keyOf = (values) => Object.fromEntries(pkFields.map((f, i) => [f, values[i]]));
15
21
  if (tableConf.beforeBulkDelete) {
16
22
  // Enforce tenant ownership of every id before the hook (single batched SELECT), so it
17
23
  // never runs for rows the tenant cannot access. Called once with all ids — no loop.
18
- await assertTenantOwnsAll(db, tenant, tableName, pkCol, ids);
19
- await tableConf.beforeBulkDelete(db, request, ids);
20
- }
21
- let where;
22
- let values;
23
- if (tenant) {
24
- ({ where, values } = buildTenantDeleteWhere(db, tableName, pkCol, ids, tenant));
25
- }
26
- else {
27
- const cb = new ConditionBuilder('AND', db.cbDialect);
28
- cb.isIn(db.qi(pkCol), ids);
29
- where = cb.build(1, db.ph);
30
- values = cb.getValues();
24
+ await assertTenantOwnsAll(db, tenant, tableName, pkCols, keys);
25
+ await tableConf.beforeBulkDelete({ db, req: request, ids });
31
26
  }
27
+ // The keys, and the tenant's guard when the table is scoped: a row the caller does not own
28
+ // is not deleted, and is left out of the answer like a missing one.
29
+ const keyMatch = buildKeyMatch(db, pkCols.map((c) => db.qi(c)), keys);
30
+ const guard = buildTenantRowGuard(db, tenant, tableName);
31
+ const condition = guard
32
+ ? new ConditionBuilder('AND', db.cbDialect).append(keyMatch).append(guard)
33
+ : keyMatch;
34
+ const where = condition.build(1, db.ph);
35
+ const values = condition.getValues();
36
+ const quotedPkCols = pkCols.map((c) => db.qi(c)).join(', ');
32
37
  let results;
33
38
  if (db.supportsReturning) {
34
- const result = await db.query(`DELETE FROM ${db.qi(tableName)} WHERE ${where}${db.returningPk(db.qi(pkCol))}`, values);
39
+ const result = await db.query(`DELETE FROM ${db.qi(tableName)} WHERE ${where}${db.returningPk(quotedPkCols)}`, values);
35
40
  // Happy path: everything requested was deleted
36
- if (result.affectedRows === ids.length) {
37
- results = ids.map((id) => ({ main: { [pk]: id } }));
41
+ if (result.affectedRows === keys.length) {
42
+ results = keys.map((k) => ({ main: keyOf(k) }));
38
43
  }
39
44
  else {
40
45
  // Partial delete: RETURNING tells exactly which rows went away
41
- results = result.rows.map((r) => ({ main: { [pk]: r[pkCol] } }));
46
+ results = result.rows.map((r) => ({ main: keyOf(pkCols.map((c) => r[c])) }));
42
47
  }
43
48
  }
44
49
  else {
45
50
  // No RETURNING (mysql): affectedRows alone cannot tell WHICH ids were deleted on a
46
51
  // partial match, so look up the rows visible through the same WHERE before deleting.
47
- const existing = await db.query(`SELECT ${db.qi(pkCol)} AS pk FROM ${db.qi(tableName)} WHERE ${where}`, values);
52
+ const keyList = single ? `${quotedPkCols} AS pk` : quotedPkCols;
53
+ const existing = await db.query(`SELECT ${keyList} FROM ${db.qi(tableName)} WHERE ${where}`, values);
48
54
  await db.query(`DELETE FROM ${db.qi(tableName)} WHERE ${where}`, values);
49
- results = existing.rows.map((r) => ({ main: { [pk]: r.pk } }));
55
+ results = existing.rows.map((r) => ({ main: keyOf(single ? [r.pk] : pkCols.map((c) => r[c])) }));
50
56
  }
51
57
  // Called once with the ACTUALLY deleted ids (possibly a subset of the requested ones)
52
58
  if (tableConf.afterBulkDelete && results.length > 0) {
53
- const deletedIds = results.map((r) => r.main[pk]);
54
- await tableConf.afterBulkDelete(db, request, deletedIds);
59
+ const deletedIds = results.map((r) => (single ? r.main[pkFields[0]] : r.main));
60
+ await tableConf.afterBulkDelete({ db, req: request, ids: deletedIds });
55
61
  }
56
62
  return results;
57
63
  }
64
+ /**
65
+ * One value per key column for each id, in `pkFields` order. The HTTP body schema already
66
+ * enforces this shape; `sqlApi` runs no body schema, so it is checked here too, as a 400 at the
67
+ * same paths: an object for a single-column key, or a composite id that is not an object, is a
68
+ * `type` at `ids.<i>`; a missing key field a `required`, a field outside the key an
69
+ * `additionalProperties` at `ids.<i>.<field>`.
70
+ */
71
+ function keyValues(ids, pkFields) {
72
+ return ids.map((id, i) => {
73
+ const isObject = id !== null && typeof id === 'object' && !Array.isArray(id);
74
+ if (pkFields.length === 1) {
75
+ if (isObject)
76
+ throw httpError(400, `ids.${i}: a single-column key takes its value, not an object`, { code: 'type', path: `ids.${i}` });
77
+ return [id];
78
+ }
79
+ if (!isObject) {
80
+ throw httpError(400, `ids.${i}: a composite key takes an object naming ${pkFields.join(', ')}`, { code: 'type', path: `ids.${i}` });
81
+ }
82
+ const key = id;
83
+ const extra = Object.keys(key).find((f) => !pkFields.includes(f));
84
+ if (extra !== undefined) {
85
+ throw httpError(400, `ids.${i}.${extra} is not a primary key field`, { code: 'additionalProperties', path: `ids.${i}.${extra}` });
86
+ }
87
+ const missing = pkFields.find((f) => key[f] == null);
88
+ if (missing !== undefined) {
89
+ throw httpError(400, `ids.${i}.${missing} is required`, { code: 'required', path: `ids.${i}.${missing}` });
90
+ }
91
+ return pkFields.map((f) => key[f]);
92
+ });
93
+ }
@@ -1 +1 @@
1
- {"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAgE3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}
1
+ {"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAIjB,MAAM,mBAAmB,CAAC;AA6F3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA4C5F"}
@@ -1,72 +1,91 @@
1
1
  import { camelcaseObject } from '../../naming.js';
2
- import { processSecondaries, processDeletions, prepareInsertRecord, assertUpsertKeys, } from '../write-helpers.js';
2
+ import { processSecondaries, processDeletions, prepareInsertRecord, assertUpsertKeys, assertExcludedKeysExist, insertExcludedKeyFields, assertWriteJoinAliases, hasAliases, } from '../write-helpers.js';
3
3
  import { enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../../tenant.js';
4
4
  import { runBulkValidation } from '../validate.js';
5
5
  import { primaryAsCols } from '../../../types.js';
6
- /** One bulk statement for every main row, returning the PKs only. */
7
- function upsertMains(params, preparedMains, pkCol) {
6
+ /** One bulk statement for every main row: its PK and what the statement did to it. */
7
+ async function upsertMains(params, preparedMains, pkCol) {
8
8
  const { db, tableConf, tenant } = params;
9
- const schema = tableConf.Schema;
10
- const upsertKeys = tableConf.upsertMap?.get(schema);
9
+ const schema = tableConf.schema;
10
+ const upsertKeys = tableConf.upsertKey;
11
11
  if (!upsertKeys) {
12
- return db.bulkInsert(schema.tableName, preparedMains, pkCol);
12
+ const pkRows = await db.bulkInsert(schema.tableName, preparedMains, pkCol);
13
+ return pkRows.map((pk) => ({ pk, action: 'inserted' }));
13
14
  }
14
15
  const conflictCols = upsertKeys.map((k) => schema.col(k));
15
16
  assertUpsertKeys(schema, conflictCols, [pkCol].flat(), preparedMains);
17
+ await assertExcludedKeysExist(db, schema, conflictCols, insertExcludedKeyFields(tableConf, upsertKeys), preparedMains, params.items.map((item) => item.main), (i, field) => `${i}.main.${field}`);
16
18
  // Tenant isolation: a conflicting upsert must not overwrite rows owned by another tenant, nor
17
19
  // re-assign the owner of a row it legitimately updates.
18
- return assertTenantOwnsConflicts(db, tenant, schema.tableName, conflictCols, preparedMains)
19
- .then(() => db.bulkInsertOrUpdate(schema.tableName, preparedMains, conflictCols, pkCol, undefined, tenantImmutableColumns(tenant)));
20
+ await assertTenantOwnsConflicts(db, tenant, schema.tableName, conflictCols, preparedMains);
21
+ return db.bulkUpsert(schema.tableName, preparedMains, conflictCols, pkCol, { immutableCols: tenantImmutableColumns(tenant) });
20
22
  }
21
- /** Secondaries, deletions and the afterInsert hook for one upserted item. */
22
- async function finalizeUpsertedItem(params, item, inputMain, pkRow) {
23
+ /**
24
+ * The child rows and the afterInsert hook of one upserted item. The batch runs without a
25
+ * transaction (ADR 0003), but an item with a `replace` runs this in a transaction of its own
26
+ * (ADR 0029): its upsert and the removal of the rows it left out commit together, so the item
27
+ * never ends with half its children replaced.
28
+ */
29
+ function finalizeUpsertedItem(params, at, item, inputMain, written) {
30
+ return hasAliases(item.replace)
31
+ ? params.db.withTransaction((tx) => writeItemChildren({ ...params, db: tx }, at, item, inputMain, written))
32
+ : writeItemChildren(params, at, item, inputMain, written);
33
+ }
34
+ async function writeItemChildren(params, at, item, inputMain, written) {
23
35
  const { db, tableConf, dbTables, request, tenant } = params;
24
- // pkRow comes from SQL RETURNING or mysql insertId synthesis — keys are DB column names;
36
+ // The PK row comes from SQL RETURNING or mysql insertId synthesis — keys are DB column names;
25
37
  // camelcaseObject maps them back to schema fields (full composite PK).
26
- const mainPkCamel = camelcaseObject(pkRow, tableConf.Schema);
27
- const result = { main: mainPkCamel };
38
+ const mainPkCamel = camelcaseObject(written.pk, tableConf.schema);
39
+ const result = { main: mainPkCamel, action: written.action };
28
40
  // FK auto-fill: input camelCase + generated PK
29
41
  const mainForFK = { ...inputMain, ...mainPkCamel };
30
- if (item.secondaries && Object.keys(item.secondaries).length > 0) {
31
- const sec = await processSecondaries({ db, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, item.secondaries);
32
- if (Object.keys(sec).length > 0)
33
- result.secondaries = sec;
42
+ let removed = {};
43
+ if (hasAliases(item.upsert, item.replace)) {
44
+ const outcome = await processSecondaries({ db, tableConf, dbTables, mainRecord: mainForFK, tenant, request, at: String(at) }, { upsert: item.upsert, replace: item.replace });
45
+ if (Object.keys(outcome.written).length > 0)
46
+ result.secondaries = outcome.written;
47
+ removed = outcome.removed;
34
48
  }
35
- if (item.deletions && Object.keys(item.deletions).length > 0) {
36
- const del = await processDeletions({ db, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, item.deletions);
49
+ if (hasAliases(item.delete)) {
50
+ const del = await processDeletions({ db, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, item.delete ?? {});
37
51
  if (Object.keys(del).length > 0)
38
52
  result.deletions = del;
39
53
  }
54
+ if (Object.keys(removed).length > 0)
55
+ result.deletions = { ...result.deletions, ...removed };
40
56
  if (tableConf.afterInsert) {
41
- await tableConf.afterInsert(db, request, mainForFK, result.secondaries);
57
+ await tableConf.afterInsert({
58
+ db, req: request, record: mainForFK, secondaries: result.secondaries, deletions: result.deletions,
59
+ });
42
60
  }
43
61
  return result;
44
62
  }
45
63
  export async function bulkUpsertEngine(params) {
46
- const { db, tableConf, request, items, tenant } = params;
64
+ const { db, tableConf, dbTables, request, items, tenant } = params;
47
65
  if (!items.length)
48
66
  return [];
49
- const schema = tableConf.Schema;
67
+ const schema = tableConf.schema;
50
68
  // Full primary key columns — composite PKs need every column (see insertEngine).
51
69
  const pkCol = primaryAsCols(tableConf.primary, (f) => schema.col(f));
70
+ items.forEach((item, i) => assertWriteJoinAliases(tableConf, item, String(i)));
52
71
  // 1. Bulk validation runs once for all items (skips per-item validate). Otherwise per-item
53
72
  // validation happens inside prepareInsertRecord below.
54
73
  if (tableConf.validateBulk) {
55
74
  await runBulkValidation(db, request, tableConf, items);
56
75
  }
57
76
  // 2. For each item: validate (unless validateBulk ran) → beforeInsert → snake → remove excluded.
58
- const prepared = await Promise.all(items.map((item) => prepareInsertRecord({ db, tableConf, request }, item.main, item.secondaries, { skipValidate: !!tableConf.validateBulk })));
77
+ const prepared = await Promise.all(items.map((item, i) => prepareInsertRecord({ db, tableConf, dbTables, request }, item.main, { upsert: item.upsert, replace: item.replace }, { skipValidate: !!tableConf.validateBulk, at: String(i) })));
59
78
  const inputMains = prepared.map((p) => p.camel);
60
79
  const preparedMains = prepared.map((p) => p.snake);
61
80
  // 3. Tenant: inject (direct) or batch-validate FK (indirect) — enforced after user mutations
62
81
  await enforceTenantOnWrites(db, tenant, preparedMains);
63
- // 4. Bulk upsert all mains in one query → returns PK-only
64
- const pkRows = await upsertMains(params, preparedMains, pkCol);
82
+ // 4. Bulk upsert all mains in one query → PK and action per row
83
+ const written = await upsertMains(params, preparedMains, pkCol);
65
84
  // 5-6. Secondaries, deletions and afterInsert per item — sequential on purpose, so hooks
66
85
  // observe the same order the caller sent, and errors surface on the first bad item.
67
86
  const results = [];
68
87
  for (let i = 0; i < items.length; i++) {
69
- results.push(await finalizeUpsertedItem(params, items[i], inputMains[i], pkRows[i]));
88
+ results.push(await finalizeUpsertedItem(params, i, items[i], inputMains[i], written[i]));
70
89
  }
71
90
  return results;
72
91
  }
@@ -1,6 +1,6 @@
1
1
  import type { ApiRequest } from '../../types/request.js';
2
2
  import type { QueryClient } from '../db.js';
3
- import type { ITable, ReadSource } from '../../types.js';
3
+ import type { TableConfig, ReadSource } from '../../types.js';
4
4
  /**
5
5
  * Run a table's `afterRead` hook over the rows a read produced.
6
6
  *
@@ -10,10 +10,10 @@ import type { ITable, ReadSource } from '../../types.js';
10
10
  * gets one call per result set instead of one per row.
11
11
  *
12
12
  * `tableConf` is resolved by the caller, which on a join is the JOINED table's config
13
- * (`dbTables[joinSchema.tableName]`). That is what makes the hook follow a relation without
13
+ * (`resolveJoinTableConf`). That is what makes the hook follow a relation without
14
14
  * being declared on the host, the way `readExclude` and `tenantScope` do (ADR 0010).
15
15
  *
16
16
  * An empty result set is skipped: there is nothing to transform, and the hook may be costly.
17
17
  */
18
- export declare function runAfterRead(db: QueryClient, request: ApiRequest | undefined, rows: Record<string, unknown>[], tableConf: ITable | undefined, source: ReadSource, alias?: string): Promise<void>;
18
+ export declare function runAfterRead(db: QueryClient, request: ApiRequest | undefined, rows: Record<string, unknown>[], tableConf: TableConfig | undefined, source: ReadSource, alias?: string): Promise<void>;
19
19
  //# sourceMappingURL=read-hooks.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"read-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/read-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAoB,MAAM,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAIf"}
1
+ {"version":3,"file":"read-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/read-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAoB,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,MAAM,EAAE,UAAU,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAIf"}
@@ -7,7 +7,7 @@
7
7
  * gets one call per result set instead of one per row.
8
8
  *
9
9
  * `tableConf` is resolved by the caller, which on a join is the JOINED table's config
10
- * (`dbTables[joinSchema.tableName]`). That is what makes the hook follow a relation without
10
+ * (`resolveJoinTableConf`). That is what makes the hook follow a relation without
11
11
  * being declared on the host, the way `readExclude` and `tenantScope` do (ADR 0010).
12
12
  *
13
13
  * An empty result set is skipped: there is nothing to transform, and the hook may be costly.
@@ -15,6 +15,6 @@
15
15
  export async function runAfterRead(db, request, rows, tableConf, source, alias) {
16
16
  if (!tableConf?.afterRead || rows.length === 0)
17
17
  return;
18
- const ctx = alias === undefined ? { source } : { source, alias };
19
- await tableConf.afterRead(db, request, rows, ctx);
18
+ const ctx = { db, req: request, rows, source, ...(alias === undefined ? {} : { alias }) };
19
+ await tableConf.afterRead(ctx);
20
20
  }
@@ -1 +1 @@
1
- {"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/delete.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEpE,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAuC9E"}
1
+ {"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/delete.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEpE,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA8B9E"}
@@ -1,34 +1,28 @@
1
- import { buildTenantDeleteWhere, assertTenantOwnsAll } from '../../tenant.js';
1
+ import { buildTenantRowGuard, assertTenantOwnsAll } from '../../tenant.js';
2
2
  import { httpError } from '../../errors.js';
3
3
  import { primaryAsString, isCompositePrimary } from '../../../types.js';
4
4
  export async function deleteEngine(params) {
5
5
  const { db, tableConf, id, tenant, request } = params;
6
6
  if (isCompositePrimary(tableConf.primary)) {
7
- throw httpError(400, `Table "${tableConf.Schema.tableName}" has a composite primary key: delete-by-id would match on "${primaryAsString(tableConf.primary)}" alone and could remove multiple rows. Use a custom query.`);
7
+ throw httpError(400, `Table "${tableConf.schema.tableName}" has a composite primary key: delete-by-id would match on "${primaryAsString(tableConf.primary)}" alone and could remove multiple rows. Use a custom query.`);
8
8
  }
9
9
  const pk = primaryAsString(tableConf.primary);
10
- const pkCol = tableConf.Schema.col(pk);
11
- const tableName = tableConf.Schema.tableName;
10
+ const pkCol = tableConf.schema.col(pk);
11
+ const tableName = tableConf.schema.tableName;
12
12
  if (tableConf.beforeDelete) {
13
13
  // Enforce tenant ownership before the hook so it never runs for rows the tenant
14
14
  // cannot access. (When no hook is defined, the tenant-scoped DELETE below already
15
15
  // prevents deleting non-owned rows, so the extra SELECT is skipped.)
16
- await assertTenantOwnsAll(db, tenant, tableName, pkCol, [id]);
17
- await tableConf.beforeDelete(db, request, id);
18
- }
19
- if (!tenant) {
20
- const affectedRows = await db.delete(tableName, { [pkCol]: id });
21
- if (affectedRows === 0)
22
- throw httpError(404, `Record not found: ${id}`);
23
- }
24
- else {
25
- const { where, values } = buildTenantDeleteWhere(db, tableName, pkCol, id, tenant);
26
- const result = await db.query(`DELETE FROM ${db.qi(tableName)} WHERE ${where}`, values);
27
- if (result.affectedRows === 0)
28
- throw httpError(404, `Record not found: ${id}`);
16
+ await assertTenantOwnsAll(db, tenant, tableName, [pkCol], [[id]]);
17
+ await tableConf.beforeDelete({ db, req: request, id });
29
18
  }
19
+ // The tenant's guard, when the table is scoped, joins the key in the same DELETE: a row the
20
+ // caller does not own is not deleted, and answers 404 like a missing one.
21
+ const affectedRows = await db.delete(tableName, { [pkCol]: id }, buildTenantRowGuard(db, tenant, tableName));
22
+ if (affectedRows === 0)
23
+ throw httpError(404, `Record not found: ${id}`);
30
24
  if (tableConf.afterDelete) {
31
- await tableConf.afterDelete(db, request, id);
25
+ await tableConf.afterDelete({ db, req: request, id });
32
26
  }
33
27
  return { main: { [pk]: id } };
34
28
  }
@@ -8,26 +8,26 @@ import { primaryAsString, isCompositePrimary } from '../../../types.js';
8
8
  export async function getEngine(params) {
9
9
  const { db, tableConf, id, tenant, request } = params;
10
10
  if (isCompositePrimary(tableConf.primary)) {
11
- throw httpError(400, `Table "${tableConf.Schema.tableName}" has a composite primary key: get-by-id would match on "${primaryAsString(tableConf.primary)}" alone. Use search with all PK fields.`);
11
+ throw httpError(400, `Table "${tableConf.schema.tableName}" has a composite primary key: get-by-id would match on "${primaryAsString(tableConf.primary)}" alone. Use search with all PK fields.`);
12
12
  }
13
- const pkCol = tableConf.Schema.col(primaryAsString(tableConf.primary));
13
+ const pkCol = tableConf.schema.col(primaryAsString(tableConf.primary));
14
14
  const cb = new ConditionBuilder('AND', db.cbDialect);
15
15
  // Table-qualified: the tenant scope may add a through-join, and a bare PK column
16
16
  // shared with the through table would be ambiguous.
17
- cb.isEqual(`${db.qi(tableConf.Schema.tableName)}.${db.qi(pkCol)}`, id);
17
+ cb.isEqual(`${db.qi(tableConf.schema.tableName)}.${db.qi(pkCol)}`, id);
18
18
  const joins = [];
19
19
  if (tenant?.scope) {
20
20
  const scope = tenant.scope;
21
- cb.append(buildTenantCondition(db, scope, tenant.ids, tableConf.Schema.tableName));
21
+ cb.append(buildTenantCondition(db, scope, tenant.ids, tableConf.schema.tableName));
22
22
  if ('through' in scope) {
23
- joins.push(buildTenantJoin(db, scope, tableConf.Schema.tableName));
23
+ joins.push(buildTenantJoin(db, scope, tableConf.schema.tableName));
24
24
  }
25
25
  }
26
26
  const where = cb.build(1, db.ph);
27
27
  const values = cb.getValues();
28
28
  const rows = await db.select({
29
- tableName: tableConf.Schema.tableName,
30
- columns: readableSelectColumns(tableConf, tableConf.Schema, db),
29
+ tableName: tableConf.schema.tableName,
30
+ columns: readableSelectColumns(tableConf, tableConf.schema, db),
31
31
  where,
32
32
  values,
33
33
  limit: '1',
@@ -35,7 +35,7 @@ export async function getEngine(params) {
35
35
  });
36
36
  if (rows.length === 0)
37
37
  throw httpError(404, `Record not found: ${id}`);
38
- const main = camelcaseObject(rows[0], tableConf.Schema);
38
+ const main = camelcaseObject(rows[0], tableConf.schema);
39
39
  await runAfterRead(db, request, [main], tableConf, 'get');
40
40
  return { main };
41
41
  }
@@ -1 +1 @@
1
- {"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAoE9E"}
1
+ {"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAIb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA+E9E"}
@@ -1,50 +1,63 @@
1
1
  import { camelcaseObject } from '../../naming.js';
2
- import { processSecondaries, prepareInsertRecord, assertUpsertKeys } from '../write-helpers.js';
2
+ import { processSecondaries, prepareInsertRecord, assertUpsertKeys, assertWriteJoinAliases, hasAliases, assertExcludedKeysExist, insertExcludedKeyFields, } from '../write-helpers.js';
3
3
  import { enforceTenantOnWrites, assertTenantOwnsConflicts } from '../../tenant.js';
4
4
  import { primaryAsCols } from '../../../types.js';
5
5
  export async function insertEngine(params) {
6
- const { db, tableConf, dbTables, request, record, secondaries, tenant } = params;
7
- const schema = tableConf.Schema;
6
+ const { db, tableConf, dbTables, request, record, upsert, replace, tenant } = params;
7
+ const children = { upsert, replace };
8
+ const schema = tableConf.schema;
8
9
  // Full primary key columns (composite PKs need every column for RETURNING /
9
10
  // mysql synthesis, otherwise the response is missing PK fields).
10
11
  const pkCol = primaryAsCols(tableConf.primary, (f) => schema.col(f));
12
+ assertWriteJoinAliases(tableConf, children);
11
13
  // 1. Validate, run beforeInsert hook, snakecase, drop excluded fields.
12
- const { camel: inputRecord, snake: mainRecord } = await prepareInsertRecord({ db, tableConf, request }, record, secondaries);
13
- // Steps 2-5 are atomic: a failure in secondaries or afterInsert rolls back the
14
- // main insert too. Degrades to non-transactional when the adapter has no connect().
14
+ const { camel: inputRecord, snake: mainRecord } = await prepareInsertRecord({ db, tableConf, dbTables, request }, record, children);
15
+ // Steps 2-5 are atomic: a failure in the child rows or afterInsert rolls back the
16
+ // main insert too. An adapter without connect() cannot run this at all (ADR 0023).
15
17
  return db.withTransaction(async (tx) => {
16
18
  // 2. Tenant: inject (direct) or validate FK (indirect) — enforced after user mutations
17
19
  await enforceTenantOnWrites(tx, tenant, [mainRecord]);
18
- // 3. Insert main → returns PK-only
19
- let pkResult;
20
- const upsertKeys = tableConf.upsertMap?.get(schema);
20
+ // 3. Insert main → its PK, and what the statement did to the row
21
+ let written;
22
+ const upsertKeys = tableConf.upsertKey;
21
23
  if (upsertKeys) {
22
24
  const conflictCols = upsertKeys.map((k) => schema.col(k));
23
25
  assertUpsertKeys(schema, conflictCols, [pkCol].flat(), [mainRecord]);
26
+ await assertExcludedKeysExist(tx, schema, conflictCols, insertExcludedKeyFields(tableConf, upsertKeys), [mainRecord], [record], (_, field) => `main.${field}`);
24
27
  // Tenant isolation: a conflicting upsert must not overwrite a row owned by another tenant.
25
28
  await assertTenantOwnsConflicts(tx, tenant, schema.tableName, conflictCols, [mainRecord]);
26
- pkResult = await tx.insertOrUpdate(schema.tableName, mainRecord, conflictCols, pkCol);
29
+ written = await tx.upsert(schema.tableName, mainRecord, conflictCols, pkCol);
27
30
  }
28
31
  else {
29
- pkResult = await tx.insert(schema.tableName, mainRecord, pkCol);
32
+ const pk = await tx.insert(schema.tableName, mainRecord, pkCol);
33
+ written = { pk, action: 'inserted' };
30
34
  }
31
- const mainPkCamel = camelcaseObject(pkResult, schema);
32
- // 4. Secondaries: need full record for FK auto-fill (camelCase)
35
+ const mainPkCamel = camelcaseObject(written.pk, schema);
36
+ // 4. Child rows: need full record for FK auto-fill (camelCase). A `replace` also removes
37
+ // the child rows the request left out — an upserted main row may have some (ADR 0029).
33
38
  let secondaryResults;
34
- if (secondaries && Object.keys(secondaries).length > 0) {
39
+ let deletionResults;
40
+ if (hasAliases(upsert, replace)) {
35
41
  const mainForFK = { ...inputRecord, ...mainPkCamel };
36
- secondaryResults = await processSecondaries({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, secondaries);
42
+ const outcome = await processSecondaries({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, children);
43
+ secondaryResults = outcome.written;
44
+ if (Object.keys(outcome.removed).length > 0)
45
+ deletionResults = outcome.removed;
37
46
  }
38
47
  // 5. afterInsert hook (camelCase — input merged with generated PK)
39
48
  if (tableConf.afterInsert) {
40
49
  const mainForHook = { ...inputRecord, ...mainPkCamel };
41
- await tableConf.afterInsert(tx, request, mainForHook, secondaryResults);
50
+ await tableConf.afterInsert({
51
+ db: tx, req: request, record: mainForHook, secondaries: secondaryResults, deletions: deletionResults,
52
+ });
42
53
  }
43
- // 6. Return PK-only
44
- const result = { main: mainPkCamel };
54
+ // 6. Return the PK and the action
55
+ const result = { main: mainPkCamel, action: written.action };
45
56
  if (secondaryResults && Object.keys(secondaryResults).length > 0) {
46
57
  result.secondaries = secondaryResults;
47
58
  }
59
+ if (deletionResults)
60
+ result.deletions = deletionResults;
48
61
  return result;
49
62
  });
50
63
  }
@@ -1 +1 @@
1
- {"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/update.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAiC3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA+G9E"}
1
+ {"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/update.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAiC3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA2H9E"}
@@ -1,8 +1,8 @@
1
1
  import { snakecaseRecord } from '../../naming.js';
2
2
  import { removeWriteExcluded } from '../../write-access.js';
3
- import { processSecondaries, processDeletions } from '../write-helpers.js';
3
+ import { processSecondaries, processDeletions, assertWriteJoinAliases, hasAliases } from '../write-helpers.js';
4
4
  import { stripTenantColumn, assertTenantOwnership, buildTenantUpdateExtra, enforceTenantFKOnUpdate, } from '../../tenant.js';
5
- import { runValidation } from '../validate.js';
5
+ import { runValidation, runChildValidation } from '../validate.js';
6
6
  import { httpError } from '../../errors.js';
7
7
  /**
8
8
  * Confirm the row exists — and is visible to this tenant — when the request carries no
@@ -27,25 +27,32 @@ async function assertRecordExists(tx, tableName, pkCols, pkValues, extraConditio
27
27
  throw httpError(404, `Record not found`);
28
28
  }
29
29
  export async function updateEngine(params) {
30
- const { db, tableConf, dbTables, request, record, secondaries, deletions, tenant } = params;
31
- const schema = tableConf.Schema;
30
+ const { db, tableConf, dbTables, request, record, upsert, delete: toDelete, replace, tenant } = params;
31
+ const children = { upsert, replace };
32
+ const schema = tableConf.schema;
32
33
  // Every primary key field/column: composite PKs must match on ALL columns, otherwise an
33
34
  // UPDATE keyed on the first column alone would hit every row sharing that value.
34
35
  const pkFields = Array.isArray(tableConf.primary) ? tableConf.primary : [tableConf.primary];
35
36
  const pkCols = pkFields.map((f) => schema.col(f));
36
37
  const pkValues = pkFields.map((f) => record[f]);
38
+ assertWriteJoinAliases(tableConf, { upsert, delete: toDelete, replace });
37
39
  const missingIdx = pkValues.findIndex((v) => v == null);
38
- if (missingIdx !== -1)
39
- throw httpError(400, `Primary key "${pkFields[missingIdx]}" is required`);
40
+ if (missingIdx !== -1) {
41
+ throw httpError(400, `Primary key "${pkFields[missingIdx]}" is required`, {
42
+ code: 'required',
43
+ path: `main.${pkFields[missingIdx]}`,
44
+ });
45
+ }
40
46
  // 1. Tenant ownership check (indirect) — do it early so user mutations don't run on records they can't access
41
47
  await assertTenantOwnership(db, tenant, schema.tableName, pkCols, pkValues);
42
48
  // 2. Mutable copy of input in camelCase
43
49
  const inputRecord = { ...record };
44
50
  // 3. Custom validation (camelCase)
45
- await runValidation(db, request, tableConf, inputRecord, secondaries);
51
+ await runValidation(db, request, tableConf, inputRecord, children);
52
+ await runChildValidation({ db, request, tableConf, dbTables }, record, children);
46
53
  // 4. beforeUpdate hook (camelCase — user can mutate with schema field names)
47
54
  if (tableConf.beforeUpdate) {
48
- await tableConf.beforeUpdate(db, request, inputRecord);
55
+ await tableConf.beforeUpdate({ db, req: request, record: inputRecord });
49
56
  }
50
57
  // 5. Drop what the database will not be told about (generated columns, writeExclude).
51
58
  // After the hook on purpose: the column refuses a value whoever assigned it.
@@ -62,8 +69,8 @@ export async function updateEngine(params) {
62
69
  stripTenantColumn(updateFields, tenant.scope);
63
70
  await enforceTenantFKOnUpdate(db, tenant, updateFields);
64
71
  }
65
- // Steps 8-10 are atomic: a failure in secondaries or deletions rolls back the main
66
- // update too. Degrades to non-transactional when the adapter has no connect().
72
+ // Steps 8-10 are atomic: a failure in the child rows rolls back the main
73
+ // update too. An adapter without connect() cannot run this at all (ADR 0023).
67
74
  return db.withTransaction(async (tx) => {
68
75
  // 8. Update main
69
76
  const hasFieldsToUpdate = Object.keys(updateFields).length > 0;
@@ -80,21 +87,31 @@ export async function updateEngine(params) {
80
87
  }
81
88
  // Build the main response (PK-only — every PK field)
82
89
  const mainResult = Object.fromEntries(pkFields.map((f, i) => [f, pkValues[i]]));
83
- // 9. Secondaries (upsert/insert with FK auto-fill — camelCase)
90
+ // 9. Child rows to write (`upsert` and `replace`, FK auto-filled — camelCase); a `replace`
91
+ // also removes the child rows the request left out (ADR 0029)
84
92
  let secondaryResults;
85
- if (secondaries && Object.keys(secondaries).length > 0) {
93
+ let replaced = {};
94
+ if (hasAliases(upsert, replace)) {
86
95
  const mainForFK = { ...inputRecord };
87
- secondaryResults = await processSecondaries({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, secondaries);
96
+ ({ written: secondaryResults, removed: replaced } = await processSecondaries({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, children));
88
97
  }
89
- // 10. Deletions (FK auto-fill from main like secondaries)
98
+ // 10. Child rows to delete (FK auto-fill from main), then the rows a replace removed
90
99
  let deletionResults;
91
- if (deletions && Object.keys(deletions).length > 0) {
100
+ if (hasAliases(toDelete)) {
92
101
  const mainForFK = { ...inputRecord };
93
- deletionResults = await processDeletions({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, deletions);
102
+ deletionResults = await processDeletions({ db: tx, tableConf, dbTables, mainRecord: mainForFK, tenant, request }, toDelete ?? {});
94
103
  }
104
+ if (Object.keys(replaced).length > 0)
105
+ deletionResults = { ...deletionResults, ...replaced };
95
106
  // 11. afterUpdate hook (inside the transaction: throwing rolls everything back)
96
107
  if (tableConf.afterUpdate) {
97
- await tableConf.afterUpdate(tx, request, inputRecord, secondaryResults, deletionResults);
108
+ await tableConf.afterUpdate({
109
+ db: tx,
110
+ req: request,
111
+ record: inputRecord,
112
+ secondaries: secondaryResults,
113
+ deletions: deletionResults,
114
+ });
98
115
  }
99
116
  // 12. Return PK-only
100
117
  const result = { main: mainResult };
@@ -10,7 +10,7 @@
10
10
  import { Expression } from 'node-condition-builder';
11
11
  import type { QueryClient } from '../../db.js';
12
12
  import type { QueryParams } from '../query-params.js';
13
- import type { DbTables, ITable, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
13
+ import type { DbTables, TableConfig, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
14
14
  /**
15
15
  * One aggregation function, as SQL. `zeroWhenEmpty`: over no rows it means 0 (nothing counted,
16
16
  * nothing summed), so the correlated subquery coalesces its NULL to 0. min/max/avg over no rows
@@ -34,7 +34,7 @@ export declare function aggExpr(fn: AggFn, qualifiedCol: string): string;
34
34
  * child rows of other tenants, disagreeing with the scoped `result.joinGroup` for the same
35
35
  * alias and leaking their existence.
36
36
  */
37
- export declare function buildAggOrderExpr(db: QueryClient, dbTables: DbTables, tableConf: ITable, alias: string, fn: string, field: string, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext): Expression;
37
+ export declare function buildAggOrderExpr(db: QueryClient, dbTables: DbTables, tableConf: TableConfig, alias: string, fn: string, field: string, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext, at?: string): Expression;
38
38
  /** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */
39
- export declare function appendAggConditions(params: QueryParams, conditions: SearchCondition[], db: QueryClient, dbTables: DbTables, tableConf: ITable, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext): string;
39
+ export declare function appendAggConditions(params: QueryParams, conditions: SearchCondition[], db: QueryClient, dbTables: DbTables, tableConf: TableConfig, joinGroup: Record<string, JoinGroupRequest> | undefined, tenant?: TenantContext): string;
40
40
  //# sourceMappingURL=aggregations.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE;AAEjF,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAOxC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,UAAU,CAiEZ;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,eAAe,EAAE,EAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAyBR"}
1
+ {"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE;AAEjF,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAOxC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,EACtB,EAAE,SAAK,GACN,UAAU,CAoEZ;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,eAAe,EAAE,EAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CA0BR"}