@classytic/mongokit 3.1.6 → 3.2.1

package/dist/{index-BXSSv1pW.d.ts → index-BDn5fSTE.d.ts}

@@ -1,5 +1,5 @@
 import { PipelineStage, ClientSession, Model } from 'mongoose';
-import { A as AnyDocument, y as CreateOptions, k as ObjectId, x as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, l as UpdateOptions, E as UpdateWithValidationResult, B as UpdateManyResult, z as DeleteResult, a6 as GroupResult, a7 as MinMaxResult } from './types-B5Uv6Ak7.js';
+import { A as AnyDocument, v as CreateOptions, j as ObjectId, u as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, U as UpdateOptions, y as UpdateWithValidationResult, x as UpdateManyResult, w as DeleteResult, a5 as GroupResult, a6 as MinMaxResult } from './types-Jni1KgkP.js';
 
 /**
  * LookupBuilder - MongoDB $lookup Utility
@@ -59,6 +59,8 @@ interface LookupOptions {
     options?: {
         session?: ClientSession;
     };
+    /** Sanitize pipeline stages (default: true). Set false only for trusted server-side pipelines */
+    sanitize?: boolean;
 }
 /**
  * Fluent builder for MongoDB $lookup aggregation stage
@@ -160,6 +162,15 @@ declare class LookupBuilder {
      * ```
      */
     static nested(lookups: LookupOptions[]): PipelineStage[];
+    /**
+     * Sanitize pipeline stages by blocking dangerous stages and operators.
+     * Used internally by build() and available for external use (e.g., aggregate.ts).
+     */
+    static sanitizePipeline(stages: PipelineStage[]): PipelineStage[];
+    /**
+     * Recursively remove dangerous operators from an expression object.
+     */
+    private static _sanitizeDeep;
 }
 
 /**
@@ -349,6 +360,7 @@ declare namespace update$1 {
  */
 declare function deleteById(Model: Model<any>, id: string | ObjectId, options?: {
     session?: ClientSession;
+    query?: Record<string, unknown>;
 }): Promise<DeleteResult>;
 /**
  * Delete many documents

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)
      */
@@ -974,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
@@ -1057,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
  *
@@ -1158,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
@@ -1280,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