json-rest-api 1.0.23 → 1.0.24

package/tests/logical-id-write-validation.test.js

@@ -0,0 +1,151 @@
+import { describe, it, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+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 {
+  cleanTables,
+  validateJsonApiStructure,
+} from './helpers/test-utils.js'
+
+const knex = knexLib({
+  client: 'better-sqlite3',
+  connection: {
+    filename: ':memory:'
+  },
+  useNullAsDefault: true
+})
+
+let api
+
+describe('Logical resource ids in write validation', () => {
+  before(async () => {
+    api = new Api({
+      name: 'logical-id-write-validation-test'
+    })
+
+    await api.use(RestApiPlugin, {
+      simplifiedApi: false,
+      simplifiedTransport: false,
+      returnRecordApi: {
+        post: 'full',
+        put: 'full',
+        patch: 'full'
+      }
+    })
+    await api.use(RestApiKnexPlugin, { knex })
+
+    await api.addResource('profiles', {
+      tableName: 'logical_id_profiles',
+      idProperty: 'user_id',
+      schema: {
+        id: { type: 'id', required: true, storage: { column: 'user_id' } },
+        name: { type: 'string', required: true, max: 64 }
+      }
+    })
+    await api.resources.profiles.createKnexTable()
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['logical_id_profiles'])
+  })
+
+  it('accepts explicit resource ids in non-simplified POST without exposing id as an attribute', async () => {
+    const created = await api.resources.profiles.post({
+      inputRecord: {
+        data: {
+          type: 'profiles',
+          id: '101',
+          attributes: {
+            name: 'Alice'
+          }
+        }
+      }
+    })
+
+    validateJsonApiStructure(created)
+    assert.equal(created.data.id, '101')
+    assert.equal(created.data.attributes.name, 'Alice')
+    assert.ok(!('id' in created.data.attributes))
+
+    const dbRow = await knex('logical_id_profiles').where('user_id', 101).first()
+    assert.ok(dbRow)
+    assert.equal(String(dbRow.user_id), '101')
+    assert.equal(dbRow.name, 'Alice')
+  })
+
+  it('reports missing logical ids against data.id during POST validation', async () => {
+    await assert.rejects(
+      () => api.resources.profiles.post({
+        inputRecord: {
+          data: {
+            type: 'profiles',
+            attributes: {
+              name: 'Missing Id'
+            }
+          }
+        }
+      }),
+      (error) => {
+        assert.equal(error.code, 'REST_API_VALIDATION')
+        assert.deepEqual(error.details?.fields, ['data.id'])
+        assert.equal(error.details?.violations?.[0]?.field, 'data.id')
+        return true
+      }
+    )
+  })
+
+  it('accepts explicit resource ids in simplified POST and still keeps id out of attributes', async () => {
+    const created = await api.resources.profiles.post({
+      id: '202',
+      name: 'Bob'
+    })
+
+    assert.equal(created.id, '202')
+    assert.equal(created.name, 'Bob')
+
+    const fetched = await api.resources.profiles.get({
+      id: '202',
+      simplified: false
+    })
+
+    validateJsonApiStructure(fetched)
+    assert.equal(fetched.data.id, '202')
+    assert.equal(fetched.data.attributes.name, 'Bob')
+    assert.ok(!('id' in fetched.data.attributes))
+  })
+
+  it('accepts logical id validation through PUT full replacement', async () => {
+    await knex('logical_id_profiles').insert({
+      user_id: 303,
+      name: 'Before'
+    })
+
+    const updated = await api.resources.profiles.put({
+      id: '303',
+      inputRecord: {
+        data: {
+          type: 'profiles',
+          id: '303',
+          attributes: {
+            name: 'After'
+          }
+        }
+      }
+    })
+
+    validateJsonApiStructure(updated)
+    assert.equal(updated.data.id, '303')
+    assert.equal(updated.data.attributes.name, 'After')
+    assert.ok(!('id' in updated.data.attributes))
+
+    const dbRow = await knex('logical_id_profiles').where('user_id', 303).first()
+    assert.ok(dbRow)
+    assert.equal(dbRow.name, 'After')
+  })
+})

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

@@ -55,7 +55,7 @@ describe('Multi-field Cursor Pagination', () => {
       }
     })
 
