fastify-auto-sqlapi 0.5.1 → 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 +246 -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 +93 -27
  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 -64
  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 +25 -16
  91. package/dist/lib/read-access.d.ts.map +1 -1
  92. package/dist/lib/read-access.js +33 -17
  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,9 +1,20 @@
1
- import type { DialectName } from '../lib/dialect.js';
2
- export interface SqlApiConfig {
3
- outputDir: string;
1
+ /**
2
+ * `sqlapi.config.ts`, read by the CLI only — never at runtime:
3
+ * `export default { outputDir: './src/db' } satisfies CliConfig`. Every key is optional; an
4
+ * unknown one is an error. The `.env` of the current directory is loaded before this file.
5
+ */
6
+ export interface CliConfig {
7
+ /**
8
+ * The database `sqlapi-generate-schema` introspects, as a URL whose scheme names the dialect:
9
+ * `postgres://` (or `postgresql://`), `mysql://`, `mariadb://`. Typically read from the
10
+ * environment, `connection: process.env.SHOP_DB_URL`, so the password stays out of the file.
11
+ * `--url` wins over it; without either, `DATABASE_URL` is used. Present but empty is an error.
12
+ */
13
+ connection?: string;
14
+ /** Where `schemas/` and `tables/` are generated. Default `./src/db`. */
15
+ outputDir?: string;
16
+ /** The PostgreSQL schema to introspect. Default `public`; MySQL/MariaDB use the URL's database. */
4
17
  schema?: string;
5
- dialect?: DialectName;
6
- envFile?: string;
7
18
  /**
8
19
  * Tables to skip during schema generation (`sqlapi-generate-schema`).
9
20
  * Matched against the DB table name; `*` is a wildcard (e.g. "knex_*").
@@ -33,7 +44,7 @@ export interface ColumnInfo {
33
44
  * True for columns the database fills in by itself without a visible `column_default`:
34
45
  * MySQL `AUTO_INCREMENT` and PostgreSQL `GENERATED ... AS IDENTITY`. Both behave like a
35
46
  * default — omit the column and the value appears — so the generated field is Optional and
36
- * the CLI lists it under `excludeFromCreation`.
47
+ * the CLI lists it under `insertExclude`.
37
48
  */
38
49
  is_auto_increment?: boolean;
39
50
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;QAChB;;;WAGG;QACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;KACzB,CAAC;CACH"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;QAChB;;;WAGG;QACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;KACzB,CAAC;CACH"}
@@ -1,4 +1,4 @@
1
- import type { TSchema } from '@sinclair/typebox';
1
+ import type { TSchema } from 'typebox';
2
2
  import type { QueryClient } from '../lib/db.js';
3
3
  /**
4
4
  * Context passed to ComputedFieldFn when the engine resolves a computed field.
@@ -1 +1 @@
1
- {"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/types/computed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,iBAAiB,CAAC"}
1
+ {"version":3,"file":"computed.d.ts","sourceRoot":"","sources":["../../src/types/computed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,WAAW,CAAC;IAChB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,iBAAiB,CAAC"}
@@ -1,4 +1,6 @@
1
- import type { ConditionBuilder as CB } from 'node-condition-builder';
1
+ import type { ConditionBuilder as CB, ConditionValueOrUndefined } from 'node-condition-builder';
2
+ /** Search filters by field name, as the request and `extendedCondition` see them. */
3
+ export type FilterRecord = Record<string, ConditionValueOrUndefined>;
2
4
  type SingleValueMethods = 'isEqual' | 'isNotEqual' | 'isGreater' | 'isNotGreater' | 'isGreaterOrEqual' | 'isNotGreaterOrEqual' | 'isLess' | 'isNotLess' | 'isLessOrEqual' | 'isNotLessOrEqual' | 'isLike' | 'isNotLike' | 'isILike' | 'isNotILike';
3
5
  type BetweenMethods = 'isBetween' | 'isNotBetween';
4
6
  type InMethods = 'isIn' | 'isNotIn';
@@ -1 +1 @@
1
- {"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/types/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,IAAI,EAAE,EAAE,MAAM,wBAAwB,CAAC;AAGrE,KAAK,kBAAkB,GACnB,SAAS,GAAG,YAAY,GACxB,WAAW,GAAG,cAAc,GAAG,kBAAkB,GAAG,qBAAqB,GACzE,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,kBAAkB,GAC7D,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AAGtD,KAAK,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAGnD,KAAK,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAGpC,KAAK,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAG5F,KAAK,eAAe,CAAC,CAAC,SAAS,eAAe,IAC5C,CAAC,SAAS,kBAAkB,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC5D,CAAC,SAAS,cAAc,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjF,CAAC,SAAS,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpD,CAAC,SAAS,WAAW,GAAG,EAAE,GAC1B,KAAK,CAAC;AAER,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;KACtD,CAAC,IAAI,eAAe,GAAG;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;KAAE;CAC5E,CAAC,eAAe,CAAC,CAAC"}
1
+ {"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../src/types/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,IAAI,EAAE,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAEhG,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;AAGrE,KAAK,kBAAkB,GACnB,SAAS,GAAG,YAAY,GACxB,WAAW,GAAG,cAAc,GAAG,kBAAkB,GAAG,qBAAqB,GACzE,QAAQ,GAAG,WAAW,GAAG,eAAe,GAAG,kBAAkB,GAC7D,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AAGtD,KAAK,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAGnD,KAAK,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAGpC,KAAK,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1C,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAG5F,KAAK,eAAe,CAAC,CAAC,SAAS,eAAe,IAC5C,CAAC,SAAS,kBAAkB,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC5D,CAAC,SAAS,cAAc,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjF,CAAC,SAAS,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpD,CAAC,SAAS,WAAW,GAAG,EAAE,GAC1B,KAAK,CAAC;AAER,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;KACtD,CAAC,IAAI,eAAe,GAAG;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;KAAE;CAC5E,CAAC,eAAe,CAAC,CAAC"}
@@ -12,14 +12,54 @@ export interface TransactionQueryable extends Queryable {
12
12
  export interface Queryable {
13
13
  query<T = Record<string, unknown>>(text: string, values?: unknown[]): Promise<SqlResult<T>>;
14
14
  /**
15
- * Optional: check out a dedicated connection for `QueryClient.withTransaction`.
16
- * When absent, `withTransaction` degrades to running its callback without
17
- * transactional guarantees (legacy custom adapters keep working unchanged).
15
+ * Check out a dedicated connection for `QueryClient.withTransaction`. Optional in the type
16
+ * because a read-only client needs none, but every insert and update runs in a transaction:
17
+ * without `connect()` they fail with an explicit error instead of running unprotected
18
+ * (ADR 0023). The built-in adapters provide it from a pool.
18
19
  */
19
20
  connect?(): Promise<TransactionQueryable>;
20
21
  }
21
- export type DbRecordValue = string | number | boolean | null | Expression;
22
+ /**
23
+ * A value the QueryClient binds. `Date` is handed to the driver as is (pg and mysql2 both
24
+ * convert it). A JSON object or array is not: pg sends an array as a Postgres array literal
25
+ * and mysql2 expands an object into `key = value` pairs — `JSON.stringify` it first.
26
+ */
27
+ export type DbRecordValue = string | number | boolean | null | Date | Expression;
22
28
  export type DbRecord = Record<string, DbRecordValue>;
29
+ /**
30
+ * A primary key as a request names a row: the value itself for a single-column key, an object
31
+ * naming every key field for a composite one (`{ postId: 1, tagId: 2 }`).
32
+ */
33
+ export type PrimaryKeyValue = string | number | Record<string, string | number>;
34
+ /** What a write that may be an upsert did to a row. */
35
+ export type WriteAction = 'inserted' | 'updated';
36
+ /** A written row: its primary key columns, and whether the statement inserted or updated it. */
37
+ export interface WrittenRow {
38
+ pk: Record<string, unknown>;
39
+ action: WriteAction;
40
+ }
41
+ /**
42
+ * Rows grouped by relation alias: the `upsert`, `delete` and `replace` sections of a write
43
+ * request, the rows written (`secondaries`) and removed (`deletions`) as a write answers them
44
+ * and hands them to `afterInsert`/`afterUpdate`, and `joinMultiple` / `joinLeft` in a search
45
+ * result. Rows are camelCase.
46
+ */
47
+ export type RowsByAlias = Record<string, Record<string, unknown>[]>;
48
+ /**
49
+ * The child rows a write request carries, by write-join alias, one section per action
50
+ * (ADR 0029). An alias appears in one section at most.
51
+ */
52
+ export interface WriteJoinSections {
53
+ /** Child rows to write: inserted, or upserted on the relation's `upsertKey`. Others stay. */
54
+ upsert?: RowsByAlias;
55
+ /** Child rows to delete, named by their key (the FK to the main row is filled in). Update only. */
56
+ delete?: RowsByAlias;
57
+ /**
58
+ * The complete set of child rows: upserted on the relation's `upsertKey`, and every other
59
+ * child row of the main row deleted. `[]` deletes them all. Needs the relation's `upsertKey`.
60
+ */
61
+ replace?: RowsByAlias;
62
+ }
23
63
  export interface SelectOptions {
24
64
  tableName: string;
25
65
  columns?: string;
@@ -1 +1 @@
1
- {"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/types/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAqB,SAAQ,SAAS;IACrD,uEAAuE;IACvE,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,UAAU,CAAC;AAEf,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
1
+ {"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/types/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACpD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAqB,SAAQ,SAAS;IACrD,uEAAuE;IACvE,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,IAAI,GACJ,UAAU,CAAC;AAEf,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAEhF,uDAAuD;AACvD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjD,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mGAAmG;IACnG,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
@@ -1,33 +1,40 @@
1
1
  import type { ApiRequest } from './request.js';
2
2
  import type { QueryClient } from '../lib/db.js';
3
- import type { ITable, DbTables } from './table.js';
3
+ import type { TableConfig, DbTables } from './table.js';
4
4
  import type { TenantContext } from './tenant.js';
5
+ import type { RowsByAlias } from './db.js';
6
+ import type { WriteAction, PrimaryKeyValue, WriteJoinSections } from './db.js';
5
7
  interface DmlBaseParams {
6
8
  db: QueryClient;
7
- tableConf: ITable;
9
+ tableConf: TableConfig;
8
10
  tenant?: TenantContext;
9
11
  }
10
12
  interface DmlWriteBaseParams extends DmlBaseParams {
11
13
  dbTables: DbTables;
12
- request: ApiRequest;
14
+ /** Handed to hooks and validators as `ctx.req`; absent for a programmatic caller that did not pass one. */
15
+ request?: ApiRequest;
13
16
  }
14
- export interface InsertParams extends DmlWriteBaseParams {
17
+ export interface InsertParams extends DmlWriteBaseParams, Omit<WriteJoinSections, 'delete'> {
15
18
  record: Record<string, unknown>;
16
- secondaries?: Record<string, Record<string, unknown>[]>;
17
19
  }
18
20
  export interface InsertResult {
19
21
  main: Record<string, unknown>;
20
- secondaries?: Record<string, Record<string, unknown>[]>;
22
+ /** `'updated'` when an upsert rule landed the write on an existing row, else `'inserted'`. */
23
+ action: WriteAction;
24
+ /** The child rows written, by alias: those of `upsert` and of `replace`. */
25
+ secondaries?: RowsByAlias;
26
+ /** The child rows a `replace` removed, by alias (ADR 0029). */
27
+ deletions?: RowsByAlias;
21
28
  }
22
- export interface UpdateParams extends DmlWriteBaseParams {
29
+ export interface UpdateParams extends DmlWriteBaseParams, WriteJoinSections {
23
30
  record: Record<string, unknown>;
24
- secondaries?: Record<string, Record<string, unknown>[]>;
25
- deletions?: Record<string, Record<string, unknown>[]>;
26
31
  }
27
32
  export interface UpdateResult {
28
33
  main: Record<string, unknown>;
29
- secondaries?: Record<string, Record<string, unknown>[]>;
30
- deletions?: Record<string, Record<string, unknown>[]>;
34
+ /** The child rows written, by alias: those of `upsert` and of `replace`. */
35
+ secondaries?: RowsByAlias;
36
+ /** The child rows removed, by alias: those of `delete`, and those a `replace` left out. */
37
+ deletions?: RowsByAlias;
31
38
  }
32
39
  export interface GetParams extends DmlBaseParams {
33
40
  id: string | number;
@@ -44,21 +51,23 @@ export interface DeleteParams extends DmlBaseParams {
44
51
  export interface DeleteResult {
45
52
  main: Record<string, unknown>;
46
53
  }
47
- export interface BulkUpsertItem {
54
+ export interface BulkUpsertItem extends WriteJoinSections {
48
55
  main: Record<string, unknown>;
49
- secondaries?: Record<string, Record<string, unknown>[]>;
50
- deletions?: Record<string, Record<string, unknown>[]>;
51
56
  }
52
57
  export interface BulkUpsertParams extends DmlWriteBaseParams {
53
58
  items: BulkUpsertItem[];
54
59
  }
55
60
  export interface BulkUpsertResult {
56
61
  main: Record<string, unknown>;
57
- secondaries?: Record<string, Record<string, unknown>[]>;
58
- deletions?: Record<string, Record<string, unknown>[]>;
62
+ /** What the statement did to this item's main row; `'inserted'` for every item without an upsert rule. */
63
+ action: WriteAction;
64
+ /** The child rows written, by alias: those of `upsert` and of `replace`. */
65
+ secondaries?: RowsByAlias;
66
+ /** The child rows removed, by alias: those of `delete`, and those a `replace` left out. */
67
+ deletions?: RowsByAlias;
59
68
  }
60
69
  export interface BulkDeleteParams extends DmlBaseParams {
61
- ids: (string | number)[];
70
+ ids: PrimaryKeyValue[];
62
71
  request?: ApiRequest;
63
72
  }
64
73
  export interface BulkDeleteResult {
@@ -1 +1 @@
1
- {"version":3,"file":"dml.d.ts","sourceRoot":"","sources":["../../src/types/dml.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"dml.d.ts","sourceRoot":"","sources":["../../src/types/dml.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,62 @@
1
+ import type { TSchema, Static } from 'typebox';
2
+ import type { Expression } from 'node-condition-builder';
3
+ import type { ApiRequest } from './request.js';
4
+ import type { QueryClient } from '../lib/db.js';
5
+ import type { RowsByAlias, PrimaryKeyValue } from './db.js';
6
+ /**
7
+ * What every hook and validator of a table config receives: one object, so a new piece of
8
+ * information is a new property rather than a new positional parameter, and so the request
9
+ * is typed as what it is.
10
+ *
11
+ * - `db`: the QueryClient the operation runs on — inside a write, the transaction's client,
12
+ * so a statement the hook issues commits or rolls back with the write.
13
+ * - `req`: the request that triggered the operation. Present through the auto-generated
14
+ * HTTP routes; `undefined` when `sqlApi.*` is called without one (a job, a script, a
15
+ * test). A hook reading `req.user` must guard for it.
16
+ */
17
+ export interface HookContext {
18
+ db: QueryClient;
19
+ req: ApiRequest | undefined;
20
+ }
21
+ /** A camelCase record on its way to the database: fields may carry raw SQL (`db.expression`) or `null`. */
22
+ export type WriteRecord<F extends Record<string, TSchema> = Record<string, TSchema>> = {
23
+ [K in keyof F]?: Static<F[K]> | Expression | null;
24
+ };
25
+ /** `beforeInsert` / `beforeUpdate`: the record about to be written, mutable in place. */
26
+ export interface WriteHookContext<F extends Record<string, TSchema> = Record<string, TSchema>> extends HookContext {
27
+ record: WriteRecord<F>;
28
+ }
29
+ /**
30
+ * `afterInsert`: the input record merged with the generated primary key, the child rows
31
+ * written (`secondaries`: those of `upsert` and `replace`) and removed (`deletions`: those a
32
+ * `replace` left out, plus, in a bulk upsert, the item's `delete`), by alias.
33
+ */
34
+ export interface AfterInsertContext<F extends Record<string, TSchema> = Record<string, TSchema>> extends HookContext {
35
+ record: WriteRecord<F>;
36
+ secondaries?: RowsByAlias;
37
+ deletions?: RowsByAlias;
38
+ }
39
+ /** `afterUpdate`: as `afterInsert`; `deletions` also holds the rows the request's `delete` removed. */
40
+ export type AfterUpdateContext<F extends Record<string, TSchema> = Record<string, TSchema>> = AfterInsertContext<F>;
41
+ /** Which read path produced the rows an `afterRead` hook is handed. */
42
+ export type ReadSource = 'get' | 'search' | 'joinMultiple' | 'joinLeft';
43
+ /** `afterRead`: the camelCase rows a read produced, mutable in place, and where they came from. */
44
+ export interface AfterReadContext extends HookContext {
45
+ rows: Record<string, unknown>[];
46
+ source: ReadSource;
47
+ /** The relation's alias, on the two join sources; absent on `get` and `search`. */
48
+ alias?: string;
49
+ }
50
+ /** `beforeDelete` / `afterDelete`: the primary key of the row. */
51
+ export interface DeleteHookContext extends HookContext {
52
+ id: string | number;
53
+ }
54
+ /**
55
+ * `beforeBulkDelete` / `afterBulkDelete`: the primary keys — those requested before the delete,
56
+ * those actually deleted after it (a subset when some rows did not exist). Values for a
57
+ * single-column key, `{ <field>: value }` objects for a composite one.
58
+ */
59
+ export interface BulkDeleteHookContext extends HookContext {
60
+ ids: PrimaryKeyValue[];
61
+ }
62
+ //# sourceMappingURL=hooks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/types/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,WAAW,CAAC;IAChB,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC;CAC7B;AAED,2GAA2G;AAC3G,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;KACpF,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,IAAI;CAClD,CAAC;AAEF,yFAAyF;AACzF,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW;IAChH,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,WAAW;IAClH,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACvB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,uGAAuG;AACvG,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAEpH,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAC;AAExE,mGAAmG;AACnG,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,GAAG,EAAE,eAAe,EAAE,CAAC;CACxB"}
@@ -0,0 +1 @@
1
+ export {};
@@ -1,22 +1,35 @@
1
1
  import type { SchemaDefinition } from './schema.js';
2
- import type { FilterRecord } from './table.js';
3
- import type { SearchCondition } from './conditions.js';
2
+ import type { FilterRecord, SearchCondition } from './conditions.js';
4
3
  export interface JoinDefinition {
5
4
  joinSchema: SchemaDefinition;
6
5
  joinField: string;
7
6
  mainField: string | string[];
8
7
  alias: string;
9
- selection: string;
8
+ /** Default fields of the joined rows, when the request names none; absent, every readable field. */
9
+ select?: string[];
10
10
  unique: boolean;
11
+ /**
12
+ * The `dbTables` key whose config governs the joined table: its `readExclude`, `tenantScope`,
13
+ * `afterRead`, computed fields and write-side rules apply to the rows this relation reaches.
14
+ * Required only when `dbTables` exposes the joined table under several keys; with one key,
15
+ * that config is used whatever the key is called. Resolved by `resolveJoinTableConf`.
16
+ */
17
+ target?: string;
11
18
  /**
12
19
  * Allowlist of the target table's fields reachable through this relation, when
13
20
  * `buildRelation` was given one. `joinSchema` is already narrowed to it — this is kept
14
21
  * so the engine can tell a restricted relation from a full one, which is what stops the
15
- * default `'*'` selection from falling back to a real `SELECT *`.
22
+ * default projection from falling back to a real `SELECT *`.
16
23
  *
17
24
  * Read joins only: a write join declaring it is rejected by `defineTable`.
18
25
  */
19
26
  fields?: string[];
27
+ /**
28
+ * Upsert the secondaries written through this relation on this key of the joined table
29
+ * (fields, camelCase): `INSERT … ON CONFLICT (<key>) DO UPDATE`. Absent, they are plain
30
+ * INSERTs. Write joins only; checked against the joined schema's keys at startup (ADR 0021).
31
+ */
32
+ upsertKey?: string[];
20
33
  }
21
34
  export interface AggregationRequest {
22
35
  /**
@@ -31,8 +44,11 @@ export interface AggregationRequest {
31
44
  avg?: string[];
32
45
  count?: string[];
33
46
  }
34
- export interface JoinGroupRequest {
35
- aggregations: AggregationRequest;
47
+ /**
48
+ * One `joinGroup` entry: the optional GROUP BY and the aggregate functions, beside the
49
+ * filters and conditions that narrow the children first. At least one function is required.
50
+ */
51
+ export interface JoinGroupRequest extends AggregationRequest {
36
52
  filters?: FilterRecord;
37
53
  conditions?: SearchCondition[];
38
54
  }
@@ -46,8 +62,9 @@ export interface JoinRefFilter {
46
62
  filters?: FilterRecord;
47
63
  conditions?: SearchCondition[];
48
64
  }
49
- /** Per-request override of the per-relation default selection. */
65
+ /** Per-request override of the relation's default projection. */
50
66
  export interface JoinFetchRequest extends JoinRefFilter {
51
- selection?: string;
67
+ /** Fields of the joined rows to return. Absent, the relation's `select`, else every readable field. */
68
+ select?: string[];
52
69
  }
53
70
  //# sourceMappingURL=join.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
1
+ {"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}
@@ -1,15 +1,30 @@
1
1
  import type { ApiRequest, ApiReply } from './request.js';
2
2
  import type { DialectName } from '../lib/dialect.js';
3
- import type { DbTables } from './table.js';
4
- import type { TenantId } from './tenant.js';
3
+ import type { DbTables, TableOperation } from './table.js';
4
+ import type { GetTenantId } from './tenant.js';
5
5
  export interface SwaggerOptions {
6
6
  title?: string;
7
7
  description?: string;
8
8
  version?: string;
9
9
  routePrefix?: string;
10
10
  }
11
+ /** One `dbErrors` entry: the HTTP status and the stable code the client translates. */
12
+ export interface DbErrorMapping {
13
+ status: number;
14
+ code: string;
15
+ }
11
16
  export interface SqlApiPluginOptions {
12
- DbTables: DbTables;
17
+ dbTables: DbTables;
18
+ /**
19
+ * The operations this registration exposes, intersected with each table's own
20
+ * `operations`: a table registers a route only when both allow it. Omitted, every table
21
+ * exposes what its config allows. A read-only surface beside a full one is a second
22
+ * registration with `operations: ['search', 'get']`, its own `prefix` and `decorate: false`.
23
+ *
24
+ * Unlike a table's `operations`, naming a single-PK operation (`get`, `delete`) here does
25
+ * not refuse a composite-PK table: the table is skipped for it.
26
+ */
27
+ operations?: TableOperation[];
13
28
  onRequests?: ((request: ApiRequest, reply: ApiReply) => Promise<void | ApiReply>)[];
14
29
  prefix?: string;
15
30
  swagger?: boolean | SwaggerOptions;
@@ -17,25 +32,20 @@ export interface SqlApiPluginOptions {
17
32
  /**
18
33
  * Resolve the caller's tenant id(s) for this request. Returning one id (or an array, for a
19
34
  * caller who belongs to several tenants) scopes every read and write to rows that tenant owns.
35
+ * Called only when a scoped table is in reach of the request.
20
36
  *
21
- * ⚠️ **Returning `null`/`undefined` means ADMIN — no tenant filtering at all, i.e. full
22
- * cross-tenant access.** "Unauthenticated" and "admin" therefore collapse to the same value.
23
- * The tenant identity is read from the request (typically `request.user`, populated by your own
24
- * auth hook in {@link onRequests}), which this plugin does not set. If that hook is missing,
25
- * mis-ordered, or fails, `request.user` is `undefined` and the common `?? null` pattern yields
26
- * `null` → the request is served as admin. Nothing here fails closed.
27
- *
28
- * To fail closed, make this callback (or the auth hook) **reject when there is no authenticated
29
- * principal** instead of returning `null`, and reserve `null` for a real, authorized superadmin:
37
+ * Unrestricted, cross-tenant access is declared by returning {@link TENANT_ADMIN}. Returning
38
+ * `null`/`undefined` is refused with 401: the tenant identity comes from the request
39
+ * (typically `request.user`, populated by your own auth hook in {@link onRequests}), and an
40
+ * absent one is the signature of a hook that is missing, mis-ordered or failed — never of an
41
+ * admin. `[]` is a caller who belongs to no tenant: 403.
30
42
  *
31
43
  * ```ts
32
- * getTenantId: (req) => {
33
- * if (!req.user) throw app.httpErrors.unauthorized(); // no principal → deny, never admin
34
- * return req.user.isSuperadmin ? null : req.user.organizationId;
35
- * }
44
+ * getTenantId: (req) => (req.user?.isSuperadmin ? TENANT_ADMIN : req.user?.organizationId),
45
+ * // no user → undefined → 401 on scoped tables; unscoped tables never ask
36
46
  * ```
37
47
  */
38
- getTenantId?: (request: ApiRequest) => TenantId | TenantId[] | null | undefined | Promise<TenantId | TenantId[] | null | undefined>;
48
+ getTenantId?: GetTenantId;
39
49
  debug?: boolean;
40
50
  /**
41
51
  * Hard cap on the search page size (the `itemsPerPage` query param), and the row LIMIT applied
@@ -68,16 +78,45 @@ export interface SqlApiPluginOptions {
68
78
  *
69
79
  * Without it the response carries no database detail, and the original error is still
70
80
  * reachable: logged through `request.log.error` under the same `reqId` the body reports as
71
- * `requestId`, and attached as the `cause` of the error a consumer `setErrorHandler`
72
- * receives — which is where policy such as unique-violation → `409` belongs (ADR 0006).
81
+ * `requestId`. A status for a driver code (unique violation → `409`) is `dbErrors`.
73
82
  *
74
83
  * Nothing derives this: not `debug` (whoever registers the plugin decides that one, and
75
84
  * may wire it to an environment variable), not `NODE_ENV`. See ADR 0013.
76
85
  */
77
86
  exposeDebugInfo?: boolean;
87
+ /**
88
+ * Driver error codes answered with an HTTP status instead of the sanitized `500`, keyed by
89
+ * the driver's `err.code` exactly as it arrives — `'23505'` (pg unique_violation),
90
+ * `'ER_DUP_ENTRY'` (mysql2), `'40001'` (serialization failure) — and valued with the status
91
+ * (400–599) and a stable code of the consumer's choosing.
92
+ *
93
+ * The mapping is the consumer's and partial by nature: codes depend on the database and its
94
+ * version, and which ones deserve a status is a product decision, so the plugin ships none
95
+ * and interprets nothing (ADR 0006). A mapped error is answered in the plugin's envelope with
96
+ * the status' reason phrase as `message` and `fields: [{ path: '', code }]`, whatever the
97
+ * status: the client translates the code, the API carries no prose. No driver detail reaches
98
+ * the client (ADR 0013). Every other error stays a `500`.
99
+ *
100
+ * ```ts
101
+ * dbErrors: { '23505': { status: 409, code: 'duplicate' }, '23503': { status: 409, code: 'in_use' } }
102
+ * ```
103
+ *
104
+ * Applies to the auto routes only: `sqlApi.*` throws the driver error as is.
105
+ */
106
+ dbErrors?: Record<string, DbErrorMapping>;
107
+ /**
108
+ * Decorate `app.sqlApi`, this registration's programmatic API, for application code. On by
109
+ * default. The decorator belongs to one registration: when the scope already has a `sqlApi`
110
+ * (another registration of the plugin, or the application's own) startup fails, so a second
111
+ * registration — another prefix, another surface — passes `false`. Its routes run with its
112
+ * own configuration either way; `createSqlApi()` gives application code another instance.
113
+ */
114
+ decorate?: boolean;
78
115
  }
79
116
  /** Default row cap for search (page size and no-paginator LIMIT). Override via `maxItemsPerPage`. */
80
117
  export declare const DEFAULT_MAX_ITEMS_PER_PAGE = 1000;
118
+ /** Page size of a search whose paginator names a `page` but no `itemsPerPage`, capped by `maxItemsPerPage`. */
119
+ export declare const DEFAULT_ITEMS_PER_PAGE = 500;
81
120
  /** Default cap on bulk endpoint array length. Override via `maxBulkItems`. */
82
121
  export declare const DEFAULT_MAX_BULK_ITEMS = 1000;
83
122
  //# sourceMappingURL=plugin.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,GAC3E,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}
1
+ {"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,+GAA+G;AAC/G,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}
@@ -1,4 +1,6 @@
1
1
  /** Default row cap for search (page size and no-paginator LIMIT). Override via `maxItemsPerPage`. */
2
2
  export const DEFAULT_MAX_ITEMS_PER_PAGE = 1000;
3
+ /** Page size of a search whose paginator names a `page` but no `itemsPerPage`, capped by `maxItemsPerPage`. */
4
+ export const DEFAULT_ITEMS_PER_PAGE = 500;
3
5
  /** Default cap on bulk endpoint array length. Override via `maxBulkItems`. */
4
6
  export const DEFAULT_MAX_BULK_ITEMS = 1000;
@@ -12,8 +12,8 @@ import type { FastifyRequest, FastifyReply } from 'fastify';
12
12
  * else, and `.dependency-cruiser.mjs` keeps it that way by refusing a `fastify` import anywhere
13
13
  * under `src/lib/` or `src/types/` but here.
14
14
  *
15
- * It is a plain alias rather than a generic parameter on `ITable`: that type appears bare in
16
- * over a hundred places, and threading `<Req>` through all of them — plus `DbTables`, plus
15
+ * It is a plain alias rather than a generic parameter on `TableConfig`: that type appears bare in
16
+ * over a hundred places, and threading `<Req>` through all of them — plus `dbTables`, plus
17
17
  * every `*Params` — would change the public type surface today for a benefit that only
18
18
  * materialises once the core ships as its own package. See
19
19
  * [ADR 0018](../../docs/adr/0018-one-seam-to-the-http-framework.md).
@@ -1,4 +1,4 @@
1
- import type { TSchema, TObject } from '@sinclair/typebox';
1
+ import type { TSchema, TObject } from 'typebox';
2
2
  export interface SchemaDefinition<T = Record<string, TSchema>> {
3
3
  col(field: string): string;
4
4
  colMap?: Record<string, string>;
@@ -18,8 +18,8 @@ export interface SchemaDefinition<T = Record<string, TSchema>> {
18
18
  /**
19
19
  * The table's unique keys other than the primary key, each as its fields (camelCase), as
20
20
  * introspected from the DB. Set by generated schemas — always, even when empty, so an absent
21
- * property means "not known" rather than "none". `defineTable` verifies every `upsertMap`
22
- * rule against `primaryKey` and these (ADR 0021).
21
+ * property means "not known" rather than "none". `defineTable` verifies every `upsertKey`
22
+ * against `primaryKey` and these (ADR 0021).
23
23
  */
24
24
  uniqueKeys?: string[][];
25
25
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEhD,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}