@classytic/mongokit 3.0.6 → 3.1.1

package/dist/index.js

@@ -1,902 +1,709 @@
-import mongoose4 from 'mongoose';
+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';
+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 mongoose from 'mongoose';
 
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/utils/error.ts
-function createError(status, message) {
-  const error = new Error(message);
-  error.status = status;
-  return error;
-}
-
-// src/actions/create.ts
-var create_exports = {};
-__export(create_exports, {
-  create: () => create,
-  createDefault: () => createDefault,
-  createMany: () => createMany,
-  upsert: () => upsert
-});
-async function create(Model, data, options = {}) {
-  const document = new Model(data);
-  await document.save({ session: options.session });
-  return document;
-}
-async function createMany(Model, dataArray, options = {}) {
-  return Model.insertMany(dataArray, {
-    session: options.session,
-    ordered: options.ordered !== false
-  });
-}
-async function createDefault(Model, overrides = {}, options = {}) {
-  const defaults = {};
-  Model.schema.eachPath((path, schemaType) => {
-    const schemaOptions = schemaType.options;
-    if (schemaOptions.default !== void 0 && path !== "_id") {
-      defaults[path] = typeof schemaOptions.default === "function" ? schemaOptions.default() : schemaOptions.default;
-    }
-  });
-  return create(Model, { ...defaults, ...overrides }, options);
-}
-async function upsert(Model, query, data, options = {}) {
-  return Model.findOneAndUpdate(
-    query,
-    { $setOnInsert: data },
-    {
-      upsert: true,
-      new: true,
-      runValidators: true,
-      session: options.session,
-      ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-    }
-  );
-}
-
-// src/actions/read.ts
-var read_exports = {};
-__export(read_exports, {
-  count: () => count,
-  exists: () => exists,
-  getAll: () => getAll,
-  getById: () => getById,
-  getByQuery: () => getByQuery,
-  getOrCreate: () => getOrCreate,
-  tryGetByQuery: () => tryGetByQuery
-});
-function parsePopulate(populate) {
-  if (!populate) return [];
-  if (typeof populate === "string") {
-    return populate.split(",").map((p) => p.trim());
-  }
-  if (Array.isArray(populate)) {
-    return populate.map((p) => typeof p === "string" ? p.trim() : p);
-  }
-  return [populate];
-}
-async function getById(Model, id, options = {}) {
-  const query = options.query ? Model.findOne({ _id: id, ...options.query }) : Model.findById(id);
-  if (options.select) query.select(options.select);
-  if (options.populate) query.populate(parsePopulate(options.populate));
-  if (options.lean) query.lean();
-  if (options.session) query.session(options.session);
-  const document = await query.exec();
-  if (!document && options.throwOnNotFound !== false) {
-    throw createError(404, "Document not found");
-  }
-  return document;
-}
-async function getByQuery(Model, query, options = {}) {
-  const mongoQuery = Model.findOne(query);
-  if (options.select) mongoQuery.select(options.select);
-  if (options.populate) mongoQuery.populate(parsePopulate(options.populate));
-  if (options.lean) mongoQuery.lean();
-  if (options.session) mongoQuery.session(options.session);
-  const document = await mongoQuery.exec();
-  if (!document && options.throwOnNotFound !== false) {
-    throw createError(404, "Document not found");
-  }
-  return document;
-}
-async function tryGetByQuery(Model, query, options = {}) {
-  return getByQuery(Model, query, { ...options, throwOnNotFound: false });
-}
-async function getAll(Model, query = {}, options = {}) {
-  let mongoQuery = Model.find(query);
-  if (options.select) mongoQuery = mongoQuery.select(options.select);
-  if (options.populate) mongoQuery = mongoQuery.populate(parsePopulate(options.populate));
-  if (options.sort) mongoQuery = mongoQuery.sort(options.sort);
-  if (options.limit) mongoQuery = mongoQuery.limit(options.limit);
-  if (options.skip) mongoQuery = mongoQuery.skip(options.skip);
-  mongoQuery = mongoQuery.lean(options.lean !== false);
-  if (options.session) mongoQuery = mongoQuery.session(options.session);
-  return mongoQuery.exec();
-}
-async function getOrCreate(Model, query, createData, options = {}) {
-  return Model.findOneAndUpdate(
-    query,
-    { $setOnInsert: createData },
-    {
-      upsert: true,
-      new: true,
-      runValidators: true,
-      session: options.session,
-      ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-    }
-  );
-}
-async function count(Model, query = {}, options = {}) {
-  return Model.countDocuments(query).session(options.session ?? null);
-}
-async function exists(Model, query, options = {}) {
-  return Model.exists(query).session(options.session ?? null);
-}
-
-// src/actions/update.ts
-var update_exports = {};
-__export(update_exports, {
-  increment: () => increment,
-  pullFromArray: () => pullFromArray,
-  pushToArray: () => pushToArray,
-  update: () => update,
-  updateByQuery: () => updateByQuery,
-  updateMany: () => updateMany,
-  updateWithConstraints: () => updateWithConstraints,
-  updateWithValidation: () => updateWithValidation
-});
-function assertUpdatePipelineAllowed(update2, updatePipeline) {
-  if (Array.isArray(update2) && updatePipeline !== true) {
-    throw createError(
-      400,
-      "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates."
-    );
+// src/query/LookupBuilder.ts
+var LookupBuilder = class _LookupBuilder {
+  options = {};
+  constructor(from) {
+    if (from) this.options.from = from;
   }
-}
-function parsePopulate2(populate) {
-  if (!populate) return [];
-  if (typeof populate === "string") {
-    return populate.split(",").map((p) => p.trim());
+  /**
+   * Set the collection to join with
+   */
+  from(collection) {
+    this.options.from = collection;
+    return this;
   }
-  if (Array.isArray(populate)) {
-    return populate.map((p) => typeof p === "string" ? p.trim() : p);
+  /**
+   * Set the local field (source collection)
+   * IMPORTANT: This field should be indexed for optimal performance
+   */
+  localField(field) {
+    this.options.localField = field;
+    return this;
   }
-  return [populate];
-}
-async function update(Model, id, data, options = {}) {
-  assertUpdatePipelineAllowed(data, options.updatePipeline);
-  const document = await Model.findByIdAndUpdate(id, data, {
-    new: true,
-    runValidators: true,
-    session: options.session,
-    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
-  if (!document) {
-    throw createError(404, "Document not found");
-  }
-  return document;
-}
-async function updateWithConstraints(Model, id, data, constraints = {}, options = {}) {
-  assertUpdatePipelineAllowed(data, options.updatePipeline);
-  const query = { _id: id, ...constraints };
-  const document = await Model.findOneAndUpdate(query, data, {
-    new: true,
-    runValidators: true,
-    session: options.session,
-    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
-  return document;
-}
-async function updateWithValidation(Model, id, data, validationOptions = {}, options = {}) {
-  const { buildConstraints, validateUpdate } = validationOptions;
-  assertUpdatePipelineAllowed(data, options.updatePipeline);
-  if (buildConstraints) {
-    const constraints = buildConstraints(data);
-    const document = await updateWithConstraints(Model, id, data, constraints, options);
-    if (document) {
-      return { success: true, data: document };
-    }
+  /**
+   * 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;
   }
-  const existing = await Model.findById(id).select(options.select || "").lean();
-  if (!existing) {
-    return {
-      success: false,
-      error: {
-        code: 404,
-        message: "Document not found"
-      }
-    };
+  /**
+   * Set the output field name
+   * Defaults to the collection name if not specified
+   */
+  as(fieldName) {
+    this.options.as = fieldName;
+    return this;
   }
-  if (validateUpdate) {
-    const validation = validateUpdate(existing, data);
-    if (!validation.valid) {
-      return {
-        success: false,
-        error: {
-          code: 403,
-          message: validation.message || "Update not allowed",
-          violations: validation.violations
-        }
-      };
-    }
+  /**
+   * 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;
   }
-  const updated = await update(Model, id, data, options);
-  return { success: true, data: updated };
-}
-async function updateMany(Model, query, data, options = {}) {
-  assertUpdatePipelineAllowed(data, options.updatePipeline);
-  const result = await Model.updateMany(query, data, {
-    runValidators: true,
-    session: options.session,
-    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-  });
-  return {
-    matchedCount: result.matchedCount,
-    modifiedCount: result.modifiedCount
-  };
-}
-async function updateByQuery(Model, query, data, options = {}) {
-  assertUpdatePipelineAllowed(data, options.updatePipeline);
-  const document = await Model.findOneAndUpdate(query, data, {
-    new: true,
-    runValidators: true,
-    session: options.session,
-    ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-  }).select(options.select || "").populate(parsePopulate2(options.populate)).lean(options.lean ?? false);
-  if (!document && options.throwOnNotFound !== false) {
-    throw createError(404, "Document not found");
-  }
-  return document;
-}
-async function increment(Model, id, field, value = 1, options = {}) {
-  return update(Model, id, { $inc: { [field]: value } }, options);
-}
-async function pushToArray(Model, id, field, value, options = {}) {
-  return update(Model, id, { $push: { [field]: value } }, options);
-}
-async function pullFromArray(Model, id, field, value, options = {}) {
-  return update(Model, id, { $pull: { [field]: value } }, options);
-}
-
-// src/actions/delete.ts
-var delete_exports = {};
-__export(delete_exports, {
-  deleteById: () => deleteById,
-  deleteByQuery: () => deleteByQuery,
-  deleteMany: () => deleteMany,
-  restore: () => restore,
-  softDelete: () => softDelete
-});
-async function deleteById(Model, id, options = {}) {
-  const document = await Model.findByIdAndDelete(id).session(options.session ?? null);
-  if (!document) {
-    throw createError(404, "Document not found");
-  }
-  return { success: true, message: "Deleted successfully" };
-}
-async function deleteMany(Model, query, options = {}) {
-  const result = await Model.deleteMany(query).session(options.session ?? null);
-  return {
-    success: true,
-    count: result.deletedCount,
-    message: "Deleted successfully"
-  };
-}
-async function deleteByQuery(Model, query, options = {}) {
-  const document = await Model.findOneAndDelete(query).session(options.session ?? null);
-  if (!document && options.throwOnNotFound !== false) {
-    throw createError(404, "Document not found");
+  /**
+   * 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;
   }
-  return { success: true, message: "Deleted successfully" };
-}
-async function softDelete(Model, id, options = {}) {
-  const document = await Model.findByIdAndUpdate(
-    id,
-    {
-      deleted: true,
-      deletedAt: /* @__PURE__ */ new Date(),
-      deletedBy: options.userId
-    },
-    { new: true, session: options.session }
-  );
-  if (!document) {
-    throw createError(404, "Document not found");
-  }
-  return { success: true, message: "Soft deleted successfully" };
-}
-async function restore(Model, id, options = {}) {
-  const document = await Model.findByIdAndUpdate(
-    id,
-    {
-      deleted: false,
-      deletedAt: null,
-      deletedBy: null
-    },
-    { new: true, session: options.session }
-  );
-  if (!document) {
-    throw createError(404, "Document not found");
-  }
-  return { success: true, message: "Restored successfully" };
-}
-
-// src/actions/aggregate.ts
-var aggregate_exports = {};
-__export(aggregate_exports, {
-  aggregate: () => aggregate,
-  aggregatePaginate: () => aggregatePaginate,
-  average: () => average,
-  countBy: () => countBy,
-  distinct: () => distinct,
-  facet: () => facet,
-  groupBy: () => groupBy,
-  lookup: () => lookup,
-  minMax: () => minMax,
-  sum: () => sum,
-  unwind: () => unwind
-});
-async function aggregate(Model, pipeline, options = {}) {
-  const aggregation = Model.aggregate(pipeline);
-  if (options.session) {
-    aggregation.session(options.session);
-  }
-  return aggregation.exec();
-}
-async function aggregatePaginate(Model, pipeline, options = {}) {
-  const page = parseInt(String(options.page || 1), 10);
-  const limit = parseInt(String(options.limit || 10), 10);
-  const skip = (page - 1) * limit;
-  const SAFE_LIMIT = 1e3;
-  if (limit > SAFE_LIMIT) {
-    console.warn(
-      `[mongokit] Large aggregation limit (${limit}). $facet results must be <16MB. Consider using Repository.aggregatePaginate() for safer handling of large datasets.`
-    );
-  }
-  const facetPipeline = [
-    ...pipeline,
-    {
-      $facet: {
-        docs: [{ $skip: skip }, { $limit: limit }],
-        total: [{ $count: "count" }]
+  /**
+   * 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
+          }
+        };
       }
-    }
-  ];
-  const aggregation = Model.aggregate(facetPipeline);
-  if (options.session) {
-    aggregation.session(options.session);
-  }
-  const [result] = await aggregation.exec();
-  const docs = result.docs || [];
-  const total = result.total[0]?.count || 0;
-  const pages = Math.ceil(total / limit);
-  return {
-    docs,
-    total,
-    page,
-    limit,
-    pages,
-    hasNext: page < pages,
-    hasPrev: page > 1
-  };
-}
-async function groupBy(Model, field, options = {}) {
-  const pipeline = [
-    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-    { $sort: { count: -1 } }
-  ];
-  if (options.limit) {
-    pipeline.push({ $limit: options.limit });
-  }
-  return aggregate(Model, pipeline, options);
-}
-async function countBy(Model, field, query = {}, options = {}) {
-  const pipeline = [];
-  if (Object.keys(query).length > 0) {
-    pipeline.push({ $match: query });
-  }
-  pipeline.push(
-    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-    { $sort: { count: -1 } }
-  );
-  return aggregate(Model, pipeline, options);
-}
-async function lookup(Model, lookupOptions) {
-  const { from, localField, foreignField, as, pipeline = [], 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 } : {}
-    }
-  });
-  return aggregate(Model, aggPipeline, options);
-}
-async function unwind(Model, field, options = {}) {
-  const pipeline = [
-    {
-      $unwind: {
-        path: `$${field}`,
-        preserveNullAndEmptyArrays: options.preserveEmpty !== false
+    } else {
+      if (!localField || !foreignField) {
+        throw new Error("LookupBuilder: localField and foreignField are required for simple lookup");
       }
+      lookupStage = {
+        $lookup: {
+          from,
+          localField,
+          foreignField,
+          as: outputField
+        }
+      };
     }
-  ];
-  return aggregate(Model, pipeline, { session: options.session });
-}
-async function facet(Model, facets, options = {}) {
-  const pipeline = [{ $facet: facets }];
-  return aggregate(Model, pipeline, options);
-}
-async function distinct(Model, field, query = {}, options = {}) {
-  return Model.distinct(field, query).session(options.session ?? null);
-}
-async function sum(Model, field, query = {}, options = {}) {
-  const pipeline = [];
-  if (Object.keys(query).length > 0) {
-    pipeline.push({ $match: query });
-  }
-  pipeline.push({
-    $group: {
-      _id: null,
-      total: { $sum: `$${field}` }
-    }
-  });
-  const result = await aggregate(Model, pipeline, options);
-  return result[0]?.total || 0;
-}
-async function average(Model, field, query = {}, options = {}) {
-  const pipeline = [];
-  if (Object.keys(query).length > 0) {
-    pipeline.push({ $match: query });
-  }
-  pipeline.push({
-    $group: {
-      _id: null,
-      average: { $avg: `$${field}` }
-    }
-  });
-  const result = await aggregate(Model, pipeline, options);
-  return result[0]?.average || 0;
-}
-async function minMax(Model, field, query = {}, options = {}) {
-  const pipeline = [];
-  if (Object.keys(query).length > 0) {
-    pipeline.push({ $match: query });
-  }
-  pipeline.push({
-    $group: {
-      _id: null,
-      min: { $min: `$${field}` },
-      max: { $max: `$${field}` }
+    stages.push(lookupStage);
+    if (single) {
+      stages.push({
+        $unwind: {
+          path: `$${outputField}`,
+          preserveNullAndEmptyArrays: true
+          // Keep documents even if no match found
+        }
+      });
     }
-  });
-  const result = await aggregate(Model, pipeline, options);
-  return result[0] || { min: null, max: null };
-}
-function encodeCursor(doc, primaryField, sort, version = 1) {
-  const primaryValue = doc[primaryField];
-  const idValue = doc._id;
-  const payload = {
-    v: serializeValue(primaryValue),
-    t: getValueType(primaryValue),
-    id: serializeValue(idValue),
-    idType: getValueType(idValue),
-    sort,
-    ver: version
-  };
-  return Buffer.from(JSON.stringify(payload)).toString("base64");
-}
-function decodeCursor(token) {
-  try {
-    const json = Buffer.from(token, "base64").toString("utf-8");
-    const payload = JSON.parse(json);
-    return {
-      value: rehydrateValue(payload.v, payload.t),
-      id: rehydrateValue(payload.id, payload.idType),
-      sort: payload.sort,
-      version: payload.ver
-    };
-  } catch {
-    throw new Error("Invalid cursor token");
+    return stages;
   }
-}
-function validateCursorSort(cursorSort, currentSort) {
-  const cursorSortStr = JSON.stringify(cursorSort);
-  const currentSortStr = JSON.stringify(currentSort);
-  if (cursorSortStr !== currentSortStr) {
-    throw new Error("Cursor sort does not match current query sort");
+  /**
+   * 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];
   }
-}
-function validateCursorVersion(cursorVersion, expectedVersion) {
-  if (cursorVersion !== expectedVersion) {
-    throw new Error(`Cursor version ${cursorVersion} does not match expected version ${expectedVersion}`);
+  /**
+   * 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();
   }
-}
-function serializeValue(value) {
-  if (value instanceof Date) return value.toISOString();
-  if (value instanceof mongoose4.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 (typeof value === "boolean") return "boolean";
-  if (typeof value === "number") return "number";
-  if (typeof value === "string") return "string";
-  return "unknown";
-}
-function rehydrateValue(serialized, type) {
-  switch (type) {
-    case "date":
-      return new Date(serialized);
-    case "objectid":
-      return new mongoose4.Types.ObjectId(serialized);
-    case "boolean":
-      return Boolean(serialized);
-    case "number":
-      return Number(serialized);
-    default:
-      return serialized;
+  /**
+   * 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/pagination/utils/sort.ts
-function normalizeSort(sort) {
+// src/query/AggregationBuilder.ts
+function normalizeSortSpec(sortSpec) {
   const normalized = {};
-  Object.keys(sort).forEach((key) => {
-    if (key !== "_id") normalized[key] = sort[key];
-  });
-  if (sort._id !== void 0) {
-    normalized._id = sort._id;
+  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;
 }
-function validateKeysetSort(sort) {
-  const keys = Object.keys(sort);
-  if (keys.length === 1 && keys[0] !== "_id") {
-    const field = keys[0];
-    const direction = sort[field];
-    return normalizeSort({ [field]: direction, _id: direction });
-  }
-  if (keys.length === 1 && keys[0] === "_id") {
-    return normalizeSort(sort);
-  }
-  if (keys.length === 2) {
-    if (!keys.includes("_id")) {
-      throw new Error("Keyset pagination requires _id as tie-breaker");
-    }
-    const primaryField = keys.find((k) => k !== "_id");
-    const primaryDirection = sort[primaryField];
-    const idDirection = sort._id;
-    if (primaryDirection !== idDirection) {
-      throw new Error("_id direction must match primary field direction");
-    }
-    return normalizeSort(sort);
+var AggregationBuilder = class _AggregationBuilder {
+  pipeline = [];
+  /**
+   * Get the current pipeline
+   */
+  get() {
+    return [...this.pipeline];
   }
-  throw new Error("Keyset pagination only supports single field + _id");
-}
-function getPrimaryField(sort) {
-  const keys = Object.keys(sort);
-  return keys.find((k) => k !== "_id") || "_id";
-}
-
-// src/pagination/utils/filter.ts
-function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId) {
-  const primaryField = Object.keys(sort).find((k) => k !== "_id") || "_id";
-  const direction = sort[primaryField];
-  const operator = direction === 1 ? "$gt" : "$lt";
-  return {
-    ...baseFilters,
-    $or: [
-      { [primaryField]: { [operator]: cursorValue } },
-      {
-        [primaryField]: cursorValue,
-        _id: { [operator]: cursorId }
-      }
-    ]
-  };
-}
-
-// src/pagination/utils/limits.ts
-function validateLimit(limit, config) {
-  const parsed = Number(limit);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    return config.defaultLimit || 10;
+  /**
+   * Build and return the final pipeline
+   */
+  build() {
+    return this.get();
   }
-  return Math.min(Math.floor(parsed), config.maxLimit || 100);
-}
-function validatePage(page, config) {
-  const parsed = Number(page);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    return 1;
+  /**
+   * Reset the pipeline
+   */
+  reset() {
+    this.pipeline = [];
+    return this;
   }
-  const sanitized = Math.floor(parsed);
-  if (sanitized > (config.maxPage || 1e4)) {
-    throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+  /**
+   * Add a raw pipeline stage
+   */
+  addStage(stage) {
+    this.pipeline.push(stage);
+    return this;
   }
-  return sanitized;
-}
-function shouldWarnDeepPagination(page, threshold) {
-  return page > threshold;
-}
-function calculateSkip(page, limit) {
-  return (page - 1) * limit;
-}
-function calculateTotalPages(total, limit) {
-  return Math.ceil(total / limit);
-}
-
-// src/pagination/PaginationEngine.ts
-var PaginationEngine = class {
-  Model;
-  config;
   /**
-   * Create a new pagination engine
-   *
-   * @param Model - Mongoose model to paginate
-   * @param config - Pagination configuration
+   * Add multiple raw pipeline stages
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  constructor(Model, config = {}) {
-    this.Model = Model;
-    this.config = {
-      defaultLimit: config.defaultLimit || 10,
-      maxLimit: config.maxLimit || 100,
-      maxPage: config.maxPage || 1e4,
-      deepPageThreshold: config.deepPageThreshold || 100,
-      cursorVersion: config.cursorVersion || 1,
-      useEstimatedCount: config.useEstimatedCount || false
-    };
+  addStages(stages) {
+    this.pipeline.push(...stages);
+    return this;
   }
+  // ============================================================
+  // CORE AGGREGATION STAGES
+  // ============================================================
   /**
-   * Offset-based pagination using skip/limit
-   * Best for small datasets and when users need random page access
-   * O(n) performance - slower for deep pages
-   *
-   * @param options - Pagination options
-   * @returns Pagination result with total count
-   *
-   * @example
-   * const result = await engine.paginate({
-   *   filters: { status: 'active' },
-   *   sort: { createdAt: -1 },
-   *   page: 1,
-   *   limit: 20
-   * });
-   * console.log(result.docs, result.total, result.hasNext);
+   * $match - Filter documents
+   * IMPORTANT: Place $match as early as possible for performance
    */
-  async paginate(options = {}) {
-    const {
-      filters = {},
-      sort = { _id: -1 },
-      page = 1,
-      limit = this.config.defaultLimit,
-      select,
-      populate = [],
-      lean = true,
-      session
-    } = options;
-    const sanitizedPage = validatePage(page, this.config);
-    const sanitizedLimit = validateLimit(limit, this.config);
-    const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-    let query = this.Model.find(filters);
-    if (select) query = query.select(select);
-    if (populate && (Array.isArray(populate) ? populate.length : populate)) {
-      query = query.populate(populate);
-    }
-    query = query.sort(sort).skip(skip).limit(sanitizedLimit).lean(lean);
-    if (session) query = query.session(session);
-    const hasFilters = Object.keys(filters).length > 0;
-    const useEstimated = this.config.useEstimatedCount && !hasFilters;
-    const [docs, total] = await Promise.all([
-      query.exec(),
-      useEstimated ? this.Model.estimatedDocumentCount() : this.Model.countDocuments(filters).session(session ?? null)
-    ]);
-    const totalPages = calculateTotalPages(total, sanitizedLimit);
-    const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : void 0;
-    return {
-      method: "offset",
-      docs,
-      page: sanitizedPage,
-      limit: sanitizedLimit,
-      total,
-      pages: totalPages,
-      hasNext: sanitizedPage < totalPages,
-      hasPrev: sanitizedPage > 1,
-      ...warning && { warning }
-    };
+  match(query) {
+    this.pipeline.push({ $match: query });
+    return this;
   }
   /**
-   * Keyset (cursor-based) pagination for high-performance streaming
-   * Best for large datasets, infinite scroll, real-time feeds
-   * O(1) performance - consistent speed regardless of position
-   *
-   * @param options - Pagination options (sort is required)
-   * @returns Pagination result with next cursor
-   *
-   * @example
-   * // First page
-   * const page1 = await engine.stream({
-   *   sort: { createdAt: -1 },
-   *   limit: 20
-   * });
-   *
-   * // Next page using cursor
-   * const page2 = await engine.stream({
-   *   sort: { createdAt: -1 },
-   *   after: page1.next,
-   *   limit: 20
-   * });
+   * $project - Include/exclude fields or compute new fields
    */
-  async stream(options) {
-    const {
-      filters = {},
-      sort,
-      after,
-      limit = this.config.defaultLimit,
-      select,
-      populate = [],
-      lean = true,
-      session
-    } = options;
-    if (!sort) {
-      throw createError(400, "sort is required for keyset pagination");
-    }
-    const sanitizedLimit = validateLimit(limit, this.config);
-    const normalizedSort = validateKeysetSort(sort);
-    let query = { ...filters };
-    if (after) {
-      const cursor = decodeCursor(after);
-      validateCursorVersion(cursor.version, this.config.cursorVersion);
-      validateCursorSort(cursor.sort, normalizedSort);
-      query = buildKeysetFilter(query, normalizedSort, cursor.value, cursor.id);
-    }
-    let mongoQuery = this.Model.find(query);
-    if (select) mongoQuery = mongoQuery.select(select);
-    if (populate && (Array.isArray(populate) ? populate.length : populate)) {
-      mongoQuery = mongoQuery.populate(populate);
-    }
-    mongoQuery = mongoQuery.sort(normalizedSort).limit(sanitizedLimit + 1).lean(lean);
-    if (session) mongoQuery = mongoQuery.session(session);
-    const docs = await mongoQuery.exec();
-    const hasMore = docs.length > sanitizedLimit;
-    if (hasMore) docs.pop();
-    const primaryField = getPrimaryField(normalizedSort);
-    const nextCursor = hasMore && docs.length > 0 ? encodeCursor(docs[docs.length - 1], primaryField, normalizedSort, this.config.cursorVersion) : null;
-    return {
-      method: "keyset",
-      docs,
-      limit: sanitizedLimit,
-      hasMore,
-      next: nextCursor
-    };
+  project(projection) {
+    this.pipeline.push({ $project: projection });
+    return this;
   }
   /**
-   * Aggregate pipeline with pagination
-   * Best for complex queries requiring aggregation stages
-   * Uses $facet to combine results and count in single query
-   *
-   * @param options - Aggregation options
-   * @returns Pagination result with total count
+   * $group - Group documents and compute aggregations
    *
    * @example
-   * const result = await engine.aggregatePaginate({
-   *   pipeline: [
-   *     { $match: { status: 'active' } },
-   *     { $group: { _id: '$category', count: { $sum: 1 } } },
-   *     { $sort: { count: -1 } }
-   *   ],
-   *   page: 1,
-   *   limit: 20
-   * });
+   * ```typescript
+   * .group({
+   *   _id: '$department',
+   *   count: { $sum: 1 },
+   *   avgSalary: { $avg: '$salary' }
+   * })
+   * ```
    */
-  async aggregatePaginate(options = {}) {
-    const {
-      pipeline = [],
-      page = 1,
-      limit = this.config.defaultLimit,
-      session
-    } = options;
-    const sanitizedPage = validatePage(page, this.config);
-    const sanitizedLimit = validateLimit(limit, this.config);
-    const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-    const facetPipeline = [
-      ...pipeline,
-      {
-        $facet: {
-          docs: [{ $skip: skip }, { $limit: sanitizedLimit }],
-          total: [{ $count: "count" }]
-        }
-      }
-    ];
-    const aggregation = this.Model.aggregate(facetPipeline);
-    if (session) aggregation.session(session);
-    const [result] = await aggregation.exec();
-    const docs = result.docs;
-    const total = result.total[0]?.count || 0;
-    const totalPages = calculateTotalPages(total, sanitizedLimit);
-    const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination in aggregate (page ${sanitizedPage}). Uses $skip internally.` : void 0;
-    return {
-      method: "aggregate",
-      docs,
-      page: sanitizedPage,
-      limit: sanitizedLimit,
-      total,
-      pages: totalPages,
-      hasNext: sanitizedPage < totalPages,
-      hasPrev: sanitizedPage > 1,
-      ...warning && { warning }
-    };
-  }
-};
-
-// src/Repository.ts
-var Repository = class {
-  Model;
-  model;
-  _hooks;
-  _pagination;
-  _hookMode;
-  constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
-    this.Model = Model;
-    this.model = Model.modelName;
-    this._hooks = /* @__PURE__ */ new Map();
-    this._pagination = new PaginationEngine(Model, paginationConfig);
-    this._hookMode = options.hooks ?? "async";
-    plugins.forEach((plugin) => this.use(plugin));
+  group(groupSpec) {
+    this.pipeline.push({ $group: groupSpec });
+    return this;
   }
   /**
-   * Register a plugin
+   * $sort - Sort documents
    */
-  use(plugin) {
-    if (typeof plugin === "function") {
-      plugin(this);
-    } else if (plugin && typeof plugin.apply === "function") {
-      plugin.apply(this);
+  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;
   }
   /**
-   * Register event listener
+   * $limit - Limit number of documents
    */
-  on(event, listener) {
-    if (!this._hooks.has(event)) {
-      this._hooks.set(event, []);
-    }
-    this._hooks.get(event).push(listener);
+  limit(count2) {
+    this.pipeline.push({ $limit: count2 });
     return this;
   }
   /**
-   * Emit event (sync - for backwards compatibility)
+   * $skip - Skip documents
    */
-  emit(event, data) {
-    const listeners = this._hooks.get(event) || [];
-    for (const listener of listeners) {
-      try {
-        const result = listener(data);
-        if (result && typeof result.then === "function") {
-          void result.catch((error) => {
-            if (event === "error:hook") return;
-            const err = error instanceof Error ? error : new Error(String(error));
-            this.emit("error:hook", { event, error: err });
-          });
-        }
-      } catch (error) {
-        if (event === "error:hook") continue;
-        const err = error instanceof Error ? error : new Error(String(error));
-        this.emit("error:hook", { event, error: err });
-      }
-    }
+  skip(count2) {
+    this.pipeline.push({ $skip: count2 });
+    return this;
   }
   /**
-   * Emit event and await all async handlers
+   * $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;
+  model;
+  _hooks;
+  _pagination;
+  _hookMode;
+  constructor(Model, plugins = [], paginationConfig = {}, options = {}) {
+    this.Model = Model;
+    this.model = Model.modelName;
+    this._hooks = /* @__PURE__ */ new Map();
+    this._pagination = new PaginationEngine(Model, paginationConfig);
+    this._hookMode = options.hooks ?? "async";
+    plugins.forEach((plugin) => this.use(plugin));
+  }
+  /**
+   * Register a plugin
+   */
+  use(plugin) {
+    if (typeof plugin === "function") {
+      plugin(this);
+    } else if (plugin && typeof plugin.apply === "function") {
+      plugin.apply(this);
+    }
+    return this;
+  }
+  /**
+   * Register event listener
+   */
+  on(event, listener) {
+    if (!this._hooks.has(event)) {
+      this._hooks.set(event, []);
+    }
+    this._hooks.get(event).push(listener);
+    return this;
+  }
+  /**
+   * Emit event (sync - for backwards compatibility)
+   */
+  emit(event, data) {
+    const listeners = this._hooks.get(event) || [];
+    for (const listener of listeners) {
+      try {
+        const result = listener(data);
+        if (result && typeof result.then === "function") {
+          void result.catch((error) => {
+            if (event === "error:hook") return;
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.emit("error:hook", { event, error: err });
+          });
+        }
+      } catch (error) {
+        if (event === "error:hook") continue;
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.emit("error:hook", { event, error: err });
+      }
+    }
+  }
+  /**
+   * Emit event and await all async handlers
    */
   async emitAsync(event, data) {
     const listeners = this._hooks.get(event) || [];
@@ -965,7 +772,8 @@ var Repository = class {
     if (context._cacheHit) {
       return context._cachedResult;
     }
-    const result = await getByQuery(this.Model, query, context);
+    const finalQuery = context.query || query;
+    const result = await getByQuery(this.Model, finalQuery, context);
     await this._emitHook("after:getByQuery", { context, result });
     return result;
   }
@@ -999,8 +807,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";
@@ -1106,1573 +914,246 @@ var Repository = class {
     return distinct(this.Model, field, query, options);
   }
   /**
-   * Execute callback within a transaction
+   * 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 withTransaction(callback, options = {}) {
-    const session = await mongoose4.startSession();
-    let started = false;
+  async lookupPopulate(options) {
+    const context = await this._buildContext("lookupPopulate", options);
     try {
-      session.startTransaction();
-      started = true;
-      const result = await callback(session);
-      await session.commitTransaction();
-      return result;
-    } catch (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);
+      const builder = new AggregationBuilder();
+      if (options.filters && Object.keys(options.filters).length > 0) {
+        builder.match(options.filters);
       }
-      if (started && session.inTransaction()) {
-        await session.abortTransaction();
+      builder.multiLookup(options.lookups);
+      if (options.sort) {
+        builder.sort(this._parseSort(options.sort));
       }
-      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
-   */
-  async _executeQuery(buildQuery) {
-    const operation = buildQuery.name || "custom";
-    const context = await this._buildContext(operation, {});
-    try {
-      const result = await buildQuery(this.Model);
-      await this._emitHook(`after:${operation}`, { context, result });
-      return result;
-    } catch (error) {
-      await this._emitErrorHook(`error:${operation}`, { context, error });
-      throw this._handleError(error);
-    }
-  }
-  /**
-   * Build operation context and run before hooks
-   */
-  async _buildContext(operation, options) {
-    const context = { operation, model: this.model, ...options };
-    const event = `before:${operation}`;
-    const hooks = this._hooks.get(event) || [];
-    for (const hook of hooks) {
-      await hook(context);
-    }
-    return context;
-  }
-  /**
-   * Parse sort string or object
-   */
-  _parseSort(sort) {
-    if (!sort) return { createdAt: -1 };
-    if (typeof sort === "object") return sort;
-    const sortOrder = sort.startsWith("-") ? -1 : 1;
-    const sortField = sort.startsWith("-") ? sort.substring(1) : sort;
-    return { [sortField]: sortOrder };
-  }
-  /**
-   * Parse populate specification
-   */
-  _parsePopulate(populate) {
-    if (!populate) return [];
-    if (typeof populate === "string") return populate.split(",").map((p) => p.trim());
-    if (Array.isArray(populate)) return populate.map((p) => typeof p === "string" ? p.trim() : p);
-    return [populate];
-  }
-  /**
-   * Handle errors with proper HTTP status codes
-   */
-  _handleError(error) {
-    if (error instanceof mongoose4.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) {
-      return createError(400, `Invalid ${error.path}: ${error.value}`);
-    }
-    if (error.status && error.message) return error;
-    return createError(500, error.message || "Internal Server Error");
-  }
-};
-
-// src/utils/field-selection.ts
-function getFieldsForUser(user, preset) {
-  if (!preset) {
-    throw new Error("Field preset is required");
-  }
-  const fields = [...preset.public || []];
-  if (user) {
-    fields.push(...preset.authenticated || []);
-    const roles = Array.isArray(user.roles) ? user.roles : user.roles ? [user.roles] : [];
-    if (roles.includes("admin") || roles.includes("superadmin")) {
-      fields.push(...preset.admin || []);
-    }
-  }
-  return [...new Set(fields)];
-}
-function getMongooseProjection(user, preset) {
-  const fields = getFieldsForUser(user, preset);
-  return fields.join(" ");
-}
-function filterObject(obj, allowedFields) {
-  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
-    return obj;
-  }
-  const filtered = {};
-  for (const field of allowedFields) {
-    if (field in obj) {
-      filtered[field] = obj[field];
-    }
-  }
-  return filtered;
-}
-function filterResponseData(data, preset, user = null) {
-  const allowedFields = getFieldsForUser(user, preset);
-  if (Array.isArray(data)) {
-    return data.map((item) => filterObject(item, allowedFields));
-  }
-  return filterObject(data, allowedFields);
-}
-function createFieldPreset(config) {
-  return {
-    public: config.public || [],
-    authenticated: config.authenticated || [],
-    admin: config.admin || []
-  };
-}
-
-// src/plugins/field-filter.plugin.ts
-function fieldFilterPlugin(fieldPreset) {
-  return {
-    name: "fieldFilter",
-    apply(repo) {
-      const applyFieldFiltering = (context) => {
-        if (!fieldPreset) return;
-        const user = context.context?.user || context.user;
-        const fields = getFieldsForUser(user, fieldPreset);
-        const presetSelect = fields.join(" ");
-        if (context.select) {
-          context.select = `${presetSelect} ${context.select}`;
-        } else {
-          context.select = presetSelect;
-        }
-      };
-      repo.on("before:getAll", applyFieldFiltering);
-      repo.on("before:getById", applyFieldFiltering);
-      repo.on("before:getByQuery", applyFieldFiltering);
-    }
-  };
-}
-
-// src/plugins/timestamp.plugin.ts
-function timestampPlugin() {
-  return {
-    name: "timestamp",
-    apply(repo) {
-      repo.on("before:create", (context) => {
-        if (!context.data) return;
-        const now = /* @__PURE__ */ new Date();
-        if (!context.data.createdAt) context.data.createdAt = now;
-        if (!context.data.updatedAt) context.data.updatedAt = now;
-      });
-      repo.on("before:update", (context) => {
-        if (!context.data) return;
-        context.data.updatedAt = /* @__PURE__ */ new Date();
-      });
-    }
-  };
-}
-
-// src/plugins/audit-log.plugin.ts
-function auditLogPlugin(logger) {
-  return {
-    name: "auditLog",
-    apply(repo) {
-      repo.on("after:create", ({ context, result }) => {
-        logger?.info?.("Document created", {
-          model: context.model || repo.model,
-          id: result?._id,
-          userId: context.user?._id || context.user?.id,
-          organizationId: context.organizationId
-        });
-      });
-      repo.on("after:update", ({ context, result }) => {
-        logger?.info?.("Document updated", {
-          model: context.model || repo.model,
-          id: context.id || result?._id,
-          userId: context.user?._id || context.user?.id,
-          organizationId: context.organizationId
-        });
-      });
-      repo.on("after:delete", ({ context }) => {
-        logger?.info?.("Document deleted", {
-          model: context.model || repo.model,
-          id: context.id,
-          userId: context.user?._id || context.user?.id,
-          organizationId: context.organizationId
-        });
-      });
-      repo.on("error:create", ({ context, error }) => {
-        logger?.error?.("Create failed", {
-          model: context.model || repo.model,
-          error: error.message,
-          userId: context.user?._id || context.user?.id
-        });
-      });
-      repo.on("error:update", ({ context, error }) => {
-        logger?.error?.("Update failed", {
-          model: context.model || repo.model,
-          id: context.id,
-          error: error.message,
-          userId: context.user?._id || context.user?.id
-        });
-      });
-      repo.on("error:delete", ({ context, error }) => {
-        logger?.error?.("Delete failed", {
-          model: context.model || repo.model,
-          id: context.id,
-          error: error.message,
-          userId: context.user?._id || context.user?.id
-        });
-      });
-    }
-  };
-}
-
-// src/plugins/soft-delete.plugin.ts
-function buildDeletedFilter(deletedField, filterMode, includeDeleted) {
-  if (includeDeleted) {
-    return {};
-  }
-  if (filterMode === "exists") {
-    return { [deletedField]: { $exists: false } };
-  }
-  return { [deletedField]: null };
-}
-function buildGetDeletedFilter(deletedField, filterMode) {
-  if (filterMode === "exists") {
-    return { [deletedField]: { $exists: true, $ne: null } };
-  }
-  return { [deletedField]: { $ne: null } };
-}
-function softDeletePlugin(options = {}) {
-  const deletedField = options.deletedField || "deletedAt";
-  const deletedByField = options.deletedByField || "deletedBy";
-  const filterMode = options.filterMode || "null";
-  const addRestoreMethod = options.addRestoreMethod !== false;
-  const addGetDeletedMethod = options.addGetDeletedMethod !== false;
-  const ttlDays = options.ttlDays;
-  return {
-    name: "softDelete",
-    apply(repo) {
-      if (ttlDays !== void 0 && ttlDays > 0) {
-        const ttlSeconds = ttlDays * 24 * 60 * 60;
-        repo.Model.collection.createIndex(
-          { [deletedField]: 1 },
-          {
-            expireAfterSeconds: ttlSeconds,
-            partialFilterExpression: { [deletedField]: { $type: "date" } }
-          }
-        ).catch((err) => {
-          if (!err.message.includes("already exists")) {
-            console.warn(`[softDeletePlugin] Failed to create TTL index: ${err.message}`);
-          }
-        });
-      }
-      repo.on("before:delete", async (context) => {
-        if (options.soft !== false) {
-          const updateData = {
-            [deletedField]: /* @__PURE__ */ new Date()
-          };
-          if (context.user) {
-            updateData[deletedByField] = context.user._id || context.user.id;
-          }
-          await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
-          context.softDeleted = true;
-        }
-      });
-      repo.on("before:getAll", (context) => {
-        if (options.soft !== false) {
-          const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-          if (Object.keys(deleteFilter).length > 0) {
-            const existingFilters = context.filters || {};
-            context.filters = {
-              ...existingFilters,
-              ...deleteFilter
-            };
-          }
-        }
-      });
-      repo.on("before:getById", (context) => {
-        if (options.soft !== false) {
-          const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-          if (Object.keys(deleteFilter).length > 0) {
-            context.query = {
-              ...context.query || {},
-              ...deleteFilter
-            };
-          }
-        }
-      });
-      repo.on("before:getByQuery", (context) => {
-        if (options.soft !== false) {
-          const deleteFilter = buildDeletedFilter(deletedField, filterMode, !!context.includeDeleted);
-          if (Object.keys(deleteFilter).length > 0) {
-            context.query = {
-              ...context.query || {},
-              ...deleteFilter
-            };
-          }
-        }
-      });
-      if (addRestoreMethod) {
-        const restoreMethod = async function(id, restoreOptions = {}) {
-          const updateData = {
-            [deletedField]: null,
-            [deletedByField]: null
-          };
-          const result = await this.Model.findByIdAndUpdate(id, { $set: updateData }, {
-            new: true,
-            session: restoreOptions.session
-          });
-          if (!result) {
-            const error = new Error(`Document with id '${id}' not found`);
-            error.status = 404;
-            throw error;
-          }
-          await this.emitAsync("after:restore", { id, result });
-          return result;
-        };
-        if (typeof repo.registerMethod === "function") {
-          repo.registerMethod("restore", restoreMethod);
-        } else {
-          repo.restore = restoreMethod.bind(repo);
-        }
-      }
-      if (addGetDeletedMethod) {
-        const getDeletedMethod = async function(params = {}, getDeletedOptions = {}) {
-          const deletedFilter = buildGetDeletedFilter(deletedField, filterMode);
-          const combinedFilters = {
-            ...params.filters || {},
-            ...deletedFilter
-          };
-          const page = params.page || 1;
-          const limit = params.limit || 20;
-          const skip = (page - 1) * limit;
-          let sortSpec = { [deletedField]: -1 };
-          if (params.sort) {
-            if (typeof params.sort === "string") {
-              const sortOrder = params.sort.startsWith("-") ? -1 : 1;
-              const sortField = params.sort.startsWith("-") ? params.sort.substring(1) : params.sort;
-              sortSpec = { [sortField]: sortOrder };
-            } else {
-              sortSpec = params.sort;
-            }
-          }
-          let query = this.Model.find(combinedFilters).sort(sortSpec).skip(skip).limit(limit);
-          if (getDeletedOptions.session) {
-            query = query.session(getDeletedOptions.session);
-          }
-          if (getDeletedOptions.select) {
-            const selectValue = Array.isArray(getDeletedOptions.select) ? getDeletedOptions.select.join(" ") : getDeletedOptions.select;
-            query = query.select(selectValue);
-          }
-          if (getDeletedOptions.populate) {
-            const populateSpec = getDeletedOptions.populate;
-            if (typeof populateSpec === "string") {
-              query = query.populate(populateSpec.split(",").map((p) => p.trim()));
-            } else if (Array.isArray(populateSpec)) {
-              query = query.populate(populateSpec);
-            } else {
-              query = query.populate(populateSpec);
-            }
-          }
-          if (getDeletedOptions.lean !== false) {
-            query = query.lean();
-          }
-          const [docs, total] = await Promise.all([
-            query.exec(),
-            this.Model.countDocuments(combinedFilters)
-          ]);
-          const pages = Math.ceil(total / limit);
-          return {
-            method: "offset",
-            docs,
-            page,
-            limit,
-            total,
-            pages,
-            hasNext: page < pages,
-            hasPrev: page > 1
-          };
-        };
-        if (typeof repo.registerMethod === "function") {
-          repo.registerMethod("getDeleted", getDeletedMethod);
-        } else {
-          repo.getDeleted = getDeletedMethod.bind(repo);
-        }
-      }
-    }
-  };
-}
-
-// src/plugins/method-registry.plugin.ts
-function methodRegistryPlugin() {
-  return {
-    name: "method-registry",
-    apply(repo) {
-      const registeredMethods = [];
-      repo.registerMethod = function(name, fn) {
-        if (repo[name]) {
-          throw new Error(
-            `Cannot register method '${name}': Method already exists on repository. Choose a different name or use a plugin that doesn't conflict.`
-          );
-        }
-        if (!name || typeof name !== "string") {
-          throw new Error("Method name must be a non-empty string");
-        }
-        if (typeof fn !== "function") {
-          throw new Error(`Method '${name}' must be a function`);
-        }
-        repo[name] = fn.bind(repo);
-        registeredMethods.push(name);
-        repo.emit("method:registered", { name, fn });
-      };
-      repo.hasMethod = function(name) {
-        return typeof repo[name] === "function";
-      };
-      repo.getRegisteredMethods = function() {
-        return [...registeredMethods];
-      };
-    }
-  };
-}
-
-// src/plugins/validation-chain.plugin.ts
-function validationChainPlugin(validators = [], options = {}) {
-  const { stopOnFirstError = true } = options;
-  validators.forEach((v, idx) => {
-    if (!v.name || typeof v.name !== "string") {
-      throw new Error(`Validator at index ${idx} missing 'name' (string)`);
-    }
-    if (typeof v.validate !== "function") {
-      throw new Error(`Validator '${v.name}' missing 'validate' function`);
-    }
-  });
-  const validatorsByOperation = {
-    create: [],
-    update: [],
-    delete: [],
-    createMany: []
-  };
-  const allOperationsValidators = [];
-  validators.forEach((v) => {
-    if (!v.operations || v.operations.length === 0) {
-      allOperationsValidators.push(v);
-    } else {
-      v.operations.forEach((op) => {
-        if (validatorsByOperation[op]) {
-          validatorsByOperation[op].push(v);
-        }
-      });
-    }
-  });
-  return {
-    name: "validation-chain",
-    apply(repo) {
-      const getValidatorsForOperation = (operation) => {
-        const specific = validatorsByOperation[operation] || [];
-        return [...allOperationsValidators, ...specific];
-      };
-      const runValidators = async (operation, context) => {
-        const operationValidators = getValidatorsForOperation(operation);
-        const errors = [];
-        for (const validator of operationValidators) {
-          try {
-            await validator.validate(context, repo);
-          } catch (error) {
-            if (stopOnFirstError) {
-              throw error;
-            }
-            errors.push({
-              validator: validator.name,
-              error: error.message || String(error)
-            });
-          }
-        }
-        if (errors.length > 0) {
-          const err = createError(
-            400,
-            `Validation failed: ${errors.map((e) => `[${e.validator}] ${e.error}`).join("; ")}`
-          );
-          err.validationErrors = errors;
-          throw err;
-        }
-      };
-      repo.on("before:create", async (context) => runValidators("create", context));
-      repo.on("before:createMany", async (context) => runValidators("createMany", context));
-      repo.on("before:update", async (context) => runValidators("update", context));
-      repo.on("before:delete", async (context) => runValidators("delete", context));
-    }
-  };
-}
-function blockIf(name, operations, condition, errorMessage) {
-  return {
-    name,
-    operations,
-    validate: (context) => {
-      if (condition(context)) {
-        throw createError(403, errorMessage);
-      }
-    }
-  };
-}
-function requireField(field, operations = ["create"]) {
-  return {
-    name: `require-${field}`,
-    operations,
-    validate: (context) => {
-      if (!context.data || context.data[field] === void 0 || context.data[field] === null) {
-        throw createError(400, `Field '${field}' is required`);
-      }
-    }
-  };
-}
-function autoInject(field, getter, operations = ["create"]) {
-  return {
-    name: `auto-inject-${field}`,
-    operations,
-    validate: (context) => {
-      if (context.data && !(field in context.data)) {
-        const value = getter(context);
-        if (value !== null && value !== void 0) {
-          context.data[field] = value;
-        }
-      }
-    }
-  };
-}
-function immutableField(field) {
-  return {
-    name: `immutable-${field}`,
-    operations: ["update"],
-    validate: (context) => {
-      if (context.data && field in context.data) {
-        throw createError(400, `Field '${field}' cannot be modified`);
-      }
-    }
-  };
-}
-function uniqueField(field, errorMessage) {
-  return {
-    name: `unique-${field}`,
-    operations: ["create", "update"],
-    validate: async (context, repo) => {
-      if (!context.data || !context.data[field] || !repo) return;
-      const query = { [field]: context.data[field] };
-      const getByQuery2 = repo.getByQuery;
-      if (typeof getByQuery2 !== "function") return;
-      const existing = await getByQuery2.call(repo, query, {
-        select: "_id",
-        lean: true,
-        throwOnNotFound: false
-      });
-      if (existing && String(existing._id) !== String(context.id)) {
-        throw createError(409, errorMessage || `${field} already exists`);
-      }
-    }
-  };
-}
-
-// src/plugins/mongo-operations.plugin.ts
-function mongoOperationsPlugin() {
-  return {
-    name: "mongo-operations",
-    apply(repo) {
-      if (!repo.registerMethod) {
-        throw new Error(
-          "mongoOperationsPlugin requires methodRegistryPlugin. Add methodRegistryPlugin() before mongoOperationsPlugin() in plugins array."
+      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.`
         );
       }
-      repo.registerMethod("upsert", async function(query, data, options = {}) {
-        return upsert(this.Model, query, data, options);
-      });
-      const validateAndUpdateNumeric = async function(id, field, value, operator, operationName, options) {
-        if (typeof value !== "number") {
-          throw createError(400, `${operationName} value must be a number`);
-        }
-        return this.update(id, { [operator]: { [field]: value } }, options);
-      };
-      repo.registerMethod("increment", async function(id, field, value = 1, options = {}) {
-        return validateAndUpdateNumeric.call(this, id, field, value, "$inc", "Increment", options);
-      });
-      repo.registerMethod("decrement", async function(id, field, value = 1, options = {}) {
-        return validateAndUpdateNumeric.call(this, id, field, -value, "$inc", "Decrement", options);
-      });
-      const applyOperator = function(id, field, value, operator, options) {
-        return this.update(id, { [operator]: { [field]: value } }, options);
-      };
-      repo.registerMethod("pushToArray", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$push", options);
-      });
-      repo.registerMethod("pullFromArray", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$pull", options);
-      });
-      repo.registerMethod("addToSet", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$addToSet", options);
-      });
-      repo.registerMethod("setField", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$set", options);
-      });
-      repo.registerMethod("unsetField", async function(id, fields, options = {}) {
-        const fieldArray = Array.isArray(fields) ? fields : [fields];
-        const unsetObj = fieldArray.reduce((acc, field) => {
-          acc[field] = "";
-          return acc;
-        }, {});
-        return this.update(id, { $unset: unsetObj }, options);
-      });
-      repo.registerMethod("renameField", async function(id, oldName, newName, options = {}) {
-        return this.update(id, { $rename: { [oldName]: newName } }, options);
-      });
-      repo.registerMethod("multiplyField", async function(id, field, multiplier, options = {}) {
-        return validateAndUpdateNumeric.call(this, id, field, multiplier, "$mul", "Multiplier", options);
-      });
-      repo.registerMethod("setMin", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$min", options);
-      });
-      repo.registerMethod("setMax", async function(id, field, value, options = {}) {
-        return applyOperator.call(this, id, field, value, "$max", options);
-      });
-    }
-  };
-}
-
-// src/plugins/batch-operations.plugin.ts
-function batchOperationsPlugin() {
-  return {
-    name: "batch-operations",
-    apply(repo) {
-      if (!repo.registerMethod) {
-        throw new Error("batchOperationsPlugin requires methodRegistryPlugin");
-      }
-      repo.registerMethod("updateMany", async function(query, data, options = {}) {
-        const _buildContext = this._buildContext;
-        const context = await _buildContext.call(this, "updateMany", { query, data, options });
-        try {
-          this.emit("before:updateMany", context);
-          if (Array.isArray(data) && options.updatePipeline !== true) {
-            throw createError(
-              400,
-              "Update pipelines (array updates) are disabled by default; pass `{ updatePipeline: true }` to explicitly allow pipeline-style updates."
-            );
-          }
-          const result = await this.Model.updateMany(query, data, {
-            runValidators: true,
-            session: options.session,
-            ...options.updatePipeline !== void 0 ? { updatePipeline: options.updatePipeline } : {}
-          }).exec();
-          this.emit("after:updateMany", { context, result });
-          return result;
-        } catch (error) {
-          this.emit("error:updateMany", { context, error });
-          const _handleError = this._handleError;
-          throw _handleError.call(this, error);
-        }
-      });
-      repo.registerMethod("deleteMany", async function(query, options = {}) {
-        const _buildContext = this._buildContext;
-        const context = await _buildContext.call(this, "deleteMany", { query, options });
-        try {
-          this.emit("before:deleteMany", context);
-          const result = await this.Model.deleteMany(query, {
-            session: options.session
-          }).exec();
-          this.emit("after:deleteMany", { context, result });
-          return result;
-        } catch (error) {
-          this.emit("error:deleteMany", { context, error });
-          const _handleError = this._handleError;
-          throw _handleError.call(this, error);
-        }
-      });
-    }
-  };
-}
-
-// src/plugins/aggregate-helpers.plugin.ts
-function aggregateHelpersPlugin() {
-  return {
-    name: "aggregate-helpers",
-    apply(repo) {
-      if (!repo.registerMethod) {
-        throw new Error("aggregateHelpersPlugin requires methodRegistryPlugin");
-      }
-      repo.registerMethod("groupBy", async function(field, options = {}) {
-        const pipeline = [
-          { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-          { $sort: { count: -1 } }
-        ];
-        if (options.limit) {
-          pipeline.push({ $limit: options.limit });
-        }
-        const aggregate2 = this.aggregate;
-        return aggregate2.call(this, pipeline, options);
-      });
-      const aggregateOperation = async function(field, operator, resultKey, query = {}, options = {}) {
-        const pipeline = [
-          { $match: query },
-          { $group: { _id: null, [resultKey]: { [operator]: `$${field}` } } }
-        ];
-        const aggregate2 = this.aggregate;
-        const result = await aggregate2.call(this, pipeline, options);
-        return result[0]?.[resultKey] || 0;
-      };
-      repo.registerMethod("sum", async function(field, query = {}, options = {}) {
-        return aggregateOperation.call(this, field, "$sum", "total", query, options);
-      });
-      repo.registerMethod("average", async function(field, query = {}, options = {}) {
-        return aggregateOperation.call(this, field, "$avg", "avg", query, options);
-      });
-      repo.registerMethod("min", async function(field, query = {}, options = {}) {
-        return aggregateOperation.call(this, field, "$min", "min", query, options);
-      });
-      repo.registerMethod("max", async function(field, query = {}, options = {}) {
-        return aggregateOperation.call(this, field, "$max", "max", query, options);
-      });
-    }
-  };
-}
-
-// src/plugins/subdocument.plugin.ts
-function subdocumentPlugin() {
-  return {
-    name: "subdocument",
-    apply(repo) {
-      if (!repo.registerMethod) {
-        throw new Error("subdocumentPlugin requires methodRegistryPlugin");
-      }
-      repo.registerMethod("addSubdocument", async function(parentId, arrayPath, subData, options = {}) {
-        const update2 = this.update;
-        return update2.call(this, parentId, { $push: { [arrayPath]: subData } }, options);
-      });
-      repo.registerMethod("getSubdocument", async function(parentId, arrayPath, subId, options = {}) {
-        const _executeQuery = this._executeQuery;
-        return _executeQuery.call(this, async (Model) => {
-          const parent = await Model.findById(parentId).session(options.session).exec();
-          if (!parent) throw createError(404, "Parent not found");
-          const parentObj = parent;
-          const arrayField = parentObj[arrayPath];
-          if (!arrayField || typeof arrayField.id !== "function") {
-            throw createError(404, "Array field not found");
-          }
-          const sub = arrayField.id(subId);
-          if (!sub) throw createError(404, "Subdocument not found");
-          return options.lean && typeof sub.toObject === "function" ? sub.toObject() : sub;
-        });
-      });
-      repo.registerMethod("updateSubdocument", async function(parentId, arrayPath, subId, updateData, options = {}) {
-        const _executeQuery = this._executeQuery;
-        return _executeQuery.call(this, async (Model) => {
-          const query = { _id: parentId, [`${arrayPath}._id`]: subId };
-          const update2 = { $set: { [`${arrayPath}.$`]: { ...updateData, _id: subId } } };
-          const result = await Model.findOneAndUpdate(query, update2, {
-            new: true,
-            runValidators: true,
-            session: options.session
-          }).exec();
-          if (!result) throw createError(404, "Parent or subdocument not found");
-          return result;
-        });
-      });
-      repo.registerMethod("deleteSubdocument", async function(parentId, arrayPath, subId, options = {}) {
-        const update2 = this.update;
-        return update2.call(this, parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
-      });
-    }
-  };
-}
-
-// src/utils/cache-keys.ts
-function hashString(str) {
-  let hash = 5381;
-  for (let i = 0; i < str.length; i++) {
-    hash = (hash << 5) + hash ^ str.charCodeAt(i);
-  }
-  return (hash >>> 0).toString(16);
-}
-function stableStringify(obj) {
-  if (obj === null || obj === void 0) return "";
-  if (typeof obj !== "object") return String(obj);
-  if (Array.isArray(obj)) {
-    return "[" + obj.map(stableStringify).join(",") + "]";
-  }
-  const sorted = Object.keys(obj).sort().map((key) => `${key}:${stableStringify(obj[key])}`);
-  return "{" + sorted.join(",") + "}";
-}
-function byIdKey(prefix, model, id) {
-  return `${prefix}:id:${model}:${id}`;
-}
-function byQueryKey(prefix, model, query, options) {
-  const hashInput = stableStringify({ q: query, s: options?.select, p: options?.populate });
-  return `${prefix}:one:${model}:${hashString(hashInput)}`;
-}
-function listQueryKey(prefix, model, version, params) {
-  const hashInput = stableStringify({
-    f: params.filters,
-    s: params.sort,
-    pg: params.page,
-    lm: params.limit,
-    af: params.after,
-    sl: params.select,
-    pp: params.populate
-  });
-  return `${prefix}:list:${model}:${version}:${hashString(hashInput)}`;
-}
-function versionKey(prefix, model) {
-  return `${prefix}:ver:${model}`;
-}
-function modelPattern(prefix, model) {
-  return `${prefix}:*:${model}:*`;
-}
-
-// src/plugins/cache.plugin.ts
-function cachePlugin(options) {
-  const config = {
-    adapter: options.adapter,
-    ttl: options.ttl ?? 60,
-    byIdTtl: options.byIdTtl ?? options.ttl ?? 60,
-    queryTtl: options.queryTtl ?? options.ttl ?? 60,
-    prefix: options.prefix ?? "mk",
-    debug: options.debug ?? false,
-    skipIfLargeLimit: options.skipIf?.largeLimit ?? 100
-  };
-  const stats = {
-    hits: 0,
-    misses: 0,
-    sets: 0,
-    invalidations: 0
-  };
-  let collectionVersion = 0;
-  const log = (msg, data) => {
-    if (config.debug) {
-      console.log(`[mongokit:cache] ${msg}`, data ?? "");
-    }
-  };
-  return {
-    name: "cache",
-    apply(repo) {
-      const model = repo.model;
-      (async () => {
-        try {
-          const cached = await config.adapter.get(versionKey(config.prefix, model));
-          if (cached !== null) {
-            collectionVersion = cached;
-            log(`Initialized version for ${model}:`, collectionVersion);
-          }
-        } catch (e) {
-          log(`Failed to initialize version for ${model}:`, e);
-        }
-      })();
-      async function bumpVersion() {
-        collectionVersion++;
-        try {
-          await config.adapter.set(versionKey(config.prefix, model), collectionVersion, config.ttl * 10);
-          stats.invalidations++;
-          log(`Bumped version for ${model} to:`, collectionVersion);
-        } catch (e) {
-          log(`Failed to bump version for ${model}:`, e);
-        }
-      }
-      async function invalidateById(id) {
-        const key = byIdKey(config.prefix, model, id);
-        try {
-          await config.adapter.del(key);
-          stats.invalidations++;
-          log(`Invalidated byId cache:`, key);
-        } catch (e) {
-          log(`Failed to invalidate byId cache:`, e);
-        }
+      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.`
+        );
       }
-      repo.on("before:getById", async (context) => {
-        if (context.skipCache) {
-          log(`Skipping cache for getById: ${context.id}`);
-          return;
-        }
-        const id = String(context.id);
-        const key = byIdKey(config.prefix, model, id);
-        try {
-          const cached = await config.adapter.get(key);
-          if (cached !== null) {
-            stats.hits++;
-            log(`Cache HIT for getById:`, key);
-            context._cacheHit = true;
-            context._cachedResult = cached;
-          } else {
-            stats.misses++;
-            log(`Cache MISS for getById:`, key);
-          }
-        } catch (e) {
-          log(`Cache error for getById:`, e);
-          stats.misses++;
-        }
-      });
-      repo.on("before:getByQuery", async (context) => {
-        if (context.skipCache) {
-          log(`Skipping cache for getByQuery`);
-          return;
-        }
-        const query = context.query || {};
-        const key = byQueryKey(config.prefix, model, query, {
-          select: context.select,
-          populate: context.populate
-        });
-        try {
-          const cached = await config.adapter.get(key);
-          if (cached !== null) {
-            stats.hits++;
-            log(`Cache HIT for getByQuery:`, key);
-            context._cacheHit = true;
-            context._cachedResult = cached;
-          } else {
-            stats.misses++;
-            log(`Cache MISS for getByQuery:`, key);
-          }
-        } catch (e) {
-          log(`Cache error for getByQuery:`, e);
-          stats.misses++;
-        }
-      });
-      repo.on("before:getAll", async (context) => {
-        if (context.skipCache) {
-          log(`Skipping cache for getAll`);
-          return;
-        }
-        const limit = context.limit;
-        if (limit && limit > config.skipIfLargeLimit) {
-          log(`Skipping cache for large query (limit: ${limit})`);
-          return;
-        }
-        const params = {
-          filters: context.filters,
-          sort: context.sort,
-          page: context.page,
-          limit,
-          after: context.after,
-          select: context.select,
-          populate: context.populate
-        };
-        const key = listQueryKey(config.prefix, model, collectionVersion, params);
-        try {
-          const cached = await config.adapter.get(key);
-          if (cached !== null) {
-            stats.hits++;
-            log(`Cache HIT for getAll:`, key);
-            context._cacheHit = true;
-            context._cachedResult = cached;
-          } else {
-            stats.misses++;
-            log(`Cache MISS for getAll:`, key);
-          }
-        } catch (e) {
-          log(`Cache error for getAll:`, e);
-          stats.misses++;
-        }
-      });
-      repo.on("after:getById", async (payload) => {
-        const { context, result } = payload;
-        if (context._cacheHit) return;
-        if (context.skipCache) return;
-        if (result === null) return;
-        const id = String(context.id);
-        const key = byIdKey(config.prefix, model, id);
-        const ttl = context.cacheTtl ?? config.byIdTtl;
-        try {
-          await config.adapter.set(key, result, ttl);
-          stats.sets++;
-          log(`Cached getById result:`, key);
-        } catch (e) {
-          log(`Failed to cache getById:`, e);
-        }
-      });
-      repo.on("after:getByQuery", async (payload) => {
-        const { context, result } = payload;
-        if (context._cacheHit) return;
-        if (context.skipCache) return;
-        if (result === null) return;
-        const query = context.query || {};
-        const key = byQueryKey(config.prefix, model, query, {
-          select: context.select,
-          populate: context.populate
-        });
-        const ttl = context.cacheTtl ?? config.queryTtl;
-        try {
-          await config.adapter.set(key, result, ttl);
-          stats.sets++;
-          log(`Cached getByQuery result:`, key);
-        } catch (e) {
-          log(`Failed to cache getByQuery:`, e);
-        }
-      });
-      repo.on("after:getAll", async (payload) => {
-        const { context, result } = payload;
-        if (context._cacheHit) return;
-        if (context.skipCache) return;
-        const limit = context.limit;
-        if (limit && limit > config.skipIfLargeLimit) return;
-        const params = {
-          filters: context.filters,
-          sort: context.sort,
-          page: context.page,
-          limit,
-          after: context.after,
-          select: context.select,
-          populate: context.populate
-        };
-        const key = listQueryKey(config.prefix, model, collectionVersion, params);
-        const ttl = context.cacheTtl ?? config.queryTtl;
-        try {
-          await config.adapter.set(key, result, ttl);
-          stats.sets++;
-          log(`Cached getAll result:`, key);
-        } catch (e) {
-          log(`Failed to cache getAll:`, e);
-        }
-      });
-      repo.on("after:create", async () => {
-        await bumpVersion();
-      });
-      repo.on("after:createMany", async () => {
-        await bumpVersion();
-      });
-      repo.on("after:update", async (payload) => {
-        const { context } = payload;
-        const id = String(context.id);
-        await Promise.all([
-          invalidateById(id),
-          bumpVersion()
-        ]);
-      });
-      repo.on("after:updateMany", async () => {
-        await bumpVersion();
-      });
-      repo.on("after:delete", async (payload) => {
-        const { context } = payload;
-        const id = String(context.id);
-        await Promise.all([
-          invalidateById(id),
-          bumpVersion()
-        ]);
-      });
-      repo.on("after:deleteMany", async () => {
-        await bumpVersion();
-      });
-      repo.invalidateCache = async (id) => {
-        await invalidateById(id);
-        log(`Manual invalidation for ID:`, id);
-      };
-      repo.invalidateListCache = async () => {
-        await bumpVersion();
-        log(`Manual list cache invalidation for ${model}`);
-      };
-      repo.invalidateAllCache = async () => {
-        if (config.adapter.clear) {
-          try {
-            await config.adapter.clear(modelPattern(config.prefix, model));
-            stats.invalidations++;
-            log(`Full cache invalidation for ${model}`);
-          } catch (e) {
-            log(`Failed full cache invalidation for ${model}:`, e);
-          }
-        } else {
-          await bumpVersion();
-          log(`Partial cache invalidation for ${model} (adapter.clear not available)`);
-        }
-      };
-      repo.getCacheStats = () => ({ ...stats });
-      repo.resetCacheStats = () => {
-        stats.hits = 0;
-        stats.misses = 0;
-        stats.sets = 0;
-        stats.invalidations = 0;
-      };
-    }
-  };
-}
-function cascadePlugin(options) {
-  const { relations, parallel = true, logger } = options;
-  if (!relations || relations.length === 0) {
-    throw new Error("cascadePlugin requires at least one relation");
-  }
-  return {
-    name: "cascade",
-    apply(repo) {
-      repo.on("after:delete", async (payload) => {
-        const { context } = payload;
-        const deletedId = context.id;
-        if (!deletedId) {
-          logger?.warn?.("Cascade delete skipped: no document ID in context", {
-            model: context.model
-          });
-          return;
-        }
-        const isSoftDelete = context.softDeleted === true;
-        const cascadeDelete = async (relation) => {
-          const RelatedModel = mongoose4.models[relation.model];
-          if (!RelatedModel) {
-            logger?.warn?.(`Cascade delete skipped: model '${relation.model}' not found`, {
-              parentModel: context.model,
-              parentId: String(deletedId)
-            });
-            return;
-          }
-          const query = { [relation.foreignKey]: deletedId };
-          try {
-            const shouldSoftDelete = relation.softDelete ?? isSoftDelete;
-            if (shouldSoftDelete) {
-              const updateResult = await RelatedModel.updateMany(
-                query,
-                {
-                  deletedAt: /* @__PURE__ */ new Date(),
-                  ...context.user ? { deletedBy: context.user._id || context.user.id } : {}
-                },
-                { session: context.session }
-              );
-              logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents`, {
-                parentModel: context.model,
-                parentId: String(deletedId),
-                relatedModel: relation.model,
-                foreignKey: relation.foreignKey,
-                count: updateResult.modifiedCount
-              });
+      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 {
-              const deleteResult = await RelatedModel.deleteMany(query, {
-                session: context.session
-              });
-              logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents`, {
-                parentModel: context.model,
-                parentId: String(deletedId),
-                relatedModel: relation.model,
-                foreignKey: relation.foreignKey,
-                count: deleteResult.deletedCount
-              });
+              projection[field] = 1;
             }
-          } catch (error) {
-            logger?.error?.(`Cascade delete failed for model '${relation.model}'`, {
-              parentModel: context.model,
-              parentId: String(deletedId),
-              relatedModel: relation.model,
-              foreignKey: relation.foreignKey,
-              error: error.message
-            });
-            throw error;
-          }
-        };
-        if (parallel) {
-          await Promise.all(relations.map(cascadeDelete));
-        } else {
-          for (const relation of relations) {
-            await cascadeDelete(relation);
           }
-        }
-      });
-      repo.on("after:deleteMany", async (payload) => {
-        const { context, result } = payload;
-        const query = context.query;
-        if (!query || Object.keys(query).length === 0) {
-          logger?.warn?.("Cascade deleteMany skipped: empty query", {
-            model: context.model
-          });
-          return;
-        }
-        logger?.warn?.("Cascade deleteMany: use before:deleteMany hook for complete cascade support", {
-          model: context.model
-        });
-      });
-      repo.on("before:deleteMany", async (context) => {
-        const query = context.query;
-        if (!query || Object.keys(query).length === 0) {
-          return;
-        }
-        const docs = await repo.Model.find(query, { _id: 1 }).lean().session(context.session ?? null);
-        const ids = docs.map((doc) => doc._id);
-        context._cascadeIds = ids;
-      });
-      const originalAfterDeleteMany = repo._hooks.get("after:deleteMany") || [];
-      repo._hooks.set("after:deleteMany", [
-        ...originalAfterDeleteMany,
-        async (payload) => {
-          const { context } = payload;
-          const ids = context._cascadeIds;
-          if (!ids || ids.length === 0) {
-            return;
-          }
-          const isSoftDelete = context.softDeleted === true;
-          const cascadeDeleteMany = async (relation) => {
-            const RelatedModel = mongoose4.models[relation.model];
-            if (!RelatedModel) {
-              logger?.warn?.(`Cascade deleteMany skipped: model '${relation.model}' not found`, {
-                parentModel: context.model
-              });
-              return;
-            }
-            const query = { [relation.foreignKey]: { $in: ids } };
-            const shouldSoftDelete = relation.softDelete ?? isSoftDelete;
-            try {
-              if (shouldSoftDelete) {
-                const updateResult = await RelatedModel.updateMany(
-                  query,
-                  {
-                    deletedAt: /* @__PURE__ */ new Date(),
-                    ...context.user ? { deletedBy: context.user._id || context.user.id } : {}
-                  },
-                  { session: context.session }
-                );
-                logger?.info?.(`Cascade soft-deleted ${updateResult.modifiedCount} documents (bulk)`, {
-                  parentModel: context.model,
-                  parentCount: ids.length,
-                  relatedModel: relation.model,
-                  foreignKey: relation.foreignKey,
-                  count: updateResult.modifiedCount
-                });
-              } else {
-                const deleteResult = await RelatedModel.deleteMany(query, {
-                  session: context.session
-                });
-                logger?.info?.(`Cascade deleted ${deleteResult.deletedCount} documents (bulk)`, {
-                  parentModel: context.model,
-                  parentCount: ids.length,
-                  relatedModel: relation.model,
-                  foreignKey: relation.foreignKey,
-                  count: deleteResult.deletedCount
-                });
-              }
-            } catch (error) {
-              logger?.error?.(`Cascade deleteMany failed for model '${relation.model}'`, {
-                parentModel: context.model,
-                relatedModel: relation.model,
-                foreignKey: relation.foreignKey,
-                error: error.message
-              });
-              throw error;
-            }
-          };
-          if (parallel) {
-            await Promise.all(relations.map(cascadeDeleteMany));
-          } else {
-            for (const relation of relations) {
-              await cascadeDeleteMany(relation);
+        } 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;
         }
-      ]);
-    }
-  };
-}
-
-// src/utils/memory-cache.ts
-function createMemoryCache(maxEntries = 1e3) {
-  const cache = /* @__PURE__ */ new Map();
-  function cleanup() {
-    const now = Date.now();
-    for (const [key, entry] of cache) {
-      if (entry.expiresAt < now) {
-        cache.delete(key);
-      }
-    }
-  }
-  function evictOldest() {
-    if (cache.size >= maxEntries) {
-      const firstKey = cache.keys().next().value;
-      if (firstKey) cache.delete(firstKey);
-    }
-  }
-  return {
-    async get(key) {
-      cleanup();
-      const entry = cache.get(key);
-      if (!entry) return null;
-      if (entry.expiresAt < Date.now()) {
-        cache.delete(key);
-        return null;
-      }
-      return entry.value;
-    },
-    async set(key, value, ttl) {
-      cleanup();
-      evictOldest();
-      cache.set(key, {
-        value,
-        expiresAt: Date.now() + ttl * 1e3
-      });
-    },
-    async del(key) {
-      cache.delete(key);
-    },
-    async clear(pattern) {
-      if (!pattern) {
-        cache.clear();
-        return;
-      }
-      const regex = new RegExp(
-        "^" + pattern.replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
-      );
-      for (const key of cache.keys()) {
-        if (regex.test(key)) {
-          cache.delete(key);
-        }
+        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);
     }
-  };
-}
-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 jsonUpdate = buildJsonSchemaForUpdate(jsonCreate, options);
-  const jsonParams = {
-    type: "object",
-    properties: { id: { type: "string", pattern: "^[0-9a-fA-F]{24}$" } },
-    required: ["id"]
-  };
-  const jsonQuery = buildJsonSchemaForQuery(tree, options);
-  return { createBody: jsonCreate, updateBody: jsonUpdate, params: jsonParams, listQuery: jsonQuery };
-}
-function buildCrudSchemasFromModel(mongooseModel, options = {}) {
-  if (!mongooseModel || !mongooseModel.schema) {
-    throw new Error("Invalid mongoose model");
   }
-  return buildCrudSchemasFromMongooseSchema(mongooseModel.schema, options);
-}
-function getImmutableFields(options = {}) {
-  const immutable = [];
-  const fieldRules = options?.fieldRules || {};
-  Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.immutable || rules.immutableAfterCreate) {
-      immutable.push(field);
-    }
-  });
-  (options?.update?.omitFields || []).forEach((f) => {
-    if (!immutable.includes(f)) immutable.push(f);
-  });
-  return immutable;
-}
-function getSystemManagedFields(options = {}) {
-  const systemManaged = [];
-  const fieldRules = options?.fieldRules || {};
-  Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.systemManaged) {
-      systemManaged.push(field);
-    }
-  });
-  return systemManaged;
-}
-function isFieldUpdateAllowed(fieldName, options = {}) {
-  const immutableFields = getImmutableFields(options);
-  const systemManagedFields = getSystemManagedFields(options);
-  return !immutableFields.includes(fieldName) && !systemManagedFields.includes(fieldName);
-}
-function validateUpdateBody(body = {}, options = {}) {
-  const violations = [];
-  const immutableFields = getImmutableFields(options);
-  const systemManagedFields = getSystemManagedFields(options);
-  Object.keys(body).forEach((field) => {
-    if (immutableFields.includes(field)) {
-      violations.push({ field, reason: "Field is immutable" });
-    } else if (systemManagedFields.includes(field)) {
-      violations.push({ field, reason: "Field is system-managed" });
-    }
-  });
-  return {
-    valid: violations.length === 0,
-    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) };
+  /**
+   * 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();
   }
-  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 } };
+  /**
+   * 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, 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) {
+      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);
       }
-      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);
+      if (started && session.inTransaction()) {
+        await session.abortTransaction();
       }
+      throw err;
+    } finally {
+      session.endSession();
     }
   }
-  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);
+  _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");
   }
-  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 || {};
-  Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.systemManaged) {
-      fieldsToOmit.add(field);
-    }
-  });
-  fieldsToOmit.forEach((field) => {
-    if (base.properties?.[field]) {
-      delete base.properties[field];
-    }
-    if (base.required) {
-      base.required = base.required.filter((k) => k !== field);
-    }
-  });
-  const reqOv = options?.create?.requiredOverrides || {};
-  const optOv = options?.create?.optionalOverrides || {};
-  base.required = base.required || [];
-  for (const [k, v] of Object.entries(reqOv)) {
-    if (v && !base.required.includes(k)) base.required.push(k);
-  }
-  for (const [k, v] of Object.entries(optOv)) {
-    if (v && base.required) base.required = base.required.filter((x) => x !== k);
-  }
-  Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.optional && base.required) {
-      base.required = base.required.filter((x) => x !== field);
+  /**
+   * Execute custom query with event emission
+   */
+  async _executeQuery(buildQuery) {
+    const operation = buildQuery.name || "custom";
+    const context = await this._buildContext(operation, {});
+    try {
+      const result = await buildQuery(this.Model);
+      await this._emitHook(`after:${operation}`, { context, result });
+      return result;
+    } catch (error) {
+      await this._emitErrorHook(`error:${operation}`, { context, error });
+      throw this._handleError(error);
     }
-  });
-  const schemaOverrides = options?.create?.schemaOverrides || {};
-  for (const [k, override] of Object.entries(schemaOverrides)) {
-    if (base.properties?.[k]) {
-      base.properties[k] = override;
+  }
+  /**
+   * Build operation context and run before hooks
+   */
+  async _buildContext(operation, options) {
+    const context = { operation, model: this.model, ...options };
+    const event = `before:${operation}`;
+    const hooks = this._hooks.get(event) || [];
+    for (const hook of hooks) {
+      await hook(context);
     }
+    return context;
   }
-  if (options?.strictAdditionalProperties === true) {
-    base.additionalProperties = false;
+  /**
+   * Parse sort string or object
+   */
+  _parseSort(sort) {
+    if (!sort) return { createdAt: -1 };
+    if (typeof sort === "object") return sort;
+    const sortOrder = sort.startsWith("-") ? -1 : 1;
+    const sortField = sort.startsWith("-") ? sort.substring(1) : sort;
+    return { [sortField]: sortOrder };
   }
-  return base;
-}
-function buildJsonSchemaForUpdate(createJson, options) {
-  const clone = JSON.parse(JSON.stringify(createJson));
-  delete clone.required;
-  const fieldsToOmit = /* @__PURE__ */ new Set();
-  (options?.update?.omitFields || []).forEach((f) => fieldsToOmit.add(f));
-  const fieldRules = options?.fieldRules || {};
-  Object.entries(fieldRules).forEach(([field, rules]) => {
-    if (rules.immutable || rules.immutableAfterCreate) {
-      fieldsToOmit.add(field);
-    }
-  });
-  fieldsToOmit.forEach((field) => {
-    if (clone.properties?.[field]) {
-      delete clone.properties[field];
-    }
-  });
-  if (options?.strictAdditionalProperties === true) {
-    clone.additionalProperties = false;
+  /**
+   * Parse populate specification
+   */
+  _parsePopulate(populate) {
+    if (!populate) return [];
+    if (typeof populate === "string") return populate.split(",").map((p) => p.trim());
+    if (Array.isArray(populate)) return populate.map((p) => typeof p === "string" ? p.trim() : p);
+    return [populate];
   }
-  return clone;
-}
-function buildJsonSchemaForQuery(_tree, options) {
-  const basePagination = {
-    type: "object",
-    properties: {
-      page: { type: "string" },
-      limit: { type: "string" },
-      sort: { type: "string" },
-      populate: { type: "string" },
-      search: { type: "string" },
-      select: { type: "string" },
-      lean: { type: "string" },
-      includeDeleted: { type: "string" }
-    },
-    additionalProperties: true
-  };
-  const filterable = options?.query?.filterableFields || {};
-  for (const [k, v] of Object.entries(filterable)) {
-    if (basePagination.properties) {
-      basePagination.properties[k] = v && typeof v === "object" && "type" in v ? v : { type: "string" };
+  /**
+   * Handle errors with proper HTTP status codes
+   */
+  _handleError(error) {
+    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 mongoose.Error.CastError) {
+      return createError(400, `Invalid ${error.path}: ${error.value}`);
     }
+    if (error.status && error.message) return error;
+    return createError(500, error.message || "Internal Server Error");
   }
-  return basePagination;
-}
+};
 var QueryParser = class {
   options;
   operators = {
@@ -2691,21 +1172,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",
@@ -2716,9 +1202,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,
@@ -2727,15 +1220,35 @@ var QueryParser = class {
       search,
       after,
       cursor,
+      select,
+      lookup,
+      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 && lookup) {
+      parsed.lookups = this._parseLookups(lookup);
+    }
+    if (this.options.enableAggregations && aggregate2) {
+      parsed.aggregation = this._parseAggregation(aggregate2);
+    }
     if (after || cursor) {
       parsed.after = after || cursor;
     } else if (page !== void 0) {
@@ -2750,29 +1263,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(lookup) {
+    if (!lookup || typeof lookup !== "object") return [];
+    const lookups = [];
+    const lookupObj = lookup;
+    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)) {
@@ -2780,7 +1425,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(/^(.+)\[(.+)\]$/);
@@ -2794,7 +1439,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);
       }
@@ -2806,6 +1451,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) {
@@ -2823,18 +1471,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)) {
@@ -2845,17 +1493,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;
@@ -2868,7 +1524,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;
@@ -2878,31 +1534,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 {
@@ -2911,34 +1576,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));
@@ -2946,14 +1622,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;
@@ -2961,14 +1634,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 || {})) {
@@ -2985,19 +1655,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 = {};
-__export(actions_exports, {
-  aggregate: () => aggregate_exports,
-  create: () => create_exports,
-  deleteActions: () => delete_exports,
-  read: () => read_exports,
-  update: () => update_exports
-});
 
 // src/index.ts
 function createRepository(Model, plugins = [], paginationConfig = {}, options = {}) {
@@ -3011,7 +1678,7 @@ var index_default = Repository;
  * smart pagination, events, and plugins.
  * 
  * @module @classytic/mongokit
- * @author Sadman Chowdhury (Github: @siam923)
+ * @author Classytic (https://github.com/classytic)
  * @license MIT
  * 
  * @example
@@ -3043,4 +1710,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, QueryParser, Repository, createRepository, index_default as default };