@classytic/mongokit 2.0.0 → 3.0.0

package/src/pagination/PaginationEngine.js

@@ -1,348 +0,0 @@
-import { encodeCursor, decodeCursor, validateCursorSort, validateCursorVersion } from './utils/cursor.js';
-import { validateKeysetSort, getPrimaryField } from './utils/sort.js';
-import { buildKeysetFilter } from './utils/filter.js';
-import {
-  validateLimit,
-  validatePage,
-  shouldWarnDeepPagination,
-  calculateSkip,
-  calculateTotalPages
-} from './utils/limits.js';
-import { createError } from '../utils/error.js';
-
-/**
- * @typedef {import('mongoose').Model} Model
- * @typedef {import('mongoose').PopulateOptions} PopulateOptions
- * @typedef {import('mongoose').ClientSession} ClientSession
- */
-
-/**
- * @typedef {Object} PaginationConfig
- * @property {number} [defaultLimit=10] - Default number of documents per page
- * @property {number} [maxLimit=100] - Maximum allowed limit
- * @property {number} [maxPage=10000] - Maximum allowed page number
- * @property {number} [deepPageThreshold=100] - Page number that triggers performance warning
- * @property {number} [cursorVersion=1] - Cursor version for forward compatibility
- * @property {boolean} [useEstimatedCount=false] - Use estimatedDocumentCount for faster counts on large collections
- */
-
-/**
- * @typedef {Object} OffsetPaginationOptions
- * @property {Record<string, any>} [filters={}] - MongoDB query filters
- * @property {Record<string, 1|-1>} [sort] - Sort specification
- * @property {number} [page=1] - Page number (1-indexed)
- * @property {number} [limit] - Number of documents per page
- * @property {string|string[]} [select] - Fields to select
- * @property {string|string[]|PopulateOptions|PopulateOptions[]} [populate] - Fields to populate
- * @property {boolean} [lean=true] - Return plain JavaScript objects
- * @property {ClientSession} [session] - MongoDB session for transactions
- */
-
-/**
- * @typedef {Object} KeysetPaginationOptions
- * @property {Record<string, any>} [filters={}] - MongoDB query filters
- * @property {Record<string, 1|-1>} [sort] - Sort specification (required at runtime)
- * @property {string} [after] - Cursor token for next page
- * @property {number} [limit] - Number of documents per page
- * @property {string|string[]} [select] - Fields to select
- * @property {string|string[]|PopulateOptions|PopulateOptions[]} [populate] - Fields to populate
- * @property {boolean} [lean=true] - Return plain JavaScript objects
- * @property {ClientSession} [session] - MongoDB session for transactions
- */
-
-/**
- * @typedef {Object} AggregatePaginationOptions
- * @property {any[]} [pipeline=[]] - Aggregation pipeline stages
- * @property {number} [page=1] - Page number (1-indexed)
- * @property {number} [limit] - Number of documents per page
- * @property {ClientSession} [session] - MongoDB session for transactions
- */
-
-/**
- * @typedef {Object} OffsetPaginationResult
- * @property {'offset'} method - Pagination method used
- * @property {any[]} docs - Array of documents
- * @property {number} page - Current page number
- * @property {number} limit - Documents per page
- * @property {number} total - Total document count
- * @property {number} pages - Total page count
- * @property {boolean} hasNext - Whether next page exists
- * @property {boolean} hasPrev - Whether previous page exists
- * @property {string} [warning] - Performance warning for deep pagination
- */
-
-/**
- * @typedef {Object} KeysetPaginationResult
- * @property {'keyset'} method - Pagination method used
- * @property {any[]} docs - Array of documents
- * @property {number} limit - Documents per page
- * @property {boolean} hasMore - Whether more documents exist
- * @property {string|null} next - Cursor token for next page
- */
-
-/**
- * @typedef {Object} AggregatePaginationResult
- * @property {'aggregate'} method - Pagination method used
- * @property {any[]} docs - Array of documents
- * @property {number} page - Current page number
- * @property {number} limit - Documents per page
- * @property {number} total - Total document count
- * @property {number} pages - Total page count
- * @property {boolean} hasNext - Whether next page exists
- * @property {boolean} hasPrev - Whether previous page exists
- * @property {string} [warning] - Performance warning for deep pagination
- */
-
-/**
- * Production-grade pagination engine for MongoDB
- * Supports offset, keyset (cursor), and aggregate pagination
- *
- * @example
- * 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 });
- */
-export class PaginationEngine {
-  /**
-   * Create a new pagination engine
-   *
-   * @param {Model} Model - Mongoose model to paginate
-   * @param {PaginationConfig} [config={}] - Pagination configuration
-   */
-  constructor(Model, config = {}) {
-    this.Model = Model;
-    this.config = {
-      defaultLimit: config.defaultLimit || 10,
-      maxLimit: config.maxLimit || 100,
-      maxPage: config.maxPage || 10000,
-      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 {OffsetPaginationOptions} [options={}] - Pagination options
-   * @returns {Promise<OffsetPaginationResult>} 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;
-
-    // Note: estimatedDocumentCount() doesn't support sessions or filters
-    // It reads collection metadata (O(1) instant), not actual documents
-    // Falls back to countDocuments() when filters are present
-    const [docs, total] = await Promise.all([
-      query,
-      useEstimated
-        ? this.Model.estimatedDocumentCount()
-        : this.Model.countDocuments(filters).session(session)
-    ]);
-
-    const totalPages = calculateTotalPages(total, sanitizedLimit);
-    const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold)
-      ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.`
-      : undefined;
-
-    return /** @type {const} */ ({
-      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 {KeysetPaginationOptions} options - Pagination options (sort is required)
-   * @returns {Promise<KeysetPaginationResult>} 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;
-
-    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 /** @type {const} */ ({
-      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 {AggregatePaginationOptions} [options={}] - Aggregation options
-   * @returns {Promise<AggregatePaginationResult>} 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.`
-      : undefined;
-
-    return /** @type {const} */ ({
-      method: 'aggregate',
-      docs,
-      page: sanitizedPage,
-      limit: sanitizedLimit,
-      total,
-      pages: totalPages,
-      hasNext: sanitizedPage < totalPages,
-      hasPrev: sanitizedPage > 1,
-      ...(warning && { warning })
-    });
-  }
-}

