@web-ts-toolkit/access-router 0.61.0 → 0.62.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +320 -56
- package/advanced.d.mts +1 -1
- package/advanced.d.ts +1 -1
- package/advanced.js +253 -129
- package/advanced.mjs +253 -129
- package/index.d.mts +25 -17
- package/index.d.ts +25 -17
- package/index.js +724 -412
- package/index.mjs +667 -355
- package/llms.txt +4 -2
- package/package.json +3 -3
- package/{parsers-DFZ_6fGl.d.mts → parsers-Bdq0jg69.d.mts} +197 -79
- package/{parsers-DFZ_6fGl.d.ts → parsers-Bdq0jg69.d.ts} +197 -79
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
|
-
import
|
|
2
|
+
import * as mongoose from 'mongoose';
|
|
3
|
+
import mongoose__default, { Model, Schema } from 'mongoose';
|
|
3
4
|
import express from 'express';
|
|
4
5
|
|
|
5
6
|
interface BooleanObject {
|
|
@@ -168,7 +169,7 @@ type WithDefaultId<T> = T extends object ? T & {
|
|
|
168
169
|
*/
|
|
169
170
|
type WithVirtuals<TModel, TVirtuals extends object = Record<never, never>> = TModel & Partial<TVirtuals>;
|
|
170
171
|
type PublicOutput<T, TVirtuals extends object = Record<never, never>> = WithVirtuals<T, TVirtuals> extends object ? WithVirtuals<T, TVirtuals> & Record<string, unknown> : Record<string, unknown>;
|
|
171
|
-
type ModelDocument<TModel = unknown> =
|
|
172
|
+
type ModelDocument<TModel = unknown> = mongoose__default.Document & TModel;
|
|
172
173
|
type TrimLeft<S extends string> = S extends ` ${infer Rest}` ? TrimLeft<Rest> : S;
|
|
173
174
|
type TrimRight<S extends string> = S extends `${infer Rest} ` ? TrimRight<Rest> : S;
|
|
174
175
|
type Trim<S extends string> = TrimLeft<TrimRight<S>>;
|
|
@@ -324,6 +325,21 @@ type CorrelatedInclude = CorrelatedReadByIdInclude | CorrelatedReadByFilterInclu
|
|
|
324
325
|
type Include = LegacyInclude | CorrelatedInclude;
|
|
325
326
|
type FindAccess = 'list' | 'read';
|
|
326
327
|
type PopulateAccess = 'list' | 'read';
|
|
328
|
+
/**
|
|
329
|
+
* Ordinary public population intent, not model/authorization configuration.
|
|
330
|
+
* Static string refs resolve on the source model's connection and must match the
|
|
331
|
+
* exact target registered/configured in the owning runtime with an effective object
|
|
332
|
+
* permissionSchema. Explicit Model-valued schema refs can cross connections when
|
|
333
|
+
* that exact instance is configured in the same runtime. Missing/mismatched targets
|
|
334
|
+
* fail before target I/O or initiating writes; the validated model is pinned in flight.
|
|
335
|
+
* Dynamic callback/refPath refs cannot be statically bound before I/O and reject
|
|
336
|
+
* with a controlled configuration diagnostic.
|
|
337
|
+
* The actual target's requireOperationAccessForPopulateQueries controls only operation
|
|
338
|
+
* admission. Fields, document grants, rows, original selection, match and reference IDs
|
|
339
|
+
* remain enforced; direct/root target guards stay independent. Callers cannot supply
|
|
340
|
+
* a model or either populate policy flag here. Private dependsOnPopulate declarations
|
|
341
|
+
* have a narrower one-hop static-string ObjectId/same-connection contract.
|
|
342
|
+
*/
|
|
327
343
|
interface Populate {
|
|
328
344
|
path: string;
|
|
329
345
|
select?: Projection;
|
|
@@ -420,8 +436,10 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
|
|
|
420
436
|
* and traversal through target refs are rejected. `_id` is included unless excluded.
|
|
421
437
|
* Static string refs must bind the actual same-connection ObjectId model; register
|
|
422
438
|
* its model instance AND options first. Validation is eager/atomic, including setters.
|
|
439
|
+
* Model-valued/cross-connection refs supported by ordinary population are outside
|
|
440
|
+
* this private declaration's static-string, same-connection limit.
|
|
423
441
|
* This bypasses source/target input-field permissions, not the virtual's own output
|
|
424
|
-
* authorization.
|
|
442
|
+
* authorization. The target model's requireOperationAccessForPopulateDependencies defaults
|
|
425
443
|
* to true, requiring the captured caller's target base operationAccess.read for private
|
|
426
444
|
* loading. Only literal false bypasses that gate; private-only loading then adds no
|
|
427
445
|
* operation check solely for the fetch. Target overrideFilter.read/baseFilter.read and
|
|
@@ -432,9 +450,11 @@ type ModelVirtualDoc<TModel = unknown> = IsUnknownVirtual<TModel> extends true ?
|
|
|
432
450
|
* admitted ordinary population owns the slot (then its original public mask/miss applies).
|
|
433
451
|
* Strict private denial, row/query/getter failure and deferred virtual denial cannot hide
|
|
434
452
|
* permitted IDs. Only source unselection/field denial omits them; there is no extra target
|
|
435
|
-
* base-read visibility gate.
|
|
436
|
-
* independently controls ordinary target operation admission.
|
|
437
|
-
*
|
|
453
|
+
* base-read visibility gate. The target model's requireOperationAccessForPopulateQueries
|
|
454
|
+
* independently controls ordinary target operation admission. Each target resolves its
|
|
455
|
+
* override → captured runtime model default → true; undefined restores inheritance.
|
|
456
|
+
* Source flags do not propagate: Document's private User ref uses User's dependency flag.
|
|
457
|
+
* Both flags and source/target policy are captured before awaits; registration and an effective object permissionSchema
|
|
438
458
|
* remain mandatory. Private inputs never implicitly enter hooks, handles or metadata.
|
|
439
459
|
*/
|
|
440
460
|
interface ModelVirtualPopulateDependency<TModel = unknown> {
|
|
@@ -645,6 +665,8 @@ declare class AccessRuntime {
|
|
|
645
665
|
private readonly globalOptions;
|
|
646
666
|
private readonly defaultModelOptions;
|
|
647
667
|
private readonly modelOptions;
|
|
668
|
+
private readonly modelOptionOverrides;
|
|
669
|
+
private pendingSnapshotWarnings?;
|
|
648
670
|
private readonly modelJsonSchemas;
|
|
649
671
|
private readonly dataOptions;
|
|
650
672
|
private readonly modelRefs;
|
|
@@ -653,9 +675,9 @@ declare class AccessRuntime {
|
|
|
653
675
|
private readonly modelInstances;
|
|
654
676
|
private readonly openApiRegistry;
|
|
655
677
|
private openApiPathPrefix;
|
|
656
|
-
registerModelInstance<TModel>(modelName: string, model:
|
|
678
|
+
registerModelInstance<TModel>(modelName: string, model: mongoose__default.Model<TModel>): void;
|
|
657
679
|
hasModelInstance(modelName: string): boolean;
|
|
658
|
-
getModelInstance<TModel = unknown>(modelName: string):
|
|
680
|
+
getModelInstance<TModel = unknown>(modelName: string): mongoose__default.Model<TModel> | null;
|
|
659
681
|
registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
|
|
660
682
|
/**
|
|
661
683
|
* Compose OpenAPI paths while synchronously constructing mounted routers.
|
|
@@ -699,8 +721,9 @@ declare class AccessRuntime {
|
|
|
699
721
|
globalOptions: GlobalOptions;
|
|
700
722
|
defaultModelOptions: DefaultModelRouterOptions;
|
|
701
723
|
modelOptions: Record<string, ModelRouterOptions>;
|
|
724
|
+
modelOptionOverrides: Record<string, ModelRouterOptions>;
|
|
702
725
|
dataOptions: Record<string, DataRouterOptions>;
|
|
703
|
-
modelInstances: Record<string,
|
|
726
|
+
modelInstances: Record<string, mongoose__default.Model<unknown>>;
|
|
704
727
|
modelJsonSchemas: Record<string, Record<string, unknown>>;
|
|
705
728
|
modelRefs: Record<string, ModelReferenceMap>;
|
|
706
729
|
modelSubs: Record<string, string[]>;
|
|
@@ -716,15 +739,22 @@ declare class AccessRuntime {
|
|
|
716
739
|
setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
|
|
717
740
|
getGlobalOptions(): GlobalOptions;
|
|
718
741
|
getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
|
|
719
|
-
/** Update model
|
|
742
|
+
/** Update inherited model defaults shallowly. Explicit model values and captured calls are unchanged. */
|
|
720
743
|
setDefaultModelOptions(options: DefaultModelRouterOptions): void;
|
|
721
744
|
setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
|
|
722
745
|
getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
|
|
723
746
|
getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
|
|
747
|
+
private resolveModelOptions;
|
|
748
|
+
private validateModelOptions;
|
|
749
|
+
private publishDefaultModelOptions;
|
|
750
|
+
private warnSnapshotFlag;
|
|
751
|
+
private deferSnapshotWarnings;
|
|
752
|
+
private initialOutputCopyModes;
|
|
724
753
|
private createModelOptions;
|
|
725
754
|
private getOrCreateModelOptions;
|
|
726
755
|
/**
|
|
727
|
-
*
|
|
756
|
+
* Update explicit model overrides shallowly; undefined restores default inheritance
|
|
757
|
+
* (operationAccess preserves its existing exact-key-only default fallback). A supplied
|
|
728
758
|
* operationAccess/defaults object replaces that whole value. Defaults accept only
|
|
729
759
|
* query/presentation settings; virtual configuration is validated before assignment.
|
|
730
760
|
* Existing router.options remains its construction-time snapshot. Fresh model-service
|
|
@@ -732,7 +762,7 @@ declare class AccessRuntime {
|
|
|
732
762
|
*/
|
|
733
763
|
setModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, options: ModelRouterOptions<TModel, TVirtuals>): void;
|
|
734
764
|
setModelOption<K extends keyof ExtendedModelRouterOptions<TModel, TVirtuals>, TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel, TVirtuals>[K]): void;
|
|
735
|
-
/** Frozen
|
|
765
|
+
/** Frozen model/default snapshot; populate flags remain raw overrides. Read again for current values. */
|
|
736
766
|
getModelOptions<TModel = unknown, TVirtuals extends object = Record<never, never>>(modelName: string): ModelRouterOptions<TModel, TVirtuals>;
|
|
737
767
|
/**
|
|
738
768
|
* Generic stored exact → parent.default → parent lookup; only undefined falls through.
|
|
@@ -1031,6 +1061,12 @@ declare const documentAuthorizationBrand: unique symbol;
|
|
|
1031
1061
|
* unsafeSkipListNestedDocumentSnapshotChecks / unsafeSkipReadNestedDocumentSnapshotChecks
|
|
1032
1062
|
* retain weakened source checks on query descendants, using the initiating model's
|
|
1033
1063
|
* mode. In-place value mutations can therefore reuse stale grants/decisions.
|
|
1064
|
+
* unsafeSkipListInitialOutputSnapshotCopy / unsafeSkipReadInitialOutputSnapshotCopy
|
|
1065
|
+
* additionally omit eligible initial output snapshots only when the corresponding
|
|
1066
|
+
* output-value comparison skip is enabled. They retain bounded structural admission
|
|
1067
|
+
* and exact graph ownership, but omit this pass's native/BSON normalization and
|
|
1068
|
+
* validation observations. Source/callback/grant copies remain detached; unproven
|
|
1069
|
+
* graphs or open ownership bindings fall back to copying. Retained handles keep this mode.
|
|
1034
1070
|
*/
|
|
1035
1071
|
interface DocumentAuthorization {
|
|
1036
1072
|
readonly [documentAuthorizationBrand]: true;
|
|
@@ -1104,6 +1140,11 @@ type AllowedOutputFieldOptions<TModel = unknown, TVirtuals extends object = Reco
|
|
|
1104
1140
|
readonly purpose: 'output';
|
|
1105
1141
|
};
|
|
1106
1142
|
|
|
1143
|
+
/** Package-private model-default capture. Never use a source model's resolved flags as defaults. */
|
|
1144
|
+
|
|
1145
|
+
/** Function identity survives authorization snapshot copying, retaining one owner capture. */
|
|
1146
|
+
type PopulatePolicyDefaultsToken = () => void;
|
|
1147
|
+
|
|
1107
1148
|
/** Package-private D2 validation/capture. Terminal persisted inputs, never output grants or target I/O. */
|
|
1108
1149
|
|
|
1109
1150
|
interface VirtualPopulateTarget {
|
|
@@ -1171,11 +1212,15 @@ interface AuthorizationConfiguration {
|
|
|
1171
1212
|
readonly unsafeSkipReadOutputSnapshotChecks?: boolean;
|
|
1172
1213
|
readonly unsafeSkipListNestedDocumentSnapshotChecks?: boolean;
|
|
1173
1214
|
readonly unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
|
|
1215
|
+
readonly unsafeSkipListInitialOutputSnapshotCopy?: boolean;
|
|
1216
|
+
readonly unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
|
|
1174
1217
|
/** Opaque terminal private-input capture. Never related authority or public document metadata. */
|
|
1175
1218
|
readonly virtualPopulateSnapshot?: VirtualPopulateSnapshotToken;
|
|
1176
|
-
/**
|
|
1219
|
+
/** Held runtime model defaults, distinct from this model's resolved flags. */
|
|
1220
|
+
readonly populatePolicyDefaults?: PopulatePolicyDefaultsToken;
|
|
1221
|
+
/** Target-owned private input admission mode, not public output/related authority. */
|
|
1177
1222
|
readonly requireOperationAccessForPopulateDependencies?: boolean;
|
|
1178
|
-
/** Independent ordinary-populate operation admission
|
|
1223
|
+
/** Independent target-owned ordinary-populate operation admission. */
|
|
1179
1224
|
readonly requireOperationAccessForPopulateQueries?: boolean;
|
|
1180
1225
|
readonly documentPermissionField?: string;
|
|
1181
1226
|
/** Captured permission schema, virtual descriptors, always-select and metadata posture. */
|
|
@@ -1186,6 +1231,8 @@ interface AuthorizationRelatedTarget {
|
|
|
1186
1231
|
readonly path: string;
|
|
1187
1232
|
readonly modelName: string;
|
|
1188
1233
|
readonly configuration: AuthorizationConfiguration;
|
|
1234
|
+
/** Actual source-ref target or include receiver, captured with this runtime's configuration. */
|
|
1235
|
+
readonly model?: mongoose.Model<unknown>;
|
|
1189
1236
|
/** Effective include args/options, resolved with that target's captured defaults. */
|
|
1190
1237
|
readonly queryIntent?: ModelServiceIntent;
|
|
1191
1238
|
/** Existing include operation gate, resolved synchronously with its target. */
|
|
@@ -2341,7 +2388,7 @@ interface Change {
|
|
|
2341
2388
|
}
|
|
2342
2389
|
interface ModelHookContext {
|
|
2343
2390
|
modelName: string;
|
|
2344
|
-
mongooseModel:
|
|
2391
|
+
mongooseModel: mongoose__default.Model<unknown>;
|
|
2345
2392
|
operation?: string;
|
|
2346
2393
|
originalDocumentSnapshot?: Record<string, unknown>;
|
|
2347
2394
|
finalDocumentSnapshot?: Record<string, unknown>;
|
|
@@ -3149,9 +3196,12 @@ interface AccessRouterLogger {
|
|
|
3149
3196
|
isLevelEnabled?: (level: string) => boolean;
|
|
3150
3197
|
}
|
|
3151
3198
|
/**
|
|
3152
|
-
* Runtime-wide request initialization
|
|
3199
|
+
* Runtime-wide request initialization and resource settings, configured with
|
|
3153
3200
|
* api.setGlobalOptions / api.setGlobalOption. These are not model options or wire
|
|
3154
3201
|
* options. Object assignment is shallow; nested requestComplexity replaces as a unit.
|
|
3202
|
+
* Populate operation flags belong to the actual target's ModelRouterOptions or
|
|
3203
|
+
* DefaultModelRouterOptions. Stale global setters (including api.set) reject them
|
|
3204
|
+
* with migration guidance to setModelOptions / setDefaultModelOptions.
|
|
3155
3205
|
*/
|
|
3156
3206
|
interface GlobalOptions {
|
|
3157
3207
|
/** Request grant-storage property (default `_permissions`), distinct from documentPermissionField. */
|
|
@@ -3165,57 +3215,6 @@ interface GlobalOptions {
|
|
|
3165
3215
|
* context. Generated routers do not authenticate client claims for this hook.
|
|
3166
3216
|
*/
|
|
3167
3217
|
globalPermissions?: (this: AccessRouterRequest, req: AccessRouterRequest) => MaybePromise<GlobalPermissionValue>;
|
|
3168
|
-
/**
|
|
3169
|
-
* Require the caller's effective target operation (`read`, supported `list` or trusted
|
|
3170
|
-
* custom access) for ordinary query population (default `true`). Only literal `false`
|
|
3171
|
-
* skips that admission gate; source entry/field authorization, target field/document
|
|
3172
|
-
* grants, row/base/transform policies, original selection, match and mandatory reference
|
|
3173
|
-
* IDs still constrain output. Denied population retains selected/permitted original
|
|
3174
|
-
* source IDs; admitted population misses return null/filtered arrays, not restored IDs.
|
|
3175
|
-
* Targets always require an actual Mongoose model and ACL configuration with an
|
|
3176
|
-
* effective object permissionSchema in this runtime; `{}` closes business fields.
|
|
3177
|
-
* Runtime-owned and captured before awaits, independently of private dependency
|
|
3178
|
-
* admission. A configuration-only Document needs no HTTP routes. Its denied direct/root
|
|
3179
|
-
* read/list operations stay denied. No per-model/query/client override.
|
|
3180
|
-
*/
|
|
3181
|
-
requireOperationAccessForPopulateQueries?: boolean;
|
|
3182
|
-
/**
|
|
3183
|
-
* Require the original caller's target base `operationAccess.read` before loading
|
|
3184
|
-
* declared private `dependsOnPopulate` inputs (default `true`). Only literal boolean
|
|
3185
|
-
* `false` bypasses that operation gate; undefined/malformed JS values normalize to
|
|
3186
|
-
* `true`. Source/target input-field permissions are already bypassed by the server
|
|
3187
|
-
* declaration; the virtual's own output authorization still applies. Target request-mode
|
|
3188
|
-
* `baseFilter.read`, `overrideFilter.read` and retained reference IDs always constrain rows.
|
|
3189
|
-
* Captured with source/target policy and query intent before the first await, including
|
|
3190
|
-
* nested output scopes. In-flight calls retain their mode; later calls see updates.
|
|
3191
|
-
* Runtime-isolated server configuration only: no caller/query or per-model override.
|
|
3192
|
-
*
|
|
3193
|
-
* Neither mode changes ordinary reference shape: selected/permitted parent fields keep
|
|
3194
|
-
* exact original IDs (including array order, duplicates, missing IDs and nulls) when no
|
|
3195
|
-
* admitted ordinary population owns them. Private denial, row/query/getter failure or
|
|
3196
|
-
* deferred virtual denial cannot hide those IDs. Omit only for parent unselection/field
|
|
3197
|
-
* denial; admitted public DTO/null/filtered-array results retain their original masks.
|
|
3198
|
-
* There is no additional target-base-read reference-visibility gate. False-mode loading
|
|
3199
|
-
* adds no operation check solely for its private fetch. Private fourth-argument inputs
|
|
3200
|
-
* never implicitly enter DTOs, hooks, handles, snapshots or permission metadata.
|
|
3201
|
-
* An actual registered model, effective object permissionSchema and static declarations
|
|
3202
|
-
* remain mandatory, independently of requireOperationAccessForPopulateQueries.
|
|
3203
|
-
*
|
|
3204
|
-
* @example
|
|
3205
|
-
* ```ts
|
|
3206
|
-
* import { createAccessRuntime, type GlobalOptions } from '@web-ts-toolkit/access-router';
|
|
3207
|
-
* const api = createAccessRuntime();
|
|
3208
|
-
* const policy = {
|
|
3209
|
-
* requireOperationAccessForPopulateQueries: true,
|
|
3210
|
-
* requireOperationAccessForPopulateDependencies: false,
|
|
3211
|
-
* } satisfies GlobalOptions;
|
|
3212
|
-
* api.setGlobalOptions(policy); // private computation; denied public population retains permitted IDs
|
|
3213
|
-
* const snapshot: GlobalOptions = api.getGlobalOptions();
|
|
3214
|
-
* api.setGlobalOption('requireOperationAccessForPopulateDependencies', true);
|
|
3215
|
-
* void snapshot; // stored snapshot; read again to observe the setter
|
|
3216
|
-
* ```
|
|
3217
|
-
*/
|
|
3218
|
-
requireOperationAccessForPopulateDependencies?: boolean;
|
|
3219
3218
|
logger?: AccessRouterLogger;
|
|
3220
3219
|
/** Request budgets and separate hook/persistence pools; concurrency limits are captured on first owner use. */
|
|
3221
3220
|
requestComplexity?: RequestComplexityOptions;
|
|
@@ -3346,8 +3345,9 @@ type HydrationMode = 'lean' | 'hydrated';
|
|
|
3346
3345
|
* Set through ModelRouterOptions/DefaultModelRouterOptions and their whole-record
|
|
3347
3346
|
* or exact hydration.<method> setters (including existing model/default decorators).
|
|
3348
3347
|
* A supplied record replaces the previous record shallowly; omitted/undefined
|
|
3349
|
-
* members use built-ins, not an older/default record. Whole-record undefined
|
|
3350
|
-
*
|
|
3348
|
+
* members use built-ins, not an older/default record. Whole-model-record undefined
|
|
3349
|
+
* restores default-model inheritance; default-record undefined clears that default.
|
|
3350
|
+
* Invalid records/keys/modes throw before publication. Fresh calls observe owner
|
|
3351
3351
|
* updates; in-flight calls retain their captured configuration.
|
|
3352
3352
|
* Includes stay fixed lean; raw parents/lifecycle stages stay hydrated; subdocument
|
|
3353
3353
|
* post-save visibility stays lean. Populate inherits its parent query; $$sq uses
|
|
@@ -3369,7 +3369,17 @@ interface ModelHydrationOptions {
|
|
|
3369
3369
|
/** Internal findById defaults to hydrated; does not inherit findOne's setting. */
|
|
3370
3370
|
findById?: HydrationMode;
|
|
3371
3371
|
}
|
|
3372
|
-
/**
|
|
3372
|
+
/**
|
|
3373
|
+
* Inherited model defaults; data/root routers do not inherit these. Unspecified model
|
|
3374
|
+
* options follow later default updates for new calls. Explicit values (including false,
|
|
3375
|
+
* null, empty objects/arrays) win; setting a model option to undefined restores inheritance.
|
|
3376
|
+
* Exception: explicitly cleared operationAccess retains its exact-key-only default fallback;
|
|
3377
|
+
* a runtime catch-all/default guard is not an exact fallback in that mode.
|
|
3378
|
+
* Nested objects replace shallowly. Existing calls/handles and router.options keep their
|
|
3379
|
+
* captured snapshots; changing defaults does not rebuild already-mounted route paths.
|
|
3380
|
+
* The two populate operation flags retain raw override values in model snapshots;
|
|
3381
|
+
* their effective policy is resolved separately against the captured model defaults.
|
|
3382
|
+
*/
|
|
3373
3383
|
interface DefaultModelRouterOptions<TModel = unknown> {
|
|
3374
3384
|
/**
|
|
3375
3385
|
* Default business-field policy when a model's permissionSchema is undefined.
|
|
@@ -3379,6 +3389,85 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3379
3389
|
permissionSchema?: PermissionSchema<AccessRouterFieldKey<TModel>>;
|
|
3380
3390
|
/** Server-owned fetch choices, captured per call. Not a per-call or method-default option. */
|
|
3381
3391
|
hydration?: ModelHydrationOptions;
|
|
3392
|
+
/**
|
|
3393
|
+
* This target model requires the caller's effective operation (`read`, supported
|
|
3394
|
+
* `list` or trusted custom access) for ordinary query population (built-in default `true`).
|
|
3395
|
+
* Only literal `false` skips that admission gate; source entry/field authorization,
|
|
3396
|
+
* target field/document grants, row/base/transform policies, original selection,
|
|
3397
|
+
* match and mandatory reference IDs still constrain output. Denied population retains
|
|
3398
|
+
* permitted original IDs; admitted population misses return null/filtered arrays.
|
|
3399
|
+
* Targets always require an actual registered Mongoose model and an effective object permissionSchema;
|
|
3400
|
+
* `{}` closes business fields. A configuration-only Document needs no HTTP routes;
|
|
3401
|
+
* denied direct/root read/list operations stay denied.
|
|
3402
|
+
* Static string refs resolve on the source connection and must match that runtime's
|
|
3403
|
+
* configured instance. Explicit Model-valued ordinary refs can cross connections
|
|
3404
|
+
* when that exact model is registered/configured in the same runtime. The validated
|
|
3405
|
+
* model stays pinned through in-flight population; callers cannot supply a model.
|
|
3406
|
+
*
|
|
3407
|
+
* Target override → captured runtime model default → true. Explicit undefined clears
|
|
3408
|
+
* the override and restores inheritance; omission preserves it. Malformed non-undefined
|
|
3409
|
+
* JavaScript values become true. Defaults are captured before source/target option
|
|
3410
|
+
* reads and the first await; later top-level calls observe changes. getModelOptions and
|
|
3411
|
+
* router.options retain raw flag overrides; getModelOption reads the live default.
|
|
3412
|
+
* Source/sibling flags cannot relax
|
|
3413
|
+
* this target. Configure with setModelOptions/setDefaultModelOptions, never global,
|
|
3414
|
+
* per-query, service.defaults or client controls. Independent of private dependencies.
|
|
3415
|
+
*/
|
|
3416
|
+
requireOperationAccessForPopulateQueries?: boolean;
|
|
3417
|
+
/**
|
|
3418
|
+
* This target model requires the original caller's base `operationAccess.read` before
|
|
3419
|
+
* loading declared private `dependsOnPopulate` inputs (built-in default `true`). Only
|
|
3420
|
+
* literal boolean `false` bypasses that operation gate. Target override → captured
|
|
3421
|
+
* runtime model default → true; explicit undefined clears the override to inherit,
|
|
3422
|
+
* omission preserves it, and malformed JS values other than undefined normalize true.
|
|
3423
|
+
* Runtime-isolated server configuration on the actual target, not the source model;
|
|
3424
|
+
* set runtime defaults with setDefaultModelOptions. Global setters reject these keys.
|
|
3425
|
+
* Captured with source/target policy before the first await; nested stages retain the
|
|
3426
|
+
* capture and later top-level calls refresh. No caller/query or service.defaults control.
|
|
3427
|
+
* Project refs to Document use Document's flags; Document's own private User ref
|
|
3428
|
+
* uses User's dependency flag, never Project's or Document's bypass.
|
|
3429
|
+
* Source/target input-field permissions are bypassed only by the declaration; the
|
|
3430
|
+
* virtual's output authorization still applies. Target request-mode `baseFilter.read`,
|
|
3431
|
+
* `overrideFilter.read` and retained reference IDs always constrain rows.
|
|
3432
|
+
*
|
|
3433
|
+
* Neither mode changes ordinary reference shape: selected/permitted parent fields keep
|
|
3434
|
+
* exact original IDs (including order, duplicates, missing IDs and nulls) when no admitted
|
|
3435
|
+
* ordinary population owns them. Private denial, row/query/getter failure or deferred
|
|
3436
|
+
* virtual denial cannot hide those IDs. There is no additional target-base-read reference-visibility gate.
|
|
3437
|
+
* Private fourth-argument inputs never implicitly enter DTOs, hooks, handles or metadata.
|
|
3438
|
+
* An actual registered model, effective object permissionSchema and static declarations
|
|
3439
|
+
* remain mandatory, independently of requireOperationAccessForPopulateQueries.
|
|
3440
|
+
*
|
|
3441
|
+
* @example
|
|
3442
|
+
* ```ts
|
|
3443
|
+
* import mongoose from 'mongoose';
|
|
3444
|
+
* import { createAccessRuntime, type DefaultModelRouterOptions } from '@web-ts-toolkit/access-router';
|
|
3445
|
+
* const api = createAccessRuntime();
|
|
3446
|
+
* const defaults = {
|
|
3447
|
+
* requireOperationAccessForPopulateQueries: true,
|
|
3448
|
+
* requireOperationAccessForPopulateDependencies: true,
|
|
3449
|
+
* } satisfies DefaultModelRouterOptions;
|
|
3450
|
+
* api.setDefaultModelOptions(defaults);
|
|
3451
|
+
* const Document = mongoose.model('Document', new mongoose.Schema({ name: String }));
|
|
3452
|
+
* const User = mongoose.model('User', new mongoose.Schema({ name: String }));
|
|
3453
|
+
* api.registerModelInstance(Document.modelName, Document);
|
|
3454
|
+
* api.registerModelInstance(User.modelName, User);
|
|
3455
|
+
* api.setModelOptions(Document.modelName, {
|
|
3456
|
+
* operationAccess: { read: false, list: false }, permissionSchema: { name: true },
|
|
3457
|
+
* requireOperationAccessForPopulateQueries: false,
|
|
3458
|
+
* requireOperationAccessForPopulateDependencies: false,
|
|
3459
|
+
* });
|
|
3460
|
+
* api.setModelOptions(User.modelName, {
|
|
3461
|
+
* operationAccess: { read: false, list: false }, permissionSchema: {},
|
|
3462
|
+
* requireOperationAccessForPopulateQueries: true,
|
|
3463
|
+
* requireOperationAccessForPopulateDependencies: true,
|
|
3464
|
+
* });
|
|
3465
|
+
* api.setModelOption(Document.modelName, 'requireOperationAccessForPopulateDependencies', undefined); // inherit again
|
|
3466
|
+
* // Administrative default changes apply to later calls on existing unoverridden models.
|
|
3467
|
+
* api.setDefaultModelOption('requireOperationAccessForPopulateDependencies', false);
|
|
3468
|
+
* ```
|
|
3469
|
+
*/
|
|
3470
|
+
requireOperationAccessForPopulateDependencies?: boolean;
|
|
3382
3471
|
/** Maximum returned list rows (default 1000), independent of exact match/count totals. */
|
|
3383
3472
|
listHardLimit?: number;
|
|
3384
3473
|
/**
|
|
@@ -3483,7 +3572,7 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3483
3572
|
* trusted non-mutating hooks, measure before rollout and restore `false` promptly.
|
|
3484
3573
|
* Embedded/related source stages use separate nested flags. Writes (including
|
|
3485
3574
|
* read-like output) and fresh helpers stay strict. Warns per model/flag transition.
|
|
3486
|
-
* Server model or model-
|
|
3575
|
+
* Server model or inherited model-default configuration only; never method defaults
|
|
3487
3576
|
* or wire options.
|
|
3488
3577
|
*/
|
|
3489
3578
|
unsafeSkipReadDocumentSnapshotChecks?: boolean;
|
|
@@ -3492,9 +3581,10 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3492
3581
|
* top-level LIST responses and their embedded/populated/included descendants.
|
|
3493
3582
|
* Exact output associations, graph identities, bindings and permission rules remain;
|
|
3494
3583
|
* scalar/native in-place mutations can now reuse stale decisions and expose data.
|
|
3495
|
-
* Source checks
|
|
3584
|
+
* Source checks and detached callback/grant/output copies remain. Initial output
|
|
3585
|
+
* snapshots also remain unless unsafeSkipListInitialOutputSnapshotCopy is active.
|
|
3496
3586
|
* Captured before awaits; handles keep this mode after rollback. Only literal `true`
|
|
3497
|
-
* in server model/
|
|
3587
|
+
* in server model/default configuration enables it and warns on effective transition.
|
|
3498
3588
|
* READ/retries use unsafeSkipReadOutputSnapshotChecks; writes and fresh helpers stay
|
|
3499
3589
|
* strict. Never set from request/per-call/method defaults. Revisit/remove promptly.
|
|
3500
3590
|
*/
|
|
@@ -3505,7 +3595,7 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3505
3595
|
* embedded/populated/included outputs. Uses the initiating READ model's captured
|
|
3506
3596
|
* setting, not LIST or target-model settings. Value mutations may reuse stale
|
|
3507
3597
|
* decisions; exact ownership/graph identities and permissions still run. Server
|
|
3508
|
-
* model/
|
|
3598
|
+
* model/default literal `true` only; warns on effective enablement. Retained handles
|
|
3509
3599
|
* keep their mode. Writes/fresh helpers stay strict. Revisit/remove promptly.
|
|
3510
3600
|
*/
|
|
3511
3601
|
unsafeSkipReadOutputSnapshotChecks?: boolean;
|
|
@@ -3515,8 +3605,8 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3515
3605
|
* The initiating model's captured setting applies recursively, not target-model
|
|
3516
3606
|
* flags. Parent source and all output-value checks remain independently configured;
|
|
3517
3607
|
* parent snapshots still include nested values. Permission rules, exact binding,
|
|
3518
|
-
* initial snapshots and detached copies remain. Child mutation can leave stale
|
|
3519
|
-
* grants/decisions and expose data. Only server model/
|
|
3608
|
+
* initial source snapshots and detached copies remain. Child mutation can leave stale
|
|
3609
|
+
* grants/decisions and expose data. Only server model/default literal `true`
|
|
3520
3610
|
* enables it; warns on transition. Rollback affects new calls, not captured descendants
|
|
3521
3611
|
* or handles. READ uses its own flag; writes, dedicated subdocument operations and
|
|
3522
3612
|
* fresh helpers stay strict. Never derive from requests. Revisit/remove promptly.
|
|
@@ -3529,11 +3619,37 @@ interface DefaultModelRouterOptions<TModel = unknown> {
|
|
|
3529
3619
|
* initiating READ model's captured setting, independently of LIST, root source
|
|
3530
3620
|
* and output-value flags. Parent comparisons may still observe child mutation.
|
|
3531
3621
|
* Stale grants/decisions can expose data; permissions, identities and detached copies
|
|
3532
|
-
* remain. Server model/
|
|
3622
|
+
* remain. Server model/default literal `true` only; warns on effective enablement.
|
|
3533
3623
|
* Writes/dedicated subdocument operations/fresh helpers stay strict; retained handles
|
|
3534
3624
|
* keep their mode after rollback. Never set from requests. Revisit/remove promptly.
|
|
3535
3625
|
*/
|
|
3536
3626
|
unsafeSkipReadNestedDocumentSnapshotChecks?: boolean;
|
|
3627
|
+
/**
|
|
3628
|
+
* TEMPORARY UNSAFE (default `false`): omit the initial output-association snapshot
|
|
3629
|
+
* copy for eligible LIST outputs and their authenticated descendants. Active only
|
|
3630
|
+
* with unsafeSkipListOutputSnapshotChecks=true; otherwise dormant (warns).
|
|
3631
|
+
* Skips this pass's native/BSON normalization and validation observations, which
|
|
3632
|
+
* can change exceptions, side effects and permission outcomes. Exact ownership,
|
|
3633
|
+
* bounded shape admission and graph identities remain; proxies/Map/Set and open
|
|
3634
|
+
* ownership bindings use the original copy fallback. Source snapshots and detached
|
|
3635
|
+
* hook/grant/response copies remain. Not a general clone bypass. Server model/default literal true
|
|
3636
|
+
* only; warns on activation. Captured before awaits; retained handles keep their
|
|
3637
|
+
* mode after rollback. READ/retries use their own flag; writes/fresh helpers stay
|
|
3638
|
+
* strict. Restore false promptly; never select from requests or method defaults.
|
|
3639
|
+
*/
|
|
3640
|
+
unsafeSkipListInitialOutputSnapshotCopy?: boolean;
|
|
3641
|
+
/**
|
|
3642
|
+
* TEMPORARY UNSAFE (default `false`): READ equivalent of
|
|
3643
|
+
* unsafeSkipListInitialOutputSnapshotCopy, including READ-to-list retries and
|
|
3644
|
+
* authenticated embedded/populated/included outputs. Requires the independent
|
|
3645
|
+
* unsafeSkipReadOutputSnapshotChecks=true. Uses the initiating READ model's
|
|
3646
|
+
* captured setting, not LIST/target flags. Omits initial native normalization
|
|
3647
|
+
* observations; ownership/bounds/identities and detached callback/source copies
|
|
3648
|
+
* remain. Proxies/Map/Set fall back to copying. Server model/default literal true
|
|
3649
|
+
* only; warns on activation/dormancy. Writes/fresh helpers stay strict. Captured
|
|
3650
|
+
* handles do not change on rollback. Never derive from requests; restore false.
|
|
3651
|
+
*/
|
|
3652
|
+
unsafeSkipReadInitialOutputSnapshotCopy?: boolean;
|
|
3537
3653
|
}
|
|
3538
3654
|
interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultModelRouterOptions<TModel> {
|
|
3539
3655
|
'hydration.publicList'?: HydrationMode;
|
|
@@ -3573,6 +3689,8 @@ interface ExtendedDefaultModelRouterOptions<TModel = unknown> extends DefaultMod
|
|
|
3573
3689
|
* named method query/presentation defaults. Trusted service authorization is per-call.
|
|
3574
3690
|
* Router setters update live behavior shallowly; router.options retains its frozen
|
|
3575
3691
|
* construction-time snapshot. Route-shape options require constructing a new router.
|
|
3692
|
+
* Populate flags govern this model when it is the actual target, not refs leaving it.
|
|
3693
|
+
* Their model snapshots retain raw overrides; operation capture resolves live defaults.
|
|
3576
3694
|
*/
|
|
3577
3695
|
interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record<never, never>> extends DefaultModelRouterOptions<TModel> {
|
|
3578
3696
|
modelName?: string;
|
|
@@ -3611,13 +3729,13 @@ interface ModelRouterOptions<TModel = unknown, TVirtuals extends object = Record
|
|
|
3611
3729
|
* that getter's fourth argument. Annotate ModelVirtualDescriptor<Source, Value,
|
|
3612
3730
|
* { ref: Target }> separately, then assign here; persisted/write/public types
|
|
3613
3731
|
* stay unchanged. Register target models/options first in this runtime. Source
|
|
3614
|
-
* refs are retained automatically.
|
|
3732
|
+
* refs are retained automatically. The actual target's requireOperationAccessForPopulateDependencies
|
|
3615
3733
|
* defaults to true; false bypasses only private target-operation admission, never
|
|
3616
3734
|
* request read-row filters/retained IDs. Neither mode changes ordinary reference
|
|
3617
3735
|
* shape: admitted population keeps its original authorized mask/miss; otherwise
|
|
3618
3736
|
* selected/permitted parent fields keep exact original IDs, even on private failure.
|
|
3619
3737
|
* Only unselected/field-denied source refs are omitted. Query operation admission is
|
|
3620
|
-
* independently controlled by
|
|
3738
|
+
* independently controlled by that target's requireOperationAccessForPopulateQueries.
|
|
3621
3739
|
*
|
|
3622
3740
|
* @example Shortest typed happy-path (persisted model lacks `fullAddress`):
|
|
3623
3741
|
* ```ts
|