json-rest-api 1.0.22 → 1.0.24

package/plugins/core/rest-api-query-projections-plugin.js

@@ -0,0 +1,130 @@
+export const QueryProjectionsPlugin = {
+  name: 'query-projections',
+  dependencies: ['rest-api'],
+
+  install ({ addHook, log }) {
+    const normalizeQueryFields = ({ scopeName, scopeOptions = {} }) => {
+      const schema = scopeOptions.schema || {}
+      const relationships = scopeOptions.relationships || {}
+      const rawQueryFields = scopeOptions.queryFields || {}
+      const normalized = {}
+      const reservedNames = new Set(Object.keys(schema))
+
+      if (!rawQueryFields || typeof rawQueryFields !== 'object' || Array.isArray(rawQueryFields)) {
+        throw new Error(`Invalid queryFields configuration for scope '${scopeName}'. Expected an object.`)
+      }
+
+      for (const relName of Object.keys(relationships)) {
+        reservedNames.add(relName)
+      }
+
+      for (const fieldDef of Object.values(schema)) {
+        if (fieldDef?.belongsTo && fieldDef?.as) {
+          reservedNames.add(fieldDef.as)
+        }
+      }
+
+      for (const [fieldName, fieldDef] of Object.entries(rawQueryFields)) {
+        if (!fieldDef || typeof fieldDef !== 'object' || Array.isArray(fieldDef)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must be an object.`)
+        }
+
+        if (reservedNames.has(fieldName)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' conflicts with an existing schema or relationship name.`)
+        }
+
+        if (!fieldDef.type) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must have a type.`)
+        }
+
+        const select = fieldDef.select || fieldDef.project
+        if (typeof select !== 'function') {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must define a select() function.`)
+        }
+
+        normalized[fieldName] = {
+          ...fieldDef,
+          select,
+          sortable: fieldDef.sortable === true,
+          hidden: fieldDef.hidden === true,
+          normallyHidden: fieldDef.normallyHidden === true
+        }
+      }
+
+      return normalized
+    }
+
+    const stripQueryFieldInput = ({ context, scopeName, scope, scopes }) => {
+      const inputAttributes = context?.inputRecord?.data?.attributes
+      const queryFields = scopes?.[scopeName]?.vars?.queryFields || scope?.vars?.queryFields || {}
+
+      if (!inputAttributes || typeof inputAttributes !== 'object' || Array.isArray(inputAttributes)) {
+        return
+      }
+
+      const stripped = []
+      for (const fieldName of Object.keys(queryFields)) {
+        if (Object.hasOwn(inputAttributes, fieldName)) {
+          delete inputAttributes[fieldName]
+          stripped.push(fieldName)
+        }
+      }
+
+      if (stripped.length > 0) {
+        const message = `Query fields [${stripped.join(', ')}] were sent in input for resource '${scopeName}' but will be ignored as they are query output only`
+        if (typeof log?.warn === 'function') {
+          log.warn(message)
+        } else {
+          console.warn(message)
+        }
+      }
+    }
+
+    const validateCompiledQueryFieldNamespace = ({ scopeName, scope, vars, scopes }) => {
+      const activeScope = scope || scopes?.[scopeName]
+      const scopeVars = vars || activeScope?.vars || {}
+      const queryFields = scopeVars.queryFields || {}
+      const schemaInfo = activeScope?.vars?.schemaInfo || scopeVars.schemaInfo || {}
+
+      if (Object.keys(queryFields).length === 0) {
+        return
+      }
+
+      const reservedNames = new Set([
+        ...Object.keys(schemaInfo.schemaStructure || {}),
+        ...Object.keys(schemaInfo.computed || {}),
+        ...Object.keys(schemaInfo.schemaRelationships || {})
+      ])
+
+      for (const fieldDef of Object.values(schemaInfo.schemaStructure || {})) {
+        if (fieldDef?.belongsTo && fieldDef?.as) {
+          reservedNames.add(fieldDef.as)
+        }
+      }
+
+      for (const fieldName of Object.keys(queryFields)) {
+        if (reservedNames.has(fieldName)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' conflicts with an existing schema, computed, or relationship name.`)
+        }
+      }
+    }
+
+    addHook('scope:added', 'compile-query-projections', { afterFunction: 'turnScopeInitIntoVars' }, ({ context, scopes }) => {
+      const scopeName = context.scopeName
+      const scope = scopes[scopeName]
+      const vars = scope?.vars || {}
+      const scopeOptions = scope?.scopeOptions || context.scopeOptions || {}
+      const queryFields = normalizeQueryFields({ scopeName, scopeOptions })
+
+      vars.queryFields = queryFields
+      validateCompiledQueryFieldNamespace({ scopeName, scope, vars, scopes })
+
+      log.debug(`Compiled query fields for '${scopeName}'`, {
+        queryFields: Object.keys(queryFields),
+        sortable: Object.keys(queryFields).filter((fieldName) => queryFields[fieldName].sortable === true)
+      })
+    })
+
+    addHook('beforeSchemaValidate', 'strip-query-field-input', {}, stripQueryFieldInput)
+  }
+}

package/plugins/core/socketio-plugin.js

@@ -206,9 +206,7 @@ async function registerSubscription ({
       }
     }
 
-    const { validatedObject, errors } = await searchSchemaInstance.validate(validatedFilters, {
-      onlyObjectValues: true
-    })
+    const { validatedObject, errors } = await searchSchemaInstance.patch(validatedFilters)
 
     if (errors && Object.keys(errors).length > 0) {
       const error = new Error('Invalid filter values')
@@ -395,7 +393,6 @@ export const SocketIOPlugin = {
     let io
 
     api.startSocketServer = async (server, startOptions = {}) => {
-      const transportConfig = { ...config.transport, ...startOptions.transport }
       const authConfig = { ...config.auth, ...(startOptions.auth || {}) }
       const redisConfig = startOptions.redis ?? pluginOptions.redis ?? null
 

package/plugins/storage/local-storage.js

@@ -92,7 +92,7 @@ export class LocalStorage {
     return filename
       // Remove path traversal attempts
       .replace(/\.\./g, '')
-      .replace(/[\/\\]/g, '')
+      .replace(/[/\\]/g, '')
       // Remove control characters and special chars
       .replace(/[^\w\s.-]/g, '_')
       // Remove leading/trailing dots and spaces

package/plugins/storage/s3-storage.js

@@ -100,13 +100,16 @@ export class S3Storage {
    * @returns {Promise<void>}
    */
   async delete (url) {
-    // Extract key from URL
     const urlObj = new URL(url)
-    const key = urlObj.pathname.substring(1) // Remove leading /
 
     if (this.mockMode) {
       // Mock mode - just simulate deletion
       await new Promise(resolve => setTimeout(resolve, 50))
+      return
+    }
+
+    if (urlObj.pathname.length === 0) {
+      throw new Error('Invalid S3 object URL')
     }
 
     // Real S3 delete would go here

package/quickTest.js

@@ -70,6 +70,7 @@ const harperResult = await api.resources.publishers.post({
     name: 'HarperCollins'
   }
 })
+console.log('Created second publisher:', inspect(harperResult))
 
 // Method 3: Full JSON:API mode (standards compliant)
 const oxfordResult = await api.resources.publishers.post({

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',