@classytic/mongokit 3.1.5 → 3.2.0

package/dist/index.js

@@ -1,224 +1,18 @@
-import { getById, getByQuery, getOrCreate, count, exists, update, deleteById, aggregate, distinct } from './chunks/chunk-SAKSLT47.js';
-export { actions_exports as actions } from './chunks/chunk-SAKSLT47.js';
-import { PaginationEngine } from './chunks/chunk-M2XHQGZB.js';
-export { PaginationEngine } from './chunks/chunk-M2XHQGZB.js';
-export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './chunks/chunk-CSLJ2PL2.js';
-import { create, createMany } from './chunks/chunk-CF6FLC2G.js';
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, createMemoryCache, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from './chunks/chunk-IT7DCOKR.js';
+import { LookupBuilder, getById, getByQuery, getOrCreate, count, exists, update, deleteById, aggregate, distinct } from './chunks/chunk-VWKIKZYF.js';
+export { LookupBuilder, actions_exports as actions } from './chunks/chunk-VWKIKZYF.js';
+import { PaginationEngine } from './chunks/chunk-44KXLGPO.js';
+export { PaginationEngine } from './chunks/chunk-44KXLGPO.js';
+export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './chunks/chunk-DEVXDBRL.js';
+import { create, createMany } from './chunks/chunk-I7CWNAJB.js';
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, createMemoryCache, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from './chunks/chunk-UE2IEXZJ.js';
 export { createFieldPreset, filterResponseData, getFieldsForUser, getMongooseProjection } from './chunks/chunk-2ZN65ZOP.js';
-import { createError } from './chunks/chunk-VJXDGP3C.js';
-export { createError } from './chunks/chunk-VJXDGP3C.js';
+import { warn } from './chunks/chunk-URLJFIR7.js';
+export { configureLogger } from './chunks/chunk-URLJFIR7.js';
+import { createError } from './chunks/chunk-JWUAVZ3L.js';
+export { createError } from './chunks/chunk-JWUAVZ3L.js';
+import './chunks/chunk-WSFCRVEQ.js';
 import mongoose from 'mongoose';
 
-// src/query/LookupBuilder.ts
-var LookupBuilder = class _LookupBuilder {
-  options = {};
-  constructor(from) {
-    if (from) this.options.from = from;
-  }
-  /**
-   * Set the collection to join with
-   */
-  from(collection) {
-    this.options.from = collection;
-    return this;
-  }
-  /**
-   * Set the local field (source collection)
-   * IMPORTANT: This field should be indexed for optimal performance
-   */
-  localField(field) {
-    this.options.localField = field;
-    return this;
-  }
-  /**
-   * Set the foreign field (target collection)
-   * IMPORTANT: This field should be indexed (preferably unique) for optimal performance
-   */
-  foreignField(field) {
-    this.options.foreignField = field;
-    return this;
-  }
-  /**
-   * Set the output field name
-   * Defaults to the collection name if not specified
-   */
-  as(fieldName) {
-    this.options.as = fieldName;
-    return this;
-  }
-  /**
-   * Mark this lookup as returning a single document
-   * Automatically unwraps the array result to a single object or null
-   */
-  single(isSingle = true) {
-    this.options.single = isSingle;
-    return this;
-  }
-  /**
-   * Add a pipeline to filter/transform joined documents
-   * Useful for filtering, sorting, or limiting joined results
-   *
-   * @example
-   * ```typescript
-   * lookup.pipeline([
-   *   { $match: { status: 'active' } },
-   *   { $sort: { priority: -1 } },
-   *   { $limit: 5 }
-   * ]);
-   * ```
-   */
-  pipeline(stages) {
-    this.options.pipeline = stages;
-    return this;
-  }
-  /**
-   * Set let variables for use in pipeline
-   * Allows referencing local document fields in the pipeline
-   */
-  let(variables) {
-    this.options.let = variables;
-    return this;
-  }
-  /**
-   * Build the $lookup aggregation stage(s)
-   * Returns an array of pipeline stages including $lookup and optional $unwind
-   *
-   * IMPORTANT: MongoDB $lookup has two mutually exclusive forms:
-   * 1. Simple form: { from, localField, foreignField, as }
-   * 2. Pipeline form: { from, let, pipeline, as }
-   *
-   * When pipeline or let is specified, we use the pipeline form.
-   * Otherwise, we use the simpler localField/foreignField form.
-   */
-  build() {
-    const { from, localField, foreignField, as, single, pipeline, let: letVars } = this.options;
-    if (!from) {
-      throw new Error('LookupBuilder: "from" collection is required');
-    }
-    const outputField = as || from;
-    const stages = [];
-    const usePipelineForm = pipeline || letVars;
-    let lookupStage;
-    if (usePipelineForm) {
-      if (!pipeline || pipeline.length === 0) {
-        if (!localField || !foreignField) {
-          throw new Error(
-            "LookupBuilder: When using pipeline form without a custom pipeline, both localField and foreignField are required to auto-generate the pipeline"
-          );
-        }
-        const autoPipeline = [
-          {
-            $match: {
-              $expr: {
-                $eq: [`$${foreignField}`, `$$${localField}`]
-              }
-            }
-          }
-        ];
-        lookupStage = {
-          $lookup: {
-            from,
-            let: { [localField]: `$${localField}`, ...letVars || {} },
-            pipeline: autoPipeline,
-            as: outputField
-          }
-        };
-      } else {
-        lookupStage = {
-          $lookup: {
-            from,
-            ...letVars && { let: letVars },
-            pipeline,
-            as: outputField
-          }
-        };
-      }
-    } else {
-      if (!localField || !foreignField) {
-        throw new Error("LookupBuilder: localField and foreignField are required for simple lookup");
-      }
-      lookupStage = {
-        $lookup: {
-          from,
-          localField,
-          foreignField,
-          as: outputField
-        }
-      };
-    }
-    stages.push(lookupStage);
-    if (single) {
-      stages.push({
-        $unwind: {
-          path: `$${outputField}`,
-          preserveNullAndEmptyArrays: true
-          // Keep documents even if no match found
-        }
-      });
-    }
-    return stages;
-  }
-  /**
-   * Build and return only the $lookup stage (without $unwind)
-   * Useful when you want to handle unwrapping yourself
-   */
-  buildLookupOnly() {
-    const stages = this.build();
-    return stages[0];
-  }
-  /**
-   * Static helper: Create a simple lookup in one line
-   */
-  static simple(from, localField, foreignField, options = {}) {
-    return new _LookupBuilder(from).localField(localField).foreignField(foreignField).as(options.as || from).single(options.single || false).build();
-  }
-  /**
-   * Static helper: Create multiple lookups at once
-   *
-   * @example
-   * ```typescript
-   * const pipeline = LookupBuilder.multiple([
-   *   { from: 'departments', localField: 'deptSlug', foreignField: 'slug', single: true },
-   *   { from: 'managers', localField: 'managerId', foreignField: '_id', single: true }
-   * ]);
-   * ```
-   */
-  static multiple(lookups) {
-    return lookups.flatMap((lookup) => {
-      const builder = new _LookupBuilder(lookup.from).localField(lookup.localField).foreignField(lookup.foreignField);
-      if (lookup.as) builder.as(lookup.as);
-      if (lookup.single) builder.single(lookup.single);
-      if (lookup.pipeline) builder.pipeline(lookup.pipeline);
-      if (lookup.let) builder.let(lookup.let);
-      return builder.build();
-    });
-  }
-  /**
-   * Static helper: Create a nested lookup (lookup within lookup)
-   * Useful for multi-level joins like Order -> Product -> Category
-   *
-   * @example
-   * ```typescript
-   * // Join orders with products, then products with categories
-   * const pipeline = LookupBuilder.nested([
-   *   { from: 'products', localField: 'productSku', foreignField: 'sku', as: 'product', single: true },
-   *   { from: 'categories', localField: 'product.categorySlug', foreignField: 'slug', as: 'product.category', single: true }
-   * ]);
-   * ```
-   */
-  static nested(lookups) {
-    return lookups.flatMap((lookup, index) => {
-      const builder = new _LookupBuilder(lookup.from).localField(lookup.localField).foreignField(lookup.foreignField);
-      if (lookup.as) builder.as(lookup.as);
-      if (lookup.single !== void 0) builder.single(lookup.single);
-      if (lookup.pipeline) builder.pipeline(lookup.pipeline);
-      if (lookup.let) builder.let(lookup.let);
-      return builder.build();
-    });
-  }
-};
-
 // src/query/AggregationBuilder.ts
 function normalizeSortSpec(sortSpec) {
   const normalized = {};
@@ -235,6 +29,7 @@ function normalizeSortSpec(sortSpec) {
 }
 var AggregationBuilder = class _AggregationBuilder {
   pipeline = [];
+  _diskUse = false;
   /**
    * Get the current pipeline
    */
@@ -247,11 +42,35 @@ var AggregationBuilder = class _AggregationBuilder {
   build() {
     return this.get();
   }
+  /**
+   * Build pipeline with execution options (allowDiskUse, etc.)
+   */
+  plan() {
+    return { pipeline: this.get(), allowDiskUse: this._diskUse };
+  }
+  /**
+   * Build and execute the pipeline against a model
+   *
+   * @example
+   * ```typescript
+   * const results = await new AggregationBuilder()
+   *   .match({ status: 'active' })
+   *   .allowDiskUse()
+   *   .exec(MyModel);
+   * ```
+   */
+  async exec(model, session) {
+    const agg = model.aggregate(this.build());
+    if (this._diskUse) agg.allowDiskUse(true);
+    if (session) agg.session(session);
+    return agg.exec();
+  }
   /**
    * Reset the pipeline
    */
   reset() {
     this.pipeline = [];
+    this._diskUse = false;
     return this;
   }
   /**
@@ -543,6 +362,25 @@ var AggregationBuilder = class _AggregationBuilder {
     return this;
   }
   // ============================================================
+  // EXECUTION OPTIONS
+  // ============================================================
+  /**
+   * 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 = true) {
+    this._diskUse = enable;
+    return this;
+  }
+  // ============================================================
   // UTILITY METHODS
   // ============================================================
   /**
@@ -626,6 +464,56 @@ var AggregationBuilder = class _AggregationBuilder {
     return this;
   }
   // ============================================================
+  // ATLAS VECTOR SEARCH (MongoDB Atlas 7.0+)
+  // ============================================================
+  /**
+   * $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) {
+    if (this.pipeline.length > 0) {
+      throw new Error("[mongokit] $vectorSearch must be the first stage in the pipeline");
+    }
+    const rawCandidates = options.numCandidates ?? Math.max(options.limit * 10, 100);
+    const numCandidates = Math.min(Math.max(rawCandidates, options.limit), 1e4);
+    this.pipeline.push({
+      $vectorSearch: {
+        index: options.index,
+        path: options.path,
+        queryVector: options.queryVector,
+        numCandidates,
+        limit: options.limit,
+        ...options.filter && { filter: options.filter },
+        ...options.exact && { exact: options.exact }
+      }
+    });
+    return this;
+  }
+  /**
+   * Add vectorSearchScore as a field after $vectorSearch
+   * Convenience for `.addFields({ score: { $meta: 'vectorSearchScore' } })`
+   */
+  withVectorScore(fieldName = "score") {
+    return this.addFields({ [fieldName]: { $meta: "vectorSearchScore" } });
+  }
+  // ============================================================
   // HELPER FACTORY METHODS
   // ============================================================
   /**
@@ -680,6 +568,28 @@ var Repository = class {
     this._hooks.get(event).push(listener);
     return this;
   }
+  /**
+   * Remove a specific event listener
+   */
+  off(event, listener) {
+    const listeners = this._hooks.get(event);
+    if (listeners) {
+      const idx = listeners.indexOf(listener);
+      if (idx !== -1) listeners.splice(idx, 1);
+    }
+    return this;
+  }
+  /**
+   * Remove all listeners for an event, or all listeners entirely
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this._hooks.delete(event);
+    } else {
+      this._hooks.clear();
+    }
+    return this;
+  }
   /**
    * Emit event (sync - for backwards compatibility)
    */
@@ -756,26 +666,38 @@ var Repository = class {
    * Get document by ID
    */
   async getById(id, options = {}) {
-    const context = await this._buildContext("getById", { id, ...options });
+    const populateSpec = options.populateOptions || options.populate;
+    const context = await this._buildContext("getById", { id, ...options, populate: populateSpec });
     if (context._cacheHit) {
       return context._cachedResult;
     }
-    const result = await getById(this.Model, id, context);
-    await this._emitHook("after:getById", { context, result });
-    return result;
+    try {
+      const result = await getById(this.Model, id, context);
+      await this._emitHook("after:getById", { context, result });
+      return result;
+    } catch (error) {
+      await this._emitErrorHook("error:getById", { context, error });
+      throw this._handleError(error);
+    }
   }
   /**
    * Get single document by query
    */
   async getByQuery(query, options = {}) {
-    const context = await this._buildContext("getByQuery", { query, ...options });
+    const populateSpec = options.populateOptions || options.populate;
+    const context = await this._buildContext("getByQuery", { query, ...options, populate: populateSpec });
     if (context._cacheHit) {
       return context._cachedResult;
     }
     const finalQuery = context.query || query;
-    const result = await getByQuery(this.Model, finalQuery, context);
-    await this._emitHook("after:getByQuery", { context, result });
-    return result;
+    try {
+      const result = await getByQuery(this.Model, finalQuery, context);
+      await this._emitHook("after:getByQuery", { context, result });
+      return result;
+    } catch (error) {
+      await this._emitErrorHook("error:getByQuery", { context, error });
+      throw this._handleError(error);
+    }
   }
   /**
    * Unified pagination - auto-detects offset vs keyset based on params
@@ -805,17 +727,16 @@ var Repository = class {
     if (context._cacheHit) {
       return context._cachedResult;
     }
-    const hasPageParam = params.page !== void 0 || params.pagination;
-    const hasCursorParam = "cursor" in params || "after" in params;
-    const hasSortParam = params.sort !== void 0;
-    const useKeyset = !hasPageParam && (hasCursorParam || hasSortParam);
-    const filters = context.filters || params.filters || {};
-    const search = params.search;
-    const sort = params.sort || "-createdAt";
-    const limit = params.limit || params.pagination?.limit || this._pagination.config.defaultLimit;
+    const filters = context.filters ?? params.filters ?? {};
+    const search = context.search ?? params.search;
+    const sort = context.sort ?? params.sort ?? "-createdAt";
+    const limit = context.limit ?? params.limit ?? params.pagination?.limit ?? this._pagination.config.defaultLimit;
+    const page = context.page ?? params.pagination?.page ?? params.page;
+    const after = context.after ?? params.cursor ?? params.after;
+    const useKeyset = !page && (after || sort !== "-createdAt" && (context.sort ?? params.sort));
     let query = { ...filters };
     if (search) query.$text = { $search: search };
-    const populateSpec = options.populateOptions || context.populate || options.populate;
+    const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
     const paginationOptions = {
       filters: query,
       sort: this._parseSort(sort),
@@ -825,23 +746,26 @@ var Repository = class {
       lean: context.lean ?? options.lean ?? true,
       session: options.session
     };
-    let result;
-    if (useKeyset) {
-      result = await this._pagination.stream({
-        ...paginationOptions,
-        sort: paginationOptions.sort,
-        // Required for keyset
-        after: params.cursor || params.after
-      });
-    } else {
-      const page = params.pagination?.page || params.page || 1;
-      result = await this._pagination.paginate({
-        ...paginationOptions,
-        page
-      });
+    try {
+      let result;
+      if (useKeyset) {
+        result = await this._pagination.stream({
+          ...paginationOptions,
+          sort: paginationOptions.sort,
+          after
+        });
+      } else {
+        result = await this._pagination.paginate({
+          ...paginationOptions,
+          page: page || 1
+        });
+      }
+      await this._emitHook("after:getAll", { context, result });
+      return result;
+    } catch (error) {
+      await this._emitErrorHook("error:getAll", { context, error });
+      throw this._handleError(error);
     }
-    await this._emitHook("after:getAll", { context, result });
-    return result;
   }
   /**
    * Get or create document
@@ -886,7 +810,7 @@ var Repository = class {
         await this._emitHook("after:delete", { context, result: result2 });
         return result2;
       }
-      const result = await deleteById(this.Model, id, options);
+      const result = await deleteById(this.Model, id, { session: options.session, query: context.query });
       await this._emitHook("after:delete", { context, result });
       return result;
     } catch (error) {
@@ -942,8 +866,9 @@ var Repository = class {
     const context = await this._buildContext("lookupPopulate", options);
     try {
       const builder = new AggregationBuilder();
-      if (options.filters && Object.keys(options.filters).length > 0) {
-        builder.match(options.filters);
+      const filters = context.filters ?? options.filters;
+      if (filters && Object.keys(filters).length > 0) {
+        builder.match(filters);
       }
       builder.multiLookup(options.lookups);
       if (options.sort) {
@@ -955,12 +880,12 @@ var Repository = class {
       const SAFE_LIMIT = 1e3;
       const SAFE_MAX_OFFSET = 1e4;
       if (limit > SAFE_LIMIT) {
-        console.warn(
+        warn(
           `[mongokit] Large limit (${limit}) in lookupPopulate. $facet results must be <16MB. Consider using smaller limits or stream-based pagination for large datasets.`
         );
       }
       if (skip > SAFE_MAX_OFFSET) {
-        console.warn(
+        warn(
           `[mongokit] Large offset (${skip}) in lookupPopulate. $facet with high offsets can exceed 16MB. For deep pagination, consider using keyset/cursor-based pagination instead.`
         );
       }
@@ -1057,40 +982,52 @@ var Repository = class {
     return new LookupBuilder(from);
   }
   /**
-   * 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),
+   * });
+   * ```
    */
   async withTransaction(callback, options = {}) {
     const session = await mongoose.startSession();
-    let started = false;
     try {
-      session.startTransaction();
-      started = true;
-      const result = await callback(session);
-      await session.commitTransaction();
+      const result = await session.withTransaction(
+        () => callback(session),
+        options.transactionOptions
+      );
       return result;
     } catch (error) {
       const err = error;
       if (options.allowFallback && this._isTransactionUnsupported(err)) {
-        if (typeof options.onFallback === "function") {
-          options.onFallback(err);
-        }
-        if (started) {
-          try {
-            await session.abortTransaction();
-          } catch {
-          }
-        }
-        return await callback(null);
-      }
-      if (started) {
-        try {
-          await session.abortTransaction();
-        } catch {
-        }
+        options.onFallback?.(err);
+        return await callback(session);
       }
       throw err;
     } finally {
-      session.endSession();
+      await session.endSession();
     }
   }
   _isTransactionUnsupported(error) {
@@ -1197,10 +1134,11 @@ var QueryParser = class {
       enableLookups: options.enableLookups ?? true,
       enableAggregations: options.enableAggregations ?? false,
       searchMode: options.searchMode ?? "text",
-      searchFields: options.searchFields
+      searchFields: options.searchFields,
+      allowedLookupCollections: options.allowedLookupCollections
     };
     if (this.options.searchMode === "regex" && (!this.options.searchFields || this.options.searchFields.length === 0)) {
-      console.warn('[mongokit] searchMode "regex" requires searchFields to be specified. Falling back to "text" mode.');
+      warn('[mongokit] searchMode "regex" requires searchFields to be specified. Falling back to "text" mode.');
       this.options.searchMode = "text";
     }
     this.dangerousOperators = [
@@ -1240,7 +1178,7 @@ var QueryParser = class {
       parsedLimit = 20;
     }
     if (parsedLimit > this.options.maxLimit) {
-      console.warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${this.options.maxLimit}, capping to max`);
+      warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${this.options.maxLimit}, capping to max`);
       parsedLimit = this.options.maxLimit;
     }
     const sanitizedSearch = this._sanitizeSearch(search);
@@ -1339,7 +1277,7 @@ var QueryParser = class {
           lookups.push(lookupConfig);
         }
       } catch (error) {
-        console.warn(`[mongokit] Invalid lookup config for ${collectionName}:`, error);
+        warn(`[mongokit] Invalid lookup config for ${collectionName}:`, error);
       }
     }
     return lookups;
@@ -1350,8 +1288,13 @@ var QueryParser = class {
   _parseSingleLookup(collectionName, config) {
     if (!config) return null;
     if (typeof config === "string") {
+      const from = this._pluralize(collectionName);
+      if (this.options.allowedLookupCollections && !this.options.allowedLookupCollections.includes(from)) {
+        warn(`[mongokit] Blocked lookup to disallowed collection: ${from}`);
+        return null;
+      }
       return {
-        from: this._pluralize(collectionName),
+        from,
         localField: `${collectionName}${this._capitalize(config)}`,
         foreignField: config,
         as: collectionName,
@@ -1363,8 +1306,12 @@ var QueryParser = class {
       const from = opts.from || this._pluralize(collectionName);
       const localField = opts.localField;
       const foreignField = opts.foreignField;
+      if (this.options.allowedLookupCollections && !this.options.allowedLookupCollections.includes(from)) {
+        warn(`[mongokit] Blocked lookup to disallowed collection: ${from}`);
+        return null;
+      }
       if (!localField || !foreignField) {
-        console.warn(`[mongokit] Lookup requires localField and foreignField for ${collectionName}`);
+        warn(`[mongokit] Lookup requires localField and foreignField for ${collectionName}`);
         return null;
       }
       return {
@@ -1373,7 +1320,7 @@ var QueryParser = class {
         foreignField,
         as: opts.as || collectionName,
         single: opts.single === true || opts.single === "true",
-        ...opts.pipeline && Array.isArray(opts.pipeline) ? { pipeline: opts.pipeline } : {}
+        ...opts.pipeline && Array.isArray(opts.pipeline) ? { pipeline: this._sanitizePipeline(opts.pipeline) } : {}
       };
     }
     return null;
@@ -1411,7 +1358,7 @@ var QueryParser = class {
           pipeline.push({ $project: config });
         }
       } catch (error) {
-        console.warn(`[mongokit] Invalid aggregation stage ${stage}:`, error);
+        warn(`[mongokit] Invalid aggregation stage ${stage}:`, error);
       }
     }
     return pipeline.length > 0 ? pipeline : void 0;
@@ -1477,7 +1424,7 @@ var QueryParser = class {
       const populateOptions = [];
       for (const [path, config] of Object.entries(populateObj)) {
         if (path.startsWith("$") || this.dangerousOperators.includes(path)) {
-          console.warn(`[mongokit] Blocked dangerous populate path: ${path}`);
+          warn(`[mongokit] Blocked dangerous populate path: ${path}`);
           continue;
         }
         const option = this._parseSinglePopulate(path, config);
@@ -1494,7 +1441,7 @@ var QueryParser = class {
    */
   _parseSinglePopulate(path, config, depth = 0) {
     if (depth > 5) {
-      console.warn(`[mongokit] Populate depth exceeds maximum (5), truncating at path: ${path}`);
+      warn(`[mongokit] Populate depth exceeds maximum (5), truncating at path: ${path}`);
       return { path };
     }
     if (typeof config === "string") {
@@ -1566,14 +1513,14 @@ var QueryParser = class {
    */
   _parseFilters(filters, depth = 0) {
     if (depth > this.options.maxFilterDepth) {
-      console.warn(`[mongokit] Filter depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating`);
+      warn(`[mongokit] Filter depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating`);
       return {};
     }
     const parsedFilters = {};
     const regexFields = {};
     for (const [key, value] of Object.entries(filters)) {
       if (this.dangerousOperators.includes(key) || key.startsWith("$") && !["$or", "$and"].includes(key)) {
-        console.warn(`[mongokit] Blocked dangerous operator: ${key}`);
+        warn(`[mongokit] Blocked dangerous operator: ${key}`);
         continue;
       }
       if (["page", "limit", "sort", "populate", "search", "select", "lean", "includeDeleted", "lookup", "aggregate", "or", "OR", "$or"].includes(key)) {
@@ -1583,7 +1530,7 @@ var QueryParser = class {
       if (operatorMatch) {
         const [, , operator] = operatorMatch;
         if (this.dangerousOperators.includes("$" + operator)) {
-          console.warn(`[mongokit] Blocked dangerous operator: ${operator}`);
+          warn(`[mongokit] Blocked dangerous operator: ${operator}`);
           continue;
         }
         this._handleOperatorSyntax(parsedFilters, regexFields, operatorMatch, value);
@@ -1622,7 +1569,7 @@ var QueryParser = class {
     }
     const mongoOperator = this._toMongoOperator(operator);
     if (this.dangerousOperators.includes(mongoOperator)) {
-      console.warn(`[mongokit] Blocked dangerous operator: ${mongoOperator}`);
+      warn(`[mongokit] Blocked dangerous operator: ${mongoOperator}`);
       return;
     }
     if (mongoOperator === "$eq") {
@@ -1655,7 +1602,7 @@ var QueryParser = class {
    */
   _handleBracketSyntax(field, operators, parsedFilters, depth = 0) {
     if (depth > this.options.maxFilterDepth) {
-      console.warn(`[mongokit] Nested filter depth exceeds maximum, skipping field: ${field}`);
+      warn(`[mongokit] Nested filter depth exceeds maximum, skipping field: ${field}`);
       return;
     }
     if (!parsedFilters[field]) {
@@ -1714,11 +1661,11 @@ var QueryParser = class {
     if (pattern === null || pattern === void 0) return null;
     const patternStr = String(pattern);
     if (patternStr.length > this.options.maxRegexLength) {
-      console.warn(`[mongokit] Regex pattern too long, truncating`);
+      warn(`[mongokit] Regex pattern too long, truncating`);
       return new RegExp(this._escapeRegex(patternStr.substring(0, this.options.maxRegexLength)), flags);
     }
     if (this.dangerousRegexPatterns.test(patternStr)) {
-      console.warn("[mongokit] Potentially dangerous regex pattern, escaping");
+      warn("[mongokit] Potentially dangerous regex pattern, escaping");
       return new RegExp(this._escapeRegex(patternStr), flags);
     }
     try {
@@ -1738,7 +1685,7 @@ var QueryParser = class {
     const sanitized = {};
     for (const [key, value] of Object.entries(config)) {
       if (this.dangerousOperators.includes(key)) {
-        console.warn(`[mongokit] Blocked dangerous operator in aggregation: ${key}`);
+        warn(`[mongokit] Blocked dangerous operator in aggregation: ${key}`);
         continue;
       }
       if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -1756,12 +1703,65 @@ var QueryParser = class {
     }
     return sanitized;
   }
+  /**
+   * Sanitize pipeline stages for use in $lookup.
+   * Blocks dangerous stages ($out, $merge, etc.) and recursively sanitizes
+   * operator expressions within $match, $addFields, and $set stages.
+   */
+  _sanitizePipeline(stages) {
+    const blockedStages = ["$out", "$merge", "$unionWith", "$collStats", "$currentOp", "$listSessions"];
+    const sanitized = [];
+    for (const stage of stages) {
+      if (!stage || typeof stage !== "object") continue;
+      const entries = Object.entries(stage);
+      if (entries.length !== 1) continue;
+      const [op, config] = entries[0];
+      if (blockedStages.includes(op)) {
+        warn(`[mongokit] Blocked dangerous pipeline stage in lookup: ${op}`);
+        continue;
+      }
+      if (op === "$match" && typeof config === "object" && config !== null) {
+        sanitized.push({ $match: this._sanitizeMatchConfig(config) });
+      } else if ((op === "$addFields" || op === "$set") && typeof config === "object" && config !== null) {
+        sanitized.push({ [op]: this._sanitizeExpressions(config) });
+      } else {
+        sanitized.push(stage);
+      }
+    }
+    return sanitized;
+  }
+  /**
+   * Recursively sanitize expression objects, blocking dangerous operators
+   * like $where, $function, $accumulator inside $addFields/$set stages.
+   */
+  _sanitizeExpressions(config) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(config)) {
+      if (this.dangerousOperators.includes(key)) {
+        warn(`[mongokit] Blocked dangerous operator in pipeline expression: ${key}`);
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        sanitized[key] = this._sanitizeExpressions(value);
+      } else if (Array.isArray(value)) {
+        sanitized[key] = value.map((item) => {
+          if (item && typeof item === "object" && !Array.isArray(item)) {
+            return this._sanitizeExpressions(item);
+          }
+          return item;
+        });
+      } else {
+        sanitized[key] = value;
+      }
+    }
+    return sanitized;
+  }
   _sanitizeSearch(search) {
     if (search === null || search === void 0 || search === "") return void 0;
     let searchStr = String(search).trim();
     if (!searchStr) return void 0;
     if (searchStr.length > this.options.maxSearchLength) {
-      console.warn(`[mongokit] Search query too long, truncating`);
+      warn(`[mongokit] Search query too long, truncating`);
       searchStr = searchStr.substring(0, this.options.maxSearchLength);
     }
     return searchStr;
@@ -1890,4 +1890,4 @@ var index_default = Repository;
  * ```
  */
 
-export { AggregationBuilder, LookupBuilder, QueryParser, Repository, createRepository, index_default as default };
+export { AggregationBuilder, QueryParser, Repository, createRepository, index_default as default };