-    it.skip('should handle cursor pagination with multi-field sorting without skipping records', async () => {
+    it('should handle cursor pagination with multi-field sorting without skipping records', async () => {
       // Sort by category first (which has duplicates), then by name
       const pageSize = 3
       const allProducts = []
@@ -102,7 +102,7 @@ describe('Multi-field Cursor Pagination', () => {
       assert.equal(ids.length, uniqueIds.length, 'Should have no duplicate products')
     })
 
-    it.skip('should handle DESC sorting with duplicates correctly', async () => {
+    it('should handle DESC sorting with duplicates correctly', async () => {
       // Sort by category DESC, then name ASC
       const firstPage = await api.resources.products.query({
         queryParams: {
@@ -189,7 +189,7 @@ describe('Multi-field Cursor Pagination', () => {
         'Green Gardens vegetables should be in alphabetical order by name')
     })
 
-    it.skip('should handle cursor pagination with numeric and text fields', async () => {
+    it('should handle cursor pagination with numeric and text fields', async () => {
       // Sort by price (numeric), then category (text), then name (text)
       const firstPage = await api.resources.products.query({
         queryParams: {
@@ -222,7 +222,7 @@ describe('Multi-field Cursor Pagination', () => {
         'Prices should be non-decreasing across pages')
     })
 
-    it.skip('should generate correct cursor values for multi-field sorting', async () => {
+    it('should generate correct cursor values for multi-field sorting', async () => {
       const result = await api.resources.products.query({
         queryParams: {
           page: { size: 3 },
@@ -244,7 +244,7 @@ describe('Multi-field Cursor Pagination', () => {
       assert(cursor.includes('name:'), 'Cursor should include name field')
     })
 
-    it.skip('should handle page[before] with multi-field sorting', async () => {
+    it('should handle page[before] with multi-field sorting', async () => {
       // First, get to the middle of the dataset
       const firstPage = await api.resources.products.query({
         queryParams: {
@@ -272,7 +272,7 @@ describe('Multi-field Cursor Pagination', () => {
             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)}`
+                    `category:${encodeURIComponent(secondPage.data[0].attributes.category)},name:${encodeURIComponent(secondPage.data[0].attributes.name)},id:${encodeURIComponent(secondPage.data[0].id)}`
           },
           sort: ['category', 'name']
         },
@@ -292,7 +292,7 @@ describe('Multi-field Cursor Pagination', () => {
       await cleanTables(knex, ['cursor_products', 'cursor_items'])
     })
 
-    it.skip('should handle all records having the same value in first sort field', async () => {
+    it('should handle all records having the same value in first sort field', async () => {
       // Create products all in the same category
       const products = [
         { name: 'Alpha', category: 'Electronics', brand: 'TechCo', price: 100, sku: 'TC-001' },
@@ -348,7 +348,7 @@ describe('Multi-field Cursor Pagination', () => {
       assert(gadgetIncIndex < firstTechCoIndex, 'GadgetInc products should come before TechCo')
     })
 
-    it.skip('should handle empty results with multi-field cursor', async () => {
+    it('should handle empty results with multi-field cursor', async () => {
       // Create one product
       await api.resources.products.post({
         inputRecord: createJsonApiDocument('products', {
@@ -375,7 +375,7 @@ describe('Multi-field Cursor Pagination', () => {
       assert(!firstPage.meta.pagination.cursor?.next, 'Should not have next cursor on last page')
     })
 
-    it.skip('should handle special characters in multi-field cursors', async () => {
+    it('should handle special characters in multi-field cursors', async () => {
       // Create products with special characters
       const products = [
         { name: 'Product: Special', category: 'Cat:1', brand: 'Brand,A', price: 10, sku: 'SP-001' },
@@ -418,7 +418,7 @@ describe('Multi-field Cursor Pagination', () => {
         'Should get different record on second page')
     })
 
-    it.skip('should maintain stable sorting with custom id property', async () => {
+    it('should maintain stable sorting with custom id property', async () => {
       // Create items using the resource with custom ID property
       const items = [
         { code: 'A001', name: 'Apple', category: 'Fruit', type: 'Fresh' },
@@ -464,7 +464,7 @@ describe('Multi-field Cursor Pagination', () => {
       }
     })
 
-    it.skip('should handle the exact bug scenario - multiple fruits with same category', async () => {
+    it('should handle the exact bug scenario - multiple fruits with same category', async () => {
       // This is the exact scenario from the bug report
       await cleanTables(knex, ['cursor_products'])
 

package/tests/storage-mapping.test.js

@@ -70,13 +70,12 @@ describe('Storage mapping', () => {
     await api.addResource('profiles', {
       schema: {
         id: { type: 'id' },
-        displayName: { type: 'string', required: true, storage: { column: 'display_name' } },
-        loginCount: { type: 'number', defaultTo: 0, storage: { column: 'login_count' } },
+        displayName: { type: 'string', required: true, search: true },
+        loginCount: { type: 'number', defaultTo: 0 },
         lastSeenAt: {
           type: 'dateTime',
           nullable: true,
           storage: {
-            column: 'last_seen_at',
             serialize: serializeDateTimeForSql
           }
         },
@@ -84,14 +83,25 @@ describe('Storage mapping', () => {
           type: 'id',
           nullable: true,
           belongsTo: 'countries',
-          as: 'country',
-          storage: { column: 'country_id' }
+          as: 'country'
         },
+        externalRef: { type: 'string', nullable: true, search: true, storage: { column: 'legacy_ref' } },
         confirmationToken: { type: 'string', virtual: true }
       },
       tableName: 'mapped_profiles'
     })
     await api.resources.profiles.createKnexTable()
+
+    await api.addResource('verbatim_profiles', {
+      storage: { naming: 'exact' },
+      schema: {
+        id: { type: 'id' },
+        displayName: { type: 'string', required: true },
+        loginCount: { type: 'number', defaultTo: 0 }
+      },
+      tableName: 'verbatim_profiles'
+    })
+    await api.resources.verbatim_profiles.createKnexTable()
   })
 
   after(async () => {
@@ -99,7 +109,7 @@ describe('Storage mapping', () => {
   })
 
   beforeEach(async () => {
-    await cleanTables(knex, ['mapped_profiles', 'mapped_countries'])
+    await cleanTables(knex, ['mapped_profiles', 'mapped_countries', 'verbatim_profiles'])
   })
 
   it('persists mapped columns while exposing logical field names', async () => {
@@ -116,6 +126,7 @@ describe('Storage mapping', () => {
           displayName: 'Mercury',
           loginCount: 7,
           lastSeenAt: '2026-01-02T03:04:05Z',
+          externalRef: 'legacy-001',
           confirmationToken: 'secret-token'
         },
         {
@@ -140,6 +151,7 @@ describe('Storage mapping', () => {
     assert.equal(dbRecord.login_count, 7)
     assert.equal(dbRecord.last_seen_at, '2026-01-02 03:04:05')
     assert.equal(String(dbRecord.country_id), country.data.id)
+    assert.equal(dbRecord.legacy_ref, 'legacy-001')
     assert.ok(!('displayName' in dbRecord))
     assert.ok(!('countryId' in dbRecord))
     assert.ok(!('confirmationToken' in dbRecord))
@@ -164,6 +176,22 @@ describe('Storage mapping', () => {
       'country',
       resourceIdentifier('countries', country.data.id)
     )
+
+    const queryResult = await api.resources.profiles.query({
+      queryParams: {
+        filters: {
+          displayName: 'Mercury',
+          externalRef: 'legacy-001'
+        }
+      }
+    })
+
+    validateJsonApiStructure(queryResult, true)
+    assert.equal(queryResult.data.length, 1)
+    assertResourceAttributes(queryResult.data[0], {
+      displayName: 'Mercury',
+      externalRef: 'legacy-001'
+    })
   })
 
   it('applies storage mapping on PATCH updates and sparse fieldsets', async () => {
@@ -207,4 +235,25 @@ describe('Storage mapping', () => {
     assert.equal(dbRecord.last_seen_at, '2026-02-03 04:05:06')
     assert.ok(!('displayName' in dbRecord))
   })
+
+  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', {
+        displayName: 'Exact Mode',
+        loginCount: 3
+      })
+    })
+
+    validateJsonApiStructure(created)
+    assertResourceAttributes(created.data, {
+      displayName: 'Exact Mode',
+      loginCount: 3
+    })
+
+    const dbRecord = await knex('verbatim_profiles').where('id', created.data.id).first()
+    assert.equal(dbRecord.displayName, 'Exact Mode')
+    assert.equal(dbRecord.loginCount, 3)
+    assert.equal(Object.hasOwn(dbRecord, 'display_name'), false)
+    assert.equal(Object.hasOwn(dbRecord, 'login_count'), false)
+  })
 })