json-rest-api 1.0.23 → 1.0.25

package/docs/GUIDE/GUIDE_X_Autofiltering.md

@@ -77,6 +77,69 @@ await api.use(AutoFilterPlugin, {
 })
 ```
 
+## Storage Backends
+
+`AutoFilterPlugin` works with either database storage plugin:
+
+- `RestApiKnexPlugin` for resources backed by normal database tables
+- `RestApiAnyapiKnexPlugin` for logical resources backed by AnyAPI canonical storage
+
+An `Api` instance has one storage engine. Install either storage plugin, then install `AutoFilterPlugin`. If an application keeps core resources in normal tables and user-defined resources in AnyAPI, create one `Api` instance for each storage engine. Each instance owns its resources and autofilter configuration.
+
+Autofilter definitions always use logical schema field names. The selected storage plugin translates those fields to normal table columns or AnyAPI canonical slots.
+
+### Workspace Scoping with AnyAPI
+
+AnyAPI's `tenantId` is fixed when `RestApiAnyapiKnexPlugin` is installed. It identifies the metadata and canonical-storage namespace; it is not a per-request workspace value. For one AnyAPI instance serving multiple application workspaces, use a stable internal `tenantId` and persist `workspace_id` on every workspace-scoped resource:
+
+```js
+import { Api } from 'hooked-api'
+import {
+  RestApiPlugin,
+  RestApiAnyapiKnexPlugin,
+  AutoFilterPlugin
+} from 'json-rest-api'
+
+const api = new Api({ name: 'form-data-api' })
+
+await api.use(RestApiPlugin)
+await api.use(RestApiAnyapiKnexPlugin, {
+  knex,
+  tenantId: 'application'
+})
+
+await api.use(AutoFilterPlugin, {
+  resolvers: {
+    workspace: ({ context }) => context.session?.workspaceId
+  },
+  presets: {
+    workspace: {
+      filters: [
+        { field: 'workspace_id', resolver: 'workspace' }
+      ]
+    }
+  }
+})
+
+await api.addResource('form_123', {
+  schema: {
+    id: { type: 'id' },
+    workspace_id: { type: 'string', required: true },
+    customer_name: { type: 'string', required: true },
+    subscribed: { type: 'boolean' }
+  },
+  autofilter: 'workspace'
+})
+```
+
+In this arrangement:
+
+- `tenantId: 'application'` selects one fixed AnyAPI metadata and canonical-storage namespace. Do not derive it from request context.
+- `workspace_id` isolates application workspaces. `AutoFilterPlugin` stamps it on writes and filters by it on reads.
+- A trusted resolver supplies the current workspace. Do not resolve it directly from an unverified request field.
+- User-defined forms with different schemas need distinct resource names within the AnyAPI namespace, such as `form_123` and `form_456`. Put the workspace autofilter on each resource.
+- Workspaces may use the same logical resource when they share its schema; `workspace_id` still keeps their records separate.
+
 ## Resource Configuration
 
 Apply a preset by name:

package/docs/GUIDE/GUIDE_X_File_Uploads.md

@@ -19,7 +19,7 @@ The file handling system consists of three main components:
 
 1. **FileHandlingPlugin** - Orchestrates file detection and processing
 2. **Protocol Detectors** - Parse files from different protocols (HTTP, Express)
-3. **Storage Adapters** - Save files to different backends (local, S3, etc.)
+3. **Storage Adapters** - Save files to local storage or generate mock S3-style URLs for demos
 
 ### How It Works
 
@@ -115,11 +115,11 @@ Storage adapters handle where and how files are saved. The library includes two
 | **Extension Whitelist** | ✅ Yes | ❌ No |
 | **Duplicate Handling** | ✅ Yes | ✅ Automatic |
 | **Custom Naming** | ✅ Yes | ❌ No |
-| **Best For** | Local file storage | Cloud storage |
+| **Best For** | Local file storage | Tests, examples, S3-style URL demos |
 
-### S3Storage
+### S3Storage (Mock/Demo)
 
-Saves files to Amazon S3 or S3-compatible storage:
+Generates S3-style URLs without uploading files to Amazon S3:
 
 ```javascript
 import { S3Storage } from 'json-rest-api/plugins/storage/s3-storage.js';
@@ -129,7 +129,7 @@ const s3Storage = new S3Storage({
   region: 'us-east-1',                 // AWS region (default: 'us-east-1')
   prefix: 'uploads/',                  // Path prefix in bucket (default: '')
   acl: 'public-read',                  // Access control (default: 'public-read')
-  mockMode: false                      // Use mock mode? (default: true)
+  mockMode: true                       // Only supported mode
 });
 ```
 
@@ -137,7 +137,7 @@ const s3Storage = new S3Storage({
 - Always generates random hash + extension (e.g., `uploads/a7f8d9e2b4c6e1f3.jpg`)
 - Original filenames are never used for security
 
-**Note**: The included S3Storage is a mock implementation for demonstration. For production use, you'll need to implement the actual AWS SDK calls.
+**Note**: The included S3Storage is a mock implementation for demonstration. `mockMode: false` throws a clear error because real S3 uploads are not implemented. For production use, provide your own storage adapter or add an AWS SDK-backed implementation.
 
 ### LocalStorage
 
@@ -187,9 +187,11 @@ const localStorage = new LocalStorage({
    }
    // Result: "user_12345_1672531200000.jpg"
    ```
