@classytic/mongokit 1.0.2 → 2.0.0

package/src/actions/delete.js

@@ -1,88 +1,88 @@
-/**
- * Delete Actions
- * Pure functions for document deletion
- */
-
-import createError from 'http-errors';
-
-/**
- * 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' };
-}
-
+/**
+ * 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 +1,11 @@
-/**
- * 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';
-
+/**
+ * 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,86 +1,135 @@
-/**
- * Read Actions
- * Pure functions for document retrieval
- */
-
-import createError from 'http-errors';
-
-/**
- * Get by ID
- */
-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 by query
- */
-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 all with pagination
- */
-export async function getAll(Model, queryParams, options = {}) {
-  const {
-    pagination = { page: 1, limit: 10 },
-    search,
-    sort = '-createdAt',
-    filters = {},
-  } = queryParams;
-
-  let query = {};
-  
-  if (search) {
-    query.$text = { $search: search };
-  }
-  
-  if (filters) {
-    query = { ...query, ...parseFilters(filters) };
-  }
-
-  const paginateOptions = {
-    page: parseInt(pagination.page, 10),
-    limit: parseInt(pagination.limit, 10),
-    sort: parseSort(sort),
-    populate: parsePopulate(options.populate),
-    select: options.select,
-    lean: options.lean !== false,
-    session: options.session,
-  };
-
-  return Model.paginate(query, paginateOptions);
-}
-
-/**
- * Get or create
- */
-export async function getOrCreate(Model, query, createData, options = {}) {
+/**
+ * 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 },
@@ -93,64 +142,47 @@ export async function getOrCreate(Model, query, createData, options = {}) {
     }
   );
 }
-
-/**
- * Count documents
- */
-export async function count(Model, query = {}, options = {}) {
-  return Model.countDocuments(query).session(options.session);
-}
-
-/**
- * Check existence
- */
-export async function exists(Model, query, options = {}) {
-  return Model.exists(query).session(options.session);
-}
-
-// Utilities
-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];
-}
-
-function parseSort(sort) {
-  if (!sort) return { createdAt: -1 };
-  const sortOrder = sort.startsWith('-') ? -1 : 1;
-  const sortField = sort.startsWith('-') ? sort.substring(1) : sort;
-  return { [sortField]: sortOrder };
-}
-
-function parseFilters(filters) {
-  const parsed = {};
-  for (const [key, value] of Object.entries(filters)) {
-    parsed[key] = parseFilterValue(value);
-  }
-  return parsed;
-}
-
-function parseFilterValue(value) {
-  if (typeof value === 'string') return value;
-  
-  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-    const processed = {};
-    for (const [operator, operatorValue] of Object.entries(value)) {
-      if (operator === 'contains' || operator === 'like') {
-        processed.$regex = operatorValue;
-        processed.$options = 'i';
-      } else {
-        processed[operator.startsWith('$') ? operator : `$${operator}`] = operatorValue;
-      }
-    }
-    return processed;
-  }
-  
-  return value;
-}
-
+
+/**
+ * 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];
+}
+