json-rest-api 1.0.23 → 1.0.25

package/scripts/run-docs.js

@@ -1,30 +1,23 @@
 #!/usr/bin/env node
 
-/**
- * Run the documentation site
- *
- * This script:
- * 1. Syncs documentation files
- * 2. Builds the Jekyll site
- * 3. Starts the server
- * 4. Opens the browser
- */
-
 import { spawn } from 'child_process'
-import { promises as fs } from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 const projectRoot = path.join(__dirname, '..')
+const docsRoot = path.join(projectRoot, 'docs')
+const LOCAL_URL = 'http://localhost:4000/json-rest-api/'
+const BROWSER_DELAY_MS = 3000
 
-// Delay before opening browser (milliseconds)
-const BROWSER_DELAY = 3000
+function parseMode (argv = []) {
+  if (argv.includes('--serve') || argv.includes('--dev')) {
+    return 'serve'
+  }
 
-// Site URLs
-const LOCAL_URL = 'http://localhost:4000/json-rest-api/'
-const GITHUB_PAGES_URL = 'https://mobily-enterprises.github.io/json-rest-api/'
+  return 'build'
+}
 
 async function runCommand (command, args, options = {}) {
   return new Promise((resolve, reject) => {
@@ -38,100 +31,103 @@ async function runCommand (command, args, options = {}) {
     proc.on('exit', (code) => {
       if (code === 0) {
         resolve()
-      } else {
-        reject(new Error(`Command failed with code ${code}`))
+        return
       }
+
+      reject(new Error(`Command failed with code ${code}`))
     })
   })
 }
 
+async function ensureBundlerDependencies () {
+  try {
+    await runCommand('bundle', ['check'], { cwd: docsRoot })
+  } catch {
+    console.log('Installing Jekyll dependencies...')
+    await runCommand('bundle', ['install'], { cwd: docsRoot })
+  }
+}
+
 async function openBrowser (url) {
   const platform = process.platform
-  let command
-
-  if (platform === 'darwin') {
-    command = 'open'
-  } else if (platform === 'win32') {
-    command = 'start'
-  } else {
-    // Linux
-    command = 'xdg-open'
-  }
+  const command = platform === 'darwin'
+    ? 'open'
+    : platform === 'win32'
+      ? 'start'
+      : 'xdg-open'
 
   try {
     await runCommand(command, [url])
-    console.log(`\n🌐 Opened browser at ${url}`)
-  } catch (err) {
-    console.log(`\n💡 Visit ${url} in your browser`)
+    console.log(`Opened browser at ${url}`)
+  } catch {
+    console.log(`Visit ${url} in your browser`)
   }
 }
 
-async function main () {
-  console.log('📚 Starting documentation site...\n')
+async function buildDocs () {
+  console.log('Building documentation site...')
+  await runCommand('bundle', ['exec', 'jekyll', 'build'], { cwd: docsRoot })
+}
 
-  try {
-    // Step 1: There is no step 1
-
-    // Step 2: Install Jekyll dependencies if needed
-    const bundleLockPath = path.join(projectRoot, 'docs', 'Gemfile.lock')
-    try {
-      await fs.access(bundleLockPath)
-    } catch {
-      console.log('\n2️⃣  Installing Jekyll dependencies...')
-      await runCommand('bundle', ['install'], {
-        cwd: path.join(projectRoot, 'docs')
-      })
+async function serveDocs () {
+  console.log('Starting documentation server...')
+
+  const jekyll = spawn('bundle', ['exec', 'jekyll', 'serve', '--watch'], {
+    cwd: docsRoot,
+    stdio: 'pipe',
+    shell: true
+  })
+
+  jekyll.stdout.on('data', (data) => {
+    const output = data.toString()
+    process.stdout.write(output)
+
+    if (output.includes('Server running') || output.includes('Server address:')) {
+      setTimeout(() => openBrowser(LOCAL_URL), 1000)
     }
+  })
 
-    // Step 3: Start Jekyll server in background
-    console.log('\n3️⃣  Starting Jekyll server...')
-    const jekyll = spawn('bundle', ['exec', 'jekyll', 'serve', '--watch'], {
-      cwd: path.join(projectRoot, 'docs'),
-      stdio: 'pipe',
-      shell: true
-    })
+  jekyll.stderr.on('data', (data) => {
+    process.stderr.write(data)
+  })
 
-    // Handle server output
-    jekyll.stdout.on('data', (data) => {
-      const output = data.toString()
-      process.stdout.write(output)
+  process.on('SIGINT', () => {
+    console.log('\nShutting down Jekyll server...')
+    jekyll.kill()
+    process.exit(0)
+  })
 
-      // Open browser when server is ready
-      if (output.includes('Server running') || output.includes('Server address:')) {
-        setTimeout(() => openBrowser(LOCAL_URL), 1000)
-      }
-    })
+  jekyll.on('error', (err) => {
+    console.error('Jekyll server error:', err)
+    process.exit(1)
+  })
 
-    jekyll.stderr.on('data', (data) => {
-      process.stderr.write(data)
-    })
+  jekyll.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`Jekyll server exited with code ${code}`)
+      process.exit(code)
+    }
+  })
 
-    // Handle shutdown
-    process.on('SIGINT', () => {
-      console.log('\n\n👋 Shutting down Jekyll server...')
-      jekyll.kill()
-      process.exit(0)
-    })
+  setTimeout(() => openBrowser(LOCAL_URL), BROWSER_DELAY_MS)
+}
 
-    jekyll.on('error', (err) => {
-      console.error('❌ Jekyll server error:', err)
-      process.exit(1)
-    })
+async function main () {
+  const mode = parseMode(process.argv.slice(2))
 
-    jekyll.on('exit', (code) => {
-      if (code !== 0 && code !== null) {
-        console.error(`❌ Jekyll server exited with code ${code}`)
-        process.exit(code)
-      }
-    })
+  try {
+    await ensureBundlerDependencies()
+
+    if (mode === 'serve') {
+      await serveDocs()
+      return
+    }
 
-    // Wait a bit then try to open browser anyway (in case we missed the server ready message)
-    setTimeout(() => openBrowser(LOCAL_URL), BROWSER_DELAY)
+    await buildDocs()
   } catch (error) {
-    console.error('❌ Error:', error.message)
+    console.error('Error:', error.message)
     process.exit(1)
   }
 }
 
-// Run the script
 main()

package/test-debug.js

@@ -1,5 +1,5 @@
 import { createBasicApi } from './tests/fixtures/api-configs.js'
-import { cleanTables, createJsonApiDocument, createRelationship } from './tests/helpers/test-utils.js'
+import { cleanTables, createJsonApiDocument } from './tests/helpers/test-utils.js'
 import knex from 'knex'
 
 const dbConfig = {

package/tests/README.md

@@ -20,7 +20,7 @@ All tests MUST use `simplified: false` to ensure JSON:API compliance:
 const result = await api.resources.resourceName.method({
   inputRecord: jsonApiDocument,
   simplified: false,
-  returnFullRecord: true/false  // Based on needs
+  returnFullRecord: 'full' // Use 'no', 'minimal', or 'full' based on needs
 });
 ```
 
@@ -163,9 +163,16 @@ const result = await api.resources.books.query({
 # Run all tests
 npm test
 
+# Run the focused normalizeId verification path plus docs rebuild
+npm run verify
+
 # Run all tests against the AnyAPI storage backend
 npm run test:anyapi
 
+# Run only the normalizeId contract suites
+npm run test:id-contracts
+npm run test:id-contracts:anyapi
+
 # Windows PowerShell (AnyAPI run)
 $Env:JSON_REST_API_STORAGE = 'anyapi'; npm test
 

package/tests/anyapi-basic.test.js

@@ -70,6 +70,7 @@ describe('AnyAPI Knex Plugin - Basic Attributes', () => {
     assert.equal(result.data.attributes.name, 'Australia')
 
     const stored = await knex('any_records').first()
+    assert.equal(stored.logical_id, result.data.id)
     assert.equal(stored.string_1, 'Australia')
     assert.equal(stored.string_2, 'AU')
 
@@ -83,11 +84,13 @@ describe('AnyAPI Knex Plugin - Basic Attributes', () => {
 
   it('lists records', async () => {
     await knex('any_records').insert([{
+      logical_id: '1',
       tenant_id: 'default',
       resource: 'countries',
       string_1: 'Canada',
       string_2: 'CA',
     }, {
+      logical_id: '2',
       tenant_id: 'default',
       resource: 'countries',
       string_1: 'Brazil',

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

@@ -9,11 +9,17 @@ import {
   resourceIdentifier,
 } from './helpers/test-utils.js'
 import { storageMode } from './helpers/storage-mode.js'
+import { parseJsonApiQuery } from '../plugins/core/lib/querying-writing/connectors-query-parser.js'
 
 const isAnyApi = storageMode.isAnyApi()
 
 const maybeDescribe = isAnyApi ? describe : describe.skip
 
+const parseLinkQuery = (link) => {
+  const url = new URL(link, 'https://example.test')
+  return parseJsonApiQuery(url.search.slice(1))
+}
+
 maybeDescribe('AnyAPI Cursor Pagination', () => {
   const knex = knexLib({
     client: 'better-sqlite3',
@@ -78,7 +84,7 @@ maybeDescribe('AnyAPI Cursor Pagination', () => {
 
     assert.equal(result.data.length, 2)
     assert(result.meta?.pagination?.cursor?.next, 'Should include next cursor')
-    assert(result.links?.next?.includes('page[after]='), 'Next link should include cursor parameter')
+    assert(parseLinkQuery(result.links?.next).page.after, 'Next link should include cursor parameter')
   })
 
   it('paginates forward using page[after]', async () => {

package/tests/anyapi-custom-idproperty.test.js

@@ -0,0 +1,163 @@
+import { describe, it, before, beforeEach, after } from 'node:test'
+import assert from 'node:assert/strict'
+import knexLib from 'knex'
+import { Api } from 'hooked-api'
+
+import { RestApiPlugin, RestApiAnyapiKnexPlugin } from '../index.js'
+import { ensureAnyApiSchema } from '../plugins/core/lib/anyapi/schema-utils.js'
+import { storageMode } from './helpers/storage-mode.js'
+import {
+  createJsonApiDocument,
+  createRelationship,
+  resourceIdentifier,
+} from './helpers/test-utils.js'
+
+const maybeDescribe = storageMode.isAnyApi() ? describe : describe.skip
+
+maybeDescribe('AnyAPI custom idProperty', () => {
+  const knex = knexLib({
+    client: 'better-sqlite3',
+    connection: { filename: ':memory:' },
+    useNullAsDefault: true,
+  })
+
+  let api
+
+  before(async () => {
+    await ensureAnyApiSchema(knex)
+
+    api = new Api({ name: 'anyapi-custom-idproperty-test', log: { level: 'warn' } })
+    await api.use(RestApiPlugin, {
+      simplifiedApi: false,
+      simplifiedTransport: false,
+      returnRecordApi: {
+        post: 'full',
+        put: 'full',
+        patch: 'full',
+      },
+      sortableFields: ['id', 'owner_id', 'item_id', 'code', 'name', 'category'],
+      queryDefaultLimit: 20,
+      queryMaxLimit: 100,
+    })
+    await api.use(RestApiAnyapiKnexPlugin, { knex })
+
+    await api.addResource('owners', {
+      schema: {
+        owner_id: { type: 'id' },
+        name: { type: 'string', required: true },
+      },
+      idProperty: 'owner_id',
+      tableName: 'custom_id_owners',
+    })
+    await api.resources.owners.createKnexTable()
+
+    await api.addResource('items', {
+      schema: {
+        item_id: { type: 'id' },
+        code: { type: 'string', required: true, search: true },
+        name: { type: 'string', required: true },
+        category: { type: 'string', required: true },
+        owner_id: { type: 'id', belongsTo: 'owners', as: 'owner' },
+      },
+      idProperty: 'item_id',
+      tableName: 'custom_id_items',
+    })
+    await api.resources.items.createKnexTable()
+  })
+
+  after(async () => {
+    await api?.release()
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await knex('any_links').delete()
+    await knex('any_records').delete()
+  })
+
+  it('uses logical ids for post, get, query, sparse fields, cursors, and includes', async () => {
+    const owner = await api.resources.owners.post({
+      inputRecord: createJsonApiDocument('owners', { name: 'Owner One' }),
+      simplified: false,
+    })
+
+    const itemInputs = [
+      { code: 'A001', name: 'Apple', category: 'Fruit' },
+      { code: 'A002', name: 'Apricot', category: 'Fruit' },
+      { code: 'B001', name: 'Broccoli', category: 'Vegetable' },
+      { code: 'C001', name: 'Carrot', category: 'Vegetable' },
+    ]
+
+    const createdItems = []
+    for (const item of itemInputs) {
+      const created = await api.resources.items.post({
+        inputRecord: createJsonApiDocument(
+          'items',
+          item,
+          { owner: createRelationship(resourceIdentifier('owners', owner.data.id)) }
+        ),
+        simplified: false,
+      })
+      createdItems.push(created)
+    }
+
+    const fetched = await api.resources.items.get({
+      id: createdItems[0].data.id,
+      queryParams: {
+        include: ['owner'],
+        fields: {
+          items: 'item_id,code,name,category',
+          owners: 'owner_id,name',
+        },
+      },
+      simplified: false,
+    })
+
+    assert.equal(fetched.data.id, createdItems[0].data.id)
+    assert.equal(fetched.data.attributes.code, 'A001')
+    assert.equal(fetched.data.attributes.name, 'Apple')
+    assert.equal(fetched.data.attributes.item_id, undefined)
+    assert.equal(fetched.included?.[0]?.type, 'owners')
+    assert.equal(fetched.included?.[0]?.id, owner.data.id)
+    assert.equal(fetched.included?.[0]?.attributes.owner_id, undefined)
+
+    const firstPage = await api.resources.items.query({
+      queryParams: {
+        include: ['owner'],
+        fields: {
+          items: 'item_id,code,name,category',
+          owners: 'owner_id,name',
+        },
+        sort: ['category', 'name'],
+        page: { size: 2 },
+      },
+      simplified: false,
+    })
+
+    assert.equal(firstPage.data.length, 2)
+    assert(firstPage.meta.pagination.cursor.next, 'first page should include a next cursor')
+    assert(firstPage.data.every((item) => item.attributes.item_id === undefined))
+    assert(firstPage.included?.some((entry) => entry.type === 'owners' && entry.id === owner.data.id))
+
+    const secondPage = await api.resources.items.query({
+      queryParams: {
+        include: ['owner'],
+        fields: {
+          items: 'item_id,code,name,category',
+          owners: 'owner_id,name',
+        },
+        sort: ['category', 'name'],
+        page: {
+          size: 2,
+          after: firstPage.meta.pagination.cursor.next,
+        },
+      },
+      simplified: false,
+    })
+
+    const firstIds = firstPage.data.map((item) => item.id)
+    const secondIds = secondPage.data.map((item) => item.id)
+    assert.equal(secondPage.data.length, 2)
+    assert(!secondIds.some((id) => firstIds.includes(id)), 'cursor page should not repeat records')
+  })
+})

package/tests/custom-id-mysql-returning-fallback.test.js

@@ -0,0 +1,128 @@
+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
+
+function createMysqlStyleInsertDb (baseKnex) {
+  return (tableName) => {
+    const query = baseKnex(tableName)
+    const originalInsert = query.insert.bind(query)
+
+    query.insert = (...args) => {
+      const insertBuilder = originalInsert(...args)
+      const originalReturning = insertBuilder.returning.bind(insertBuilder)
+
+      insertBuilder.returning = async (...returnArgs) => {
+        await originalReturning(...returnArgs)
+        return [0]
+      }
+
+      return insertBuilder
+    }
+
+    return query
+  }
+}
+
+describe('Custom id POST fallback when insert returning is unusable', () => {
+  before(async () => {
+    api = new Api({
+      name: 'custom-id-mysql-returning-fallback-test'
+    })
+
+    await api.use(RestApiPlugin, {
+      simplifiedApi: true,
+      simplifiedTransport: false,
+      returnRecordApi: {
+        post: 'full',
+        put: 'full',
+        patch: 'full'
+      }
+    })
+    await api.use(RestApiKnexPlugin, { knex })
+
+    await api.addResource('user_settings', {
+      tableName: 'mysqlish_user_settings',
+      idProperty: 'user_id',
+      searchSchema: {
+        id: { type: 'id', actualField: 'id' }
+      },
+      schema: {
+        theme: { type: 'string', required: true, max: 32 }
+      }
+    })
+    await api.resources.user_settings.createKnexTable()
+  })
+
+  after(async () => {
+    await knex.destroy()
+  })
+
+  beforeEach(async () => {
+    await cleanTables(knex, ['mysqlish_user_settings'])
+  })
+
+  it('returns the explicit id for simplified POST when the insert result is 0', async () => {
+    const mysqlStyleDb = createMysqlStyleInsertDb(knex)
+
+    const created = await api.resources.user_settings.post({
+      inputRecord: {
+        id: '6',
+        theme: 'dark'
+      },
+      simplified: true,
+      transaction: mysqlStyleDb
+    })
+
+    assert.equal(created.id, '6')
+    assert.equal(created.theme, 'dark')
+
+    const dbRow = await knex('mysqlish_user_settings').where('user_id', 6).first()
+    assert.ok(dbRow)
+    assert.equal(String(dbRow.user_id), '6')
+    assert.equal(dbRow.theme, 'dark')
+  })
+
+  it('returns the explicit id for non-simplified POST when the insert result is 0', async () => {
+    const mysqlStyleDb = createMysqlStyleInsertDb(knex)
+
+    const created = await api.resources.user_settings.post({
+      inputRecord: {
+        data: {
+          type: 'user_settings',
+          id: '8',
+          attributes: {
+            theme: 'light'
+          }
+        }
+      },
+      simplified: false,
+      transaction: mysqlStyleDb
+    })
+
+    validateJsonApiStructure(created)
+    assert.equal(created.data.id, '8')
+    assert.equal(created.data.attributes.theme, 'light')
+
+    const dbRow = await knex('mysqlish_user_settings').where('user_id', 8).first()
+    assert.ok(dbRow)
+    assert.equal(String(dbRow.user_id), '8')
+    assert.equal(dbRow.theme, 'light')
+  })
+})

package/tests/db-introspection.test.js

@@ -5,6 +5,7 @@ import knexLib from 'knex'
 import { introspectKnexTableSnapshot } from '../plugins/core/lib/dbIntrospection.js'
 import { createKnexTable } from '../plugins/core/lib/dbTablesOperations.js'
 import { createBasicApi } from './fixtures/api-configs.js'
+import { storageMode } from './helpers/storage-mode.js'
 
 function createMysqlKnexRawDouble ({
   schemaName = 'appdb',
@@ -484,7 +485,9 @@ describe('dbIntrospection.introspectKnexTableSnapshot (mysql raw double)', () =>
   })
 })
 
-describe('RestApiKnexPlugin introspection scope method', () => {
+const describeKnexIntrospection = storageMode.isAnyApi() ? describe.skip : describe
+
+describeKnexIntrospection('RestApiKnexPlugin introspection scope method', () => {
   let db
   let api