@classytic/mongokit 2.0.0 → 2.1.0

package/src/actions/aggregate.js

@@ -1,266 +0,0 @@
-/**
- * Aggregate Actions
- * MongoDB aggregation pipeline operations
- */
-
-/**
- * @typedef {import('mongoose').Model} Model
- * @typedef {import('mongoose').ClientSession} ClientSession
- */
-
-/**
- * Execute aggregation pipeline
- *
- * @param {Model} Model - Mongoose model
- * @param {any[]} pipeline - Aggregation pipeline stages
- * @param {Object} [options={}] - Aggregation options
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<any[]>} Aggregation results
- */
-export async function aggregate(Model, pipeline, options = {}) {
-  const aggregation = Model.aggregate(pipeline);
-
-  if (options.session) {
-    aggregation.session(options.session);
-  }
-
-  return aggregation.exec();
-}
-
-/**
- * Aggregate with pagination using native MongoDB $facet
- * WARNING: $facet results must be <16MB. For larger results (limit >1000),
- * consider using Repository.aggregatePaginate() or splitting into separate queries.
- *
- * @param {Model} Model - Mongoose model
- * @param {any[]} pipeline - Aggregation pipeline stages (before pagination)
- * @param {Object} [options={}] - Pagination options
- * @param {number} [options.page=1] - Page number (1-indexed)
- * @param {number} [options.limit=10] - Documents per page
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<{docs: any[], total: number, page: number, limit: number, pages: number, hasNext: boolean, hasPrev: boolean}>} Paginated results
- *
- * @example
- * const result = await aggregatePaginate(UserModel, [
- *   { $match: { status: 'active' } },
- *   { $group: { _id: '$category', count: { $sum: 1 } } }
- * ], { page: 1, limit: 20 });
- */
-export 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;
-
-  // 16MB MongoDB document size limit safety check
-  const SAFE_LIMIT = 1000;
-  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
-  };
-}
-
-/**
- * Group documents by field value
- *
- * @param {Model} Model - Mongoose model
- * @param {string} field - Field name to group by
- * @param {Object} [options={}] - Options
- * @param {number} [options.limit] - Maximum groups to return
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<Array<{_id: any, count: number}>>} Grouped results
- */
-export async function groupBy(Model, field, options = {}) {
-  const pipeline = [
-    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-    { $sort: { count: -1 } },
-  ];
-
-  if (options.limit) {
-    pipeline.push(/** @type {any} */({ $limit: options.limit }));
-  }
-
-  return aggregate(Model, pipeline, options);
-}
-
-/**
- * Count by field values
- */
-export 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);
-}
-
-/**
- * Lookup (join) with another collection
- */
-export async function lookup(Model, {
-  from,
-  localField,
-  foreignField,
-  as,
-  pipeline = [],
-  query = {},
-  options = {}
-}) {
-  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);
-}
-
-/**
- * Unwind array field
- */
-export async function unwind(Model, field, options = {}) {
-  const pipeline = [
-    {
-      $unwind: {
-        path: `$${field}`,
-        preserveNullAndEmptyArrays: options.preserveEmpty !== false,
-      },
-    },
-  ];
-
-  return aggregate(Model, pipeline, options);
-}
-
-/**
- * Facet search (multiple aggregations in one query)
- */
-export async function facet(Model, facets, options = {}) {
-  const pipeline = [{ $facet: facets }];
-
-  return aggregate(Model, pipeline, options);
-}
-
-/**
- * Get distinct values
- */
-export async function distinct(Model, field, query = {}, options = {}) {
-  return Model.distinct(field, query).session(options.session);
-}
-
-/**
- * Calculate sum
- */
-export 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;
-}
-
-/**
- * Calculate average
- */
-export 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;
-}
-
-/**
- * Min/Max
- */
-export 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 };
-}
-

package/src/actions/create.js

