@classytic/mongokit 3.3.2 → 3.4.0

package/dist/index.d.mts

@@ -1,10 +1,9 @@
-import { $ as SchemaBuilderOptions, A as KeysetPaginationOptions, B as PaginationResult, C as GroupResult, D as InferRawDoc, E as InferDocument, F as ObjectId, G as PopulateSpec, H as Plugin, I as OffsetPaginationOptions, J as RepositoryEvent, K as ReadPreferenceType, L as OffsetPaginationResult, M as Logger, N as MinMaxResult, O as JsonSchema, P as NonNullableFields, Q as RequiredBy, R as OperationOptions, S as FieldRules, St as LookupOptions, T as HttpError, U as PluginFunction, V as PartialBy, W as PluginType, X as RepositoryOperation, Y as RepositoryInstance, Z as RepositoryOptions, _ as DeleteResult, _t as IController, a as AnyModel, at as SortSpec, b as EventPhase, bt as IResponseFormatter, c as CacheOptions, ct as UpdateManyResult, d as CascadeRelation, dt as UserContext, et as SelectSpec, f as CreateInput, ft as ValidationChainOptions, g as DeepPartial, gt as WithTransactionOptions, h as DecodedCursor, ht as WithPlugins, i as AnyDocument, it as SortDirection, j as KeysetPaginationResult, k as KeysOfType, l as CacheStats, lt as UpdateOptions, m as CrudSchemas, mt as ValidatorDefinition, n as AggregatePaginationResult, nt as SoftDeleteOptions, o as CacheAdapter, ot as Strict, p as CreateOptions, pt as ValidationResult, q as RepositoryContext, r as AllPluginMethods, rt as SoftDeleteRepository, s as CacheOperationOptions, st as UpdateInput, t as AggregatePaginationOptions, tt as SoftDeleteFilterMode, u as CascadeOptions, ut as UpdateWithValidationResult, v as EventHandlers, vt as IControllerResponse, w as HookMode, x as FieldPreset, xt as LookupBuilder, y as EventPayload, yt as IRequestContext, z as PaginationConfig } from "./types-pVY0w1Pp.mjs";
-import "./aggregate-BkOG9qwr.mjs";
-import { t as index_d_exports } from "./actions/index.mjs";
+import { $ as SchemaBuilderOptions, A as KeysetPaginationOptions, B as PaginationResult, C as GroupResult, D as InferRawDoc, E as InferDocument, F as ObjectId, G as PopulateSpec, H as Plugin, I as OffsetPaginationOptions, J as RepositoryEvent, K as ReadPreferenceType, L as OffsetPaginationResult, M as Logger, N as MinMaxResult, O as JsonSchema, P as NonNullableFields, Q as RequiredBy, R as OperationOptions, S as FieldRules, St as LookupOptions, T as HttpError, U as PluginFunction, V as PartialBy, W as PluginType, X as RepositoryOperation, Y as RepositoryInstance, Z as RepositoryOptions, _ as DeleteResult, _t as IController, a as AnyModel, at as SortSpec, b as EventPhase, bt as IResponseFormatter, c as CacheOptions, ct as UpdateManyResult, d as CascadeRelation, dt as UserContext, et as SelectSpec, f as CreateInput, ft as ValidationChainOptions, g as DeepPartial, gt as WithTransactionOptions, h as DecodedCursor, ht as WithPlugins, i as AnyDocument, it as SortDirection, j as KeysetPaginationResult, k as KeysOfType, l as CacheStats, lt as UpdateOptions, m as CrudSchemas, mt as ValidatorDefinition, n as AggregatePaginationResult, nt as SoftDeleteOptions, o as CacheAdapter, ot as Strict, p as CreateOptions, pt as ValidationResult, q as RepositoryContext, r as AllPluginMethods, rt as SoftDeleteRepository, s as CacheOperationOptions, st as UpdateInput, t as AggregatePaginationOptions, tt as SoftDeleteFilterMode, u as CascadeOptions, ut as UpdateWithValidationResult, v as EventHandlers, vt as IControllerResponse, w as HookMode, x as FieldPreset, xt as LookupBuilder, y as EventPayload, yt as IRequestContext, z as PaginationConfig } from "./types-BlCwDszq.mjs";
+import { t as index_d_exports } from "./index-Df3ernpC.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { A as subdocumentPlugin, B as immutableField, C as observabilityPlugin, D as CacheMethods, E as cascadePlugin, F as batchOperationsPlugin, G as methodRegistryPlugin, H as uniqueField, I as MongoOperationsMethods, J as auditLogPlugin, K as SoftDeleteMethods, L as mongoOperationsPlugin, M as aggregateHelpersPlugin, N as BatchOperationsMethods, O as cachePlugin, P as BulkWriteResult, R as autoInject, S as OperationMetric, T as multiTenantPlugin, U as validationChainPlugin, V as requireField, X as fieldFilterPlugin, Y as timestampPlugin, _ as AuditTrailMethods, a as SequentialIdOptions, b as auditTrailPlugin, c as getNextSequence, d as ElasticSearchOptions, f as elasticSearchPlugin, g as AuditQueryResult, h as AuditQueryOptions, i as PrefixedIdOptions, j as AggregateHelpersMethods, k as SubdocumentMethods, l as prefixedId, m as AuditOperation, n as DateSequentialIdOptions, o as customIdPlugin, p as AuditEntry, q as softDeletePlugin, r as IdGenerator, s as dateSequentialId, t as CustomIdOptions, u as sequentialId, v as AuditTrailOptions, w as MultiTenantOptions, x as ObservabilityOptions, y as AuditTrailQuery, z as blockIf } from "./custom-id.plugin-BJ3FSnzt.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as filterResponseData, f as getFieldsForUser, i as getSystemManagedFields, l as createError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as getMongooseProjection, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as createFieldPreset } from "./mongooseToJsonSchema-B6O2ED3n.mjs";
-import * as mongoose$1 from "mongoose";
+import { A as dateSequentialId, B as AuditEntry, C as elasticSearchPlugin, D as PrefixedIdOptions, E as IdGenerator, F as CacheMethods, G as AuditTrailOptions, H as AuditQueryOptions, I as cachePlugin, J as auditLogPlugin, K as AuditTrailQuery, L as BatchOperationsMethods, M as prefixedId, N as sequentialId, O as SequentialIdOptions, P as cascadePlugin, R as BulkWriteResult, S as ElasticSearchOptions, T as DateSequentialIdOptions, U as AuditQueryResult, V as AuditOperation, W as AuditTrailMethods, X as aggregateHelpersPlugin, Y as AggregateHelpersMethods, _ as MongoOperationsMethods, a as uniqueField, b as methodRegistryPlugin, c as SubdocumentMethods, d as softDeletePlugin, f as ObservabilityOptions, g as multiTenantPlugin, h as MultiTenantOptions, i as requireField, j as getNextSequence, k as customIdPlugin, l as subdocumentPlugin, m as observabilityPlugin, n as blockIf, o as validationChainPlugin, p as OperationMetric, q as auditTrailPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as SoftDeleteMethods, v as mongoOperationsPlugin, w as CustomIdOptions, x as fieldFilterPlugin, z as batchOperationsPlugin } from "./validation-chain.plugin-DxqiHv-E.mjs";
+import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BqgVOlrR.mjs";
+import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 
 //#region src/query/AggregationBuilder.d.ts
@@ -67,7 +66,7 @@ declare class AggregationBuilder {
    *   .exec(MyModel);
    * ```
    */
-  exec<T = unknown>(model: Model<any>, session?: mongoose$1.ClientSession): Promise<T[]>;
+  exec<T = unknown>(model: Model<any>, session?: _$mongoose.ClientSession): Promise<T[]>;
   /**
    * Reset the pipeline
    */
@@ -428,667 +427,668 @@ declare class AggregationBuilder {
   static startWith(query: Record<string, unknown>): AggregationBuilder;
 }
 //#endregion
-//#region src/Repository.d.ts
-type HookListener = (data: any) => void | Promise<void>;
-/** Hook with priority for phase ordering */
-interface PrioritizedHook {
-  listener: HookListener;
-  priority: number;
-}
-/**
- * Plugin phase priorities (lower = runs first)
- * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
- * to ensure filters are injected before cache keys are computed.
- */
-declare const HOOK_PRIORITY: {
-  /** Policy enforcement: tenant isolation, soft-delete filtering, validation */readonly POLICY: 100; /** Caching: lookup/store after policy filters are applied */
-  readonly CACHE: 200; /** Observability: audit logging, metrics, telemetry */
-  readonly OBSERVABILITY: 300; /** Default priority for user-registered hooks */
-  readonly DEFAULT: 500;
-};
+//#region src/query/QueryParser.d.ts
+type SortSpec$1 = Record<string, 1 | -1>;
+type FilterQuery = Record<string, unknown>;
 /**
- * Production-grade repository for MongoDB
- * Event-driven, plugin-based, with smart pagination
+ * 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 } }
+ * ```
  */
-declare class Repository<TDoc = any> {
-  readonly Model: Model<TDoc>;
-  readonly model: string;
-  readonly _hooks: Map<string, PrioritizedHook[]>;
-  readonly _pagination: PaginationEngine<TDoc>;
-  private readonly _hookMode;
-  [key: string]: unknown;
-  private _hasTextIndex;
-  constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
+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$1;
+    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$1;
+  /** Fields to populate (simple comma-separated string) */
+  populate?: string;
   /**
-   * Register a plugin
+   * Advanced populate options (Mongoose-compatible)
+   * When this is set, `populate` will be undefined
+   * @example [{ path: 'author', select: 'name email' }]
    */
-  use(plugin: PluginType): this;
+  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;
   /**
-   * Register event listener with optional priority for phase ordering.
-   *
-   * @param event - Event name (e.g. 'before:getAll')
-   * @param listener - Hook function
-   * @param options - Optional { priority } — use HOOK_PRIORITY constants.
-   *                  Lower priority numbers run first.
-   *                  Default: HOOK_PRIORITY.DEFAULT (500)
+   * Search mode (default: 'text')
+   * - 'text': Uses MongoDB $text search (requires text index)
+   * - 'regex': Uses $or with $regex across searchFields (no index required)
    */
-  on(event: string, listener: HookListener, options?: {
-    priority?: number;
-  }): this;
+  searchMode?: SearchMode;
   /**
-   * Remove a specific event listener
+   * Fields to search when searchMode is 'regex'
+   * Required when searchMode is 'regex'
+   * @example ['name', 'description', 'sku', 'tags']
    */
-  off(event: string, listener: HookListener): this;
+  searchFields?: string[];
   /**
-   * Remove all listeners for an event, or all listeners entirely
+   * 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']
    */
-  removeAllListeners(event?: string): this;
+  allowedLookupCollections?: string[];
+  /** Allowed fields for filtering. If set, ignores unknown fields. */
+  allowedFilterFields?: string[];
+  /** Allowed fields for sorting. If set, ignores unknown fields. */
+  allowedSortFields?: string[];
   /**
-   * Emit event (sync - for backwards compatibility)
+   * Whitelist of allowed filter operators.
+   * When set, only these operators can be used in filters.
+   * When undefined, all built-in operators are allowed.
+   * Values are human-readable keys: 'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin',
+   * 'like', 'contains', 'regex', 'exists', 'size', 'type'
+   * @example ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in']
    */
-  emit(event: string, data: unknown): void;
+  allowedOperators?: 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;
   /**
-   * Emit event and await all async handlers (sorted by priority)
+   * 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: [...]...[...]
    */
-  emitAsync(event: string, data: unknown): Promise<void>;
-  private _emitHook;
-  private _emitErrorHook;
+  private readonly dangerousRegexPatterns;
+  constructor(options?: QueryParserOptions);
   /**
-   * Create single document
+   * 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 }
+   * ```
    */
-  create(data: Record<string, unknown>, options?: {
-    session?: ClientSession;
-  }): Promise<TDoc>;
+  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
   /**
-   * Create multiple documents
+   * Generate OpenAPI-compatible JSON Schema for query parameters.
+   * Arc's defineResource() auto-detects this method and uses it
+   * to document list endpoint query parameters in OpenAPI/Swagger.
+   *
+   * The schema respects parser configuration:
+   * - `allowedOperators`: only documents allowed operators
+   * - `allowedFilterFields`: generates explicit field[op] entries
+   * - `enableLookups` / `enableAggregations`: includes/excludes lookup/aggregate params
+   * - `maxLimit` / `maxSearchLength`: reflected in schema constraints
    */
-  createMany(dataArray: Record<string, unknown>[], options?: {
-    session?: ClientSession;
-    ordered?: boolean;
-  }): Promise<TDoc[]>;
+  getQuerySchema(): {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
   /**
-   * Get document by ID
+   * Get the query schema with OpenAPI extensions (x-internal metadata).
+   * Use this when generating OpenAPI/Swagger docs — it includes a documentary
+   * `_filterOperators` property describing available filter operators.
+   * For validation-only schemas, use `getQuerySchema()` instead.
    */
-  getById(id: string | ObjectId, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    populateOptions?: PopulateOptions[];
-    lean?: boolean;
-    session?: ClientSession;
-    throwOnNotFound?: boolean;
-    skipCache?: boolean;
-    cacheTtl?: number;
-    readPreference?: ReadPreferenceType;
-  }): Promise<TDoc | null>;
+  getOpenAPIQuerySchema(): {
+    type: 'object';
+    properties: Record<string, unknown>;
+  };
   /**
-   * Get single document by query
+   * Get the JSON Schema type for a filter operator
    */
-  getByQuery(query: Record<string, unknown>, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    populateOptions?: PopulateOptions[];
-    lean?: boolean;
-    session?: ClientSession;
-    throwOnNotFound?: boolean;
-    skipCache?: boolean;
-    cacheTtl?: number;
-    readPreference?: ReadPreferenceType;
-  }): Promise<TDoc | null>;
+  private _getOperatorSchemaType;
   /**
-   * Unified pagination - auto-detects offset vs keyset based on params
+   * Get a human-readable description for a filter operator
+   */
+  private _getOperatorDescription;
+  /**
+   * Build a summary description of all available filter operators
+   */
+  private _buildOperatorDescription;
+  /**
+   * Parse lookup configurations from URL parameters
    *
-   * 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
+   * Supported formats:
+   * 1. Simple: ?lookup[department]=slug
+   *    → Join with 'departments' collection on slug field
    *
-   * @example
-   * // Offset pagination (page-based)
-   * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
-   * await repo.getAll({ pagination: { page: 2, limit: 20 } });
+   * 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
+   *    → Full control over join configuration
    *
-   * // Keyset pagination (cursor-based)
-   * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
-   * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+   * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
+   *    → Multiple lookups
    *
-   * // 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 | string;
-    cursor?: string;
-    after?: string;
-    page?: number;
-    pagination?: {
-      page?: number;
-      limit?: number;
-    };
-    limit?: number;
-    search?: string;
-    mode?: "offset" | "keyset";
-    hint?: string | Record<string, 1 | -1>;
-    maxTimeMS?: number;
-    countStrategy?: "exact" | "estimated" | "none";
-    readPreference?: ReadPreferenceType; /** 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;
-    readPreference?: ReadPreferenceType;
-  }): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc>>;
-  /**
-   * Get or create document
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
-   */
-  getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
-    session?: ClientSession;
-  }): Promise<TDoc | null>;
-  /**
-   * Count documents
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
-   */
-  count(query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): Promise<number>;
-  /**
-   * Check if document exists
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
-   */
-  exists(query: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): 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<DeleteResult>;
-  /**
-   * Execute aggregation pipeline
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
-   *
-   * @param pipeline - Aggregation pipeline stages
-   * @param options - Aggregation options including governance controls
-   */
-  aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: {
-    session?: ClientSession;
-    allowDiskUse?: boolean;
-    comment?: string;
-    readPreference?: ReadPreferenceType;
-    maxTimeMS?: number;
-    readConcern?: {
-      level: string;
-    };
-    collation?: Record<string, unknown>;
-    maxPipelineStages?: number;
-  }): Promise<TResult[]>;
-  /**
-   * Aggregate pipeline with pagination
-   * Best for: Complex queries, grouping, joins
-   *
-   * Policy hooks (multi-tenant, soft-delete) inject context.filters which are
-   * prepended as a $match stage to the pipeline, ensuring tenant isolation.
+   * @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 }]
+   * ```
    */
-  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  private _parseLookups;
   /**
-   * Get distinct values
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+   * Parse a single lookup configuration
    */
-  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): Promise<T[]>;
+  private _parseSingleLookup;
   /**
-   * Query with custom field lookups ($lookup)
-   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
+   * Parse aggregation pipeline from URL (advanced feature)
    *
    * @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
+   * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
+   * const pipeline = parser._parseAggregation({
+   *   group: { _id: '$status', count: '$sum:1' }
    * });
    * ```
    */
-  lookupPopulate(options: {
-    filters?: Record<string, unknown>;
-    lookups: LookupOptions[];
-    sort?: SortSpec | string;
-    page?: number;
-    limit?: number;
-    select?: SelectSpec;
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): Promise<{
-    data: TDoc[];
-    total?: number;
-    page?: number;
-    limit?: number;
-  }>;
+  private _parseAggregation;
   /**
-   * Create an aggregation builder for this model
-   * Useful for building complex custom aggregations
+   * Parse select/project fields
    *
    * @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);
+   * // URL: ?select=name,email,-password
+   * // Returns: { name: 1, email: 1, password: 0 }
    * ```
    */
-  buildAggregation(): AggregationBuilder;
+  private _parseSelect;
   /**
-   * Create a lookup builder
-   * Useful for building $lookup stages independently
+   * Parse populate parameter - handles both simple string and advanced object format
    *
    * @example
    * ```typescript
-   * const lookupStages = repo.buildLookup('departments')
-   *   .localField('deptSlug')
-   *   .foreignField('slug')
-   *   .as('department')
-   *   .single()
-   *   .build();
+   * // Simple: ?populate=author,category
+   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
    *
-   * const pipeline = [
-   *   { $match: { status: 'active' } },
-   *   ...lookupStages
-   * ];
+   * // Advanced: ?populate[author][select]=name,email
+   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
    * ```
    */
-  buildLookup(from?: string): LookupBuilder;
+  private _parsePopulate;
   /**
-   * 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),
-   * });
-   * ```
+   * Parse a single populate configuration
    */
-  withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
-  private _isTransactionUnsupported;
+  private _parseSinglePopulate;
   /**
-   * Execute custom query with event emission
+   * Convert populate match values (handles boolean strings, etc.)
    */
-  _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
+  private _convertPopulateMatch;
   /**
-   * Build operation context and run before hooks (sorted by priority).
-   *
-   * Hook execution order is deterministic:
-   * 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
-   * 2. CACHE  (200) — cache lookup (after policy filters are injected)
-   * 3. OBSERVABILITY (300) — audit logging, metrics
-   * 4. DEFAULT (500) — user-registered hooks
+   * Parse filter parameters
    */
-  _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
+  private _parseFilters;
   /**
-   * Parse sort string or object
+   * Handle operator syntax: field[operator]=value
    */
-  _parseSort(sort: SortSpec | string | undefined): SortSpec;
+  private _handleOperatorSyntax;
   /**
-   * Parse populate specification
+   * Handle bracket syntax with object value
    */
-  _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
+  private _handleBracketSyntax;
+  private _parseSort;
+  private _toMongoOperator;
+  private _createSafeRegex;
+  private _escapeRegex;
   /**
-   * Handle errors with proper HTTP status codes
+   * Sanitize $match configuration to prevent dangerous operators
+   * Recursively filters out operators like $where, $function, $accumulator
    */
-  _handleError(error: Error): HttpError;
-}
-//#endregion
-//#region src/query/QueryParser.d.ts
-type SortSpec$1 = 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$1;
-    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$1;
-  /** Fields to populate (simple comma-separated string) */
-  populate?: string;
+  private _sanitizeMatchConfig;
   /**
-   * Advanced populate options (Mongoose-compatible)
-   * When this is set, `populate` will be undefined
-   * @example [{ path: 'author', select: 'name email' }]
+   * Sanitize pipeline stages for use in $lookup.
+   * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
+   * operator expressions within $match, $addFields, and $set stages.
    */
