@web-ts-toolkit/access-router 0.51.0 → 0.53.0

package/index.d.mts

@@ -1,7 +1,7 @@
 import mongoose, { Schema } from 'mongoose';
 import { Response, NextFunction, RequestHandler, Router } from 'express';
-import { A as AccessRouterBaseRequest, aj as GuardHook, aI as ModelRequest, d8 as AccessRuntime, V as DataRouterOptions, T as DataRequest, d9 as DataService, a4 as ExtendedDataRouterOptions, a8 as Filter, b2 as Projection, c0 as Sort, a$ as Populate, aJ as ModelRouterOptions, da as Service, db as PublicService, aS as ModelVirtualRecordAccess, aO as ModelVirtualDescriptor, aQ as ModelVirtualGetter, aR as ModelVirtualLeaf, a6 as ExtendedModelRouterOptions, cL as Validation, bQ as RootRouterOptions, dc as OpenApiRouterOptions, dd as OpenApiRegistryOptions, de as OpenApiRouteDescriptor, df as OpenApiDocumentOptions, dg as OpenApiParameter, dh as OpenApiSchema, di as OpenApiResponses, ah as GlobalOptions, Z as DefaultModelRouterOptions, a5 as ExtendedDefaultModelRouterOptions } from './parsers-DhUuvj9B.mjs';
-export { dj as AccessRouterPermissionMap, dk as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, n as AjvValidatorLike, o as ArkTypeErrorsLike, p as ArkTypeLike, a7 as FieldOperationAccess, ai as GlobalPermissionValue, am as IoTsContextEntryLike, an as IoTsDecodeErrorLike, ao as IoTsDecoderLike, ap as JoiSchemaLike, aq as JoiValidationErrorDetailLike, aw as MaybePromise, ax as ModelBaseFilterHook, az as ModelDeleteHook, aA as ModelDocPermissionsHook, aC as ModelDocumentHook, aD as ModelHook, aF as ModelIdentifierHook, aG as ModelListHook, aH as ModelOverrideFilterHook, aK as ModelValidateHook, aL as ModelVirtualAccess, aM as ModelVirtualAccessRecord, aN as ModelVirtualContext, aP as ModelVirtualDoc, aT as ModelVirtuals, dl as OpenApiMethod, aU as OperationAccess, aX as PairedRouteAccess, a_ as PermissionSchema, dm as Permissions, bk as RequestSchemaAdapter, bl as RequestSchemaFailure, bm as RequestSchemaIssue, bn as RequestSchemaLike, bo as RequestSchemaOptions, bp as RequestSchemaResult, bq as RequestSchemaSuccess, br as RequestSchemaValidator, bT as RouteBaseAccess, bU as RouteGuardAccess, bV as RouteVariant, bW as RouteVariantAccess, c2 as StandardSchemaFailure, c3 as StandardSchemaInferOutput, c4 as StandardSchemaIssue, c5 as StandardSchemaPathSegment, c6 as StandardSchemaResult, c7 as StandardSchemaSuccess, c8 as StandardSchemaV1, cb as SubOperationAccess, cf as SubRouteGuardOptions, cr as SuperstructFailureLike, cs as SuperstructValidateLike, cF as ValibotIssueLike, cG as ValibotPathItemLike, cH as ValibotSafeParseLike, cI as ValibotSafeParseResult, cN as VineValidationErrorLike, cO as VineValidationMessageLike, cP as VineValidatorLike, cQ as VirtualSubModel, cR as WithVirtuals, cS as YupSchemaLike, cT as YupValidationErrorLike, dn as defaultRuntime, cU as defineRequestSchema, cV as fromAjv, cW as fromArkType, cX as fromIoTs, cY as fromJoi, cZ as fromStandardSchema, c_ as fromSuperstruct, c$ as fromValibot, d0 as fromVine, d1 as fromYup, d2 as fromZod } from './parsers-DhUuvj9B.mjs';
+import { A as AccessRouterBaseRequest, aq as GuardHook, aT as ModelRequest, dP as AccessRuntime, _ as DataRouterOptions, Y as DataRequest, dQ as DataService, aa as ExtendedDataRouterOptions, af as Filter, bm as Projection, ct as Sort, bi as Populate, aU as ModelRouterOptions, dR as Service, dS as PublicService, b1 as ModelVirtualRecordAccess, aZ as ModelVirtualDescriptor, a$ as ModelVirtualGetter, b0 as ModelVirtualLeaf, ac as ExtendedModelRouterOptions, dq as Validation, cd as RootRouterOptions, dT as OpenApiRouterOptions, dU as OpenApiRegistryOptions, dV as OpenApiRouteDescriptor, dW as OpenApiDocumentOptions, dX as OpenApiParameter, dY as OpenApiSchema, dZ as OpenApiResponses, ao as GlobalOptions, a2 as DefaultModelRouterOptions, ab as ExtendedDefaultModelRouterOptions } from './parsers-ZSrF7SNu.mjs';
+export { d_ as AccessRouterPermissionMap, d$ as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, n as AjvValidatorLike, o as AllowedOutputFieldOptions, p as ArkTypeErrorsLike, q as ArkTypeLike, s as AuthorizedListResult, t as AuthorizedSingleResult, H as CreateAuthorization, N as DataFieldOptions, a7 as DocumentAuthorization, ad as FieldAuthorization, ae as FieldOperationAccess, ap as GlobalPermissionValue, ar as HydrationMode, au as InputFieldAuthorization, av as InputFieldPath, aw as IoTsContextEntryLike, ax as IoTsDecodeErrorLike, ay as IoTsDecoderLike, az as JoiSchemaLike, aA as JoiValidationErrorDetailLike, aG as MaybePromise, aH as ModelBaseFilterHook, aJ as ModelDeleteHook, aK as ModelDocPermissionsHook, aM as ModelDocumentHook, aN as ModelHook, aP as ModelHydrationOptions, aQ as ModelIdentifierHook, aR as ModelListHook, aS as ModelOverrideFilterHook, aV as ModelValidateHook, aW as ModelVirtualAccess, aX as ModelVirtualAccessRecord, aY as ModelVirtualContext, a_ as ModelVirtualDoc, b2 as ModelVirtuals, b3 as MutationAuthorization, b4 as NewArgs, b5 as NewOptions, e0 as OpenApiMethod, b6 as OperationAccess, b7 as OperationAuthorization, b8 as OutputAuthorization, b9 as OutputFieldOptions, ba as OutputFieldPath, bb as OutputPlanningOptions, be as PairedRouteAccess, bh as PermissionSchema, e1 as Permissions, bk as PopulatePlanningOptions, by as PublicSubdocumentCreateOptions, bz as PublicSubdocumentListOptions, bA as PublicSubdocumentMutationOptions, bB as PublicSubdocumentReadOptions, bH as RelatedAuthorization, bJ as RequestSchemaAdapter, bK as RequestSchemaFailure, bL as RequestSchemaIssue, bM as RequestSchemaLike, bN as RequestSchemaOptions, bO as RequestSchemaResult, bP as RequestSchemaSuccess, bQ as RequestSchemaValidator, cg as RouteBaseAccess, ch as RouteGuardAccess, ci as RouteVariant, cj as RouteVariantAccess, ck as RowAuthorization, co as ServiceAuthorization, cp as ServiceOutputContext, cq as ServiceOutputDecorator, cv as StandardSchemaFailure, cw as StandardSchemaInferOutput, cx as StandardSchemaIssue, cy as StandardSchemaPathSegment, cz as StandardSchemaResult, cA as StandardSchemaSuccess, cB as StandardSchemaV1, cE as SubOperationAccess, cI as SubRouteGuardOptions, cL as SubdocumentCreateAuthorization, cN as SubdocumentCreateOptions, cO as SubdocumentCreateVisibilityAuthorization, cP as SubdocumentDeleteAuthorization, cQ as SubdocumentDeleteOptions, cR as SubdocumentGateAuthorization, cT as SubdocumentInputAuthorization, cU as SubdocumentListOptions, cV as SubdocumentModel, cW as SubdocumentMutationAuthorization, cX as SubdocumentName, cY as SubdocumentOutputAuthorization, c$ as SubdocumentReadAuthorization, d0 as SubdocumentReadOptions, d2 as SubdocumentUpdateOptions, d3 as SubdocumentVirtuals, d4 as SubdocumentVisibilityAuthorization, d5 as SuperstructFailureLike, d6 as SuperstructValidateLike, dj as ValibotIssueLike, dk as ValibotPathItemLike, dl as ValibotSafeParseLike, dm as ValibotSafeParseResult, ds as VineValidationErrorLike, dt as VineValidationMessageLike, du as VineValidatorLike, dv as VirtualSubModel, dw as WithVirtuals, dx as YupSchemaLike, dy as YupValidationErrorLike, e2 as defaultRuntime, dz as defineRequestSchema, dA as fromAjv, dB as fromArkType, dC as fromIoTs, dD as fromJoi, dE as fromStandardSchema, dF as fromSuperstruct, dG as fromValibot, dH as fromVine, dI as fromYup, dJ as fromZod } from './parsers-ZSrF7SNu.mjs';
 import JsonRouter from '@web-ts-toolkit/express-json-router';
 import 'zod';
 
