json-rest-api 1.0.28 → 1.0.29

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

@@ -395,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/temporal-boundaries.test.js

@@ -0,0 +1,208 @@
+import { after, before, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { applyFieldSetters, handleRecordReturnAfterWrite } from '../plugins/core/rest-api-plugin-methods/common.js'
+import knexLib from 'knex'
+import { createTemporalBoundaryApi } from './fixtures/api-configs.js'
+import { cleanTables, createJsonApiDocument } from './helpers/test-utils.js'
+import { mapRestApiErrorToHttp } from '../plugins/core/connectors/lib/transport-http-helpers.js'
+import { normalizeAttributes, normalizeRecordAttributes } from '../plugins/core/lib/querying-writing/database-value-normalizers.js'
+import { storageMode } from './helpers/storage-mode.js'
+import { RestApiTemporalDataError } from '../lib/rest-api-errors.js'
+
+const knex = knexLib({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true })
+let api
+let finishValue
+const document = (attributes = {}) => createJsonApiDocument('events', { name: 'Event', ...attributes })
+const assertValidationError = (error) => {
+  assert.equal(error.code, 'REST_API_VALIDATION')
+  assert.equal(mapRestApiErrorToHttp(error).status, 422)
+  return true
+}
+
+describe('Temporal storage and response boundaries', () => {
+  before(async () => {
+    api = await createTemporalBoundaryApi(knex)
+    const handler = async ({ context }) => {
+      if (finishValue === undefined || context.scopeName !== 'events') return
+      const attributes = context.simplified ? context.responseRecord : context.responseRecord?.data?.attributes
+      if (attributes) attributes.producedAt = finishValue
+      if (context.simplified && attributes?.person) attributes.person.producedAt = finishValue
+      for (const included of context.responseRecord?.included || []) included.attributes.producedAt = finishValue
+    }
+    await api.customize({ hooks: {
+      finishPost: { functionName: 'temporal-finish-post', handler },
+      finishPut: { functionName: 'temporal-finish-put', handler },
+      finishPatch: { functionName: 'temporal-finish-patch', handler }
+    } })
+  })
+  after(async () => { await knex.destroy() })
+  beforeEach(async () => {
+    finishValue = undefined
+    await cleanTables(knex, ['temporal_events', 'temporal_people'])
+  })
+
+  it('rejects submillisecond writes without inserting or changing data', async () => {
+    const precise = '2026-09-01T10:20:30.123456Z'
+    await assert.rejects(api.resources.events.post({ inputRecord: document({ occurredAt: precise }) }), assertValidationError)
+    assert.equal((await api.resources.events.query()).data.length, 0)
+    const created = await api.resources.events.post({ inputRecord: document({ occurredAt: '2026-09-01T10:20:30.123000Z' }) })
+    for (const method of ['put', 'patch']) {
+      const inputRecord = document({ occurredAt: precise })
+      inputRecord.data.id = created.data.id
+      await assert.rejects(api.resources.events[method]({ id: created.data.id, inputRecord }), assertValidationError)
+      const result = await api.resources.events.get({ id: created.data.id })
+      assert.equal(result.data.attributes.occurredAt, '2026-09-01T10:20:30.123Z')
+    }
+  })
+
+  it('retains submillisecond precision supplied by storage, including timezone offsets', () => {
+    for (const value of ['2026-09-01 10:20:30.123456', '2026-09-01T18:20:30.123456+08:00']) {
+      const result = normalizeAttributes({ occurredAt: value }, { occurredAt: { type: 'dateTime', temporalPrecision: 6 } })
+      assert.equal(result.occurredAt, '2026-09-01T10:20:30.123456Z')
+    }
+  })
+
+  it('normalizes numeric epoch values returned as strings or bigints by drivers', () => {
+    const schema = { milliseconds: { type: 'epochMilliseconds' }, seconds: { type: 'epochSeconds' } }
+    assert.deepEqual(normalizeAttributes({ milliseconds: '1788258030123', seconds: 1788258030n }, schema), {
+      milliseconds: 1788258030123, seconds: 1788258030
+    })
+    for (const value of ['bad', '8640000000000001', 1.25]) {
+      assert.throws(() => normalizeAttributes({ milliseconds: value }, schema), { code: 'REST_API_TEMPORAL_DATA_INVALID' })
+    }
+  })
+
+  it('normalizes temporal query projections and follows their cursors', async () => {
+    for (let index = 0; index < 4; index++) {
+      await api.resources.events.post({ inputRecord: document({ occurredAt: `2026-09-01T10:20:3${index}.123Z` }) })
+    }
+    const queryParams = { sort: ['projectedAt'], fields: { events: 'projectedAt' }, page: { size: 2 } }
+    const first = await api.resources.events.query({ queryParams })
+    assert.equal(first.data[0].attributes.projectedAt, '2026-09-01T10:20:30.123Z')
+    const second = await api.resources.events.query({ queryParams: {
+      ...queryParams, page: { size: 2, after: first.meta.pagination.cursor.next }
+    } })
+    assert.equal(second.data[0].attributes.projectedAt, '2026-09-01T10:20:32.123Z')
+  })
+
+  it('uses a custom serializer consistently for writes and filters', { skip: storageMode.isAnyApi() }, async () => {
+    const value = '2026-09-01T10:20:30.123456Z'
+    const created = await api.resources.events.post({ inputRecord: document({ serializedAt: value }) })
+    assert.equal(created.data.attributes.serializedAt, value)
+    const filtered = await api.resources.events.query({ queryParams: { filters: { serializedAt: value } } })
+    assert.deepEqual(filtered.data.map(entry => entry.id), [created.data.id])
+  })
+
+  it('validates included fieldsets even when the relationship or collection is empty', async () => {
+    const queryParams = { include: ['person'], fields: { people: 'missingField' } }
+    await assert.rejects(api.resources.events.query({ queryParams }), { code: 'REST_API_FIELDSET_INVALID' })
+    const created = await api.resources.events.post({ inputRecord: document() })
+    await assert.rejects(api.resources.events.get({ id: created.data.id, queryParams }), { code: 'REST_API_FIELDSET_INVALID' })
+  })
+
+  it('rejects inherited object names as unknown sparse fields', async () => {
+    for (const field of ['constructor', 'toString', '__proto__']) {
+      await assert.rejects(api.resources.events.query({ queryParams: { fields: { events: field } } }), {
+        code: 'REST_API_FIELDSET_INVALID'
+      })
+    }
+  })
+
+  it('normalizes nested simplified to-many and polymorphic resources without changing ordinary objects', () => {
+    const date = new Date('2026-09-08T11:22:33.987Z')
+    const child = { id: 'child', producedAt: date }
+    const payload = { id: 'event', person: { id: 'person', events: [child, child] },
+      subject: { id: 'person', _type: 'people', producedAt: date },
+      arbitrary: { producedAt: date, value: 'unchanged' } }
+    const result = normalizeRecordAttributes(payload, api.resources, { simplified: true, resourceType: 'events', source: 'response' })
+    assert.equal(result.person.events[0].producedAt, '2026-09-08T11:22:33Z')
+    assert.equal(result.person.events[0], result.person.events[1])
+    assert.equal(result.subject.producedAt, '2026-09-08T11:22:33Z')
+    assert.equal(result.subject._type, 'people')
+    assert.equal(result.arbitrary, payload.arbitrary)
+    assert.equal(child.producedAt, date)
+  })
+
+  it('preserves typed API errors thrown by computed fields', async () => {
+    const created = await api.resources.events.post({ inputRecord: document() })
+    const definition = api.resources.events.vars.schemaInfo.computed.producedAt
+    const original = definition.compute
+    const error = new RestApiTemporalDataError({ field: 'producedAt', resourceType: 'events', fieldType: 'dateTime', source: 'response' })
+    definition.compute = () => { throw error }
+    try {
+      await assert.rejects(api.resources.events.get({ id: created.data.id }), actual => actual === error)
+    } finally {
+      definition.compute = original
+    }
+  })
+
+  it('preserves typed API errors thrown by getters', async () => {
+    const created = await api.resources.events.post({ inputRecord: document() })
+    const schemaInfo = api.resources.events.vars.schemaInfo
+    const originalGetters = schemaInfo.fieldGetters
+    const originalOrder = schemaInfo.sortedGetterFields
+    const error = new RestApiTemporalDataError({ field: 'name', resourceType: 'events', source: 'response' })
+    schemaInfo.fieldGetters = { name: { getter: () => { throw error } } }
+    schemaInfo.sortedGetterFields = ['name']
+    try {
+      await assert.rejects(api.resources.events.get({ id: created.data.id }), actual => actual === error)
+    } finally {
+      schemaInfo.fieldGetters = originalGetters
+      schemaInfo.sortedGetterFields = originalOrder
+    }
+  })
+
+  it('preserves typed errors from setters and post-write storage reads', async () => {
+    const error = new RestApiTemporalDataError({ field: 'occurredAt', resourceType: 'events' })
+    await assert.rejects(applyFieldSetters({ occurredAt: '2026-09-08T00:00:00Z' }, {
+      fieldSetters: { occurredAt: { setter: () => { throw error } } },
+      sortedSetterFields: ['occurredAt']
+    }, { scopeName: 'events' }), actual => actual === error)
+    await assert.rejects(handleRecordReturnAfterWrite({
+      context: { method: 'POST' }, scopeName: 'events',
+      helpers: { dataGetMinimal: async () => { throw error } },
+      log: { warn () {} }
+    }), actual => actual === error)
+  })
+
+  for (const direction of ['after', 'before']) {
+    it(`rejects malformed temporal and numeric values in page[${direction}] as client errors`, async () => {
+      for (const [field, value] of [['occurredAt', 'garbage'], ['day', '2026-02-30'], ['atTime', '25:30'], ['observedAtMs', 'NaN']]) {
+        await assert.rejects(api.resources.events.query({ queryParams: {
+          sort: [field], page: { size: 2, [direction]: `${field}:${encodeURIComponent(value)},id:1` }
+        } }), (error) => {
+          assertValidationError(error)
+          assert.deepEqual(error.details.fields, [`page.${direction}`])
+          return true
+        })
+      }
+    })
+  }
+
+  for (const simplified of [false, true]) {
+    for (const method of ['post', 'put', 'patch']) {
+      it(`normalizes ${method} finish values and included resources with simplified=${simplified}`, async () => {
+        const person = await api.resources.people.post({ inputRecord: createJsonApiDocument('people', { name: 'Person' }) })
+        const inputRecord = document()
+        inputRecord.data.relationships = { person: { data: { type: 'people', id: person.data.id } } }
+        const created = method === 'post' ? null : await api.resources.events.post({ inputRecord })
+        if (created) inputRecord.data.id = created.data.id
+        finishValue = new Date('2026-09-08T11:22:33.987Z')
+        const result = await api.resources.events[method]({
+          ...(created ? { id: created.data.id } : {}), inputRecord,
+          queryParams: { include: ['person'] }, simplified
+        })
+        assert.equal((simplified ? result : result.data.attributes).producedAt, '2026-09-08T11:22:33Z')
+        assert.equal((simplified ? result.person : result.included[0].attributes).producedAt, '2026-09-08T11:22:33Z')
+      })
+    }
+    it(`rejects invalid finish values with simplified=${simplified}`, async () => {
+      finishValue = 'not-a-date'
+      await assert.rejects(api.resources.events.post({ inputRecord: document(), simplified }), (error) => {
+        assert.equal(error.code, 'REST_API_TEMPORAL_DATA_INVALID')
+        assert.equal(mapRestApiErrorToHttp(error).status, 500)
+        return true
+      })
+    })
+  }
+})