@classytic/mongokit 1.0.0

package/src/plugins/batch-operations.plugin.js

@@ -0,0 +1,66 @@
+/**
+ * Batch Operations Plugin
+ * Adds bulk update/delete operations with proper event emission
+ */
+
+export const batchOperationsPlugin = () => ({
+  name: 'batch-operations',
+
+  apply(repo) {
+    if (!repo.registerMethod) {
+      throw new Error('batchOperationsPlugin requires methodRegistryPlugin');
+    }
+
+    /**
+     * Update multiple documents
+     * @param {Object} query - MongoDB query to match documents
+     * @param {Object} data - Update data
+     * @param {Object} options - Additional options (session, context)
+     * @returns {Promise<Object>} MongoDB update result
+     */
+    repo.registerMethod('updateMany', async function (query, data, options = {}) {
+      const context = await this._buildContext('updateMany', { query, data, options });
+
+      try {
+        this.emit('before:updateMany', context);
+
+        const result = await this.Model.updateMany(query, data, {
+          runValidators: true,
+          session: options.session,
+        }).exec();
+
+        this.emit('after:updateMany', { context, result });
+        return result;
+      } catch (error) {
+        this.emit('error:updateMany', { context, error });
+        throw this._handleError(error);
+      }
+    });
+
+    /**
+     * Delete multiple documents
+     * @param {Object} query - MongoDB query to match documents
+     * @param {Object} options - Additional options (session, context)
+     * @returns {Promise<Object>} MongoDB delete result
+     */
+    repo.registerMethod('deleteMany', async function (query, options = {}) {
+      const context = await this._buildContext('deleteMany', { query, options });
+
+      try {
+        this.emit('before:deleteMany', context);
+
+        const result = await this.Model.deleteMany(query, {
+          session: options.session,
+        }).exec();
+
+        this.emit('after:deleteMany', { context, result });
+        return result;
+      } catch (error) {
+        this.emit('error:deleteMany', { context, error });
+        throw this._handleError(error);
+      }
+    });
+  }
+});
+
+export default batchOperationsPlugin;

package/src/plugins/field-filter.plugin.js

@@ -0,0 +1,27 @@
+import { getFieldsForUser } from '../utils/field-selection.js';
+
+export const fieldFilterPlugin = (fieldPreset) => ({
+  name: 'fieldFilter',
+
+  apply(repo) {
+    const applyFieldFiltering = (context) => {
+      if (!fieldPreset) return;
+
+      const user = context.context?.user || context.user;
+      const fields = getFieldsForUser(user, fieldPreset);
+      const presetSelect = fields.join(' ');
+
+      if (context.select) {
+        context.select = `${presetSelect} ${context.select}`;
+      } else {
+        context.select = presetSelect;
+      }
+    };
+
+    repo.on('before:getAll', applyFieldFiltering);
+    repo.on('before:getById', applyFieldFiltering);
+    repo.on('before:getByQuery', applyFieldFiltering);
+  },
+});
+
+export default fieldFilterPlugin;

package/src/plugins/index.js

@@ -0,0 +1,19 @@
+// Core plugins
+export { fieldFilterPlugin } from './field-filter.plugin.js';
+export { timestampPlugin } from './timestamp.plugin.js';
+export { auditLogPlugin } from './audit-log.plugin.js';
+export { softDeletePlugin } from './soft-delete.plugin.js';
+export { methodRegistryPlugin } from './method-registry.plugin.js';
+export {
+  validationChainPlugin,
+  blockIf,
+  requireField,
+  autoInject,
+  immutableField,
+  uniqueField,
+} from './validation-chain.plugin.js';
+export { mongoOperationsPlugin } from './mongo-operations.plugin.js';
+export { batchOperationsPlugin } from './batch-operations.plugin.js';
+export { aggregateHelpersPlugin } from './aggregate-helpers.plugin.js';
+export { subdocumentPlugin } from './subdocument.plugin.js';
+

package/src/plugins/method-registry.plugin.js

@@ -0,0 +1,140 @@
+/**
+ * Method Registry Plugin
+ *
+ * Enables plugins to dynamically add methods to repository instances.
+ * Foundation for extensibility - allows other plugins to extend repositories
+ * with custom methods while maintaining type safety and proper binding.
+ *
+ * **Pattern:** Inspired by Stripe's extension system
+ * **Philosophy:** Repositories start minimal, plugins add capabilities
+ *
+ * @module common/repositories/plugins/method-registry
+ *
+ * @example Basic Usage
+ * ```js
+ * import { Repository } from '../Repository.js';
+ * import { methodRegistryPlugin } from './method-registry.plugin.js';
+ *
+ * class UserRepository extends Repository {
+ *   constructor() {
+ *     super(User, [methodRegistryPlugin()]);
+ *
+ *     // Now you can register custom methods
+ *     this.registerMethod('findActive', async function() {
+ *       return this.getAll({ filters: { status: 'active' } });
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Plugin Using Method Registry
+ * ```js
+ * // Other plugins can use registerMethod to add functionality
+ * export const mongoOperationsPlugin = () => ({
+ *   name: 'mongo-operations',
+ *   apply(repo) {
+ *     repo.registerMethod('increment', async function(id, field, value = 1, options = {}) {
+ *       return this.update(id, { $inc: { [field]: value } }, options);
+ *     });
+ *   }
+ * });
+ * ```
+ */
+
+/**
+ * Method Registry Plugin
+ *
+ * Adds `registerMethod()` to repository instance, allowing dynamic method addition.
+ *
+ * @returns {Object} Plugin configuration
+ */
+export const methodRegistryPlugin = () => ({
+  name: 'method-registry',
+
+  apply(repo) {
+    /**
+     * Register a new method on the repository instance
+     *
+     * **Rules:**
+     * - Method name must not conflict with existing methods
+     * - Method is automatically bound to repository instance
+     * - Method has access to all repository methods via `this`
+     * - Async methods are recommended for consistency
+     *
+     * @param {string} name - Method name
+     * @param {Function} fn - Method implementation (will be bound to repo)
+     * @throws {Error} If method name already exists
+     *
+     * @example
+     * repo.registerMethod('findByEmail', async function(email) {
+     *   return this.getByQuery({ email }, { lean: true });
+     * });
+     *
+     * @example With options
+     * repo.registerMethod('incrementViews', async function(id, amount = 1) {
+     *   return this.update(id, { $inc: { views: amount } });
+     * });
+     */
+    repo.registerMethod = function (name, fn) {
+      // Check for naming conflicts
+      if (repo[name]) {
+        throw new Error(
+          `Cannot register method '${name}': Method already exists on repository. ` +
+          `Choose a different name or use a plugin that doesn't conflict.`
+        );
+      }
+
+      // Validate method name
+      if (!name || typeof name !== 'string') {
+        throw new Error('Method name must be a non-empty string');
+      }
+
+      // Validate function
+      if (typeof fn !== 'function') {
+        throw new Error(`Method '${name}' must be a function`);
+      }
+
+      // Bind function to repository instance
+      repo[name] = fn.bind(repo);
+
+      // Emit event for plugin system awareness
+      repo.emit('method:registered', { name, fn });
+    };
+
+    /**
+     * Check if a method is registered
+     *
+     * @param {string} name - Method name to check
+     * @returns {boolean} True if method exists
+     *
+     * @example
+     * if (repo.hasMethod('increment')) {
+     *   await repo.increment(id, 'count', 1);
+     * }
+     */
+    repo.hasMethod = function (name) {
+      return typeof repo[name] === 'function';
+    };
+
+    /**
+     * Get list of all dynamically registered methods
+     *
+     * @returns {Array<string>} Array of method names
+     *
+     * @example
+     * const methods = repo.getRegisteredMethods();
+     * console.log('Available methods:', methods);
+     */
+    repo.getRegisteredMethods = function () {
+      const registeredMethods = [];
+
+      repo.on('method:registered', ({ name }) => {
+        registeredMethods.push(name);
+      });
+
+      return registeredMethods;
+    };
+  }
+});
+
+export default methodRegistryPlugin;

package/src/plugins/mongo-operations.plugin.js