@@ -125,6 +125,12 @@ declare class ModelRouter<TModel = unknown, TVirtuals extends object = Record<ne
     constructor(modelName: string, initialOptions: ModelRouterOptions<TModel, TVirtuals>, runtime?: AccessRuntime);
     static fromModel<TModel, TVirtuals extends object = Record<never, never>>(model: mongoose.Model<TModel>, initialOptions: ModelRouterOptions<TModel, TVirtuals>, runtime?: AccessRuntime): ModelRouter<TModel, TVirtuals>;
     private getRequestSchema;
+    /**
+     * Acquire the model-generic internal service after this runtime's middleware
+     * initializes req.macl. Supply trusted per-call authorization in service options;
+     * selection/query args stay separate. Successful results carry opaque document
+     * handles in context(s), never data. Use getPublicService for request-only wrappers.
+     */
     getService(req: ModelRequest): Service<TModel, TVirtuals>;
     getPublicService(req: ModelRequest): PublicService<TModel, TVirtuals>;
     private assertAllowed;
@@ -443,9 +449,22 @@ declare const getDefaultModelOptions: () => DefaultModelRouterOptions<unknown>;
 declare const getDefaultModelOption: <K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]) => ExtendedDefaultModelRouterOptions<unknown>[K];
 
 interface Options {
+    /** Hydrated-document getter alias; defaults to `permissions`. */
     virtualPermissionField?: string;
+    /** Registered model whose documentPermissionField setting supplies the metadata slot. */
     modelName: string;
 }
