json-rest-api 1.0.22 → 1.0.24

package/docs/API.md

@@ -4,13 +4,17 @@ This reference provides comprehensive documentation for all methods, parameters,
 
 ## Important Notes
 
-1. **Context Parameter**: The `context` parameter shown in method signatures is typically managed internally by the framework. When using the API programmatically, you usually don't need to provide it unless you're implementing custom authentication or request-specific data.
+1. **Context Parameter**: The `context` parameter shown in method signatures is typically managed internally by the framework. When using the API programmatically, you usually don't need to provide it unless you're implementing custom request identity/auth context or other request-specific data.
 
-2. **Simplified Mode Defaults**: 
+2. **App-Owned Auth Context**: `json-rest-api` does not define authentication semantics. If you use `context.auth` in hooks, treat it as application-owned data supplied by your transport or surrounding stack.
+
+3. **Simplified Mode Defaults**: 
    - `simplifiedApi`: `true` (default for programmatic API calls)
    - `simplifiedTransport`: `false` (default for HTTP transport)
 
-3. **All parameters must be passed within a single params object** as the first argument to each method.
+4. **All parameters must be passed within a single params object** as the first argument to each method.
+
+5. **Simplified shorthand is payload-only**: when you pass attributes directly (for example, `post({ title: 'Hello' })`), that plain object is treated as the resource payload. If you also need per-call options such as `transaction`, `queryParams`, `simplified`, or `returnFullRecord`, put the record under `inputRecord` and keep those options at the top level of `params`.
 
 ## Table of Contents
 
@@ -289,6 +293,8 @@ const result = await api.resources.[resourceType].get(params, context)
 | `simplified` | Boolean | No | Override simplified mode setting (default: true) |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 **JSON:API Mode (simplified: false):**
@@ -428,7 +434,9 @@ const result = await api.resources.[resourceType].post(params, context)
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Resource data to create |
+| `inputRecord.id` | String | No (simplified) | Optional explicit logical resource ID |
 | `inputRecord.data` | Object | Yes (JSON:API) | Resource data container |
+| `inputRecord.data.id` | String | No (JSON:API) | Optional explicit logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | Yes (JSON:API) | Resource attributes |
 | `inputRecord.data.relationships` | Object | No | Related resources |
@@ -437,6 +445,8 @@ const result = await api.resources.[resourceType].post(params, context)
 | `transaction` | Object | No | Database transaction object |
 | `returnFullRecord` | String | No | Override return setting ('no', 'minimal', 'full') |
 
+When an explicit resource id is provided, `normalizeId` runs before persistence and before any follow-up record fetch used for the return payload. If the normalized id is empty, the request fails as `REST_API_VALIDATION` on `data.id`.
+
 #### Return Value Behavior
 
 The return value depends on `returnFullRecord` setting and whether it's an API or transport call:
@@ -513,6 +523,25 @@ const result = await api.resources.articles.post({
 });
 ```
 
+**Create with Explicit ID and Normalization:**
+```javascript
+// With normalizeId configured to trim and uppercase ids,
+// this record is stored as ARTICLE-42
+const result = await api.resources.articles.post({
+  inputRecord: {
+    data: {
+      type: 'articles',
+      id: '  article-42  ',
+      attributes: {
+        title: 'Canonical ID Example',
+        content: 'Stored under the normalized id'
+      }
+    }
+  },
+  simplified: false
+});
+```
+
 **Create with Multiple Relationships:**
 ```javascript
 // Create article with author and tags (simplified)
@@ -589,8 +618,8 @@ const result = await api.resources.[resourceType].put(params, context)
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Complete resource data |
-| `inputRecord.id` | String | Yes (simplified) | Resource ID |
-| `inputRecord.data.id` | String | Yes (JSON:API) | Must match the resource ID |
+| `inputRecord.id` | String | Yes (simplified) | Logical resource ID |
+| `inputRecord.data.id` | String | Yes (JSON:API) | Logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | Yes (JSON:API) | All resource attributes |
 | `inputRecord.data.relationships` | Object | No | All relationships (missing ones are nulled) |
