json-rest-api 1.0.29 → 2.1.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 (294) 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 +733 -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 +103 -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 +3838 -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 +37 -0
  44. package/index.js +3 -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 +70 -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 +586 -418
  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 +120 -56
  71. package/plugins/core/lib/anyapi/stored-definition.js +109 -0
  72. package/plugins/core/lib/anyapi/utils/descriptor-helpers.js +0 -64
  73. package/plugins/core/lib/dbIntrospection.js +228 -21
  74. package/plugins/core/lib/dbTablesOperations.js +409 -92
  75. package/plugins/core/lib/fractional-positioning.js +12 -48
  76. package/plugins/core/lib/querying/identifier-query.js +19 -0
  77. package/plugins/core/lib/querying/include-query-helpers.js +364 -0
  78. package/plugins/core/lib/querying/include-to-many.js +428 -0
  79. package/plugins/core/lib/querying/include-to-one.js +579 -0
  80. package/plugins/core/lib/querying/knex-cross-table-search.js +31 -307
  81. package/plugins/core/lib/querying/knex-json-api-transformers-querying.js +99 -401
  82. package/plugins/core/lib/querying/knex-pagination-helpers.js +48 -317
  83. package/plugins/core/lib/querying/knex-process-includes.js +5 -110
  84. package/plugins/core/lib/querying/knex-query-helpers-base.js +21 -56
  85. package/plugins/core/lib/querying/knex-query-helpers.js +298 -448
  86. package/plugins/core/lib/querying/knex-relationship-includes.js +120 -2138
  87. package/plugins/core/lib/querying/knex-window-queries.js +62 -253
  88. package/plugins/core/lib/querying/query-builder-utils.js +44 -4
  89. package/plugins/core/lib/querying/query-constraint.d.ts +12 -0
  90. package/plugins/core/lib/querying/query-constraint.js +27 -0
  91. package/plugins/core/lib/querying/query-field-sort-helpers.js +134 -37
  92. package/plugins/core/lib/querying/relationship-identifiers.js +208 -0
  93. package/plugins/core/lib/querying/sort-helpers.js +13 -1
  94. package/plugins/core/lib/querying/storage-adapter-utils.js +13 -5
  95. package/plugins/core/lib/querying/url-helpers.js +11 -4
  96. package/plugins/core/lib/querying-writing/compile-schemas.js +148 -249
  97. package/plugins/core/lib/querying-writing/connectors-query-parser.js +33 -118
  98. package/plugins/core/lib/querying-writing/database-capabilities.js +149 -223
  99. package/plugins/core/lib/querying-writing/database-value-normalizers.js +179 -194
  100. package/plugins/core/lib/querying-writing/default-data-helpers.js +15 -45
  101. package/plugins/core/lib/querying-writing/field-selection-types.d.ts +43 -0
  102. package/plugins/core/lib/querying-writing/field-utils.js +113 -92
  103. package/plugins/core/lib/querying-writing/knex-constants.d.ts +18 -0
  104. package/plugins/core/lib/querying-writing/knex-constants.js +2 -26
  105. package/plugins/core/lib/querying-writing/knex-field-helpers.js +100 -290
  106. package/plugins/core/lib/querying-writing/knex-json-api-transformers.js +31 -120
  107. package/plugins/core/lib/querying-writing/query-field-helpers.js +108 -32
  108. package/plugins/core/lib/querying-writing/query-field-types.d.ts +60 -0
  109. package/plugins/core/lib/querying-writing/relationship-contracts.js +33 -13
  110. package/plugins/core/lib/querying-writing/request-contracts.js +93 -38
  111. package/plugins/core/lib/querying-writing/resource-id-normalization.js +23 -5
  112. package/plugins/core/lib/querying-writing/response-options.js +35 -0
  113. package/plugins/core/lib/querying-writing/schema-helpers.js +203 -324
  114. package/plugins/core/lib/querying-writing/scope-validations.js +92 -290
  115. package/plugins/core/lib/querying-writing/simplified-helpers.js +113 -712
  116. package/plugins/core/lib/storage/canonical-data-helpers.js +683 -0
  117. package/plugins/core/lib/storage/canonical-storage-mapping.js +51 -20
  118. package/plugins/core/lib/storage/ordinary-data-helpers.js +710 -0
  119. package/plugins/core/lib/storage/storage-adapter.js +128 -62
  120. package/plugins/core/lib/storage/storage-mapping.js +78 -28
  121. package/plugins/core/lib/storage/storage-types.d.ts +502 -0
  122. package/plugins/core/lib/writing/many-to-many-manipulations.js +114 -284
  123. package/plugins/core/lib/writing/relationship-processor.js +94 -158
  124. package/plugins/core/lib/writing/resource-version.js +172 -0
  125. package/plugins/core/lib/writing/reverse-relationship-manipulations.js +110 -0
  126. package/plugins/core/rest-api-anyapi-knex-plugin.js +290 -2475
  127. package/plugins/core/rest-api-autofilter-plugin.js +17 -19
  128. package/plugins/core/rest-api-cors-plugin.js +52 -205
  129. package/plugins/core/rest-api-knex-plugin.js +45 -1077
  130. package/plugins/core/rest-api-label-plugin.js +25 -38
  131. package/plugins/core/rest-api-plugin-hooks/register-relationship-routes.js +5 -5
  132. package/plugins/core/rest-api-plugin-hooks/register-scope-routes.js +9 -6
  133. package/plugins/core/rest-api-plugin-hooks/turn-scope-init-into-vars.js +7 -26
  134. package/plugins/core/rest-api-plugin-hooks/validate-include-configurations.js +20 -26
  135. package/plugins/core/rest-api-plugin-methods/add-route.js +4 -6
  136. package/plugins/core/rest-api-plugin-methods/apply-query-filters.js +42 -13
  137. package/plugins/core/rest-api-plugin-methods/check-permissions.js +11 -5
  138. package/plugins/core/rest-api-plugin-methods/common.js +291 -395
  139. package/plugins/core/rest-api-plugin-methods/delete-relationship.js +49 -47
  140. package/plugins/core/rest-api-plugin-methods/delete.js +31 -25
  141. package/plugins/core/rest-api-plugin-methods/enrich-attributes.js +108 -148
  142. package/plugins/core/rest-api-plugin-methods/get-related.js +113 -305
  143. package/plugins/core/rest-api-plugin-methods/get-relationship.js +25 -18
  144. package/plugins/core/rest-api-plugin-methods/get.js +36 -68
  145. package/plugins/core/rest-api-plugin-methods/lifecycle-types.d.ts +225 -0
  146. package/plugins/core/rest-api-plugin-methods/patch-relationship.js +28 -25
  147. package/plugins/core/rest-api-plugin-methods/patch.js +46 -99
  148. package/plugins/core/rest-api-plugin-methods/post-relationship.js +49 -53
  149. package/plugins/core/rest-api-plugin-methods/post.js +51 -51
  150. package/plugins/core/rest-api-plugin-methods/put.js +69 -148
  151. package/plugins/core/rest-api-plugin-methods/query.js +37 -81
  152. package/plugins/core/rest-api-plugin-methods/release.js +2 -1
  153. package/plugins/core/rest-api-plugin.js +32 -46
  154. package/plugins/core/rest-api-positioning-plugin.js +183 -628
  155. package/plugins/core/rest-api-query-projections-plugin.js +19 -102
  156. package/plugins/core/rest-api-row-policy-plugin.js +3 -3
  157. package/plugins/core/socketio-plugin.js +364 -344
  158. package/plugins/storage/local-storage.js +40 -36
  159. package/types/anyapi.d.ts +30 -0
  160. package/types/autofilter.d.ts +57 -0
  161. package/types/bulk-methods.d.ts +63 -0
  162. package/types/errors.d.ts +118 -0
  163. package/types/fastify-options.d.ts +19 -0
  164. package/types/file-detectors.d.ts +33 -0
  165. package/types/file-storage.d.ts +48 -0
  166. package/types/hook-context.d.ts +180 -0
  167. package/types/plugin-options.d.ts +65 -0
  168. package/types/relationship-methods.d.ts +74 -0
  169. package/types/representations.d.ts +50 -0
  170. package/types/resource-methods.d.ts +95 -0
  171. package/types/resource-schema.d.ts +157 -0
  172. package/types/row-policy.d.ts +31 -0
  173. package/types/runtime.d.ts +132 -0
  174. package/types/transactions.d.ts +21 -0
  175. package/.claude/agents/library-guide-expert.md +0 -30
  176. package/.claude/agents/rest-api-internals-expert.md +0 -54
  177. package/.claude/settings.local.json +0 -70
  178. package/AGENTS.md +0 -34
  179. package/CLAUDE.md +0 -160
  180. package/CRUSH.md +0 -55
  181. package/JSKIT_BACKEND_MIGRATION_TRACKER.txt +0 -180
  182. package/SINGLE_VALIDATION_CONTRACT_TODO.txt +0 -172
  183. package/TODO.todo +0 -13
  184. package/connectors_ideas/fastify.js +0 -217
  185. package/connectors_ideas/koa-plugin.js +0 -112
  186. package/docs/.bundle/config +0 -2
  187. package/docs/COMPARISON.md +0 -433
  188. package/docs/GUIDE/GUIDE_1_Initial_Setup.md +0 -1057
  189. package/docs/GUIDE/GUIDE_2_1_The_Starting_Point.md +0 -88
  190. package/docs/GUIDE/GUIDE_2_2_Manipulating_And_Searching_Tables.md +0 -808
  191. package/docs/GUIDE/GUIDE_2_3_BelongsTo_Relationships.md +0 -491
  192. package/docs/GUIDE/GUIDE_2_4_HasMany_Records.md +0 -398
  193. package/docs/GUIDE/GUIDE_2_5_HasMany_Polymorphic.md +0 -898
  194. package/docs/GUIDE/GUIDE_2_6_Many_To_Many.md +0 -712
  195. package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md +0 -1247
  196. package/docs/GUIDE/GUIDE_2_8_Effects_of_PUT_and_PATCH.md +0 -748
  197. package/docs/GUIDE/GUIDE_2_9_Relationships_Urls.md +0 -517
  198. package/docs/GUIDE/GUIDE_2_Data_And_Relations.md +0 -66
  199. package/docs/GUIDE/GUIDE_3_Field_Transformations.md +0 -1252
  200. package/docs/GUIDE/GUIDE_5_Non-Db_Resources.md +0 -1107
  201. package/docs/GUIDE/GUIDE_6_Positioning.md +0 -692
  202. package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md +0 -1491
  203. package/docs/GUIDE/GUIDE_X_Bulk_Operations.md +0 -732
  204. package/docs/GUIDE/GUIDE_X_Cors.md +0 -1957
  205. package/docs/GUIDE/GUIDE_X_Fastify.md +0 -78
  206. package/docs/GUIDE/GUIDE_X_File_Uploads.md +0 -729
  207. package/docs/GUIDE/GUIDE_X_Knex_Schema_And_Migrations.md +0 -370
  208. package/docs/GUIDE/GUIDE_X_Query_Projections.md +0 -159
  209. package/docs/GUIDE/GUIDE_X_SocketIO.md +0 -1040
  210. package/docs/GUIDE/GUIDE_X_Writing_Plugins.md +0 -201
  211. package/docs/Gemfile +0 -6
  212. package/docs/Gemfile.lock +0 -308
  213. package/docs/ONBOARDING.md +0 -315
  214. package/docs/_config.yml +0 -36
  215. package/docs/_layouts/default.html +0 -123
  216. package/docs/apple-touch-icon.svg +0 -4
  217. package/docs/assets/css/style.scss +0 -392
  218. package/docs/favicon.svg +0 -4
  219. package/docs/index.md +0 -164
  220. package/docs/mini-guides/file-uploads-complete.md +0 -161
  221. package/eslint.config.js +0 -13
  222. package/examples/url-override-example.js +0 -137
  223. package/fixing_plan.md +0 -112
  224. package/plugins/core/lib/anyapi/query/anyapi-query-adapter.js +0 -657
  225. package/plugins/core/lib/querying-writing/return-record-settings.js +0 -47
  226. package/plugins/core/lib/writing/knex-json-api-transformers-writing.js +0 -110
  227. package/plugins/storage/s3-storage.js +0 -93
  228. package/quickTest.js +0 -136
  229. package/scripts/debug-anyapi-review-filter.mjs +0 -63
  230. package/scripts/inspect-anyapi-descriptor-country.mjs +0 -19
  231. package/scripts/inspect-anyapi-descriptor.mjs +0 -19
  232. package/scripts/run-docs.js +0 -133
  233. package/test-debug.js +0 -59
  234. package/tests/README.md +0 -202
  235. package/tests/TEST_TEMPLATE.test.js +0 -178
  236. package/tests/anyapi-basic.test.js +0 -105
  237. package/tests/anyapi-cursor-pagination.test.js +0 -148
  238. package/tests/anyapi-custom-idproperty.test.js +0 -163
  239. package/tests/autofilter.test.js +0 -463
  240. package/tests/bulk-operations.test.js +0 -657
  241. package/tests/computed-fields.test.js +0 -586
  242. package/tests/cors.test.js +0 -834
  243. package/tests/curl.test.js +0 -467
  244. package/tests/custom-id-mysql-returning-fallback.test.js +0 -128
  245. package/tests/custom-id-simplified-post.test.js +0 -75
  246. package/tests/custom-idproperty-relationships.test.js +0 -932
  247. package/tests/db-introspection.test.js +0 -521
  248. package/tests/db-table-operations.test.js +0 -798
  249. package/tests/fastify-plugin.test.js +0 -184
  250. package/tests/field-getters.test.js +0 -370
  251. package/tests/field-setters.test.js +0 -306
  252. package/tests/file-handling.test.js +0 -155
  253. package/tests/fixtures/api-configs.js +0 -2566
  254. package/tests/full-jsonapi-belongsto-linkage.test.js +0 -150
  255. package/tests/helpers/fake-fastify.js +0 -99
  256. package/tests/helpers/storage-mode.js +0 -65
  257. package/tests/helpers/test-utils.js +0 -203
  258. package/tests/http-connectors-parity.test.js +0 -395
  259. package/tests/id-normalization.test.js +0 -444
  260. package/tests/include-depth-validation.test.js +0 -331
  261. package/tests/includes.test.js +0 -427
  262. package/tests/local-storage.test.js +0 -96
  263. package/tests/logical-id-write-validation.test.js +0 -151
  264. package/tests/nested-includes.test.js +0 -617
  265. package/tests/pagination-boundaries.test.js +0 -154
  266. package/tests/pagination-contract.test.js +0 -122
  267. package/tests/pagination-cursor-multifield.test.js +0 -641
  268. package/tests/pagination-enhanced.test.js +0 -563
  269. package/tests/polymorphic-relationships.test.js +0 -347
  270. package/tests/polymorphic-simple.test.js +0 -148
  271. package/tests/positioning-advanced.test.js +0 -692
  272. package/tests/positioning-extended.test.js +0 -915
  273. package/tests/positioning-multifilter.test.js +0 -699
  274. package/tests/positioning.test.js +0 -560
  275. package/tests/post-commit-hooks.test.js +0 -120
  276. package/tests/projected-fields.test.js +0 -319
  277. package/tests/public-exports.test.js +0 -15
  278. package/tests/put-create-parity.test.js +0 -216
  279. package/tests/queries.test.js +0 -521
  280. package/tests/query-limits.test.js +0 -584
  281. package/tests/relationship-endpoints.test.js +0 -620
  282. package/tests/relationship-include-storage-adapter.test.js +0 -56
  283. package/tests/relationships.test.js +0 -681
  284. package/tests/rest-api.test.js +0 -337
  285. package/tests/return-record-settings.test.js +0 -184
  286. package/tests/row-policy.test.js +0 -489
  287. package/tests/s3-storage.test.js +0 -38
  288. package/tests/searchschema-knex-behavior.test.js +0 -187
  289. package/tests/searchschema-merge.test.js +0 -151
  290. package/tests/socketio.test.js +0 -860
  291. package/tests/storage-mapping.test.js +0 -362
  292. package/tests/temporal-boundaries.test.js +0 -208
  293. package/tests/test-development-guide.md +0 -370
  294. 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
- })