@@ -1,59 +0,0 @@
-/**
- * Create Actions
- * Pure functions for document creation
- */
-
-/**
- * Create single document
- */
-export async function create(Model, data, options = {}) {
-  const document = new Model(data);
-  await document.save({ session: options.session });
-  return document;
-}
-
-/**
- * Create multiple documents
- */
-export async function createMany(Model, dataArray, options = {}) {
-  return Model.insertMany(dataArray, {
-    session: options.session,
-    ordered: options.ordered !== false,
-  });
-}
-
-/**
- * Create with defaults (useful for initialization)
- */
-export async function createDefault(Model, overrides = {}, options = {}) {
-  const defaults = {};
-  
-  // Extract defaults from schema
-  Model.schema.eachPath((path, schemaType) => {
-    if (schemaType.options.default !== undefined && path !== '_id') {
-      defaults[path] = typeof schemaType.options.default === 'function'
-        ? schemaType.options.default()
-        : schemaType.options.default;
-    }
-  });
-  
-  return create(Model, { ...defaults, ...overrides }, options);
-}
-
-/**
- * Upsert (create or update)
- */
-export async function upsert(Model, query, data, options = {}) {
-  return Model.findOneAndUpdate(
-    query,
-    { $setOnInsert: data },
-    {
-      upsert: true,
-      new: true,
-      runValidators: true,
-      session: options.session,
-      ...(options.updatePipeline !== undefined ? { updatePipeline: options.updatePipeline } : {}),
-    }
-  );
-}
-

package/src/actions/delete.js

