@classytic/mongokit 1.0.2 → 2.1.0

package/dist/index.js

@@ -0,0 +1,2108 @@
+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 parsePopulate2(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 update(Model, id, data, options = {}) {
+  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 = {}) {
+  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;
+  if (buildConstraints) {
+    const constraints = buildConstraints(data);
+    const document = await updateWithConstraints(Model, id, data, constraints, options);
+    if (document) {
+      return { success: true, data: document };
+    }
+  }
+  const existing = await Model.findById(id).select(options.select || "").lean();
+  if (!existing) {
+    return {
+      success: false,
+      error: {
+        code: 404,
+        message: "Document not found"
+      }
+    };
+  }
+  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
+        }
+      };
+    }
+  }
+  const updated = await update(Model, id, data, options);
+  return { success: true, data: updated };
+}
+async function updateMany(Model, query, data, options = {}) {
+  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 = {}) {
+  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");
+  }
+  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" }]
+      }
+    }
+  ];
+  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
+      }
+    }
+  ];
+  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}` }
+    }
+  });
+  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");
+  }
+}
+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");
+  }
+}
+function validateCursorVersion(cursorVersion, expectedVersion) {
+  if (cursorVersion !== expectedVersion) {
+    throw new Error(`Cursor version ${cursorVersion} does not match expected version ${expectedVersion}`);
+  }
+}
+function serializeValue(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof mongoose.Types.ObjectId) return value.toString();
+  return value;
+}
+function getValueType(value) {
+  if (value instanceof Date) return "date";
+  if (value instanceof mongoose.Types.ObjectId) return "objectid";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return "number";
+  if (typeof value === "string") return "string";
+  return "unknown";
+}
+function rehydrateValue(serialized, type) {
+  switch (type) {
+    case "date":
+      return new Date(serialized);
+    case "objectid":
+      return new mongoose.Types.ObjectId(serialized);
+    case "boolean":
+      return Boolean(serialized);
+    case "number":
+      return Number(serialized);
+    default:
+      return serialized;
+  }
+}
+
+// src/pagination/utils/sort.ts
+function normalizeSort(sort) {
+  const normalized = {};
+  Object.keys(sort).forEach((key) => {
+    if (key !== "_id") normalized[key] = sort[key];
+  });
+  if (sort._id !== void 0) {
+    normalized._id = sort._id;
+  }
+  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);
+  }
+  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;
+  }
+  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;
+  }
+  const sanitized = Math.floor(parsed);
+  if (sanitized > (config.maxPage || 1e4)) {
+    throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+  }
+  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
+   */
+  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
+    };
+  }
+  /**
+   * 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);
+   */
+  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 }
+    };
+  }
+  /**
+   * 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
+   * });
+   */
+  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
+    };
+  }
+  /**
+   * 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
+   *
+   * @example
+   * const result = await engine.aggregatePaginate({
+   *   pipeline: [
+   *     { $match: { status: 'active' } },
+   *     { $group: { _id: '$category', count: { $sum: 1 } } },
+   *     { $sort: { count: -1 } }
+   *   ],
+   *   page: 1,
+   *   limit: 20
+   * });
+   */
+  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;
+  constructor(Model, plugins = [], paginationConfig = {}) {
+    this.Model = Model;
+    this.model = Model.modelName;
+    this._hooks = /* @__PURE__ */ new Map();
+    this._pagination = new PaginationEngine(Model, paginationConfig);
+    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
+   */
+  emit(event, data) {
+    const listeners = this._hooks.get(event) || [];
+    listeners.forEach((listener) => listener(data));
+  }
+  /**
+   * Create single document
+   */
+  async create(data, options = {}) {
+    const context = await this._buildContext("create", { data, ...options });
+    try {
+      const result = await create(this.Model, context.data || data, options);
+      this.emit("after:create", { context, result });
+      return result;
+    } catch (error) {
+      this.emit("error:create", { context, error });
+      throw this._handleError(error);
+    }
+  }
+  /**
+   * Create multiple documents
+   */
+  async createMany(dataArray, options = {}) {
+    const context = await this._buildContext("createMany", { dataArray, ...options });
+    try {
+      const result = await createMany(this.Model, context.dataArray || dataArray, options);
+      this.emit("after:createMany", { context, result });
+      return result;
+    } catch (error) {
+      this.emit("error:createMany", { context, error });
+      throw this._handleError(error);
+    }
+  }
+  /**
+   * Get document by ID
+   */
+  async getById(id, options = {}) {
+    const context = await this._buildContext("getById", { id, ...options });
+    if (context._cacheHit) {
+      return context._cachedResult;
+    }
+    const result = await getById(this.Model, id, context);
+    this.emit("after:getById", { context, result });
+    return result;
+  }
+  /**
+   * Get single document by query
+   */
+  async getByQuery(query, options = {}) {
+    const context = await this._buildContext("getByQuery", { query, ...options });
+    if (context._cacheHit) {
+      return context._cachedResult;
+    }
+    const result = await getByQuery(this.Model, query, context);
+    this.emit("after:getByQuery", { context, result });
+    return result;
+  }
+  /**
+   * Unified pagination - auto-detects offset vs keyset based on params
+   *
+   * Auto-detection logic:
+   * - If params has 'cursor' or 'after' → uses keyset pagination (stream)
+   * - If params has 'pagination' or 'page' → uses offset pagination (paginate)
+   * - Else → defaults to offset pagination with page=1
+   *
+   * @example
+   * // Offset pagination (page-based)
+   * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
+   * await repo.getAll({ pagination: { page: 2, limit: 20 } });
+   *
+   * // Keyset pagination (cursor-based)
+   * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
+   * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
+   *
+   * // Simple query (defaults to page 1)
+   * await repo.getAll({ filters: { status: 'active' } });
+   * 
+   * // Skip cache for fresh data
+   * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+   */
+  async getAll(params = {}, options = {}) {
+    const context = await this._buildContext("getAll", { ...params, ...options });
+    if (context._cacheHit) {
+      return context._cachedResult;
+    }
+    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 filters = params.filters || {};
+    const search = params.search;
+    const sort = params.sort || "-createdAt";
+    const limit = params.limit || params.pagination?.limit || this._pagination.config.defaultLimit;
+    let query = { ...filters };
+    if (search) query.$text = { $search: search };
+    const paginationOptions = {
+      filters: query,
+      sort: this._parseSort(sort),
+      limit,
+      populate: this._parsePopulate(context.populate || options.populate),
+      select: context.select || options.select,
+      lean: context.lean ?? options.lean ?? true,
+      session: options.session
+    };
+    let result;
+    if (useKeyset) {
+      result = await this._pagination.stream({
+        ...paginationOptions,
+        sort: paginationOptions.sort,
+        // Required for keyset
+        after: params.cursor || params.after
+      });
+    } else {
+      const page = params.pagination?.page || params.page || 1;
+      result = await this._pagination.paginate({
+        ...paginationOptions,
+        page
+      });
+    }
+    this.emit("after:getAll", { context, result });
+    return result;
+  }
+  /**
+   * Get or create document
+   */
+  async getOrCreate(query, createData, options = {}) {
+    return getOrCreate(this.Model, query, createData, options);
+  }
+  /**
+   * Count documents
+   */
+  async count(query = {}, options = {}) {
+    return count(this.Model, query, options);
+  }
+  /**
+   * Check if document exists
+   */
+  async exists(query, options = {}) {
+    return exists(this.Model, query, options);
+  }
+  /**
+   * Update document by ID
+   */
+  async update(id, data, options = {}) {
+    const context = await this._buildContext("update", { id, data, ...options });
+    try {
+      const result = await update(this.Model, id, context.data || data, context);
+      this.emit("after:update", { context, result });
+      return result;
+    } catch (error) {
+      this.emit("error:update", { context, error });
+      throw this._handleError(error);
+    }
+  }
+  /**
+   * Delete document by ID
+   */
+  async delete(id, options = {}) {
+    const context = await this._buildContext("delete", { id, ...options });
+    try {
+      if (context.softDeleted) {
+        const result2 = { success: true, message: "Soft deleted successfully" };
+        this.emit("after:delete", { context, result: result2 });
+        return result2;
+      }
+      const result = await deleteById(this.Model, id, options);
+      this.emit("after:delete", { context, result });
+      return result;
+    } catch (error) {
+      this.emit("error:delete", { context, error });
+      throw this._handleError(error);
+    }
+  }
+  /**
+   * Execute aggregation pipeline
+   */
+  async aggregate(pipeline, options = {}) {
+    return aggregate(this.Model, pipeline, options);
+  }
+  /**
+   * Aggregate pipeline with pagination
+   * Best for: Complex queries, grouping, joins
+   */
+  async aggregatePaginate(options = {}) {
+    const context = await this._buildContext("aggregatePaginate", options);
+    return this._pagination.aggregatePaginate(context);
+  }
+  /**
+   * Get distinct values
+   */
+  async distinct(field, query = {}, options = {}) {
+    return distinct(this.Model, field, query, options);
+  }
+  /**
+   * Execute callback within a transaction
+   */
+  async withTransaction(callback) {
+    const session = await mongoose.startSession();
+    session.startTransaction();
+    try {
+      const result = await callback(session);
+      await session.commitTransaction();
+      return result;
+    } catch (error) {
+      await session.abortTransaction();
+      throw error;
+    } finally {
+      session.endSession();
+    }
+  }
+  /**
+   * 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);
+      this.emit(`after:${operation}`, { context, result });
+      return result;
+    } catch (error) {
+      this.emit(`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 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");
+  }
+};
+
+// 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 softDeletePlugin(options = {}) {
+  const deletedField = options.deletedField || "deletedAt";
+  const deletedByField = options.deletedByField || "deletedBy";
+  return {
+    name: "softDelete",
+    apply(repo) {
+      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 (!context.includeDeleted && options.soft !== false) {
+          const queryParams = context.queryParams || {};
+          queryParams.filters = {
+            ...queryParams.filters || {},
+            [deletedField]: { $exists: false }
+          };
+          context.queryParams = queryParams;
+        }
+      });
+      repo.on("before:getById", (context) => {
+        if (!context.includeDeleted && options.soft !== false) {
+          context.query = {
+            ...context.query || {},
+            [deletedField]: { $exists: false }
+          };
+        }
+      });
+    }
+  };
+}
+
+// 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."
+        );
+      }
+      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);
+          const result = await this.Model.updateMany(query, data, {
+            runValidators: true,
+            session: options.session
+          }).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);
+        }
+      }
+      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;
+      };
+    }
+  };
+}
+
+// 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);
+        }
+      }
+    }
+  };
+}
+
+// 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 = []) {
+  return new Repository(Model, plugins);
+}
+var index_default = Repository;
+/**
+ * MongoKit - Event-driven repository pattern for MongoDB
+ * 
+ * Production-grade MongoDB repositories with zero dependencies -
+ * smart pagination, events, and plugins.
+ * 
+ * @module @classytic/mongokit
+ * @author Sadman Chowdhury (Github: @siam923)
+ * @license MIT
+ * 
+ * @example
+ * ```typescript
+ * import { Repository, createRepository } from '@classytic/mongokit';
+ * import { timestampPlugin, softDeletePlugin } from '@classytic/mongokit';
+ * 
+ * // Create repository with plugins
+ * const userRepo = createRepository(UserModel, [
+ *   timestampPlugin(),
+ *   softDeletePlugin(),
+ * ]);
+ * 
+ * // Create
+ * const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
+ * 
+ * // Read with pagination (auto-detects offset vs keyset)
+ * const users = await userRepo.getAll({ page: 1, limit: 20 });
+ * 
+ * // Keyset pagination for infinite scroll
+ * const stream = await userRepo.getAll({ sort: { createdAt: -1 }, limit: 50 });
+ * const nextStream = await userRepo.getAll({ after: stream.next, sort: { createdAt: -1 } });
+ * 
+ * // Update
+ * await userRepo.update(user._id, { name: 'John Doe' });
+ * 
+ * // Delete
+ * await userRepo.delete(user._id);
+ * ```
+ */
+
+export { PaginationEngine, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, createError, createFieldPreset, createMemoryCache, createRepository, index_default as default, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map