@classytic/mongokit 3.2.0 → 3.2.2

package/dist/index.d.ts

@@ -1,1422 +0,0 @@
-import { h as PaginationResult, A as AnyDocument, i as PluginType, P as PaginationConfig, R as RepositoryOptions, j as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, U as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, k as RepositoryContext, H as HttpError } from './types-Jni1KgkP.js';
-export { c as AggregatePaginationOptions, ad as AllPluginMethods, l as AnyModel, a7 as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, C as CreateInput, v as CreateOptions, Z as CrudSchemas, _ as DecodedCursor, D as DeepPartial, w as DeleteResult, L as EventHandlers, M as EventPayload, G as EventPhase, Q as FieldPreset, T as FieldRules, a5 as GroupResult, n as HookMode, I as InferDocument, o as InferRawDoc, Y as JsonSchema, r as KeysOfType, K as KeysetPaginationOptions, a1 as Logger, a6 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, u as OperationOptions, p as PartialBy, g as Plugin, B as PluginFunction, J as RepositoryEvent, E as RepositoryInstance, F as RepositoryOperation, q as RequiredBy, X as SchemaBuilderOptions, a3 as SoftDeleteFilterMode, a2 as SoftDeleteOptions, a4 as SoftDeleteRepository, m as SortDirection, s as Strict, t as UpdateInput, x as UpdateManyResult, y as UpdateWithValidationResult, z as UserContext, a0 as ValidationChainOptions, V as ValidationResult, $ as ValidatorDefinition, ae as WithPlugins } from './types-Jni1KgkP.js';
-import * as mongoose from 'mongoose';
-import { PipelineStage, Model, Expression, ClientSession, PopulateOptions } from 'mongoose';
-import { PaginationEngine } from './pagination/PaginationEngine.js';
-import { L as LookupOptions, a as LookupBuilder } from './index-BDn5fSTE.js';
-export { i as actions } from './index-BDn5fSTE.js';
-export { AggregateHelpersMethods, BatchOperationsMethods, CacheMethods, MongoOperationsMethods, MultiTenantOptions, ObservabilityOptions, OperationMetric, SoftDeleteMethods, SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
-export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, k as configureLogger, j as createError, c as createFieldPreset, l as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from './mongooseToJsonSchema-CaRF_bCN.js';
-
-/**
- * Framework-Agnostic Controller Interfaces
- *
- * These interfaces define contracts for building controllers that work with any framework.
- * Implement these in your chosen framework (Express, Fastify, Next.js, etc.)
- *
- * @see examples/api/baseController.ts for Express implementation
- * @see examples/fastify for Fastify implementation
- * @see examples/nextjs for Next.js implementation
- */
-
-/**
- * Framework-agnostic request context
- *
- * Extract this from your framework's request object:
- * - Express: { query: req.query, body: req.body, params: req.params, user: req.user }
- * - Fastify: { query: request.query, body: request.body, params: request.params, user: request.user }
- * - Next.js: { query: searchParams, body: await request.json(), params: params, user: await getUser() }
- *
- * @example
- * ```typescript
- * // Express
- * const context: IRequestContext = {
- *   query: req.query,
- *   body: req.body,
- *   params: req.params,
- *   user: req.user,
- *   context: { organizationId: req.headers['x-org-id'] }
- * };
- *
- * // Fastify
- * const context: IRequestContext = {
- *   query: request.query,
- *   body: request.body,
- *   params: request.params,
- *   user: request.user,
- * };
- *
- * // Next.js App Router
- * const context: IRequestContext = {
- *   query: Object.fromEntries(request.nextUrl.searchParams),
- *   body: await request.json(),
- *   params: params,
- *   user: await auth(),
- * };
- * ```
- */
-interface IRequestContext {
-    /** Query parameters (from URL query string) */
-    query: Record<string, unknown>;
-    /** Request body (parsed JSON) */
-    body: Record<string, unknown>;
-    /** Route parameters (dynamic segments in URL) */
-    params: Record<string, string>;
-    /**
-     * Authenticated user (from your auth middleware)
-     * Shape depends on your auth system
-     */
-    user?: {
-        id: string;
-        role?: string;
-        [key: string]: unknown;
-    };
-    /**
-     * Custom context (tenant ID, organization, locale, etc.)
-     * Use this for multi-tenant apps, feature flags, etc.
-     */
-    context?: Record<string, unknown>;
-}
-/**
- * Framework-agnostic controller response
- *
- * Your controller methods should return this shape.
- * Adapt it to your framework's response format in the handler layer.
- *
- * @example
- * ```typescript
- * // In controller method
- * async list(context: IRequestContext): Promise<IControllerResponse> {
- *   const result = await this.repository.getAll(context.query);
- *   return {
- *     success: true,
- *     data: result,
- *     status: 200,
- *   };
- * }
- *
- * // In Express handler
- * const response = await controller.list(context);
- * res.status(response.status).json(response);
- *
- * // In Fastify handler
- * const response = await controller.list(context);
- * return reply.code(response.status).send(response);
- *
- * // In Next.js handler
- * const response = await controller.list(context);
- * return NextResponse.json(response.data, { status: response.status });
- * ```
- */
-interface IControllerResponse<T = unknown> {
-    /** Whether the operation succeeded */
-    success: boolean;
-    /** Response data (undefined on error) */
-    data?: T;
-    /** Error message (only if success = false) */
-    error?: string;
-    /** Additional error details (validation errors, stack trace, etc.) */
-    details?: unknown;
-    /** HTTP status code */
-    status: number;
-    /** Optional metadata (pagination info, warnings, etc.) */
-    meta?: Record<string, unknown>;
-}
-/**
- * Framework-agnostic CRUD controller interface
- *
- * Implement this interface in your controller classes.
- * Each method receives a framework-agnostic context and returns a framework-agnostic response.
- *
- * @template TDoc - The Mongoose document type
- *
- * @example
- * ```typescript
- * import { IController, IRequestContext, IControllerResponse } from '@mongokit/core';
- *
- * class UserController implements IController<IUser> {
- *   async list(context: IRequestContext): Promise<IControllerResponse> {
- *     // Implementation
- *   }
- *
- *   async get(context: IRequestContext): Promise<IControllerResponse> {
- *     // Implementation
- *   }
- *
- *   // ... other methods
- * }
- * ```
- */
-interface IController<TDoc> {
-    /**
-     * List resources with filtering, pagination, sorting, lookups
-     *
-     * @param context - Framework-agnostic request context
-     * @returns Promise resolving to controller response with paginated data
-     *
-     * @example
-     * ```typescript
-     * // URL: GET /users?status=active&sort=-createdAt&limit=20
-     * const response = await controller.list({
-     *   query: { status: 'active', sort: '-createdAt', limit: '20' },
-     *   body: {},
-     *   params: {},
-     * });
-     *
-     * // Response:
-     * {
-     *   success: true,
-     *   data: {
-     *     method: 'offset',
-     *     docs: [...],
-     *     total: 100,
-     *     page: 1,
-     *     pages: 5
-     *   },
-     *   status: 200
-     * }
-     * ```
-     */
-    list(context: IRequestContext): Promise<IControllerResponse<PaginationResult<TDoc>>>;
-    /**
-     * Get single resource by ID
-     *
-     * @param context - Framework-agnostic request context (id in params)
-     * @returns Promise resolving to controller response with single document
-     *
-     * @example
-     * ```typescript
-     * // URL: GET /users/507f1f77bcf86cd799439011
-     * const response = await controller.get({
-     *   query: {},
-     *   body: {},
-     *   params: { id: '507f1f77bcf86cd799439011' },
-     * });
-     *
-     * // Success response:
-     * {
-     *   success: true,
-     *   data: { _id: '...', name: 'John', ... },
-     *   status: 200
-     * }
-     *
-     * // Not found response:
-     * {
-     *   success: false,
-     *   error: 'Resource not found',
-     *   status: 404
-     * }
-     * ```
-     */
-    get(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    /**
-     * Create new resource
-     *
-     * @param context - Framework-agnostic request context (data in body)
-     * @returns Promise resolving to controller response with created document
-     *
-     * @example
-     * ```typescript
-     * // URL: POST /users
-     * // Body: { name: 'John', email: 'john@example.com' }
-     * const response = await controller.create({
-     *   query: {},
-     *   body: { name: 'John', email: 'john@example.com' },
-     *   params: {},
-     * });
-     *
-     * // Response:
-     * {
-     *   success: true,
-     *   data: { _id: '...', name: 'John', email: '...', createdAt: '...' },
-     *   status: 201
-     * }
-     * ```
-     */
-    create(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    /**
-     * Update existing resource
-     *
-     * @param context - Framework-agnostic request context (id in params, updates in body)
-     * @returns Promise resolving to controller response with updated document
-     *
-     * @example
-     * ```typescript
-     * // URL: PATCH /users/507f1f77bcf86cd799439011
-     * // Body: { name: 'Jane' }
-     * const response = await controller.update({
-     *   query: {},
-     *   body: { name: 'Jane' },
-     *   params: { id: '507f1f77bcf86cd799439011' },
-     * });
-     *
-     * // Response:
-     * {
-     *   success: true,
-     *   data: { _id: '...', name: 'Jane', ... },
-     *   status: 200
-     * }
-     * ```
-     */
-    update(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    /**
-     * Delete resource
-     *
-     * @param context - Framework-agnostic request context (id in params)
-     * @returns Promise resolving to controller response with deletion result
-     *
-     * @example
-     * ```typescript
-     * // URL: DELETE /users/507f1f77bcf86cd799439011
-     * const response = await controller.delete({
-     *   query: {},
-     *   body: {},
-     *   params: { id: '507f1f77bcf86cd799439011' },
-     * });
-     *
-     * // Response:
-     * {
-     *   success: true,
-     *   data: { message: 'Resource deleted successfully' },
-     *   status: 200
-     * }
-     * ```
-     */
-    delete(context: IRequestContext): Promise<IControllerResponse<{
-        message: string;
-    }>>;
-}
-/**
- * Optional: Response formatter utilities
- *
- * Helper functions to create standardized controller responses.
- * Use these to maintain consistent response shapes across your API.
- *
- * @example
- * ```typescript
- * class BaseController {
- *   protected success<T>(data: T, status = 200): IControllerResponse<T> {
- *     return { success: true, data, status };
- *   }
- *
- *   protected error(message: string, status = 500, details?: unknown): IControllerResponse {
- *     return { success: false, error: message, status, details };
- *   }
- *
- *   protected paginated<T>(result: PaginationResult<T>): IControllerResponse<PaginationResult<T>> {
- *     return { success: true, data: result, status: 200 };
- *   }
- * }
- * ```
- */
-interface IResponseFormatter {
-    /**
-     * Format successful response
-     * @param data - Response data
-     * @param status - HTTP status code (default: 200)
-     */
-    success<T>(data: T, status?: number): IControllerResponse<T>;
-    /**
-     * Format error response
-     * @param message - Error message
-     * @param status - HTTP status code (default: 500)
-     * @param details - Additional error details
-     */
-    error(message: string, status?: number, details?: unknown): IControllerResponse;
-    /**
-     * Format paginated response
-     * @param result - Pagination result from Repository.getAll()
-     */
-    paginated<T>(result: PaginationResult<T>): IControllerResponse<PaginationResult<T>>;
-}
-
-/** Options for $vectorSearch stage (Atlas only) */
-interface VectorSearchOptions {
-    /** Atlas Search index name */
-    index: string;
-    /** Field path containing the vector embedding */
-    path: string;
-    /** Query vector to search against */
-    queryVector: number[];
-    /** Number of candidates to consider (higher = more accurate, slower) */
-    numCandidates?: number;
-    /** Max results to return */
-    limit: number;
-    /** Pre-filter documents before vector search */
-    filter?: Record<string, unknown>;
-    /** Use exact search instead of ANN (slower but precise) */
-    exact?: boolean;
-}
-/** Result from build() including execution options */
-interface AggregationPlan {
-    pipeline: PipelineStage[];
-    allowDiskUse: boolean;
-}
-type SortOrder = 1 | -1 | 'asc' | 'desc';
-type SortSpec$1 = Record<string, SortOrder>;
-type ProjectionSpec = Record<string, 0 | 1 | Expression>;
-type GroupSpec = {
-    _id: string | Record<string, unknown> | null;
-    [key: string]: unknown;
-};
-/**
- * Fluent builder for MongoDB aggregation pipelines
- * Optimized for complex queries at scale
- */
-declare class AggregationBuilder {
-    private pipeline;
-    private _diskUse;
-    /**
-     * Get the current pipeline
-     */
-    get(): PipelineStage[];
-    /**
-     * Build and return the final pipeline
-     */
-    build(): PipelineStage[];
-    /**
-     * Build pipeline with execution options (allowDiskUse, etc.)
-     */
-    plan(): AggregationPlan;
-    /**
-     * Build and execute the pipeline against a model
-     *
-     * @example
-     * ```typescript
-     * const results = await new AggregationBuilder()
-     *   .match({ status: 'active' })
-     *   .allowDiskUse()
-     *   .exec(MyModel);
-     * ```
-     */
-    exec<T = unknown>(model: Model<any>, session?: mongoose.ClientSession): Promise<T[]>;
-    /**
-     * Reset the pipeline
-     */
-    reset(): this;
-    /**
-     * Add a raw pipeline stage
-     */
-    addStage(stage: PipelineStage): this;
-    /**
-     * Add multiple raw pipeline stages
-     */
-    addStages(stages: PipelineStage[]): this;
-    /**
-     * $match - Filter documents
-     * IMPORTANT: Place $match as early as possible for performance
-     */
-    match(query: Record<string, unknown>): this;
-    /**
-     * $project - Include/exclude fields or compute new fields
-     */
-    project(projection: ProjectionSpec): this;
-    /**
-     * $group - Group documents and compute aggregations
-     *
-     * @example
-     * ```typescript
-     * .group({
-     *   _id: '$department',
-     *   count: { $sum: 1 },
-     *   avgSalary: { $avg: '$salary' }
-     * })
-     * ```
-     */
-    group(groupSpec: GroupSpec): this;
-    /**
-     * $sort - Sort documents
-     */
-    sort(sortSpec: SortSpec$1 | string): this;
-    /**
-     * $limit - Limit number of documents
-     */
-    limit(count: number): this;
-    /**
-     * $skip - Skip documents
-     */
-    skip(count: number): this;
-    /**
-     * $unwind - Deconstruct array field
-     */
-    unwind(path: string, preserveNullAndEmptyArrays?: boolean): this;
-    /**
-     * $addFields - Add new fields or replace existing fields
-     */
-    addFields(fields: Record<string, unknown>): this;
-    /**
-     * $set - Alias for $addFields
-     */
-    set(fields: Record<string, unknown>): this;
-    /**
-     * $unset - Remove fields
-     */
-    unset(fields: string | string[]): this;
-    /**
-     * $replaceRoot - Replace the root document
-     */
-    replaceRoot(newRoot: string | Record<string, unknown>): this;
-    /**
-     * $lookup - Join with another collection (simple form)
-     *
-     * @param from - Collection to join with
-     * @param localField - Field from source collection
-     * @param foreignField - Field from target collection
-     * @param as - Output field name
-     * @param single - Unwrap array to single object
-     *
-     * @example
-     * ```typescript
-     * // Join employees with departments by slug
-     * .lookup('departments', 'deptSlug', 'slug', 'department', true)
-     * ```
-     */
-    lookup(from: string, localField: string, foreignField: string, as?: string, single?: boolean): this;
-    /**
-     * $lookup - Join with another collection (advanced form with pipeline)
-     *
-     * @example
-     * ```typescript
-     * .lookupWithPipeline({
-     *   from: 'products',
-     *   localField: 'productIds',
-     *   foreignField: 'sku',
-     *   as: 'products',
-     *   pipeline: [
-     *     { $match: { status: 'active' } },
-     *     { $project: { name: 1, price: 1 } }
-     *   ]
-     * })
-     * ```
-     */
-    lookupWithPipeline(options: LookupOptions): this;
-    /**
-     * Multiple lookups at once
-     *
-     * @example
-     * ```typescript
-     * .multiLookup([
-     *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
-     *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
-     * ])
-     * ```
-     */
-    multiLookup(lookups: LookupOptions[]): this;
-    /**
-     * $facet - Process multiple aggregation pipelines in a single stage
-     * Useful for computing multiple aggregations in parallel
-     *
-     * @example
-     * ```typescript
-     * .facet({
-     *   totalCount: [{ $count: 'count' }],
-     *   avgPrice: [{ $group: { _id: null, avg: { $avg: '$price' } } }],
-     *   topProducts: [{ $sort: { sales: -1 } }, { $limit: 10 }]
-     * })
-     * ```
-     */
-    facet(facets: Record<string, PipelineStage[]>): this;
-    /**
-     * $bucket - Categorize documents into buckets
-     *
-     * @example
-     * ```typescript
-     * .bucket({
-     *   groupBy: '$price',
-     *   boundaries: [0, 50, 100, 200],
-     *   default: 'Other',
-     *   output: {
-     *     count: { $sum: 1 },
-     *     products: { $push: '$name' }
-     *   }
-     * })
-     * ```
-     */
-    bucket(options: {
-        groupBy: string | Expression;
-        boundaries: unknown[];
-        default?: string;
-        output?: Record<string, unknown>;
-    }): this;
-    /**
-     * $bucketAuto - Automatically determine bucket boundaries
-     */
-    bucketAuto(options: {
-        groupBy: string | Expression;
-        buckets: number;
-        output?: Record<string, unknown>;
-        granularity?: string;
-    }): this;
-    /**
-     * $setWindowFields - Perform window functions (MongoDB 5.0+)
-     * Useful for rankings, running totals, moving averages
-     *
-     * @example
-     * ```typescript
-     * .setWindowFields({
-     *   partitionBy: '$department',
-     *   sortBy: { salary: -1 },
-     *   output: {
-     *     rank: { $rank: {} },
-     *     runningTotal: { $sum: '$salary', window: { documents: ['unbounded', 'current'] } }
-     *   }
-     * })
-     * ```
-     */
-    setWindowFields(options: {
-        partitionBy?: string | Expression;
-        sortBy?: SortSpec$1;
-        output: Record<string, unknown>;
-    }): this;
-    /**
-     * $unionWith - Combine results from multiple collections (MongoDB 4.4+)
-     *
-     * @example
-     * ```typescript
-     * .unionWith({
-     *   coll: 'archivedOrders',
-     *   pipeline: [{ $match: { year: 2024 } }]
-     * })
-     * ```
-     */
-    unionWith(options: {
-        coll: string;
-        pipeline?: PipelineStage[];
-    }): this;
-    /**
-     * $densify - Fill gaps in data (MongoDB 5.1+)
-     * Useful for time series data with missing points
-     */
-    densify(options: {
-        field: string;
-        range: {
-            step: number;
-            unit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
-            bounds: 'full' | 'partition' | [unknown, unknown];
-        };
-    }): this;
-    /**
-     * $fill - Fill null or missing field values (MongoDB 5.3+)
-     */
-    fill(options: {
-        sortBy?: SortSpec$1;
-        output: Record<string, {
-            method: 'linear' | 'locf' | 'value';
-            value?: unknown;
-        }>;
-    }): this;
-    /**
-     * Enable allowDiskUse for large aggregations that exceed 100MB memory limit
-     *
-     * @example
-     * ```typescript
-     * const results = await new AggregationBuilder()
-     *   .match({ status: 'active' })
-     *   .group({ _id: '$category', total: { $sum: '$amount' } })
-     *   .allowDiskUse()
-     *   .exec(Model);
-     * ```
-     */
-    allowDiskUse(enable?: boolean): this;
-    /**
-     * Paginate - Add skip and limit for offset-based pagination
-     */
-    paginate(page: number, limit: number): this;
-    /**
-     * Count total documents (useful with $facet for pagination metadata)
-     */
-    count(outputField?: string): this;
-    /**
-     * Sample - Randomly select N documents
-     */
-    sample(size: number): this;
-    /**
-     * Out - Write results to a collection
-     */
-    out(collection: string): this;
-    /**
-     * Merge - Merge results into a collection
-     */
-    merge(options: string | {
-        into: string;
-        on?: string | string[];
-        whenMatched?: string;
-        whenNotMatched?: string;
-    }): this;
-    /**
-     * GeoNear - Perform geospatial queries
-     */
-    geoNear(options: {
-        near: {
-            type: 'Point';
-            coordinates: [number, number];
-        };
-        distanceField: string;
-        maxDistance?: number;
-        query?: Record<string, unknown>;
-        spherical?: boolean;
-    }): this;
-    /**
-     * GraphLookup - Perform recursive search (graph traversal)
-     */
-    graphLookup(options: {
-        from: string;
-        startWith: string | Expression;
-        connectFromField: string;
-        connectToField: string;
-        as: string;
-        maxDepth?: number;
-        depthField?: string;
-        restrictSearchWithMatch?: Record<string, unknown>;
-    }): this;
-    /**
-     * $search - Atlas Search full-text search (Atlas only)
-     *
-     * @example
-     * ```typescript
-     * .search({
-     *   index: 'default',
-     *   text: {
-     *     query: 'laptop computer',
-     *     path: ['title', 'description'],
-     *     fuzzy: { maxEdits: 2 }
-     *   }
-     * })
-     * ```
-     */
-    search(options: {
-        index?: string;
-        text?: {
-            query: string;
-            path: string | string[];
-            fuzzy?: {
-                maxEdits?: number;
-                prefixLength?: number;
-            };
-            score?: {
-                boost?: {
-                    value?: number;
-                };
-            };
-        };
-        compound?: {
-            must?: unknown[];
-            mustNot?: unknown[];
-            should?: unknown[];
-            filter?: unknown[];
-        };
-        autocomplete?: unknown;
-        near?: unknown;
-        range?: unknown;
-    }): this;
-    /**
-     * $searchMeta - Get Atlas Search metadata (Atlas only)
-     */
-    searchMeta(options: Record<string, unknown>): this;
-    /**
-     * $vectorSearch - Semantic similarity search using vector embeddings (Atlas only)
-     *
-     * Requires an Atlas Vector Search index on the target field.
-     * Must be the first stage in the pipeline.
-     *
-     * @example
-     * ```typescript
-     * const results = await new AggregationBuilder()
-     *   .vectorSearch({
-     *     index: 'vector_index',
-     *     path: 'embedding',
-     *     queryVector: await getEmbedding('running shoes'),
-     *     limit: 10,
-     *     numCandidates: 100,
-     *     filter: { category: 'footwear' }
-     *   })
-     *   .project({ embedding: 0, score: { $meta: 'vectorSearchScore' } })
-     *   .exec(ProductModel);
-     * ```
-     */
-    vectorSearch(options: VectorSearchOptions): this;
-    /**
-     * Add vectorSearchScore as a field after $vectorSearch
-     * Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
-     */
-    withVectorScore(fieldName?: string): this;
-    /**
-     * Create a builder from an existing pipeline
-     */
-    static from(pipeline: PipelineStage[]): AggregationBuilder;
-    /**
-     * Create a builder with initial match stage
-     */
-    static startWith(query: Record<string, unknown>): AggregationBuilder;
-}
-
-/**
- * Repository Pattern - Data Access Layer
- *
- * Event-driven, plugin-based abstraction for MongoDB operations
- * Inspired by Meta & Stripe's repository patterns
- *
- * @example
- * ```typescript
- * const userRepo = new Repository(UserModel, [
- *   timestampPlugin(),
- *   softDeletePlugin(),
- * ]);
- *
- * // Create
- * const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
- *
- * // Read with pagination
- * const users = await userRepo.getAll({ page: 1, limit: 20, filters: { status: 'active' } });
- *
- * // Update
- * const updated = await userRepo.update(user._id, { name: 'John Doe' });
- *
- * // Delete
- * await userRepo.delete(user._id);
- * ```
- */
-
-type HookListener = (data: any) => void | Promise<void>;
-/**
- * Production-grade repository for MongoDB
- * Event-driven, plugin-based, with smart pagination
- */
-declare class Repository<TDoc = AnyDocument> {
-    readonly Model: Model<TDoc>;
-    readonly model: string;
-    readonly _hooks: Map<string, HookListener[]>;
-    readonly _pagination: PaginationEngine<TDoc>;
-    private readonly _hookMode;
-    [key: string]: unknown;
-    constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
-    /**
-     * Register a plugin
-     */
-    use(plugin: PluginType): this;
-    /**
-     * Register event listener
-     */
-    on(event: string, listener: HookListener): this;
-    /**
-     * Remove a specific event listener
-     */
-    off(event: string, listener: HookListener): this;
-    /**
-     * Remove all listeners for an event, or all listeners entirely
-     */
-    removeAllListeners(event?: string): this;
-    /**
-     * Emit event (sync - for backwards compatibility)
-     */
-    emit(event: string, data: unknown): void;
-    /**
-     * Emit event and await all async handlers
-     */
-    emitAsync(event: string, data: unknown): Promise<void>;
-    private _emitHook;
-    private _emitErrorHook;
-    /**
-     * Create single document
-     */
-    create(data: Record<string, unknown>, options?: {
-        session?: ClientSession;
-    }): Promise<TDoc>;
-    /**
-     * Create multiple documents
-     */
-    createMany(dataArray: Record<string, unknown>[], options?: {
-        session?: ClientSession;
-        ordered?: boolean;
-    }): Promise<TDoc[]>;
-    /**
-     * Get document by ID
-     */
-    getById(id: string | ObjectId, options?: {
-        select?: SelectSpec;
-        populate?: PopulateSpec;
-        populateOptions?: PopulateOptions[];
-        lean?: boolean;
-        session?: ClientSession;
-        throwOnNotFound?: boolean;
-        skipCache?: boolean;
-        cacheTtl?: number;
-    }): Promise<TDoc | null>;
-    /**
-     * Get single document by query
-     */
-    getByQuery(query: Record<string, unknown>, options?: {
-        select?: SelectSpec;
-        populate?: PopulateSpec;
-        populateOptions?: PopulateOptions[];
-        lean?: boolean;
-        session?: ClientSession;
-        throwOnNotFound?: boolean;
-        skipCache?: boolean;
-        cacheTtl?: number;
-    }): Promise<TDoc | null>;
-    /**
-     * Unified pagination - auto-detects offset vs keyset based on params
-     *
-     * Auto-detection logic:
-     * - If params has 'cursor' or 'after' → uses keyset pagination (stream)
-     * - If params has 'pagination' or 'page' → uses offset pagination (paginate)
-     * - Else → defaults to offset pagination with page=1
-     *
-     * @example
-     * // Offset pagination (page-based)
-     * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
-     * await repo.getAll({ pagination: { page: 2, limit: 20 } });
-     *
-     * // Keyset pagination (cursor-based)
-     * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
-     * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
-     *
-     * // Simple query (defaults to page 1)
-     * await repo.getAll({ filters: { status: 'active' } });
-     *
-     * // Skip cache for fresh data
-     * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
-     */
-    getAll(params?: {
-        filters?: Record<string, unknown>;
-        sort?: SortSpec$2 | string;
-        cursor?: string;
-        after?: string;
-        page?: number;
-        pagination?: {
-            page?: number;
-            limit?: number;
-        };
-        limit?: number;
-        search?: string;
-        /** Advanced populate options (from QueryParser or Arc's BaseController) */
-        populateOptions?: PopulateOptions[];
-    }, options?: {
-        select?: SelectSpec;
-        populate?: PopulateSpec;
-        populateOptions?: PopulateOptions[];
-        lean?: boolean;
-        session?: ClientSession;
-        skipCache?: boolean;
-        cacheTtl?: number;
-    }): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc>>;
-    /**
-     * Get or create document
-     */
-    getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
-        session?: ClientSession;
-    }): Promise<TDoc | null>;
-    /**
-     * Count documents
-     */
-    count(query?: Record<string, unknown>, options?: {
-        session?: ClientSession;
-    }): Promise<number>;
-    /**
-     * Check if document exists
-     */
-    exists(query: Record<string, unknown>, options?: {
-        session?: ClientSession;
-    }): Promise<{
-        _id: unknown;
-    } | null>;
-    /**
-     * Update document by ID
-     */
-    update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
-    /**
-     * Delete document by ID
-     */
-    delete(id: string | ObjectId, options?: {
-        session?: ClientSession;
-    }): Promise<{
-        success: boolean;
-        message: string;
-    }>;
-    /**
-     * Execute aggregation pipeline
-     */
-    aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: {
-        session?: ClientSession;
-    }): Promise<TResult[]>;
-    /**
-     * Aggregate pipeline with pagination
-     * Best for: Complex queries, grouping, joins
-     */
-    aggregatePaginate(options?: {
-        pipeline?: PipelineStage[];
-        page?: number;
-        limit?: number;
-        session?: ClientSession;
-    }): Promise<AggregatePaginationResult<TDoc>>;
-    /**
-     * Get distinct values
-     */
-    distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
-        session?: ClientSession;
-    }): Promise<T[]>;
-    /**
-     * Query with custom field lookups ($lookup)
-     * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
-     *
-     * @example
-     * ```typescript
-     * // Join employees with departments using slug instead of ObjectId
-     * const employees = await employeeRepo.lookupPopulate({
-     *   filters: { status: 'active' },
-     *   lookups: [
-     *     {
-     *       from: 'departments',
-     *       localField: 'departmentSlug',
-     *       foreignField: 'slug',
-     *       as: 'department',
-     *       single: true
-     *     }
-     *   ],
-     *   sort: '-createdAt',
-     *   page: 1,
-     *   limit: 50
-     * });
-     * ```
-     */
-    lookupPopulate(options: {
-        filters?: Record<string, unknown>;
-        lookups: LookupOptions[];
-        sort?: SortSpec$2 | string;
-        page?: number;
-        limit?: number;
-        select?: SelectSpec;
-        session?: ClientSession;
-    }): Promise<{
-        data: TDoc[];
-        total?: number;
-        page?: number;
-        limit?: number;
-    }>;
-    /**
-     * Create an aggregation builder for this model
-     * Useful for building complex custom aggregations
-     *
-     * @example
-     * ```typescript
-     * const pipeline = repo.buildAggregation()
-     *   .match({ status: 'active' })
-     *   .lookup('departments', 'deptSlug', 'slug', 'department', true)
-     *   .group({ _id: '$department', count: { $sum: 1 } })
-     *   .sort({ count: -1 })
-     *   .build();
-     *
-     * const results = await repo.Model.aggregate(pipeline);
-     * ```
-     */
-    buildAggregation(): AggregationBuilder;
-    /**
-     * Create a lookup builder
-     * Useful for building $lookup stages independently
-     *
-     * @example
-     * ```typescript
-     * const lookupStages = repo.buildLookup('departments')
-     *   .localField('deptSlug')
-     *   .foreignField('slug')
-     *   .as('department')
-     *   .single()
-     *   .build();
-     *
-     * const pipeline = [
-     *   { $match: { status: 'active' } },
-     *   ...lookupStages
-     * ];
-     * ```
-     */
-    buildLookup(from?: string): LookupBuilder;
-    /**
-     * Execute callback within a transaction with automatic retry on transient failures.
-     *
-     * Uses the MongoDB driver's `session.withTransaction()` which automatically retries
-     * on `TransientTransactionError` and `UnknownTransactionCommitResult`.
-     *
-     * The callback always receives a `ClientSession`. When `allowFallback` is true
-     * and the MongoDB deployment doesn't support transactions (e.g., standalone),
-     * the callback runs without a transaction on the same session.
-     *
-     * @param callback - Receives a `ClientSession` to pass to repository operations
-     * @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
-     * @param options.onFallback - Called when falling back to non-transactional execution
-     * @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
-     *
-     * @example
-     * ```typescript
-     * const result = await repo.withTransaction(async (session) => {
-     *   const order = await repo.create({ total: 100 }, { session });
-     *   await paymentRepo.create({ orderId: order._id }, { session });
-     *   return order;
-     * });
-     *
-     * // With fallback for standalone/dev environments
-     * await repo.withTransaction(callback, {
-     *   allowFallback: true,
-     *   onFallback: (err) => logger.warn('Running without transaction', err),
-     * });
-     * ```
-     */
-    withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
-    private _isTransactionUnsupported;
-    /**
-     * Execute custom query with event emission
-     */
-    _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
-    /**
-     * Build operation context and run before hooks
-     */
-    _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
-    /**
-     * Parse sort string or object
-     */
-    _parseSort(sort: SortSpec$2 | string | undefined): SortSpec$2;
-    /**
-     * Parse populate specification
-     */
-    _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
-    /**
-     * Handle errors with proper HTTP status codes
-     */
-    _handleError(error: Error): HttpError;
-}
-
-/**
- * Modern Query Parser - URL to MongoDB Query Transpiler
- *
- * Next-generation query parser that converts URL parameters to MongoDB aggregation pipelines.
- * Smarter than Prisma/tRPC for MongoDB with support for:
- * - Custom field lookups ($lookup)
- * - Complex filtering with operators
- * - Full-text search
- * - Aggregations via URL
- * - Security hardening
- *
- * @example
- * ```typescript
- * // Simple usage
- * const parser = new QueryParser();
- * const query = parser.parse(req.query);
- *
- * // URL: ?status=active&lookup[department]=slug&sort=-createdAt&page=1&limit=20
- * // Result: Complete MongoDB query with $lookup, filters, sort, pagination
- * ```
- *
- * ## SECURITY CONSIDERATIONS FOR PRODUCTION
- *
- * ### Aggregation Security (enableAggregations option)
- *
- * **IMPORTANT:** The `enableAggregations` option exposes powerful MongoDB aggregation
- * pipeline capabilities via URL parameters. While this feature includes sanitization
- * (blocks $where, $function, $accumulator), it should be used with caution:
- *
- * **Recommended security practices:**
- * 1. **Disable by default for public endpoints:**
- *    ```typescript
- *    const parser = new QueryParser({
- *      enableAggregations: false  // Default: disabled
- *    });
- *    ```
- *
- * 2. **Use per-route allowlists for trusted clients:**
- *    ```typescript
- *    // Admin/internal routes only
- *    if (req.user?.role === 'admin') {
- *      const allowedStages = ['$match', '$project', '$sort', '$limit'];
- *      // Validate aggregate parameter against allowlist
- *    }
- *    ```
- *
- * 3. **Validate stage structure:** Even with sanitization, complex pipelines can
- *    cause performance issues. Consider limiting:
- *    - Number of pipeline stages (e.g., max 5)
- *    - Specific allowed operators per stage
- *    - Allowed fields in $project/$match
- *
- * 4. **Monitor resource usage:** Aggregation pipelines can be expensive.
- *    Use MongoDB profiling to track slow operations.
- *
- * ### Lookup Security
- *
- * Lookup pipelines are sanitized by default:
- * - Dangerous stages blocked ($out, $merge, $unionWith, $collStats, $currentOp, $listSessions)
- * - Dangerous operators blocked inside $match/$addFields/$set ($where, $function, $accumulator, $expr)
- * - Optional collection whitelist via `allowedLookupCollections`
- * For maximum security, use per-collection field allowlists in your controller layer.
- *
- * ### Filter Security
- *
- * All filters are sanitized:
- * - Dangerous operators blocked ($where, $function, $accumulator, $expr)
- * - Regex patterns validated (ReDoS protection)
- * - Max filter depth enforced (prevents filter bombs)
- * - Max limit enforced (prevents resource exhaustion)
- *
- * @see {@link https://github.com/classytic/mongokit/blob/main/docs/SECURITY.md}
- */
-
-type SortSpec = Record<string, 1 | -1>;
-type FilterQuery = Record<string, unknown>;
-/**
- * Mongoose-compatible populate option
- * Supports advanced populate with select, match, limit, sort, and nested populate
- *
- * @example
- * ```typescript
- * // URL: ?populate[author][select]=name,email&populate[author][match][active]=true
- * // Generates: { path: 'author', select: 'name email', match: { active: true } }
- * ```
- */
-interface PopulateOption {
-    /** Field path to populate */
-    path: string;
-    /** Fields to select (space-separated) */
-    select?: string;
-    /** Filter conditions for populated documents */
-    match?: Record<string, unknown>;
-    /** Query options (limit, sort, skip) */
-    options?: {
-        limit?: number;
-        sort?: SortSpec;
-        skip?: number;
-    };
-    /** Nested populate configuration */
-    populate?: PopulateOption;
-}
-/** Parsed query result with optional lookup configuration */
-interface ParsedQuery {
-    /** MongoDB filter query */
-    filters: FilterQuery;
-    /** Sort specification */
-    sort?: SortSpec;
-    /** Fields to populate (simple comma-separated string) */
-    populate?: string;
-    /**
-     * Advanced populate options (Mongoose-compatible)
-     * When this is set, `populate` will be undefined
-     * @example [{ path: 'author', select: 'name email' }]
-     */
-    populateOptions?: PopulateOption[];
-    /** Page number for offset pagination */
-    page?: number;
-    /** Cursor for keyset pagination */
-    after?: string;
-    /** Limit */
-    limit: number;
-    /** Full-text search query */
-    search?: string;
-    /** Lookup configurations for custom field joins */
-    lookups?: LookupOptions[];
-    /** Aggregation pipeline stages (advanced) */
-    aggregation?: PipelineStage[];
-    /** Select/project fields */
-    select?: Record<string, 0 | 1>;
-}
-/** Search mode for query parser */
-type SearchMode = 'text' | 'regex';
-interface QueryParserOptions {
-    /** Maximum allowed regex pattern length (default: 500) */
-    maxRegexLength?: number;
-    /** Maximum allowed text search query length (default: 200) */
-    maxSearchLength?: number;
-    /** Maximum allowed filter depth (default: 10) */
-    maxFilterDepth?: number;
-    /** Maximum allowed limit value (default: 1000) */
-    maxLimit?: number;
-    /** Additional operators to block */
-    additionalDangerousOperators?: string[];
-    /** Enable lookup parsing (default: true) */
-    enableLookups?: boolean;
-    /** Enable aggregation parsing (default: false - requires explicit opt-in) */
-    enableAggregations?: boolean;
-    /**
-     * Search mode (default: 'text')
-     * - 'text': Uses MongoDB $text search (requires text index)
-     * - 'regex': Uses $or with $regex across searchFields (no index required)
-     */
-    searchMode?: SearchMode;
-    /**
-     * Fields to search when searchMode is 'regex'
-     * Required when searchMode is 'regex'
-     * @example ['name', 'description', 'sku', 'tags']
-     */
-    searchFields?: string[];
-    /**
-     * Whitelist of collection names allowed in lookups.
-     * When set, only these collections can be used in $lookup stages.
-     * When undefined, all collection names are allowed.
-     * @example ['departments', 'categories', 'users']
-     */
-    allowedLookupCollections?: string[];
-}
-/**
- * Modern Query Parser
- * Converts URL parameters to MongoDB queries with $lookup support
- */
-declare class QueryParser {
-    private readonly options;
-    private readonly operators;
-    private readonly dangerousOperators;
-    /**
-     * Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
-     * Detects:
-     * - Quantifiers: {n,m}
-     * - Possessive quantifiers: *+, ++, ?+
-     * - Nested quantifiers: (a+)+, (a*)*
-     * - Backreferences: \1, \2, etc.
-     * - Complex character classes: [...]...[...]
-     */
-    private readonly dangerousRegexPatterns;
-    constructor(options?: QueryParserOptions);
-    /**
-     * Parse URL query parameters into MongoDB query format
-     *
-     * @example
-     * ```typescript
-     * // URL: ?status=active&lookup[department][foreignField]=slug&sort=-createdAt&page=1
-     * const query = parser.parse(req.query);
-     * // Returns: { filters: {...}, lookups: [...], sort: {...}, page: 1 }
-     * ```
-     */
-    parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
-    /**
-     * Parse lookup configurations from URL parameters
-     *
-     * Supported formats:
-     * 1. Simple: ?lookup[department]=slug
-     *    → Join with 'departments' collection on slug field
-     *
-     * 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
-     *    → Full control over join configuration
-     *
-     * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
-     *    → Multiple lookups
-     *
-     * @example
-     * ```typescript
-     * // URL: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug&lookup[department][single]=true
-     * const lookups = parser._parseLookups({
-     *   department: { localField: 'deptSlug', foreignField: 'slug', single: 'true' }
-     * });
-     * // Returns: [{ from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true }]
-     * ```
-     */
-    private _parseLookups;
-    /**
-     * Parse a single lookup configuration
-     */
-    private _parseSingleLookup;
-    /**
-     * Parse aggregation pipeline from URL (advanced feature)
-     *
-     * @example
-     * ```typescript
-     * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
-     * const pipeline = parser._parseAggregation({
-     *   group: { _id: '$status', count: '$sum:1' }
-     * });
-     * ```
-     */
-    private _parseAggregation;
-    /**
-     * Parse select/project fields
-     *
-     * @example
-     * ```typescript
-     * // URL: ?select=name,email,-password
-     * // Returns: { name: 1, email: 1, password: 0 }
-     * ```
-     */
-    private _parseSelect;
-    /**
-     * Parse populate parameter - handles both simple string and advanced object format
-     *
-     * @example
-     * ```typescript
-     * // Simple: ?populate=author,category
-     * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
-     *
-     * // Advanced: ?populate[author][select]=name,email
-     * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
-     * ```
-     */
-    private _parsePopulate;
-    /**
-     * Parse a single populate configuration
-     */
-    private _parseSinglePopulate;
-    /**
-     * Convert populate match values (handles boolean strings, etc.)
-     */
-    private _convertPopulateMatch;
-    /**
-     * Parse filter parameters
-     */
-    private _parseFilters;
-    /**
-     * Handle operator syntax: field[operator]=value
-     */
-    private _handleOperatorSyntax;
-    /**
-     * Handle bracket syntax with object value
-     */
-    private _handleBracketSyntax;
-    private _parseSort;
-    private _toMongoOperator;
-    private _createSafeRegex;
-    private _escapeRegex;
-    /**
-     * Sanitize $match configuration to prevent dangerous operators
-     * Recursively filters out operators like $where, $function, $accumulator
-     */
-    private _sanitizeMatchConfig;
-    /**
-     * Sanitize pipeline stages for use in $lookup.
-     * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
-     * operator expressions within $match, $addFields, and $set stages.
-     */
-    private _sanitizePipeline;
-    /**
-     * Recursively sanitize expression objects, blocking dangerous operators
-     * like $where, $function, $accumulator inside $addFields/$set stages.
-     */
-    private _sanitizeExpressions;
-    private _sanitizeSearch;
-    /**
-     * Build regex-based multi-field search filters
-     * Creates an $or query with case-insensitive regex across all searchFields
-     *
-     * @example
-     * // searchFields: ['name', 'description', 'sku']
-     * // search: 'azure'
-     * // Returns: [
-     * //   { name: { $regex: /azure/i } },
-     * //   { description: { $regex: /azure/i } },
-     * //   { sku: { $regex: /azure/i } }
-     * // ]
-     */
-    private _buildRegexSearch;
-    private _convertValue;
-    private _parseOr;
-    private _enhanceWithBetween;
-    private _pluralize;
-    private _capitalize;
-}
-
-/**
- * Factory function to create a repository instance
- *
- * @param Model - Mongoose model
- * @param plugins - Array of plugins to apply
- * @returns Repository instance
- *
- * @example
- * const userRepo = createRepository(UserModel, [timestampPlugin()]);
- */
-declare function createRepository<TDoc>(Model: mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
-
-export { AggregatePaginationResult, AggregationBuilder, AnyDocument, type FilterQuery, HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, KeysetPaginationResult, LookupBuilder, LookupOptions, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PaginationResult, type ParsedQuery, PluginType, type PopulateOption, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, type SearchMode, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };