json-rest-api 1.0.27 → 1.0.28

package/tests/fixtures/api-configs.js

@@ -334,6 +334,68 @@ export async function createCamelCaseBelongsToApi (knex, pluginOptions = {}) {
   return api
 }
 
+export async function createRelationshipIncludeStorageAdapterApi (knex) {
+  const api = new Api({
+    name: 'relationship-include-storage-adapter-test',
+    log: { level: process.env.LOG_LEVEL || 'info' }
+  })
+
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false
+  })
+  await api.use(RestApiKnexPlugin, { knex })
+
+  await knex.schema.createTable('uninitialized_pets', table => {
+    table.increments('id').primary()
+    table.string('first_name').notNullable()
+    table.string('last_name').notNullable()
+  })
+  await knex.schema.createTable('uninitialized_bookings', table => {
+    table.increments('id').primary()
+    table.string('reference').notNullable()
+    table.integer('pet_id').notNullable()
+  })
+
+  await api.addResource('pets', {
+    schema: {
+      id: { type: 'id' },
+      firstName: { type: 'string', required: true },
+      lastName: { type: 'string', required: true }
+    },
+    tableName: 'uninitialized_pets'
+  })
+
+  await api.addResource('bookings', {
+    schema: {
+      id: { type: 'id' },
+      reference: { type: 'string', required: true },
+      petId: {
+        type: 'id',
+        required: true,
+        belongsTo: 'pets',
+        as: 'pet'
+      }
+    },
+    tableName: 'uninitialized_bookings'
+  })
+
+  return api
+}
+
+export async function seedRelationshipIncludeStorageAdapterApi (knex) {
+  await knex('uninitialized_pets').insert({
+    id: 7,
+    first_name: 'Coco',
+    last_name: 'Spaniel'
+  })
+  await knex('uninitialized_bookings').insert({
+    id: 41,
+    reference: 'BOOK-41',
+    pet_id: 7
+  })
+}
+
 /**
  * Creates a small API focused on resource ID normalization behavior.
  */
@@ -641,7 +703,7 @@ export async function createExtendedApi (knex) {
         title: { type: 'string', max: 200 },
         content: { type: 'string', required: true, max: 5000 },
         reviewer_name: { type: 'string', required: true, max: 100 },
-        review_date: { type: 'dateTime', default: 'now()' },
+        review_date: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() },
         helpful_count: { type: 'number', default: 0 },
         reviewable_type: { type: 'string', required: true },
         reviewable_id: { type: 'number', required: true }
@@ -976,6 +1038,18 @@ export async function createComputedFieldsApi (knex, pluginOptions = {}) {
           compute: ({ attributes }) => {
             return Number((attributes.price - attributes.cost).toFixed(2))
           }
+        },
+        calculated_at: {
+          type: 'dateTime',
+          temporalPrecision: 0,
+          computed: true,
+          compute: () => new Date('2026-08-25T23:45:01.987Z')
+        },
+        calculated_time: {
+          type: 'time',
+          temporalPrecision: 3,
+          computed: true,
+          compute: () => new Date('2026-08-25T23:45:01.987Z')
         }
       },
       relationships: {
@@ -1016,6 +1090,12 @@ export async function createComputedFieldsApi (knex, pluginOptions = {}) {
             const helpfulnessScore = (attributes.helpful_votes / attributes.total_votes) * 100
             return helpfulnessScore > 70 && attributes.spam_score < 0.5
           }
+        },
+        calculated_at: {
+          type: 'dateTime',
+          temporalPrecision: 0,
+          computed: true,
+          compute: () => new Date('2026-08-25T23:46:02.654Z')
         }
       },
       tableName: 'test_reviews'
@@ -2090,7 +2170,7 @@ export async function createCustomIdPropertyApi (knex, pluginOptions = {}) {
       title: { type: 'string', max: 200 },
       content: { type: 'string', required: true, max: 5000 },
       reviewer_name: { type: 'string', required: true, max: 100 },
-      review_date: { type: 'dateTime', default: 'now()' },
+      review_date: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() },
       reviewable_type: { type: 'string', required: true, search: true },
       reviewable_id: { type: 'number', required: true },
       // Define the polymorphic field in schema
@@ -2164,7 +2244,7 @@ export async function createCursorPaginationApi (knex) {
       price: { type: 'number', required: true },
       sku: { type: 'string', required: true, max: 50, unique: true },
       status: { type: 'string', max: 50, default: 'active' },
-      createdAt: { type: 'dateTime', default: 'now()' }
+      createdAt: { type: 'dateTime', temporalPrecision: 3, defaultTo: () => new Date().toISOString() }
     },
     tableName: 'cursor_products'
   })

package/tests/pagination-cursor-multifield.test.js

@@ -337,6 +337,10 @@ describe('Multi-field Cursor Pagination', () => {
         firstPage.data.map((record) => record.attributes.name),
         ['Newest Product', 'Recent Product']
       )
+      assert.deepEqual(
+        firstPage.data.map((record) => record.attributes.createdAt),
+        ['2026-05-03T10:00:00.000Z', '2026-05-03T09:00:00.000Z']
+      )
       assert.deepEqual(
         secondPage.data.map((record) => record.attributes.name),
         ['Older Product']

package/tests/relationship-include-storage-adapter.test.js

@@ -0,0 +1,56 @@
+import { after, before, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import {
+  createRelationshipIncludeStorageAdapterApi,
+  seedRelationshipIncludeStorageAdapterApi
+} from './fixtures/api-configs.js'
+import { cleanTables } from './helpers/test-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+describe('Relationship include storage adapters', () => {
+  let api
+
+  before(async () => {
+    api = await createRelationshipIncludeStorageAdapterApi(knex)
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, [
+      'uninitialized_bookings',
+      'uninitialized_pets'
+    ])
+    await seedRelationshipIncludeStorageAdapterApi(knex)
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  it('maps sparse fields for an included scope whose adapter is not initialized', async () => {
+    assert.equal(api.resources.pets.vars.storageAdapter, undefined)
+
+    const result = await api.resources.bookings.get({
+      id: 41,
+      queryParams: {
+        include: ['pet'],
+        fields: {
+          bookings: 'reference,petId',
+          pets: 'firstName'
+        }
+      },
+      simplified: false
+    })
+
+    const includedPet = result.included.find(resource => resource.type === 'pets')
+    assert(includedPet)
+    assert.deepEqual(includedPet.attributes, { firstName: 'Coco' })
+  })
+})

package/tests/storage-mapping.test.js

@@ -4,6 +4,11 @@ import knexLib from 'knex'
 import { Api } from 'hooked-api'
 import { RestApiPlugin } from '../plugins/core/rest-api-plugin.js'
 import { RestApiKnexPlugin } from '../plugins/core/rest-api-knex-plugin.js'
+import {
+  REST_API_TEMPORAL_DATA_ERROR_CODE,
+  RestApiTemporalDataError
+} from '../lib/rest-api-errors.js'
+import { mapRestApiErrorToHttp } from '../plugins/core/connectors/lib/transport-http-helpers.js'
 import {
   cleanTables,
   createJsonApiDocument,
@@ -23,14 +28,16 @@ const knex = knexLib({
 })
 
 let api
+const DEFAULT_PROFILE_CREATED_AT = '2026-08-25T12:34:56.789Z'
+const COMPUTED_PROFILE_DATE = new Date('2026-08-25T23:45:01.987Z')
 
 const serializeDateTimeForSql = (value) => {
   if (value == null) return null
-  if (!(value instanceof Date)) {
-    throw new Error('serializeDateTimeForSql expects a Date value after schema normalization')
+  if (typeof value !== 'string') {
+    throw new Error('serializeDateTimeForSql expects an RFC 3339 string after schema validation')
   }
 
-  return value.toISOString().replace('T', ' ').slice(0, 19)
+  return new Date(value).toISOString().replace('T', ' ').slice(0, 19)
 }
 
 describe('Storage mapping', () => {
@@ -76,10 +83,27 @@ describe('Storage mapping', () => {
         lastSeenAt: {
           type: 'dateTime',
           nullable: true,
+          temporalPrecision: 0,
+          getter: (value) => value == null ? value : new Date(value),
           storage: {
             serialize: serializeDateTimeForSql
           }
         },
+        createdAt: {
+          type: 'dateTime',
+          temporalPrecision: 3,
+          defaultTo: () => new Date(DEFAULT_PROFILE_CREATED_AT).toISOString()
+        },
+        calculatedAt: {
+          type: 'dateTime',
+          temporalPrecision: 0,
+          computed: true,
+          compute: () => new Date(COMPUTED_PROFILE_DATE)
+        },
+        birthDate: { type: 'date', nullable: true },
+        openingTime: { type: 'time', nullable: true, temporalPrecision: 2 },
+        observedAtMs: { type: 'epochMilliseconds', nullable: true },
+        observedAtSeconds: { type: 'epochSeconds', nullable: true },
         countryId: {
           type: 'id',
           nullable: true,
@@ -126,7 +150,11 @@ describe('Storage mapping', () => {
         {
           displayName: 'Mercury',
           loginCount: 7,
-          lastSeenAt: '2026-01-02T03:04:05Z',
+          lastSeenAt: '2026-01-02T11:04:05+08:00',
+          birthDate: '2020-02-29',
+          openingTime: '09:30:15.12',
+          observedAtMs: '1767323045000',
+          observedAtSeconds: '1767323045',
           externalRef: 'legacy-001',
           confirmationToken: 'secret-token'
         },
@@ -142,8 +170,13 @@ describe('Storage mapping', () => {
       loginCount: 7
     })
     assert.equal(createResult.data.attributes.confirmationToken, 'secret-token')
-    assert.ok(createResult.data.attributes.lastSeenAt instanceof Date)
-    assert.equal(createResult.data.attributes.lastSeenAt.toISOString(), '2026-01-02T03:04:05.000Z')
+    assert.equal(createResult.data.attributes.lastSeenAt, '2026-01-02T03:04:05Z')
+    assert.equal(createResult.data.attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
+    assert.equal(createResult.data.attributes.calculatedAt, '2026-08-25T23:45:01Z')
+    assert.equal(createResult.data.attributes.birthDate, '2020-02-29')
+    assert.equal(createResult.data.attributes.openingTime, '09:30:15.12')
+    assert.equal(createResult.data.attributes.observedAtMs, 1767323045000)
+    assert.equal(createResult.data.attributes.observedAtSeconds, 1767323045)
     assert.ok(!('display_name' in createResult.data.attributes))
     assert.ok(!('country_id' in createResult.data.attributes))
 
@@ -151,6 +184,8 @@ describe('Storage mapping', () => {
     assert.equal(dbRecord.display_name, 'Mercury')
     assert.equal(dbRecord.login_count, 7)
     assert.equal(dbRecord.last_seen_at, '2026-01-02 03:04:05')
+    assert.equal(dbRecord.observed_at_ms, 1767323045000)
+    assert.equal(dbRecord.observed_at_seconds, 1767323045)
     assert.equal(String(dbRecord.country_id), country.data.id)
     assert.equal(dbRecord.legacy_ref, 'legacy-001')
     assert.ok(!('displayName' in dbRecord))
@@ -169,8 +204,13 @@ describe('Storage mapping', () => {
       displayName: 'Mercury',
       loginCount: 7
     })
-    assert.ok(getResult.data.attributes.lastSeenAt instanceof Date)
-    assert.equal(getResult.data.attributes.lastSeenAt.toISOString(), '2026-01-02T03:04:05.000Z')
+    assert.equal(getResult.data.attributes.lastSeenAt, '2026-01-02T03:04:05Z')
+    assert.equal(getResult.data.attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
+    assert.equal(getResult.data.attributes.calculatedAt, '2026-08-25T23:45:01Z')
+    assert.equal(getResult.data.attributes.birthDate, '2020-02-29')
+    assert.equal(getResult.data.attributes.openingTime, '09:30:15.12')
+    assert.equal(getResult.data.attributes.observedAtMs, 1767323045000)
+    assert.equal(getResult.data.attributes.observedAtSeconds, 1767323045)
     assert.ok(!('display_name' in getResult.data.attributes))
     assertResourceRelationship(
       getResult.data,
@@ -193,6 +233,8 @@ describe('Storage mapping', () => {
       displayName: 'Mercury',
       externalRef: 'legacy-001'
     })
+    assert.equal(queryResult.data[0].attributes.createdAt, DEFAULT_PROFILE_CREATED_AT)
+    assert.equal(queryResult.data[0].attributes.calculatedAt, '2026-08-25T23:45:01Z')
   })
 
   it('applies storage mapping on PATCH updates and sparse fieldsets', async () => {
@@ -228,8 +270,7 @@ describe('Storage mapping', () => {
     assert.deepEqual(Object.keys(patchResult.data.attributes).sort(), ['confirmationToken', 'displayName', 'lastSeenAt'])
     assert.equal(patchResult.data.attributes.displayName, 'After')
     assert.equal(patchResult.data.attributes.confirmationToken, 'updated-token')
-    assert.ok(patchResult.data.attributes.lastSeenAt instanceof Date)
-    assert.equal(patchResult.data.attributes.lastSeenAt.toISOString(), '2026-02-03T04:05:06.000Z')
+    assert.equal(patchResult.data.attributes.lastSeenAt, '2026-02-03T04:05:06Z')
 
     const dbRecord = await knex('mapped_profiles').where('id', created.data.id).first()
     assert.equal(dbRecord.display_name, 'After')
@@ -237,6 +278,67 @@ describe('Storage mapping', () => {
     assert.ok(!('displayName' in dbRecord))
   })
 
+  it('rejects temporal values outside the public JSON contract before storage', async () => {
+    const invalidTemporalValues = [
+      { lastSeenAt: '2026-01-02 03:04:05' },
+      { lastSeenAt: new Date('2026-01-02T03:04:05Z') },
+      { birthDate: '2026-02-30' },
+      { openingTime: '09:30Z' }
+    ]
+
+    for (const [index, temporalAttributes] of invalidTemporalValues.entries()) {
+      await assert.rejects(
+        api.resources.profiles.post({
+          inputRecord: createJsonApiDocument('profiles', {
+            displayName: `Invalid temporal value ${index}`,
+            ...temporalAttributes
+          })
+        }),
+        (error) => error?.code === 'REST_API_VALIDATION'
+      )
+    }
+  })
+
+  it('fails loudly when storage returns an invalid non-null temporal value', async () => {
+    const insertedIds = await knex('mapped_profiles').insert({
+      display_name: 'Corrupt temporal row',
+      login_count: 0,
+      last_seen_at: 'not-a-date',
+      created_at: new Date(DEFAULT_PROFILE_CREATED_AT)
+    })
+    const profileId = insertedIds[0]
+
+    await assert.rejects(
+      api.resources.profiles.get({ id: profileId }),
+      (error) => {
+        assert(error instanceof RestApiTemporalDataError)
+        assert.equal(error.code, REST_API_TEMPORAL_DATA_ERROR_CODE)
+        assert.equal(
+          error.message,
+          "Invalid database value for dateTime field 'profiles.lastSeenAt'."
+        )
+        assert.deepEqual(error.details, {
+          field: 'lastSeenAt',
+          resourceType: 'profiles',
+          fieldType: 'dateTime',
+          source: 'database'
+        })
+        assert.deepEqual(mapRestApiErrorToHttp(error), {
+          status: 500,
+          body: {
+            errors: [{
+              status: '500',
+              code: REST_API_TEMPORAL_DATA_ERROR_CODE,
+              title: 'Invalid Temporal Data',
+              detail: "Invalid database value for dateTime field 'profiles.lastSeenAt'."
+            }]
+          }
+        })
+        return true
+      }
+    )
+  })
+
   it('can opt out of snake_case translation for an entire resource', async () => {
     const created = await api.resources.verbatim_profiles.post({
       inputRecord: createJsonApiDocument('verbatim_profiles', {