@@ -599,6 +628,10 @@ const result = await api.resources.[resourceType].put(params, context)
 | `transaction` | Object | No | Database transaction object |
 | `returnFullRecord` | String | No | Override return setting |
 
+`inputRecord.id` and `inputRecord.data.id` always refer to the logical resource id. `idProperty` and storage mapping affect the backing column name, not the API field name, and the resource id is not part of `attributes`.
+
+If both the URL id and body id are present, both are normalized before the equality check. If either id normalizes to an empty value, the operation fails before storage is touched.
+
 #### Return Value
 
 Updated resource based on `returnFullRecord` setting (defaults: API='full', transport='no').
@@ -716,8 +749,8 @@ const result = await api.resources.[resourceType].patch(params, context)
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `inputRecord` | Object | Yes | Partial resource data |
-| `inputRecord.id` | String | Yes (simplified) | Resource ID |
-| `inputRecord.data.id` | String | Yes (JSON:API) | Resource ID |
+| `inputRecord.id` | String | Yes (simplified) | Logical resource ID |
+| `inputRecord.data.id` | String | Yes (JSON:API) | Logical resource ID |
 | `inputRecord.data.type` | String | Yes (JSON:API) | Resource type |
 | `inputRecord.data.attributes` | Object | No | Attributes to update |
 | `inputRecord.data.relationships` | Object | No | Relationships to update |
@@ -726,6 +759,8 @@ const result = await api.resources.[resourceType].patch(params, context)
 | `transaction` | Object | No | Database transaction object |
 | `returnFullRecord` | String | No | Override return setting |
 
+If both the URL id and body id are present, both are normalized before the equality check. If either id normalizes to an empty value, the operation fails before storage is touched.
+
 #### Return Value
 
 Updated resource based on `returnFullRecord` setting (defaults: API='full', transport='no').
@@ -847,6 +882,8 @@ const result = await api.resources.[resourceType].delete(params, context)
 | `id` | String\|Number | Yes | ID of resource to delete |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -933,6 +970,8 @@ const result = await api.resources.[resourceType].getRelated(params, context)
 | `queryParams` | Object | No | Standard query parameters for related resources |
 | `transaction` | Object | No | Database transaction object |
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 JSON:API response with related resources (supports all query features like filtering, pagination, etc.)
@@ -1005,6 +1044,8 @@ const result = await api.resources.[resourceType].getRelationship(params, contex
 }
 ```
 
+`id` is normalized with the effective `normalizeId` function before validation and lookup. If it normalizes to an empty value, the operation fails as `REST_API_RESOURCE` with subtype `not_found`.
+
 #### Return Value
 
 JSON:API relationship document with resource identifiers only
@@ -1079,6 +1120,8 @@ const result = await api.resources.[resourceType].postRelationship(params, conte
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each `relationshipData[*].id` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1114,6 +1157,8 @@ await api.resources.articles.postRelationship({
 // Existing tags remain, new tags are added
 ```
 
+If `normalizeId` is configured, both the parent id and each relationship identifier are normalized before the relationship is written.
+
 ---
 
 ### patchRelationship - Replace Relationship