+/**
+ * Optional Mongoose getter alias for existing document permission metadata. Defaults
+ * to `doc.permissions`, reading `_doc[documentPermissionField]` (usually `_permissions`).
+ * Option lookup uses the active runtime, or the default runtime outside managed execution.
+ * This plugin neither computes grants nor enables field enforcement: routers/services
+ * already enforce operationAccess and permissionSchema without it. It is separate from
+ * the package's computed `virtuals` output API. Finalized rows already get their
+ * own non-enumerable `permissions` alias from exposed metadata in both modes without
+ * this plugin. virtualPermissionField only names this raw getter; its literal _doc
+ * lookup does not traverse dotted metadata paths.
+ */
 declare function permissionsPlugin(schema: Schema, options: Options): void;
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -471,24 +490,49 @@ interface OpLogContext {
 }
 
 type CreateRouter = {
+    /**
+     * Create a model CRUD router and register this exact Mongoose model/connection
+     * with the owning runtime. Configure operationAccess and permissionSchema, then
+     * mount the returned `.routes` in Express after express.json(). Route middleware
+     * initializes req.macl; field enforcement does not require permissionsPlugin.
+     */
     <TModel, TVirtuals extends object = Record<never, never>>(model: mongoose.Model<TModel>, options: ModelRouterOptions<TModel, TVirtuals>): ModelRouter<TModel, TVirtuals>;
+    /**
+     * Create a router for an already-registered model name. Isolated runtimes require
+     * registerModelInstance(name, model) first; default acl also adopts mongoose.model(name).
+     * Prefer the model-instance overload for explicit connection ownership.
+     */
     <TModel, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): ModelRouter<TModel, TVirtuals>;
+    /** Create an ordered root batch endpoint for this runtime's targets; mount `.routes`. */
     (options: RootRouterOptions): RootRouter;
 };
 type CreateDataRouter = {
+    /**
+     * Create request-only list/read routes over an owned in-memory dataset. Set
+     * operationAccess, permissionSchema, idParam and idField explicitly. Mount `.routes`;
+     * middleware initializes req.dacl. No MongoDB connection or model defaults are used.
+     * Data replacement affects new services; existing services keep their captured version.
+     */
     <TData>(dataName: string, options: DataRouterOptions<TData>): DataRouter<TData>;
 };