@@ -0,0 +1,313 @@
+/**
+ * MongoDB Operations Plugin
+ *
+ * Adds MongoDB-specific operations to repositories.
+ * Requires method-registry.plugin.js to be loaded first.
+ *
+ * **Operations Added:**
+ * - upsert(query, data, options) - Update or insert
+ * - increment(id, field, value, options) - Atomic increment
+ * - decrement(id, field, value, options) - Atomic decrement
+ * - pushToArray(id, field, value, options) - Add to array
+ * - pullFromArray(id, field, value, options) - Remove from array
+ * - addToSet(id, field, value, options) - Add unique to array
+ *
+ * **Pattern:** Opt-in MongoDB features
+ * **Philosophy:** Keep core pure, add database-specific features via plugins
+ *
+ * @module common/repositories/plugins/mongo-operations
+ * @requires method-registry.plugin
+ *
+ * @example Basic Usage
+ * ```js
+ * import { Repository } from '../Repository.js';
+ * import { method
+
+RegistryPlugin } from './method-registry.plugin.js';
+ * import { mongoOperationsPlugin } from './mongo-operations.plugin.js';
+ *
+ * class ProductRepository extends Repository {
+ *   constructor() {
+ *     super(Product, [
+ *       methodRegistryPlugin(),
+ *       mongoOperationsPlugin(),
+ *     ]);
+ *   }
+ * }
+ *
+ * // Now you can use MongoDB operations
+ * await productRepo.increment(productId, 'views', 1);
+ * await productRepo.pushToArray(productId, 'tags', 'featured');
+ * ```
+ */
+
+import createError from 'http-errors';
+import * as createActions from '../actions/create.js';
+
+/**
+ * MongoDB Operations Plugin
+ *
+ * Adds common MongoDB atomic operations to repository.
+ * All operations use repository's update method internally (events/plugins run).
+ *
+ * @returns {Object} Plugin configuration
+ */
+export const mongoOperationsPlugin = () => ({
+  name: 'mongo-operations',
+
+  apply(repo) {
+    // Check if method-registry is available
+    if (!repo.registerMethod) {
+      throw new Error(
+        'mongoOperationsPlugin requires methodRegistryPlugin. ' +
+        'Add methodRegistryPlugin() before mongoOperationsPlugin() in plugins array.'
+      );
+    }
+
+    /**
+     * Update existing document or insert new one
+     *
+     * @param {Object} query - Query to find existing document
+     * @param {Object} data - Data to insert/update
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Upserted document
+     *
+     * @example
+     * // Create or update user session
+     * await repo.upsert(
+     *   { userId, deviceId },
+     *   { lastActive: new Date(), ipAddress },
+     *   { lean: true }
+     * );
+     */
+    repo.registerMethod('upsert', async function (query, data, options = {}) {
+      return createActions.upsert(this.Model, query, data, options);
+    });
+
+    // Helper: Validate and perform numeric operation
+    const validateAndUpdateNumeric = function (id, field, value, operator, operationName, options) {
+      if (typeof value !== 'number') {
+        throw createError(400, `${operationName} value must be a number`);
+      }
+      return this.update(id, { [operator]: { [field]: value } }, options);
+    };
+
+    /**
+     * Atomically increment numeric field
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name to increment
+     * @param {number} [value=1] - Amount to increment by
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Increment product views
+     * await productRepo.increment(productId, 'views', 1);
+     *
+     * @example
+     * // Increment multiple times
+     * await productRepo.increment(userId, 'points', 100);
+     */
+    repo.registerMethod('increment', async function (id, field, value = 1, options = {}) {
+      return validateAndUpdateNumeric.call(this, id, field, value, '$inc', 'Increment', options);
+    });
+
+    /**
+     * Atomically decrement numeric field
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name to decrement
+     * @param {number} [value=1] - Amount to decrement by
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Decrement product stock
+     * await productRepo.decrement(productId, 'stock', 1);
+     */
+    repo.registerMethod('decrement', async function (id, field, value = 1, options = {}) {
+      return validateAndUpdateNumeric.call(this, id, field, -value, '$inc', 'Decrement', options);
+    });
+
+    // Helper: Generic MongoDB operator update
+    const applyOperator = function (id, field, value, operator, options) {
+      return this.update(id, { [operator]: { [field]: value } }, options);
+    };
+
+    /**
+     * Push value to array field
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Array field name
+     * @param {*} value - Value to push
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Add tag to product
+     * await productRepo.pushToArray(productId, 'tags', 'new-arrival');
+     *
+     * @example
+     * // Add multiple items
+     * await productRepo.pushToArray(userId, 'notifications', {
+     *   message: 'Welcome!',
+     *   createdAt: new Date()
+     * });
+     */
+    repo.registerMethod('pushToArray', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$push', options);
+    });
+
+    /**
+     * Remove value from array field
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Array field name
+     * @param {*} value - Value to remove (can be query object)
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Remove tag from product
+     * await productRepo.pullFromArray(productId, 'tags', 'old-tag');
+     *
+     * @example
+     * // Remove by query
+     * await productRepo.pullFromArray(userId, 'notifications', { read: true });
+     */
+    repo.registerMethod('pullFromArray', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$pull', options);
+    });
+
+    /**
+     * Add value to array only if not already present (unique)
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Array field name
+     * @param {*} value - Value to add
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Add unique follower
+     * await userRepo.addToSet(userId, 'followers', followerId);
+     */
+    repo.registerMethod('addToSet', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$addToSet', options);
+    });
+
+    /**
+     * Set field value (alias for update with $set)
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name
+     * @param {*} value - New value
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Set last login
+     * await userRepo.setField(userId, 'lastLogin', new Date());
+     */
+    repo.registerMethod('setField', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$set', options);
+    });
+
+    /**
+     * Unset (remove) field from document
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string|string[]} fields - Field name(s) to remove
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Remove temporary field
+     * await userRepo.unsetField(userId, 'tempToken');
+     *
+     * @example
+     * // Remove multiple fields
+     * await userRepo.unsetField(userId, ['tempToken', 'tempData']);
+     */
+    repo.registerMethod('unsetField', async function (id, fields, options = {}) {
+      const fieldArray = Array.isArray(fields) ? fields : [fields];
+      const unsetObj = fieldArray.reduce((acc, field) => {
+        acc[field] = '';
+        return acc;
+      }, {});
+
+      return this.update(id, { $unset: unsetObj }, options);
+    });
+
+    /**
+     * Rename field in document
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} oldName - Current field name
+     * @param {string} newName - New field name
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Rename field
+     * await userRepo.renameField(userId, 'username', 'displayName');
+     */
+    repo.registerMethod('renameField', async function (id, oldName, newName, options = {}) {
+      return this.update(id, { $rename: { [oldName]: newName } }, options);
+    });
+
+    /**
+     * Multiply numeric field by value
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name
+     * @param {number} multiplier - Multiplier value
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Double points
+     * await userRepo.multiplyField(userId, 'points', 2);
+     */
+    repo.registerMethod('multiplyField', async function (id, field, multiplier, options = {}) {
+      return validateAndUpdateNumeric.call(this, id, field, multiplier, '$mul', 'Multiplier', options);
+    });
+
+    /**
+     * Set field to minimum value (only if current value is greater)
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name
+     * @param {number} value - Minimum value
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Set minimum price
+     * await productRepo.setMin(productId, 'price', 999);
+     */
+    repo.registerMethod('setMin', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$min', options);
+    });
+
+    /**
+     * Set field to maximum value (only if current value is less)
+     *
+     * @param {string|ObjectId} id - Document ID
+     * @param {string} field - Field name
+     * @param {number} value - Maximum value
+     * @param {Object} [options={}] - Options
+     * @returns {Promise<Object>} Updated document
+     *
+     * @example
+     * // Set maximum score
+     * await gameRepo.setMax(gameId, 'highScore', newScore);
+     */
+    repo.registerMethod('setMax', async function (id, field, value, options = {}) {
+      return applyOperator.call(this, id, field, value, '$max', options);
+    });
+  }
+});
+
+export default mongoOperationsPlugin;

package/src/plugins/soft-delete.plugin.js

@@ -0,0 +1,46 @@
+export const softDeletePlugin = (options = {}) => ({
+  name: 'softDelete',
+
+  apply(repo) {
+    const deletedField = options.deletedField || 'deletedAt';
+    const deletedByField = options.deletedByField || 'deletedBy';
+
+    repo.on('before:delete', async (context) => {
+      if (options.soft !== false) {
+        const updateData = {
+          [deletedField]: new Date(),
+        };
+
+        if (context.user) {
+          updateData[deletedByField] = context.user._id || context.user.id;
+        }
+
+        await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
+
+        context.softDeleted = true;
+      }
+    });
+
+    repo.on('before:getAll', (context) => {
+      if (!context.includeDeleted && options.soft !== false) {
+        const queryParams = context.queryParams || {};
+        queryParams.filters = {
+          ...(queryParams.filters || {}),
+          [deletedField]: { $exists: false },
+        };
+        context.queryParams = queryParams;
+      }
+    });
+
+    repo.on('before:getById', (context) => {
+      if (!context.includeDeleted && options.soft !== false) {
+        context.query = {
+          ...(context.query || {}),
+          [deletedField]: { $exists: false },
+        };
+      }
+    });
+  },
+});
+
+export default softDeletePlugin;