@@ -1,88 +0,0 @@
-/**
- * Delete Actions
- * Pure functions for document deletion
- */
-
-import { createError } from '../utils/error.js';
-
-/**
- * Delete by ID
- */
-export async function deleteById(Model, id, options = {}) {
-  const document = await Model.findByIdAndDelete(id).session(options.session);
-
-  if (!document) {
-    throw createError(404, 'Document not found');
-  }
-
-  return { success: true, message: 'Deleted successfully' };
-}
-
-/**
- * Delete many documents
- */
-export async function deleteMany(Model, query, options = {}) {
-  const result = await Model.deleteMany(query).session(options.session);
-
-  return {
-    success: true,
-    count: result.deletedCount,
-    message: 'Deleted successfully',
-  };
-}
-
-/**
- * Delete by query
- */
-export async function deleteByQuery(Model, query, options = {}) {
-  const document = await Model.findOneAndDelete(query).session(options.session);
-
-  if (!document && options.throwOnNotFound !== false) {
-    throw createError(404, 'Document not found');
-  }
-
-  return { success: true, message: 'Deleted successfully' };
-}
-
-/**
- * Soft delete (set deleted flag)
- */
-export async function softDelete(Model, id, options = {}) {
-  const document = await Model.findByIdAndUpdate(
-    id,
-    {
-      deleted: true,
-      deletedAt: 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' };
-}
-
-/**
- * Restore soft deleted document
- */
-export 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' };
-}
-

package/src/actions/index.js

@@ -1,11 +0,0 @@
-/**
- * Repository Actions
- * Modular, composable data access operations
- */
-
-export * as create from './create.js';
-export * as read from './read.js';
-export * as update from './update.js';
-export * as deleteActions from './delete.js';
-export * as aggregate from './aggregate.js';
-

package/src/actions/read.js

@@ -1,188 +0,0 @@
-/**
- * Read Actions
- * Pure functions for document retrieval
- */
-
-import { createError } from '../utils/error.js';
-
-/**
- * @typedef {import('mongoose').Model} Model
- * @typedef {import('mongoose').PopulateOptions} PopulateOptions
- * @typedef {import('mongoose').ClientSession} ClientSession
- */
-
-/**
- * Get document by ID
- *
- * @param {Model} Model - Mongoose model
- * @param {string} id - Document ID
- * @param {Object} [options={}] - Query options
- * @param {string|string[]} [options.select] - Fields to select
- * @param {string|string[]|PopulateOptions|PopulateOptions[]} [options.populate] - Fields to populate
- * @param {boolean} [options.lean] - Return plain JavaScript object
- * @param {ClientSession} [options.session] - MongoDB session
- * @param {boolean} [options.throwOnNotFound=true] - Throw error if not found
- * @returns {Promise<any>} Document or null
- * @throws {Error} If document not found and throwOnNotFound is true
- */
-export async function getById(Model, id, options = {}) {
-  const 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;
-}
-
-/**
- * Get document by query
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} query - MongoDB query
- * @param {Object} [options={}] - Query options
- * @param {string|string[]} [options.select] - Fields to select
- * @param {string|string[]|PopulateOptions|PopulateOptions[]} [options.populate] - Fields to populate
- * @param {boolean} [options.lean] - Return plain JavaScript object
- * @param {ClientSession} [options.session] - MongoDB session
- * @param {boolean} [options.throwOnNotFound=true] - Throw error if not found
- * @returns {Promise<any>} Document or null
- * @throws {Error} If document not found and throwOnNotFound is true
- */
-export 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;
-}
-
-/**
- * Get document by query without throwing (returns null if not found)
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} query - MongoDB query
- * @param {Object} [options={}] - Query options
- * @param {string|string[]} [options.select] - Fields to select
- * @param {string|string[]|PopulateOptions|PopulateOptions[]} [options.populate] - Fields to populate
- * @param {boolean} [options.lean] - Return plain JavaScript object
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<any|null>} Document or null
- */
-export async function tryGetByQuery(Model, query, options = {}) {
-  return getByQuery(Model, query, { ...options, throwOnNotFound: false });
-}
-
-/**
- * Get all documents (basic query without pagination)
- * For pagination, use Repository.paginate() or Repository.stream()
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} [query={}] - MongoDB query
- * @param {Object} [options={}] - Query options
- * @param {string|string[]} [options.select] - Fields to select
- * @param {string|string[]|PopulateOptions|PopulateOptions[]} [options.populate] - Fields to populate
- * @param {Record<string, 1|-1>} [options.sort] - Sort specification
- * @param {number} [options.limit] - Maximum documents to return
- * @param {number} [options.skip] - Documents to skip
- * @param {boolean} [options.lean=true] - Return plain JavaScript objects
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<any[]>} Array of documents
- */
-export 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();
-}
-
-/**
- * Get or create document (upsert)
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} query - Query to find document
- * @param {Record<string, any>} createData - Data to insert if not found
- * @param {Object} [options={}] - Query options
- * @param {ClientSession} [options.session] - MongoDB session
- * @param {boolean} [options.updatePipeline] - Use update pipeline
- * @returns {Promise<any>} Created or found document
- */
-export async function getOrCreate(Model, query, createData, options = {}) {
-  return Model.findOneAndUpdate(
-    query,
-    { $setOnInsert: createData },
-    {
-      upsert: true,
-      new: true,
-      runValidators: true,
-      session: options.session,
-      ...(options.updatePipeline !== undefined ? { updatePipeline: options.updatePipeline } : {}),
-    }
-  );
-}
-
-/**
- * Count documents matching query
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} [query={}] - MongoDB query
- * @param {Object} [options={}] - Query options
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<number>} Document count
- */
-export async function count(Model, query = {}, options = {}) {
-  return Model.countDocuments(query).session(options.session);
-}
-
-/**
- * Check if document exists
- *
- * @param {Model} Model - Mongoose model
- * @param {Record<string, any>} query - MongoDB query
- * @param {Object} [options={}] - Query options
- * @param {ClientSession} [options.session] - MongoDB session
- * @returns {Promise<{_id: any} | null>} Document ID if exists, null otherwise
- */
-export async function exists(Model, query, options = {}) {
-  return Model.exists(query).session(options.session);
-}
-
-/**
- * Parses populate parameter into Mongoose-compatible format
- *
- * @param {string|string[]|PopulateOptions|PopulateOptions[]} populate - Populate specification
- * @returns {(string|PopulateOptions)[]} Normalized populate array
- */
-function parsePopulate(populate) {
-  if (!populate) return [];
-  if (typeof populate === 'string') {
-    return populate.split(',').map(/** @param {string} p */ (p) => p.trim());
-  }
-  if (Array.isArray(populate)) {
-    return populate.map(/** @param {string|PopulateOptions} p */ (p) => typeof p === 'string' ? p.trim() : p);
-  }
-  return [populate];
-}
-