-  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>;
+  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;
 }
-/** 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;
+//#endregion
+//#region src/Repository.d.ts
+type HookListener = (data: any) => void | Promise<void>;
+/** Hook with priority for phase ordering */
+interface PrioritizedHook {
+  listener: HookListener;
+  priority: number;
+}
+/**
+ * Plugin phase priorities (lower = runs first)
+ * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
+ * to ensure filters are injected before cache keys are computed.
+ */
+declare const HOOK_PRIORITY: {
+  /** Policy enforcement: tenant isolation, soft-delete filtering, validation */readonly POLICY: 100; /** Caching: lookup/store after policy filters are applied */
+  readonly CACHE: 200; /** Observability: audit logging, metrics, telemetry */
+  readonly OBSERVABILITY: 300; /** Default priority for user-registered hooks */
+  readonly DEFAULT: 500;
+};
+/**
+ * Production-grade repository for MongoDB
+ * Event-driven, plugin-based, with smart pagination
+ */
+declare class Repository<TDoc = any> {
+  readonly Model: Model<TDoc>;
+  readonly model: string;
+  readonly _hooks: Map<string, PrioritizedHook[]>;
+  readonly _pagination: PaginationEngine<TDoc>;
+  private readonly _hookMode;
+  [key: string]: unknown;
+  private _hasTextIndex;
+  constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
   /**
-   * Search mode (default: 'text')
-   * - 'text': Uses MongoDB $text search (requires text index)
-   * - 'regex': Uses $or with $regex across searchFields (no index required)
+   * Register a plugin
    */
-  searchMode?: SearchMode;
+  use(plugin: PluginType): this;
   /**
-   * Fields to search when searchMode is 'regex'
-   * Required when searchMode is 'regex'
-   * @example ['name', 'description', 'sku', 'tags']
+   * Register event listener with optional priority for phase ordering.
+   *
+   * @param event - Event name (e.g. 'before:getAll')
+   * @param listener - Hook function
+   * @param options - Optional { priority } — use HOOK_PRIORITY constants.
+   *                  Lower priority numbers run first.
+   *                  Default: HOOK_PRIORITY.DEFAULT (500)
    */
-  searchFields?: string[];
+  on(event: string, listener: HookListener, options?: {
+    priority?: number;
+  }): this;
   /**
-   * 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']
+   * Remove a specific event listener
    */
-  allowedLookupCollections?: string[];
-  /** Allowed fields for filtering. If set, ignores unknown fields. */
-  allowedFilterFields?: string[];
-  /** Allowed fields for sorting. If set, ignores unknown fields. */
-  allowedSortFields?: string[];
+  off(event: string, listener: HookListener): this;
   /**
-   * Whitelist of allowed filter operators.
-   * When set, only these operators can be used in filters.
-   * When undefined, all built-in operators are allowed.
-   * Values are human-readable keys: 'eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin',
-   * 'like', 'contains', 'regex', 'exists', 'size', 'type'
-   * @example ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in']
+   * Remove all listeners for an event, or all listeners entirely
    */
-  allowedOperators?: 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;
+  removeAllListeners(event?: string): this;
   /**
-   * 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: [...]...[...]
+   * Emit event (sync - for backwards compatibility)
    */
-  private readonly dangerousRegexPatterns;
-  constructor(options?: QueryParserOptions);
+  emit(event: string, data: unknown): void;
   /**
-   * Parse URL query parameters into MongoDB query format
+   * Emit event and await all async handlers (sorted by priority)
+   */
+  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;
+    readPreference?: ReadPreferenceType;
+  }): 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;
+    readPreference?: ReadPreferenceType;
+  }): 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
-   * ```typescript
-   * // URL: ?status=active&lookup[department][foreignField]=slug&sort=-createdAt&page=1
-   * const query = parser.parse(req.query);
-   * // Returns: { filters: {...}, lookups: [...], sort: {...}, page: 1 }
-   * ```
+   * // 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 });
    */
-  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+  getAll(params?: {
+    filters?: Record<string, unknown>;
+    sort?: SortSpec | string;
+    cursor?: string;
+    after?: string;
+    page?: number;
+    pagination?: {
+      page?: number;
+      limit?: number;
+    };
+    limit?: number;
+    search?: string;
+    mode?: 'offset' | 'keyset';
+    hint?: string | Record<string, 1 | -1>;
+    maxTimeMS?: number;
+    countStrategy?: 'exact' | 'estimated' | 'none';
+    readPreference?: ReadPreferenceType; /** Advanced populate options (from QueryParser or Arc's BaseController) */
+    populateOptions?: PopulateOptions[]; /** Lookup configurations for $lookup joins (from QueryParser or manual) */
+    lookups?: LookupOptions[];
+  }, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    populateOptions?: PopulateOptions[];
+    lean?: boolean;
+    session?: ClientSession;
+    skipCache?: boolean;
+    cacheTtl?: number;
+    readPreference?: ReadPreferenceType;
+  }): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc>>;
   /**
-   * Generate OpenAPI-compatible JSON Schema for query parameters.
-   * Arc's defineResource() auto-detects this method and uses it
-   * to document list endpoint query parameters in OpenAPI/Swagger.
-   *
-   * The schema respects parser configuration:
-   * - `allowedOperators`: only documents allowed operators
-   * - `allowedFilterFields`: generates explicit field[op] entries
-   * - `enableLookups` / `enableAggregations`: includes/excludes lookup/aggregate params
-   * - `maxLimit` / `maxSearchLength`: reflected in schema constraints
+   * Get or create document
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  getQuerySchema(): {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
+  getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
+    session?: ClientSession;
+  }): Promise<TDoc | null>;
   /**
-   * Get the query schema with OpenAPI extensions (x-internal metadata).
-   * Use this when generating OpenAPI/Swagger docs — it includes a documentary
-   * `_filterOperators` property describing available filter operators.
-   * For validation-only schemas, use `getQuerySchema()` instead.
+   * Count documents
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  getOpenAPIQuerySchema(): {
-    type: "object";
-    properties: Record<string, unknown>;
-  };
+  count(query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<number>;
   /**
-   * Get the JSON Schema type for a filter operator
+   * Check if document exists
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  private _getOperatorSchemaType;
+  exists(query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<{
+    _id: unknown;
+  } | null>;
   /**
-   * Get a human-readable description for a filter operator
+   * Update document by ID
    */
-  private _getOperatorDescription;
+  update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
   /**
-   * Build a summary description of all available filter operators
+   * Delete document by ID
    */
-  private _buildOperatorDescription;
+  delete(id: string | ObjectId, options?: {
+    session?: ClientSession;
+  }): Promise<DeleteResult>;
   /**
-   * 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
+   * Execute aggregation pipeline
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    *
-   * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
-   *    → Multiple lookups
+   * @param pipeline - Aggregation pipeline stages
+   * @param options - Aggregation options including governance controls
+   */
+  aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: {
+    session?: ClientSession;
+    allowDiskUse?: boolean;
+    comment?: string;
+    readPreference?: ReadPreferenceType;
+    maxTimeMS?: number;
+    readConcern?: {
+      level: string;
+    };
+    collation?: Record<string, unknown>;
+    maxPipelineStages?: number;
+  }): Promise<TResult[]>;
+  /**
+   * Aggregate pipeline with pagination
+   * Best for: Complex queries, grouping, joins
    *
-   * @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 }]
-   * ```
+   * Policy hooks (multi-tenant, soft-delete) inject context.filters which are
+   * prepended as a $match stage to the pipeline, ensuring tenant isolation.
    */
-  private _parseLookups;
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
   /**
-   * Parse a single lookup configuration
+   * Get distinct values
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  private _parseSingleLookup;
+  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<T[]>;
   /**
-   * Parse aggregation pipeline from URL (advanced feature)
+   * Query with custom field lookups ($lookup)
+   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
    *
    * @example
    * ```typescript
-   * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
-   * const pipeline = parser._parseAggregation({
-   *   group: { _id: '$status', count: '$sum:1' }
+   * // 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
    * });
    * ```
    */
-  private _parseAggregation;
+  lookupPopulate(options: {
+    filters?: Record<string, unknown>;
+    lookups: LookupOptions[];
+    sort?: SortSpec | string;
+    page?: number;
+    limit?: number;
+    select?: SelectSpec;
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<{
+    data: TDoc[];
+    total?: number;
+    page?: number;
+    limit?: number;
+  }>;
   /**
-   * Parse select/project fields
+   * Create an aggregation builder for this model
+   * Useful for building complex custom aggregations
    *
    * @example
    * ```typescript
-   * // URL: ?select=name,email,-password
-   * // Returns: { name: 1, email: 1, password: 0 }
+   * 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);
    * ```
    */
-  private _parseSelect;
+  buildAggregation(): AggregationBuilder;
   /**
-   * Parse populate parameter - handles both simple string and advanced object format
+   * Create a lookup builder
+   * Useful for building $lookup stages independently
    *
    * @example
    * ```typescript
-   * // Simple: ?populate=author,category
-   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+   * const lookupStages = repo.buildLookup('departments')
+   *   .localField('deptSlug')
+   *   .foreignField('slug')
+   *   .as('department')
+   *   .single()
+   *   .build();
    *
-   * // Advanced: ?populate[author][select]=name,email
-   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+   * const pipeline = [
+   *   { $match: { status: 'active' } },
+   *   ...lookupStages
+   * ];
    * ```
    */
-  private _parsePopulate;
-  /**
-   * Parse a single populate configuration
-   */
-  private _parseSinglePopulate;
-  /**
-   * Convert populate match values (handles boolean strings, etc.)
-   */
-  private _convertPopulateMatch;
-  /**
-   * Parse filter parameters
-   */
-  private _parseFilters;
+  buildLookup(from?: string): LookupBuilder;
   /**
-   * Handle operator syntax: field[operator]=value
+   * 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),
+   * });
+   * ```
    */
-  private _handleOperatorSyntax;
+  withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
+  private _isTransactionUnsupported;
   /**
-   * Handle bracket syntax with object value
+   * Execute custom query with event emission
    */
-  private _handleBracketSyntax;
-  private _parseSort;
-  private _toMongoOperator;
-  private _createSafeRegex;
-  private _escapeRegex;
+  _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
   /**
-   * Sanitize $match configuration to prevent dangerous operators
-   * Recursively filters out operators like $where, $function, $accumulator
+   * Build operation context and run before hooks (sorted by priority).
+   *
+   * Hook execution order is deterministic:
+   * 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
+   * 2. CACHE  (200) — cache lookup (after policy filters are injected)
+   * 3. OBSERVABILITY (300) — audit logging, metrics
+   * 4. DEFAULT (500) — user-registered hooks
    */
-  private _sanitizeMatchConfig;
+  _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
   /**
-   * Sanitize pipeline stages for use in $lookup.
-   * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
-   * operator expressions within $match, $addFields, and $set stages.
+   * Parse sort string or object
    */
-  private _sanitizePipeline;
+  _parseSort(sort: SortSpec | string | undefined): SortSpec;
   /**
-   * Recursively sanitize expression objects, blocking dangerous operators
-   * like $where, $function, $accumulator inside $addFields/$set stages.
+   * Parse populate specification
    */
-  private _sanitizeExpressions;
-  private _sanitizeSearch;
+  _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
   /**
-   * 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 } }
-   * // ]
+   * Handle errors with proper HTTP status codes
    */
-  private _buildRegexSearch;
-  private _convertValue;
-  private _parseOr;
-  private _enhanceWithBetween;
-  private _pluralize;
-  private _capitalize;
+  _handleError(error: Error): HttpError;
 }
 //#endregion
 //#region src/index.d.ts
@@ -1102,6 +1102,6 @@ declare class QueryParser {
  * @example
  * const userRepo = createRepository(UserModel, [timestampPlugin()]);
  */
-declare function createRepository<TDoc>(Model: mongoose$1.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
+declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { type AggregateHelpersMethods, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CascadeOptions, type CascadeRelation, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SearchMode, type SelectSpec, type SequentialIdOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };
+export { type AggregateHelpersMethods, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CascadeOptions, type CascadeRelation, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FilterQuery, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SearchMode, type SelectSpec, type SequentialIdOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };