@classytic/mongokit 1.0.2 → 2.1.0

package/src/hooks/lifecycle.js

@@ -1,146 +0,0 @@
-/**
- * Lifecycle Hooks
- * Event system for repository actions
- */
-
-import { EventEmitter } from 'events';
-
-export class RepositoryLifecycle extends EventEmitter {
-  constructor() {
-    super();
-    this.hooks = new Map();
-  }
-
-  /**
-   * Register hook
-   */
-  on(event, handler) {
-    if (!this.hooks.has(event)) {
-      this.hooks.set(event, []);
-    }
-    this.hooks.get(event).push(handler);
-    return super.on(event, handler);
-  }
-
-  /**
-   * Execute hooks before action
-   */
-  async runBeforeHooks(action, context) {
-    const event = `before:${action}`;
-    await this.emit(event, context);
-    
-    const hooks = this.hooks.get(event) || [];
-    for (const hook of hooks) {
-      await hook(context);
-    }
-  }
-
-  /**
-   * Execute hooks after action
-   */
-  async runAfterHooks(action, context, result) {
-    const event = `after:${action}`;
-    await this.emit(event, context, result);
-    
-    const hooks = this.hooks.get(event) || [];
-    for (const hook of hooks) {
-      await hook(context, result);
-    }
-  }
-
-  /**
-   * Execute hooks on error
-   */
-  async runErrorHooks(action, context, error) {
-    const event = `error:${action}`;
-    await this.emit(event, context, error);
-    
-    const hooks = this.hooks.get(event) || [];
-    for (const hook of hooks) {
-      await hook(context, error);
-    }
-  }
-}
-
-/**
- * Hook decorators for common patterns
- */
-export const hooks = {
-  /**
-   * Auto-timestamp before create/update
-   */
-  autoTimestamp: () => ({
-    'before:create': (context) => {
-      context.data.createdAt = new Date();
-      context.data.updatedAt = new Date();
-    },
-    'before:update': (context) => {
-      context.data.updatedAt = new Date();
-    },
-  }),
-
-  /**
-   * Auto-inject user context
-   */
-  autoUser: (userField = 'userId') => ({
-    'before:create': (context) => {
-      if (context.user && !context.data[userField]) {
-        context.data[userField] = context.user._id || context.user.id;
-      }
-    },
-  }),
-
-  /**
-   * Auto-inject organization scope
-   */
-  autoOrganization: (orgField = 'organizationId') => ({
-    'before:create': (context) => {
-      if (context.organizationId && !context.data[orgField]) {
-        context.data[orgField] = context.organizationId;
-      }
-    },
-  }),
-
-  /**
-   * Audit log
-   */
-  auditLog: (logger) => ({
-    'after:create': (context, result) => {
-      logger.info('Document created', {
-        model: context.model,
-        id: result._id,
-        user: context.user?.id,
-      });
-    },
-    'after:update': (context, result) => {
-      logger.info('Document updated', {
-        model: context.model,
-        id: result._id,
-        user: context.user?.id,
-      });
-    },
-    'after:delete': (context, result) => {
-      logger.info('Document deleted', {
-        model: context.model,
-        user: context.user?.id,
-      });
-    },
-  }),
-
-  /**
-   * Cache invalidation
-   */
-  cacheInvalidation: (cache) => ({
-    'after:create': async (context, result) => {
-      await cache.invalidate(`${context.model}:*`);
-    },
-    'after:update': async (context, result) => {
-      await cache.invalidate(`${context.model}:${result._id}`);
-      await cache.invalidate(`${context.model}:*`);
-    },
-    'after:delete': async (context) => {
-      await cache.invalidate(`${context.model}:*`);
-    },
-  }),
-};
-

package/src/index.js

@@ -1,60 +0,0 @@
-/**
- * Repository Pattern - Data Access Layer
- * 
- * Event-driven, plugin-based abstraction for MongoDB operations
- * Inspired by Meta & Stripe's repository patterns
- * 
- * @module common/repositories
- * 
- * Documentation:
- * - README.md - Main documentation (concise overview)
- * - QUICK_REFERENCE.md - One-page cheat sheet
- * - EXAMPLES.md - Detailed examples and patterns
- */
-
-/**
- * MongoKit - Event-driven repository pattern for MongoDB
- * 
- * @module @classytic/mongokit
- * @author Sadman Chowdhury (Github: @siam923)
- * @license MIT
- */
-
-export { Repository } from './Repository.js';
-
-// Plugins
-export { fieldFilterPlugin } from './plugins/field-filter.plugin.js';
-export { timestampPlugin } from './plugins/timestamp.plugin.js';
-export { auditLogPlugin } from './plugins/audit-log.plugin.js';
-export { softDeletePlugin } from './plugins/soft-delete.plugin.js';
-export { methodRegistryPlugin } from './plugins/method-registry.plugin.js';
-export {
-  validationChainPlugin,
-  blockIf,
-  requireField,
-  autoInject,
-  immutableField,
-  uniqueField,
-} from './plugins/validation-chain.plugin.js';
-export { mongoOperationsPlugin } from './plugins/mongo-operations.plugin.js';
-export { batchOperationsPlugin } from './plugins/batch-operations.plugin.js';
-export { aggregateHelpersPlugin } from './plugins/aggregate-helpers.plugin.js';
-export { subdocumentPlugin } from './plugins/subdocument.plugin.js';
-
-// Utilities
-export {
-  getFieldsForUser,
-  getMongooseProjection,
-  filterResponseData,
-  createFieldPreset,
-} from './utils/field-selection.js';
-
-export * as actions from './actions/index.js';
-
-import { Repository } from './Repository.js';
-
-export const createRepository = (Model, plugins = []) => {
-  return new Repository(Model, plugins);
-};
-
-export default Repository;

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({ $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;