json-rest-api 1.0.22 → 1.0.24

package/docs/GUIDE/GUIDE_2_8_Effects_of_PUT_and_PATCH.md

@@ -314,66 +314,17 @@ await api.resources.books.put({
   // publisher_id and genres NOT included!
 });
 ```
-**Effects on the database:**
+**Result: request rejected**
 
-| Table | Changes |
-|-------|---------|
-| **books** | • title: Updated<br>• author_id: Remains 1 (Tolkien)<br>• publisher_id: **SET TO NULL** |
-| **book_genres** | **ALL 3 RECORDS DELETED** - Book no longer has any genres |
-| **Other books** | **NO CHANGES** - LOTR and Silmarillion unchanged |
+PUT now fails fast when you omit a persisted field that already has a stored value. Since this book already has a `publisher_id`, leaving it out would silently discard data, so the API rejects the request instead of clearing it.
 
-Again, PUT is a **complete replacement** operation. Since we didn't include `publisher_id` or `genres` in our request, the API treats this as "I want a book with no publisher and no genres." The result:
-- `publisher_id` becomes NULL (it's nullable, so this is allowed)  
-- All genre relationships are removed from the pivot table
-- Missing fields are NOT preserved from the current state - they're cleared
+Relationship collections still follow replacement semantics when you provide a `relationships` object. The rejection in this example happens because `publisher_id` is an existing stored belongsTo value that was omitted entirely.
 
 **Expected output**
 
 ```text
-Book state BEFORE the change: {
-  id: '1',
-  title: 'The Hobbit',
-  isbn: '9780547928227',
-  published_year: 1937,
-  page_count: 310,
-  genres_ids: [ '1', '2', '3' ],
-  genres: [
-    { id: '1', name: 'Fantasy' },
-    { id: '2', name: 'Adventure' },
-    { id: '3', name: 'Classic' }
-  ],
-  author_id: '1',
-  author: {
-    id: '1',
-    name: 'J.R.R.',
-    surname: 'Tolkien',
-    birth_year: 1892,
-    books_ids: []
-  },
-  publisher_id: '1',
-  publisher: {
-    id: '1',
-    name: 'Penguin Random House',
-    country: 'USA',
-    books_ids: []
-  }
-}
-Book state AFTER the change: {
-  id: '1',
-  title: 'The Hobbit - Revised',
-  isbn: '9780547928227',
-  published_year: 1937,
-  page_count: 310,
-  genres_ids: [],
-  author_id: '1',
-  author: {
-    id: '1',
-    name: 'J.R.R.',
-    surname: 'Tolkien',
-    birth_year: 1892,
-    books_ids: []
-  }
-}
+RestApiValidationError: PUT request omits persisted fields that already have stored values
+fields: [ 'data.attributes.publisher_id' ]
 ```
 
 ### Example 3: PUT with Explicit Nulls
@@ -400,9 +351,10 @@ await api.resources.books.put({
 | **book_genres** | **ALL 3 RECORDS DELETED** |
 | **Other books** | **NO CHANGES** |
 
-This example shows PUT with **explicit nulls and empty arrays**. There's no difference between omitting a field and explicitly setting it to null/[] in a PUT operation - both result in clearing the data. This reinforces that PUT is about **complete state replacement**:
+This example shows PUT with **explicit nulls and empty arrays**. Explicit clearing is still allowed when the schema permits it, but it must be intentional. This reinforces that PUT is about **complete state replacement**:
 - You must include ALL data you want to keep
-- Anything missing or null is cleared
+- Existing stored values are not cleared by omission; omission is rejected
+- Explicit `null` / `[]` is how you clear data intentionally
 - Required fields (like `author_id`) must always be provided and cannot be null
 
 
@@ -782,8 +734,8 @@ This preservation is crucial for:
 ## Best Practices
 
 1. **Use PATCH for targeted updates** - When you only want to change specific fields
-2. **Use PUT when replacing everything** - When you have the complete new state
-3. **Always include relationships you want to keep with PUT** - They will be cleared otherwise
+2. **Use PUT when replacing everything** - When you are explicitly resending the stored values you want to keep
+3. **Always include existing stored fields you want to preserve with PUT** - Omitted persisted values are rejected
 4. **Remember required fields** - PUT must include all required fields like author_id
 5. **Child records are independent** - Other books by the same author are never affected
 
@@ -791,6 +743,6 @@ This preservation is crucial for:
 
 Now that you understand how updates affect relationships:
 - Practice with PATCH for surgical updates
-- Use PUT for complete replacements
+- Use PUT for explicit full-state replacements
 - Plan your API calls to avoid unintended data loss
-- Remember that the intelligent sync preserves pivot table metadata
+- Remember that the intelligent sync preserves pivot table metadata

package/docs/GUIDE/GUIDE_2_Data_And_Relations.md

@@ -49,7 +49,7 @@ This guide has been split into the following sections for easier navigation:
 
 ## [2.8 Effects of PUT and PATCH](./GUIDE_2_8_Effects_of_PUT_and_PATCH.md)
 - Understanding the difference between PUT and PATCH
-- How PUT affects relationships (complete replacement)
+- How PUT affects relationships and existing stored fields
 - How PATCH affects relationships (partial updates)
 - Managing belongsTo relationships
 - Handling hasMany relationships
@@ -63,4 +63,4 @@ This guide has been split into the following sections for easier navigation:
 
 ---
 
-[Back to Guide](./index.md)
+[Back to Guide](./index.md)

package/docs/GUIDE/GUIDE_3_Field_Transformations.md

@@ -11,6 +11,8 @@ Field transformations allow you to:
 - Calculate values from other fields (computed fields)
 - Control which fields are visible in responses (hidden fields)
 
+For SQL-backed derived values that must participate in sorting or cursor pagination, use [Query Projections](GUIDE_X_Query_Projections.md). Those are query-layer fields, not normal computed fields.
+
 ## The Data Transformation Pipeline
 
 Understanding when each transformation occurs is crucial for building robust APIs:
@@ -235,6 +237,8 @@ setter: (value, context) => {
 
 Computed fields are output-only fields calculated from other fields. They're never stored and always calculated fresh when requested.
 
+If a derived field must participate in SQL list behavior such as sorting or cursor pagination, use a query projection instead. Query projections are documented separately in [Query Projections](GUIDE_X_Query_Projections.md).
+
 ### Basic Computed Fields
 
 ```javascript
@@ -1243,4 +1247,4 @@ Common uses:
 - Title case formatting
 - Password hashing
 - Price calculations
-- Data consistency across related records
+- Data consistency across related records

package/docs/GUIDE/GUIDE_7_Hooks_Data_Management_And_Plugins.md

@@ -2,6 +2,8 @@
 
 This guide provides a comprehensive reference for all hooks available in the json-rest-api system, including system-wide hooks from hooked-api and method-specific hooks from the REST API plugin.
 
+If you are building a reusable plugin rather than just attaching hooks to one API, see [Writing Plugins](GUIDE_X_Writing_Plugins.md). This guide focuses on hook behavior; the plugin guide focuses on the supported extension surface.
+
 An important concept when working with hooks is understanding how simplified mode affects data flow.
 
 Inside hooks, JSON:API format is king _regardless of simplified mode_.

package/docs/GUIDE/GUIDE_X_Autofiltering.md

@@ -0,0 +1,355 @@
+# Autofiltering
+
+The `AutoFilterPlugin` provides declarative dataset scoping for `json-rest-api`.
+
+It does one job:
+
+- resolve scope values from request/runtime context
+- apply those values as automatic filters
+- stamp scoped fields on create
+- preserve scoped fields on replace
+- reject inconsistent scoped-field updates
+
+It does **not** define authentication, roles, or permissions.
+
+## Overview
+
+Autofiltering is useful whenever a resource should be constrained by one or more persisted fields:
+
+- `workspace_id`
+- `user_id`
+- `workspace_id + user_id`
+- any other application-defined scope field
+
+The plugin is generic. It does not assume:
+
+- `context.auth`
+- `authenticated`
+- `admin`
+- JWTs
+- sessions
+
+Your application decides where scope values come from. The plugin only consumes configured resolver functions.
+
+## Installation
+
+```js
+import { Api } from 'hooked-api'
+import {
+  RestApiPlugin,
+  RestApiKnexPlugin,
+  AutoFilterPlugin
+} from 'json-rest-api'
+
+const api = new Api({ name: 'scoped-api' })
+
+await api.use(RestApiPlugin)
+await api.use(RestApiKnexPlugin, { knex })
+
+await api.use(AutoFilterPlugin, {
+  resolvers: {
+    workspace: ({ context }) => context.session?.workspaceId,
+    user: ({ context }) => context.subject?.id,
+  },
+
+  presets: {
+    public: { filters: [] },
+
+    workspace: {
+      filters: [
+        { field: 'workspace_id', resolver: 'workspace' }
+      ]
+    },
+
+    user: {
+      filters: [
+        { field: 'user_id', resolver: 'user' }
+      ]
+    },
+
+    workspace_user: {
+      filters: [
+        { field: 'workspace_id', resolver: 'workspace' },
+        { field: 'user_id', resolver: 'user' }
+      ]
+    }
+  }
+})
+```
+
+## Resource Configuration
+
+Apply a preset by name:
+
+```js
+await api.addResource('projects', {
+  schema: {
+    id: { type: 'id' },
+    name: { type: 'string', required: true },
+    workspace_id: { type: 'string', required: true },
+    user_id: { type: 'number', required: true }
+  },
+  autofilter: 'workspace_user'
+})
+```
+
+Use a preset with extra filters:
+
+```js
+await api.addResource('documents', {
+  schema: {
+    id: { type: 'id' },
+    workspace_id: { type: 'string', required: true },
+    user_id: { type: 'number', required: true },
+    locale: { type: 'string', required: true }
+  },
+  autofilter: {
+    preset: 'workspace_user',
+    filters: [
+      {
+        field: 'locale',
+        resolve: ({ context }) => context.requestState?.locale
+      }
+    ]
+  }
+})
+```
+
+Use inline filters with no preset:
+
+```js
+await api.addResource('reports', {
+  schema: {
+    id: { type: 'id' },
+    account_id: { type: 'string', required: true }
+  },
+  autofilter: {
+    filters: [
+      {
+        field: 'account_id',
+        resolve: ({ context }) => context.scopeValues?.accountId
+      }
+    ]
+  }
+})
+```
+
+Declare a public resource explicitly:
+
+```js
+await api.addResource('system_settings', {
+  schema: {
+    id: { type: 'id' },
+    key: { type: 'string', required: true },
+    value: { type: 'string', required: true }
+  },
+  autofilter: 'public'
+})
+```
+
+If a resource has no `autofilter` setting, the plugin does nothing for that resource.
+
+## Runtime Behavior
+
+### Query Scoping
+
+Collection queries automatically receive all configured filters.
+
+For a `workspace_user` resource:
+
+```js
+await api.resources.projects.query(
+  { simplified: false },
+  {
+    session: { workspaceId: 'acme' },
+    subject: { id: 101 }
+  }
+)
+```
+
+behaves like:
+
+```sql
+SELECT * FROM projects
+WHERE workspace_id = 'acme'
+  AND user_id = 101
+```
+
+### Single-Record Scoping
+
+`get`, `put`, `patch`, and `delete` operate on the already-scoped dataset.
+
+If a record is outside the current scope, it behaves as not found.
+
+### Create-Time Stamping
+
+On `POST`, scoped fields are injected automatically when missing.
+
+Example:
+
+```js
+await api.resources.projects.post({
+  inputRecord: {
+    data: {
+      type: 'projects',
+      attributes: {
+        name: 'Roadmap'
+      }
+    }
+  },
+  simplified: false
+}, {
+  session: { workspaceId: 'acme' },
+  subject: { id: 101 }
+})
+```
+
+Stored attributes:
+
+```js
+{
+  name: 'Roadmap',
+  workspace_id: 'acme',
+  user_id: 101
+}
+```
+
+### Replace/Update Consistency
+
+On `PUT`:
+
+- missing scoped fields are injected so replacement stays consistent
+- mismatched scoped fields are rejected
+
+On `PATCH`:
+
+- omitted scoped fields stay omitted
+- explicitly provided mismatched scoped fields are rejected
+
+## Relationship-Aware Scoping
+
+Autofiltering also affects relationship validation because scoped single-record lookups are used when checking related resources.
+
+So this will fail if the referenced project is outside scope:
+
+```js
+await api.resources.tasks.post({
+  inputRecord: {
+    data: {
+      type: 'tasks',
+      attributes: { title: 'Cross-scope task' },
+      relationships: {
+        project: {
+          data: { type: 'projects', id: '123' }
+        }
+      }
+    }
+  },
+  simplified: false
+}, {
+  scopeValues: {
+    workspaceId: 'workspace-a',
+    userId: 101
+  }
+})
+```
+
+## Missing Scope Values
+
+By default, each filter is required.
+
+If a resolver returns `undefined`, the plugin throws:
+
+```text
+Missing autofilter value for resolver 'workspace' on resource 'projects'
+```
+
+To make a filter optional, set `required: false`:
+
+```js
+{
+  field: 'workspace_id',
+  resolver: 'workspace',
+  required: false
+}
+```
+
+When `required: false` and the resolver returns `undefined`, that filter is skipped.
+
+## BelongsTo Foreign Keys
+
+If the scoped field is a `belongsTo` foreign key with an alias, the plugin works through the JSON:API relationship shape.
+
+Example:
+
+```js
+user_id: {
+  type: 'number',
+  belongsTo: 'users',
+  as: 'user'
+}
+```
+
+The plugin will stamp or validate:
+
+```js
+data.relationships.user.data.id
+```
+
+instead of treating it as a direct client-owned attribute.
+
+## Storage Mapping
+
+Autofiltering uses the compiled storage adapter automatically.
+
+So this works correctly:
+
+```js
+workspace_id: {
+  type: 'string',
+  storage: { column: 'workspace_key' }
+}
+```
+
+The plugin scopes using the logical field name, while Knex filtering uses the mapped storage column.
+
+## Introspection Helpers
+
+The plugin exposes light runtime inspection helpers:
+
+```js
+api.autofilter.getConfig()
+api.autofilter.getScopeConfig('projects')
+```
+
+Example:
+
+```js
+api.autofilter.getScopeConfig('projects')
+// {
+//   preset: 'workspace_user',
+//   filters: [
+//     { field: 'workspace_id', resolver: 'workspace', required: true },
+//     { field: 'user_id', resolver: 'user', required: true }
+//   ]
+// }
+```
+
+## Design Boundary
+
+`AutoFilterPlugin` is intentionally narrower than an auth plugin.
+
+It owns:
+
+- dataset scoping
+- scoped-field stamping
+- scoped-field consistency
+
+It does **not** own:
+
+- authentication meaning
+- role policy
+- admission checks
+- permissions like `authenticated` or `owns`
+
+That logic belongs in higher layers or custom `checkPermissions` hooks.

package/docs/GUIDE/GUIDE_X_Fastify.md

@@ -0,0 +1,78 @@
+# Fastify Integration
+
+`json-rest-api` now ships a Fastify-oriented connector:
+
+```js
+import fastify from 'fastify'
+import {
+  RestApiPlugin,
+  RestApiKnexPlugin,
+  FastifyPlugin
+} from 'json-rest-api'
+
+const app = fastify()
+
+await api.use(RestApiPlugin, {
+  simplifiedApi: false,
+  simplifiedTransport: false
+})
+
+await api.use(RestApiKnexPlugin, { knex })
+
+await api.use(FastifyPlugin, {
+  app,
+  mountPath: '/api'
+})
+```
+
+## What the connector does
+
+The Fastify connector listens to the same `addRoute` hook as the Express connector and registers the generated REST routes on the Fastify instance you pass in `pluginOptions.app`.
+
+It also consumes the transport schema exported by `json-rest-schema` before the request reaches the resource method:
+
+- `POST` routes use the schema export in `create` mode
+- `PUT` routes use the schema export in `replace` mode
+- `PATCH` routes use the schema export in `patch` mode
+- relationship `POST` / `PATCH` / `DELETE` routes use JSON:API relationship document schemas
+
+Those field schemas are wrapped in the JSON:API document envelope expected by `json-rest-api`.
+
+## What gets rejected early
+
+Fastify can now stop malformed write payloads before they reach the app layer:
+
+- missing `data`
+- invalid `data.type`
+- invalid `data.id` on `PUT` / `PATCH`
+- malformed attribute payloads
+- unknown attribute fields
+- invalid scalar types according to the resource schema
+- malformed relationship write documents
+
+The transport schema also reflects the existing write contract:
+
+- output-only computed fields are removed from `data.attributes`
+- direct `belongsTo` foreign keys are removed from `data.attributes`
+- relationship linkage still belongs under `data.relationships`
+
+This keeps Fastify transport validation aligned with the same transport rules already enforced by the runtime methods.
+
+## Content types
+
+The connector registers an `application/vnd.api+json` parser and rejects unsupported write content types before the route handler runs.
+
+Accepted write content types are:
+
+- `application/vnd.api+json`
+- `application/json`
+
+## Scope
+
+This connector is intentionally narrow:
+
+- it uses the exported schema already owned by `json-rest-schema`
+- it does not add a JSKIT-specific compatibility layer
+- it does not move business validation out of the resource methods
+
+The goal is transport-level shape rejection, not a second validation system.