@classytic/mongokit 3.0.5 → 3.1.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import mongoose4 from 'mongoose';
+import mongoose from 'mongoose';
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -403,20 +403,51 @@ async function countBy(Model, field, query = {}, options = {}) {
   return aggregate(Model, pipeline, options);
 }
 async function lookup(Model, lookupOptions) {
-  const { from, localField, foreignField, as, pipeline = [], query = {}, options = {} } = lookupOptions;
+  const { from, localField, foreignField, as, pipeline = [], let: letVars, query = {}, options = {} } = lookupOptions;
   const aggPipeline = [];
   if (Object.keys(query).length > 0) {
     aggPipeline.push({ $match: query });
   }
-  aggPipeline.push({
-    $lookup: {
-      from,
-      localField,
-      foreignField,
-      as,
-      ...pipeline.length > 0 ? { pipeline } : {}
+  const usePipelineForm = pipeline.length > 0 || letVars;
+  if (usePipelineForm) {
+    if (pipeline.length === 0 && localField && foreignField) {
+      const autoPipeline = [
+        {
+          $match: {
+            $expr: {
+              $eq: [`$${foreignField}`, `$$${localField}`]
+            }
+          }
+        }
+      ];
+      aggPipeline.push({
+        $lookup: {
+          from,
+          let: { [localField]: `$${localField}`, ...letVars || {} },
+          pipeline: autoPipeline,
+          as
+        }
+      });
+    } else {
+      aggPipeline.push({
+        $lookup: {
+          from,
+          ...letVars && { let: letVars },
+          pipeline,
+          as
+        }
+      });
     }
-  });
+  } else {
+    aggPipeline.push({
+      $lookup: {
+        from,
+        localField,
+        foreignField,
+        as
+      }
+    });
+  }
   return aggregate(Model, aggPipeline, options);
 }
 async function unwind(Model, field, options = {}) {
@@ -521,12 +552,12 @@ function validateCursorVersion(cursorVersion, expectedVersion) {
 }
 function serializeValue(value) {
   if (value instanceof Date) return value.toISOString();
-  if (value instanceof mongoose4.Types.ObjectId) return value.toString();
+  if (value instanceof mongoose.Types.ObjectId) return value.toString();
   return value;
 }
 function getValueType(value) {
   if (value instanceof Date) return "date";
-  if (value instanceof mongoose4.Types.ObjectId) return "objectid";
+  if (value instanceof mongoose.Types.ObjectId) return "objectid";
   if (typeof value === "boolean") return "boolean";
   if (typeof value === "number") return "number";
   if (typeof value === "string") return "string";
@@ -537,7 +568,7 @@ function rehydrateValue(serialized, type) {
     case "date":
       return new Date(serialized);
     case "objectid":
-      return new mongoose4.Types.ObjectId(serialized);
+      return new mongoose.Types.ObjectId(serialized);
     case "boolean":
       return Boolean(serialized);
     case "number":
@@ -837,6 +868,640 @@ var PaginationEngine = class {
   }
 };
 
+// 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((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();
+    });
+  }
+};
+
+// src/query/AggregationBuilder.ts
+function normalizeSortSpec(sortSpec) {
+  const normalized = {};
+  for (const [field, order] of Object.entries(sortSpec)) {
+    if (order === "asc") {
+      normalized[field] = 1;
+    } else if (order === "desc") {
+      normalized[field] = -1;
+    } else {
+      normalized[field] = order;
+    }
+  }
+  return normalized;
+}
+var AggregationBuilder = class _AggregationBuilder {
+  pipeline = [];
+  /**
+   * Get the current pipeline
+   */
+  get() {
+    return [...this.pipeline];
+  }
+  /**
+   * Build and return the final pipeline
+   */
+  build() {
+    return this.get();
+  }
+  /**
+   * Reset the pipeline
+   */
+  reset() {
+    this.pipeline = [];
+    return this;
+  }
+  /**
+   * Add a raw pipeline stage
+   */
+  addStage(stage) {
+    this.pipeline.push(stage);
+    return this;
+  }
+  /**
+   * Add multiple raw pipeline stages
+   */
+  addStages(stages) {
+    this.pipeline.push(...stages);
+    return this;
+  }
+  // ============================================================
+  // CORE AGGREGATION STAGES
+  // ============================================================
+  /**
+   * $match - Filter documents
+   * IMPORTANT: Place $match as early as possible for performance
+   */
+  match(query) {
+    this.pipeline.push({ $match: query });
+    return this;
+  }
+  /**
+   * $project - Include/exclude fields or compute new fields
+   */
+  project(projection) {
+    this.pipeline.push({ $project: projection });
+    return this;
+  }
+  /**
+   * $group - Group documents and compute aggregations
+   *
+   * @example
+   * ```typescript
+   * .group({
+   *   _id: '$department',
+   *   count: { $sum: 1 },
+   *   avgSalary: { $avg: '$salary' }
+   * })
+   * ```
+   */
+  group(groupSpec) {
+    this.pipeline.push({ $group: groupSpec });
+    return this;
+  }
+  /**
+   * $sort - Sort documents
+   */
+  sort(sortSpec) {
+    if (typeof sortSpec === "string") {
+      const order = sortSpec.startsWith("-") ? -1 : 1;
+      const field = sortSpec.startsWith("-") ? sortSpec.substring(1) : sortSpec;
+      this.pipeline.push({ $sort: { [field]: order } });
+    } else {
+      this.pipeline.push({ $sort: normalizeSortSpec(sortSpec) });
+    }
+    return this;
+  }
+  /**
+   * $limit - Limit number of documents
+   */
+  limit(count2) {
+    this.pipeline.push({ $limit: count2 });
+    return this;
+  }
+  /**
+   * $skip - Skip documents
+   */
+  skip(count2) {
+    this.pipeline.push({ $skip: count2 });
+    return this;
+  }
+  /**
+   * $unwind - Deconstruct array field
+   */
+  unwind(path, preserveNullAndEmptyArrays = false) {
+    this.pipeline.push({
+      $unwind: {
+        path: path.startsWith("$") ? path : `$${path}`,
+        preserveNullAndEmptyArrays
+      }
+    });
+    return this;
+  }
+  /**
+   * $addFields - Add new fields or replace existing fields
+   */
+  addFields(fields) {
+    this.pipeline.push({ $addFields: fields });
+    return this;
+  }
+  /**
+   * $set - Alias for $addFields
+   */
+  set(fields) {
+    return this.addFields(fields);
+  }
+  /**
+   * $unset - Remove fields
+   */
+  unset(fields) {
+    this.pipeline.push({ $unset: fields });
+    return this;
+  }
+  /**
+   * $replaceRoot - Replace the root document
+   */
+  replaceRoot(newRoot) {
+    this.pipeline.push({
+      $replaceRoot: {
+        newRoot: typeof newRoot === "string" ? `$${newRoot}` : newRoot
+      }
+    });
+    return this;
+  }
+  // ============================================================
+  // LOOKUP (JOINS)
+  // ============================================================
+  /**
+   * $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, localField, foreignField, as, single) {
+    const stages = new LookupBuilder(from).localField(localField).foreignField(foreignField).as(as || from).single(single || false).build();
+    this.pipeline.push(...stages);
+    return 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) {
+    const builder = new LookupBuilder(options.from).localField(options.localField).foreignField(options.foreignField);
+    if (options.as) builder.as(options.as);
+    if (options.single) builder.single(options.single);
+    if (options.pipeline) builder.pipeline(options.pipeline);
+    if (options.let) builder.let(options.let);
+    this.pipeline.push(...builder.build());
+    return 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) {
+    const stages = LookupBuilder.multiple(lookups);
+    this.pipeline.push(...stages);
+    return this;
+  }
+  // ============================================================
+  // ADVANCED OPERATORS (MongoDB 6+)
+  // ============================================================
+  /**
+   * $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) {
+    this.pipeline.push({ $facet: facets });
+    return 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) {
+    this.pipeline.push({ $bucket: options });
+    return this;
+  }
+  /**
+   * $bucketAuto - Automatically determine bucket boundaries
+   */
+  bucketAuto(options) {
+    this.pipeline.push({ $bucketAuto: options });
+    return 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) {
+    const normalizedOptions = {
+      ...options,
+      sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+    };
+    this.pipeline.push({ $setWindowFields: normalizedOptions });
+    return this;
+  }
+  /**
+   * $unionWith - Combine results from multiple collections (MongoDB 4.4+)
+   *
+   * @example
+   * ```typescript
+   * .unionWith({
+   *   coll: 'archivedOrders',
+   *   pipeline: [{ $match: { year: 2024 } }]
+   * })
+   * ```
+   */
+  unionWith(options) {
+    this.pipeline.push({ $unionWith: options });
+    return this;
+  }
+  /**
+   * $densify - Fill gaps in data (MongoDB 5.1+)
+   * Useful for time series data with missing points
+   */
+  densify(options) {
+    this.pipeline.push({ $densify: options });
+    return this;
+  }
+  /**
+   * $fill - Fill null or missing field values (MongoDB 5.3+)
+   */
+  fill(options) {
+    const normalizedOptions = {
+      ...options,
+      sortBy: options.sortBy ? normalizeSortSpec(options.sortBy) : void 0
+    };
+    this.pipeline.push({ $fill: normalizedOptions });
+    return this;
+  }
+  // ============================================================
+  // UTILITY METHODS
+  // ============================================================
+  /**
+   * Paginate - Add skip and limit for offset-based pagination
+   */
+  paginate(page, limit) {
+    const skip = (page - 1) * limit;
+    return this.skip(skip).limit(limit);
+  }
+  /**
+   * Count total documents (useful with $facet for pagination metadata)
+   */
+  count(outputField = "count") {
+    this.pipeline.push({ $count: outputField });
+    return this;
+  }
+  /**
+   * Sample - Randomly select N documents
+   */
+  sample(size) {
+    this.pipeline.push({ $sample: { size } });
+    return this;
+  }
+  /**
+   * Out - Write results to a collection
+   */
+  out(collection) {
+    this.pipeline.push({ $out: collection });
+    return this;
+  }
+  /**
+   * Merge - Merge results into a collection
+   */
+  merge(options) {
+    this.pipeline.push({
+      $merge: typeof options === "string" ? { into: options } : options
+    });
+    return this;
+  }
+  /**
+   * GeoNear - Perform geospatial queries
+   */
+  geoNear(options) {
+    this.pipeline.push({ $geoNear: options });
+    return this;
+  }
+  /**
+   * GraphLookup - Perform recursive search (graph traversal)
+   */
+  graphLookup(options) {
+    this.pipeline.push({ $graphLookup: options });
+    return this;
+  }
+  // ============================================================
+  // ATLAS SEARCH (MongoDB Atlas only)
+  // ============================================================
+  /**
+   * $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) {
+    this.pipeline.push({ $search: options });
+    return this;
+  }
+  /**
+   * $searchMeta - Get Atlas Search metadata (Atlas only)
+   */
+  searchMeta(options) {
+    this.pipeline.push({ $searchMeta: options });
+    return this;
+  }
+  // ============================================================
+  // HELPER FACTORY METHODS
+  // ============================================================
+  /**
+   * Create a builder from an existing pipeline
+   */
+  static from(pipeline) {
+    const builder = new _AggregationBuilder();
+    builder.pipeline = [...pipeline];
+    return builder;
+  }
+  /**
+   * Create a builder with initial match stage
+   */
+  static startWith(query) {
+    return new _AggregationBuilder().match(query);
+  }
+};
+
 // src/Repository.ts
 var Repository = class {
   Model;
@@ -999,8 +1664,8 @@ var Repository = class {
     }
     const hasPageParam = params.page !== void 0 || params.pagination;
     const hasCursorParam = "cursor" in params || "after" in params;
-    const hasExplicitSort = params.sort !== void 0;
-    const useKeyset = !hasPageParam && (hasCursorParam || hasExplicitSort);
+    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";
@@ -1105,23 +1770,186 @@ var Repository = class {
   async distinct(field, query = {}, options = {}) {
     return distinct(this.Model, field, query, options);
   }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async lookupPopulate(options) {
+    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);
+      }
+      builder.multiLookup(options.lookups);
+      if (options.sort) {
+        builder.sort(this._parseSort(options.sort));
+      }
+      const page = options.page || 1;
+      const limit = options.limit || this._pagination.config.defaultLimit || 20;
+      const skip = (page - 1) * limit;
+      const SAFE_LIMIT = 1e3;
+      const SAFE_MAX_OFFSET = 1e4;
+      if (limit > SAFE_LIMIT) {
+        console.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(
+          `[mongokit] Large offset (${skip}) in lookupPopulate. $facet with high offsets can exceed 16MB. For deep pagination, consider using keyset/cursor-based pagination instead.`
+        );
+      }
+      const dataStages = [
+        { $skip: skip },
+        { $limit: limit }
+      ];
+      if (options.select) {
+        let projection;
+        if (typeof options.select === "string") {
+          projection = {};
+          const fields = options.select.split(",").map((f) => f.trim());
+          for (const field of fields) {
+            if (field.startsWith("-")) {
+              projection[field.substring(1)] = 0;
+            } else {
+              projection[field] = 1;
+            }
+          }
+        } else if (Array.isArray(options.select)) {
+          projection = {};
+          for (const field of options.select) {
+            if (field.startsWith("-")) {
+              projection[field.substring(1)] = 0;
+            } else {
+              projection[field] = 1;
+            }
+          }
+        } else {
+          projection = options.select;
+        }
+        dataStages.push({ $project: projection });
+      }
+      builder.facet({
+        metadata: [{ $count: "total" }],
+        data: dataStages
+      });
+      const pipeline = builder.build();
+      const results = await this.Model.aggregate(pipeline).session(options.session || null);
+      const result = results[0] || { metadata: [], data: [] };
+      const total = result.metadata[0]?.total || 0;
+      const data = result.data || [];
+      await this._emitHook("after:lookupPopulate", { context, result: data });
+      return {
+        data,
+        total,
+        page,
+        limit
+      };
+    } catch (error) {
+      await this._emitErrorHook("error:lookupPopulate", { context, error });
+      throw this._handleError(error);
+    }
+  }
+  /**
+   * 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() {
+    return new 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) {
+    return new LookupBuilder(from);
+  }
   /**
    * Execute callback within a transaction
    */
