@classytic/mongokit 1.0.0

package/src/actions/read.js

@@ -0,0 +1,155 @@
+/**
+ * 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 = {}) {
+  return Model.findOneAndUpdate(
+    query,
+    { $setOnInsert: createData },
+    {
+      upsert: true,
+      new: true,
+      runValidators: true,
+      session: options.session,
+    }
+  );
+}
+
+/**
+ * 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;
+}
+

package/src/actions/update.js

@@ -0,0 +1,172 @@
+/**
+ * Update Actions
+ * Pure functions for document updates with optimizations
+ */
+
+import createError from 'http-errors';
+
+/**
+ * Update by ID
+ */
+export async function update(Model, id, data, options = {}) {
+  const document = await Model.findByIdAndUpdate(id, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+  })
+    .select(options.select)
+    .populate(parsePopulate(options.populate))
+    .lean(options.lean);
+
+  if (!document) {
+    throw createError(404, 'Document not found');
+  }
+
+  return document;
+}
+
+/**
+ * Update with query constraints (optimized)
+ * Returns null if constraints not met (not an error)
+ */
+export async function updateWithConstraints(Model, id, data, constraints = {}, options = {}) {
+  const query = { _id: id, ...constraints };
+
+  const document = await Model.findOneAndUpdate(query, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+  })
+    .select(options.select)
+    .populate(parsePopulate(options.populate))
+    .lean(options.lean);
+
+  return document;
+}
+
+/**
+ * Update with validation (smart optimization)
+ * 1-query on success, 2-queries for detailed errors
+ */
+export async function updateWithValidation(
+  Model,
+  id,
+  data,
+  validationOptions = {},
+  options = {}
+) {
+  const { buildConstraints, validateUpdate } = validationOptions;
+
+  // Try optimized update with constraints
+  if (buildConstraints) {
+    const constraints = buildConstraints(data);
+    const document = await updateWithConstraints(Model, id, data, constraints, options);
+
+    if (document) {
+      return { success: true, data: document };
+    }
+  }
+
+  // Fetch for validation
+  const existing = await Model.findById(id)
+    .select(options.select)
+    .lean();
+
+  if (!existing) {
+    return {
+      success: false,
+      error: {
+        code: 404,
+        message: 'Document not found',
+      },
+    };
+  }
+
+  // Run custom validation
+  if (validateUpdate) {
+    const validation = validateUpdate(existing, data);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          code: 403,
+          message: validation.message || 'Update not allowed',
+          violations: validation.violations,
+        },
+      };
+    }
+  }
+
+  // Validation passed - perform update
+  const updated = await update(Model, id, data, options);
+  return { success: true, data: updated };
+}
+
+/**
+ * Update many documents
+ */
+export async function updateMany(Model, query, data, options = {}) {
+  const result = await Model.updateMany(query, data, {
+    runValidators: true,
+    session: options.session,
+  });
+
+  return {
+    matchedCount: result.matchedCount,
+    modifiedCount: result.modifiedCount,
+  };
+}
+
+/**
+ * Update by query
+ */
+export async function updateByQuery(Model, query, data, options = {}) {
+  const document = await Model.findOneAndUpdate(query, data, {
+    new: true,
+    runValidators: true,
+    session: options.session,
+  })
+    .select(options.select)
+    .populate(parsePopulate(options.populate))
+    .lean(options.lean);
+
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, 'Document not found');
+  }
+
+  return document;
+}
+
+/**
+ * Increment field
+ */
+export async function increment(Model, id, field, value = 1, options = {}) {
+  return update(Model, id, { $inc: { [field]: value } }, options);
+}
+
+/**
+ * Push to array
+ */
+export async function pushToArray(Model, id, field, value, options = {}) {
+  return update(Model, id, { $push: { [field]: value } }, options);
+}
+
+/**
+ * Pull from array
+ */
+export async function pullFromArray(Model, id, field, value, options = {}) {
+  return update(Model, id, { $pull: { [field]: value } }, options);
+}
+
+// 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];
+}
+

package/src/hooks/lifecycle.js

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

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

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

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