@web-ts-toolkit/access-router 0.43.0 → 0.45.0

package/README.md

@@ -104,6 +104,17 @@ snapshots. Mutating the original options object, a fetched options snapshot, or
 not change live runtime policy or served in-memory records. Replace configured data through `router.data(next)`
 or `setDataOption(name, 'data', next)`.
 
+ACL filter hooks may return `false` to deny a query. That denial is terminal through identifier, override, and
+base-filter composition. `overrideFilter` is a trusted hook that may replace an ordinary client or identifier
+filter before the base filter is applied, but it is not called for an existing `false` filter and cannot revive
+that denial. Returning `false` from `overrideFilter` also denies the query. Empty or absent filters retain their
+normal unrestricted meaning unless a base filter restricts them.
+
+Advanced mutation validators drive dispatch: nested `data` validators run first, then the whole-body (`default`)
+validator sees that transformed envelope, and the service persists only the final parsed `data`, `select`,
+`populate`, `tasks`, and allowed `options`. Missing body options fall back to `returning_all`/`include_permissions`
+query params; only `includePermissions`/`populateAccess` (plus `returningAll` for update/upsert) are forwarded.
+
 ## Main Exports
 
 Root entrypoint (`@web-ts-toolkit/access-router`):
@@ -115,12 +126,14 @@ Root entrypoint (`@web-ts-toolkit/access-router`):
 - `guard(...)` and `GuardModelCondition`, `GuardModelConditionID` types
 - `combineRoutes(...)` and `createOpenApiRouter(runtime, options)` (note: prefer `acl.createOpenApiRouter(options)` for the default runtime)
 - validation adapters: `defineRequestSchema(...)`, `fromZod(...)`, `fromYup(...)`, `fromJoi(...)`, `fromAjv(...)`, `fromStandardSchema(...)`, `fromValibot(...)`, `fromArkType(...)`, `fromIoTs(...)`, `fromSuperstruct(...)`, `fromVine(...)`
+- `permissionsPlugin` (src/plugins.ts) — Mongoose schema plugin used as `schema.plugin(permissionsPlugin, { modelName })`
+- logger helpers: `redactFilter`, `redactPayload`, `safeStringify`, `isLevelEnabled` + `OpLogContext` type
 - option helpers: `setGlobalOptions`, `setGlobalOption`, `getGlobalOptions`, `getGlobalOption`, `setModelOptions`, `setModelOption`, `getModelOptions`, `getModelOption`, `getModelNames`, `getModelJsonSchema`, `setDefaultModelOptions`, `setDefaultModelOption`, `getDefaultModelOptions`, `getDefaultModelOption`
 
 Subpath entrypoints:
 
-- `@web-ts-toolkit/access-router/advanced` — low-level runtime context, symbols (`MIDDLEWARE`, `PERMISSIONS`, ...), enums (`Codes`, `StatusCodes`), internals (`parseBody`, `parseQuery`, request schemas). Does NOT export `acl`, `defaultRuntime`, or router-creation helpers.
-- `@web-ts-toolkit/access-router/processors` — `copyAndDepopulate` and its `ProcessCopy` / `CopyAndDepopulateOptions` / `CopyAndDepopulateOutput` types for transforming populated documents.
+- `@web-ts-toolkit/access-router/advanced` — low-level runtime context, symbols (`MIDDLEWARE`, `DATA_MIDDLEWARE`, `PERMISSIONS`, ...), enums (`Codes`, `StatusCodes`), internals (`parseBody`, `parseQuery`, `parseBodyWithSchema`, request schemas). Does NOT export `acl`, `defaultRuntime`, or router-creation helpers.
+- `@web-ts-toolkit/access-router/processors` — `copyAndDepopulate`, `copyPaths`, `movePaths`, `sliceArrays`, `countPaths`, `maskPaths` and processor option types (`ProcessCopy`, `CopyAndDepopulateOptions`, `CopyAndDepopulateOutput`, `ProcessorOptions`, `SliceProcessorOptions`, `ProcessSlice`, `ProcessCount`, `ProcessMask`, `ProcessorOutput`) for transforming populated documents.
 
 ## Default runtime vs. isolated runtime
 
@@ -152,6 +165,15 @@ to `runtime.createRouter(model, options)` or call `runtime.registerModelInstance
 string-name router. The default `acl` runtime retains string-name compatibility with `mongoose.model(name, schema)` and
 adopts that exact global model instance into its registry on first lookup.
 
+Cross-runtime composition on a shared request keeps independent runtime-owned state. When one request passes through
+middleware from runtime A and then runtime B, B initializes its own core, resolves its own `globalPermissions`, and
+uses its own base-filter cache; it never reuses A's permissions or cached filters, even when both runtimes use the
+same `requestPermissionField` name. Repeating the same runtime's middleware on one request reuses that runtime's state
+without rerunning its resolver. Values already present in `requestPermissionField` before any runtime middleware runs
+are treated as application-supplied and preserved. Migration: if you relied on B silently inheriting A's resolved
+permissions on a shared request, set those permissions explicitly before the chain or configure B's `globalPermissions`
+to resolve them.
+
 ## createRouter overloads
 
 `createRouter(modelName, options)` — on the default `acl` runtime, accept the Mongoose model name registered with `mongoose.model(name, schema)`. On isolated runtimes, the name must already be registered with that runtime.
@@ -180,6 +202,79 @@ Advanced read/list requests can attach related model data with `include` entries
 `op: 'count'` returns exact authorized counts and ignores include pagination fields such as `args.limit`.
 `op: 'list'` materializes authorized related rows through the target model's normal list path, so target `limit`, `page`, `pageSize`, and `listHardLimit` bounds still apply to included rows.
 
+## Correlated Includes
+
+Besides the legacy `localField`/`foreignField` joins, `include` entries accept
+a correlated variant (`mode: 'correlated'`) that runs a target query **per
+parent document** using values from that parent. References are explicit
+structural markers — `{ "$parent": "<field>" }`, dotted paths allowed —
+recognized only in filter _value_ positions (bare values, field operators
+such as `$eq`/`$in`, `$in` array elements, `$and`/`$or`/`$nor` clauses,
+`$elemMatch` subtrees) and as the whole `id` of identifier reads. Plain
+strings are never references: `'$special'` keeps its literal query meaning.
+Match a literal `{ "$parent": "x" }` object with
+`{ "$escape": { "$parent": "x" } }` (use the `$eq`-wrapped form when the
+literal sits in a bare field position).
+
+Wire shapes (the originating method fixes `op`; there is no override):
+
+```json
+{ "mode": "correlated", "model": "Org", "op": "read", "path": "org", "id": { "$parent": "orgId" } }
+{ "mode": "correlated", "model": "Org", "op": "read", "path": "org",
+  "filter": { "_id": { "$parent": "orgId" }, "active": true }, "args": { "select": ["name"] } }
+{ "mode": "correlated", "model": "Post", "op": "list", "path": "posts",
+  "filter": { "authorId": { "$parent": "_id" }, "title": "$special" },
+  "args": { "select": ["title"], "sort": { "createdAt": -1 }, "limit": 5 } }
+{ "mode": "correlated", "model": "Post", "op": "count", "path": "postCount",
+  "filter": { "authorId": { "$parent": "_id" } } }
+```
+
+Semantics:
+
+- References resolve against the **immediate parent** document as fetched
+  from persistence (including internally loaded reference fields), before
+  include attachment, `decorate` hooks, and task mutation. Nested
+  `args.include` entries bind to the target doc of the enclosing include.
+  Sibling include output never feeds references.
+- A missing (`undefined`) or `null` reference short-circuits that parent's
+  execution to the no-match shape with no target query: `read` attaches
+  `null`, `list` attaches `[]`, `count` attaches `0`. Target misses produce
+  the same shapes. The output path is always set.
+- Identifier reads use the target's configured identifier behavior
+  (`resolveIdentifierFilter`/`genIDFilter`, custom `resolveIdFilter`
+  honored) with no read-to-list fallback. Counts use explicit count access
+  with count semantics, independent of any list limit. List pagination
+  (`skip`/`limit`/`page`/`pageSize`) applies **per parent** — contrast with
+  legacy batched list includes, whose pagination applies across the parent
+  set. Substituted parent values are data: objects match literally (never
+  become operators) and arrays are never flattened.
+- Each correlated entry counts toward `maxIncludeCount`; expanded filters
+  are revalidated against `maxNodes`/`maxDepth`/`maxInValues`/
+  `maxLogicalClauses`. Total inner executions per request are bounded by
+  `maxCorrelatedQueries` (default `100`) and nesting by
+  `maxCorrelatedDepth` (default `5`); exceeding any bound fails the whole
+  request. Fan-out shares the request-scoped scheduler (no per-parent
+  reset). Target authorization denials fail the whole request with zero
+  target persistence queries; target runtime errors fail the whole request.
+  `path` must be a non-empty valid field path (not `_id`, not `$`-prefixed);
+  duplicates in one include array are `BadRequest`; collisions with parent
+  fields overwrite (legacy `setDocValue` parity).
+- Referenced parent fields are added to the parent DB select like legacy
+  `localField`s, then trimmed unless allowed by field policy and selected.
+  A policy-forbidden reference still resolves — only its query effects are
+  visible, never the value.
+- Direct count parents carry no `include`; correlated _count_ includes
+  attach to read/list parents only. Correlated entries are accepted in both
+  direct (`model-router.ts`) and root (`root-router.ts`) validators with
+  identical verdicts; malformed correlated input is a controlled
+  `BadRequest`, never a silent drop. Legacy entries are unchanged, and
+  legacy-shaped entries carrying `$parent` markers are rejected.
+
+The TypeScript wire types (`ParentRef`, `CorrelatedInclude`, `Include`) are
+reachable without deep imports via `@web-ts-toolkit/access-router/advanced`
+(which re-exports `./interfaces`). See the website `services`,
+`configuration`, `validation`, and `openapi` pages for the full contract.
+
 ## Import styles
 
 The package ships both a default export and named exports: