json-rest-api 1.0.29 → 2.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 (292) hide show
  1. package/LICENSE +10 -670
  2. package/LICENSE-GPL-3.0 +674 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +39 -30
  5. package/docs/API.md +744 -1273
  6. package/docs/GUIDE/01-getting-started.md +338 -0
  7. package/docs/GUIDE/02-resources-and-relationships.md +33 -0
  8. package/docs/GUIDE/03-running-example.md +87 -0
  9. package/docs/GUIDE/04-creating-and-querying.md +181 -0
  10. package/docs/GUIDE/05-belongs-to.md +177 -0
  11. package/docs/GUIDE/06-has-many.md +184 -0
  12. package/docs/GUIDE/07-polymorphic-relationships.md +191 -0
  13. package/docs/GUIDE/08-many-to-many.md +184 -0
  14. package/docs/GUIDE/09-pagination-and-sorting.md +149 -0
  15. package/docs/GUIDE/10-put-and-patch.md +174 -0
  16. package/docs/GUIDE/11-relationship-endpoints.md +174 -0
  17. package/docs/GUIDE/12-field-transformations.md +287 -0
  18. package/docs/GUIDE/13-hooks-and-lifecycle.md +479 -0
  19. package/docs/GUIDE/14-custom-resource-methods.md +125 -0
  20. package/docs/GUIDE/15-query-projections.md +266 -0
  21. package/docs/GUIDE/{GUIDE_X_Autofiltering.md → 16-autofiltering.md} +77 -15
  22. package/docs/GUIDE/{GUIDE_X_Row_Policies.md → 17-row-policies.md} +137 -44
  23. package/docs/GUIDE/18-labels.md +86 -0
  24. package/docs/GUIDE/19-managed-transactions.md +179 -0
  25. package/docs/GUIDE/20-transaction-outcomes.md +207 -0
  26. package/docs/GUIDE/21-schema-and-migrations.md +634 -0
  27. package/docs/GUIDE/22-version-field-migrations.md +208 -0
  28. package/docs/GUIDE/23-fastify.md +179 -0
  29. package/docs/GUIDE/24-cors.md +172 -0
  30. package/docs/GUIDE/{GUIDE_X_URL_Management.md → 25-url-management.md} +7 -1
  31. package/docs/GUIDE/26-file-uploads.md +278 -0
  32. package/docs/GUIDE/27-bulk-operations.md +277 -0
  33. package/docs/GUIDE/28-socketio.md +325 -0
  34. package/docs/GUIDE/29-writing-plugins.md +278 -0
  35. package/docs/GUIDE/30-backend-capabilities.md +100 -0
  36. package/docs/GUIDE/31-positioning.md +181 -0
  37. package/docs/GUIDE/{GUIDE_Y_Appendices.md → 32-date-and-time.md} +74 -30
  38. package/docs/GUIDE/33-migrating-to-v2.md +3827 -0
  39. package/docs/GUIDE/index.md +51 -59
  40. package/docs/QUICKSTART.md +120 -287
  41. package/docs/architecture.md +75 -0
  42. package/docs/contributing.md +178 -0
  43. package/index.d.ts +36 -0
  44. package/index.js +1 -22
  45. package/lib/enhanced-logger.js +91 -85
  46. package/lib/error-context.js +445 -5
  47. package/lib/error-formatter.js +219 -59
  48. package/lib/knex-transaction.js +64 -0
  49. package/lib/logger-types.d.ts +22 -0
  50. package/lib/missing-package.js +4 -0
  51. package/lib/rest-api-errors.js +103 -8
  52. package/lib/runtime/json-rest-api.js +172 -0
  53. package/lib/transaction-types.d.ts +59 -0
  54. package/package.json +97 -27
  55. package/plugins/core/bulk-operations-plugin.js +191 -184
  56. package/plugins/core/connectors/express-plugin.js +148 -219
  57. package/plugins/core/connectors/fastify-plugin.js +125 -82
  58. package/plugins/core/connectors/lib/busboy-detector.js +74 -156
  59. package/plugins/core/connectors/lib/connector-core.js +144 -20
  60. package/plugins/core/connectors/lib/formidable-detector.js +63 -120
  61. package/plugins/core/connectors/lib/http-validators.js +77 -0
  62. package/plugins/core/connectors/lib/multipart-helpers.js +18 -0
  63. package/plugins/core/connectors/lib/request-helpers.js +10 -1
  64. package/plugins/core/connectors/lib/transport-http-helpers.js +89 -8
  65. package/plugins/core/connectors/lib/transport-route-schemas.js +7 -4
  66. package/plugins/core/file-handling-plugin.js +87 -177
  67. package/plugins/core/lib/anyapi/anyapi-registry.js +213 -164
  68. package/plugins/core/lib/anyapi/canonical-link-store.js +507 -0
  69. package/plugins/core/lib/anyapi/canonical-relationship-reader.js +598 -0
  70. package/plugins/core/lib/anyapi/schema-utils.js +25 -16
  71. package/plugins/core/lib/anyapi/utils/descriptor-helpers.js +0 -64
  72. package/plugins/core/lib/dbIntrospection.js +228 -21
  73. package/plugins/core/lib/dbTablesOperations.js +409 -92
  74. package/plugins/core/lib/fractional-positioning.js +12 -48
  75. package/plugins/core/lib/querying/identifier-query.js +19 -0
  76. package/plugins/core/lib/querying/include-query-helpers.js +364 -0
  77. package/plugins/core/lib/querying/include-to-many.js +428 -0
  78. package/plugins/core/lib/querying/include-to-one.js +579 -0
  79. package/plugins/core/lib/querying/knex-cross-table-search.js +31 -307
  80. package/plugins/core/lib/querying/knex-json-api-transformers-querying.js +99 -401
  81. package/plugins/core/lib/querying/knex-pagination-helpers.js +48 -317
  82. package/plugins/core/lib/querying/knex-process-includes.js +5 -110
  83. package/plugins/core/lib/querying/knex-query-helpers-base.js +21 -56
  84. package/plugins/core/lib/querying/knex-query-helpers.js +298 -448
  85. package/plugins/core/lib/querying/knex-relationship-includes.js +120 -2138
  86. package/plugins/core/lib/querying/knex-window-queries.js +62 -253
  87. package/plugins/core/lib/querying/query-builder-utils.js +44 -4
  88. package/plugins/core/lib/querying/query-constraint.d.ts +12 -0
  89. package/plugins/core/lib/querying/query-constraint.js +27 -0
  90. package/plugins/core/lib/querying/query-field-sort-helpers.js +134 -37
  91. package/plugins/core/lib/querying/relationship-identifiers.js +208 -0
  92. package/plugins/core/lib/querying/sort-helpers.js +13 -1
  93. package/plugins/core/lib/querying/storage-adapter-utils.js +13 -5
  94. package/plugins/core/lib/querying/url-helpers.js +11 -4
  95. package/plugins/core/lib/querying-writing/compile-schemas.js +148 -249
  96. package/plugins/core/lib/querying-writing/connectors-query-parser.js +33 -118
  97. package/plugins/core/lib/querying-writing/database-capabilities.js +149 -223
  98. package/plugins/core/lib/querying-writing/database-value-normalizers.js +179 -194
  99. package/plugins/core/lib/querying-writing/default-data-helpers.js +15 -45
  100. package/plugins/core/lib/querying-writing/field-selection-types.d.ts +43 -0
  101. package/plugins/core/lib/querying-writing/field-utils.js +113 -92
  102. package/plugins/core/lib/querying-writing/knex-constants.d.ts +18 -0
  103. package/plugins/core/lib/querying-writing/knex-constants.js +2 -26
  104. package/plugins/core/lib/querying-writing/knex-field-helpers.js +100 -290
  105. package/plugins/core/lib/querying-writing/knex-json-api-transformers.js +31 -120
  106. package/plugins/core/lib/querying-writing/query-field-helpers.js +108 -32
  107. package/plugins/core/lib/querying-writing/query-field-types.d.ts +60 -0
  108. package/plugins/core/lib/querying-writing/relationship-contracts.js +33 -13
  109. package/plugins/core/lib/querying-writing/request-contracts.js +93 -38
  110. package/plugins/core/lib/querying-writing/resource-id-normalization.js +23 -5
  111. package/plugins/core/lib/querying-writing/response-options.js +35 -0
  112. package/plugins/core/lib/querying-writing/schema-helpers.js +203 -324
  113. package/plugins/core/lib/querying-writing/scope-validations.js +92 -290
  114. package/plugins/core/lib/querying-writing/simplified-helpers.js +113 -712
  115. package/plugins/core/lib/storage/canonical-data-helpers.js +683 -0
  116. package/plugins/core/lib/storage/canonical-storage-mapping.js +51 -20
  117. package/plugins/core/lib/storage/ordinary-data-helpers.js +710 -0
  118. package/plugins/core/lib/storage/storage-adapter.js +128 -62
  119. package/plugins/core/lib/storage/storage-mapping.js +78 -28
  120. package/plugins/core/lib/storage/storage-types.d.ts +502 -0
  121. package/plugins/core/lib/writing/many-to-many-manipulations.js +114 -284
  122. package/plugins/core/lib/writing/relationship-processor.js +94 -158
  123. package/plugins/core/lib/writing/resource-version.js +172 -0
  124. package/plugins/core/lib/writing/reverse-relationship-manipulations.js +110 -0
  125. package/plugins/core/rest-api-anyapi-knex-plugin.js +116 -2485
  126. package/plugins/core/rest-api-autofilter-plugin.js +17 -19
  127. package/plugins/core/rest-api-cors-plugin.js +52 -205
  128. package/plugins/core/rest-api-knex-plugin.js +45 -1077
  129. package/plugins/core/rest-api-label-plugin.js +25 -38
  130. package/plugins/core/rest-api-plugin-hooks/register-relationship-routes.js +5 -5
  131. package/plugins/core/rest-api-plugin-hooks/register-scope-routes.js +9 -6
  132. package/plugins/core/rest-api-plugin-hooks/turn-scope-init-into-vars.js +7 -26
  133. package/plugins/core/rest-api-plugin-hooks/validate-include-configurations.js +20 -26
  134. package/plugins/core/rest-api-plugin-methods/add-route.js +4 -6
  135. package/plugins/core/rest-api-plugin-methods/apply-query-filters.js +42 -13
  136. package/plugins/core/rest-api-plugin-methods/check-permissions.js +11 -5
  137. package/plugins/core/rest-api-plugin-methods/common.js +291 -395
  138. package/plugins/core/rest-api-plugin-methods/delete-relationship.js +49 -47
  139. package/plugins/core/rest-api-plugin-methods/delete.js +31 -25
  140. package/plugins/core/rest-api-plugin-methods/enrich-attributes.js +108 -148
  141. package/plugins/core/rest-api-plugin-methods/get-related.js +113 -305
  142. package/plugins/core/rest-api-plugin-methods/get-relationship.js +25 -18
  143. package/plugins/core/rest-api-plugin-methods/get.js +36 -68
  144. package/plugins/core/rest-api-plugin-methods/lifecycle-types.d.ts +225 -0
  145. package/plugins/core/rest-api-plugin-methods/patch-relationship.js +28 -25
  146. package/plugins/core/rest-api-plugin-methods/patch.js +46 -99
  147. package/plugins/core/rest-api-plugin-methods/post-relationship.js +49 -53
  148. package/plugins/core/rest-api-plugin-methods/post.js +51 -51
  149. package/plugins/core/rest-api-plugin-methods/put.js +69 -148
  150. package/plugins/core/rest-api-plugin-methods/query.js +37 -81
  151. package/plugins/core/rest-api-plugin-methods/release.js +2 -1
  152. package/plugins/core/rest-api-plugin.js +32 -46
  153. package/plugins/core/rest-api-positioning-plugin.js +183 -628
  154. package/plugins/core/rest-api-query-projections-plugin.js +19 -102
  155. package/plugins/core/rest-api-row-policy-plugin.js +3 -3
  156. package/plugins/core/socketio-plugin.js +364 -344
  157. package/plugins/storage/local-storage.js +40 -36
  158. package/types/autofilter.d.ts +57 -0
  159. package/types/bulk-methods.d.ts +63 -0
  160. package/types/errors.d.ts +118 -0
  161. package/types/fastify-options.d.ts +19 -0
  162. package/types/file-detectors.d.ts +33 -0
  163. package/types/file-storage.d.ts +48 -0
  164. package/types/hook-context.d.ts +180 -0
  165. package/types/plugin-options.d.ts +53 -0
  166. package/types/relationship-methods.d.ts +74 -0
  167. package/types/representations.d.ts +50 -0
  168. package/types/resource-methods.d.ts +95 -0
  169. package/types/resource-schema.d.ts +157 -0
  170. package/types/row-policy.d.ts +31 -0
  171. package/types/runtime.d.ts +132 -0
  172. package/types/transactions.d.ts +21 -0
  173. package/.claude/agents/library-guide-expert.md +0 -30
  174. package/.claude/agents/rest-api-internals-expert.md +0 -54
  175. package/.claude/settings.local.json +0 -70
  176. package/AGENTS.md +0 -34
  177. package/CLAUDE.md +0 -160
  178. package/CRUSH.md +0 -55
  179. package/JSKIT_BACKEND_MIGRATION_TRACKER.txt +0 -180
  180. package/SINGLE_VALIDATION_CONTRACT_TODO.txt +0 -172
  181. package/TODO.todo +0 -13
  182. package/connectors_ideas/fastify.js +0 -217
  183. package/connectors_ideas/koa-plugin.js +0 -112
  184. package/docs/.bundle/config +0 -2
  185. package/docs/COMPARISON.md +0 -433
  186. package/docs/GUIDE/GUIDE_1_Initial_Setup.md +0 -1057
  187. package/docs/GUIDE/GUIDE_2_1_The_Starting_Point.md +0 -88
  188. package/docs/GUIDE/GUIDE_2_2_Manipulating_And_Searching_Tables.md +0 -808
  189. package/docs/GUIDE/GUIDE_2_3_BelongsTo_Relationships.md +0 -491
  190. package/docs/GUIDE/GUIDE_2_4_HasMany_Records.md +0 -398
  191. package/docs/GUIDE/GUIDE_2_5_HasMany_Polymorphic.md +0 -898
  192. package/docs/GUIDE/GUIDE_2_6_Many_To_Many.md +0 -712
  193. package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md +0 -1247
  194. package/docs/GUIDE/GUIDE_2_8_Effects_of_PUT_and_PATCH.md +0 -748
  195. package/docs/GUIDE/GUIDE_2_9_Relationships_Urls.md +0 -517
  196. package/docs/GUIDE/GUIDE_2_Data_And_Relations.md +0 -66
  197. package/docs/GUIDE/GUIDE_3_Field_Transformations.md +0 -1252
  198. package/docs/GUIDE/GUIDE_5_Non-Db_Resources.md +0 -1107
  199. package/docs/GUIDE/GUIDE_6_Positioning.md +0 -692
  200. package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md +0 -1491
  201. package/docs/GUIDE/GUIDE_X_Bulk_Operations.md +0 -732
  202. package/docs/GUIDE/GUIDE_X_Cors.md +0 -1957
  203. package/docs/GUIDE/GUIDE_X_Fastify.md +0 -78
  204. package/docs/GUIDE/GUIDE_X_File_Uploads.md +0 -729
  205. package/docs/GUIDE/GUIDE_X_Knex_Schema_And_Migrations.md +0 -370
  206. package/docs/GUIDE/GUIDE_X_Query_Projections.md +0 -159
  207. package/docs/GUIDE/GUIDE_X_SocketIO.md +0 -1040
  208. package/docs/GUIDE/GUIDE_X_Writing_Plugins.md +0 -201
  209. package/docs/Gemfile +0 -6
  210. package/docs/Gemfile.lock +0 -308
  211. package/docs/ONBOARDING.md +0 -315
  212. package/docs/_config.yml +0 -36
  213. package/docs/_layouts/default.html +0 -123
  214. package/docs/apple-touch-icon.svg +0 -4
  215. package/docs/assets/css/style.scss +0 -392
  216. package/docs/favicon.svg +0 -4
  217. package/docs/index.md +0 -164
  218. package/docs/mini-guides/file-uploads-complete.md +0 -161
  219. package/eslint.config.js +0 -13
  220. package/examples/url-override-example.js +0 -137
  221. package/fixing_plan.md +0 -112
  222. package/plugins/core/lib/anyapi/query/anyapi-query-adapter.js +0 -657
  223. package/plugins/core/lib/querying-writing/return-record-settings.js +0 -47
  224. package/plugins/core/lib/writing/knex-json-api-transformers-writing.js +0 -110
  225. package/plugins/storage/s3-storage.js +0 -93
  226. package/quickTest.js +0 -136
  227. package/scripts/debug-anyapi-review-filter.mjs +0 -63
  228. package/scripts/inspect-anyapi-descriptor-country.mjs +0 -19
  229. package/scripts/inspect-anyapi-descriptor.mjs +0 -19
  230. package/scripts/run-docs.js +0 -133
  231. package/test-debug.js +0 -59
  232. package/tests/README.md +0 -202
  233. package/tests/TEST_TEMPLATE.test.js +0 -178
  234. package/tests/anyapi-basic.test.js +0 -105
  235. package/tests/anyapi-cursor-pagination.test.js +0 -148
  236. package/tests/anyapi-custom-idproperty.test.js +0 -163
  237. package/tests/autofilter.test.js +0 -463
  238. package/tests/bulk-operations.test.js +0 -657
  239. package/tests/computed-fields.test.js +0 -586
  240. package/tests/cors.test.js +0 -834
  241. package/tests/curl.test.js +0 -467
  242. package/tests/custom-id-mysql-returning-fallback.test.js +0 -128
  243. package/tests/custom-id-simplified-post.test.js +0 -75
  244. package/tests/custom-idproperty-relationships.test.js +0 -932
  245. package/tests/db-introspection.test.js +0 -521
  246. package/tests/db-table-operations.test.js +0 -798
  247. package/tests/fastify-plugin.test.js +0 -184
  248. package/tests/field-getters.test.js +0 -370
  249. package/tests/field-setters.test.js +0 -306
  250. package/tests/file-handling.test.js +0 -155
  251. package/tests/fixtures/api-configs.js +0 -2566
  252. package/tests/full-jsonapi-belongsto-linkage.test.js +0 -150
  253. package/tests/helpers/fake-fastify.js +0 -99
  254. package/tests/helpers/storage-mode.js +0 -65
  255. package/tests/helpers/test-utils.js +0 -203
  256. package/tests/http-connectors-parity.test.js +0 -395
  257. package/tests/id-normalization.test.js +0 -444
  258. package/tests/include-depth-validation.test.js +0 -331
  259. package/tests/includes.test.js +0 -427
  260. package/tests/local-storage.test.js +0 -96
  261. package/tests/logical-id-write-validation.test.js +0 -151
  262. package/tests/nested-includes.test.js +0 -617
  263. package/tests/pagination-boundaries.test.js +0 -154
  264. package/tests/pagination-contract.test.js +0 -122
  265. package/tests/pagination-cursor-multifield.test.js +0 -641
  266. package/tests/pagination-enhanced.test.js +0 -563
  267. package/tests/polymorphic-relationships.test.js +0 -347
  268. package/tests/polymorphic-simple.test.js +0 -148
  269. package/tests/positioning-advanced.test.js +0 -692
  270. package/tests/positioning-extended.test.js +0 -915
  271. package/tests/positioning-multifilter.test.js +0 -699
  272. package/tests/positioning.test.js +0 -560
  273. package/tests/post-commit-hooks.test.js +0 -120
  274. package/tests/projected-fields.test.js +0 -319
  275. package/tests/public-exports.test.js +0 -15
  276. package/tests/put-create-parity.test.js +0 -216
  277. package/tests/queries.test.js +0 -521
  278. package/tests/query-limits.test.js +0 -584
  279. package/tests/relationship-endpoints.test.js +0 -620
  280. package/tests/relationship-include-storage-adapter.test.js +0 -56
  281. package/tests/relationships.test.js +0 -681
  282. package/tests/rest-api.test.js +0 -337
  283. package/tests/return-record-settings.test.js +0 -184
  284. package/tests/row-policy.test.js +0 -489
  285. package/tests/s3-storage.test.js +0 -38
  286. package/tests/searchschema-knex-behavior.test.js +0 -187
  287. package/tests/searchschema-merge.test.js +0 -151
  288. package/tests/socketio.test.js +0 -860
  289. package/tests/storage-mapping.test.js +0 -362
  290. package/tests/temporal-boundaries.test.js +0 -208
  291. package/tests/test-development-guide.md +0 -370
  292. package/tests/virtual-fields.test.js +0 -404
@@ -1,362 +0,0 @@
1
- import { describe, it, before, after, beforeEach } from 'node:test'
2
- import assert from 'node:assert/strict'
3
- import knexLib from 'knex'
4
- import { Api } from 'hooked-api'
5
- import { RestApiPlugin } from '../plugins/core/rest-api-plugin.js'
6
- import { RestApiKnexPlugin } from '../plugins/core/rest-api-knex-plugin.js'
7
- import {
8
- REST_API_TEMPORAL_DATA_ERROR_CODE,
9
- RestApiTemporalDataError
10
- } from '../lib/rest-api-errors.js'
11
- import { mapRestApiErrorToHttp } from '../plugins/core/connectors/lib/transport-http-helpers.js'
12
- import {
13
- cleanTables,
14
- createJsonApiDocument,
15
- createRelationship,
16
- resourceIdentifier,
17
- assertResourceAttributes,
18
- assertResourceRelationship,
19
- validateJsonApiStructure,
20
- } from './helpers/test-utils.js'
21
-
22
- const knex = knexLib({
23
- client: 'better-sqlite3',
24
- connection: {
25
- filename: ':memory:'
26
- },
27
- useNullAsDefault: true
28
- })
29
-
30
- let api
31
- const DEFAULT_PROFILE_CREATED_AT = '2026-08-25T12:34:56.789Z'
32
- const COMPUTED_PROFILE_DATE = new Date('2026-08-25T23:45:01.987Z')
33
-
34
- const serializeDateTimeForSql = (value) => {
35
- if (value == null) return null
36
- if (typeof value !== 'string') {
37
- throw new Error('serializeDateTimeForSql expects an RFC 3339 string after schema validation')
38
- }
39
-
40
- return new Date(value).toISOString().replace('T', ' ').slice(0, 19)
41
- }
42
-
43
- describe('Storage mapping', () => {
44
- before(async () => {
45
- api = new Api({
46
- name: 'storage-mapping-test',
47
- })
48
-
49
- await api.use(RestApiPlugin, {
50
- simplifiedApi: false,
51
- simplifiedTransport: false,
52
- sortableFields: ['id', 'displayName', 'loginCount', 'lastSeenAt', 'countryId', 'externalRef'],
53
- returnRecordApi: {
54
- post: 'full',
55
- put: 'full',
56
- patch: 'full'
57
- },
58
- returnRecordTransport: {
59
- post: 'full',
60
- put: 'full',
61
- patch: 'full'
62
- }
63
- })
64
- await api.use(RestApiKnexPlugin, { knex })
65
-
66
- await api.addResource('countries', {
67
- schema: {
68
- id: { type: 'id' },
69
- name: { type: 'string', required: true }
70
- },
71
- relationships: {
72
- profiles: { type: 'hasMany', target: 'profiles', foreignKey: 'country_id' }
73
- },
74
- tableName: 'mapped_countries'
75
- })
76
- await api.resources.countries.createKnexTable()
77
-
78
- await api.addResource('profiles', {
79
- schema: {
80
- id: { type: 'id' },
81
- displayName: { type: 'string', required: true, search: true },
82
- loginCount: { type: 'number', defaultTo: 0 },
83
- lastSeenAt: {
84
- type: 'dateTime',
85
- nullable: true,
86
- temporalPrecision: 0,
87
- getter: (value) => value == null ? value : new Date(value),
88
- storage: {
89
- serialize: serializeDateTimeForSql
90
- }
91
- },
92
- createdAt: {
93
- type: 'dateTime',
94
- temporalPrecision: 3,
95
- defaultTo: () => new Date(DEFAULT_PROFILE_CREATED_AT).toISOString()
96
- },
97
- calculatedAt: {
98
- type: 'dateTime',
99
- temporalPrecision: 0,
100
- computed: true,
101
- compute: () => new Date(COMPUTED_PROFILE_DATE)
102
- },
103
- birthDate: { type: 'date', nullable: true },
104
- openingTime: { type: 'time', nullable: true, temporalPrecision: 2 },
105
- observedAtMs: { type: 'epochMilliseconds', nullable: true },
106
- observedAtSeconds: { type: 'epochSeconds', nullable: true },
107
- countryId: {
108
- type: 'id',
109
- nullable: true,
110
- belongsTo: 'countries',
111
- as: 'country'
112
- },
113
- externalRef: { type: 'string', nullable: true, search: true, storage: { column: 'legacy_ref' } },
114
- confirmationToken: { type: 'string', virtual: true }
115
- },
116
- tableName: 'mapped_profiles'
117
- })
118
- await api.resources.profiles.createKnexTable()
119
-
120
- await api.addResource('verbatim_profiles', {
121
- storage: { naming: 'exact' },
122
- schema: {
123
- id: { type: 'id' },
124
- displayName: { type: 'string', required: true },
125
- loginCount: { type: 'number', defaultTo: 0 }
126
- },
127
- tableName: 'verbatim_profiles'
128
- })
129
- await api.resources.verbatim_profiles.createKnexTable()
130
- })
131
-
132
- after(async () => {
133
- await knex.destroy()
134
- })
135
-
136
- beforeEach(async () => {
137
- await cleanTables(knex, ['mapped_profiles', 'mapped_countries', 'verbatim_profiles'])
138
- })
139
-
140
- it('persists mapped columns while exposing logical field names', async () => {
141
- const country = await api.resources.countries.post({
142
- inputRecord: createJsonApiDocument('countries', {
143
- name: 'Australia'
144
- })
145
- })
146
-
147
- const createResult = await api.resources.profiles.post({
148
- inputRecord: createJsonApiDocument(
149
- 'profiles',
150
- {
151
- displayName: 'Mercury',
152
- loginCount: 7,
153
- lastSeenAt: '2026-01-02T11:04:05+08:00',
154
- birthDate: '2020-02-29',
155
- openingTime: '09:30:15.12',
156
- observedAtMs: '1767323045000',
157
- observedAtSeconds: '1767323045',
158
- externalRef: 'legacy-001',
159
- confirmationToken: 'secret-token'
160
- },
161
- {
162
- country: createRelationship(resourceIdentifier('countries', country.data.id))
163
- }
164
- )
165
- })
166
-
167
- validateJsonApiStructure(createResult)
168
- assertResourceAttributes(createResult.data, {
169
- displayName: 'Mercury',
170
- loginCount: 7
171
- })
172
- assert.equal(createResult.data.attributes.confirmationToken, 'secret-token')
173
- assert.equal(createResult.data.attributes.lastSeenAt, '2026-01-02T03:04:05Z')
174
- assert.equal(createResult.data.attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
175
- assert.equal(createResult.data.attributes.calculatedAt, '2026-08-25T23:45:01Z')
176
- assert.equal(createResult.data.attributes.birthDate, '2020-02-29')
177
- assert.equal(createResult.data.attributes.openingTime, '09:30:15.12')
178
- assert.equal(createResult.data.attributes.observedAtMs, 1767323045000)
179
- assert.equal(createResult.data.attributes.observedAtSeconds, 1767323045)
180
- assert.ok(!('display_name' in createResult.data.attributes))
181
- assert.ok(!('country_id' in createResult.data.attributes))
182
-
183
- const dbRecord = await knex('mapped_profiles').first()
184
- assert.equal(dbRecord.display_name, 'Mercury')
185
- assert.equal(dbRecord.login_count, 7)
186
- assert.equal(dbRecord.last_seen_at, '2026-01-02 03:04:05')
187
- assert.equal(dbRecord.observed_at_ms, 1767323045000)
188
- assert.equal(dbRecord.observed_at_seconds, 1767323045)
189
- assert.equal(String(dbRecord.country_id), country.data.id)
190
- assert.equal(dbRecord.legacy_ref, 'legacy-001')
191
- assert.ok(!('displayName' in dbRecord))
192
- assert.ok(!('countryId' in dbRecord))
193
- assert.ok(!('confirmationToken' in dbRecord))
194
-
195
- const getResult = await api.resources.profiles.get({
196
- id: createResult.data.id,
197
- queryParams: {
198
- include: ['country']
199
- }
200
- })
201
-
202
- validateJsonApiStructure(getResult)
203
- assertResourceAttributes(getResult.data, {
204
- displayName: 'Mercury',
205
- loginCount: 7
206
- })
207
- assert.equal(getResult.data.attributes.lastSeenAt, '2026-01-02T03:04:05Z')
208
- assert.equal(getResult.data.attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
209
- assert.equal(getResult.data.attributes.calculatedAt, '2026-08-25T23:45:01Z')
210
- assert.equal(getResult.data.attributes.birthDate, '2020-02-29')
211
- assert.equal(getResult.data.attributes.openingTime, '09:30:15.12')
212
- assert.equal(getResult.data.attributes.observedAtMs, 1767323045000)
213
- assert.equal(getResult.data.attributes.observedAtSeconds, 1767323045)
214
- assert.ok(!('display_name' in getResult.data.attributes))
215
- assertResourceRelationship(
216
- getResult.data,
217
- 'country',
218
- resourceIdentifier('countries', country.data.id)
219
- )
220
-
221
- const queryResult = await api.resources.profiles.query({
222
- queryParams: {
223
- filters: {
224
- displayName: 'Mercury',
225
- externalRef: 'legacy-001'
226
- }
227
- }
228
- })
229
-
230
- validateJsonApiStructure(queryResult, true)
231
- assert.equal(queryResult.data.length, 1)
232
- assertResourceAttributes(queryResult.data[0], {
233
- displayName: 'Mercury',
234
- externalRef: 'legacy-001'
235
- })
236
- assert.equal(queryResult.data[0].attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
237
- assert.equal(queryResult.data[0].attributes.calculatedAt, '2026-08-25T23:45:01Z')
238
- })
239
-
240
- it('applies storage mapping on PATCH updates and sparse fieldsets', async () => {
241
- const created = await api.resources.profiles.post({
242
- inputRecord: createJsonApiDocument('profiles', {
243
- displayName: 'Before',
244
- loginCount: 1,
245
- lastSeenAt: '2026-01-01T00:00:00Z'
246
- })
247
- })
248
-
249
- const patchResult = await api.resources.profiles.patch({
250
- id: created.data.id,
251
- inputRecord: {
252
- data: {
253
- type: 'profiles',
254
- id: created.data.id,
255
- attributes: {
256
- displayName: 'After',
257
- lastSeenAt: '2026-02-03T04:05:06Z',
258
- confirmationToken: 'updated-token'
259
- }
260
- }
261
- },
262
- queryParams: {
263
- fields: {
264
- profiles: 'displayName,lastSeenAt,confirmationToken'
265
- }
266
- }
267
- })
268
-
269
- validateJsonApiStructure(patchResult)
270
- assert.deepEqual(Object.keys(patchResult.data.attributes).sort(), ['confirmationToken', 'displayName', 'lastSeenAt'])
271
- assert.equal(patchResult.data.attributes.displayName, 'After')
272
- assert.equal(patchResult.data.attributes.confirmationToken, 'updated-token')
273
- assert.equal(patchResult.data.attributes.lastSeenAt, '2026-02-03T04:05:06Z')
274
-
275
- const dbRecord = await knex('mapped_profiles').where('id', created.data.id).first()
276
- assert.equal(dbRecord.display_name, 'After')
277
- assert.equal(dbRecord.last_seen_at, '2026-02-03 04:05:06')
278
- assert.ok(!('displayName' in dbRecord))
279
- })
280
-
281
- it('rejects temporal values outside the public JSON contract before storage', async () => {
282
- const invalidTemporalValues = [
283
- { lastSeenAt: '2026-01-02 03:04:05' },
284
- { lastSeenAt: new Date('2026-01-02T03:04:05Z') },
285
- { birthDate: '2026-02-30' },
286
- { openingTime: '09:30Z' }
287
- ]
288
-
289
- for (const [index, temporalAttributes] of invalidTemporalValues.entries()) {
290
- await assert.rejects(
291
- api.resources.profiles.post({
292
- inputRecord: createJsonApiDocument('profiles', {
293
- displayName: `Invalid temporal value ${index}`,
294
- ...temporalAttributes
295
- })
296
- }),
297
- (error) => error?.code === 'REST_API_VALIDATION'
298
- )
299
- }
300
- })
301
-
302
- it('fails loudly when storage returns an invalid non-null temporal value', async () => {
303
- const insertedIds = await knex('mapped_profiles').insert({
304
- display_name: 'Corrupt temporal row',
305
- login_count: 0,
306
- last_seen_at: 'not-a-date',
307
- created_at: new Date(DEFAULT_PROFILE_CREATED_AT)
308
- })
309
- const profileId = insertedIds[0]
310
-
311
- await assert.rejects(
312
- api.resources.profiles.get({ id: profileId }),
313
- (error) => {
314
- assert(error instanceof RestApiTemporalDataError)
315
- assert.equal(error.code, REST_API_TEMPORAL_DATA_ERROR_CODE)
316
- assert.equal(
317
- error.message,
318
- "Invalid database value for dateTime field 'profiles.lastSeenAt'."
319
- )
320
- assert.deepEqual(error.details, {
321
- field: 'lastSeenAt',
322
- resourceType: 'profiles',
323
- fieldType: 'dateTime',
324
- source: 'database'
325
- })
326
- assert.deepEqual(mapRestApiErrorToHttp(error), {
327
- status: 500,
328
- body: {
329
- errors: [{
330
- status: '500',
331
- code: REST_API_TEMPORAL_DATA_ERROR_CODE,
332
- title: 'Invalid Temporal Data',
333
- detail: "Invalid database value for dateTime field 'profiles.lastSeenAt'."
334
- }]
335
- }
336
- })
337
- return true
338
- }
339
- )
340
- })
341
-
342
- it('can opt out of snake_case translation for an entire resource', async () => {
343
- const created = await api.resources.verbatim_profiles.post({
344
- inputRecord: createJsonApiDocument('verbatim_profiles', {
345
- displayName: 'Exact Mode',
346
- loginCount: 3
347
- })
348
- })
349
-
350
- validateJsonApiStructure(created)
351
- assertResourceAttributes(created.data, {
352
- displayName: 'Exact Mode',
353
- loginCount: 3
354
- })
355
-
356
- const dbRecord = await knex('verbatim_profiles').where('id', created.data.id).first()
357
- assert.equal(dbRecord.displayName, 'Exact Mode')
358
- assert.equal(dbRecord.loginCount, 3)
359
- assert.equal(Object.hasOwn(dbRecord, 'display_name'), false)
360
- assert.equal(Object.hasOwn(dbRecord, 'login_count'), false)
361
- })
362
- })
@@ -1,208 +0,0 @@
1
- import { after, before, beforeEach, describe, it } from 'node:test'
2
- import assert from 'node:assert/strict'
3
- import { applyFieldSetters, handleRecordReturnAfterWrite } from '../plugins/core/rest-api-plugin-methods/common.js'
4
- import knexLib from 'knex'
5
- import { createTemporalBoundaryApi } from './fixtures/api-configs.js'
6
- import { cleanTables, createJsonApiDocument } from './helpers/test-utils.js'
7
- import { mapRestApiErrorToHttp } from '../plugins/core/connectors/lib/transport-http-helpers.js'
8
- import { normalizeAttributes, normalizeRecordAttributes } from '../plugins/core/lib/querying-writing/database-value-normalizers.js'
9
- import { storageMode } from './helpers/storage-mode.js'
10
- import { RestApiTemporalDataError } from '../lib/rest-api-errors.js'
11
-
12
- const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
13
- let api
14
- let finishValue
15
- const document = (attributes = {}) => createJsonApiDocument('events', { name: 'Event', ...attributes })
16
- const assertValidationError = (error) => {
17
- assert.equal(error.code, 'REST_API_VALIDATION')
18
- assert.equal(mapRestApiErrorToHttp(error).status, 422)
19
- return true
20
- }
21
-
22
- describe('Temporal storage and response boundaries', () => {
23
- before(async () => {
24
- api = await createTemporalBoundaryApi(knex)
25
- const handler = async ({ context }) => {
26
- if (finishValue === undefined || context.scopeName !== 'events') return
27
- const attributes = context.simplified ? context.responseRecord : context.responseRecord?.data?.attributes
28
- if (attributes) attributes.producedAt = finishValue
29
- if (context.simplified && attributes?.person) attributes.person.producedAt = finishValue
30
- for (const included of context.responseRecord?.included || []) included.attributes.producedAt = finishValue
31
- }
32
- await api.customize({ hooks: {
33
- finishPost: { functionName: 'temporal-finish-post', handler },
34
- finishPut: { functionName: 'temporal-finish-put', handler },
35
- finishPatch: { functionName: 'temporal-finish-patch', handler }
36
- } })
37
- })
38
- after(async () => { await knex.destroy() })
39
- beforeEach(async () => {
40
- finishValue = undefined
41
- await cleanTables(knex, ['temporal_events', 'temporal_people'])
42
- })
43
-
44
- it('rejects submillisecond writes without inserting or changing data', async () => {
45
- const precise = '2026-09-01T10:20:30.123456Z'
46
- await assert.rejects(api.resources.events.post({ inputRecord: document({ occurredAt: precise }) }), assertValidationError)
47
- assert.equal((await api.resources.events.query()).data.length, 0)
48
- const created = await api.resources.events.post({ inputRecord: document({ occurredAt: '2026-09-01T10:20:30.123000Z' }) })
49
- for (const method of ['put', 'patch']) {
50
- const inputRecord = document({ occurredAt: precise })
51
- inputRecord.data.id = created.data.id
52
- await assert.rejects(api.resources.events[method]({ id: created.data.id, inputRecord }), assertValidationError)
53
- const result = await api.resources.events.get({ id: created.data.id })
54
- assert.equal(result.data.attributes.occurredAt, '2026-09-01T10:20:30.123Z')
55
- }
56
- })
57
-
58
- it('retains submillisecond precision supplied by storage, including timezone offsets', () => {
59
- for (const value of ['2026-09-01 10:20:30.123456', '2026-09-01T18:20:30.123456+08:00']) {
60
- const result = normalizeAttributes({ occurredAt: value }, { occurredAt: { type: 'dateTime', temporalPrecision: 6 } })
61
- assert.equal(result.occurredAt, '2026-09-01T10:20:30.123456Z')
62
- }
63
- })
64
-
65
- it('normalizes numeric epoch values returned as strings or bigints by drivers', () => {
66
- const schema = { milliseconds: { type: 'epochMilliseconds' }, seconds: { type: 'epochSeconds' } }
67
- assert.deepEqual(normalizeAttributes({ milliseconds: '1788258030123', seconds: 1788258030n }, schema), {
68
- milliseconds: 1788258030123, seconds: 1788258030
69
- })
70
- for (const value of ['bad', '8640000000000001', 1.25]) {
71
- assert.throws(() => normalizeAttributes({ milliseconds: value }, schema), { code: 'REST_API_TEMPORAL_DATA_INVALID' })
72
- }
73
- })
74
-
75
- it('normalizes temporal query projections and follows their cursors', async () => {
76
- for (let index = 0; index < 4; index++) {
77
- await api.resources.events.post({ inputRecord: document({ occurredAt: `2026-09-01T10:20:3${index}.123Z` }) })
78
- }
79
- const queryParams = { sort: ['projectedAt'], fields: { events: 'projectedAt' }, page: { size: 2 } }
80
- const first = await api.resources.events.query({ queryParams })
81
- assert.equal(first.data[0].attributes.projectedAt, '2026-09-01T10:20:30.123Z')
82
- const second = await api.resources.events.query({ queryParams: {
83
- ...queryParams, page: { size: 2, after: first.meta.pagination.cursor.next }
84
- } })
85
- assert.equal(second.data[0].attributes.projectedAt, '2026-09-01T10:20:32.123Z')
86
- })
87
-
88
- it('uses a custom serializer consistently for writes and filters', { skip: storageMode.isAnyApi() }, async () => {
89
- const value = '2026-09-01T10:20:30.123456Z'
90
- const created = await api.resources.events.post({ inputRecord: document({ serializedAt: value }) })
91
- assert.equal(created.data.attributes.serializedAt, value)
92
- const filtered = await api.resources.events.query({ queryParams: { filters: { serializedAt: value } } })
93
- assert.deepEqual(filtered.data.map(entry => entry.id), [created.data.id])
94
- })
95
-
96
- it('validates included fieldsets even when the relationship or collection is empty', async () => {
97
- const queryParams = { include: ['person'], fields: { people: 'missingField' } }
98
- await assert.rejects(api.resources.events.query({ queryParams }), { code: 'REST_API_FIELDSET_INVALID' })
99
- const created = await api.resources.events.post({ inputRecord: document() })
100
- await assert.rejects(api.resources.events.get({ id: created.data.id, queryParams }), { code: 'REST_API_FIELDSET_INVALID' })
101
- })
102
-
103
- it('rejects inherited object names as unknown sparse fields', async () => {
104
- for (const field of ['constructor', 'toString', '__proto__']) {
105
- await assert.rejects(api.resources.events.query({ queryParams: { fields: { events: field } } }), {
106
- code: 'REST_API_FIELDSET_INVALID'
107
- })
108
- }
109
- })
110
-
111
- it('normalizes nested simplified to-many and polymorphic resources without changing ordinary objects', () => {
112
- const date = new Date('2026-09-08T11:22:33.987Z')
113
- const child = { id: 'child', producedAt: date }
114
- const payload = { id: 'event', person: { id: 'person', events: [child, child] },
115
- subject: { id: 'person', _type: 'people', producedAt: date },
116
- arbitrary: { producedAt: date, value: 'unchanged' } }
117
- const result = normalizeRecordAttributes(payload, api.resources, { simplified: true, resourceType: 'events', source: 'response' })
118
- assert.equal(result.person.events[0].producedAt, '2026-09-08T11:22:33Z')
119
- assert.equal(result.person.events[0], result.person.events[1])
120
- assert.equal(result.subject.producedAt, '2026-09-08T11:22:33Z')
121
- assert.equal(result.subject._type, 'people')
122
- assert.equal(result.arbitrary, payload.arbitrary)
123
- assert.equal(child.producedAt, date)
124
- })
125
-
126
- it('preserves typed API errors thrown by computed fields', async () => {
127
- const created = await api.resources.events.post({ inputRecord: document() })
128
- const definition = api.resources.events.vars.schemaInfo.computed.producedAt
129
- const original = definition.compute
130
- const error = new RestApiTemporalDataError({ field: 'producedAt', resourceType: 'events', fieldType: 'dateTime', source: 'response' })
131
- definition.compute = () => { throw error }
132
- try {
133
- await assert.rejects(api.resources.events.get({ id: created.data.id }), actual => actual === error)
134
- } finally {
135
- definition.compute = original
136
- }
137
- })
138
-
139
- it('preserves typed API errors thrown by getters', async () => {
140
- const created = await api.resources.events.post({ inputRecord: document() })
141
- const schemaInfo = api.resources.events.vars.schemaInfo
142
- const originalGetters = schemaInfo.fieldGetters
143
- const originalOrder = schemaInfo.sortedGetterFields
144
- const error = new RestApiTemporalDataError({ field: 'name', resourceType: 'events', source: 'response' })
145
- schemaInfo.fieldGetters = { name: { getter: () => { throw error } } }
146
- schemaInfo.sortedGetterFields = ['name']
147
- try {
148
- await assert.rejects(api.resources.events.get({ id: created.data.id }), actual => actual === error)
149
- } finally {
150
- schemaInfo.fieldGetters = originalGetters
151
- schemaInfo.sortedGetterFields = originalOrder
152
- }
153
- })
154
-
155
- it('preserves typed errors from setters and post-write storage reads', async () => {
156
- const error = new RestApiTemporalDataError({ field: 'occurredAt', resourceType: 'events' })
157
- await assert.rejects(applyFieldSetters({ occurredAt: '2026-09-08T00:00:00Z' }, {
158
- fieldSetters: { occurredAt: { setter: () => { throw error } } },
159
- sortedSetterFields: ['occurredAt']
160
- }, { scopeName: 'events' }), actual => actual === error)
161
- await assert.rejects(handleRecordReturnAfterWrite({
162
- context: { method: 'POST' }, scopeName: 'events',
163
- helpers: { dataGetMinimal: async () => { throw error } },
164
- log: { warn () {} }
165
- }), actual => actual === error)
166
- })
167
-
168
- for (const direction of ['after', 'before']) {
169
- it(`rejects malformed temporal and numeric values in page[${direction}] as client errors`, async () => {
170
- for (const [field, value] of [['occurredAt', 'garbage'], ['day', '2026-02-30'], ['atTime', '25:30'], ['observedAtMs', 'NaN']]) {
171
- await assert.rejects(api.resources.events.query({ queryParams: {
172
- sort: [field], page: { size: 2, [direction]: `${field}:${encodeURIComponent(value)},id:1` }
173
- } }), (error) => {
174
- assertValidationError(error)
175
- assert.deepEqual(error.details.fields, [`page.${direction}`])
176
- return true
177
- })
178
- }
179
- })
180
- }
181
-
182
- for (const simplified of [false, true]) {
183
- for (const method of ['post', 'put', 'patch']) {
184
- it(`normalizes ${method} finish values and included resources with simplified=${simplified}`, async () => {
185
- const person = await api.resources.people.post({ inputRecord: createJsonApiDocument('people', { name: 'Person' }) })
186
- const inputRecord = document()
187
- inputRecord.data.relationships = { person: { data: { type: 'people', id: person.data.id } } }
188
- const created = method === 'post' ? null : await api.resources.events.post({ inputRecord })
189
- if (created) inputRecord.data.id = created.data.id
190
- finishValue = new Date('2026-09-08T11:22:33.987Z')
191
- const result = await api.resources.events[method]({
192
- ...(created ? { id: created.data.id } : {}), inputRecord,
193
- queryParams: { include: ['person'] }, simplified
194
- })
195
- assert.equal((simplified ? result : result.data.attributes).producedAt, '2026-09-08T11:22:33Z')
196
- assert.equal((simplified ? result.person : result.included[0].attributes).producedAt, '2026-09-08T11:22:33Z')
197
- })
198
- }
199
- it(`rejects invalid finish values with simplified=${simplified}`, async () => {
200
- finishValue = 'not-a-date'
201
- await assert.rejects(api.resources.events.post({ inputRecord: document(), simplified }), (error) => {
202
- assert.equal(error.code, 'REST_API_TEMPORAL_DATA_INVALID')
203
- assert.equal(mapRestApiErrorToHttp(error).status, 500)
204
- return true
205
- })
206
- })
207
- }
208
- })