+/** Runtime-bound OpenAPI factory; returns an Express router mounted directly with app.use(). */
 type CreateRuntimeOpenApiRouter = (options?: OpenApiRouterOptions) => Router;
 type WttSet = {
+    /** Set one global option on this API's runtime, not a model option or method default. */
     <K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
+    /** Shallowly replace supplied global option values; equivalent to setGlobalOptions(options). */
     (options: {
         [K in keyof GlobalOptions]: GlobalOptions[K];
     }): void;
 };
 interface Wtt {
+    /** Owning options/model/OpenAPI registry; also exposes data and exact option getters/setters. */
     runtime: AccessRuntime;
+    /** Model instance/name + options creates CRUD routes; a single options object creates a root batch. */
     createRouter: CreateRouter;
+    /** Owned in-memory list/read router; no model-default or backend field-grant layer. */
     createDataRouter: CreateDataRouter;
+    /** This runtime's OpenAPI/Swagger UI router. Unlike the standalone export, takes only options. */
     createOpenApiRouter: CreateRuntimeOpenApiRouter;
     combineRoutes: typeof combineRoutes;
     set: WttSet;
@@ -513,8 +557,50 @@ interface Wtt {
     ModelRouter: typeof ModelRouter;
     DataRouter: typeof DataRouter;
 }
+/**
+ * Callable runtime-bound facade returned by createAccessRuntime (also the type of acl).
+ * Calling api() creates model request middleware for custom routes; generated `.routes`
+ * already initialize their own model/data cores. api.runtime is the AccessRuntime owner.
+ * Configuration methods on this facade remain bound to that owner.
+ */
 type AccessRuntimeApi = typeof macl & Wtt;
+/**
+ * Create an isolated Express/Mongoose router API with its own options, model registry,
+ * OpenAPI registry and request-owned work pools. Requires Node >=22, Express >=5 and
+ * Mongoose >=8. Pass a Mongoose model instance to createRouter, or register it before
+ * using a string name; isolated runtimes do not fall back to global mongoose.models.
+ *
+ * The returned callable facade exposes factories/setters; `.runtime` is its owner.
+ * Mount generated `.routes` after express.json(); connect MongoDB before listening.
+ * Model operations default to denied until operationAccess is configured, and field
+ * visibility requires permissionSchema. permissionsPlugin is only an optional raw-document alias.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import mongoose from 'mongoose';
+ * import { createAccessRuntime } from '@web-ts-toolkit/access-router';
+ * const api = createAccessRuntime();
+ * const Product = mongoose.model('Product', new mongoose.Schema({ name: String }));
+ * const products = api.createRouter(Product, {
+ *   basePath: '/products',
+ *   operationAccess: { list: true, read: true },
+ *   permissionSchema: { name: true },
+ * });
+ * const app = express();
+ * app.use(express.json());
+ * app.use(products.routes);
+ * // Await mongoose.connect(uri) before app.listen(port).
+ * ```
+ * @returns A fresh AccessRuntimeApi. See the shipped README's Configuration layers.
+ */
 declare function createAccessRuntime(): AccessRuntimeApi;
+/**
+ * Shared default-runtime API. Canonical import: `import acl from '@web-ts-toolkit/access-router'`;
+ * named `{ acl }` is identical. CommonJS uses `require('@web-ts-toolkit/access-router').acl`.
+ * Use createAccessRuntime() for an isolated registry/configuration. Mount factory `.routes`;
+ * calling acl() alone supplies model middleware for custom handlers.
+ */
 declare const acl: AccessRuntimeApi;
 
 export { AccessRuntime, type AccessRuntimeApi, type CombinedRouteInput, DataRouter, DataRouterOptions, DefaultModelRouterOptions, ExtendedDataRouterOptions, ExtendedDefaultModelRouterOptions, ExtendedModelRouterOptions, GlobalOptions, GuardHook, type GuardModelCondition, type GuardModelConditionID, ModelRouter, ModelRouterOptions, ModelVirtualDescriptor, ModelVirtualGetter, ModelVirtualLeaf, ModelVirtualRecordAccess, type OpLogContext, OpenApiCollisionError, OpenApiDocumentOptions, OpenApiRegistry, OpenApiRegistryOptions, OpenApiRouteDescriptor, OpenApiRouterOptions, RootRouter, RootRouterOptions, Validation, acl, combineRoutes, createAccessRuntime, createOpenApiRouter, acl as default, getDefaultModelOption, getDefaultModelOptions, getGlobalOption, getGlobalOptions, getModelInstance, getModelJsonSchema, getModelNames, getModelOption, getModelOptions, guard, hasModelInstance, isLevelEnabled, permissionsPlugin, redactFilter, redactPayload, registerModelInstance, safeStringify, setDefaultModelOption, setDefaultModelOptions, setGlobalOption, setGlobalOptions, setModelOption, setModelOptions };

package/index.d.ts

@@ -1,7 +1,7 @@
 import mongoose, { Schema } from 'mongoose';
 import { Response, NextFunction, RequestHandler, Router } from 'express';
-import { A as AccessRouterBaseRequest, aj as GuardHook, aI as ModelRequest, d8 as AccessRuntime, V as DataRouterOptions, T as DataRequest, d9 as DataService, a4 as ExtendedDataRouterOptions, a8 as Filter, b2 as Projection, c0 as Sort, a$ as Populate, aJ as ModelRouterOptions, da as Service, db as PublicService, aS as ModelVirtualRecordAccess, aO as ModelVirtualDescriptor, aQ as ModelVirtualGetter, aR as ModelVirtualLeaf, a6 as ExtendedModelRouterOptions, cL as Validation, bQ as RootRouterOptions, dc as OpenApiRouterOptions, dd as OpenApiRegistryOptions, de as OpenApiRouteDescriptor, df as OpenApiDocumentOptions, dg as OpenApiParameter, dh as OpenApiSchema, di as OpenApiResponses, ah as GlobalOptions, Z as DefaultModelRouterOptions, a5 as ExtendedDefaultModelRouterOptions } from './parsers-DhUuvj9B.js';
-export { dj as AccessRouterPermissionMap, dk as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, n as AjvValidatorLike, o as ArkTypeErrorsLike, p as ArkTypeLike, a7 as FieldOperationAccess, ai as GlobalPermissionValue, am as IoTsContextEntryLike, an as IoTsDecodeErrorLike, ao as IoTsDecoderLike, ap as JoiSchemaLike, aq as JoiValidationErrorDetailLike, aw as MaybePromise, ax as ModelBaseFilterHook, az as ModelDeleteHook, aA as ModelDocPermissionsHook, aC as ModelDocumentHook, aD as ModelHook, aF as ModelIdentifierHook, aG as ModelListHook, aH as ModelOverrideFilterHook, aK as ModelValidateHook, aL as ModelVirtualAccess, aM as ModelVirtualAccessRecord, aN as ModelVirtualContext, aP as ModelVirtualDoc, aT as ModelVirtuals, dl as OpenApiMethod, aU as OperationAccess, aX as PairedRouteAccess, a_ as PermissionSchema, dm as Permissions, bk as RequestSchemaAdapter, bl as RequestSchemaFailure, bm as RequestSchemaIssue, bn as RequestSchemaLike, bo as RequestSchemaOptions, bp as RequestSchemaResult, bq as RequestSchemaSuccess, br as RequestSchemaValidator, bT as RouteBaseAccess, bU as RouteGuardAccess, bV as RouteVariant, bW as RouteVariantAccess, c2 as StandardSchemaFailure, c3 as StandardSchemaInferOutput, c4 as StandardSchemaIssue, c5 as StandardSchemaPathSegment, c6 as StandardSchemaResult, c7 as StandardSchemaSuccess, c8 as StandardSchemaV1, cb as SubOperationAccess, cf as SubRouteGuardOptions, cr as SuperstructFailureLike, cs as SuperstructValidateLike, cF as ValibotIssueLike, cG as ValibotPathItemLike, cH as ValibotSafeParseLike, cI as ValibotSafeParseResult, cN as VineValidationErrorLike, cO as VineValidationMessageLike, cP as VineValidatorLike, cQ as VirtualSubModel, cR as WithVirtuals, cS as YupSchemaLike, cT as YupValidationErrorLike, dn as defaultRuntime, cU as defineRequestSchema, cV as fromAjv, cW as fromArkType, cX as fromIoTs, cY as fromJoi, cZ as fromStandardSchema, c_ as fromSuperstruct, c$ as fromValibot, d0 as fromVine, d1 as fromYup, d2 as fromZod } from './parsers-DhUuvj9B.js';
+import { A as AccessRouterBaseRequest, aq as GuardHook, aT as ModelRequest, dP as AccessRuntime, _ as DataRouterOptions, Y as DataRequest, dQ as DataService, aa as ExtendedDataRouterOptions, af as Filter, bm as Projection, ct as Sort, bi as Populate, aU as ModelRouterOptions, dR as Service, dS as PublicService, b1 as ModelVirtualRecordAccess, aZ as ModelVirtualDescriptor, a$ as ModelVirtualGetter, b0 as ModelVirtualLeaf, ac as ExtendedModelRouterOptions, dq as Validation, cd as RootRouterOptions, dT as OpenApiRouterOptions, dU as OpenApiRegistryOptions, dV as OpenApiRouteDescriptor, dW as OpenApiDocumentOptions, dX as OpenApiParameter, dY as OpenApiSchema, dZ as OpenApiResponses, ao as GlobalOptions, a2 as DefaultModelRouterOptions, ab as ExtendedDefaultModelRouterOptions } from './parsers-ZSrF7SNu.js';
+export { d_ as AccessRouterPermissionMap, d$ as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, n as AjvValidatorLike, o as AllowedOutputFieldOptions, p as ArkTypeErrorsLike, q as ArkTypeLike, s as AuthorizedListResult, t as AuthorizedSingleResult, H as CreateAuthorization, N as DataFieldOptions, a7 as DocumentAuthorization, ad as FieldAuthorization, ae as FieldOperationAccess, ap as GlobalPermissionValue, ar as HydrationMode, au as InputFieldAuthorization, av as InputFieldPath, aw as IoTsContextEntryLike, ax as IoTsDecodeErrorLike, ay as IoTsDecoderLike, az as JoiSchemaLike, aA as JoiValidationErrorDetailLike, aG as MaybePromise, aH as ModelBaseFilterHook, aJ as ModelDeleteHook, aK as ModelDocPermissionsHook, aM as ModelDocumentHook, aN as ModelHook, aP as ModelHydrationOptions, aQ as ModelIdentifierHook, aR as ModelListHook, aS as ModelOverrideFilterHook, aV as ModelValidateHook, aW as ModelVirtualAccess, aX as ModelVirtualAccessRecord, aY as ModelVirtualContext, a_ as ModelVirtualDoc, b2 as ModelVirtuals, b3 as MutationAuthorization, b4 as NewArgs, b5 as NewOptions, e0 as OpenApiMethod, b6 as OperationAccess, b7 as OperationAuthorization, b8 as OutputAuthorization, b9 as OutputFieldOptions, ba as OutputFieldPath, bb as OutputPlanningOptions, be as PairedRouteAccess, bh as PermissionSchema, e1 as Permissions, bk as PopulatePlanningOptions, by as PublicSubdocumentCreateOptions, bz as PublicSubdocumentListOptions, bA as PublicSubdocumentMutationOptions, bB as PublicSubdocumentReadOptions, bH as RelatedAuthorization, bJ as RequestSchemaAdapter, bK as RequestSchemaFailure, bL as RequestSchemaIssue, bM as RequestSchemaLike, bN as RequestSchemaOptions, bO as RequestSchemaResult, bP as RequestSchemaSuccess, bQ as RequestSchemaValidator, cg as RouteBaseAccess, ch as RouteGuardAccess, ci as RouteVariant, cj as RouteVariantAccess, ck as RowAuthorization, co as ServiceAuthorization, cp as ServiceOutputContext, cq as ServiceOutputDecorator, cv as StandardSchemaFailure, cw as StandardSchemaInferOutput, cx as StandardSchemaIssue, cy as StandardSchemaPathSegment, cz as StandardSchemaResult, cA as StandardSchemaSuccess, cB as StandardSchemaV1, cE as SubOperationAccess, cI as SubRouteGuardOptions, cL as SubdocumentCreateAuthorization, cN as SubdocumentCreateOptions, cO as SubdocumentCreateVisibilityAuthorization, cP as SubdocumentDeleteAuthorization, cQ as SubdocumentDeleteOptions, cR as SubdocumentGateAuthorization, cT as SubdocumentInputAuthorization, cU as SubdocumentListOptions, cV as SubdocumentModel, cW as SubdocumentMutationAuthorization, cX as SubdocumentName, cY as SubdocumentOutputAuthorization, c$ as SubdocumentReadAuthorization, d0 as SubdocumentReadOptions, d2 as SubdocumentUpdateOptions, d3 as SubdocumentVirtuals, d4 as SubdocumentVisibilityAuthorization, d5 as SuperstructFailureLike, d6 as SuperstructValidateLike, dj as ValibotIssueLike, dk as ValibotPathItemLike, dl as ValibotSafeParseLike, dm as ValibotSafeParseResult, ds as VineValidationErrorLike, dt as VineValidationMessageLike, du as VineValidatorLike, dv as VirtualSubModel, dw as WithVirtuals, dx as YupSchemaLike, dy as YupValidationErrorLike, e2 as defaultRuntime, dz as defineRequestSchema, dA as fromAjv, dB as fromArkType, dC as fromIoTs, dD as fromJoi, dE as fromStandardSchema, dF as fromSuperstruct, dG as fromValibot, dH as fromVine, dI as fromYup, dJ as fromZod } from './parsers-ZSrF7SNu.js';
 import JsonRouter from '@web-ts-toolkit/express-json-router';
 import 'zod';
 
@@ -125,6 +125,12 @@ declare class ModelRouter<TModel = unknown, TVirtuals extends object = Record<ne
     constructor(modelName: string, initialOptions: ModelRouterOptions<TModel, TVirtuals>, runtime?: AccessRuntime);
     static fromModel<TModel, TVirtuals extends object = Record<never, never>>(model: mongoose.Model<TModel>, initialOptions: ModelRouterOptions<TModel, TVirtuals>, runtime?: AccessRuntime): ModelRouter<TModel, TVirtuals>;
     private getRequestSchema;
+    /**
+     * Acquire the model-generic internal service after this runtime's middleware
+     * initializes req.macl. Supply trusted per-call authorization in service options;
+     * selection/query args stay separate. Successful results carry opaque document
+     * handles in context(s), never data. Use getPublicService for request-only wrappers.
+     */
     getService(req: ModelRequest): Service<TModel, TVirtuals>;
     getPublicService(req: ModelRequest): PublicService<TModel, TVirtuals>;
     private assertAllowed;
@@ -443,9 +449,22 @@ declare const getDefaultModelOptions: () => DefaultModelRouterOptions<unknown>;
 declare const getDefaultModelOption: <K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]) => ExtendedDefaultModelRouterOptions<unknown>[K];
 
 interface Options {
+    /** Hydrated-document getter alias; defaults to `permissions`. */
     virtualPermissionField?: string;
+    /** Registered model whose documentPermissionField setting supplies the metadata slot. */
     modelName: string;
 }
+/**
+ * Optional Mongoose getter alias for existing document permission metadata. Defaults
+ * to `doc.permissions`, reading `_doc[documentPermissionField]` (usually `_permissions`).
+ * Option lookup uses the active runtime, or the default runtime outside managed execution.
+ * This plugin neither computes grants nor enables field enforcement: routers/services
+ * already enforce operationAccess and permissionSchema without it. It is separate from
+ * the package's computed `virtuals` output API. Finalized rows already get their
+ * own non-enumerable `permissions` alias from exposed metadata in both modes without
+ * this plugin. virtualPermissionField only names this raw getter; its literal _doc
+ * lookup does not traverse dotted metadata paths.
+ */
 declare function permissionsPlugin(schema: Schema, options: Options): void;
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -471,24 +490,49 @@ interface OpLogContext {
 }
 
 type CreateRouter = {
+    /**
+     * Create a model CRUD router and register this exact Mongoose model/connection
+     * with the owning runtime. Configure operationAccess and permissionSchema, then
+     * mount the returned `.routes` in Express after express.json(). Route middleware
+     * initializes req.macl; field enforcement does not require permissionsPlugin.
+     */
     <TModel, TVirtuals extends object = Record<never, never>>(model: mongoose.Model<TModel>, options: ModelRouterOptions<TModel, TVirtuals>): ModelRouter<TModel, TVirtuals>;
+    /**
+     * Create a router for an already-registered model name. Isolated runtimes require
+     * registerModelInstance(name, model) first; default acl also adopts mongoose.model(name).
+     * Prefer the model-instance overload for explicit connection ownership.
+     */
     <TModel, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): ModelRouter<TModel, TVirtuals>;
