@classytic/mongokit 3.1.0 → 3.1.2

package/dist/chunks/chunk-IT7DCOKR.js

@@ -0,0 +1,299 @@
+import 'mongoose';
+
+// 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);
+        }
+      }
+    }
+  };
+}
+function buildCrudSchemasFromMongooseSchema(mongooseSchema, options = {}) {
+  const jsonCreate = buildJsonSchemaFromPaths(mongooseSchema, options);
+  const jsonUpdate = buildJsonSchemaForUpdate(jsonCreate, options);
+  const jsonParams = {
+    type: "object",
+    properties: { id: { type: "string", pattern: "^[0-9a-fA-F]{24}$" } },
+    required: ["id"]
+  };
+  const tree = mongooseSchema?.obj || {};
+  const jsonQuery = buildJsonSchemaForQuery(tree, options);
+  return { createBody: jsonCreate, updateBody: jsonUpdate, params: jsonParams, listQuery: jsonQuery };
+}
+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 buildJsonSchemaFromPaths(mongooseSchema, options) {
+  const properties = {};
+  const required = [];
+  const paths = mongooseSchema.paths;
+  const rootFields = /* @__PURE__ */ new Map();
+  for (const [path, schemaType] of Object.entries(paths)) {
+    if (path === "_id" || path === "__v") continue;
+    const parts = path.split(".");
+    const rootField = parts[0];
+    if (!rootFields.has(rootField)) {
+      rootFields.set(rootField, []);
+    }
+    rootFields.get(rootField).push({ path, schemaType });
+  }
+  for (const [rootField, fieldPaths] of rootFields.entries()) {
+    if (fieldPaths.length === 1 && fieldPaths[0].path === rootField) {
+      const schemaType = fieldPaths[0].schemaType;
+      properties[rootField] = schemaTypeToJsonSchema(schemaType);
+      if (schemaType.isRequired) {
+        required.push(rootField);
+      }
+    } else {
+      const nestedSchema = buildNestedJsonSchema(fieldPaths, rootField);
+      properties[rootField] = nestedSchema.schema;
+      if (nestedSchema.required) {
+        required.push(rootField);
+      }
+    }
+  }
+  const schema = { type: "object", properties };
+  if (required.length) schema.required = required;
+  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 (schema.properties?.[field]) {
+      delete schema.properties[field];
+    }
+    if (schema.required) {
+      schema.required = schema.required.filter((k) => k !== field);
+    }
+  });
+  const reqOv = options?.create?.requiredOverrides || {};
+  const optOv = options?.create?.optionalOverrides || {};
+  schema.required = schema.required || [];
+  for (const [k, v] of Object.entries(reqOv)) {
+    if (v && !schema.required.includes(k)) schema.required.push(k);
+  }
+  for (const [k, v] of Object.entries(optOv)) {
+    if (v && schema.required) schema.required = schema.required.filter((x) => x !== k);
+  }
+  Object.entries(fieldRules).forEach(([field, rules]) => {
+    if (rules.optional && schema.required) {
+      schema.required = schema.required.filter((x) => x !== field);
+    }
+  });
+  const schemaOverrides = options?.create?.schemaOverrides || {};
+  for (const [k, override] of Object.entries(schemaOverrides)) {
+    if (schema.properties?.[k]) {
+      schema.properties[k] = override;
+    }
+  }
+  if (options?.strictAdditionalProperties === true) {
+    schema.additionalProperties = false;
+  }
+  return schema;
+}
+function buildNestedJsonSchema(fieldPaths, rootField) {
+  const properties = {};
+  const required = [];
+  let hasRequiredFields = false;
+  for (const { path, schemaType } of fieldPaths) {
+    const relativePath = path.substring(rootField.length + 1);
+    const parts = relativePath.split(".");
+    if (parts.length === 1) {
+      properties[parts[0]] = schemaTypeToJsonSchema(schemaType);
+      if (schemaType.isRequired) {
+        required.push(parts[0]);
+        hasRequiredFields = true;
+      }
+    } else {
+      const fieldName = parts[0];
+      if (!properties[fieldName]) {
+        properties[fieldName] = { type: "object", properties: {} };
+      }
+      const nestedObj = properties[fieldName];
+      if (!nestedObj.properties) nestedObj.properties = {};
+      const deepPath = parts.slice(1).join(".");
+      nestedObj.properties[deepPath] = schemaTypeToJsonSchema(schemaType);
+    }
+  }
+  const schema = { type: "object", properties };
+  if (required.length) schema.required = required;
+  return { schema, required: hasRequiredFields };
+}
+function schemaTypeToJsonSchema(schemaType) {
+  const result = {};
+  const instance = schemaType.instance;
+  const options = schemaType.options || {};
+  if (instance === "String") {
+    result.type = "string";
+    if (typeof options.minlength === "number") result.minLength = options.minlength;
+    if (typeof options.maxlength === "number") result.maxLength = options.maxlength;
+    if (options.match instanceof RegExp) result.pattern = options.match.source;
+    if (options.enum && Array.isArray(options.enum)) result.enum = options.enum;
+  } else if (instance === "Number") {
+    result.type = "number";
+    if (typeof options.min === "number") result.minimum = options.min;
+    if (typeof options.max === "number") result.maximum = options.max;
+  } else if (instance === "Boolean") {
+    result.type = "boolean";
+  } else if (instance === "Date") {
+    result.type = "string";
+    result.format = "date-time";
+  } else if (instance === "ObjectId" || instance === "ObjectID") {
+    result.type = "string";
+    result.pattern = "^[0-9a-fA-F]{24}$";
+  } else if (instance === "Array") {
+    result.type = "array";
+    result.items = { type: "string" };
+  } else {
+    result.type = "object";
+    result.additionalProperties = true;
+  }
+  return result;
+}
+function buildJsonSchemaForUpdate(createJson, options) {
+  const clone = JSON.parse(JSON.stringify(createJson));
+  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;
+  }
+  if (options?.update?.requireAtLeastOne === true) {
+    clone.minProperties = 1;
+  }
+  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" };
+    }
+  }
+  return basePagination;
+}
+
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, createMemoryCache, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };

package/dist/chunks/chunk-M2XHQGZB.js

@@ -0,0 +1,361 @@
+import { createError } from './chunk-VJXDGP3C.js';
+import mongoose from 'mongoose';
+
+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
+   */
+  // 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
+    };
+  }
+  /**
+   * 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 }
+    };
+  }
+};
+
+export { PaginationEngine };