package/src/pagination/utils/cursor.js

@@ -1,119 +0,0 @@
-import mongoose from 'mongoose';
-
-/**
- * Encodes document values and sort metadata into a base64 cursor token
- *
- * @param {any} doc - Document to extract cursor values from
- * @param {string} primaryField - Primary sort field name
- * @param {Record<string, 1|-1>} sort - Normalized sort specification
- * @param {number} [version=1] - Cursor version for forward compatibility
- * @returns {string} Base64-encoded cursor token
- */
-export 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');
-}
-
-/**
- * Decodes a cursor token back into document values and sort metadata
- *
- * @param {string} token - Base64-encoded cursor token
- * @returns {{value: any, id: any, sort: Record<string, 1|-1>, version: number}} Decoded cursor data
- * @throws {Error} If token is invalid or malformed
- */
-export 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 (err) {
-    throw new Error('Invalid cursor token');
-  }
-}
-
-/**
- * Validates that cursor sort matches current query sort
- *
- * @param {Record<string, 1|-1>} cursorSort - Sort specification from cursor
- * @param {Record<string, 1|-1>} currentSort - Sort specification from query
- * @throws {Error} If sorts don't match
- */
-export 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');
-  }
-}
-
-/**
- * Validates cursor version matches expected version
- *
- * @param {number} cursorVersion - Version from cursor
- * @param {number} expectedVersion - Expected version from config
- * @throws {Error} If versions don't match
- */
-export function validateCursorVersion(cursorVersion, expectedVersion) {
-  if (cursorVersion !== expectedVersion) {
-    throw new Error(`Cursor version ${cursorVersion} does not match expected version ${expectedVersion}`);
-  }
-}
-
-/**
- * Serializes a value for cursor storage
- * @param {any} value - Value to serialize
- * @returns {string|number|boolean} Serialized value
- */
-function serializeValue(value) {
-  if (value instanceof Date) return value.toISOString();
-  if (value instanceof mongoose.Types.ObjectId) return value.toString();
-  return value;
-}
-
-/**
- * Gets the type identifier for a value
- * @param {any} value - Value to identify
- * @returns {'date'|'objectid'|'boolean'|'number'|'string'|'unknown'} Type identifier
- */
-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';
-}
-
-/**
- * Rehydrates a serialized value back to its original type
- * @param {any} serialized - Serialized value
- * @param {string} type - Type identifier
- * @returns {any} Rehydrated value
- */
-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;
-  }
-}

package/src/pagination/utils/filter.js

@@ -1,42 +0,0 @@
-/**
- * Builds MongoDB filter for keyset pagination
- * Creates compound $or condition for proper cursor-based filtering
- *
- * @param {Record<string, any>} baseFilters - Existing query filters
- * @param {Record<string, 1|-1>} sort - Normalized sort specification
- * @param {any} cursorValue - Primary field value from cursor
- * @param {any} cursorId - _id value from cursor
- * @returns {Record<string, any>} MongoDB filter with keyset condition
- *
- * @example
- * buildKeysetFilter(
- *   { status: 'active' },
- *   { createdAt: -1, _id: -1 },
- *   new Date('2024-01-01'),
- *   new ObjectId('...')
- * )
- * // Returns:
- * // {
- * //   status: 'active',
- * //   $or: [
- * //     { createdAt: { $lt: Date('2024-01-01') } },
- * //     { createdAt: Date('2024-01-01'), _id: { $lt: ObjectId('...') } }
- * //   ]
- * // }
- */
-export 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 }
-      }
-    ]
-  };
-}

package/src/pagination/utils/limits.js

@@ -1,82 +0,0 @@
-/**
- * @typedef {Object} PaginationConfig
- * @property {number} defaultLimit - Default limit value
- * @property {number} maxLimit - Maximum allowed limit
- * @property {number} maxPage - Maximum allowed page number
- */
-
-/**
- * Validates and sanitizes limit value
- * Parses strings to numbers and prevents NaN bugs
- *
- * @param {number|string} limit - Requested limit
- * @param {PaginationConfig} config - Pagination configuration
- * @returns {number} Sanitized limit between 1 and maxLimit
- */
-export 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);
-}
-
-/**
- * Validates and sanitizes page number
- * Parses strings to numbers and prevents NaN bugs
- *
- * @param {number|string} page - Requested page (1-indexed)
- * @param {PaginationConfig} config - Pagination configuration
- * @returns {number} Sanitized page number >= 1
- * @throws {Error} If page exceeds maxPage
- */
-export 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) {
-    throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage}`);
-  }
-
-  return sanitized;
-}
-
-/**
- * Checks if page number should trigger deep pagination warning
- *
- * @param {number} page - Current page number
- * @param {number} threshold - Warning threshold
- * @returns {boolean} True if warning should be shown
- */
-export function shouldWarnDeepPagination(page, threshold) {
-  return page > threshold;
-}
-
-/**
- * Calculates number of documents to skip for offset pagination
- *
- * @param {number} page - Page number (1-indexed)
- * @param {number} limit - Documents per page
- * @returns {number} Number of documents to skip
- */
-export function calculateSkip(page, limit) {
-  return (page - 1) * limit;
-}
-
-/**
- * Calculates total number of pages
- *
- * @param {number} total - Total document count
- * @param {number} limit - Documents per page
- * @returns {number} Total number of pages
- */
-export function calculateTotalPages(total, limit) {
-  return Math.ceil(total / limit);
-}

package/src/pagination/utils/sort.js

@@ -1,101 +0,0 @@
-/**
- * Normalizes sort object to ensure stable key order
- * Primary fields first, _id last (not alphabetical)
- *
- * @param {Record<string, 1|-1>} sort - Sort specification
- * @returns {Record<string, 1|-1>} Normalized sort with stable key order
- */
-export function normalizeSort(sort) {
-  /** @type {Record<string, 1|-1>} */
-  const normalized = {};
-
-  Object.keys(sort).forEach(key => {
-    if (key !== '_id') normalized[key] = sort[key];
-  });
-
-  if (sort._id !== undefined) {
-    normalized._id = sort._id;
-  }
-
-  return normalized;
-}
-
-/**
- * Validates and normalizes sort for keyset pagination
- * Auto-adds _id tie-breaker if needed
- * Ensures _id direction matches primary field
- *
- * @param {Record<string, 1|-1>} sort - Sort specification
- * @returns {Record<string, 1|-1>} Validated and normalized sort
- * @throws {Error} If sort is invalid for keyset pagination
- */
-export 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');
-}
-
-/**
- * Inverts sort directions (1 becomes -1, -1 becomes 1)
- *
- * @param {Record<string, 1|-1>} sort - Sort specification
- * @returns {Record<string, 1|-1>} Inverted sort
- */
-export function invertSort(sort) {
-  /** @type {Record<string, 1|-1>} */
-  const inverted = {};
-
-  Object.keys(sort).forEach(key => {
-    inverted[key] = sort[key] === 1 ? -1 : 1;
-  });
-
-  return inverted;
-}
-
-/**
- * Extracts primary sort field (first non-_id field)
- *
- * @param {Record<string, 1|-1>} sort - Sort specification
- * @returns {string} Primary field name
- */
-export function getPrimaryField(sort) {
-  const keys = Object.keys(sort);
-  return keys.find(k => k !== '_id') || '_id';
-}
-
-/**
- * Gets sort direction for a specific field
- *
- * @param {Record<string, 1|-1>} sort - Sort specification
- * @param {string} field - Field name
- * @returns {1|-1|undefined} Sort direction
- */
-export function getDirection(sort, field) {
-  return sort[field];
-}