@classytic/mongokit 1.0.0

package/src/Repository.js

@@ -0,0 +1,225 @@
+import mongoose from 'mongoose';
+import createError from 'http-errors';
+import * as createActions from './actions/create.js';
+import * as readActions from './actions/read.js';
+import * as updateActions from './actions/update.js';
+import * as deleteActions from './actions/delete.js';
+import * as aggregateActions from './actions/aggregate.js';
+
+export class Repository {
+  constructor(Model, plugins = []) {
+    this.Model = Model;
+    this.model = Model.modelName;
+    this._hooks = new Map();
+    plugins.forEach(plugin => this.use(plugin));
+  }
+
+  use(plugin) {
+    if (typeof plugin === 'function') {
+      plugin(this);
+    } else if (plugin && typeof plugin.apply === 'function') {
+      plugin.apply(this);
+    }
+    return this;
+  }
+
+  on(event, listener) {
+    if (!this._hooks.has(event)) {
+      this._hooks.set(event, []);
+    }
+    this._hooks.get(event).push(listener);
+    return this;
+  }
+
+  emit(event, data) {
+    const listeners = this._hooks.get(event) || [];
+    listeners.forEach(listener => listener(data));
+  }
+
+  async create(data, options = {}) {
+    const context = await this._buildContext('create', { data, ...options });
+
+    try {
+      const result = await createActions.create(this.Model, context.data, options);
+      this.emit('after:create', { context, result });
+      return result;
+    } catch (error) {
+      this.emit('error:create', { context, error });
+      throw this._handleError(error);
+    }
+  }
+
+  async createMany(dataArray, options = {}) {
+    const context = await this._buildContext('createMany', { dataArray, ...options });
+
+    try {
+      const result = await createActions.createMany(this.Model, context.dataArray || dataArray, options);
+      this.emit('after:createMany', { context, result });
+      return result;
+    } catch (error) {
+      this.emit('error:createMany', { context, error });
+      throw this._handleError(error);
+    }
+  }
+
+  async getById(id, options = {}) {
+    const context = await this._buildContext('getById', { id, ...options });
+    return readActions.getById(this.Model, id, context);
+  }
+
+  async getByQuery(query, options = {}) {
+    const context = await this._buildContext('getByQuery', { query, ...options });
+    return readActions.getByQuery(this.Model, query, context);
+  }
+
+  async getAll(queryParams = {}, options = {}) {
+    const context = await this._buildContext('getAll', { queryParams, ...options });
+
+    const {
+      pagination = { page: 1, limit: 10 },
+      search,
+      sort = '-createdAt',
+      filters = {},
+    } = context.queryParams || queryParams;
+
+    let query = { ...filters };
+    if (search) query.$text = { $search: search };
+
+    const paginateOptions = {
+      page: parseInt(pagination.page, 10),
+      limit: parseInt(pagination.limit, 10),
+      sort: this._parseSort(sort),
+      populate: this._parsePopulate(context.populate || options.populate),
+      select: context.select || options.select,
+      lean: context.lean ?? options.lean ?? true,
+      session: options.session,
+    };
+
+    if (!this.Model.paginate) {
+      throw createError(500, `Model ${this.model} missing paginate plugin`);
+    }
+
+    return this.Model.paginate(query, paginateOptions);
+  }
+
+  async getOrCreate(query, createData, options = {}) {
+    return readActions.getOrCreate(this.Model, query, createData, options);
+  }
+
+  async count(query = {}, options = {}) {
+    return readActions.count(this.Model, query, options);
+  }
+
+  async exists(query, options = {}) {
+    return readActions.exists(this.Model, query, options);
+  }
+
+  async update(id, data, options = {}) {
+    const context = await this._buildContext('update', { id, data, ...options });
+
+    try {
+      const result = await updateActions.update(this.Model, id, context.data, context);
+      this.emit('after:update', { context, result });
+      return result;
+    } catch (error) {
+      this.emit('error:update', { context, error });
+      throw this._handleError(error);
+    }
+  }
+
+  async delete(id, options = {}) {
+    const context = await this._buildContext('delete', { id, ...options });
+
+    try {
+      const result = await deleteActions.deleteById(this.Model, id, options);
+      this.emit('after:delete', { context, result });
+      return result;
+    } catch (error) {
+      this.emit('error:delete', { context, error });
+      throw this._handleError(error);
+    }
+  }
+
+  async aggregate(pipeline, options = {}) {
+    return aggregateActions.aggregate(this.Model, pipeline, options);
+  }
+
+  async aggregatePaginate(pipeline, options = {}) {
+    return aggregateActions.aggregatePaginate(this.Model, pipeline, options);
+  }
+
+  async distinct(field, query = {}, options = {}) {
+    return aggregateActions.distinct(this.Model, field, query, options);
+  }
+
+  async withTransaction(callback) {
+    const session = await mongoose.startSession();
+    session.startTransaction();
+    try {
+      const result = await callback(session);
+      await session.commitTransaction();
+      return result;
+    } catch (error) {
+      await session.abortTransaction();
+      throw error;
+    } finally {
+      session.endSession();
+    }
+  }
+
+  async _executeQuery(buildQuery) {
+    const operation = buildQuery.name || 'custom';
+    const context = await this._buildContext(operation, {});
+
+    try {
+      const result = await buildQuery(this.Model);
+      this.emit(`after:${operation}`, { context, result });
+      return result;
+    } catch (error) {
+      this.emit(`error:${operation}`, { context, error });
+      throw this._handleError(error);
+    }
+  }
+
+  async _buildContext(operation, options) {
+    const context = { operation, model: this.model, ...options };
+    const event = `before:${operation}`;
+    const hooks = this._hooks.get(event) || [];
+
+    for (const hook of hooks) {
+      await hook(context);
+    }
+
+    return context;
+  }
+
+  _parseSort(sort) {
+    if (!sort) return { createdAt: -1 };
+    if (typeof sort === 'object') return sort;
+
+    const sortOrder = sort.startsWith('-') ? -1 : 1;
+    const sortField = sort.startsWith('-') ? sort.substring(1) : sort;
+    return { [sortField]: sortOrder };
+  }
+
+  _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];
+  }
+
+  _handleError(error) {
+    if (error instanceof mongoose.Error.ValidationError) {
+      const messages = Object.values(error.errors).map(err => err.message);
+      return createError(400, `Validation Error: ${messages.join(', ')}`);
+    }
+    if (error instanceof mongoose.Error.CastError) {
+      return createError(400, `Invalid ${error.path}: ${error.value}`);
+    }
+    if (error.status && error.message) return error;
+    return createError(500, error.message || 'Internal Server Error');
+  }
+}
+
+export default Repository;