-  async withTransaction(callback) {
-    const session = await mongoose4.startSession();
-    session.startTransaction();
+  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();
       return result;
     } catch (error) {
-      await session.abortTransaction();
-      throw error;
+      const err = error;
+      if (options.allowFallback && this._isTransactionUnsupported(err)) {
+        if (typeof options.onFallback === "function") {
+          options.onFallback(err);
+        }
+        if (started && session.inTransaction()) {
+          try {
+            await session.abortTransaction();
+          } catch {
+          }
+        }
+        return await callback(null);
+      }
+      if (started && session.inTransaction()) {
+        await session.abortTransaction();
+      }
+      throw err;
     } finally {
       session.endSession();
     }
   }
+  _isTransactionUnsupported(error) {
+    const message = (error.message || "").toLowerCase();
+    return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("replica set") || message.includes("mongos");
+  }
   /**
    * Execute custom query with event emission
    */
@@ -1172,11 +2000,11 @@ var Repository = class {
    * Handle errors with proper HTTP status codes
    */
   _handleError(error) {
-    if (error instanceof mongoose4.Error.ValidationError) {
+    if (error instanceof mongoose.Error.ValidationError) {
       const messages = Object.values(error.errors).map((err) => err.message);
       return createError(400, `Validation Error: ${messages.join(", ")}`);
     }
-    if (error instanceof mongoose4.Error.CastError) {
+    if (error instanceof mongoose.Error.CastError) {
       return createError(400, `Invalid ${error.path}: ${error.value}`);
     }
     if (error.status && error.message) return error;
@@ -2207,7 +3035,7 @@ function cascadePlugin(options) {
         }
         const isSoftDelete = context.softDeleted === true;
         const cascadeDelete = async (relation) => {
-          const RelatedModel = mongoose4.models[relation.model];
+          const RelatedModel = mongoose.models[relation.model];
           if (!RelatedModel) {
             logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`, {
               parentModel: context.model,
@@ -2298,7 +3126,7 @@ function cascadePlugin(options) {
           }
           const isSoftDelete = context.softDeleted === true;
           const cascadeDeleteMany = async (relation) => {
-            const RelatedModel = mongoose4.models[relation.model];
+            const RelatedModel = mongoose.models[relation.model];
             if (!RelatedModel) {
               logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`, {
                 parentModel: context.model
@@ -2414,24 +3242,15 @@ function createMemoryCache(maxEntries = 1e3) {
     }
   };
 }
-function isMongooseSchema(value) {
-  return value instanceof mongoose4.Schema;
-}
-function isPlainObject(value) {
-  return Object.prototype.toString.call(value) === "[object Object]";
-}
-function isObjectIdType(t) {
-  return t === mongoose4.Schema.Types.ObjectId || t === mongoose4.Types.ObjectId;
-}
 function buildCrudSchemasFromMongooseSchema(mongooseSchema, options = {}) {
-  const tree = mongooseSchema?.obj || {};
-  const jsonCreate = buildJsonSchemaForCreate(tree, options);
+  const jsonCreate = buildJsonSchemaFromPaths(mongooseSchema, options);
   const jsonUpdate = buildJsonSchemaForUpdate(jsonCreate, options);
   const jsonParams = {
     type: "object",
     properties: { id: { type: "string", pattern: "^[0-9a-fA-F]{24}$" } },
     required: ["id"]
   };
+  const tree = mongooseSchema?.obj || {};
   const jsonQuery = buildJsonSchemaForQuery(tree, options);
   return { createBody: jsonCreate, updateBody: jsonUpdate, params: jsonParams, listQuery: jsonQuery };
 }
@@ -2485,88 +3304,37 @@ function validateUpdateBody(body = {}, options = {}) {
     violations
   };
 }
-function jsonTypeFor(def, options, seen) {
-  if (Array.isArray(def)) {
-    if (def[0] === mongoose4.Schema.Types.Mixed) {
-      return { type: "array", items: { type: "object", additionalProperties: true } };
-    }
-    return { type: "array", items: jsonTypeFor(def[0] ?? String, options, seen) };
-  }
-  if (isPlainObject(def) && "type" in def) {
-    const typedDef = def;
-    if (typedDef.enum && Array.isArray(typedDef.enum) && typedDef.enum.length) {
-      return { type: "string", enum: typedDef.enum.map(String) };
-    }
-    if (Array.isArray(typedDef.type)) {
-      const inner = typedDef.type[0] !== void 0 ? typedDef.type[0] : String;
-      if (inner === mongoose4.Schema.Types.Mixed) {
-        return { type: "array", items: { type: "object", additionalProperties: true } };
+function buildJsonSchemaFromPaths(mongooseSchema, options) {
+  const properties = {};
+  const required = [];
+  const paths = mongooseSchema.paths;
+  const rootFields = /* @__PURE__ */ new Map();
+  for (const [path, schemaType] of Object.entries(paths)) {
+    if (path === "_id" || path === "__v") continue;
+    const parts = path.split(".");
+    const rootField = parts[0];
+    if (!rootFields.has(rootField)) {
+      rootFields.set(rootField, []);
+    }
+    rootFields.get(rootField).push({ path, schemaType });
+  }
+  for (const [rootField, fieldPaths] of rootFields.entries()) {
+    if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
+      const schemaType = fieldPaths[0].schemaType;
+      properties[rootField] = schemaTypeToJsonSchema(schemaType);
+      if (schemaType.isRequired) {
+        required.push(rootField);
       }
-      return { type: "array", items: jsonTypeFor(inner, options, seen) };
-    }
-    if (typedDef.type === String) return { type: "string" };
-    if (typedDef.type === Number) return { type: "number" };
-    if (typedDef.type === Boolean) return { type: "boolean" };
-    if (typedDef.type === Date) {
-      const mode = options?.dateAs || "datetime";
-      return mode === "date" ? { type: "string", format: "date" } : { type: "string", format: "date-time" };
-    }
-    if (typedDef.type === Map || typedDef.type === mongoose4.Schema.Types.Map) {
-      const ofSchema = jsonTypeFor(typedDef.of || String, options, seen);
-      return { type: "object", additionalProperties: ofSchema };
-    }
-    if (typedDef.type === mongoose4.Schema.Types.Mixed) {
-      return { type: "object", additionalProperties: true };
-    }
-    if (isObjectIdType(typedDef.type)) {
-      return { type: "string", pattern: "^[0-9a-fA-F]{24}$" };
-    }
-    if (isMongooseSchema(typedDef.type)) {
-      const obj = typedDef.type.obj;
-      if (obj && typeof obj === "object") {
-        if (seen.has(obj)) return { type: "object", additionalProperties: true };
-        seen.add(obj);
-        return convertTreeToJsonSchema(obj, options, seen);
+    } else {
+      const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
+      properties[rootField] = nestedSchema.schema;
+      if (nestedSchema.required) {
+        required.push(rootField);
       }
     }
   }
-  if (def === String) return { type: "string" };
-  if (def === Number) return { type: "number" };
-  if (def === Boolean) return { type: "boolean" };
-  if (def === Date) {
-    const mode = options?.dateAs || "datetime";
-    return mode === "date" ? { type: "string", format: "date" } : { type: "string", format: "date-time" };
-  }
-  if (isObjectIdType(def)) return { type: "string", pattern: "^[0-9a-fA-F]{24}$" };
-  if (isPlainObject(def)) {
-    if (seen.has(def)) return { type: "object", additionalProperties: true };
-    seen.add(def);
-    return convertTreeToJsonSchema(def, options, seen);
-  }
-  return {};
-}
-function convertTreeToJsonSchema(tree, options, seen = /* @__PURE__ */ new WeakSet()) {
-  if (!tree || typeof tree !== "object") {
-    return { type: "object", properties: {} };
-  }
-  if (seen.has(tree)) {
-    return { type: "object", additionalProperties: true };
-  }
-  seen.add(tree);
-  const properties = {};
-  const required = [];
-  for (const [key, val] of Object.entries(tree || {})) {
-    if (key === "__v" || key === "_id" || key === "id") continue;
-    const cfg = isPlainObject(val) && "type" in val ? val : { };
-    properties[key] = jsonTypeFor(val, options, seen);
-    if (cfg.required === true) required.push(key);
-  }
   const schema = { type: "object", properties };
   if (required.length) schema.required = required;
-  return schema;
-}
-function buildJsonSchemaForCreate(tree, options) {
-  const base = convertTreeToJsonSchema(tree, options, /* @__PURE__ */ new WeakSet());
   const fieldsToOmit = /* @__PURE__ */ new Set(["createdAt", "updatedAt", "__v"]);
   (options?.create?.omitFields || []).forEach((f) => fieldsToOmit.add(f));
   const fieldRules = options?.fieldRules || {};
@@ -2576,37 +3344,96 @@ function buildJsonSchemaForCreate(tree, options) {
     }
   });
   fieldsToOmit.forEach((field) => {
-    if (base.properties?.[field]) {
-      delete base.properties[field];
+    if (schema.properties?.[field]) {
+      delete schema.properties[field];
     }
-    if (base.required) {
-      base.required = base.required.filter((k) => k !== field);
+    if (schema.required) {
+      schema.required = schema.required.filter((k) => k !== field);
     }
   });
   const reqOv = options?.create?.requiredOverrides || {};
   const optOv = options?.create?.optionalOverrides || {};
-  base.required = base.required || [];
+  schema.required = schema.required || [];
   for (const [k, v] of Object.entries(reqOv)) {
-    if (v && !base.required.includes(k)) base.required.push(k);
+    if (v && !schema.required.includes(k)) schema.required.push(k);
   }
   for (const [k, v] of Object.entries(optOv)) {
-    if (v && base.required) base.required = base.required.filter((x) => x !== k);
+    if (v && schema.required) schema.required = schema.required.filter((x) => x !== k);
   }
   Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.optional && base.required) {
-      base.required = base.required.filter((x) => x !== field);
+    if (rules.optional && schema.required) {
+      schema.required = schema.required.filter((x) => x !== field);
     }
   });
   const schemaOverrides = options?.create?.schemaOverrides || {};
   for (const [k, override] of Object.entries(schemaOverrides)) {
-    if (base.properties?.[k]) {
-      base.properties[k] = override;
+    if (schema.properties?.[k]) {
+      schema.properties[k] = override;
     }
   }
   if (options?.strictAdditionalProperties === true) {
-    base.additionalProperties = false;
+    schema.additionalProperties = false;
   }
-  return base;
+  return schema;
+}
+function buildNestedJsonSchema(fieldPaths, rootField) {
+  const properties = {};
+  const required = [];
+  let hasRequiredFields = false;
+  for (const { path, schemaType } of fieldPaths) {
+    const relativePath = path.substring(rootField.length + 1);
+    const parts = relativePath.split(".");
+    if (parts.length === 1) {
+      properties[parts[0]] = schemaTypeToJsonSchema(schemaType);
+      if (schemaType.isRequired) {
+        required.push(parts[0]);
+        hasRequiredFields = true;
+      }
+    } else {
+      const fieldName = parts[0];
+      if (!properties[fieldName]) {
+        properties[fieldName] = { type: "object", properties: {} };
+      }
+      const nestedObj = properties[fieldName];
+      if (!nestedObj.properties) nestedObj.properties = {};
+      const deepPath = parts.slice(1).join(".");
+      nestedObj.properties[deepPath] = schemaTypeToJsonSchema(schemaType);
+    }
+  }
+  const schema = { type: "object", properties };
+  if (required.length) schema.required = required;
+  return { schema, required: hasRequiredFields };
+}
+function schemaTypeToJsonSchema(schemaType) {
+  const result = {};
+  const instance = schemaType.instance;
+  const options = schemaType.options || {};
+  if (instance === "String") {
+    result.type = "string";
+    if (typeof options.minlength === "number") result.minLength = options.minlength;
+    if (typeof options.maxlength === "number") result.maxLength = options.maxlength;
+    if (options.match instanceof RegExp) result.pattern = options.match.source;
+    if (options.enum && Array.isArray(options.enum)) result.enum = options.enum;
+  } else if (instance === "Number") {
+    result.type = "number";
+    if (typeof options.min === "number") result.minimum = options.min;
+    if (typeof options.max === "number") result.maximum = options.max;
+  } else if (instance === "Boolean") {
+    result.type = "boolean";
+  } else if (instance === "Date") {
+    result.type = "string";
+    result.format = "date-time";
+  } else if (instance === "ObjectId" || instance === "ObjectID") {
+    result.type = "string";
+    result.pattern = "^[0-9a-fA-F]{24}$";
+  } else if (instance === "Array") {
+    result.type = "array";
+    result.items = { type: "string" };
+  } else {
+    result.type = "object";
+    result.additionalProperties = true;
+  }
+  return result;
 }
 function buildJsonSchemaForUpdate(createJson, options) {
   const clone = JSON.parse(JSON.stringify(createJson));
@@ -2627,6 +3454,9 @@ function buildJsonSchemaForUpdate(createJson, options) {
   if (options?.strictAdditionalProperties === true) {
     clone.additionalProperties = false;
   }
+  if (options?.update?.requireAtLeastOne === true) {
+    clone.minProperties = 1;
+  }
   return clone;
 }
 function buildJsonSchemaForQuery(_tree, options) {
@@ -2670,21 +3500,26 @@ var QueryParser = class {
     size: "$size",
     type: "$type"
   };
-  /**
-   * Dangerous MongoDB operators that should never be accepted from user input
-   * Security: Prevent NoSQL injection attacks
-   */
   dangerousOperators;
   /**
-   * Regex pattern characters that can cause catastrophic backtracking (ReDoS)
+   * 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: [...]...[...]
    */
-  dangerousRegexPatterns = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\([^)]*\))\1|\(\?[^)]*\)|[\[\]].*[\[\]])/;
+  dangerousRegexPatterns = /(\{[0-9,]+\}|\*\+|\+\+|\?\+|(\(.+\))\+|\(\?\:|\\[0-9]|(\[.+\]).+(\[.+\]))/;
   constructor(options = {}) {
     this.options = {
       maxRegexLength: options.maxRegexLength ?? 500,
       maxSearchLength: options.maxSearchLength ?? 200,
       maxFilterDepth: options.maxFilterDepth ?? 10,
-      additionalDangerousOperators: options.additionalDangerousOperators ?? []
+      maxLimit: options.maxLimit ?? 1e3,
+      additionalDangerousOperators: options.additionalDangerousOperators ?? [],
+      enableLookups: options.enableLookups ?? true,
+      enableAggregations: options.enableAggregations ?? false
     };
     this.dangerousOperators = [
       "$where",
@@ -2695,9 +3530,16 @@ var QueryParser = class {
     ];
   }
   /**
-   * Parse query parameters into MongoDB query format
+   * 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 }
+   * ```
    */
-  parseQuery(query) {
+  parse(query) {
     const {
       page,
       limit = 20,
@@ -2706,15 +3548,35 @@ var QueryParser = class {
       search,
       after,
       cursor,
+      select,
+      lookup: lookup2,
+      aggregate: aggregate2,
       ...filters
     } = query || {};
+    let parsedLimit = parseInt(String(limit), 10);
+    if (isNaN(parsedLimit) || parsedLimit < 1) {
+      parsedLimit = 20;
+    }
+    if (parsedLimit > this.options.maxLimit) {
+      console.warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${this.options.maxLimit}, capping to max`);
+      parsedLimit = this.options.maxLimit;
+    }
     const parsed = {
       filters: this._parseFilters(filters),
-      limit: parseInt(String(limit), 10),
+      limit: parsedLimit,
       sort: this._parseSort(sort),
       populate,
       search: this._sanitizeSearch(search)
     };
+    if (select) {
+      parsed.select = this._parseSelect(select);
+    }
+    if (this.options.enableLookups && lookup2) {
+      parsed.lookups = this._parseLookups(lookup2);
+    }
+    if (this.options.enableAggregations && aggregate2) {
+      parsed.aggregation = this._parseAggregation(aggregate2);
+    }
     if (after || cursor) {
       parsed.after = after || cursor;
     } else if (page !== void 0) {
@@ -2729,29 +3591,161 @@ var QueryParser = class {
     parsed.filters = this._enhanceWithBetween(parsed.filters);
     return parsed;
   }
+  // ============================================================
+  // LOOKUP PARSING (NEW)
+  // ============================================================
   /**
-   * Parse sort parameter
-   * Converts string like '-createdAt' to { createdAt: -1 }
-   * Handles multiple sorts: '-createdAt,name' → { createdAt: -1, name: 1 }
+   * 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 }]
+   * ```
    */
-  _parseSort(sort) {
-    if (!sort) return void 0;
-    if (typeof sort === "object") return sort;
-    const sortObj = {};
-    const fields = sort.split(",").map((s) => s.trim());
-    for (const field of fields) {
-      if (field.startsWith("-")) {
-        sortObj[field.substring(1)] = -1;
-      } else {
-        sortObj[field] = 1;
+  _parseLookups(lookup2) {
+    if (!lookup2 || typeof lookup2 !== "object") return [];
+    const lookups = [];
+    const lookupObj = lookup2;
+    for (const [collectionName, config] of Object.entries(lookupObj)) {
+      try {
+        const lookupConfig = this._parseSingleLookup(collectionName, config);
+        if (lookupConfig) {
+          lookups.push(lookupConfig);
+        }
+      } catch (error) {
+        console.warn(`[mongokit] Invalid lookup config for ${collectionName}:`, error);
       }
     }
-    return sortObj;
+    return lookups;
+  }
+  /**
+   * Parse a single lookup configuration
+   */
+  _parseSingleLookup(collectionName, config) {
+    if (!config) return null;
+    if (typeof config === "string") {
+      return {
+        from: this._pluralize(collectionName),
+        localField: `${collectionName}${this._capitalize(config)}`,
+        foreignField: config,
+        as: collectionName,
+        single: true
+      };
+    }
+    if (typeof config === "object" && config !== null) {
+      const opts = config;
+      const from = opts.from || this._pluralize(collectionName);
+      const localField = opts.localField;
+      const foreignField = opts.foreignField;
+      if (!localField || !foreignField) {
+        console.warn(`[mongokit] Lookup requires localField and foreignField for ${collectionName}`);
+        return null;
+      }
+      return {
+        from,
+        localField,
+        foreignField,
+        as: opts.as || collectionName,
+        single: opts.single === true || opts.single === "true",
+        ...opts.pipeline && Array.isArray(opts.pipeline) ? { pipeline: opts.pipeline } : {}
+      };
+    }
+    return null;
+  }
+  // ============================================================
+  // AGGREGATION PARSING (ADVANCED)
+  // ============================================================
+  /**
+   * 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' }
+   * });
+   * ```
+   */
+  _parseAggregation(aggregate2) {
+    if (!aggregate2 || typeof aggregate2 !== "object") return void 0;
+    const pipeline = [];
+    const aggObj = aggregate2;
+    for (const [stage, config] of Object.entries(aggObj)) {
+      try {
+        if (stage === "group" && typeof config === "object") {
+          pipeline.push({ $group: config });
+        } else if (stage === "match" && typeof config === "object") {
+          const sanitizedMatch = this._sanitizeMatchConfig(config);
+          if (Object.keys(sanitizedMatch).length > 0) {
+            pipeline.push({ $match: sanitizedMatch });
+          }
+        } else if (stage === "sort" && typeof config === "object") {
+          pipeline.push({ $sort: config });
+        } else if (stage === "project" && typeof config === "object") {
+          pipeline.push({ $project: config });
+        }
+      } catch (error) {
+        console.warn(`[mongokit] Invalid aggregation stage ${stage}:`, error);
+      }
+    }
+    return pipeline.length > 0 ? pipeline : void 0;
+  }
+  // ============================================================
+  // SELECT/PROJECT PARSING
+  // ============================================================
+  /**
+   * Parse select/project fields
+   *
+   * @example
+   * ```typescript
+   * // URL: ?select=name,email,-password
+   * // Returns: { name: 1, email: 1, password: 0 }
+   * ```
+   */
+  _parseSelect(select) {
+    if (!select) return void 0;
+    if (typeof select === "string") {
+      const projection = {};
+      const fields = select.split(",").map((f) => f.trim());
+      for (const field of fields) {
+        if (field.startsWith("-")) {
+          projection[field.substring(1)] = 0;
+        } else {
+          projection[field] = 1;
+        }
+      }
+      return projection;
+    }
+    if (typeof select === "object" && select !== null) {
+      return select;
+    }
+    return void 0;
   }
+  // ============================================================
+  // FILTER PARSING (Enhanced from original)
+  // ============================================================
   /**
-   * Parse standard filter parameter (filter[field]=value)
+   * Parse filter parameters
    */
-  _parseFilters(filters) {
+  _parseFilters(filters, depth = 0) {
+    if (depth > this.options.maxFilterDepth) {
+      console.warn(`[mongokit] Filter depth ${depth} exceeds maximum ${this.options.maxFilterDepth}, truncating`);
+      return {};
+    }
     const parsedFilters = {};
     const regexFields = {};
     for (const [key, value] of Object.entries(filters)) {
@@ -2759,7 +3753,7 @@ var QueryParser = class {
         console.warn(`[mongokit] Blocked dangerous operator: ${key}`);
         continue;
       }
-      if (["page", "limit", "sort", "populate", "search", "select", "lean", "includeDeleted"].includes(key)) {
+      if (["page", "limit", "sort", "populate", "search", "select", "lean", "includeDeleted", "lookup", "aggregate"].includes(key)) {
         continue;
       }
       const operatorMatch = key.match(/^(.+)\[(.+)\]$/);
@@ -2773,7 +3767,7 @@ var QueryParser = class {
         continue;
       }
       if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-        this._handleBracketSyntax(key, value, parsedFilters);
+        this._handleBracketSyntax(key, value, parsedFilters, depth + 1);
       } else {
         parsedFilters[key] = this._convertValue(value);
       }
@@ -2785,6 +3779,9 @@ var QueryParser = class {
    */
   _handleOperatorSyntax(filters, regexFields, operatorMatch, value) {
     const [, field, operator] = operatorMatch;
+    if (value === "" || value === null || value === void 0) {
+      return;
+    }
     if (operator.toLowerCase() === "options" && regexFields[field]) {
       const fieldValue = filters[field];
       if (typeof fieldValue === "object" && fieldValue !== null && "$regex" in fieldValue) {
@@ -2802,18 +3799,18 @@ var QueryParser = class {
     }
     const mongoOperator = this._toMongoOperator(operator);
     if (this.dangerousOperators.includes(mongoOperator)) {
-      console.warn(`[mongokit] Blocked dangerous operator in field[${operator}]: ${mongoOperator}`);
+      console.warn(`[mongokit] Blocked dangerous operator: ${mongoOperator}`);
       return;
     }
     if (mongoOperator === "$eq") {
       filters[field] = value;
     } else if (mongoOperator === "$regex") {
-      filters[field] = { $regex: value };
-      regexFields[field] = true;
-    } else {
-      if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) {
-        filters[field] = {};
+      const safeRegex = this._createSafeRegex(value);
+      if (safeRegex) {
+        filters[field] = { $regex: safeRegex };
+        regexFields[field] = true;
       }
+    } else {
       let processedValue;
       const op = operator.toLowerCase();
       if (["gt", "gte", "lt", "lte", "size"].includes(op)) {
@@ -2824,17 +3821,25 @@ var QueryParser = class {
       } else {
         processedValue = this._convertValue(value);
       }
+      if (typeof filters[field] !== "object" || filters[field] === null || Array.isArray(filters[field])) {
+        filters[field] = {};
+      }
       filters[field][mongoOperator] = processedValue;
     }
   }
   /**
    * Handle bracket syntax with object value
    */
-  _handleBracketSyntax(field, operators, parsedFilters) {
+  _handleBracketSyntax(field, operators, parsedFilters, depth = 0) {
+    if (depth > this.options.maxFilterDepth) {
+      console.warn(`[mongokit] Nested filter depth exceeds maximum, skipping field: ${field}`);
+      return;
+    }
     if (!parsedFilters[field]) {
       parsedFilters[field] = {};
     }
     for (const [operator, value] of Object.entries(operators)) {
+      if (value === "" || value === null || value === void 0) continue;
       if (operator === "between") {
         parsedFilters[field].between = value;
         continue;
@@ -2847,7 +3852,7 @@ var QueryParser = class {
           if (isNaN(processedValue)) continue;
         } else if (operator === "in" || operator === "nin") {
           processedValue = Array.isArray(value) ? value : String(value).split(",").map((v) => v.trim());
-        } else if (operator === "like" || operator === "contains") {
+        } else if (operator === "like" || operator === "contains" || operator === "regex") {
           const safeRegex = this._createSafeRegex(value);
           if (!safeRegex) continue;
           processedValue = safeRegex;
@@ -2857,31 +3862,40 @@ var QueryParser = class {
         parsedFilters[field][mongoOperator] = processedValue;
       }
     }
+    if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) {
+      delete parsedFilters[field];
+    }
+  }
+  // ============================================================
+  // UTILITY METHODS
+  // ============================================================
+  _parseSort(sort) {
+    if (!sort) return void 0;
+    if (typeof sort === "object") return sort;
+    const sortObj = {};
+    const fields = sort.split(",").map((s) => s.trim());
+    for (const field of fields) {
+      if (field.startsWith("-")) {
+        sortObj[field.substring(1)] = -1;
+      } else {
+        sortObj[field] = 1;
+      }
+    }
+    return sortObj;
   }
-  /**
-   * Convert operator to MongoDB format
-   */
   _toMongoOperator(operator) {
     const op = operator.toLowerCase();
     return op.startsWith("$") ? op : "$" + op;
   }
-  /**
-   * Create a safe regex pattern with protection against ReDoS attacks
-   * @param pattern - The pattern string from user input
-   * @param flags - Regex flags (default: 'i' for case-insensitive)
-   * @returns A safe RegExp or null if pattern is invalid/dangerous
-   */
   _createSafeRegex(pattern, flags = "i") {
-    if (pattern === null || pattern === void 0) {
-      return null;
-    }
+    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 (${patternStr.length} > ${this.options.maxRegexLength}), truncating`);
+      console.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 detected, escaping");
+      console.warn("[mongokit] Potentially dangerous regex pattern, escaping");
       return new RegExp(this._escapeRegex(patternStr), flags);
     }
     try {
@@ -2890,34 +3904,45 @@ var QueryParser = class {
       return new RegExp(this._escapeRegex(patternStr), flags);
     }
   }
-  /**
-   * Escape special regex characters for literal matching
-   */
   _escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   }
   /**
-   * Sanitize text search query for MongoDB $text search
-   * @param search - Raw search input from user
-   * @returns Sanitized search string or undefined
+   * Sanitize $match configuration to prevent dangerous operators
+   * Recursively filters out operators like $where, $function, $accumulator
    */
-  _sanitizeSearch(search) {
-    if (search === null || search === void 0 || search === "") {
-      return void 0;
+  _sanitizeMatchConfig(config) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(config)) {
+      if (this.dangerousOperators.includes(key)) {
+        console.warn(`[mongokit] Blocked dangerous operator in aggregation: ${key}`);
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        sanitized[key] = this._sanitizeMatchConfig(value);
+      } else if (Array.isArray(value)) {
+        sanitized[key] = value.map((item) => {
+          if (item && typeof item === "object" && !Array.isArray(item)) {
+            return this._sanitizeMatchConfig(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) return void 0;
     if (searchStr.length > this.options.maxSearchLength) {
-      console.warn(`[mongokit] Search query too long (${searchStr.length} > ${this.options.maxSearchLength}), truncating`);
+      console.warn(`[mongokit] Search query too long, truncating`);
       searchStr = searchStr.substring(0, this.options.maxSearchLength);
     }
     return searchStr;
   }
-  /**
-   * Convert values based on operator type
-   */
   _convertValue(value) {
     if (value === null || value === void 0) return value;
     if (Array.isArray(value)) return value.map((v) => this._convertValue(v));
@@ -2925,14 +3950,11 @@ var QueryParser = class {
     const stringValue = String(value);
     if (stringValue === "true") return true;
     if (stringValue === "false") return false;
-    if (mongoose4.Types.ObjectId.isValid(stringValue) && stringValue.length === 24) {
+    if (mongoose.Types.ObjectId.isValid(stringValue) && stringValue.length === 24) {
       return stringValue;
     }
     return stringValue;
   }
-  /**
-   * Parse $or conditions
-   */
   _parseOr(query) {
     const orArray = [];
     const raw = query?.or || query?.OR || query?.$or;
@@ -2940,14 +3962,11 @@ var QueryParser = class {
     const items = Array.isArray(raw) ? raw : typeof raw === "object" ? Object.values(raw) : [];
     for (const item of items) {
       if (typeof item === "object" && item) {
-        orArray.push(this._parseFilters(item));
+        orArray.push(this._parseFilters(item, 1));
       }
     }
     return orArray.length ? orArray : void 0;
   }
-  /**
-   * Enhance filters with between operator
-   */
   _enhanceWithBetween(filters) {
     const output = { ...filters };
     for (const [key, value] of Object.entries(filters || {})) {
@@ -2964,9 +3983,16 @@ var QueryParser = class {
     }
     return output;
   }
+  // String helpers
+  _pluralize(str) {
+    if (str.endsWith("y")) return str.slice(0, -1) + "ies";
+    if (str.endsWith("s")) return str;
+    return str + "s";
+  }
+  _capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
 };
-var defaultQueryParser = new QueryParser();
-var queryParser_default = defaultQueryParser;
 
 // src/actions/index.ts
 var actions_exports = {};
@@ -3022,4 +4048,4 @@ var index_default = Repository;
  * ```
  */
 
-export { PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, createError, createFieldPreset, createMemoryCache, createRepository, index_default as default, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, queryParser_default as queryParser, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };
+export { AggregationBuilder, LookupBuilder, PaginationEngine, QueryParser, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, createError, createFieldPreset, createMemoryCache, createRepository, index_default as default, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getSystemManagedFields, immutableField, isFieldUpdateAllowed, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin };