json-rest-api 1.0.27 → 1.0.29

package/tests/fixtures/api-configs.js

@@ -58,6 +58,63 @@ async function withTenantContext (tenantId, fn) {
   }
 }
 
+export async function createTemporalBoundaryApi (knex) {
+  const api = new Api({ name: 'temporal-boundaries', log: { level: 'error' } })
+  await api.use(RestApiPlugin, {
+    simplifiedApi: false,
+    simplifiedTransport: false,
+    returnRecordApi: { post: 'full', put: 'full', patch: 'full' },
+    queryDefaultLimit: 2,
+    queryMaxLimit: 3
+  })
+  await api.use(QueryProjectionsPlugin)
+  await useStoragePlugin(api, knex)
+  const producedAt = {
+    type: 'dateTime', temporalPrecision: 0, computed: true,
+    compute: () => new Date('2026-09-08T01:02:03.456Z')
+  }
+  await api.addResource('people', {
+    schema: { id: { type: 'id' }, name: { type: 'string' }, producedAt },
+    relationships: { events: { type: 'hasMany', target: 'events', foreignKey: 'personId' } },
+    tableName: 'temporal_people'
+  })
+  await api.resources.people.createKnexTable()
+  mapTable('temporal_people', 'people')
+  await api.addResource('events', {
+    sortableFields: ['id', 'name', 'occurredAt', 'day', 'atTime', 'observedAtMs'],
+    schema: {
+      id: { type: 'id' },
+      name: { type: 'string', required: true },
+      occurredAt: { type: 'dateTime', temporalPrecision: 6, nullable: true, search: true },
+      day: { type: 'date', nullable: true, search: true },
+      atTime: { type: 'time', temporalPrecision: 3, nullable: true, search: true },
+      observedAtMs: { type: 'epochMilliseconds', nullable: true, search: true },
+      observedAtSeconds: { type: 'epochSeconds', nullable: true, search: true },
+      serializedAt: {
+        type: 'dateTime', temporalPrecision: 6, nullable: true, search: true,
+        storage: { serialize: value => value == null ? null : value.replace('T', ' ').replace(/Z$/, '') }
+      },
+      personId: { type: 'id', belongsTo: 'people', as: 'person', nullable: true },
+      subjectId: { type: 'number', nullable: true },
+      subjectType: { type: 'string', nullable: true },
+      producedAt
+    },
+    queryFields: {
+      projectedAt: {
+        type: 'dateTime', temporalPrecision: 3, sortable: true,
+        select: ({ knex, column }) => knex.raw('??', [column('occurredAt')])
+      }
+    },
+    relationships: {
+      subject: { belongsToPolymorphic: { types: ['people'], typeField: 'subjectType', idField: 'subjectId' } }
+    },
+    tableName: 'temporal_events'
+  })
+  await api.resources.events.createKnexTable()
+  mapTable('temporal_events', 'events')
+  return api
+}
+
 /**
  * Creates a basic API configuration with Countries, Publishers, Authors, Books
  */
@@ -334,6 +391,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 +760,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 +1095,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 +1147,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 +2227,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 +2301,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-boundaries.test.js

@@ -0,0 +1,154 @@
+import { after, before, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { createTemporalBoundaryApi } from './fixtures/api-configs.js'
+import { cleanTables, createJsonApiDocument } from './helpers/test-utils.js'
+import { createCursor, parseCursor } from '../plugins/core/lib/querying/knex-pagination-helpers.js'
+
+const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
+let api
+let ids
+
+describe('Pagination boundary audit', () => {
+  before(async () => { api = await createTemporalBoundaryApi(knex) })
+  after(async () => { await knex.destroy() })
+  beforeEach(async () => {
+    await cleanTables(knex, ['temporal_events', 'temporal_people'])
+    ids = []
+    for (let index = 0; index < 8; index++) {
+      const result = await api.resources.events.post({ inputRecord: createJsonApiDocument('events', {
+        name: `Event ${index}`, occurredAt: `2026-09-01T10:20:3${index}.000Z`
+      }), simplified: false })
+      ids.push(result.data.id)
+    }
+  })
+
+  it('rejects zero, negative, fractional and conflicting page parameters', async () => {
+    for (const page of [
+      { size: 0 }, { size: -1 }, { size: 0.5 }, { number: 0 }, { number: -1 }, { number: 1.5 },
+      { after: '' }, { after: 'id:1', before: 'id:8' }, { number: 1, after: 'id:1' }
+    ]) {
+      await assert.rejects(api.resources.events.query({ queryParams: { page }, simplified: false }), {
+        code: 'REST_API_VALIDATION'
+      }, JSON.stringify(page))
+    }
+  })
+
+  it('returns the adjacent page before a cursor rather than restarting at the beginning', async () => {
+    const result = await api.resources.events.query({ queryParams: {
+      sort: ['id'], page: { size: 2, before: `id:${ids[6]}` }
+    }, simplified: false })
+    assert.deepEqual(result.data.map(entry => entry.id), ids.slice(4, 6))
+    assert.equal(result.meta.pagination.hasMore, true)
+    const next = await api.resources.events.query({ queryParams: {
+      sort: ['id'], page: { size: 2, before: result.meta.pagination.cursor.next }
+    }, simplified: false })
+    assert.deepEqual(next.data.map(entry => entry.id), ids.slice(2, 4))
+    assert.equal(new URL(result.links.next, 'https://api.test').searchParams.get('page[before]'), result.meta.pagination.cursor.next)
+  })
+
+  it('caps default limits even without explicit page parameters', async () => {
+    const original = api.resources.events.vars.queryDefaultLimit
+    api.resources.events.vars.queryDefaultLimit = 20
+    try {
+      assert.equal((await api.resources.events.query({ simplified: false })).data.length, 3)
+    } finally {
+      api.resources.events.vars.queryDefaultLimit = original
+    }
+  })
+
+  it('distinguishes null values from literal strings in cursors and rejects duplicate fields', () => {
+    for (const value of [null, '~null', 'null', '', 'colon:comma,']) {
+      const cursor = createCursor({ id: 'opaque:id', name: value }, ['name', 'id'])
+      assert.equal(parseCursor(cursor).name, value)
+      assert.equal(parseCursor(cursor).id, 'opaque:id')
+    }
+    assert.throws(() => parseCursor('id:1,id:2'), /Duplicate/)
+  })
+
+  it('generates usable cursors when a sort field is repeated', async () => {
+    const sort = ['name', 'name', 'id', 'id']
+    const first = await api.resources.events.query({ queryParams: { sort, page: { size: 2 } } })
+    const second = await api.resources.events.query({ queryParams: {
+      sort, page: { size: 2, after: first.meta.pagination.cursor.next }
+    } })
+    assert.deepEqual(second.data.map(entry => entry.id), ids.slice(2, 4))
+  })
+
+  it('validates schema sorts without an explicit allowlist, alongside query projections', async () => {
+    const original = api.resources.events.vars.sortableFields
+    api.resources.events.vars.sortableFields = []
+    try {
+      for (const field of ['name', 'occurredAt', 'projectedAt']) {
+        const result = await api.resources.events.query({ queryParams: { sort: [field], page: { size: 2 } } })
+        assert.deepEqual(result.data.map(entry => entry.id), ids.slice(0, 2))
+      }
+      for (const field of ['missingField', 'constructor', 'producedAt']) {
+        await assert.rejects(api.resources.events.query({ queryParams: { sort: [field] } }), {
+          code: 'REST_API_VALIDATION'
+        })
+      }
+      await assert.rejects(api.resources.people.query({ queryParams: { sort: ['missingField'] } }), {
+        code: 'REST_API_VALIDATION'
+      })
+    } finally {
+      api.resources.events.vars.sortableFields = original
+    }
+  })
+
+  it('generates valid last-page links for an empty collection', async () => {
+    await cleanTables(knex, ['temporal_events', 'temporal_people'])
+    const original = api.resources.events.vars.enablePaginationCounts
+    api.resources.events.vars.enablePaginationCounts = true
+    try {
+      const result = await api.resources.events.query({ queryParams: { page: { number: 1, size: 2 } } })
+      const last = new URL(result.links.last, 'https://api.test')
+      const finalPage = await api.resources.events.query({ queryParams: {
+        page: { number: last.searchParams.get('page[number]'), size: last.searchParams.get('page[size]') }
+      } })
+      assert.deepEqual(finalPage.data, [])
+    } finally {
+      api.resources.events.vars.enablePaginationCounts = original
+    }
+  })
+
+  for (const sort of [['occurredAt'], ['-occurredAt']]) {
+    it(`traverses null sort values exactly once in both directions with sort=${sort}`, async () => {
+      for (const id of [ids[1], ids[4], ids[6]]) {
+        await api.resources.events.patch({ id, inputRecord: { data: {
+          type: 'events', id, attributes: { occurredAt: null }
+        } }, simplified: false })
+      }
+      const seen = []
+      let after
+      const pages = []
+      for (let index = 0; index < 6; index++) {
+        const page = await api.resources.events.query({ queryParams: {
+          sort, page: { size: 2, ...(after ? { after } : {}) }
+        }, simplified: false })
+        pages.push(page)
+        seen.push(...page.data.map(entry => entry.id))
+        after = page.meta.pagination.cursor?.next
+        if (!after) break
+      }
+      assert.equal(after, undefined)
+      assert.equal(seen.length, ids.length)
+      assert.equal(new Set(seen).size, ids.length)
+      const nonNull = ids.filter(id => ![ids[1], ids[4], ids[6]].includes(id))
+      if (sort[0].startsWith('-')) nonNull.reverse()
+      assert.deepEqual(seen.slice(0, nonNull.length), nonNull)
+
+      const firstOfLast = pages.at(-1).data[0]
+      let before = createCursor({ id: firstOfLast.id, ...firstOfLast.attributes }, ['occurredAt', 'id'])
+      const reversed = [...pages.at(-1).data.map(entry => entry.id)]
+      for (let index = 0; index < 6; index++) {
+        const page = await api.resources.events.query({ queryParams: { sort, page: { size: 2, before } }, simplified: false })
+        reversed.unshift(...page.data.map(entry => entry.id))
+        before = page.meta.pagination.cursor?.next
+        if (!before) break
+      }
+      assert.equal(before, undefined)
+      assert.deepEqual(reversed, seen)
+    })
+  }
+})

package/tests/pagination-contract.test.js

@@ -0,0 +1,122 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { createCursorPaginationApi } from './fixtures/api-configs.js'
+import { cleanTables, createJsonApiDocument } from './helpers/test-utils.js'
+import { storageMode } from './helpers/storage-mode.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: { filename: ':memory:' },
+  useNullAsDefault: true
+})
+const recordCount = 205
+let api
+
+describe('Knex pagination contract', { skip: storageMode.isAnyApi() }, () => {
+  before(async () => {
+    api = await createCursorPaginationApi(knex)
+    api.resources.products.vars.defaultSort = ['-createdAt']
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['cursor_products'])
+    for (let index = 0; index < recordCount; index++) {
+      await api.resources.products.post({
+        inputRecord: createJsonApiDocument('products', {
+          name: `Product ${index}`,
+          category: 'Fixture',
+          brand: 'Fixture',
+          price: index,
+          sku: `PAGE-${index}`,
+          createdAt: new Date(Date.UTC(2026, 8, 1, 0, 0, Math.floor(index / 3))).toISOString()
+        }),
+        simplified: false
+      })
+    }
+  })
+
+  it('traverses every record once when sparse fields omit the default sort field', async () => {
+    const expected = await knex('cursor_products').orderBy('created_at', 'desc').orderBy('id', 'asc').pluck('id')
+    const ids = []
+    const cursors = new Set()
+    let cursor
+
+    for (let page = 0; page < 4; page++) {
+      const result = await api.resources.products.query({
+        queryParams: {
+          fields: { products: 'name' },
+          page: { size: 100, ...(cursor ? { after: cursor } : {}) }
+        },
+        simplified: false
+      })
+      for (const record of result.data) {
+        assert.deepEqual(Object.keys(record.attributes), ['name'])
+        ids.push(record.id)
+      }
+      cursor = result.meta.pagination.cursor?.next
+      assert.equal(result.meta.pagination.hasMore, Boolean(cursor))
+      if (!cursor) break
+      assert.equal(cursors.has(cursor), false, 'Each cursor must advance')
+      cursors.add(cursor)
+      assert.match(cursor, /createdAt:/)
+    }
+
+    assert.equal(cursor, undefined, 'Traversal must reach the end')
+    assert.deepEqual(ids, expected.map(String))
+    assert.equal(new Set(ids).size, recordCount)
+  })
+
+  for (const mode of ['cursor', 'offset']) {
+    it(`uses the capped size for ${mode} pages, metadata, and links`, async () => {
+      const expected = await knex('cursor_products').orderBy('id', 'asc').pluck('id')
+      const ids = []
+      let cursor
+
+      for (let page = 1; page <= 3; page++) {
+        const result = await api.resources.products.query({
+          queryParams: {
+            sort: ['id'],
+            page: {
+              size: 200,
+              ...(mode === 'offset' ? { number: page } : cursor ? { after: cursor } : {})
+            }
+          },
+          simplified: false
+        })
+        ids.push(...result.data.map(record => record.id))
+        assert.equal(result.data.length, page < 3 ? 100 : 5)
+        assert.equal(result.meta.pagination.pageSize, 100)
+        assert.equal(result.meta.pagination.hasMore, page < 3)
+        assert.equal(Boolean(result.links.next), page < 3)
+        if (result.links.next) {
+          assert.equal(new URL(result.links.next, 'https://api.example.com').searchParams.get('page[size]'), '100')
+        }
+        cursor = result.meta.pagination.cursor?.next
+        if (mode === 'cursor') assert.equal(Boolean(cursor), page < 3)
+      }
+
+      assert.deepEqual(ids, expected.map(String))
+      assert.equal(new Set(ids).size, recordCount)
+    })
+  }
+
+  it('rejects cursors missing any sort value in either direction', async () => {
+    for (const direction of ['after', 'before']) {
+      for (const cursor of ['id:1', 'createdAt:2026-09-01T00%3A00%3A00.000Z']) {
+        await assert.rejects(api.resources.products.query({
+          queryParams: { page: { size: 100, [direction]: cursor } },
+          simplified: false
+        }), (error) => {
+          assert.equal(error.code, 'REST_API_VALIDATION')
+          assert.match(error.message, /Cursor.*missing.*sort field/i)
+          return true
+        })
+      }
+    }
+  })
+})

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']
@@ -391,9 +395,7 @@ describe('Multi-field Cursor Pagination', () => {
         queryParams: {
           page: {
             size: 4,
-            before: secondPage.meta.pagination.cursor?.next ||
-                    // If no next cursor, create one from the last record
-                    `category:${encodeURIComponent(secondPage.data[0].attributes.category)},name:${encodeURIComponent(secondPage.data[0].attributes.name)},id:${encodeURIComponent(secondPage.data[0].id)}`
+            before: `category:${encodeURIComponent(secondPage.data[0].attributes.category)},name:${encodeURIComponent(secondPage.data[0].attributes.name)},id:${encodeURIComponent(secondPage.data[0].id)}`
           },
           sort: ['category', 'name']
         },

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' })
+  })
+})