@classytic/mongokit 3.0.6 → 3.1.1

package/dist/index.d.ts

@@ -1,11 +1,704 @@
-import { A as AnyDocument, g as PluginType, P as PaginationConfig, R as RepositoryOptions, h as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec, a as OffsetPaginationResult, b as KeysetPaginationResult, U as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, i as RepositoryContext, H as HttpError } from './types-DDDYo18H.js';
-export { c as AggregatePaginationOptions, j as AnyModel, Z as CacheAdapter, $ as CacheOperationOptions, _ as CacheOptions, a0 as CacheStats, a2 as CascadeOptions, a1 as CascadeRelation, C as CreateOptions, z as CrudSchemas, B as DecodedCursor, D as DeleteResult, E as EventPayload, F as FieldPreset, x as FieldRules, w as FilterQuery, X as GroupResult, l as HookMode, J as JsonSchema, K as KeysetPaginationOptions, L as Logger, T as LookupOptions, Y as MinMaxResult, O as OffsetPaginationOptions, n as OperationOptions, m as PaginationResult, v as ParsedQuery, r as Plugin, s as PluginFunction, u as RepositoryEvent, t as RepositoryInstance, y as SchemaBuilderOptions, N as SoftDeleteFilterMode, M as SoftDeleteOptions, Q as SoftDeleteRepository, k as SortDirection, o as UpdateManyResult, p as UpdateWithValidationResult, q as UserContext, I as ValidationChainOptions, V as ValidationResult, G as ValidatorDefinition } from './types-DDDYo18H.js';
+import { i as PaginationResult, A as AnyDocument, j as PluginType, P as PaginationConfig, R as RepositoryOptions, k as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, l as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, m as RepositoryContext, H as HttpError } from './types-DA0rs2Jh.js';
+export { c as AggregatePaginationOptions, n as AnyModel, C as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, v as CreateInput, y as CreateOptions, h as CrudSchemas, $ as DecodedCursor, D as DeepPartial, z as DeleteResult, X as EventHandlers, Y as EventPayload, Q as EventPhase, F as FieldPreset, Z as FieldRules, a6 as GroupResult, p as HookMode, I as InferDocument, q as InferRawDoc, _ as JsonSchema, t as KeysOfType, K as KeysetPaginationOptions, a2 as Logger, a7 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, x as OperationOptions, r as PartialBy, G as Plugin, J as PluginFunction, T as RepositoryEvent, L as RepositoryInstance, M as RepositoryOperation, s as RequiredBy, g as SchemaBuilderOptions, a4 as SoftDeleteFilterMode, a3 as SoftDeleteOptions, a5 as SoftDeleteRepository, o as SortDirection, u as Strict, w as UpdateInput, B as UpdateManyResult, E as UpdateWithValidationResult, U as UserContext, a1 as ValidationChainOptions, V as ValidationResult, a0 as ValidatorDefinition } from './types-DA0rs2Jh.js';
 import * as mongoose from 'mongoose';
-import { Model, ClientSession, PipelineStage, PopulateOptions } from 'mongoose';
+import { PipelineStage, Expression, Model, ClientSession, PopulateOptions } from 'mongoose';
 import { PaginationEngine } from './pagination/PaginationEngine.js';
+import { L as LookupOptions, a as LookupBuilder } from './index-C2NCVxJK.js';
+export { i as actions } from './index-C2NCVxJK.js';
 export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
-export { F as FilterValue, O as OperatorMap, Q as QueryParser, b as QueryParserOptions, h as buildCrudSchemasFromModel, e as buildCrudSchemasFromMongooseSchema, l as createError, c as createFieldPreset, m as createMemoryCache, f as filterResponseData, g as getFieldsForUser, i as getImmutableFields, a as getMongooseProjection, j as getSystemManagedFields, k as isFieldUpdateAllowed, d as queryParser, v as validateUpdateBody } from './queryParser-Do3SgsyJ.js';
-export { i as actions } from './index-CkwbNdpJ.js';
+export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k 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-BKMxPbPp.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>>;
+}
+
+/**
+ * AggregationBuilder - Fluent MongoDB Aggregation Pipeline Builder
+ *
+ * Modern, type-safe builder for complex MongoDB aggregations.
+ * Supports MongoDB 6+ features with optimized query patterns.
+ *
+ * Features:
+ * - Fluent, chainable API
+ * - $lookup with custom field joins
+ * - Faceted search
+ * - Window functions ($setWindowFields)
+ * - Atlas Search ($search)
+ * - Union queries ($unionWith)
+ * - Full aggregation operator support
+ *
+ * @example
+ * ```typescript
+ * const pipeline = new AggregationBuilder()
+ *   .match({ status: 'active' })
+ *   .lookup('departments', 'deptSlug', 'slug', 'department', true)
+ *   .sort({ createdAt: -1 })
+ *   .limit(50)
+ *   .project({ password: 0 })
+ *   .build();
+ *
+ * const results = await Model.aggregate(pipeline);
+ * ```
+ */
+
+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;
+    /**
+     * Get the current pipeline
+     */
+    get(): PipelineStage[];
+    /**
+     * Build and return the final pipeline
+     */
+    build(): PipelineStage[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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
@@ -127,7 +820,7 @@ declare class Repository<TDoc = AnyDocument> {
      */
     getAll(params?: {
         filters?: Record<string, unknown>;
-        sort?: SortSpec | string;
+        sort?: SortSpec$2 | string;
         cursor?: string;
         after?: string;
         page?: number;
@@ -200,6 +893,81 @@ declare class Repository<TDoc = AnyDocument> {
     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
      */
@@ -216,7 +984,7 @@ declare class Repository<TDoc = AnyDocument> {
     /**
      * Parse sort string or object
      */
-    _parseSort(sort: SortSpec | string | undefined): SortSpec;
+    _parseSort(sort: SortSpec$2 | string | undefined): SortSpec$2;
     /**
      * Parse populate specification
      */
@@ -227,6 +995,227 @@ declare class Repository<TDoc = AnyDocument> {
     _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
+ *
+ * Lookups are sanitized by default (collection whitelists, field validation,
+ * pipeline/let blocking). For maximum security, use per-collection field allowlists
+ * in your controller layer (see BaseController example).
+ *
+ * ### 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>;
+/** Parsed query result with optional lookup configuration */
+interface ParsedQuery {
+    /** MongoDB filter query */
+    filters: FilterQuery;
+    /** Sort specification */
+    sort?: SortSpec;
+    /** Fields to populate (ObjectId-based) */
+    populate?: string;
+    /** 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>;
+}
+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;
+}
+/**
+ * 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 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;
+    private _sanitizeSearch;
+    private _convertValue;
+    private _parseOr;
+    private _enhanceWithBetween;
+    private _pluralize;
+    private _capitalize;
+}
+
 /**
  * Factory function to create a repository instance
  *
@@ -239,4 +1228,4 @@ declare class Repository<TDoc = AnyDocument> {
  */
 declare function createRepository<TDoc>(Model: mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 
-export { AggregatePaginationResult, AnyDocument, HttpError, KeysetPaginationResult, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PluginType, PopulateSpec, Repository, RepositoryContext, RepositoryOptions, SelectSpec, SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };
+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, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };