@classytic/mongokit 3.1.5 → 3.2.0

package/dist/chunks/{chunk-CSLJ2PL2.js → chunk-DEVXDBRL.js}

@@ -1,6 +1,7 @@
-import { upsert } from './chunk-CF6FLC2G.js';
+import { upsert } from './chunk-I7CWNAJB.js';
 import { versionKey, byIdKey, byQueryKey, listQueryKey, modelPattern, getFieldsForUser } from './chunk-2ZN65ZOP.js';
-import { createError } from './chunk-VJXDGP3C.js';
+import { warn, debug } from './chunk-URLJFIR7.js';
+import { createError } from './chunk-JWUAVZ3L.js';
 import mongoose from 'mongoose';
 
 // src/plugins/field-filter.plugin.ts
@@ -137,7 +138,7 @@ function softDeletePlugin(options = {}) {
           }
         ).catch((err) => {
           if (!err.message.includes("already exists")) {
-            console.warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
+            warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
           }
         });
       }
@@ -675,7 +676,7 @@ function cachePlugin(options) {
   let collectionVersion = 0;
   const log = (msg, data) => {
     if (config.debug) {
-      console.log(`[mongokit:cache] ${msg}`, data ?? "");
+      debug(`[mongokit:cache] ${msg}`, data ?? "");
     }
   };
   return {
@@ -779,7 +780,8 @@ function cachePlugin(options) {
           limit,
           after: context.after,
           select: context.select,
-          populate: context.populate
+          populate: context.populate,
+          search: context.search
         };
         const key = listQueryKey(config.prefix, model, collectionVersion, params);
         try {
@@ -846,7 +848,8 @@ function cachePlugin(options) {
           limit,
           after: context.after,
           select: context.select,
-          populate: context.populate
+          populate: context.populate,
+          search: context.search
         };
         const key = listQueryKey(config.prefix, model, collectionVersion, params);
         const ttl = context.cacheTtl ?? config.queryTtl;
@@ -988,7 +991,15 @@ function cascadePlugin(options) {
           }
         };
         if (parallel) {
-          await Promise.all(relations.map(cascadeDelete));
+          const results = await Promise.allSettled(relations.map(cascadeDelete));
+          const failures = results.filter((r) => r.status === "rejected");
+          if (failures.length) {
+            const err = failures[0].reason;
+            if (failures.length > 1) {
+              err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
+            }
+            throw err;
+          }
         } else {
           for (const relation of relations) {
             await cascadeDelete(relation);
@@ -1077,7 +1088,15 @@ function cascadePlugin(options) {
             }
           };
           if (parallel) {
-            await Promise.all(relations.map(cascadeDeleteMany));
+            const results = await Promise.allSettled(relations.map(cascadeDeleteMany));
+            const failures = results.filter((r) => r.status === "rejected");
+            if (failures.length) {
+              const err = failures[0].reason;
+              if (failures.length > 1) {
+                err.message = `${failures.length} cascade deletes failed. First: ${err.message}`;
+              }
+              throw err;
+            }
           } else {
             for (const relation of relations) {
               await cascadeDeleteMany(relation);
@@ -1089,4 +1108,119 @@ function cascadePlugin(options) {
   };
 }
 
-export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };
+// src/plugins/multi-tenant.plugin.ts
+function multiTenantPlugin(options = {}) {
+  const {
+    tenantField = "organizationId",
+    contextKey = "organizationId",
+    required = true,
+    skipOperations = [],
+    skipWhen,
+    resolveContext
+  } = options;
+  const readOps = ["getById", "getByQuery", "getAll", "aggregatePaginate", "lookupPopulate"];
+  const writeOps = ["create", "createMany", "update", "delete"];
+  const allOps = [...readOps, ...writeOps];
+  return {
+    name: "multi-tenant",
+    apply(repo) {
+      for (const op of allOps) {
+        if (skipOperations.includes(op)) continue;
+        repo.on(`before:${op}`, (context) => {
+          if (skipWhen?.(context, op)) return;
+          let tenantId = context[contextKey];
+          if (!tenantId && resolveContext) {
+            tenantId = resolveContext();
+            if (tenantId) context[contextKey] = tenantId;
+          }
+          if (!tenantId && required) {
+            throw new Error(
+              `[mongokit] Multi-tenant: Missing '${contextKey}' in context for '${op}'. Pass it via options or set required: false.`
+            );
+          }
+          if (!tenantId) return;
+          if (readOps.includes(op)) {
+            if (op === "getAll" || op === "aggregatePaginate" || op === "lookupPopulate") {
+              context.filters = { ...context.filters, [tenantField]: tenantId };
+            } else {
+              context.query = { ...context.query, [tenantField]: tenantId };
+            }
+          }
+          if (op === "create" && context.data) {
+            context.data[tenantField] = tenantId;
+          }
+          if (op === "createMany" && context.dataArray) {
+            for (const doc of context.dataArray) {
+              doc[tenantField] = tenantId;
+            }
+          }
+          if (op === "update" || op === "delete") {
+            context.query = { ...context.query, [tenantField]: tenantId };
+          }
+        });
+      }
+    }
+  };
+}
+
+// src/plugins/observability.plugin.ts
+var DEFAULT_OPS = [
+  "create",
+  "createMany",
+  "update",
+  "delete",
+  "getById",
+  "getByQuery",
+  "getAll",
+  "aggregatePaginate",
+  "lookupPopulate"
+];
+var timers = /* @__PURE__ */ new WeakMap();
+function observabilityPlugin(options) {
+  const { onMetric, slowThresholdMs } = options;
+  const ops = options.operations ?? DEFAULT_OPS;
+  return {
+    name: "observability",
+    apply(repo) {
+      for (const op of ops) {
+        repo.on(`before:${op}`, (context) => {
+          timers.set(context, performance.now());
+        });
+        repo.on(`after:${op}`, ({ context }) => {
+          const start = timers.get(context);
+          if (start == null) return;
+          const durationMs = Math.round((performance.now() - start) * 100) / 100;
+          timers.delete(context);
+          if (slowThresholdMs != null && durationMs < slowThresholdMs) return;
+          onMetric({
+            operation: op,
+            model: context.model || repo.model,
+            durationMs,
+            success: true,
+            startedAt: new Date(Date.now() - durationMs),
+            userId: context.user?._id?.toString() || context.user?.id?.toString(),
+            organizationId: context.organizationId?.toString()
+          });
+        });
+        repo.on(`error:${op}`, ({ context, error }) => {
+          const start = timers.get(context);
+          if (start == null) return;
+          const durationMs = Math.round((performance.now() - start) * 100) / 100;
+          timers.delete(context);
+          onMetric({
+            operation: op,
+            model: context.model || repo.model,
+            durationMs,
+            success: false,
+            error: error.message,
+            startedAt: new Date(Date.now() - durationMs),
+            userId: context.user?._id?.toString() || context.user?.id?.toString(),
+            organizationId: context.organizationId?.toString()
+          });
+        });
+      }
+    }
+  };
+}
+
+export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/chunks/{chunk-CF6FLC2G.js → chunk-I7CWNAJB.js}

@@ -1,4 +1,4 @@
-import { __export } from './chunk-VJXDGP3C.js';
+import { __export } from './chunk-WSFCRVEQ.js';
 
 // src/actions/create.ts
 var create_exports = {};

package/dist/chunks/chunk-JWUAVZ3L.js

@@ -0,0 +1,8 @@
+// src/utils/error.ts
+function createError(status, message) {
+  const error = new Error(message);
+  error.status = status;
+  return error;
+}
+
+export { createError };

package/dist/chunks/{chunk-IT7DCOKR.js → chunk-UE2IEXZJ.js}

@@ -3,34 +3,41 @@ import 'mongoose';
 // src/utils/memory-cache.ts
 function createMemoryCache(maxEntries = 1e3) {
   const cache = /* @__PURE__ */ new Map();
-  function cleanup() {
+  let lastCleanup = Date.now();
+  const CLEANUP_INTERVAL_MS = 6e4;
+  function cleanupIfNeeded() {
     const now = Date.now();
+    if (now - lastCleanup < CLEANUP_INTERVAL_MS) return;
+    lastCleanup = now;
     for (const [key, entry] of cache) {
-      if (entry.expiresAt < now) {
-        cache.delete(key);
-      }
+      if (entry.expiresAt < now) cache.delete(key);
     }
   }
   function evictOldest() {
-    if (cache.size >= maxEntries) {
+    while (cache.size >= maxEntries) {
       const firstKey = cache.keys().next().value;
       if (firstKey) cache.delete(firstKey);
+      else break;
     }
   }
   return {
     async get(key) {
-      cleanup();
       const entry = cache.get(key);
       if (!entry) return null;
       if (entry.expiresAt < Date.now()) {
         cache.delete(key);
         return null;
       }
+      cache.delete(key);
+      cache.set(key, entry);
       return entry.value;
     },
     async set(key, value, ttl) {
-      cleanup();
-      evictOldest();
+      cache.delete(key);
+      if (cache.size >= maxEntries) {
+        cleanupIfNeeded();
+        evictOldest();
+      }
       cache.set(key, {
         value,
         expiresAt: Date.now() + ttl * 1e3

package/dist/chunks/chunk-URLJFIR7.js

@@ -0,0 +1,22 @@
+// src/utils/logger.ts
+var noop = () => {
+};
+var current = {
+  warn: console.warn.bind(console),
+  debug: noop
+};
+function configureLogger(config) {
+  if (config === false) {
+    current = { warn: noop, debug: noop };
+  } else {
+    current = { ...current, ...config };
+  }
+}
+function warn(message, ...args) {
+  current.warn(message, ...args);
+}
+function debug(message, ...args) {
+  current.debug(message, ...args);
+}
+
+export { configureLogger, debug, warn };

package/dist/chunks/{chunk-SAKSLT47.js → chunk-VWKIKZYF.js}

@@ -1,5 +1,7 @@
-import { create_exports } from './chunk-CF6FLC2G.js';
-import { __export, createError } from './chunk-VJXDGP3C.js';
+import { create_exports } from './chunk-I7CWNAJB.js';
+import { warn } from './chunk-URLJFIR7.js';
+import { createError } from './chunk-JWUAVZ3L.js';
+import { __export } from './chunk-WSFCRVEQ.js';
 
 // src/actions/index.ts
 var actions_exports = {};
@@ -122,7 +124,8 @@ function parsePopulate2(populate) {
 }
 async function update(Model, id, data, options = {}) {
   assertUpdatePipelineAllowed(data, options.updatePipeline);
-  const document = await Model.findByIdAndUpdate(id, data, {
+  const query = { _id: id, ...options.query };
+  const document = await Model.findOneAndUpdate(query, data, {
     new: true,
     runValidators: true,
     session: options.session,
@@ -225,7 +228,8 @@ __export(delete_exports, {
   softDelete: () => softDelete
 });
 async function deleteById(Model, id, options = {}) {
-  const document = await Model.findByIdAndDelete(id).session(options.session ?? null);
+  const query = { _id: id, ...options.query };
+  const document = await Model.findOneAndDelete(query).session(options.session ?? null);
   if (!document) {
     throw createError(404, "Document not found");
   }
@@ -292,6 +296,268 @@ __export(aggregate_exports, {
   sum: () => sum,
   unwind: () => unwind
 });
+
+// src/query/LookupBuilder.ts
+var BLOCKED_PIPELINE_STAGES = ["$out", "$merge", "$unionWith", "$collStats", "$currentOp", "$listSessions"];
+var DANGEROUS_OPERATORS = ["$where", "$function", "$accumulator", "$expr"];
+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 {
+        const safePipeline = this.options.sanitize !== false ? _LookupBuilder.sanitizePipeline(pipeline) : pipeline;
+        lookupStage = {
+          $lookup: {
+            from,
+            ...letVars && { let: letVars },
+            pipeline: safePipeline,
+            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((lookup2) => {
+      const builder = new _LookupBuilder(lookup2.from).localField(lookup2.localField).foreignField(lookup2.foreignField);
+      if (lookup2.as) builder.as(lookup2.as);
+      if (lookup2.single) builder.single(lookup2.single);
+      if (lookup2.pipeline) builder.pipeline(lookup2.pipeline);
+      if (lookup2.let) builder.let(lookup2.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((lookup2, index) => {
+      const builder = new _LookupBuilder(lookup2.from).localField(lookup2.localField).foreignField(lookup2.foreignField);
+      if (lookup2.as) builder.as(lookup2.as);
+      if (lookup2.single !== void 0) builder.single(lookup2.single);
+      if (lookup2.pipeline) builder.pipeline(lookup2.pipeline);
+      if (lookup2.let) builder.let(lookup2.let);
+      return builder.build();
+    });
+  }
+  /**
+   * 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) {
+    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 (BLOCKED_PIPELINE_STAGES.includes(op)) {
+        warn(`[mongokit] Blocked dangerous pipeline stage in lookup: ${op}`);
+        continue;
+      }
+      if ((op === "$match" || op === "$addFields" || op === "$set") && typeof config === "object" && config !== null) {
+        sanitized.push({ [op]: _LookupBuilder._sanitizeDeep(config) });
+      } else {
+        sanitized.push(stage);
+      }
+    }
+    return sanitized;
+  }
+  /**
+   * Recursively remove dangerous operators from an expression object.
+   */
+  static _sanitizeDeep(config) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(config)) {
+      if (DANGEROUS_OPERATORS.includes(key)) {
+        warn(`[mongokit] Blocked dangerous operator in lookup pipeline: ${key}`);
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        sanitized[key] = _LookupBuilder._sanitizeDeep(value);
+      } else if (Array.isArray(value)) {
+        sanitized[key] = value.map((item) => {
+          if (item && typeof item === "object" && !Array.isArray(item)) {
+            return _LookupBuilder._sanitizeDeep(item);
+          }
+          return item;
+        });
+      } else {
+        sanitized[key] = value;
+      }
+    }
+    return sanitized;
+  }
+};
+
+// src/actions/aggregate.ts
 async function aggregate(Model, pipeline, options = {}) {
   const aggregation = Model.aggregate(pipeline);
   if (options.session) {
@@ -305,7 +571,7 @@ async function aggregatePaginate(Model, pipeline, options = {}) {
   const skip = (page - 1) * limit;
   const SAFE_LIMIT = 1e3;
   if (limit > SAFE_LIMIT) {
-    console.warn(
+    warn(
       `[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`
     );
   }
@@ -384,11 +650,12 @@ async function lookup(Model, lookupOptions) {
         }
       });
     } else {
+      const safePipeline = lookupOptions.sanitize !== false ? LookupBuilder.sanitizePipeline(pipeline) : pipeline;
       aggPipeline.push({
         $lookup: {
           from,
           ...letVars && { let: letVars },
-          pipeline,
+          pipeline: safePipeline,
           as
         }
       });
@@ -467,4 +734,4 @@ async function minMax(Model, field, query = {}, options = {}) {
   return result[0] || { min: null, max: null };
 }
 
-export { actions_exports, aggregate, aggregate_exports, count, deleteById, delete_exports, distinct, exists, getById, getByQuery, getOrCreate, read_exports, update, update_exports };
+export { LookupBuilder, actions_exports, aggregate, aggregate_exports, count, deleteById, delete_exports, distinct, exists, getById, getByQuery, getOrCreate, read_exports, update, update_exports };

package/dist/chunks/chunk-WSFCRVEQ.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export { __export };

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