@classytic/mongokit 2.0.0 → 3.0.0

package/dist/memory-cache-DG2oSSbx.d.ts

@@ -0,0 +1,142 @@
+import { o as UserContext, F as FieldPreset, H as HttpError, N as CacheAdapter } from './types-Nxhmi1aI.js';
+
+/**
+ * Field Selection Utilities
+ *
+ * Provides explicit, performant field filtering using Mongoose projections.
+ *
+ * Philosophy:
+ * - Explicit is better than implicit
+ * - Filter at DB level (10x faster than in-memory)
+ * - Progressive disclosure (show more fields as trust increases)
+ *
+ * @example
+ * ```typescript
+ * // For Mongoose queries (PREFERRED - 90% of cases)
+ * const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
+ * const plans = await GymPlan.find().select(projection).lean();
+ *
+ * // For complex data (10% of cases - aggregations, multiple sources)
+ * const filtered = filterResponseData(complexData, fieldPresets.gymPlans, request.user);
+ * ```
+ */
+
+/**
+ * Get allowed fields for a user based on their context
+ *
+ * @param user - User object from request.user (or null for public)
+ * @param preset - Field preset configuration
+ * @returns Array of allowed field names
+ *
+ * @example
+ * const fields = getFieldsForUser(request.user, {
+ *   public: ['id', 'name', 'price'],
+ *   authenticated: ['description', 'features'],
+ *   admin: ['createdAt', 'internalNotes']
+ * });
+ */
+declare function getFieldsForUser(user: UserContext | null | undefined, preset: FieldPreset): string[];
+/**
+ * Get Mongoose projection string for query .select()
+ *
+ * @param user - User object from request.user
+ * @param preset - Field preset configuration
+ * @returns Space-separated field names for Mongoose .select()
+ *
+ * @example
+ * const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
+ * const plans = await GymPlan.find({ organizationId }).select(projection).lean();
+ */
+declare function getMongooseProjection(user: UserContext | null | undefined, preset: FieldPreset): string;
+/**
+ * Filter response data to include only allowed fields
+ *
+ * Use this for complex responses where Mongoose projections aren't applicable:
+ * - Aggregation pipeline results
+ * - Data from multiple sources
+ * - Custom computed fields
+ *
+ * For simple DB queries, prefer getMongooseProjection() (10x faster)
+ *
+ * @param data - Data to filter
+ * @param preset - Field preset configuration
+ * @param user - User object from request.user
+ * @returns Filtered data
+ *
+ * @example
+ * const stats = await calculateComplexStats();
+ * const filtered = filterResponseData(stats, fieldPresets.dashboard, request.user);
+ * return reply.send(filtered);
+ */
+declare function filterResponseData<T extends Record<string, unknown>>(data: T | T[], preset: FieldPreset, user?: UserContext | null): Partial<T> | Partial<T>[];
+/**
+ * Helper to create field presets (module-level)
+ *
+ * Each module should define its own field preset in its own directory.
+ * This keeps modules independent and self-contained.
+ *
+ * @param config - Field configuration
+ * @returns Field preset
+ *
+ * @example
+ * // In modules/gym-plan/gym-plan.fields.ts
+ * export const gymPlanFieldPreset = createFieldPreset({
+ *   public: ['id', 'name', 'price'],
+ *   authenticated: ['features', 'description'],
+ *   admin: ['createdAt', 'updatedAt', 'internalNotes']
+ * });
+ */
+declare function createFieldPreset(config: Partial<FieldPreset>): FieldPreset;
+
+/**
+ * Error Utilities
+ *
+ * HTTP-compatible error creation for repository operations
+ */
+
+/**
+ * Creates an error with HTTP status code
+ *
+ * @param status - HTTP status code
+ * @param message - Error message
+ * @returns Error with status property
+ *
+ * @example
+ * throw createError(404, 'Document not found');
+ * throw createError(400, 'Invalid input');
+ * throw createError(403, 'Access denied');
+ */
+declare function createError(status: number, message: string): HttpError;
+
+/**
+ * In-Memory Cache Adapter
+ *
+ * Simple cache adapter for development and testing.
+ * NOT recommended for production - use Redis or similar.
+ *
+ * @example
+ * ```typescript
+ * import { cachePlugin, createMemoryCache } from '@classytic/mongokit';
+ *
+ * const repo = new Repository(UserModel, [
+ *   cachePlugin({
+ *     adapter: createMemoryCache(),
+ *     ttl: 60,
+ *   })
+ * ]);
+ * ```
+ */
+
+/**
+ * Creates an in-memory cache adapter
+ *
+ * Features:
+ * - Automatic TTL expiration
+ * - Pattern-based clearing (simple glob with *)
+ * - Max entries limit to prevent memory leaks
+ *
+ * @param maxEntries - Maximum cache entries before oldest are evicted (default: 1000)
+ */
+declare function createMemoryCache(maxEntries?: number): CacheAdapter;
+
+export { getMongooseProjection as a, createError as b, createFieldPreset as c, createMemoryCache as d, filterResponseData as f, getFieldsForUser as g };

package/dist/pagination/PaginationEngine.d.ts

@@ -0,0 +1,117 @@
+import { Model } from 'mongoose';
+import { A as AnyDocument, P as PaginationConfig, O as OffsetPaginationOptions, a as OffsetPaginationResult, K as KeysetPaginationOptions, b as KeysetPaginationResult, c as AggregatePaginationOptions, d as AggregatePaginationResult } from '../types-Nxhmi1aI.js';
+
+/**
+ * Pagination Engine
+ *
+ * Production-grade pagination for MongoDB with support for:
+ * - Offset pagination (page-based) - Best for small datasets, random page access
+ * - Keyset pagination (cursor-based) - Best for large datasets, infinite scroll
+ * - Aggregate pagination - Best for complex queries requiring aggregation
+ *
+ * @example
+ * ```typescript
+ * const engine = new PaginationEngine(UserModel, {
+ *   defaultLimit: 20,
+ *   maxLimit: 100,
+ *   useEstimatedCount: true
+ * });
+ *
+ * // Offset pagination
+ * const page1 = await engine.paginate({ page: 1, limit: 20 });
+ *
+ * // Keyset pagination (better for large datasets)
+ * const stream1 = await engine.stream({ sort: { createdAt: -1 }, limit: 20 });
+ * const stream2 = await engine.stream({ sort: { createdAt: -1 }, after: stream1.next });
+ * ```
+ */
+
+/**
+ * Internal pagination config with required values
+ */
+interface ResolvedPaginationConfig {
+    defaultLimit: number;
+    maxLimit: number;
+    maxPage: number;
+    deepPageThreshold: number;
+    cursorVersion: number;
+    useEstimatedCount: boolean;
+}
+/**
+ * Production-grade pagination engine for MongoDB
+ * Supports offset, keyset (cursor), and aggregate pagination
+ */
+declare class PaginationEngine<TDoc = AnyDocument> {
+    readonly Model: Model<TDoc>;
+    readonly config: ResolvedPaginationConfig;
+    /**
+     * Create a new pagination engine
+     *
+     * @param Model - Mongoose model to paginate
+     * @param config - Pagination configuration
+     */
+    constructor(Model: Model<TDoc>, config?: PaginationConfig);
+    /**
+     * 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);
+     */
+    paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc>>;
+    /**
+     * 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
+     * });
+     */
+    stream(options: KeysetPaginationOptions): Promise<KeysetPaginationResult<TDoc>>;
+    /**
+     * 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
+     * });
+     */
+    aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+}
+
+export { PaginationEngine };

package/dist/pagination/PaginationEngine.js

@@ -0,0 +1,369 @@
+import mongoose from 'mongoose';
+
+// src/pagination/utils/cursor.ts
+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/utils/error.ts
+function createError(status, message) {
+  const error = new Error(message);
+  error.status = status;
+  return error;
+}
+
+// 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 }
+    };
+  }
+};
+
+export { PaginationEngine };
+//# sourceMappingURL=PaginationEngine.js.map
+//# sourceMappingURL=PaginationEngine.js.map