+   Custom generators must return a basename only, not a path. Values containing `/`, `\`, drive prefixes, or only whitespace are rejected.
 
 **Security Features:**
-- Path traversal protection (removes `..` and `/`)
+- Path traversal protection (sanitizes original names and rejects path-like custom names)
+- Custom generated names are restricted to basenames
 - Control character filtering
 - Extension validation against whitelist
 - Automatic duplicate handling
@@ -218,12 +220,15 @@ class MyCustomStorage {
   }
   
   async delete(url) {
-    // Optional: implement file deletion
+    // Optional but recommended: FileHandlingPlugin calls this after
+    // an uploaded file's write transaction rolls back.
     await deleteFileSomewhere(url);
   }
 }
 ```
 
+`FileHandlingPlugin` always calls detector-provided `file.cleanup()` after parsing, including validation failures. If a file has already been uploaded and the later resource write rolls back, the plugin calls `storage.delete(url)` when the adapter implements it. Storage adapters that need rollback cleanup should make `delete(url)` idempotent for URLs returned by `upload(file)`.
+
 ## Protocol Configuration
 
 Different protocols have different configuration options for file parsing.
@@ -536,11 +541,11 @@ const organizedStorage = new LocalStorage({
   nameStrategy: 'custom',
   nameGenerator: async (file) => {
     const date = new Date();
-    const dateDir = `${date.getFullYear()}/${String(date.getMonth() + 1).padStart(2, '0')}`;
-    return `${dateDir}/${crypto.randomBytes(16).toString('hex')}`;
+    const datePrefix = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+    return `${datePrefix}-${crypto.randomBytes(16).toString('hex')}`;
   }
 });
-// Saves as: "2024/01/a7f8d9e2b4c6e1f3.jpg"
+// Saves as: "2024-01-a7f8d9e2b4c6e1f3.jpg"
 ```
 
 ### Using cURL
@@ -721,4 +726,4 @@ Then visit http://localhost:3000 to see the test forms.
 - Add image processing (thumbnails, resizing)
 - Implement virus scanning for uploads
 - Add progress tracking for large files
-- Create a chunked upload system for very large files
+- Create a chunked upload system for very large files

package/docs/GUIDE/GUIDE_X_Knex_Schema_And_Migrations.md

@@ -29,8 +29,8 @@ Example:
 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' }
   },
 
@@ -64,6 +64,126 @@ await api.addResource('memberships', {
 })
 ```
 
+## Default Column Naming
+
+Table-backed resources keep logical field names in the resource schema and map them to physical columns for Knex operations.
+
+By default, physical columns use snake_case:
+
+- `workspaceId` -> `workspace_id`
+- `userId` -> `user_id`
+- `createdAt` -> `created_at`
+
+This keeps the API surface expressive without repeating `storage.column` on every camelCase field.
+
+You only need `storage.column` when a field should use a non-standard column name:
+
+```js
+await api.addResource('profiles', {
+  schema: {
+    id: { type: 'id' },
+    displayName: { type: 'string', required: true },
+    legacyRef: { type: 'string', storage: { column: 'legacy_profile_ref' } }
+  },
+  tableName: 'profiles'
+})
+```
+
+If you need physical columns to match the logical field names exactly for a whole resource, opt out explicitly:
+
+```js
+await api.addResource('verbatim_profiles', {
+  storage: { naming: 'exact' },
+  schema: {
+    id: { type: 'id' },
+    displayName: { type: 'string', required: true }
+  },
+  tableName: 'verbatim_profiles'
+})
+```
+
+## Logical IDs and `idProperty`
+
+`idProperty` names the physical primary-key column for table-backed resources. The API contract still uses the logical resource id.
+
+```js
+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'
+})
+```
+
+With this definition:
+
+- writes send the resource id as `id` or `data.id`
+- reads return the resource id as `id` or `data.id`
+- the primary key is stored in `user_id`
+- `displayName` and `loginCount` are stored in `display_name` and `login_count`
+
+The resource id is not part of `attributes`:
+
+```js
+await api.resources.profiles.post({
+  inputRecord: {
+    data: {
+      type: 'profiles',
+      id: '42',
+      attributes: {
+        displayName: 'Mercury'
+      }
+    }
+  }
+})
+```
+
+### ID normalization
+
+If your primary keys need canonicalization beyond the default trim-and-stringify behavior, configure `normalizeId`.
+
+```js
+await api.use(RestApiPlugin, {
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toUpperCase() : null
+  }
+})
+```
+
+You can override that per resource:
+
+```js
+await api.addResource('profiles', {
+  idProperty: 'user_id',
+  normalizeId: (value) => {
+    if (value === null || value === undefined) return null
+
+    const normalized = String(value).trim()
+    return normalized ? normalized.toLowerCase() : null
+  },
+  schema: {
+    id: { type: 'id', required: true, storage: { column: 'user_id' } },
+    displayName: { type: 'string', required: true }
+  },
+  tableName: 'profiles'
+})
+```
+
+For table-backed resources, `normalizeId` is applied before:
+
+- reading a record by id
+- replacing, patching, or deleting a record
+- persisting an explicit `POST` resource id
+- validating or writing relationship identifiers that point at the resource
+
+If the normalizer returns an empty value, existing-resource operations fail as `not_found`, while explicit `POST` document ids fail validation on `data.id`.
+
 ## Create Tables
 
 Create the table directly from the resource definition: