@classytic/mongokit 2.0.0 → 2.1.0

package/src/plugins/aggregate-helpers.plugin.js

@@ -1,71 +0,0 @@
-/**
- * Aggregate Helpers Plugin
- * Adds common aggregation helper methods
- */
-
-export const aggregateHelpersPlugin = () => ({
-  name: 'aggregate-helpers',
-
-  apply(repo) {
-    if (!repo.registerMethod) {
-      throw new Error('aggregateHelpersPlugin requires methodRegistryPlugin');
-    }
-
-    /**
-     * Group by field
-     */
-    repo.registerMethod('groupBy', async function (field, options = {}) {
-      const pipeline = [
-        { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-        { $sort: { count: -1 } }
-      ];
-
-      if (options.limit) {
-        pipeline.push(/** @type {any} */({ $limit: options.limit }));
-      }
-
-      return this.aggregate(pipeline, options);
-    });
-
-    // Helper: Generic aggregation operation
-    const aggregateOperation = async function (field, operator, resultKey, query = {}, options = {}) {
-      const pipeline = [
-        { $match: query },
-        { $group: { _id: null, [resultKey]: { [operator]: `$${field}` } } }
-      ];
-
-      const result = await this.aggregate(pipeline, options);
-      return result[0]?.[resultKey] || 0;
-    };
-
-    /**
-     * Sum field values
-     */
-    repo.registerMethod('sum', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$sum', 'total', query, options);
-    });
-
-    /**
-     * Average field values
-     */
-    repo.registerMethod('average', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$avg', 'avg', query, options);
-    });
-
-    /**
-     * Get minimum value
-     */
-    repo.registerMethod('min', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$min', 'min', query, options);
-    });
-
-    /**
-     * Get maximum value
-     */
-    repo.registerMethod('max', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$max', 'max', query, options);
-    });
-  }
-});
-
-export default aggregateHelpersPlugin;

package/src/plugins/audit-log.plugin.js

@@ -1,60 +0,0 @@
-export const auditLogPlugin = (logger) => ({
-  name: 'auditLog',
-
-  apply(repo) {
-    repo.on('after:create', ({ context, result }) => {
-      logger?.info?.('Document created', {
-        model: context.model || repo.model,
-        id: result._id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('after:update', ({ context, result }) => {
-      logger?.info?.('Document updated', {
-        model: context.model || repo.model,
-        id: context.id || result._id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('after:delete', ({ context, result }) => {
-      logger?.info?.('Document deleted', {
-        model: context.model || repo.model,
-        id: context.id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('error:create', ({ context, error }) => {
-      logger?.error?.('Create failed', {
-        model: context.model || repo.model,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-
-    repo.on('error:update', ({ context, error }) => {
-      logger?.error?.('Update failed', {
-        model: context.model || repo.model,
-        id: context.id,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-
-    repo.on('error:delete', ({ context, error }) => {
-      logger?.error?.('Delete failed', {
-        model: context.model || repo.model,
-        id: context.id,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-  },
-});
-
-export default auditLogPlugin;

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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-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

@@ -1,19 +0,0 @@
-// 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

@@ -1,140 +0,0 @@
-/**
- * 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

@@ -1,317 +0,0 @@
-/**
- * @typedef {import('../types.js').ObjectId} ObjectId
- */
-
-/**
- * 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 '../utils/error.js';
-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;