@classytic/mongokit 1.0.2 → 2.1.0

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

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

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

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

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

package/src/plugins/validation-chain.plugin.js

@@ -1,145 +0,0 @@
-import createError from 'http-errors';
-
-export const validationChainPlugin = (validators = [], options = {}) => {
-  const { stopOnFirstError = true } = options;
-
-  validators.forEach((v, idx) => {
-    if (!v.name || typeof v.name !== 'string') {
-      throw new Error(`Validator at index ${idx} missing 'name' (string)`);
-    }
-    if (typeof v.validate !== 'function') {
-      throw new Error(`Validator '${v.name}' missing 'validate' function`);
-    }
-  });
-
-  const validatorsByOperation = { create: [], update: [], delete: [], createMany: [] };
-  const allOperationsValidators = [];
-
-  validators.forEach(v => {
-    if (!v.operations || v.operations.length === 0) {
-      allOperationsValidators.push(v);
-    } else {
-      v.operations.forEach(op => {
-        if (validatorsByOperation[op]) {
-          validatorsByOperation[op].push(v);
-        }
-      });
-    }
-  });
-
-  return {
-    name: 'validation-chain',
-
-    apply(repo) {
-      const getValidatorsForOperation = (operation) => {
-        const specific = validatorsByOperation[operation] || [];
-        return [...allOperationsValidators, ...specific];
-      };
-
-      const runValidators = async (operation, context) => {
-        const validators = getValidatorsForOperation(operation);
-        const errors = [];
-
-        for (const validator of validators) {
-          try {
-            await validator.validate(context, repo);
-          } catch (error) {
-            if (stopOnFirstError) {
-              throw error;
-            }
-            errors.push({
-              validator: validator.name,
-              error: error.message || String(error)
-            });
-          }
-        }
-
-        if (errors.length > 0) {
-          const error = createError(
-            400,
-            `Validation failed: ${errors.map(e => `[${e.validator}] ${e.error}`).join('; ')}`
-          );
-          error.validationErrors = errors;
-          throw error;
-        }
-      };
-
-      repo.on('before:create', async (context) => await runValidators('create', context));
-      repo.on('before:createMany', async (context) => await runValidators('createMany', context));
-      repo.on('before:update', async (context) => await runValidators('update', context));
-      repo.on('before:delete', async (context) => await runValidators('delete', context));
-    }
-  };
-};
-
-/**
- * Block operation if condition is true
- * @param {string} name - Validator name
- * @param {string[]} operations - Operations to block on
- * @param {Function} condition - Condition function (context) => boolean
- * @param {string} errorMessage - Error message to throw
- * @example blockIf('block-library', ['delete'], ctx => ctx.data.managed, 'Cannot delete managed records')
- */
-export const blockIf = (name, operations, condition, errorMessage) => ({
-  name,
-  operations,
-  validate: (context) => {
-    if (condition(context)) {
-      throw createError(403, errorMessage);
-    }
-  }
-});
-
-export const requireField = (field, operations = ['create']) => ({
-  name: `require-${field}`,
-  operations,
-  validate: (context) => {
-    if (!context.data || context.data[field] === undefined || context.data[field] === null) {
-      throw createError(400, `Field '${field}' is required`);
-    }
-  }
-});
-
-export const autoInject = (field, getter, operations = ['create']) => ({
-  name: `auto-inject-${field}`,
-  operations,
-  validate: (context) => {
-    if (context.data && !(field in context.data)) {
-      const value = getter(context);
-      if (value !== null && value !== undefined) {
-        context.data[field] = value;
-      }
-    }
-  }
-});
-
-export const immutableField = (field) => ({
-  name: `immutable-${field}`,
-  operations: ['update'],
-  validate: (context) => {
-    if (context.data && field in context.data) {
-      throw createError(400, `Field '${field}' cannot be modified`);
-    }
-  }
-});
-
-export const uniqueField = (field, errorMessage) => ({
-  name: `unique-${field}`,
-  operations: ['create', 'update'],
-  validate: async (context, repo) => {
-    if (!context.data || !context.data[field]) return;
-
-    const query = { [field]: context.data[field] };
-    const existing = await repo.getByQuery(query, {
-      select: '_id',
-      lean: true,
-      throwOnNotFound: false
-    });
-
-    if (existing && existing._id.toString() !== context.id?.toString()) {
-      throw createError(409, errorMessage || `${field} already exists`);
-    }
-  }
-});
-
-export default validationChainPlugin;