json-rest-api 1.0.23 → 1.0.24

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

@@ -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/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
 

package/tests/db-table-operations.test.js

@@ -118,10 +118,10 @@ describe('dbTablesOperations.createKnexTable', () => {
 
     await db('users').insert({ username: 'testuser' })
     const user = await db('users').where('username', 'testuser').first()
-    await db('posts').insert({ title: 'Test Post', userId: user.id })
+    await db('posts').insert({ title: 'Test Post', user_id: user.id })
 
     const posts = await db('posts')
-      .join('users', 'posts.userId', 'users.id')
+      .join('users', 'posts.user_id', 'users.id')
       .select('posts.title', 'users.username')
 
     assert.equal(posts.length, 1)
@@ -173,10 +173,11 @@ describe('dbTablesOperations.createKnexTable', () => {
     })
   })
 
-  it('uses storage column overrides when creating tables', async () => {
+  it('defaults storage columns to snake_case and keeps per-field overrides', async () => {
     const schema = makeTableSchema({
-      displayName: { type: 'string', required: true, storage: { column: 'display_name' } },
-      lastSeenAt: { type: 'dateTime', storage: { column: 'last_seen_at' } }
+      displayName: { type: 'string', required: true },
+      lastSeenAt: { type: 'dateTime' },
+      externalRef: { type: 'string', storage: { column: 'legacy_ref' } }
     })
 
     await createKnexTable(db, makeSchemaInfo('mapped_profiles'), schema)
@@ -185,7 +186,9 @@ describe('dbTablesOperations.createKnexTable', () => {
     assert.ok(info.id)
     assert.ok(info.display_name)
     assert.ok(info.last_seen_at)
+    assert.ok(info.legacy_ref)
     assert.equal(info.displayName, undefined)
+    assert.equal(info.external_ref, undefined)
   })
 
   it('supports logical id fields mapped to custom storage columns', async () => {
@@ -221,10 +224,10 @@ describe('dbTablesOperations.createKnexTable', () => {
     `)
 
     const schema = makeTableSchema({
-      workspaceId: { type: 'id', required: true, storage: { column: 'workspace_id' } },
-      userId: { type: 'id', required: true, storage: { column: 'user_id' } },
+      workspaceId: { type: 'id', required: true },
+      userId: { type: 'id', required: true },
       role: { type: 'string', enum: ['owner', 'member'], required: true, defaultTo: 'member' },
-      noteCount: { type: 'number', defaultTo: 0, storage: { column: 'note_count' } }
+      noteCount: { type: 'number', defaultTo: 0 }
     }, {
       indexes: [
         {
@@ -352,20 +355,22 @@ describe('dbTablesOperations.generateKnexMigration', () => {
     assert.ok(migration.includes("table.string('title', 200).notNullable()"))
     assert.ok(migration.includes("table.decimal('price', 10, 2)"))
     assert.ok(migration.includes(".defaultTo(true)"))
-    assert.ok(migration.includes("table.foreign(['categoryId'], 'products_categoryId_foreign').references(['id']).inTable('categories').onDelete('SET NULL')"))
+    assert.ok(migration.includes("table.foreign(['category_id'], 'products_category_id_foreign').references(['id']).inTable('categories').onDelete('SET NULL')"))
     assert.ok(migration.includes('table.timestamps(true, true)'))
   })
 
-  it('uses storage column overrides in generated migrations', () => {
+  it('uses default snake_case columns in generated migrations and keeps per-field overrides', () => {
     const schema = makeTableSchema({
-      displayName: { type: 'string', required: true, storage: { column: 'display_name' } },
-      loginCount: { type: 'number', defaultTo: 0, storage: { column: 'login_count' } }
+      displayName: { type: 'string', required: true },
+      loginCount: { type: 'number', defaultTo: 0 },
+      externalRef: { type: 'string', storage: { column: 'legacy_ref' } }
     })
 
     const migration = generateKnexMigration('mapped_profiles', schema)
 
     assert.ok(migration.includes("table.string('display_name').notNullable()"))
     assert.ok(migration.includes("table.float('login_count').defaultTo(0)"))
+    assert.ok(migration.includes("table.string('legacy_ref')"))
     assert.ok(!migration.includes("table.string('displayName')"))
   })
 
@@ -384,11 +389,11 @@ describe('dbTablesOperations.generateKnexMigration', () => {
 
   it('includes named composite indexes, foreign keys, checks, enum, and set columns in generated migrations', () => {
     const schema = makeTableSchema({
-      workspaceId: { type: 'id', required: true, storage: { column: 'workspace_id' } },
-      userId: { type: 'id', required: true, storage: { column: 'user_id' } },
+      workspaceId: { type: 'id', required: true },
+      userId: { type: 'id', required: true },
       role: { type: 'string', enum: ['owner', 'member'], required: true, defaultTo: 'member' },
       flags: { type: 'string', setValues: ['featured', 'archived'] },
-      noteCount: { type: 'number', defaultTo: 0, storage: { column: 'note_count' } }
+      noteCount: { type: 'number', defaultTo: 0 }
     }, {
       indexes: [
         {
@@ -502,10 +507,10 @@ describe('dbTablesOperations.generateKnexMigrationDiff', () => {
       idColumn: 'id'
     })
     const desiredSchema = makeTableSchema({
-      workspaceId: { type: 'id', required: true, storage: { column: 'workspace_id' } },
-      userId: { type: 'id', required: true, storage: { column: 'user_id' } },
+      workspaceId: { type: 'id', required: true },
+      userId: { type: 'id', required: true },
       role: { type: 'string', enum: ['owner', 'member'], required: true, defaultTo: 'member' },
-      noteCount: { type: 'number', defaultTo: 0, storage: { column: 'note_count' } }
+      noteCount: { type: 'number', defaultTo: 0 }
     }, {
       indexes: [
         {
@@ -737,8 +742,8 @@ describe('RestApiKnexPlugin migration scope methods', () => {
     await api.addResource('memberships', {
       schema: {
         id: { type: 'id' },
-        workspaceId: { type: 'id', required: true, storage: { column: 'workspace_id' } },
-        userId: { type: 'id', required: true, storage: { column: 'user_id' } },
+        workspaceId: { type: 'id', required: true },
+        userId: { type: 'id', required: true },
         role: { type: 'string', enum: ['owner', 'member'], required: true, defaultTo: 'member' }
       },
       indexes: [

package/tests/fastify-plugin.test.js

@@ -8,6 +8,20 @@ import {
   findFastifyRoute
 } from './helpers/fake-fastify.js'
 
+function resolveSchemaNode (rootSchema, schemaNode) {
+  if (!schemaNode || !Array.isArray(schemaNode.allOf) || schemaNode.allOf.length !== 1) {
+    return schemaNode
+  }
+
+  const ref = schemaNode.allOf[0]?.$ref || ''
+  if (!ref.startsWith('#/definitions/')) {
+    return schemaNode
+  }
+
+  const definitionName = ref.slice('#/definitions/'.length)
+  return rootSchema?.definitions?.[definitionName] || schemaNode
+}
+
 async function createFastifyConnectorApi () {
   const app = new FakeFastifyApp()
   const api = new Api({
@@ -70,7 +84,7 @@ describe('Fastify Plugin', () => {
     assert.ok(patchRelationshipRoute?.schema?.body, 'PATCH relationship route should have a body schema')
     assert.ok(deleteRelationshipRoute?.schema?.body, 'DELETE relationship route should have a body schema')
 
-    const postDataSchema = postRoute.schema.body.properties.data
+    const postDataSchema = resolveSchemaNode(postRoute.schema.body, postRoute.schema.body.properties.data)
     const postAttributes = postDataSchema.properties.attributes
 
     assert.deepEqual(postDataSchema.required, ['type'])
@@ -78,14 +92,15 @@ describe('Fastify Plugin', () => {
     assert.equal(postAttributes.properties.author_id, undefined, 'belongsTo foreign key should not be accepted in attributes')
     assert.equal(postAttributes.properties.internal_summary, undefined, 'computed fields should not be accepted in attributes')
     assert.equal(postAttributes.properties.id, undefined, 'resource ids should not appear in attributes')
-    assert.ok(postDataSchema.properties.relationships.properties.author, 'declared belongsTo relationships should be represented in the transport schema')
+    const postRelationships = resolveSchemaNode(postRoute.schema.body, postDataSchema.properties.relationships)
+    assert.ok(postRelationships.properties.author, 'declared belongsTo relationships should be represented in the transport schema')
 
-    const putDataSchema = putRoute.schema.body.properties.data
+    const putDataSchema = resolveSchemaNode(putRoute.schema.body, putRoute.schema.body.properties.data)
     assert.ok(putDataSchema.required.includes('id'), 'PUT body schema should require data.id')
 
-    const patchDataSchema = patchRoute.schema.body.properties.data
-    assert.ok(Array.isArray(patchDataSchema.anyOf), 'PATCH body schema should require at least one writable section')
-    assert.deepEqual(patchDataSchema.anyOf, [
+    const patchDataSchemaNode = patchRoute.schema.body.properties.data
+    assert.ok(Array.isArray(patchDataSchemaNode.anyOf), 'PATCH body schema should require at least one writable section')
+    assert.deepEqual(patchDataSchemaNode.anyOf, [
       { required: ['attributes'] },
       { required: ['relationships'] }
     ])