json-rest-api 1.0.22 → 1.0.24

package/docs/GUIDE/index.md

@@ -15,16 +15,13 @@ Welcome to the comprehensive guide for JSON REST API. This guide will walk you t
 3. **[Field Transformations](GUIDE_3_Field_Transformations.md)**  
    Transform data with virtual fields, getters, setters, computed fields, and visibility control.
 
-4. **[Authentication and Permissions](GUIDE_4_Authentication_And_Permissions.md)**  
-   Implement security with authentication strategies and fine-grained permissions.
-
-5. **[Non-Database Resources](GUIDE_5_Non-Db_Resources.md)**  
+4. **[Non-Database Resources](GUIDE_5_Non-Db_Resources.md)**  
    Connect your API to alternative data sources beyond traditional databases.
 
-6. **[Positioning](GUIDE_6_Positioning.md)**  
+5. **[Positioning](GUIDE_6_Positioning.md)**  
    Implement drag-and-drop functionality with automatic position management.
 
-7. **[Hooks, Data Management, and Plugins](GUIDE_7_Hooks_Data_Management_And_Plugins.md)**  
+6. **[Hooks, Data Management, and Plugins](GUIDE_7_Hooks_Data_Management_And_Plugins.md)**  
    Master the hook system for data validation, transformation, and business logic.
 
 
@@ -39,8 +36,20 @@ Welcome to the comprehensive guide for JSON REST API. This guide will walk you t
 - **[CORS Configuration](GUIDE_X_Cors.md)**  
   Set up Cross-Origin Resource Sharing for browser-based applications.
 
-- **[Multihome Support](GUIDE_X_Multihome.md)**  
-  Run multiple API instances or serve different domains from a single server.
+- **[Autofiltering](GUIDE_X_Autofiltering.md)**  
+  Scope datasets automatically using configured context values, without baking in auth semantics.
+
+- **[Knex Schema and Migrations](GUIDE_X_Knex_Schema_And_Migrations.md)**  
+  Create tables, inspect live table snapshots, and generate create or additive diff migrations from table-backed resource scopes.
+
+- **[Query Projections](GUIDE_X_Query_Projections.md)**  
+  Use the optional query-projections plugin to add SQL-backed, output-only derived fields that can participate in sorting and cursor pagination.
+
+- **[Writing Plugins](GUIDE_X_Writing_Plugins.md)**  
+  Build plugins against the supported extension surface, including hooks, scope methods, and query-only read fields.
+
+- **[Fastify Integration](GUIDE_X_Fastify.md)**  
+  Register REST routes on Fastify and reject malformed write payloads at the transport layer using exported resource schemas.
 
 - **[Socket.IO Integration](GUIDE_X_SocketIO.md)**  
   Add real-time capabilities to your API with WebSocket support.
@@ -61,4 +70,4 @@ Before starting this guide, you should have:
 
 ---
 
-Ready to get started? Head to [Chapter 1: Initial Setup](GUIDE_1_Initial_Setup.md) →
+Ready to get started? Head to [Chapter 1: Initial Setup](GUIDE_1_Initial_Setup.md) →

package/docs/QUICKSTART.md

@@ -103,6 +103,10 @@ await api.addResource('authors', {
 await api.resources.authors.createKnexTable();
 ```
 
+`searchSchema` defines the public filter names your API accepts. Those keys do not need to match database columns or even resource field names. Keep the quickstart mental model simple: `searchSchema` is the resource's public filter contract. For advanced mapping, multi-field search, and custom backend filtering, see [Manipulating and Searching Tables](GUIDE/GUIDE_2_2_Manipulating_And_Searching_Tables.md).
+
+If you want to inspect the physical table shape or generate Knex migrations directly from your resource definitions, see [Knex Schema and Migrations](GUIDE/GUIDE_X_Knex_Schema_And_Migrations.md).
+
 ## Run the program
 
 ```bash
@@ -332,7 +336,7 @@ You've successfully set up a basic JSON REST API! This quickstart covered the es
 
 Check out the [full guide](./GUIDE) to learn about:
 - Advanced relationships (many-to-many, polymorphic)
-- Authentication and authorization
+- Permission hooks, request auth context, and autofiltering
 - Hooks and middleware
 - Custom validation
 - Pagination strategies

package/docs/index.md

@@ -27,7 +27,7 @@ JSON REST API is a lightweight, plugin-based framework that makes building REST
   
   <div class="feature-card">
     <h3>🔌 Plugin Architecture</h3>
-    <p>Extend your API with powerful plugins. Authentication, validation, CORS, and more - just plug and play.</p>
+    <p>Extend your API with focused plugins for transports, dataset scoping, query fields, CORS, and more.</p>
   </div>
   
   <div class="feature-card">

package/index.js

@@ -10,9 +10,10 @@
 
 // Core plugins
 export { RestApiPlugin } from './plugins/core/rest-api-plugin.js'
+export { AutoFilterPlugin } from './plugins/core/rest-api-autofilter-plugin.js'
+export { QueryProjectionsPlugin } from './plugins/core/rest-api-query-projections-plugin.js'
 export { FileHandlingPlugin } from './plugins/core/file-handling-plugin.js'
 export { CorsPlugin } from './plugins/core/rest-api-cors-plugin.js'
-export { AccessPlugin } from './plugins/core/rest-api-access.js'
 export { LabelPlugin } from './plugins/core/rest-api-label-plugin.js'
 
 // Database plugins
@@ -21,7 +22,7 @@ export { RestApiAnyapiKnexPlugin } from './plugins/core/rest-api-anyapi-knex-plu
 
 // Connector plugins
 export { ExpressPlugin } from './plugins/core/connectors/express-plugin.js'
-// Future: export { FastifyPlugin } from './plugins/core/connectors/fastify-plugin.js';
+export { FastifyPlugin } from './plugins/core/connectors/fastify-plugin.js'
 // Future: export { KoaPlugin } from './plugins/core/connectors/koa-plugin.js';
 
 // Storage plugins for file handling

package/lib/enhanced-logger.js

@@ -3,7 +3,7 @@
  * Wraps any logger to provide comprehensive error logging
  */
 
-import { formatError, formatErrorSummary, formatErrorString } from './error-formatter.js'
+import { formatError, formatErrorSummary } from './error-formatter.js'
 
 /**
  * Creates an enhanced logger that automatically formats errors

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "json-rest-api",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "test": "node --test tests/*.test.js",
     "test:anyapi": "JSON_REST_API_STORAGE=anyapi node --test tests/*.test.js",
+    "test:id-contracts": "node --test tests/id-normalization.test.js tests/logical-id-write-validation.test.js tests/custom-id-simplified-post.test.js",
+    "test:id-contracts:anyapi": "JSON_REST_API_STORAGE=anyapi node --test tests/id-normalization.test.js",
     "docs": "node scripts/run-docs.js",
+    "docs:dev": "node scripts/run-docs.js --serve",
+    "verify": "npm run test:id-contracts && npm run test:id-contracts:anyapi && npm run docs",
     "sloc": "sloc --exclude \"(_site|node_modules|\\.git|vendor|docs)\" .",
     "slod": "cd docs;echo 'DOC LINES:'; cat `find . -iname \\*md | grep -v _site | grep -v vendor` | wc",
     "lint": "eslint .",
@@ -25,7 +29,7 @@
   "description": "REST API plugin for hooked-api with JSON:API compliance",
   "dependencies": {
     "hooked-api": "^1.0.24",
-    "json-rest-schema": "^1.0.12",
+    "json-rest-schema": "^1.0.14",
     "semver": "^7.7.2"
   },
   "peerDependencies": {

package/plugins/core/bulk-operations-plugin.js

@@ -1,4 +1,4 @@
-import { RestApiValidationError, RestApiResourceError } from '../../lib/rest-api-errors.js'
+import { RestApiValidationError } from '../../lib/rest-api-errors.js'
 
 export const BulkOperationsPlugin = {
   name: 'bulk-operations',
@@ -353,41 +353,33 @@ export const BulkOperationsPlugin = {
       // Create route handlers
       const createBulkRouteHandler = (method) => {
         return async ({ context, body, query }) => {
-          try {
-            // Parse query params for atomic mode override
-            const atomic = query?.atomic !== undefined
-              ? query.atomic === 'true'
-              : defaultAtomic
-
-            let params
-            if (method === 'bulkPost') {
-              // For bulk create, expect array in data field (JSON:API style)
-              params = {
-                inputRecords: body?.data || body,
-                atomic
-              }
-            } else if (method === 'bulkPatch') {
-              // For bulk update, expect operations array
-              params = {
-                operations: body?.operations || body,
-                atomic
-              }
-            } else if (method === 'bulkDelete') {
-              // For bulk delete, expect IDs array
-              params = {
-                ids: body?.data || body?.ids || body,
-                atomic
-              }
+          // Parse query params for atomic mode override
+          const atomic = query?.atomic !== undefined
+            ? query.atomic === 'true'
+            : defaultAtomic
+
+          let params
+          if (method === 'bulkPost') {
+            // For bulk create, expect array in data field (JSON:API style)
+            params = {
+              inputRecords: body?.data || body,
+              atomic
+            }
+          } else if (method === 'bulkPatch') {
+            // For bulk update, expect operations array
+            params = {
+              operations: body?.operations || body,
+              atomic
+            }
+          } else if (method === 'bulkDelete') {
+            // For bulk delete, expect IDs array
+            params = {
+              ids: body?.data || body?.ids || body,
+              atomic
             }
-
-            // Call the scope method
-            const result = await api.scopes[scopeName][method](params)
-
-            return result
-          } catch (error) {
-            // Let transport plugin handle error mapping
-            throw error
           }
+
+          return await api.scopes[scopeName][method](params)
         }
       }
 

package/plugins/core/connectors/express-plugin.js

@@ -15,9 +15,22 @@
  */
 
 import { requirePackage } from 'hooked-api'
-import { parseJsonApiQuery } from '../lib/querying-writing/connectors-query-parser.js'
 import { createContext } from './lib/request-helpers.js'
 import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
+import {
+  isWriteMethod,
+  isAllowedWriteContentType,
+  getUnsupportedMediaTypeErrorBody
+} from './lib/transport-http-helpers.js'
+import {
+  extractQueryString,
+  buildTransportRequestData,
+  createConnectorContext,
+  runTransportRequestLifecycle,
+  buildTransportRejectionBody,
+  executeConnectorRoute,
+  handleConnectorError
+} from './lib/connector-core.js'
 
 export const ExpressPlugin = {
   name: 'express',
@@ -115,58 +128,39 @@ export const ExpressPlugin = {
 
     // Add transport hook middleware
     router.use(async (req, res, next) => {
-      const context = createContext(req, res, 'express')
-
-      // Check for Express middleware override first
-      if (req.urlPrefixOverride) {
-        context.urlPrefixOverride = req.urlPrefixOverride
-      }
-
-      // Calculate and cache URL prefix (getUrlPrefix handles all logic)
-      const { getUrlPrefix } = await import('../lib/querying/url-helpers.js')
-      context.urlPrefix = getUrlPrefix(context, { vars: { transport: { mountPath: basePath } } }, req)
-
-      // Transport-specific data for hooks
-      const transportData = {
-        request: {
-          method: req.method,
-          url: req.url,
-          path: req.path,
-          headers: req.headers,
-          body: req.body,
-          params: req.params,
-          query: req.query
-        },
-        response: {
-          headers: {},
-          status: null
-        }
-      }
-
-      // Add transport data to context
-      context.transport = transportData
-
-      // Run transport hooks - don't check return value for consistency with other hooks
-      // Hooks communicate via context flags (rejection, handled) not return values
-      await runHooks('transport:request', context)
+      const requestData = buildTransportRequestData({
+        method: req.method,
+        url: req.url,
+        path: req.path,
+        headers: req.headers,
+        body: req.body,
+        params: req.params,
+        query: req.query
+      })
+      const { context, transportData } = createConnectorContext({
+        request: req,
+        reply: res,
+        source: 'express',
+        mountPath: basePath,
+        requestData,
+        createContext,
+        urlPrefixOverride: req.urlPrefixOverride
+      })
+      const { rejected, handled } = await runTransportRequestLifecycle({
+        context,
+        runHooks
+      })
 
-      // Check if request was rejected (e.g., authentication failure)
-      if (context.rejection) {
-        // Apply response headers from hooks
+      if (rejected) {
         if (transportData.response.headers) {
           res.set(transportData.response.headers)
         }
-        return res.status(context.rejection.status || 500).json({
-          errors: [{
-            status: String(context.rejection.status || 500),
-            title: context.rejection.title || 'Request Rejected',
-            detail: context.rejection.message
-          }]
-        })
+        return res.status(context.rejection.status || 500).json(
+          buildTransportRejectionBody(context)
+        )
       }
 
-      // Check if request was already handled by a hook
-      if (context.handled) {
+      if (handled) {
         return
       }
 
@@ -179,18 +173,13 @@ export const ExpressPlugin = {
     // Content type validation middleware
     if (strictContentType) {
       router.use((req, res, next) => {
-        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+        if (isWriteMethod(req.method)) {
           const contentType = req.get('Content-Type')
 
-          if (contentType && !contentType.includes('application/vnd.api+json') &&
-              !contentType.includes('application/json') && !contentType.includes('multipart/form-data')) {
-            return res.status(415).json({
-              errors: [{
-                status: '415',
-                title: 'Unsupported Media Type',
-                detail: 'Content-Type must be application/vnd.api+json or application/json'
-              }]
-            })
+          if (!isAllowedWriteContentType(contentType, { allowMultipart: true })) {
+            return res.status(415).json(
+              getUnsupportedMediaTypeErrorBody({ allowMultipart: true })
+            )
           }
         }
         next()
@@ -207,77 +196,16 @@ export const ExpressPlugin = {
         url: req.url
       })
 
-      let status = 500
-      const errorResponse = {
-        errors: [{
-          status: '500',
-          title: 'Internal Server Error',
-          detail: error.message
-        }]
-      }
-
-      // Map error codes to HTTP status
-      if (error.code === 'REST_API_VALIDATION') {
-        status = 422
-        errorResponse.errors = [{
-          status: '422',
-          title: 'Validation Error',
-          detail: error.message,
-          source: error.details
-        }]
-        if (error.details?.violations) {
-          errorResponse.errors = error.details.violations.map(v => ({
-            status: '422',
-            title: 'Validation Error',
-            detail: v.message,
-            source: { pointer: v.field }
-          }))
-        }
-      } else if (error.code === 'REST_API_RESOURCE') {
-        switch (error.subtype) {
-          case 'not_found':
-            status = 404
-            errorResponse.errors[0].status = '404'
-            errorResponse.errors[0].title = 'Not Found'
-            break
-          case 'conflict':
-            status = 409
-            errorResponse.errors[0].status = '409'
-            errorResponse.errors[0].title = 'Conflict'
-            break
-          case 'forbidden':
-            status = 403
-            errorResponse.errors[0].status = '403'
-            errorResponse.errors[0].title = 'Forbidden'
-            break
-          default:
-            status = 400
-            errorResponse.errors[0].status = '400'
-            errorResponse.errors[0].title = 'Bad Request'
-        }
-      } else if (error.code === 'REST_API_PAYLOAD') {
-        status = 400
-        errorResponse.errors = [{
-          status: '400',
-          title: 'Bad Request',
-          detail: error.message,
-          source: { pointer: error.path }
-        }]
-      }
-
-      // Run transport:response hook for errors
-      if (req.transportData && req.context) {
-        req.transportData.response.status = status
-        req.transportData.response.body = errorResponse
-        req.context.transport = req.transportData
-        await runHooks('transport:response', req.context)
+      const { status, body: errorResponse, headers } = await handleConnectorError({
+        error,
+        context: req.context,
+        transportData: req.transportData,
+        runHooks
+      })
 
-        // Apply response headers from hooks
-        if (req.transportData.response.headers) {
-          res.set(req.transportData.response.headers)
-        }
+      if (headers) {
+        res.set(headers)
       }
-
       res.status(status).json(errorResponse)
     }
 
@@ -285,7 +213,7 @@ export const ExpressPlugin = {
      * Listen to addRoute hook to create Express routes
      */
     addHook('addRoute', 'expressRouteCreator', {}, async ({ context }) => {
-      const { method, path, handler } = context
+      const { method, path, handler, routeMeta } = context
 
       // Apply any global before middleware
       const beforeMiddleware = expressOptions.middleware?.beforeAll || []
@@ -294,78 +222,62 @@ export const ExpressPlugin = {
         // Extract the handler logic into a shared function to keep it DRY (Don't Repeat Yourself).
         const expressHandler = async (req, res) => {
           try {
-            // Extract request data
-            const queryString = req.url.split('?')[1] || ''
-            const context = req.context || createContext(req, res, 'express')
+            let context = req.context
+            let transportData = req.transportData
+
+            if (!context || !transportData) {
+              const requestData = buildTransportRequestData({
+                method: req.method,
+                url: req.url,
+                path: req.path,
+                headers: req.headers,
+                body: req.body,
+                params: req.params,
+                query: req.query
+              })
+              const setup = createConnectorContext({
+                request: req,
+                reply: res,
+                source: 'express',
+                mountPath: basePath,
+                requestData,
+                createContext,
+                urlPrefixOverride: req.urlPrefixOverride
+              })
+              context = setup.context
+              transportData = setup.transportData
+              req.context = context
+              req.transportData = transportData
+            }
 
-            // Call the generic handler
-            const result = await handler({
-              queryString,
+            const outcome = await executeConnectorRoute({
+              method: req.method,
+              handler,
+              queryString: extractQueryString(req.url),
               headers: req.headers,
               params: req.params,
               body: req.body,
-              context
+              context,
+              transportData,
+              routeMeta,
+              helpers,
+              mountPath: basePath,
+              runHooks
             })
-
-            // Prepare response status
-            let responseStatus = 200
-            if (result && typeof result.statusCode === 'number') {
-              responseStatus = result.statusCode
-            } else if (req.method === 'POST' && result) {
-              // POST with content returns 201 Created
-              responseStatus = 201
-            } else if (req.method === 'POST' && !result) {
-              // POST without content returns 204 No Content
-              responseStatus = 204
-            } else if (req.method === 'DELETE') {
-              // DELETE always returns 204 No Content
-              responseStatus = 204
-            } else if ((req.method === 'PUT' || req.method === 'PATCH') && !result) {
-              // PUT/PATCH return 204 when no content is returned
-              responseStatus = 204
-            }
-
-            // Apply headers from the handler result
-            if (result && result.headers) {
-              res.set(result.headers)
-            }
-
-            // Update transport data for response (if transport data exists)
-            if (req.transportData) {
-              req.transportData.response.status = responseStatus
-              req.transportData.response.body = result
-              context.transport = req.transportData
-              await runHooks('transport:response', context)
-              if (req.transportData.response.headers) {
-                res.set(req.transportData.response.headers)
-              }
-            }
+            res.set(outcome.headers)
 
             // Set content type
             res.set('Content-Type', 'application/vnd.api+json')
 
-            // Set Location header for successful POST requests
-            if (req.method === 'POST' && context.id) {
-              // Extract scopeName from the path (e.g., /api/countries -> countries)
-              const pathParts = path.split('/')
-              const scopeName = pathParts[pathParts.length - 1]
-
-              // Set Location header for any successful POST (201 or 204)
-              if (helpers.getLocation) {
-                const location = helpers.getLocation({ scopeName, id: context.id })
-                const baseUrl = context.urlPrefix || basePath
-                res.set('Location', `${baseUrl}${location}`)
-              }
+            if (outcome.location) {
+              res.set('Location', outcome.location)
             }
 
             // Handle response based on status
-            if (responseStatus === 204) {
+            if (outcome.status === 204) {
               res.sendStatus(204)
             } else {
-              // If result has a body property, that's what we should send
-              // This happens when handler returns { statusCode, body, headers }
-              const responseBody = result && result.body !== undefined ? result.body : result
-              res.status(responseStatus).json(responseBody)
+              res.status(outcome.status).json(outcome.body)
             }
           } catch (error) {
             handleError(error, req, res)
@@ -424,11 +336,6 @@ export const ExpressPlugin = {
           router[method.toLowerCase()](path, ...beforeMiddleware, expressHandler)
 
           // Debug logging for route registration
-
-          // Check if the route was actually added
-          if (router.stack) {
-            const lastRoute = router.stack[router.stack.length - 1]
-          }
         }
       } catch (routeError) {
         log.error('[EXPRESS DEBUG] Error creating route:', {