@classytic/mongokit 3.1.5 → 3.2.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { i as PaginationResult, A as AnyDocument, j as PluginType, P as PaginationConfig, R as RepositoryOptions, k as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, l as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, m as RepositoryContext, H as HttpError } from './types-B5Uv6Ak7.js';
-export { c as AggregatePaginationOptions, ad as AllPluginMethods, n as AnyModel, C as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, v as CreateInput, y as CreateOptions, h as CrudSchemas, $ as DecodedCursor, D as DeepPartial, z as DeleteResult, X as EventHandlers, Y as EventPayload, Q as EventPhase, F as FieldPreset, Z as FieldRules, a6 as GroupResult, p as HookMode, I as InferDocument, q as InferRawDoc, _ as JsonSchema, t as KeysOfType, K as KeysetPaginationOptions, a2 as Logger, a7 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, x as OperationOptions, r as PartialBy, G as Plugin, J as PluginFunction, T as RepositoryEvent, L as RepositoryInstance, M as RepositoryOperation, s as RequiredBy, g as SchemaBuilderOptions, a4 as SoftDeleteFilterMode, a3 as SoftDeleteOptions, a5 as SoftDeleteRepository, o as SortDirection, u as Strict, w as UpdateInput, B as UpdateManyResult, E as UpdateWithValidationResult, U as UserContext, a1 as ValidationChainOptions, V as ValidationResult, a0 as ValidatorDefinition, ae as WithPlugins } from './types-B5Uv6Ak7.js';
+import { h as PaginationResult, A as AnyDocument, i as PluginType, P as PaginationConfig, R as RepositoryOptions, j as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, U as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, k as RepositoryContext, H as HttpError } from './types-Jni1KgkP.js';
+export { c as AggregatePaginationOptions, ad as AllPluginMethods, l as AnyModel, a7 as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, C as CreateInput, v as CreateOptions, Z as CrudSchemas, _ as DecodedCursor, D as DeepPartial, w as DeleteResult, L as EventHandlers, M as EventPayload, G as EventPhase, Q as FieldPreset, T as FieldRules, a5 as GroupResult, n as HookMode, I as InferDocument, o as InferRawDoc, Y as JsonSchema, r as KeysOfType, K as KeysetPaginationOptions, a1 as Logger, a6 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, u as OperationOptions, p as PartialBy, g as Plugin, B as PluginFunction, J as RepositoryEvent, E as RepositoryInstance, F as RepositoryOperation, q as RequiredBy, X as SchemaBuilderOptions, a3 as SoftDeleteFilterMode, a2 as SoftDeleteOptions, a4 as SoftDeleteRepository, m as SortDirection, s as Strict, t as UpdateInput, x as UpdateManyResult, y as UpdateWithValidationResult, z as UserContext, a0 as ValidationChainOptions, V as ValidationResult, $ as ValidatorDefinition, ae as WithPlugins } from './types-Jni1KgkP.js';
 import * as mongoose from 'mongoose';
-import { PipelineStage, Expression, Model, ClientSession, PopulateOptions } from 'mongoose';
+import { PipelineStage, Model, Expression, ClientSession, PopulateOptions } from 'mongoose';
 import { PaginationEngine } from './pagination/PaginationEngine.js';
