@web-ts-toolkit/access-router 0.38.0 → 0.40.0

package/index.d.ts

@@ -1,10 +1,173 @@
 import mongoose, { Schema } from 'mongoose';
 import { Response, NextFunction, RequestHandler, Router } from 'express';
-import { A as AccessRouterBaseRequest, aa as GuardHook, ay as ModelRequest, cG as AccessRuntime, N as DataRouterOptions, L as DataRequest, cH as DataService, cI as Model, az as ModelRouterOptions, cJ as Service, cK as PublicService, _ as ExtendedModelRouterOptions, cj as Validation, bu as RootRouterOptions, cL as OpenApiRouterOptions, cM as OpenApiRegistryOptions, cN as OpenApiRouteDescriptor, cO as OpenApiDocumentOptions, cP as OpenApiParameter, cQ as OpenApiSchema, cR as OpenApiResponses, a8 as GlobalOptions, R as DefaultModelRouterOptions, Z as ExtendedDefaultModelRouterOptions } from './parsers--DZcTstL.js';
-export { cS as AccessRouterPermissionMap, cT as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, m as AjvValidatorLike, n as ArkTypeErrorsLike, o as ArkTypeLike, a9 as GlobalPermissionValue, ad as IoTsContextEntryLike, ae as IoTsDecodeErrorLike, af as IoTsDecoderLike, ag as JoiSchemaLike, ah as JoiValidationErrorDetailLike, am as MaybePromise, an as ModelBaseFilterHook, ap as ModelDeleteHook, aq as ModelDocPermissionsHook, as as ModelDocumentHook, at as ModelHook, av as ModelIdentifierHook, aw as ModelListHook, ax as ModelOverrideFilterHook, aA as ModelValidateHook, cU as OpenApiMethod, cV as Permissions, a_ as RequestSchemaAdapter, a$ as RequestSchemaFailure, b0 as RequestSchemaIssue, b1 as RequestSchemaLike, b2 as RequestSchemaOptions, b3 as RequestSchemaResult, b4 as RequestSchemaSuccess, b5 as RequestSchemaValidator, bF as StandardSchemaFailure, bG as StandardSchemaInferOutput, bH as StandardSchemaIssue, bI as StandardSchemaPathSegment, bJ as StandardSchemaResult, bK as StandardSchemaSuccess, bL as StandardSchemaV1, c0 as SuperstructFailureLike, c1 as SuperstructValidateLike, cd as ValibotIssueLike, ce as ValibotPathItemLike, cf as ValibotSafeParseLike, cg as ValibotSafeParseResult, cl as VineValidationErrorLike, cm as VineValidationMessageLike, cn as VineValidatorLike, co as YupSchemaLike, cp as YupValidationErrorLike, cW as defaultRuntime, cq as defineRequestSchema, cr as fromAjv, cs as fromArkType, ct as fromIoTs, cu as fromJoi, cv as fromStandardSchema, cw as fromSuperstruct, cx as fromValibot, cy as fromVine, cz as fromYup, cA as fromZod } from './parsers--DZcTstL.js';
+import { a8 as GlobalOptions, R as DefaultModelRouterOptions, Z as ExtendedDefaultModelRouterOptions, az as ModelRouterOptions, _ as ExtendedModelRouterOptions, N as DataRouterOptions, Y as ExtendedDataRouterOptions, A as AccessRouterBaseRequest, aa as GuardHook, ay as ModelRequest, L as DataRequest, cG as DataService, $ as Filter, aI as Projection, bD as Sort, aF as Populate, cH as Service, cI as PublicService, cj as Validation, bu as RootRouterOptions } from './parsers-PMWujHUV.js';
+export { cJ as AccessRouterPermissionMap, cK as AccessRouterPermissions, c as AccessRouterRequest, d as AccessRouterRequestExtensions, l as AjvErrorObjectLike, m as AjvValidatorLike, n as ArkTypeErrorsLike, o as ArkTypeLike, a9 as GlobalPermissionValue, ad as IoTsContextEntryLike, ae as IoTsDecodeErrorLike, af as IoTsDecoderLike, ag as JoiSchemaLike, ah as JoiValidationErrorDetailLike, am as MaybePromise, an as ModelBaseFilterHook, ap as ModelDeleteHook, aq as ModelDocPermissionsHook, as as ModelDocumentHook, at as ModelHook, av as ModelIdentifierHook, aw as ModelListHook, ax as ModelOverrideFilterHook, aA as ModelValidateHook, cL as Permissions, a_ as RequestSchemaAdapter, a$ as RequestSchemaFailure, b0 as RequestSchemaIssue, b1 as RequestSchemaLike, b2 as RequestSchemaOptions, b3 as RequestSchemaResult, b4 as RequestSchemaSuccess, b5 as RequestSchemaValidator, bF as StandardSchemaFailure, bG as StandardSchemaInferOutput, bH as StandardSchemaIssue, bI as StandardSchemaPathSegment, bJ as StandardSchemaResult, bK as StandardSchemaSuccess, bL as StandardSchemaV1, c0 as SuperstructFailureLike, c1 as SuperstructValidateLike, cd as ValibotIssueLike, ce as ValibotPathItemLike, cf as ValibotSafeParseLike, cg as ValibotSafeParseResult, cl as VineValidationErrorLike, cm as VineValidationMessageLike, cn as VineValidatorLike, co as YupSchemaLike, cp as YupValidationErrorLike, cq as defineRequestSchema, cr as fromAjv, cs as fromArkType, ct as fromIoTs, cu as fromJoi, cv as fromStandardSchema, cw as fromSuperstruct, cx as fromValibot, cy as fromVine, cz as fromYup, cA as fromZod } from './parsers-PMWujHUV.js';
 import JsonRouter from '@web-ts-toolkit/express-json-router';
 import 'zod';
 
