@classytic/mongokit 3.3.1 → 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,135 +427,435 @@ 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
-   *
-   * 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
+   * 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
    *
-   * @example
-   * // Offset pagination (page-based)
-   * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
-   * await repo.getAll({ pagination: { page: 2, limit: 20 } });
+   * Supported formats:
+   * 1. Simple: ?lookup[department]=slug
+   *    → Join with 'departments' collection on slug field
    *
-   * // Keyset pagination (cursor-based)
-   * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
-   * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+   * 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
+   *    → Full control over join configuration
    *
-   * // Simple query (defaults to page 1)
-   * await repo.getAll({ filters: { status: 'active' } });
+   * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
+   *    → Multiple lookups
    *
-   * // Skip cache for fresh data
-   * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
-   */
+   * @example
+   * ```typescript
+   * // URL: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug&lookup[department][single]=true
+   * const lookups = parser._parseLookups({
+   *   department: { localField: 'deptSlug', foreignField: 'slug', single: 'true' }
+   * });
+   * // Returns: [{ from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true }]
+   * ```
+   */
+  private _parseLookups;
+  /**
+   * Parse a single lookup configuration
+   */
+  private _parseSingleLookup;
+  /**
+   * Parse aggregation pipeline from URL (advanced feature)
+   *
+   * @example
+   * ```typescript
+   * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
+   * const pipeline = parser._parseAggregation({
+   *   group: { _id: '$status', count: '$sum:1' }
+   * });
+   * ```
+   */
+  private _parseAggregation;
+  /**
+   * Parse select/project fields
+   *
+   * @example
+   * ```typescript
+   * // URL: ?select=name,email,-password
+   * // Returns: { name: 1, email: 1, password: 0 }
+   * ```
+   */
+  private _parseSelect;
+  /**
+   * Parse populate parameter - handles both simple string and advanced object format
+   *
+   * @example
+   * ```typescript
+   * // Simple: ?populate=author,category
+   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+   *
+   * // Advanced: ?populate[author][select]=name,email
+   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+   * ```
+   */
+  private _parsePopulate;
+  /**
+   * Parse a single populate configuration
+   */
+  private _parseSinglePopulate;
+  /**
+   * Convert populate match values (handles boolean strings, etc.)
+   */
+  private _convertPopulateMatch;
+  /**
+   * Parse filter parameters
+   */
+  private _parseFilters;
+  /**
+   * Handle operator syntax: field[operator]=value
+   */
+  private _handleOperatorSyntax;
+  /**
+   * Handle bracket syntax with object value
+   */
+  private _handleBracketSyntax;
+  private _parseSort;
+  private _toMongoOperator;
+  private _createSafeRegex;
+  private _escapeRegex;
+  /**
+   * Sanitize $match configuration to prevent dangerous operators
+   * Recursively filters out operators like $where, $function, $accumulator
+   */
+  private _sanitizeMatchConfig;
+  /**
+   * Sanitize pipeline stages for use in $lookup.
+   * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
+   * operator expressions within $match, $addFields, and $set stages.
+   */
+  private _sanitizePipeline;
+  /**
+   * Recursively sanitize expression objects, blocking dangerous operators
+   * like $where, $function, $accumulator inside $addFields/$set stages.
+   */
+  private _sanitizeExpressions;
+  private _sanitizeSearch;
+  /**
+   * Build regex-based multi-field search filters
+   * Creates an $or query with case-insensitive regex across all searchFields
+   *
+   * @example
+   * // searchFields: ['name', 'description', 'sku']
+   * // search: 'azure'
+   * // Returns: [
+   * //   { name: { $regex: /azure/i } },
+   * //   { description: { $regex: /azure/i } },
+   * //   { sku: { $regex: /azure/i } }
+   * // ]
+   */
+  private _buildRegexSearch;
+  private _convertValue;
+  private _parseOr;
+  private _enhanceWithBetween;
+  private _pluralize;
+  private _capitalize;
+}
+//#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);
+  /**
+   * Register a plugin
+   */
+  use(plugin: PluginType): this;
+  /**
+   * 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)
+   */
+  on(event: string, listener: HookListener, options?: {
+    priority?: number;
+  }): this;
+  /**
+   * Remove a specific event listener
+   */
+  off(event: string, listener: HookListener): this;
+  /**
+   * Remove all listeners for an event, or all listeners entirely
+   */
+  removeAllListeners(event?: string): this;
+  /**
+   * Emit event (sync - for backwards compatibility)
+   */
+  emit(event: string, data: unknown): void;
+  /**
+   * Emit event and await all async handlers (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
+   * // Offset pagination (page-based)
+   * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
+   * await repo.getAll({ pagination: { page: 2, limit: 20 } });
+   *
+   * // Keyset pagination (cursor-based)
+   * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
+   * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+   *
+   * // Simple query (defaults to page 1)
+   * await repo.getAll({ filters: { status: 'active' } });
+   *
+   * // Skip cache for fresh data
+   * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+   */
   getAll(params?: {
     filters?: Record<string, unknown>;
     sort?: SortSpec | string;
@@ -569,12 +868,13 @@ declare class Repository<TDoc = any> {
     };
     limit?: number;
     search?: string;
-    mode?: "offset" | "keyset";
+    mode?: 'offset' | 'keyset';
     hint?: string | Record<string, 1 | -1>;
     maxTimeMS?: number;
-    countStrategy?: "exact" | "estimated" | "none";
+    countStrategy?: 'exact' | 'estimated' | 'none';
     readPreference?: ReadPreferenceType; /** Advanced populate options (from QueryParser or Arc's BaseController) */
-    populateOptions?: PopulateOptions[];
+    populateOptions?: PopulateOptions[]; /** Lookup configurations for $lookup joins (from QueryParser or manual) */
+    lookups?: LookupOptions[];
   }, options?: {
     select?: SelectSpec;
     populate?: PopulateSpec;
@@ -602,483 +902,193 @@ declare class Repository<TDoc = any> {
   }): 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.
-   */
-  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
-  /**
-   * Get distinct values
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
-   */
-  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): Promise<T[]>;
-  /**
-   * Query with custom field lookups ($lookup)
-   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
-   *
-   * @example
-   * ```typescript
-   * // Join employees with departments using slug instead of ObjectId
-   * const employees = await employeeRepo.lookupPopulate({
-   *   filters: { status: 'active' },
-   *   lookups: [
-   *     {
-   *       from: 'departments',
-   *       localField: 'departmentSlug',
-   *       foreignField: 'slug',
-   *       as: 'department',
-   *       single: true
-   *     }
-   *   ],
-   *   sort: '-createdAt',
-   *   page: 1,
-   *   limit: 50
-   * });
-   * ```
-   */
-  lookupPopulate(options: {
-    filters?: Record<string, unknown>;
-    lookups: LookupOptions[];
-    sort?: SortSpec | string;
-    page?: number;
-    limit?: number;
-    select?: SelectSpec;
-    session?: ClientSession;
-    readPreference?: ReadPreferenceType;
-  }): Promise<{
-    data: TDoc[];
-    total?: number;
-    page?: number;
-    limit?: number;
-  }>;
-  /**
-   * Create an aggregation builder for this model
-   * Useful for building complex custom aggregations
-   *
-   * @example
-   * ```typescript
-   * const pipeline = repo.buildAggregation()
-   *   .match({ status: 'active' })
-   *   .lookup('departments', 'deptSlug', 'slug', 'department', true)
-   *   .group({ _id: '$department', count: { $sum: 1 } })
-   *   .sort({ count: -1 })
-   *   .build();
-   *
-   * const results = await repo.Model.aggregate(pipeline);
-   * ```
-   */
-  buildAggregation(): AggregationBuilder;
-  /**
-   * Create a lookup builder
-   * Useful for building $lookup stages independently
-   *
-   * @example
-   * ```typescript
-   * const lookupStages = repo.buildLookup('departments')
-   *   .localField('deptSlug')
-   *   .foreignField('slug')
-   *   .as('department')
-   *   .single()
-   *   .build();
-   *
-   * const pipeline = [
-   *   { $match: { status: 'active' } },
-   *   ...lookupStages
-   * ];
-   * ```
-   */
-  buildLookup(from?: string): LookupBuilder;
-  /**
-   * Execute callback within a transaction with automatic retry on transient failures.
-   *
-   * Uses the MongoDB driver's `session.withTransaction()` which automatically retries
-   * on `TransientTransactionError` and `UnknownTransactionCommitResult`.
-   *
-   * The callback always receives a `ClientSession`. When `allowFallback` is true
-   * and the MongoDB deployment doesn't support transactions (e.g., standalone),
-   * the callback runs without a transaction on the same session.
-   *
-   * @param callback - Receives a `ClientSession` to pass to repository operations
-   * @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
-   * @param options.onFallback - Called when falling back to non-transactional execution
-   * @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
-   *
-   * @example
-   * ```typescript
-   * const result = await repo.withTransaction(async (session) => {
-   *   const order = await repo.create({ total: 100 }, { session });
-   *   await paymentRepo.create({ orderId: order._id }, { session });
-   *   return order;
-   * });
-   *
-   * // With fallback for standalone/dev environments
-   * await repo.withTransaction(callback, {
-   *   allowFallback: true,
-   *   onFallback: (err) => logger.warn('Running without transaction', err),
-   * });
-   * ```
-   */
-  withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
-  private _isTransactionUnsupported;
-  /**
-   * Execute custom query with event emission
-   */
-  _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
-  /**
-   * Build operation context and run before hooks (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
-   */
-  _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
-  /**
-   * Parse sort string or object
-   */
-  _parseSort(sort: SortSpec | string | undefined): SortSpec;
-  /**
-   * Parse populate specification
-   */
-  _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
-  /**
-   * Handle errors with proper HTTP status codes
-   */
-  _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;
-  /**
-   * Advanced populate options (Mongoose-compatible)
-   * When this is set, `populate` will be undefined
-   * @example [{ path: 'author', select: 'name email' }]
-   */
-  populateOptions?: PopulateOption[];
-  /** Page number for offset pagination */
-  page?: number;
-  /** Cursor for keyset pagination */
-  after?: string;
-  /** Limit */
-  limit: number;
-  /** Full-text search query */
-  search?: string;
-  /** Lookup configurations for custom field joins */
-  lookups?: LookupOptions[];
-  /** Aggregation pipeline stages (advanced) */
-  aggregation?: PipelineStage[];
-  /** Select/project fields */
-  select?: Record<string, 0 | 1>;
-}
-/** Search mode for query parser */
-type SearchMode = "text" | "regex";
-interface QueryParserOptions {
-  /** Maximum allowed regex pattern length (default: 500) */
-  maxRegexLength?: number;
-  /** Maximum allowed text search query length (default: 200) */
-  maxSearchLength?: number;
-  /** Maximum allowed filter depth (default: 10) */
-  maxFilterDepth?: number;
-  /** Maximum allowed limit value (default: 1000) */
-  maxLimit?: number;
-  /** Additional operators to block */
-  additionalDangerousOperators?: string[];
-  /** Enable lookup parsing (default: true) */
-  enableLookups?: boolean;
-  /** Enable aggregation parsing (default: false - requires explicit opt-in) */
-  enableAggregations?: boolean;
-  /**
-   * Search mode (default: 'text')
-   * - 'text': Uses MongoDB $text search (requires text index)
-   * - 'regex': Uses $or with $regex across searchFields (no index required)
-   */
-  searchMode?: SearchMode;
-  /**
-   * Fields to search when searchMode is 'regex'
-   * Required when searchMode is 'regex'
-   * @example ['name', 'description', 'sku', 'tags']
-   */
-  searchFields?: string[];
-  /**
-   * Whitelist of collection names allowed in lookups.
-   * When set, only these collections can be used in $lookup stages.
-   * When undefined, all collection names are allowed.
-   * @example ['departments', 'categories', 'users']
-   */
-  allowedLookupCollections?: string[];
-  /** Allowed fields for filtering. If set, ignores unknown fields. */
-  allowedFilterFields?: string[];
-  /** Allowed fields for sorting. If set, ignores unknown fields. */
-  allowedSortFields?: string[];
-  /**
-   * 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']
-   */
-  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;
-  /**
-   * 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: [...]...[...]
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  private readonly dangerousRegexPatterns;
-  constructor(options?: QueryParserOptions);
+  exists(query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<{
+    _id: unknown;
+  } | null>;
   /**
-   * 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 }
-   * ```
+   * Update document by ID
    */
-  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+  update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<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
+   * Delete document by ID
    */
-  getQuerySchema(): {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
+  delete(id: string | ObjectId, options?: {
+    session?: ClientSession;
+  }): Promise<DeleteResult>;
   /**
-   * Get the JSON Schema type for a filter operator
+   * 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
    */
-  private _getOperatorSchemaType;
+  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[]>;
   /**
-   * Get a human-readable description for a filter operator
+   * 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.
    */
-  private _getOperatorDescription;
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
   /**
-   * Build a summary description of all available filter operators
+   * Get distinct values
+   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
    */
-  private _buildOperatorDescription;
+  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<T[]>;
   /**
-   * Parse lookup configurations from URL parameters
-   *
-   * Supported formats:
-   * 1. Simple: ?lookup[department]=slug
-   *    → Join with 'departments' collection on slug field
-   *
-   * 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
-   *    → Full control over join configuration
-   *
-   * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
-   *    → Multiple lookups
+   * Query with custom field lookups ($lookup)
+   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
    *
    * @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' }
+   * // 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
    * });
-   * // Returns: [{ from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true }]
    * ```
    */
-  private _parseLookups;
-  /**
-   * Parse a single lookup configuration
-   */
-  private _parseSingleLookup;
+  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 aggregation pipeline from URL (advanced feature)
+   * Create an aggregation builder for this model
+   * Useful for building complex custom aggregations
    *
    * @example
    * ```typescript
-   * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
-   * const pipeline = parser._parseAggregation({
-   *   group: { _id: '$status', count: '$sum:1' }
-   * });
+   * 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 _parseAggregation;
+  buildAggregation(): AggregationBuilder;
   /**
-   * Parse select/project fields
+   * Create a lookup builder
+   * Useful for building $lookup stages independently
    *
    * @example
    * ```typescript
-   * // URL: ?select=name,email,-password
-   * // Returns: { name: 1, email: 1, password: 0 }
+   * const lookupStages = repo.buildLookup('departments')
+   *   .localField('deptSlug')
+   *   .foreignField('slug')
+   *   .as('department')
+   *   .single()
+   *   .build();
+   *
+   * const pipeline = [
+   *   { $match: { status: 'active' } },
+   *   ...lookupStages
+   * ];
    * ```
    */
-  private _parseSelect;
+  buildLookup(from?: string): LookupBuilder;
   /**
-   * Parse populate parameter - handles both simple string and advanced object format
+   * 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
-   * // Simple: ?populate=author,category
-   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+   * const result = await repo.withTransaction(async (session) => {
+   *   const order = await repo.create({ total: 100 }, { session });
+   *   await paymentRepo.create({ orderId: order._id }, { session });
+   *   return order;
+   * });
    *
-   * // Advanced: ?populate[author][select]=name,email
-   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+   * // With fallback for standalone/dev environments
+   * await repo.withTransaction(callback, {
+   *   allowFallback: true,
+   *   onFallback: (err) => logger.warn('Running without transaction', err),
+   * });
    * ```
    */
-  private _parsePopulate;
-  /**
-   * Parse a single populate configuration
-   */
-  private _parseSinglePopulate;
-  /**
-   * Convert populate match values (handles boolean strings, etc.)
-   */
-  private _convertPopulateMatch;
-  /**
-   * Parse filter parameters
-   */
-  private _parseFilters;
-  /**
-   * Handle operator syntax: field[operator]=value
-   */
-  private _handleOperatorSyntax;
+  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
@@ -1092,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 };