@classytic/mongokit 3.2.0 → 3.2.2

package/dist/index.d.mts

@@ -0,0 +1,1012 @@
+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-D-gploPr.mjs";
+import "./aggregate-CCHI7F51.mjs";
+import { t as index_d_exports } from "./actions/index.mjs";
+import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
+import { A as blockIf, B as timestampPlugin, C as AggregateHelpersMethods, D as MongoOperationsMethods, E as batchOperationsPlugin, I as methodRegistryPlugin, L as SoftDeleteMethods, M as requireField, N as uniqueField, O as mongoOperationsPlugin, P as validationChainPlugin, R as softDeletePlugin, S as subdocumentPlugin, T as BatchOperationsMethods, V as fieldFilterPlugin, _ as multiTenantPlugin, a as SequentialIdOptions, b as cachePlugin, c as getNextSequence, d as ElasticSearchOptions, f as elasticSearchPlugin, g as MultiTenantOptions, h as observabilityPlugin, i as PrefixedIdOptions, j as immutableField, k as autoInject, l as prefixedId, m as OperationMetric, n as DateSequentialIdOptions, o as customIdPlugin, p as ObservabilityOptions, r as IdGenerator, s as dateSequentialId, t as CustomIdOptions, u as sequentialId, v as cascadePlugin, w as aggregateHelpersPlugin, x as SubdocumentMethods, y as CacheMethods, z as auditLogPlugin } from "./custom-id.plugin-BzZI4gnE.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-Wbvjfwkn.mjs";
+import * as mongoose$1 from "mongoose";
+import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
+
+//#region src/query/AggregationBuilder.d.ts
+/** Options for $vectorSearch stage (Atlas only) */
+interface VectorSearchOptions {
+  /** Atlas Search index name */
+  index: string;
+  /** Field path containing the vector embedding */
+  path: string;
+  /** Query vector to search against */
+  queryVector: number[];
+  /** Number of candidates to consider (higher = more accurate, slower) */
+  numCandidates?: number;
+  /** Max results to return */
+  limit: number;
+  /** Pre-filter documents before vector search */
+  filter?: Record<string, unknown>;
+  /** Use exact search instead of ANN (slower but precise) */
+  exact?: boolean;
+}
+/** Result from build() including execution options */
+interface AggregationPlan {
+  pipeline: PipelineStage[];
+  allowDiskUse: boolean;
+}
+type SortOrder = 1 | -1 | 'asc' | 'desc';
+type SortSpec$2 = Record<string, SortOrder>;
+type ProjectionSpec = Record<string, 0 | 1 | Expression>;
+type GroupSpec = {
+  _id: string | Record<string, unknown> | null;
+  [key: string]: unknown;
+};
+/**
+ * Fluent builder for MongoDB aggregation pipelines
+ * Optimized for complex queries at scale
+ */
+declare class AggregationBuilder {
+  private pipeline;
+  private _diskUse;
+  /**
+   * Get the current pipeline
+   */
+  get(): PipelineStage[];
+  /**
+   * Build and return the final pipeline
+   */
+  build(): PipelineStage[];
+  /**
+   * Build pipeline with execution options (allowDiskUse, etc.)
+   */
+  plan(): AggregationPlan;
+  /**
+   * Build and execute the pipeline against a model
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .match({ status: 'active' })
+   *   .allowDiskUse()
+   *   .exec(MyModel);
+   * ```
+   */
+  exec<T = unknown>(model: Model<any>, session?: mongoose$1.ClientSession): Promise<T[]>;
+  /**
+   * Reset the pipeline
+   */
+  reset(): this;
+  /**
+   * Add a raw pipeline stage
+   */
+  addStage(stage: PipelineStage): this;
+  /**
+   * Add multiple raw pipeline stages
+   */
+  addStages(stages: PipelineStage[]): this;
+  /**
+   * $match - Filter documents
+   * IMPORTANT: Place $match as early as possible for performance
+   */
+  match(query: Record<string, unknown>): this;
+  /**
+   * $project - Include/exclude fields or compute new fields
+   */
+  project(projection: ProjectionSpec): this;
+  /**
+   * $group - Group documents and compute aggregations
+   *
+   * @example
+   * ```typescript
+   * .group({
+   *   _id: '$department',
+   *   count: { $sum: 1 },
+   *   avgSalary: { $avg: '$salary' }
+   * })
+   * ```
+   */
+  group(groupSpec: GroupSpec): this;
+  /**
+   * $sort - Sort documents
+   */
+  sort(sortSpec: SortSpec$2 | string): this;
+  /**
+   * $limit - Limit number of documents
+   */
+  limit(count: number): this;
+  /**
+   * $skip - Skip documents
+   */
+  skip(count: number): this;
+  /**
+   * $unwind - Deconstruct array field
+   */
+  unwind(path: string, preserveNullAndEmptyArrays?: boolean): this;
+  /**
+   * $addFields - Add new fields or replace existing fields
+   */
+  addFields(fields: Record<string, unknown>): this;
+  /**
+   * $set - Alias for $addFields
+   */
+  set(fields: Record<string, unknown>): this;
+  /**
+   * $unset - Remove fields
+   */
+  unset(fields: string | string[]): this;
+  /**
+   * $replaceRoot - Replace the root document
+   */
+  replaceRoot(newRoot: string | Record<string, unknown>): this;
+  /**
+   * $lookup - Join with another collection (simple form)
+   *
+   * @param from - Collection to join with
+   * @param localField - Field from source collection
+   * @param foreignField - Field from target collection
+   * @param as - Output field name
+   * @param single - Unwrap array to single object
+   *
+   * @example
+   * ```typescript
+   * // Join employees with departments by slug
+   * .lookup('departments', 'deptSlug', 'slug', 'department', true)
+   * ```
+   */
+  lookup(from: string, localField: string, foreignField: string, as?: string, single?: boolean): this;
+  /**
+   * $lookup - Join with another collection (advanced form with pipeline)
+   *
+   * @example
+   * ```typescript
+   * .lookupWithPipeline({
+   *   from: 'products',
+   *   localField: 'productIds',
+   *   foreignField: 'sku',
+   *   as: 'products',
+   *   pipeline: [
+   *     { $match: { status: 'active' } },
+   *     { $project: { name: 1, price: 1 } }
+   *   ]
+   * })
+   * ```
+   */
+  lookupWithPipeline(options: LookupOptions): this;
+  /**
+   * Multiple lookups at once
+   *
+   * @example
+   * ```typescript
+   * .multiLookup([
+   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
+   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
+   * ])
+   * ```
+   */
+  multiLookup(lookups: LookupOptions[]): this;
+  /**
+   * $facet - Process multiple aggregation pipelines in a single stage
+   * Useful for computing multiple aggregations in parallel
+   *
+   * @example
+   * ```typescript
+   * .facet({
+   *   totalCount: [{ $count: 'count' }],
+   *   avgPrice: [{ $group: { _id: null, avg: { $avg: '$price' } } }],
+   *   topProducts: [{ $sort: { sales: -1 } }, { $limit: 10 }]
+   * })
+   * ```
+   */
+  facet(facets: Record<string, PipelineStage[]>): this;
+  /**
+   * $bucket - Categorize documents into buckets
+   *
+   * @example
+   * ```typescript
+   * .bucket({
+   *   groupBy: '$price',
+   *   boundaries: [0, 50, 100, 200],
+   *   default: 'Other',
+   *   output: {
+   *     count: { $sum: 1 },
+   *     products: { $push: '$name' }
+   *   }
+   * })
+   * ```
+   */
+  bucket(options: {
+    groupBy: string | Expression;
+    boundaries: unknown[];
+    default?: string;
+    output?: Record<string, unknown>;
+  }): this;
+  /**
+   * $bucketAuto - Automatically determine bucket boundaries
+   */
+  bucketAuto(options: {
+    groupBy: string | Expression;
+    buckets: number;
+    output?: Record<string, unknown>;
+    granularity?: string;
+  }): this;
+  /**
+   * $setWindowFields - Perform window functions (MongoDB 5.0+)
+   * Useful for rankings, running totals, moving averages
+   *
+   * @example
+   * ```typescript
+   * .setWindowFields({
+   *   partitionBy: '$department',
+   *   sortBy: { salary: -1 },
+   *   output: {
+   *     rank: { $rank: {} },
+   *     runningTotal: { $sum: '$salary', window: { documents: ['unbounded', 'current'] } }
+   *   }
+   * })
+   * ```
+   */
+  setWindowFields(options: {
+    partitionBy?: string | Expression;
+    sortBy?: SortSpec$2;
+    output: Record<string, unknown>;
+  }): this;
+  /**
+   * $unionWith - Combine results from multiple collections (MongoDB 4.4+)
+   *
+   * @example
+   * ```typescript
+   * .unionWith({
+   *   coll: 'archivedOrders',
+   *   pipeline: [{ $match: { year: 2024 } }]
+   * })
+   * ```
+   */
+  unionWith(options: {
+    coll: string;
+    pipeline?: PipelineStage[];
+  }): this;
+  /**
+   * $densify - Fill gaps in data (MongoDB 5.1+)
+   * Useful for time series data with missing points
+   */
+  densify(options: {
+    field: string;
+    range: {
+      step: number;
+      unit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+      bounds: 'full' | 'partition' | [unknown, unknown];
+    };
+  }): this;
+  /**
+   * $fill - Fill null or missing field values (MongoDB 5.3+)
+   */
+  fill(options: {
+    sortBy?: SortSpec$2;
+    output: Record<string, {
+      method: 'linear' | 'locf' | 'value';
+      value?: unknown;
+    }>;
+  }): this;
+  /**
+   * Enable allowDiskUse for large aggregations that exceed 100MB memory limit
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .match({ status: 'active' })
+   *   .group({ _id: '$category', total: { $sum: '$amount' } })
+   *   .allowDiskUse()
+   *   .exec(Model);
+   * ```
+   */
+  allowDiskUse(enable?: boolean): this;
+  /**
+   * Paginate - Add skip and limit for offset-based pagination
+   */
+  paginate(page: number, limit: number): this;
+  /**
+   * Count total documents (useful with $facet for pagination metadata)
+   */
+  count(outputField?: string): this;
+  /**
+   * Sample - Randomly select N documents
+   */
+  sample(size: number): this;
+  /**
+   * Out - Write results to a collection
+   */
+  out(collection: string): this;
+  /**
+   * Merge - Merge results into a collection
+   */
+  merge(options: string | {
+    into: string;
+    on?: string | string[];
+    whenMatched?: string;
+    whenNotMatched?: string;
+  }): this;
+  /**
+   * GeoNear - Perform geospatial queries
+   */
+  geoNear(options: {
+    near: {
+      type: 'Point';
+      coordinates: [number, number];
+    };
+    distanceField: string;
+    maxDistance?: number;
+    query?: Record<string, unknown>;
+    spherical?: boolean;
+  }): this;
+  /**
+   * GraphLookup - Perform recursive search (graph traversal)
+   */
+  graphLookup(options: {
+    from: string;
+    startWith: string | Expression;
+    connectFromField: string;
+    connectToField: string;
+    as: string;
+    maxDepth?: number;
+    depthField?: string;
+    restrictSearchWithMatch?: Record<string, unknown>;
+  }): this;
+  /**
+   * $search - Atlas Search full-text search (Atlas only)
+   *
+   * @example
+   * ```typescript
+   * .search({
+   *   index: 'default',
+   *   text: {
+   *     query: 'laptop computer',
+   *     path: ['title', 'description'],
+   *     fuzzy: { maxEdits: 2 }
+   *   }
+   * })
+   * ```
+   */
+  search(options: {
+    index?: string;
+    text?: {
+      query: string;
+      path: string | string[];
+      fuzzy?: {
+        maxEdits?: number;
+        prefixLength?: number;
+      };
+      score?: {
+        boost?: {
+          value?: number;
+        };
+      };
+    };
+    compound?: {
+      must?: unknown[];
+      mustNot?: unknown[];
+      should?: unknown[];
+      filter?: unknown[];
+    };
+    autocomplete?: unknown;
+    near?: unknown;
+    range?: unknown;
+  }): this;
+  /**
+   * $searchMeta - Get Atlas Search metadata (Atlas only)
+   */
+  searchMeta(options: Record<string, unknown>): this;
+  /**
+   * $vectorSearch - Semantic similarity search using vector embeddings (Atlas only)
+   *
+   * Requires an Atlas Vector Search index on the target field.
+   * Must be the first stage in the pipeline.
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .vectorSearch({
+   *     index: 'vector_index',
+   *     path: 'embedding',
+   *     queryVector: await getEmbedding('running shoes'),
+   *     limit: 10,
+   *     numCandidates: 100,
+   *     filter: { category: 'footwear' }
+   *   })
+   *   .project({ embedding: 0, score: { $meta: 'vectorSearchScore' } })
+   *   .exec(ProductModel);
+   * ```
+   */
+  vectorSearch(options: VectorSearchOptions): this;
+  /**
+   * Add vectorSearchScore as a field after $vectorSearch
+   * Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
+   */
+  withVectorScore(fieldName?: string): this;
+  /**
+   * Create a builder from an existing pipeline
+   */
+  static from(pipeline: PipelineStage[]): AggregationBuilder;
+  /**
+   * Create a builder with initial match stage
+   */
+  static startWith(query: Record<string, unknown>): AggregationBuilder;
+}
+//#endregion
+//#region src/Repository.d.ts
+type HookListener = (data: any) => void | Promise<void>;
+/**
+ * Production-grade repository for MongoDB
+ * Event-driven, plugin-based, with smart pagination
+ */
+declare class Repository<TDoc = AnyDocument> {
+  readonly Model: Model<TDoc>;
+  readonly model: string;
+  readonly _hooks: Map<string, HookListener[]>;
+  readonly _pagination: PaginationEngine<TDoc>;
+  private readonly _hookMode;
+  [key: string]: unknown;
+  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
+   */
+  on(event: string, listener: HookListener): this;
+  /**
+   * Remove a specific event listener
+   */
+  off(event: string, listener: HookListener): this;
+  /**
+   * Remove all listeners for an event, or all listeners entirely
+   */
+  removeAllListeners(event?: string): this;
+  /**
+   * Emit event (sync - for backwards compatibility)
+   */
+  emit(event: string, data: unknown): void;
+  /**
+   * Emit event and await all async handlers
+   */
+  emitAsync(event: string, data: unknown): Promise<void>;
+  private _emitHook;
+  private _emitErrorHook;
+  /**
+   * Create single document
+   */
+  create(data: Record<string, unknown>, options?: {
+    session?: ClientSession;
+  }): Promise<TDoc>;
+  /**
+   * Create multiple documents
+   */
+  createMany(dataArray: Record<string, unknown>[], options?: {
+    session?: ClientSession;
+    ordered?: boolean;
+  }): Promise<TDoc[]>;
+  /**
+   * Get document by ID
+   */
+  getById(id: string | ObjectId, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    populateOptions?: PopulateOptions[];
+    lean?: boolean;
+    session?: ClientSession;
+    throwOnNotFound?: boolean;
+    skipCache?: boolean;
+    cacheTtl?: number;
+    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;
+    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
+   */
+  getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
+    session?: ClientSession;
+  }): Promise<TDoc | null>;
+  /**
+   * Count documents
+   */
+  count(query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    readPreference?: ReadPreferenceType;
+  }): Promise<number>;
+  /**
+   * Check if document exists
+   */
+  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<{
+    success: boolean;
+    message: string;
+  }>;
+  /**
+   * Execute aggregation pipeline
+   */
+  aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: {
+    session?: ClientSession;
+  }): Promise<TResult[]>;
+  /**
+   * Aggregate pipeline with pagination
+   * Best for: Complex queries, grouping, joins
+   */
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  /**
+   * Get distinct values
+   */
+  distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+  }): Promise<T[]>;
+  /**
+   * Query with custom field lookups ($lookup)
+   * Best for: Joins on slugs, SKUs, codes, or other indexed custom fields
+   *
+   * @example
+   * ```typescript
+   * // Join employees with departments using slug instead of ObjectId
+   * const employees = await employeeRepo.lookupPopulate({
+   *   filters: { status: 'active' },
+   *   lookups: [
+   *     {
+   *       from: 'departments',
+   *       localField: 'departmentSlug',
+   *       foreignField: 'slug',
+   *       as: 'department',
+   *       single: true
+   *     }
+   *   ],
+   *   sort: '-createdAt',
+   *   page: 1,
+   *   limit: 50
+   * });
+   * ```
+   */
+  lookupPopulate(options: {
+    filters?: Record<string, unknown>;
+    lookups: LookupOptions[];
+    sort?: SortSpec | 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
+   */
+  _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[];
+}
+/**
+ * Modern Query Parser
+ * Converts URL parameters to MongoDB queries with $lookup support
+ */
+declare class QueryParser {
+  private readonly options;
+  private readonly operators;
+  private readonly dangerousOperators;
+  /**
+   * Regex patterns that can cause catastrophic backtracking (ReDoS attacks)
+   * Detects:
+   * - Quantifiers: {n,m}
+   * - Possessive quantifiers: *+, ++, ?+
+   * - Nested quantifiers: (a+)+, (a*)*
+   * - Backreferences: \1, \2, etc.
+   * - Complex character classes: [...]...[...]
+   */
+  private readonly dangerousRegexPatterns;
+  constructor(options?: QueryParserOptions);
+  /**
+   * Parse URL query parameters into MongoDB query format
+   *
+   * @example
+   * ```typescript
+   * // URL: ?status=active&lookup[department][foreignField]=slug&sort=-createdAt&page=1
+   * const query = parser.parse(req.query);
+   * // Returns: { filters: {...}, lookups: [...], sort: {...}, page: 1 }
+   * ```
+   */
+  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+  /**
+   * Parse lookup configurations from URL parameters
+   *
+   * Supported formats:
+   * 1. Simple: ?lookup[department]=slug
+   *    → Join with 'departments' collection on slug field
+   *
+   * 2. Detailed: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug
+   *    → Full control over join configuration
+   *
+   * 3. Multiple: ?lookup[department]=slug&lookup[category]=categorySlug
+   *    → Multiple lookups
+   *
+   * @example
+   * ```typescript
+   * // URL: ?lookup[department][localField]=deptSlug&lookup[department][foreignField]=slug&lookup[department][single]=true
+   * const lookups = parser._parseLookups({
+   *   department: { localField: 'deptSlug', foreignField: 'slug', single: 'true' }
+   * });
+   * // Returns: [{ from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true }]
+   * ```
+   */
+  private _parseLookups;
+  /**
+   * Parse a single lookup configuration
+   */
+  private _parseSingleLookup;
+  /**
+   * Parse aggregation pipeline from URL (advanced feature)
+   *
+   * @example
+   * ```typescript
+   * // URL: ?aggregate[group][_id]=$status&aggregate[group][count]=$sum:1
+   * const pipeline = parser._parseAggregation({
+   *   group: { _id: '$status', count: '$sum:1' }
+   * });
+   * ```
+   */
+  private _parseAggregation;
+  /**
+   * Parse select/project fields
+   *
+   * @example
+   * ```typescript
+   * // URL: ?select=name,email,-password
+   * // Returns: { name: 1, email: 1, password: 0 }
+   * ```
+   */
+  private _parseSelect;
+  /**
+   * Parse populate parameter - handles both simple string and advanced object format
+   *
+   * @example
+   * ```typescript
+   * // Simple: ?populate=author,category
+   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+   *
+   * // Advanced: ?populate[author][select]=name,email
+   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+   * ```
+   */
+  private _parsePopulate;
+  /**
+   * Parse a single populate configuration
+   */
+  private _parseSinglePopulate;
+  /**
+   * Convert populate match values (handles boolean strings, etc.)
+   */
+  private _convertPopulateMatch;
+  /**
+   * Parse filter parameters
+   */
+  private _parseFilters;
+  /**
+   * Handle operator syntax: field[operator]=value
+   */
+  private _handleOperatorSyntax;
+  /**
+   * Handle bracket syntax with object value
+   */
+  private _handleBracketSyntax;
+  private _parseSort;
+  private _toMongoOperator;
+  private _createSafeRegex;
+  private _escapeRegex;
+  /**
+   * Sanitize $match configuration to prevent dangerous operators
+   * Recursively filters out operators like $where, $function, $accumulator
+   */
+  private _sanitizeMatchConfig;
+  /**
+   * Sanitize pipeline stages for use in $lookup.
+   * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
+   * operator expressions within $match, $addFields, and $set stages.
+   */
+  private _sanitizePipeline;
+  /**
+   * Recursively sanitize expression objects, blocking dangerous operators
+   * like $where, $function, $accumulator inside $addFields/$set stages.
+   */
+  private _sanitizeExpressions;
+  private _sanitizeSearch;
+  /**
+   * Build regex-based multi-field search filters
+   * Creates an $or query with case-insensitive regex across all searchFields
+   *
+   * @example
+   * // searchFields: ['name', 'description', 'sku']
+   * // search: 'azure'
+   * // Returns: [
+   * //   { name: { $regex: /azure/i } },
+   * //   { description: { $regex: /azure/i } },
+   * //   { sku: { $regex: /azure/i } }
+   * // ]
+   */
+  private _buildRegexSearch;
+  private _convertValue;
+  private _parseOr;
+  private _enhanceWithBetween;
+  private _pluralize;
+  private _capitalize;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Factory function to create a repository instance
+ *
+ * @param Model - Mongoose model
+ * @param plugins - Array of plugins to apply
+ * @returns Repository instance
+ *
+ * @example
+ * const userRepo = createRepository(UserModel, [timestampPlugin()]);
+ */
+declare function createRepository<TDoc>(Model: mongoose$1.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 BatchOperationsMethods, 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, 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, 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 };