+type OpenApiMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+type OpenApiSchema = Record<string, unknown>;
+type OpenApiSchemaSource = unknown;
+type OpenApiParameter = {
+    name: string;
+    in: 'path' | 'query';
+    required?: boolean;
+    description?: string;
+    schema?: OpenApiSchema;
+};
+type OpenApiResponse = {
+    description: string;
+    content?: Record<string, {
+        schema: OpenApiSchema;
+    }>;
+};
+type OpenApiResponses = Record<string, OpenApiResponse>;
+type OpenApiRouteDescriptor = {
+    method: OpenApiMethod;
+    path: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    acl?: string;
+    deprecated?: boolean;
+    query?: OpenApiSchemaSource;
+    body?: OpenApiSchemaSource;
+    pathParams?: Record<string, OpenApiSchemaSource>;
+    responses?: OpenApiResponses;
+    /**
+     * When true, replaces an existing registration with the same method/path
+     * even when the descriptors differ. When false (default), conflicting
+     * registrations throw at registration time so consumers can detect
+     * accidental route shadowing.
+     */
+    allowReplace?: boolean;
+    /**
+     * When true, this exact descriptor is idempotent and registering the same
+     * method/path with an equivalent descriptor again is silently accepted.
+     * Differing re-registrations still throw unless {@link allowReplace} is set.
+     * Additionally, an idempotent descriptor may share its operationId with
+     * another idempotent descriptor mounted at a different path on the same
+     * registry, so reserved operations (e.g. the root batch route) can be
+     * exposed from multiple base paths without triggering strict-mode
+     * duplicate-operationId rejection.
+     */
+    idempotent?: boolean;
+};
+type OpenApiRegistryOptions = {
+    /**
+     * Throw when the same method/path is registered twice with differing
+     * descriptors, instead of silently replacing. Default: true (strict).
+     * The {@link AccessRuntime} registry is constructed in strict mode by
+     * default; construct {@link OpenApiRegistry} directly with
+     * `rejectConflicts: false` for legacy replacement semantics.
+     */
+    rejectConflicts?: boolean;
+    /**
+     * Throw when the same operationId is registered more than once, including
+     * when {@link OpenApiRouteDescriptor.allowReplace} is set. Default: true.
+     */
+    rejectDuplicateOperationIds?: boolean;
+};
+type OpenApiDocumentOptions = {
+    title: string;
+    version: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+};
+type OpenApiRouterOptions = Partial<OpenApiDocumentOptions> & {
+    jsonPath?: string;
+    docsPath?: string | false;
+    swaggerUiCssUrl?: string;
+    swaggerUiBundleUrl?: string;
+};
+
+declare class AccessRuntime {
+    private readonly allowGlobalModelLookup;
+    constructor(options?: {
+        allowGlobalModelLookup?: boolean;
+    });
+    private readonly globalOptions;
+    private readonly defaultModelOptions;
+    private readonly modelOptions;
+    private readonly modelJsonSchemas;
+    private readonly dataOptions;
+    private readonly modelRefs;
+    private readonly modelSubs;
+    private readonly modelAtts;
+    private readonly modelInstances;
+    private readonly openApiRegistry;
+    registerModelInstance(modelName: string, model: mongoose.Model<unknown>): void;
+    hasModelInstance(modelName: string): boolean;
+    getModelInstance(modelName: string): mongoose.Model<unknown> | null;
+    registerOpenApiRoute(route: OpenApiRouteDescriptor): void;
+    /**
+     * Enable strict OpenAPI collision detection for the remainder of this
+     * runtime's lifetime. After this call, conflicting method/path
+     * registrations and duplicate operationIds throw {@link OpenApiCollisionError}
+     * instead of silently replacing. Existing already-registered routes are
+     * not retroactively re-validated.
+     */
+    enableOpenApiCollisionDetection(): void;
+    getOpenApiRoutes(): OpenApiRouteDescriptor[];
+    clearOpenApiRoutes(): void;
+    getOpenApiSpec(info: OpenApiDocumentOptions): {
+        openapi: string;
+        info: Omit<OpenApiDocumentOptions, "servers">;
+        servers?: OpenApiDocumentOptions["servers"];
+        paths: Record<string, Record<string, {
+            [key: `x-${string}`]: unknown;
+            operationId?: string;
+            summary?: string;
+            description?: string;
+            tags?: string[];
+            deprecated?: boolean;
+            parameters?: OpenApiParameter[];
+            requestBody?: {
+                required?: boolean;
+                content: Record<string, {
+                    schema: OpenApiSchema;
+                }>;
+            };
+            responses: OpenApiResponses;
+        }>>;
+    };
+    setGlobalOptions(options: GlobalOptions): void;
+    setGlobalOption<K extends keyof GlobalOptions>(key: K, value: GlobalOptions[K]): void;
+    getGlobalOptions(): GlobalOptions;
+    getGlobalOption<K extends keyof GlobalOptions>(key: K, defaultValue?: GlobalOptions[K]): GlobalOptions[K];
+    setDefaultModelOptions(options: DefaultModelRouterOptions): void;
+    setDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, value: ExtendedDefaultModelRouterOptions[K]): void;
+    getDefaultModelOptions(): DefaultModelRouterOptions<unknown>;
+    getDefaultModelOption<K extends keyof ExtendedDefaultModelRouterOptions>(key: K, defaultValue?: ExtendedDefaultModelRouterOptions[K]): ExtendedDefaultModelRouterOptions<unknown>[K];
+    private createModelOptions;
+    private getOrCreateModelOptions;
+    setModelOptions<TModel = unknown>(modelName: string, options: ModelRouterOptions<TModel>): void;
+    setModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K, value: ExtendedModelRouterOptions<TModel>[K]): void;
+    getModelOptions<TModel = unknown>(modelName: string): ModelRouterOptions<TModel>;
+    getModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K | string, defaultValue?: ExtendedModelRouterOptions<TModel>[K]): ExtendedModelRouterOptions<TModel>[K];
+    getExactModelOption<K extends keyof ExtendedModelRouterOptions<TModel>, TModel = unknown>(modelName: string, key: K | string): ExtendedModelRouterOptions<TModel>[K];
+    getModelNames(): string[];
+    hasModel(modelName: string): boolean;
+    getModelJsonSchema(modelName: string): Record<string, unknown>;
+    private createDataOptions;
+    private getOrCreateDataOptions;
+    setDataOptions<TData = unknown>(dataName: string, options: DataRouterOptions<TData>): void;
+    setDataOption<K extends keyof DataRouterOptions<TData>, TData = unknown>(dataName: string, key: K, value: DataRouterOptions<TData>[K]): void;
+    getDataOptions<TData = unknown>(dataName: string): DataRouterOptions<TData>;
+    getDataOption<K extends keyof DataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string, defaultValue?: DataRouterOptions<TData>[K]): DataRouterOptions<TData>[K];
+    getExactDataOption<K extends keyof ExtendedDataRouterOptions<TData>, TData = unknown>(dataName: string, key: K | string): ExtendedDataRouterOptions<TData>[K];
+    getDataNames(): string[];
+    ensureModelMeta(modelName: string): void;
+    getModelRef(modelName: string, refPath: string): string | null;
+    getModelSub(modelName: string): string[];
+    getModelAtt(modelName: string): string[];
+}
+declare const defaultRuntime: AccessRuntime;
+
 declare function macl(): (req: AccessRouterBaseRequest, res: Response, next: NextFunction) => Promise<void>;
 interface GuardModelConditionID {
     type: 'param' | 'query';
@@ -55,6 +218,38 @@ declare class DataRouter<TData = unknown> {
     get routes(): Router;
 }
 
+interface FindProps {
+    filter: Filter;
+    select?: Projection;
+    sort?: Sort;
+    populate?: Populate[] | string;
+    limit?: string | number;
+    hardLimit?: number;
+    skip?: string | number;
+    lean?: boolean;
+}
+interface FindOneProps {
+    filter: Filter;
+    select?: Projection;
+    sort?: Sort;
+    populate?: Populate[] | string;
+    lean?: boolean;
+}
+declare class Model {
+    modelName: string;
+    mongooseModel: mongoose.Model<any>;
+    runtime: AccessRuntime | null;
+    constructor(modelName: string, runtime?: AccessRuntime);
+    new(): any;
+    create(data: unknown): Promise<any>;
+    find({ filter, select, sort, populate, limit, hardLimit, skip, lean }: FindProps): mongoose.Query<any[], any>;
+    findOne({ filter, select, sort, populate, lean }: FindOneProps): mongoose.Query<any, any>;
+    exists(filter: Filter): ReturnType<typeof Model.prototype.findOne> | null;
+    countDocuments(filter?: {}): mongoose.Query<number, any>;
+    distinct(field: string, conditions?: {}): mongoose.Query<any[], any>;
+    aggregate(pipeline: unknown[]): mongoose.Aggregate<any[]>;
+}
+
 type SetTargetOption<TRouter, TOption> = {
     (option: TOption): TRouter;
     (key: string, option: unknown): TRouter;
@@ -379,4 +574,4 @@ type AccessRuntimeApi = typeof macl & Wtt;
 declare function createAccessRuntime(): AccessRuntimeApi;
 declare const acl: AccessRuntimeApi;
 
-export { AccessRuntime, type AccessRuntimeApi, type CombinedRouteInput, DataRouter, DataRouterOptions, ExtendedDefaultModelRouterOptions, ExtendedModelRouterOptions, GlobalOptions, type GuardModelCondition, type GuardModelConditionID, ModelRouter, ModelRouterOptions, type OpLogContext, OpenApiCollisionError, OpenApiDocumentOptions, OpenApiRegistry, OpenApiRegistryOptions, OpenApiRouteDescriptor, OpenApiRouterOptions, RootRouter, RootRouterOptions, 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 };
+export { AccessRuntime, type AccessRuntimeApi, type CombinedRouteInput, DataRouter, DataRouterOptions, ExtendedDefaultModelRouterOptions, ExtendedModelRouterOptions, GlobalOptions, type GuardModelCondition, type GuardModelConditionID, ModelRouter, ModelRouterOptions, type OpLogContext, OpenApiCollisionError, type OpenApiDocumentOptions, type OpenApiMethod, OpenApiRegistry, type OpenApiRegistryOptions, type OpenApiRouteDescriptor, type OpenApiRouterOptions, RootRouter, RootRouterOptions, acl, combineRoutes, createAccessRuntime, createOpenApiRouter, acl as default, defaultRuntime, getDefaultModelOption, getDefaultModelOptions, getGlobalOption, getGlobalOptions, getModelInstance, getModelJsonSchema, getModelNames, getModelOption, getModelOptions, guard, hasModelInstance, isLevelEnabled, permissionsPlugin, redactFilter, redactPayload, registerModelInstance, safeStringify, setDefaultModelOption, setDefaultModelOptions, setGlobalOption, setGlobalOptions, setModelOption, setModelOptions };