package/src/actions/aggregate.js

@@ -0,0 +1,191 @@
+/**
+ * Aggregate Actions
+ * MongoDB aggregation pipeline operations
+ */
+
+/**
+ * Execute aggregation pipeline
+ */
+export async function aggregate(Model, pipeline, options = {}) {
+  const aggregation = Model.aggregate(pipeline);
+
+  if (options.session) {
+    aggregation.session(options.session);
+  }
+
+  return aggregation.exec();
+}
+
+/**
+ * Aggregate with pagination
+ */
+export async function aggregatePaginate(Model, pipeline, options = {}) {
+  const { page = 1, limit = 10 } = options;
+
+  return Model.aggregatePaginate(Model.aggregate(pipeline), {
+    page: parseInt(page, 10),
+    limit: parseInt(limit, 10),
+  });
+}
+
+/**
+ * Group by field
+ */
+export async function groupBy(Model, field, options = {}) {
+  const pipeline = [
+    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+    { $sort: { count: -1 } },
+  ];
+
+  if (options.limit) {
+    pipeline.push({ $limit: options.limit });
+  }
+
+  return aggregate(Model, pipeline, options);
+}
+
+/**
+ * Count by field values
+ */
+export async function countBy(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+
+  pipeline.push(
+    { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+    { $sort: { count: -1 } }
+  );
+
+  return aggregate(Model, pipeline, options);
+}
+
+/**
+ * Lookup (join) with another collection
+ */
+export async function lookup(Model, {
+  from,
+  localField,
+  foreignField,
+  as,
+  pipeline = [],
+  query = {},
+  options = {}
+}) {
+  const aggPipeline = [];
+
+  if (Object.keys(query).length > 0) {
+    aggPipeline.push({ $match: query });
+  }
+
+  aggPipeline.push({
+    $lookup: {
+      from,
+      localField,
+      foreignField,
+      as,
+      ...(pipeline.length > 0 ? { pipeline } : {}),
+    },
+  });
+
+  return aggregate(Model, aggPipeline, options);
+}
+
+/**
+ * Unwind array field
+ */
+export async function unwind(Model, field, options = {}) {
+  const pipeline = [
+    {
+      $unwind: {
+        path: `$${field}`,
+        preserveNullAndEmptyArrays: options.preserveEmpty !== false,
+      },
+    },
+  ];
+
+  return aggregate(Model, pipeline, options);
+}
+
+/**
+ * Facet search (multiple aggregations in one query)
+ */
+export async function facet(Model, facets, options = {}) {
+  const pipeline = [{ $facet: facets }];
+
+  return aggregate(Model, pipeline, options);
+}
+
+/**
+ * Get distinct values
+ */
+export async function distinct(Model, field, query = {}, options = {}) {
+  return Model.distinct(field, query).session(options.session);
+}
+
+/**
+ * Calculate sum
+ */
+export async function sum(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+
+  pipeline.push({
+    $group: {
+      _id: null,
+      total: { $sum: `$${field}` },
+    },
+  });
+
+  const result = await aggregate(Model, pipeline, options);
+  return result[0]?.total || 0;
+}
+
+/**
+ * Calculate average
+ */
+export async function average(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+
+  pipeline.push({
+    $group: {
+      _id: null,
+      average: { $avg: `$${field}` },
+    },
+  });
+
+  const result = await aggregate(Model, pipeline, options);
+  return result[0]?.average || 0;
+}
+
+/**
+ * Min/Max
+ */
+export async function minMax(Model, field, query = {}, options = {}) {
+  const pipeline = [];
+
+  if (Object.keys(query).length > 0) {
+    pipeline.push({ $match: query });
+  }
+
+  pipeline.push({
+    $group: {
+      _id: null,
+      min: { $min: `$${field}` },
+      max: { $max: `$${field}` },
+    },
+  });
+
+  const result = await aggregate(Model, pipeline, options);
+  return result[0] || { min: null, max: null };
+}
+

package/src/actions/create.js

@@ -0,0 +1,58 @@
+/**
+ * Create Actions
+ * Pure functions for document creation
+ */
+
+/**
+ * Create single document
+ */
+export async function create(Model, data, options = {}) {
+  const document = new Model(data);
+  await document.save({ session: options.session });
+  return document;
+}
+
+/**
+ * Create multiple documents
+ */
+export async function createMany(Model, dataArray, options = {}) {
+  return Model.insertMany(dataArray, {
+    session: options.session,
+    ordered: options.ordered !== false,
+  });
+}
+
+/**
+ * Create with defaults (useful for initialization)
+ */
+export async function createDefault(Model, overrides = {}, options = {}) {
+  const defaults = {};
+  
+  // Extract defaults from schema
+  Model.schema.eachPath((path, schemaType) => {
+    if (schemaType.options.default !== undefined && path !== '_id') {
+      defaults[path] = typeof schemaType.options.default === 'function'
+        ? schemaType.options.default()
+        : schemaType.options.default;
+    }
+  });
+  
+  return create(Model, { ...defaults, ...overrides }, options);
+}
+
+/**
+ * Upsert (create or update)
+ */
+export async function upsert(Model, query, data, options = {}) {
+  return Model.findOneAndUpdate(
+    query,
+    { $setOnInsert: data },
+    {
+      upsert: true,
+      new: true,
+      runValidators: true,
+      session: options.session,
+    }
+  );
+}
+

package/src/actions/delete.js

@@ -0,0 +1,88 @@
+/**
+ * Delete Actions
+ * Pure functions for document deletion
+ */
+
+import createError from 'http-errors';
+
+/**
+ * Delete by ID
+ */
+export async function deleteById(Model, id, options = {}) {
+  const document = await Model.findByIdAndDelete(id).session(options.session);
+
+  if (!document) {
+    throw createError(404, 'Document not found');
+  }
+
+  return { success: true, message: 'Deleted successfully' };
+}
+
+/**
+ * Delete many documents
+ */
+export async function deleteMany(Model, query, options = {}) {
+  const result = await Model.deleteMany(query).session(options.session);
+
+  return {
+    success: true,
+    count: result.deletedCount,
+    message: 'Deleted successfully',
+  };
+}
+
+/**
+ * Delete by query
+ */
+export async function deleteByQuery(Model, query, options = {}) {
+  const document = await Model.findOneAndDelete(query).session(options.session);
+
+  if (!document && options.throwOnNotFound !== false) {
+    throw createError(404, 'Document not found');
+  }
+
+  return { success: true, message: 'Deleted successfully' };
+}
+
+/**
+ * Soft delete (set deleted flag)
+ */
+export async function softDelete(Model, id, options = {}) {
+  const document = await Model.findByIdAndUpdate(
+    id,
+    {
+      deleted: true,
+      deletedAt: new Date(),
+      deletedBy: options.userId,
+    },
+    { new: true, session: options.session }
+  );
+
+  if (!document) {
+    throw createError(404, 'Document not found');
+  }
+
+  return { success: true, message: 'Soft deleted successfully' };
+}
+
+/**
+ * Restore soft deleted document
+ */
+export async function restore(Model, id, options = {}) {
+  const document = await Model.findByIdAndUpdate(
+    id,
+    {
+      deleted: false,
+      deletedAt: null,
+      deletedBy: null,
+    },
+    { new: true, session: options.session }
+  );
+
+  if (!document) {
+    throw createError(404, 'Document not found');
+  }
+
+  return { success: true, message: 'Restored successfully' };
+}
+

package/src/actions/index.js

@@ -0,0 +1,11 @@
+/**
+ * Repository Actions
+ * Modular, composable data access operations
+ */
+
+export * as create from './create.js';
+export * as read from './read.js';
+export * as update from './update.js';
+export * as deleteActions from './delete.js';
+export * as aggregate from './aggregate.js';
+