package/src/plugins/subdocument.plugin.js

@@ -0,0 +1,66 @@
+/**
+ * Subdocument Plugin
+ * Adds subdocument array operations
+ */
+
+import createError from 'http-errors';
+
+export const subdocumentPlugin = () => ({
+  name: 'subdocument',
+
+  apply(repo) {
+    if (!repo.registerMethod) {
+      throw new Error('subdocumentPlugin requires methodRegistryPlugin');
+    }
+
+    /**
+     * Add subdocument to array
+     */
+    repo.registerMethod('addSubdocument', async function (parentId, arrayPath, subData, options = {}) {
+      return this.update(parentId, { $push: { [arrayPath]: subData } }, options);
+    });
+
+    /**
+     * Get subdocument from array
+     */
+    repo.registerMethod('getSubdocument', async function (parentId, arrayPath, subId, options = {}) {
+      return this._executeQuery(async (Model) => {
+        const parent = await Model.findById(parentId).session(options.session).exec();
+        if (!parent) throw createError(404, 'Parent not found');
+
+        const sub = parent[arrayPath].id(subId);
+        if (!sub) throw createError(404, 'Subdocument not found');
+
+        return options.lean ? sub.toObject() : sub;
+      });
+    });
+
+    /**
+     * Update subdocument in array
+     */
+    repo.registerMethod('updateSubdocument', async function (parentId, arrayPath, subId, updateData, options = {}) {
+      return this._executeQuery(async (Model) => {
+        const query = { _id: parentId, [`${arrayPath}._id`]: subId };
+        const update = { $set: { [`${arrayPath}.$`]: { ...updateData, _id: subId } } };
+
+        const result = await Model.findOneAndUpdate(query, update, {
+          new: true,
+          runValidators: true,
+          session: options.session,
+        }).exec();
+
+        if (!result) throw createError(404, 'Parent or subdocument not found');
+        return result;
+      });
+    });
+
+    /**
+     * Delete subdocument from array
+     */
+    repo.registerMethod('deleteSubdocument', async function (parentId, arrayPath, subId, options = {}) {
+      return this.update(parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
+    });
+  }
+});
+
+export default subdocumentPlugin;

package/src/plugins/timestamp.plugin.js

@@ -0,0 +1,19 @@
+export const timestampPlugin = () => ({
+  name: 'timestamp',
+
+  apply(repo) {
+    repo.on('before:create', (context) => {
+      if (!context.data) return;
+      const now = new Date();
+      if (!context.data.createdAt) context.data.createdAt = now;
+      if (!context.data.updatedAt) context.data.updatedAt = now;
+    });
+
+    repo.on('before:update', (context) => {
+      if (!context.data) return;
+      context.data.updatedAt = new Date();
+    });
+  },
+});
+
+export default timestampPlugin;