-import { L as LookupOptions, a as LookupBuilder } from './index-BXSSv1pW.js';
-export { i as actions } from './index-BXSSv1pW.js';
-export { AggregateHelpersMethods, BatchOperationsMethods, CacheMethods, MongoOperationsMethods, SoftDeleteMethods, SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
-export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from './mongooseToJsonSchema-Cc5AwuDu.js';
+import { L as LookupOptions, a as LookupBuilder } from './index-BDn5fSTE.js';
+export { i as actions } from './index-BDn5fSTE.js';
+export { AggregateHelpersMethods, BatchOperationsMethods, CacheMethods, MongoOperationsMethods, MultiTenantOptions, ObservabilityOptions, OperationMetric, SoftDeleteMethods, SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
+export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, k as configureLogger, j as createError, c as createFieldPreset, l as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from './mongooseToJsonSchema-CaRF_bCN.js';
 
 /**
  * Framework-Agnostic Controller Interfaces
@@ -330,35 +330,28 @@ interface IResponseFormatter {
     paginated<T>(result: PaginationResult<T>): IControllerResponse<PaginationResult<T>>;
 }
 
-/**
- * AggregationBuilder - Fluent MongoDB Aggregation Pipeline Builder
- *
- * Modern, type-safe builder for complex MongoDB aggregations.
- * Supports MongoDB 6+ features with optimized query patterns.
- *
- * Features:
- * - Fluent, chainable API
- * - $lookup with custom field joins
- * - Faceted search
- * - Window functions ($setWindowFields)
- * - Atlas Search ($search)
- * - Union queries ($unionWith)
- * - Full aggregation operator support
- *
- * @example
- * ```typescript
- * const pipeline = new AggregationBuilder()
- *   .match({ status: 'active' })
- *   .lookup('departments', 'deptSlug', 'slug', 'department', true)
- *   .sort({ createdAt: -1 })
- *   .limit(50)
- *   .project({ password: 0 })
- *   .build();
- *
- * const results = await Model.aggregate(pipeline);
- * ```
- */
-
+/** 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$1 = Record<string, SortOrder>;
 type ProjectionSpec = Record<string, 0 | 1 | Expression>;
@@ -372,6 +365,7 @@ type GroupSpec = {
  */
 declare class AggregationBuilder {
     private pipeline;
+    private _diskUse;
     /**
      * Get the current pipeline
      */
@@ -380,6 +374,22 @@ declare class AggregationBuilder {
      * 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.ClientSession): Promise<T[]>;
     /**
      * Reset the pipeline
      */
@@ -595,6 +605,19 @@ declare class AggregationBuilder {
             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
      */
@@ -690,6 +713,33 @@ declare class AggregationBuilder {
      * $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
      */
@@ -748,6 +798,14 @@ declare class Repository<TDoc = AnyDocument> {
      * 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)
      */
@@ -777,6 +835,7 @@ declare class Repository<TDoc = AnyDocument> {
     getById(id: string | ObjectId, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
+        populateOptions?: PopulateOptions[];
         lean?: boolean;
         session?: ClientSession;
         throwOnNotFound?: boolean;
@@ -789,6 +848,7 @@ declare class Repository<TDoc = AnyDocument> {
     getByQuery(query: Record<string, unknown>, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
+        populateOptions?: PopulateOptions[];
         lean?: boolean;
         session?: ClientSession;
         throwOnNotFound?: boolean;
@@ -830,6 +890,8 @@ declare class Repository<TDoc = AnyDocument> {
         };
         limit?: number;
         search?: string;
+        /** Advanced populate options (from QueryParser or Arc's BaseController) */
+        populateOptions?: PopulateOptions[];
     }, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
@@ -970,9 +1032,36 @@ declare class Repository<TDoc = AnyDocument> {
      */
     buildLookup(from?: string): LookupBuilder;
     /**
-     * Execute callback within a transaction
+     * 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 | null) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
+    withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
     private _isTransactionUnsupported;
     /**
      * Execute custom query with event emission
@@ -1053,9 +1142,11 @@ declare class Repository<TDoc = AnyDocument> {
  *
  * ### Lookup Security
  *
- * Lookups are sanitized by default (collection whitelists, field validation,
- * pipeline/let blocking). For maximum security, use per-collection field allowlists
- * in your controller layer (see BaseController example).
+ * Lookup pipelines are sanitized by default:
+ * - Dangerous stages blocked ($out, $merge, $unionWith, $collStats, $currentOp, $listSessions)
+ * - Dangerous operators blocked inside $match/$addFields/$set ($where, $function, $accumulator, $expr)
+ * - Optional collection whitelist via `allowedLookupCollections`
+ * For maximum security, use per-collection field allowlists in your controller layer.
  *
  * ### Filter Security
  *
@@ -1154,6 +1245,13 @@ interface QueryParserOptions {
      * @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[];
 }
 /**
  * Modern Query Parser
@@ -1276,6 +1374,17 @@ declare class QueryParser {
      * 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
@@ -1310,4 +1419,4 @@ declare class QueryParser {
  */
 declare function createRepository<TDoc>(Model: mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 
-export { AggregatePaginationResult, AggregationBuilder, AnyDocument, type FilterQuery, HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, KeysetPaginationResult, LookupBuilder, LookupOptions, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PaginationResult, type ParsedQuery, PluginType, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, type SearchMode, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };
+export { AggregatePaginationResult, AggregationBuilder, AnyDocument, type FilterQuery, HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, KeysetPaginationResult, LookupBuilder, LookupOptions, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PaginationResult, type ParsedQuery, PluginType, type PopulateOption, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, type SearchMode, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };