@classytic/mongokit 3.2.0 → 3.2.2

package/dist/types-D-gploPr.d.mts

@@ -0,0 +1,1241 @@
+import * as mongoose$1 from "mongoose";
+import { ClientSession, Document, Model, PipelineStage, PopulateOptions, Types } from "mongoose";
+
+//#region src/query/LookupBuilder.d.ts
+interface LookupOptions {
+  /** Collection to join with */
+  from: string;
+  /** Field from the input documents */
+  localField: string;
+  /** Field from the documents of the "from" collection */
+  foreignField: string;
+  /** Name of the new array field to add to the input documents */
+  as?: string;
+  /** Whether to unwrap array to single object */
+  single?: boolean;
+  /** Additional pipeline to run on the joined collection */
+  pipeline?: PipelineStage[];
+  /** Optional let variables for pipeline */
+  let?: Record<string, string>;
+  /** Query filter to apply before join (legacy, for aggregate.ts compatibility) */
+  query?: Record<string, unknown>;
+  /** Query options (legacy, for aggregate.ts compatibility) */
+  options?: {
+    session?: ClientSession;
+  };
+  /** Sanitize pipeline stages (default: true). Set false only for trusted server-side pipelines */
+  sanitize?: boolean;
+}
+/**
+ * Fluent builder for MongoDB $lookup aggregation stage
+ * Optimized for custom field joins at scale
+ */
+declare class LookupBuilder {
+  private options;
+  constructor(from?: string);
+  /**
+   * Set the collection to join with
+   */
+  from(collection: string): this;
+  /**
+   * Set the local field (source collection)
+   * IMPORTANT: This field should be indexed for optimal performance
+   */
+  localField(field: string): this;
+  /**
+   * Set the foreign field (target collection)
+   * IMPORTANT: This field should be indexed (preferably unique) for optimal performance
+   */
+  foreignField(field: string): this;
+  /**
+   * Set the output field name
+   * Defaults to the collection name if not specified
+   */
+  as(fieldName: string): this;
+  /**
+   * Mark this lookup as returning a single document
+   * Automatically unwraps the array result to a single object or null
+   */
+  single(isSingle?: boolean): this;
+  /**
+   * Add a pipeline to filter/transform joined documents
+   * Useful for filtering, sorting, or limiting joined results
+   *
+   * @example
+   * ```typescript
+   * lookup.pipeline([
+   *   { $match: { status: 'active' } },
+   *   { $sort: { priority: -1 } },
+   *   { $limit: 5 }
+   * ]);
+   * ```
+   */
+  pipeline(stages: PipelineStage[]): this;
+  /**
+   * Set let variables for use in pipeline
+   * Allows referencing local document fields in the pipeline
+   */
+  let(variables: Record<string, string>): this;
+  /**
+   * Build the $lookup aggregation stage(s)
+   * Returns an array of pipeline stages including $lookup and optional $unwind
+   *
+   * IMPORTANT: MongoDB $lookup has two mutually exclusive forms:
+   * 1. Simple form: { from, localField, foreignField, as }
+   * 2. Pipeline form: { from, let, pipeline, as }
+   *
+   * When pipeline or let is specified, we use the pipeline form.
+   * Otherwise, we use the simpler localField/foreignField form.
+   */
+  build(): PipelineStage[];
+  /**
+   * Build and return only the $lookup stage (without $unwind)
+   * Useful when you want to handle unwrapping yourself
+   */
+  buildLookupOnly(): PipelineStage.Lookup;
+  /**
+   * Static helper: Create a simple lookup in one line
+   */
+  static simple(from: string, localField: string, foreignField: string, options?: {
+    as?: string;
+    single?: boolean;
+  }): PipelineStage[];
+  /**
+   * Static helper: Create multiple lookups at once
+   *
+   * @example
+   * ```typescript
+   * const pipeline = LookupBuilder.multiple([
+   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+   * ]);
+   * ```
+   */
+  static multiple(lookups: LookupOptions[]): PipelineStage[];
+  /**
+   * Static helper: Create a nested lookup (lookup within lookup)
+   * Useful for multi-level joins like Order -> Product -> Category
+   *
+   * @example
+   * ```typescript
+   * // Join orders with products, then products with categories
+   * const pipeline = LookupBuilder.nested([
+   *   { from: 'products', localField: 'productSku', foreignField: 'sku', as: 'product', single: true },
+   *   { from: 'categories', localField: 'product.categorySlug', foreignField: 'slug', as: 'product.category', single: true }
+   * ]);
+   * ```
+   */
+  static nested(lookups: LookupOptions[]): PipelineStage[];
+  /**
+   * Sanitize pipeline stages by blocking dangerous stages and operators.
+   * Used internally by build() and available for external use (e.g., aggregate.ts).
+   */
+  static sanitizePipeline(stages: PipelineStage[]): PipelineStage[];
+  /**
+   * Recursively remove dangerous operators from an expression object.
+   */
+  private static _sanitizeDeep;
+}
+//#endregion
+//#region src/types/controller.types.d.ts
+/**
+ * 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>>;
+}
+//#endregion
+//#region src/types.d.ts
+/** Read Preference Type for replica sets */
+type ReadPreferenceType = "primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest" | (string & {});
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Generic model type */
+type AnyModel = Model<AnyDocument>;
+/** Sort direction */
+type SortDirection = 1 | -1;
+/** Sort specification for MongoDB queries */
+type SortSpec = Record<string, SortDirection>;
+/** Populate specification */
+type PopulateSpec = string | string[] | PopulateOptions | PopulateOptions[];
+/** Select specification */
+type SelectSpec = string | string[] | Record<string, 0 | 1>;
+/** Filter query type for MongoDB queries (compatible with Mongoose 8 & 9) */
+type FilterQuery<_T = unknown> = Record<string, unknown>;
+/**
+ * Infer document type from a Mongoose Model
+ * @example
+ * type UserDoc = InferDocument<typeof UserModel>;
+ */
+type InferDocument<TModel> = TModel extends Model<infer TDoc> ? TDoc : never;
+/**
+ * Infer raw document shape (without Mongoose Document methods)
+ * @example
+ * type User = InferRawDoc<typeof UserModel>;
+ */
+type InferRawDoc<TModel> = TModel extends Model<infer TDoc> ? TDoc extends Document ? Omit<TDoc, keyof Document> : TDoc : never;
+/**
+ * Make specific fields optional
+ * @example
+ * type CreateUser = PartialBy<User, 'createdAt' | 'updatedAt'>;
+ */
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Make specific fields required
+ * @example
+ * type UserWithId = RequiredBy<User, '_id'>;
+ */
+type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Extract keys of type T that have values of type V
+ * @example
+ * type StringFields = KeysOfType<User, string>; // 'name' | 'email'
+ */
+type KeysOfType<T, V> = { [K in keyof T]: T[K] extends V ? K : never }[keyof T];
+/**
+ * Deep partial - makes all nested properties optional
+ */
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+/**
+ * Strict object type - prevents excess properties
+ * Use with `satisfies` for compile-time validation
+ */
+type Strict<T> = T & { [K in Exclude<string, keyof T>]?: never };
+/**
+ * NonNullable fields extractor
+ */
+type NonNullableFields<T> = { [K in keyof T]: NonNullable<T[K]> };
+/**
+ * Create/Update input types from document
+ */
+type CreateInput<TDoc> = Omit<TDoc, "_id" | "createdAt" | "updatedAt" | "__v">;
+type UpdateInput<TDoc> = Partial<Omit<TDoc, "_id" | "createdAt" | "__v">>;
+/** Hook execution mode */
+type HookMode = "sync" | "async";
+/** Repository options */
+interface RepositoryOptions {
+  /** Whether repository event hooks are awaited */
+  hooks?: HookMode;
+}
+/** Pagination configuration */
+interface PaginationConfig {
+  /** Default number of documents per page (default: 10) */
+  defaultLimit?: number;
+  /** Maximum allowed limit (default: 100) */
+  maxLimit?: number;
+  /** Maximum allowed page number (default: 10000) */
+  maxPage?: number;
+  /** Page number that triggers performance warning (default: 100) */
+  deepPageThreshold?: number;
+  /** Cursor version for forward compatibility (default: 1) */
+  cursorVersion?: number;
+  /** Use estimatedDocumentCount for faster counts on large collections */
+  useEstimatedCount?: boolean;
+}
+/** Base pagination options */
+interface BasePaginationOptions {
+  /** Pagination mode (explicit override) */
+  mode?: "offset" | "keyset";
+  /** MongoDB query filters */
+  filters?: FilterQuery<AnyDocument>;
+  /** Sort specification */
+  sort?: SortSpec;
+  /** Number of documents per page */
+  limit?: number;
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Fields to populate */
+  populate?: PopulateSpec;
+  /** Return plain JavaScript objects */
+  lean?: boolean;
+  /** MongoDB session for transactions */
+  session?: ClientSession;
+  /** Query hint (index name or document) */
+  hint?: string | Record<string, 1 | -1>;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+}
+/** Offset pagination options */
+interface OffsetPaginationOptions extends BasePaginationOptions {
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Count strategy for filtered queries (default: 'exact') */
+  countStrategy?: "exact" | "estimated" | "none";
+}
+/** Keyset (cursor) pagination options */
+interface KeysetPaginationOptions extends BasePaginationOptions {
+  /** Cursor token for next page */
+  after?: string;
+  /** Sort is required for keyset pagination */
+  sort: SortSpec;
+}
+/** Aggregate pagination options */
+interface AggregatePaginationOptions {
+  /** Aggregation pipeline stages */
+  pipeline?: PipelineStage[];
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Number of documents per page */
+  limit?: number;
+  /** MongoDB session for transactions */
+  session?: ClientSession;
+  /** Query hint (index name or document) for aggregation */
+  hint?: string | Record<string, 1 | -1>;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Count strategy (default: 'exact' via $facet) */
+  countStrategy?: "exact" | "none";
+  /** Pagination mode (reserved for API consistency) */
+  mode?: "offset";
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+}
+/** Offset pagination result */
+interface OffsetPaginationResult<T = unknown> {
+  /** Pagination method used */
+  method: "offset";
+  /** Array of documents */
+  docs: T[];
+  /** Current page number */
+  page: number;
+  /** Documents per page */
+  limit: number;
+  /** Total document count */
+  total: number;
+  /** Total page count */
+  pages: number;
+  /** Whether next page exists */
+  hasNext: boolean;
+  /** Whether previous page exists */
+  hasPrev: boolean;
+  /** Performance warning for deep pagination */
+  warning?: string;
+}
+/** Keyset pagination result */
+interface KeysetPaginationResult<T = unknown> {
+  /** Pagination method used */
+  method: "keyset";
+  /** Array of documents */
+  docs: T[];
+  /** Documents per page */
+  limit: number;
+  /** Whether more documents exist */
+  hasMore: boolean;
+  /** Cursor token for next page */
+  next: string | null;
+}
+/** Aggregate pagination result */
+interface AggregatePaginationResult<T = unknown> {
+  /** Pagination method used */
+  method: "aggregate";
+  /** Array of documents */
+  docs: T[];
+  /** Current page number */
+  page: number;
+  /** Documents per page */
+  limit: number;
+  /** Total document count */
+  total: number;
+  /** Total page count */
+  pages: number;
+  /** Whether next page exists */
+  hasNext: boolean;
+  /** Whether previous page exists */
+  hasPrev: boolean;
+  /** Performance warning for deep pagination */
+  warning?: string;
+}
+/** Union type for all pagination results */
+type PaginationResult<T = unknown> = OffsetPaginationResult<T> | KeysetPaginationResult<T> | AggregatePaginationResult<T>;
+/** Repository operation options */
+interface OperationOptions {
+  /** MongoDB session for transactions */
+  session?: ClientSession;
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Fields to populate */
+  populate?: PopulateSpec;
+  /** Return plain JavaScript objects */
+  lean?: boolean;
+  /** Throw error if document not found (default: true) */
+  throwOnNotFound?: boolean;
+  /** Additional query filters (e.g., for soft delete) */
+  query?: Record<string, unknown>;
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: "primary" | "primaryPreferred" | "secondary" | "secondaryPreferred" | "nearest" | string;
+}
+/** withTransaction options */
+interface WithTransactionOptions {
+  /** Allow non-transactional fallback when transactions are unsupported */
+  allowFallback?: boolean;
+  /** Optional hook to observe fallback triggers */
+  onFallback?: (error: Error) => void;
+  /** MongoDB transaction options (readConcern, writeConcern, readPreference, maxCommitTimeMS) */
+  transactionOptions?: mongoose$1.mongo.TransactionOptions;
+}
+/** Create operation options */
+interface CreateOptions {
+  /** MongoDB session for transactions */
+  session?: ClientSession;
+  /** Keep insertion order on error (default: true) */
+  ordered?: boolean;
+}
+/** Update operation options */
+interface UpdateOptions extends OperationOptions {
+  /** Enable update pipeline syntax */
+  updatePipeline?: boolean;
+}
+/** Delete result */
+interface DeleteResult {
+  success: boolean;
+  message: string;
+  count?: number;
+}
+/** Update many result */
+interface UpdateManyResult {
+  matchedCount: number;
+  modifiedCount: number;
+}
+/** Validation result */
+interface ValidationResult {
+  valid: boolean;
+  violations?: Array<{
+    field: string;
+    reason: string;
+  }>;
+  message?: string;
+}
+/** Update with validation result */
+type UpdateWithValidationResult<T> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: {
+    code: number;
+    message: string;
+    violations?: ValidationResult["violations"];
+  };
+};
+/** User context for operations */
+interface UserContext {
+  _id?: ObjectId | string;
+  id?: string;
+  roles?: string | string[];
+  [key: string]: unknown;
+}
+/** Repository operation context */
+interface RepositoryContext {
+  /** Operation name */
+  operation: string;
+  /** Model name */
+  model: string;
+  /** Document data (for create/update) */
+  data?: Record<string, unknown>;
+  /** Array of documents (for createMany) */
+  dataArray?: Record<string, unknown>[];
+  /** Document ID (for update/delete/getById) */
+  id?: string | ObjectId;
+  /** Query filters */
+  query?: FilterQuery<AnyDocument>;
+  /** User making the request */
+  user?: UserContext;
+  /** Organization ID for multi-tenancy */
+  organizationId?: string | ObjectId;
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Fields to populate */
+  populate?: PopulateSpec;
+  /** Return lean documents */
+  lean?: boolean;
+  /** MongoDB session */
+  session?: ClientSession;
+  /** Read preference for replica sets */
+  readPreference?: ReadPreferenceType;
+  /** Pagination filters */
+  filters?: Record<string, unknown>;
+  /** Sort specification */
+  sort?: SortSpec;
+  /** Page number (offset pagination) */
+  page?: number;
+  /** Items per page */
+  limit?: number;
+  /** Cursor for next page (keyset pagination) */
+  after?: string;
+  /** Search query string */
+  search?: string;
+  /** Pagination mode */
+  mode?: "offset" | "keyset";
+  /** Query hint */
+  hint?: string | Record<string, 1 | -1>;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Count strategy for offset pagination */
+  countStrategy?: "exact" | "estimated" | "none";
+  /** Whether this is a soft delete operation (set by softDeletePlugin) */
+  softDeleted?: boolean;
+  /** Include soft-deleted documents in queries */
+  includeDeleted?: boolean;
+  /** Skip cache for this operation */
+  skipCache?: boolean;
+  /** Custom TTL for this operation (seconds) */
+  cacheTtl?: number;
+  /** Whether result was served from cache (internal) */
+  _cacheHit?: boolean;
+  /** Cached result (internal) */
+  _cachedResult?: unknown;
+  /** IDs to cascade delete (internal) */
+  _cascadeIds?: unknown[];
+  /** Custom context data from plugins */
+  [key: string]: unknown;
+}
+/** Plugin interface */
+interface Plugin {
+  /** Plugin name */
+  name: string;
+  /** Apply plugin to repository */
+  apply(repo: RepositoryInstance): void;
+}
+/** Plugin function signature */
+type PluginFunction = (repo: RepositoryInstance) => void;
+/** Plugin type (object or function) */
+type PluginType = Plugin | PluginFunction;
+/** Repository instance for plugin type reference */
+interface RepositoryInstance {
+  Model: Model<any>;
+  model: string;
+  _hooks: Map<string, Array<(data: any) => void | Promise<void>>>;
+  _pagination: unknown;
+  use(plugin: PluginType): this;
+  on(event: string, listener: (data: any) => void | Promise<void>): this;
+  off(event: string, listener: (data: any) => void | Promise<void>): this;
+  removeAllListeners(event?: string): this;
+  emit(event: string, data: unknown): void;
+  emitAsync(event: string, data: unknown): Promise<void>;
+  registerMethod?(name: string, fn: Function): void;
+  hasMethod?(name: string): boolean;
+  [key: string]: unknown;
+}
+/** Repository operation names */
+type RepositoryOperation = "create" | "createMany" | "update" | "updateMany" | "delete" | "deleteMany" | "getById" | "getByQuery" | "getAll" | "aggregatePaginate" | "lookupPopulate";
+/** Event lifecycle phases */
+type EventPhase = "before" | "after" | "error";
+/** Repository event names (generated from template literals) */
+type RepositoryEvent = `${EventPhase}:${RepositoryOperation}` | "method:registered" | "error:hook";
+/**
+ * Type-safe event handler map
+ *
+ * Hook signature contract:
+ * - `before:*` — receives `context: RepositoryContext` directly (not wrapped).
+ *   Plugins mutate context in-place to inject filters, data, etc.
+ * - `after:*`  — receives `{ context, result }` where result is the operation output.
+ * - `error:*`  — receives `{ context, error }` where error is the caught Error.
+ */
+type EventHandlers<TDoc = unknown> = { [K in RepositoryEvent]?: K extends `before:${string}` ? (context: RepositoryContext) => void | Promise<void> : K extends `after:${string}` ? (payload: {
+  context: RepositoryContext;
+  result: TDoc | TDoc[];
+}) => void | Promise<void> : K extends `error:${string}` ? (payload: {
+  context: RepositoryContext;
+  error: Error;
+}) => void | Promise<void> : (payload: {
+  context: RepositoryContext;
+}) => void | Promise<void> };
+/** Event payload */
+interface EventPayload {
+  context: RepositoryContext;
+  result?: unknown;
+  error?: Error;
+}
+/** Field preset configuration */
+interface FieldPreset {
+  /** Fields visible to everyone */
+  public: string[];
+  /** Additional fields for authenticated users */
+  authenticated?: string[];
+  /** Additional fields for admins */
+  admin?: string[];
+}
+/** Field rules for schema building */
+interface FieldRules {
+  [fieldName: string]: {
+    /** Field cannot be updated */immutable?: boolean; /** Alias for immutable */
+    immutableAfterCreate?: boolean; /** System-only field (omitted from create/update) */
+    systemManaged?: boolean; /** Remove from required array */
+    optional?: boolean;
+  };
+}
+/** Schema builder options */
+interface SchemaBuilderOptions {
+  /** Field rules for create/update */
+  fieldRules?: FieldRules;
+  /** Strict additional properties (default: false) */
+  strictAdditionalProperties?: boolean;
+  /** Date format: 'date' | 'datetime' */
+  dateAs?: "date" | "datetime";
+  /** Create schema options */
+  create?: {
+    /** Fields to omit from create schema */omitFields?: string[]; /** Override required status */
+    requiredOverrides?: Record<string, boolean>; /** Override optional status */
+    optionalOverrides?: Record<string, boolean>; /** Schema overrides */
+    schemaOverrides?: Record<string, unknown>;
+  };
+  /** Update schema options */
+  update?: {
+    /** Fields to omit from update schema */omitFields?: string[]; /** Require at least one field to be provided (default: false) */
+    requireAtLeastOne?: boolean;
+  };
+  /** Query schema options */
+  query?: {
+    /** Filterable fields */filterableFields?: Record<string, {
+      type: string;
+    } | unknown>;
+  };
+}
+/** JSON Schema type */
+interface JsonSchema {
+  type: string;
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean | unknown;
+  items?: unknown;
+  enum?: string[];
+  format?: string;
+  pattern?: string;
+  minProperties?: number;
+  maxProperties?: number;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+}
+/** CRUD schemas result - framework-agnostic JSON schemas */
+interface CrudSchemas {
+  /** JSON Schema for create request body */
+  createBody: JsonSchema;
+  /** JSON Schema for update request body */
+  updateBody: JsonSchema;
+  /** JSON Schema for route params (id validation) */
+  params: JsonSchema;
+  /** JSON Schema for list/query parameters */
+  listQuery: JsonSchema;
+}
+/** Decoded cursor */
+interface DecodedCursor {
+  /** Primary sort field value (rehydrated) */
+  value: unknown;
+  /** Document ID (rehydrated) */
+  id: ObjectId | string;
+  /** Sort specification */
+  sort: SortSpec;
+  /** Cursor version */
+  version: number;
+}
+/** Validator definition */
+interface ValidatorDefinition {
+  /** Validator name */
+  name: string;
+  /** Operations to apply validator to */
+  operations?: Array<"create" | "createMany" | "update" | "delete">;
+  /** Validation function */
+  validate: (context: RepositoryContext, repo?: RepositoryInstance) => void | Promise<void>;
+}
+/** Validation chain options */
+interface ValidationChainOptions {
+  /** Stop on first validation error (default: true) */
+  stopOnFirstError?: boolean;
+}
+/** Logger interface for audit plugin */
+interface Logger {
+  info?(message: string, meta?: Record<string, unknown>): void;
+  error?(message: string, meta?: Record<string, unknown>): void;
+  warn?(message: string, meta?: Record<string, unknown>): void;
+  debug?(message: string, meta?: Record<string, unknown>): void;
+}
+/** Filter mode for soft delete queries */
+type SoftDeleteFilterMode = "null" | "exists";
+/** Soft delete plugin options */
+interface SoftDeleteOptions {
+  /** Field name for deletion timestamp (default: 'deletedAt') */
+  deletedField?: string;
+  /** Field name for deleting user (default: 'deletedBy') */
+  deletedByField?: string;
+  /** Enable soft delete (default: true) */
+  soft?: boolean;
+  /**
+   * Filter mode for excluding deleted documents (default: 'null')
+   * - 'null': Filters where deletedField is null (works with `default: null` in schema)
+   * - 'exists': Filters where deletedField does not exist (legacy behavior)
+   */
+  filterMode?: SoftDeleteFilterMode;
+  /** Add restore method to repository (default: true) */
+  addRestoreMethod?: boolean;
+  /** Add getDeleted method to repository (default: true) */
+  addGetDeletedMethod?: boolean;
+  /**
+   * TTL in days for auto-cleanup of deleted documents.
+   * When set, creates a TTL index on the deletedField.
+   * Documents will be automatically removed after the specified days.
+   */
+  ttlDays?: number;
+}
+/** Repository with soft delete methods */
+interface SoftDeleteRepository {
+  /**
+   * Restore a soft-deleted document by setting deletedAt to null
+   * @param id - Document ID to restore
+   * @param options - Optional session for transactions
+   * @returns The restored document
+   */
+  restore(id: string | ObjectId, options?: {
+    session?: ClientSession;
+  }): Promise<unknown>;
+  /**
+   * Get all soft-deleted documents
+   * @param params - Query parameters (filters, pagination, etc.)
+   * @param options - Query options (select, populate, etc.)
+   * @returns Paginated result of deleted documents
+   */
+  getDeleted(params?: {
+    filters?: Record<string, unknown>;
+    sort?: SortSpec | string;
+    page?: number;
+    limit?: number;
+  }, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    lean?: boolean;
+    session?: ClientSession;
+  }): Promise<OffsetPaginationResult<unknown>>;
+}
+/** Group result */
+interface GroupResult {
+  _id: unknown;
+  count: number;
+}
+/** Min/Max result */
+interface MinMaxResult {
+  min: unknown;
+  max: unknown;
+}
+/**
+ * Cache adapter interface - bring your own cache implementation
+ * Works with Redis, Memcached, in-memory, or any key-value store
+ *
+ * @example Redis implementation:
+ * ```typescript
+ * const redisCache: CacheAdapter = {
+ *   async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
+ *   async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
+ *   async del(key) { await redis.del(key); },
+ *   async clear(pattern) {
+ *     const keys = await redis.keys(pattern || '*');
+ *     if (keys.length) await redis.del(...keys);
+ *   }
+ * };
+ * ```
+ */
+interface CacheAdapter {
+  /** Get value by key, returns null if not found or expired */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /** Set value with TTL in seconds */
+  set<T = unknown>(key: string, value: T, ttl: number): Promise<void>;
+  /** Delete single key */
+  del(key: string): Promise<void>;
+  /** Clear keys matching pattern (optional, used for bulk invalidation) */
+  clear?(pattern?: string): Promise<void>;
+}
+/** Cache plugin options */
+interface CacheOptions {
+  /** Cache adapter implementation (required) */
+  adapter: CacheAdapter;
+  /** Default TTL in seconds (default: 60) */
+  ttl?: number;
+  /** TTL for byId queries in seconds (default: same as ttl) */
+  byIdTtl?: number;
+  /** TTL for query/list results in seconds (default: same as ttl) */
+  queryTtl?: number;
+  /** Key prefix for namespacing (default: 'mk') */
+  prefix?: string;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+  /**
+   * Skip caching for queries with these characteristics:
+   * - largeLimit: Skip if limit > value (default: 100)
+   */
+  skipIf?: {
+    largeLimit?: number;
+  };
+}
+/** Options for cache-aware operations */
+interface CacheOperationOptions {
+  /** Skip cache for this operation (read from DB directly) */
+  skipCache?: boolean;
+  /** Custom TTL for this operation in seconds */
+  cacheTtl?: number;
+}
+/** Cache statistics (for debugging/monitoring) */
+interface CacheStats {
+  hits: number;
+  misses: number;
+  sets: number;
+  invalidations: number;
+}
+/** Cascade relation definition */
+interface CascadeRelation {
+  /** Model name to cascade delete to */
+  model: string;
+  /** Foreign key field in the related model that references the deleted document */
+  foreignKey: string;
+  /** Whether to use soft delete if available (default: follows parent behavior) */
+  softDelete?: boolean;
+}
+/** Cascade delete plugin options */
+interface CascadeOptions {
+  /** Relations to cascade delete */
+  relations: CascadeRelation[];
+  /** Run cascade deletes in parallel (default: true) */
+  parallel?: boolean;
+  /** Logger for cascade operations */
+  logger?: Logger;
+}
+/** HTTP Error with status code */
+interface HttpError extends Error {
+  status: number;
+  validationErrors?: Array<{
+    validator: string;
+    error: string;
+  }>;
+}
+/**
+ * Combines all plugin method types into a single type
+ * Useful when you're using all plugins and want full type safety
+ *
+ * @example
+ * ```typescript
+ * import { Repository } from '@classytic/mongokit';
+ * import type { AllPluginMethods } from '@classytic/mongokit';
+ *
+ * class UserRepo extends Repository<IUser> {}
+ *
+ * const repo = new UserRepo(Model, [...allPlugins]) as UserRepo & AllPluginMethods<IUser>;
+ *
+ * // TypeScript knows about all plugin methods!
+ * await repo.increment(id, 'views', 1);
+ * await repo.restore(id);
+ * await repo.invalidateCache(id);
+ * ```
+ *
+ * Note: Import the individual plugin method types if you need them:
+ * ```typescript
+ * import type {
+ *   MongoOperationsMethods,
+ *   BatchOperationsMethods,
+ *   AggregateHelpersMethods,
+ *   SubdocumentMethods,
+ *   SoftDeleteMethods,
+ *   CacheMethods,
+ * } from '@classytic/mongokit';
+ * ```
+ */
+type AllPluginMethods<TDoc> = {
+  upsert(query: Record<string, unknown>, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+  increment(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+  decrement(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+  pushToArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  pullFromArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  addToSet(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  setField(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  unsetField(id: string | ObjectId, fields: string | string[], options?: Record<string, unknown>): Promise<TDoc>;
+  renameField(id: string | ObjectId, oldName: string, newName: string, options?: Record<string, unknown>): Promise<TDoc>;
+  multiplyField(id: string | ObjectId, field: string, multiplier: number, options?: Record<string, unknown>): Promise<TDoc>;
+  setMin(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  setMax(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  updateMany(query: Record<string, unknown>, data: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    updatePipeline?: boolean;
+  }): Promise<{
+    acknowledged: boolean;
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedCount: number;
+    upsertedId: unknown;
+  }>;
+  deleteMany(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<{
+    acknowledged: boolean;
+    deletedCount: number;
+  }>;
+  groupBy(field: string, options?: {
+    limit?: number;
+    session?: unknown;
+  }): Promise<Array<{
+    _id: unknown;
+    count: number;
+  }>>;
+  sum(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  average(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  min(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+  addSubdocument(parentId: string | ObjectId, arrayPath: string, subData: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+  getSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: {
+    lean?: boolean;
+    session?: unknown;
+  }): Promise<Record<string, unknown>>;
+  updateSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, updateData: Record<string, unknown>, options?: {
+    session?: unknown;
+  }): Promise<TDoc>;
+  deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
+  restore(id: string | ObjectId, options?: {
+    session?: ClientSession;
+  }): Promise<TDoc>;
+  getDeleted(params?: {
+    filters?: Record<string, unknown>;
+    sort?: SortSpec | string;
+    page?: number;
+    limit?: number;
+  }, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    lean?: boolean;
+    session?: ClientSession;
+  }): Promise<OffsetPaginationResult<TDoc>>;
+  invalidateCache(id: string): Promise<void>;
+  invalidateListCache(): Promise<void>;
+  invalidateAllCache(): Promise<void>;
+  getCacheStats(): CacheStats;
+  resetCacheStats(): void;
+};
+/**
+ * Helper type to add all plugin methods to a repository class
+ * Cleaner than manually typing the intersection
+ *
+ * @example
+ * ```typescript
+ * import { Repository } from '@classytic/mongokit';
+ * import type { WithPlugins } from '@classytic/mongokit';
+ *
+ * class OrderRepo extends Repository<IOrder> {
+ *   async getCustomerOrders(customerId: string) {
+ *     return this.getAll({ filters: { customerId } });
+ *   }
+ * }
+ *
+ * const orderRepo = new OrderRepo(Model, [
+ *   ...allPlugins
+ * ]) as WithPlugins<IOrder, OrderRepo>;
+ *
+ * // Works: custom methods + plugin methods
+ * await orderRepo.getCustomerOrders('123');
+ * await orderRepo.increment(orderId, 'total', 100);
+ * ```
+ */
+type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
+//#endregion
+export { SchemaBuilderOptions as $, KeysetPaginationOptions as A, PaginationResult as B, GroupResult as C, InferRawDoc as D, InferDocument as E, ObjectId as F, PopulateSpec as G, Plugin as H, OffsetPaginationOptions as I, RepositoryEvent as J, ReadPreferenceType as K, OffsetPaginationResult as L, Logger as M, MinMaxResult as N, JsonSchema as O, NonNullableFields as P, RequiredBy as Q, OperationOptions as R, FieldRules as S, LookupOptions as St, HttpError as T, PluginFunction as U, PartialBy as V, PluginType as W, RepositoryOperation as X, RepositoryInstance as Y, RepositoryOptions as Z, DeleteResult as _, IController as _t, AnyModel as a, SortSpec as at, EventPhase as b, IResponseFormatter as bt, CacheOptions as c, UpdateManyResult as ct, CascadeRelation as d, UserContext as dt, SelectSpec as et, CreateInput as f, ValidationChainOptions as ft, DeepPartial as g, WithTransactionOptions as gt, DecodedCursor as h, WithPlugins as ht, AnyDocument as i, SortDirection as it, KeysetPaginationResult as j, KeysOfType as k, CacheStats as l, UpdateOptions as lt, CrudSchemas as m, ValidatorDefinition as mt, AggregatePaginationResult as n, SoftDeleteOptions as nt, CacheAdapter as o, Strict as ot, CreateOptions as p, ValidationResult as pt, RepositoryContext as q, AllPluginMethods as r, SoftDeleteRepository as rt, CacheOperationOptions as s, UpdateInput as st, AggregatePaginationOptions as t, SoftDeleteFilterMode as tt, CascadeOptions as u, UpdateWithValidationResult as ut, EventHandlers as v, IControllerResponse as vt, HookMode as w, FieldPreset as x, LookupBuilder as xt, EventPayload as y, IRequestContext as yt, PaginationConfig as z };