@@ -1136,6 +1181,8 @@ const result = await api.resources.[resourceType].patchRelationship(params, cont
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each relationship identifier inside `relationshipData` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1217,6 +1264,8 @@ const result = await api.resources.[resourceType].deleteRelationship(params, con
 }
 ```
 
+The parent `id` is normalized with the parent resource's normalizer. Each `relationshipData[*].id` is normalized with the related target resource's normalizer before validation and persistence.
+
 #### Return Value
 
 Returns `undefined` (204 No Content)
@@ -1400,7 +1449,7 @@ Each API method has its own specific hook execution order. Here's the exact sequ
 
 1. **Processing Hooks**: Only POST, PUT, and PATCH have `beforeProcessing` hooks
 2. **Schema Validation**: Only POST, PUT, and PATCH have schema validation hooks
-3. **Permission Checks**: GET uses `checkDataPermissions`, while relationship methods use `checkPermissions`
+3. **Permission Hooks**: GET uses `checkDataPermissions`, while relationship methods use `checkPermissions`
 4. **Query Filtering**: Only QUERY method triggers `knexQueryFiltering` hooks
 5. **Enrichment**: Only GET and QUERY have `enrichRecord` hooks
 6. **Relationships**: Only GET has `enrichRecordWithRelationships`
@@ -1421,7 +1470,7 @@ Each hook receives a context object with different properties based on the hook
     queryParams: {...},
     simplified: true
   },
-  auth: {...},                 // Authentication info
+  auth: {...},                 // App-provided auth/identity context if present
   transaction: {...},          // Database transaction
   schemaInfo: {...},           // Resource schema
   db: {...}                    // Database connection
@@ -1490,7 +1539,7 @@ api.resource('articles').hook('afterSchemaValidate', async (context) => {
 }
 ```
 
-**Purpose:** Authorization checks - throw error to deny access
+**Purpose:** Permission or visibility checks implemented by your app hooks. Throw an error to deny the operation.
 
 **Example:**
 ```javascript
@@ -2073,24 +2122,30 @@ api.resource('articles').hook('afterDataQuery', async (context) => {
 ### Plugin Configuration
 
 ```javascript
-const restApiPlugin = new RestApiPlugin({
+await api.use(RestApiPlugin, {
   // API behavior
   simplifiedApi: true,              // Use simplified mode for programmatic calls (default: true)
   simplifiedTransport: false,       // Use JSON:API for HTTP transport (default: false)
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  },
   
   // Return record configuration
   returnRecordApi: {
     post: 'full',                   // Return full record after create (default)
     put: 'full',                    // Return full record after replace (default)
-    patch: 'full',                  // Return full record after update (default)
-    delete: 'no'                    // Return nothing after delete (default)
+    patch: 'full'                   // Return full record after update (default)
   },
   
   returnRecordTransport: {
     post: 'no',                     // Return 204 for HTTP POST (default)
     put: 'no',                      // Return 204 for HTTP PUT (default)
-    patch: 'no',                    // Return 204 for HTTP PATCH (default)
-    delete: 'no'                    // Return 204 for HTTP DELETE (default)
+    patch: 'no'                     // Return 204 for HTTP PATCH (default)
   },
   
   // Query limits
@@ -2101,15 +2156,7 @@ const restApiPlugin = new RestApiPlugin({
   includeDepthLimit: 3,             // Maximum relationship nesting depth
   
   // Performance
-  enablePaginationCounts: true,     // Execute count queries for total pages
-  
-  // Error handling
-  exposeErrors: false,              // Include error details in responses
-  
-  // Custom serializers
-  serializers: {
-    articles: customArticleSerializer
-  }
+  enablePaginationCounts: true      // Execute count queries for total pages
 });
 ```
 
@@ -2124,7 +2171,7 @@ api.addResource({
   name: 'articles',
   
   // Primary key configuration
-  idProperty: 'id',                 // Custom primary key field (default: 'id')
+  idProperty: 'id',                 // Physical primary-key column name for table-backed resources
   
   schema: {
     // Attributes
@@ -2243,13 +2290,9 @@ api.addResource({
       }
     },
     
-    // Permissions
-    permissions: {
-      create: ['author', 'admin'],
-      read: ['*'],
-      update: ['author', 'editor', 'admin'],
-      delete: ['admin']
-    },
+    // No built-in permissions option exists here.
+    // Use permission hooks for access decisions, and optional plugins
+    // such as AutoFilterPlugin for dataset scoping.
     
     // Soft delete configuration
     softDelete: {
@@ -2275,19 +2318,95 @@ api.addResource({
 
 #### ID Property Configuration
 ```javascript
-// Custom primary key
+// Physical primary key column: user_id
 api.addResource({
   name: 'users',
-  idProperty: 'user_id',  // Use 'user_id' instead of 'id'
+  idProperty: 'user_id',
   schema: {
-    attributes: {
-      user_id: { type: 'number', required: true },
-      email: { type: 'string', required: true }
+    id: { type: 'id', required: true, storage: { column: 'user_id' } },
+    email: { type: 'string', required: true },
+    displayName: { type: 'string' }
+  }
+});
+```
+
+`idProperty` names the physical primary-key column for table-backed resources. At the API layer, the resource id remains `id`, so writes use `inputRecord.id` or `inputRecord.data.id`, reads return `id` or `data.id`, and the resource id is not part of `attributes`.
+
+#### Resource ID Normalization
+
+`normalizeId` canonicalizes resource identifiers before the library reads, writes, validates, or links records.
+
+The default normalizer:
+
+- trims surrounding whitespace from strings
+- converts finite numbers and bigints to strings
+- rejects values that normalize to an empty identifier
+
+Provide a custom normalizer when your ids need additional canonicalization:
+
+```javascript
+await api.use(RestApiPlugin, {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
+    }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  }
+});
+```
+
+Resource-level overrides take precedence over the plugin-level default:
+
+```javascript
+await api.addResource('countries', {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) {
+      return null
     }
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toLowerCase() : null
+  },
+  schema: {
+    name: { type: 'string', required: true }
+  }
+});
+```
+
+Normalization is applied to:
+
+- parent ids used by `get`, `put`, `patch`, `delete`, `getRelated`, and `getRelationship`
+- explicit `POST`, `PUT`, and `PATCH` document ids
+- relationship identifiers used by `postRelationship`, `patchRelationship`, and `deleteRelationship`
+
+Relationship identifiers use the normalizer of the related target resource, not the parent resource.
+
+If an id normalizes to an empty value:
+
+- existing-resource operations fail as `REST_API_RESOURCE` with subtype `not_found`
+- explicit `POST` document ids fail as `REST_API_VALIDATION` on `data.id`
+
+#### Storage Column Naming
+
+Table-backed resources use snake_case physical columns by default. For example, `displayName` maps to `display_name`.
+
+Use `storage.column` when a field needs a specific column name:
+
+```javascript
+api.addResource({
+  name: 'profiles',
+  schema: {
+    id: { type: 'id' },
+    displayName: { type: 'string', required: true },
+    legacyRef: { type: 'string', storage: { column: 'legacy_profile_ref' } }
   }
 });
 ```
 
+If physical columns should match logical field names exactly for an entire resource, use `storage: { naming: 'exact' }`.
+
 #### Virtual Fields
 Virtual fields are excluded from database operations but can be used for temporary UI state:
 
@@ -2499,6 +2618,45 @@ try {
 
 **Important:** When you provide a transaction, you're responsible for committing/rolling back. When you don't provide one, the library auto-commits.
 
+### Knex Schema Helpers
+
+When a resource is backed by `RestApiKnexPlugin`, its scope also exposes table-management helpers:
+
+```javascript
+await api.resources.articles.createKnexTable()
+
+const snapshot = await api.resources.articles.introspectKnexTableSnapshot()
+const createMigration = await api.resources.articles.generateKnexMigration()
+const diff = await api.resources.articles.generateKnexMigrationDiff()
+```
+
+Available helpers:
+
+- `createKnexTable()`
+- `addKnexFields({ fields })`
+- `alterKnexFields({ fields })`
+- `introspectKnexTableSnapshot()`
+- `generateKnexMigration()`
+- `generateKnexMigrationDiff()`
+
+`generateKnexMigrationDiff()` returns:
+
+```javascript
+{
+  migration,
+  warnings,
+  plan
+}
+```
+
+Important boundaries:
+
+- this is a live-table snapshot diff, not migration-history reconstruction
+- `addKnexFields()` and `alterKnexFields()` are field-only helpers
+- indexes, foreign keys, and check constraints belong on the full table schema surface
+
+For full examples and dialect notes, see [Knex Schema and Migrations](GUIDE/GUIDE_X_Knex_Schema_And_Migrations.md).
+
 ### Batch Operations
 
 Process multiple operations efficiently:
@@ -2746,4 +2904,4 @@ api.resource('articles').hook('knexQueryFiltering', async (context) => {
     query.whereRaw("metadata->>'key' = ?", [filters.metadata_key]);
   }
 });
-```
+```

package/docs/COMPARISON.md

@@ -30,7 +30,7 @@ json-rest-api is a full-featured, plugin-based JSON:API implementation built on
 | WebSocket support | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Bulk operations | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Positioning/sorting | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Authentication | ✅ | ❌ | ⚠️ | ❌ | ❌ |
+| Permission hooks / app-owned auth integration | ✅ | ❌ | ⚠️ | ❌ | ❌ |
 | **Developer Experience** |
 | TypeScript support | ✅ | ✅ | ✅ | ❌ | ❌ |
 | Active maintenance | ✅ (2025) | ✅ (2024) | ✅ (2024) | 🟡 (2022) | ❌ (2022) |
@@ -430,4 +430,4 @@ json-rest-api stands out as the most comprehensive JSON:API solution for Node.js
 4. **Active Development**: Regular updates and community support
 5. **Production Ready**: Battle-tested with extensive test coverage
 
-For teams building JSON:API services in 2025, json-rest-api offers the best combination of compliance, features, and developer experience.
+For teams building JSON:API services in 2025, json-rest-api offers the best combination of compliance, features, and developer experience.

package/docs/GUIDE/GUIDE_1_Initial_Setup.md

@@ -325,6 +325,8 @@ const result = await api.resources.countries.post({
 });
 ```
 
+If you need per-call options such as `transaction`, `returnFullRecord`, or `queryParams`, move the record under `inputRecord` and keep those options at the top level of the params object.
+
 By default, `simplifiedApi` is `true` for programmatic usage, making it easier to work with the API in your code while still maintaining full JSON:API compliance internally.
 
 #### API usage and returning records
@@ -778,6 +780,7 @@ Here is a full list of parameters and their respective variables:
 | `simplifiedApi` | `vars.simplifiedApi` | `true` | Use simplified format for programmatic API calls | ✓ |
 | `simplifiedTransport` | `vars.simplifiedTransport` | `false` | Use simplified format for HTTP/REST endpoints | ✓ |
 | `idProperty` | `vars.idProperty` | `'id'` | Name of the ID field in resources | ✓ |
+| `normalizeId` | `vars.normalizeId` | trim strings, stringify finite numbers | Normalize resource identifiers before lookups and writes | ✓ |
 | `returnRecordApi` | `vars.returnRecordApi` | `{ post: 'full', put: 'full', patch: 'full' }` | What to return for programmatic API write operations | ✓ |
 | `returnRecordTransport` | `vars.returnRecordTransport` | `{ post: 'no', put: 'no', patch: 'no' }` | What to return for HTTP/REST write operations | ✓ |
 
@@ -795,9 +798,79 @@ Here is a full list of parameters and their respective variables:
   - An object: `{ post: 'full', put: 'minimal', patch: 'no' }` (per-method configuration)
 - All parameters support the cascade: per-call → resource-level → plugin-level default
 
-# Custom ID parameter
+# Logical IDs and Physical Columns
+
+For table-backed resources, `idProperty` defines the physical primary-key column. The API surface still uses the logical resource id.
+
+- simplified writes use `inputRecord.id`
+- JSON:API writes use `inputRecord.data.id`
+- responses expose `id` or `data.id`
+- the resource id is not part of `attributes`
+
+```javascript
+await api.addResource('profiles', {
+  idProperty: 'user_id',
+  schema: {
+    id: { type: 'id', required: true, storage: { column: 'user_id' } },
+    displayName: { type: 'string', required: true },
+    loginCount: { type: 'number', defaultTo: 0 }
+  },
+  tableName: 'profiles'
+});
+```
+
+For table-backed resources, storage columns default to snake_case, so `displayName` maps to `display_name` and `loginCount` maps to `login_count`. Use `storage.column` for a per-field override, or `storage: { naming: 'exact' }` when physical column names should match logical field names exactly.
+
+## ID normalization
+
+`normalizeId` lets you canonicalize resource identifiers before the library reads, writes, validates, or links records.
 
-TODO: Explain how idParam works, clarify that for the api it's always 'id' and there is no ID in the attributes
+The default normalizer already handles the common cases:
+
+- trims surrounding whitespace from strings
+- converts finite numbers and bigints to strings
+- rejects values that normalize to an empty identifier
+
+You only need to provide `normalizeId` when your resource ids need additional canonicalization, such as uppercasing, lowercasing, or removing formatting characters.
+
+```javascript
+await api.use(RestApiPlugin, {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  }
+})
+
+await api.addResource('countries', {
+  // Override the plugin-wide normalizer for this one resource
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toLowerCase() : null
+  },
+  schema: {
+    name: { type: 'string', required: true }
+  }
+})
+```
+
+Normalization is applied consistently to:
+
+- `get`, `put`, `patch`, `delete`, `getRelated`, and `getRelationship` parent ids
+- explicit resource ids in `POST`, `PUT`, and `PATCH` documents
+- relationship identifiers supplied to `postRelationship`, `patchRelationship`, and `deleteRelationship`
+
+The resource-level `normalizeId` override also applies to relationship identifiers when that resource appears as the related target.
+
+If an id normalizes to an empty value:
+
+- existing-resource operations behave as `not_found`
+- explicit `POST` document ids are rejected as validation errors on `data.id`
+
+For full examples of table creation, physical column naming, and migration generation, see [Knex Schema and Migrations](GUIDE_X_Knex_Schema_And_Migrations.md).
 
 # Helpers and Methods Provided by REST API Plugins
 
@@ -828,8 +901,14 @@ When you install the REST API plugins, the following helpers are added to `api.h
   const trx = await api.helpers.newTransaction();
   try {
     // Use transaction in multiple operations
-    await api.resources.countries.post({ name: 'France', code: 'FR' }, { transaction: trx });
-    await api.resources.publishers.post({ name: 'French Press', country: 1 }, { transaction: trx });
+    await api.resources.countries.post({
+      inputRecord: { name: 'France', code: 'FR' },
+      transaction: trx
+    });
+    await api.resources.publishers.post({
+      inputRecord: { name: 'French Press', country: 1 },
+      transaction: trx
+    });
     await trx.commit();
   } catch (error) {
     await trx.rollback();
@@ -928,6 +1007,32 @@ Each resource (added via `api.addResource()`) gets these methods automatically:
   await api.resources.countries.createKnexTable();
   ```
 
+- **`api.resources.{resourceName}.introspectKnexTableSnapshot()`** - Returns a normalized snapshot of the live physical table
+  ```javascript
+  const snapshot = await api.resources.countries.introspectKnexTableSnapshot();
+  ```
+
+- **`api.resources.{resourceName}.generateKnexMigration()`** - Generates a Knex create migration string for the resource
+  ```javascript
+  const migration = await api.resources.countries.generateKnexMigration();
+  ```
+
+- **`api.resources.{resourceName}.generateKnexMigrationDiff()`** - Generates an additive diff migration from the live table snapshot
+  ```javascript
+  const diff = await api.resources.countries.generateKnexMigrationDiff();
+  ```
+
+- **`api.resources.{resourceName}.addKnexFields({ fields })`** / **`alterKnexFields({ fields })`** - Column-only helpers for existing tables
+  ```javascript
+  await api.resources.countries.addKnexFields({
+    fields: {
+      iso3: { type: 'string', maxLength: 3 }
+    }
+  });
+  ```
+
+For full examples of snapshots, migration generation, diffing, and table metadata such as indexes / foreign keys / checks, see [Knex Schema and Migrations](GUIDE_X_Knex_Schema_And_Migrations.md).
+
 
 ## API Namespaces (internal, for plugin developers)
 
@@ -943,6 +1048,7 @@ These helpers and methods provide a complete toolkit for:
 - Managing database transactions
 - Generating proper URLs and links
 - Accessing the underlying database when needed
+- Inspecting live tables and generating Knex migrations when using table-backed resources
 - Integrating with web frameworks like Express
 
-The architecture ensures clean separation between HTTP transport, business logic, and data persistence layers.
+The architecture ensures clean separation between HTTP transport, business logic, and data persistence layers.

package/docs/GUIDE/GUIDE_2_2_Manipulating_And_Searching_Tables.md

@@ -306,6 +306,10 @@ The `searchSchema` gives you:
 * Flexibility to extend: Add virtual fields or complex filters via searchSchema while basic fields use `search: true`
 * Best of both worlds: Explicit control for complex cases, automatic setup for simple ones
 
+`searchSchema` also defines the public filter names your API accepts. Those keys do not need to match database columns or even resource field names. Treat `searchSchema` as an allowlist plus normalization layer for filter input: the actual meaning of each key is still implemented by the backend through mappings such as `actualField`, multi-field rules such as `oneOf`, standard operators, or custom `applyFilter` logic. It is not a portable filter DSL.
+
+The merge rules and validation surface are shared across storage backends. Advanced execution semantics are still backend-owned. In practice, that means alias filters such as `oneOf` and custom `applyFilter` functions should be validated against the backend you actually run, and the SQL-heavy examples in this chapter assume the Knex-backed query layer.
+
 `searchSchema` also gives you the ability to define a search field that will search in multiple fields. For example:
 
 ```javascript
@@ -801,4 +805,4 @@ GET /api/countries?filter[search]=united+states&fields[countries]=code
 
 ---
 
-[Previous: 2.1 The starting point](./GUIDE_2_1_The_Starting_Point.md) | [Back to Guide](./README.md) | [Next: 2.3 `belongsTo` Relationships](./GUIDE_2_3_BelongsTo_Relationships.md)
+[Previous: 2.1 The starting point](./GUIDE_2_1_The_Starting_Point.md) | [Back to Guide](./README.md) | [Next: 2.3 `belongsTo` Relationships](./GUIDE_2_3_BelongsTo_Relationships.md)

package/docs/GUIDE/GUIDE_2_7_Pagination_And_Ordering.md

@@ -2,6 +2,8 @@
 
 Pagination and ordering are essential features for working with large datasets. The json-rest-api library provides powerful pagination that applies not just to main resources, but also to included relationships. This means you can limit and order both parent records AND their children independently.
 
+For derived fields that must participate in `ORDER BY` and cursor pagination, see [Query Projections](GUIDE_X_Query_Projections.md). Regular computed fields are response-layer only and are not the right tool for stable SQL ordering.
+
 Let's create a comprehensive example with posts, comments, and tags to demonstrate all pagination and ordering features:
 
 ```javascript
@@ -1233,4 +1235,4 @@ The pagination and ordering system is designed to be efficient and predictable:
 
 ---
 
-[Previous: 2.6 Many to Many Relationships](./GUIDE_2_6_Many_To_Many.md) | [Back to Guide](./README.md)
+[Previous: 2.6 Many to Many Relationships](./GUIDE_2_6_Many_To_Many.md) | [Back to Guide](./README.md)