+    /** Create an ordered root batch endpoint for this runtime's targets; mount `.routes`. */
     (options: RootRouterOptions): RootRouter;
 };
 type CreateDataRouter = {
+    /**
+     * Create request-only list/read routes over an owned in-memory dataset. Set
+     * operationAccess, permissionSchema, idParam and idField explicitly. Mount `.routes`;
+     * middleware initializes req.dacl. No MongoDB connection or model defaults are used.
+     * Data replacement affects new services; existing services keep their captured version.
+     */
     <TData>(dataName: string, options: DataRouterOptions<TData>): DataRouter<TData>;
 };
+/** Runtime-bound OpenAPI factory; returns an Express router mounted directly with app.use(). */
 type CreateRuntimeOpenApiRouter = (options?: OpenApiRouterOptions) => Router;
 type WttSet = {
+    /** Set one global option on this API's runtime, not a model option or method default. */
     <K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
+    /** Shallowly replace supplied global option values; equivalent to setGlobalOptions(options). */
     (options: {
         [K in keyof GlobalOptions]: GlobalOptions[K];
     }): void;
 };
 interface Wtt {
+    /** Owning options/model/OpenAPI registry; also exposes data and exact option getters/setters. */
     runtime: AccessRuntime;
+    /** Model instance/name + options creates CRUD routes; a single options object creates a root batch. */
     createRouter: CreateRouter;
+    /** Owned in-memory list/read router; no model-default or backend field-grant layer. */
     createDataRouter: CreateDataRouter;
+    /** This runtime's OpenAPI/Swagger UI router. Unlike the standalone export, takes only options. */
     createOpenApiRouter: CreateRuntimeOpenApiRouter;
     combineRoutes: typeof combineRoutes;
     set: WttSet;
@@ -513,8 +557,50 @@ interface Wtt {
     ModelRouter: typeof ModelRouter;
     DataRouter: typeof DataRouter;
 }
+/**
+ * Callable runtime-bound facade returned by createAccessRuntime (also the type of acl).
+ * Calling api() creates model request middleware for custom routes; generated `.routes`
+ * already initialize their own model/data cores. api.runtime is the AccessRuntime owner.
+ * Configuration methods on this facade remain bound to that owner.
+ */
 type AccessRuntimeApi = typeof macl & Wtt;
+/**
+ * Create an isolated Express/Mongoose router API with its own options, model registry,
+ * OpenAPI registry and request-owned work pools. Requires Node >=22, Express >=5 and
+ * Mongoose >=8. Pass a Mongoose model instance to createRouter, or register it before
+ * using a string name; isolated runtimes do not fall back to global mongoose.models.
+ *
+ * The returned callable facade exposes factories/setters; `.runtime` is its owner.
+ * Mount generated `.routes` after express.json(); connect MongoDB before listening.
+ * Model operations default to denied until operationAccess is configured, and field
+ * visibility requires permissionSchema. permissionsPlugin is only an optional raw-document alias.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import mongoose from 'mongoose';
+ * import { createAccessRuntime } from '@web-ts-toolkit/access-router';
+ * const api = createAccessRuntime();
+ * const Product = mongoose.model('Product', new mongoose.Schema({ name: String }));
+ * const products = api.createRouter(Product, {
+ *   basePath: '/products',
+ *   operationAccess: { list: true, read: true },
+ *   permissionSchema: { name: true },
+ * });
+ * const app = express();
+ * app.use(express.json());
+ * app.use(products.routes);
+ * // Await mongoose.connect(uri) before app.listen(port).
+ * ```
+ * @returns A fresh AccessRuntimeApi. See the shipped README's Configuration layers.
+ */
 declare function createAccessRuntime(): AccessRuntimeApi;
+/**
+ * Shared default-runtime API. Canonical import: `import acl from '@web-ts-toolkit/access-router'`;
+ * named `{ acl }` is identical. CommonJS uses `require('@web-ts-toolkit/access-router').acl`.
+ * Use createAccessRuntime() for an isolated registry/configuration. Mount factory `.routes`;
+ * calling acl() alone supplies model middleware for custom handlers.
+ */
 declare const acl: AccessRuntimeApi;
 
 export { AccessRuntime, type AccessRuntimeApi, type CombinedRouteInput, DataRouter, DataRouterOptions, DefaultModelRouterOptions, ExtendedDataRouterOptions, ExtendedDefaultModelRouterOptions, ExtendedModelRouterOptions, GlobalOptions, GuardHook, type GuardModelCondition, type GuardModelConditionID, ModelRouter, ModelRouterOptions, ModelVirtualDescriptor, ModelVirtualGetter, ModelVirtualLeaf, ModelVirtualRecordAccess, type OpLogContext, OpenApiCollisionError, OpenApiDocumentOptions, OpenApiRegistry, OpenApiRegistryOptions, OpenApiRouteDescriptor, OpenApiRouterOptions, RootRouter, RootRouterOptions, Validation, acl, combineRoutes, createAccessRuntime, createOpenApiRouter, acl as default, getDefaultModelOption, getDefaultModelOptions, getGlobalOption, getGlobalOptions, getModelInstance, getModelJsonSchema, getModelNames, getModelOption, getModelOptions, guard, hasModelInstance, isLevelEnabled, permissionsPlugin, redactFilter, redactPayload, registerModelInstance, safeStringify, setDefaultModelOption, setDefaultModelOptions, setGlobalOption, setGlobalOptions, setModelOption, setModelOptions };