@classytic/mongokit 1.0.0

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

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

package/src/utils/field-selection.js

@@ -0,0 +1,156 @@
+/**
+ * Field Selection Utilities
+ *
+ * Provides explicit, performant field filtering using Mongoose projections.
+ *
+ * Philosophy:
+ * - Explicit is better than implicit
+ * - Filter at DB level (10x faster than in-memory)
+ * - Progressive disclosure (show more fields as trust increases)
+ *
+ * Usage:
+ * ```javascript
+ * // For Mongoose queries (PREFERRED - 90% of cases)
+ * const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
+ * const plans = await GymPlan.find().select(projection).lean();
+ *
+ * // For complex data (10% of cases - aggregations, multiple sources)
+ * const filtered = filterResponseData(complexData, fieldPresets.gymPlans, request.user);
+ * ```
+ */
+
+/**
+ * Get allowed fields for a user based on their context
+ *
+ * @param {Object} user - User object from request.user (or null for public)
+ * @param {Object} preset - Field preset configuration
+ * @param {string[]} preset.public - Fields visible to everyone
+ * @param {string[]} preset.authenticated - Additional fields for authenticated users
+ * @param {string[]} preset.admin - Additional fields for admins
+ * @returns {string[]} Array of allowed field names
+ */
+export const getFieldsForUser = (user, preset) => {
+  if (!preset) {
+    throw new Error('Field preset is required');
+  }
+
+  // Start with public fields
+  let fields = [...(preset.public || [])];
+
+  // Add authenticated fields if user is logged in
+  if (user) {
+    fields.push(...(preset.authenticated || []));
+
+    // Add admin fields if user is admin/superadmin
+    const roles = Array.isArray(user.roles) ? user.roles : (user.roles ? [user.roles] : []);
+    if (roles.includes('admin') || roles.includes('superadmin')) {
+      fields.push(...(preset.admin || []));
+    }
+  }
+
+  // Remove duplicates
+  return [...new Set(fields)];
+};
+
+/**
+ * Get Mongoose projection string for query .select()
+ *
+ * @param {Object} user - User object from request.user
+ * @param {Object} preset - Field preset configuration
+ * @returns {string} Space-separated field names for Mongoose .select()
+ *
+ * @example
+ * const projection = getMongooseProjection(request.user, fieldPresets.gymPlans);
+ * const plans = await GymPlan.find({ organizationId }).select(projection).lean();
+ */
+export const getMongooseProjection = (user, preset) => {
+  const fields = getFieldsForUser(user, preset);
+  return fields.join(' ');
+};
+
+/**
+ * Filter response data to include only allowed fields
+ *
+ * Use this for complex responses where Mongoose projections aren't applicable:
+ * - Aggregation pipeline results
+ * - Data from multiple sources
+ * - Custom computed fields
+ *
+ * For simple DB queries, prefer getMongooseProjection() (10x faster)
+ *
+ * @param {Object|Array} data - Data to filter
+ * @param {Object} preset - Field preset configuration
+ * @param {Object} user - User object from request.user
+ * @returns {Object|Array} Filtered data
+ *
+ * @example
+ * const stats = await calculateComplexStats();
+ * const filtered = filterResponseData(stats, fieldPresets.dashboard, request.user);
+ * return reply.send(filtered);
+ */
+export const filterResponseData = (data, preset, user = null) => {
+  const allowedFields = getFieldsForUser(user, preset);
+
+  // Handle arrays
+  if (Array.isArray(data)) {
+    return data.map(item => filterObject(item, allowedFields));
+  }
+
+  // Handle single object
+  return filterObject(data, allowedFields);
+};
+
+/**
+ * Filter a single object to include only allowed fields
+ *
+ * @private
+ * @param {Object} obj - Object to filter
+ * @param {string[]} allowedFields - Array of allowed field names
+ * @returns {Object} Filtered object
+ */
+const filterObject = (obj, allowedFields) => {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    return obj;
+  }
+
+  const filtered = {};
+
+  for (const field of allowedFields) {
+    if (field in obj) {
+      filtered[field] = obj[field];
+    }
+  }
+
+  return filtered;
+};
+
+/**
+ * Helper to create field presets (module-level)
+ *
+ * Each module should define its own field preset in its own directory.
+ * This keeps modules independent and self-contained.
+ *
+ * @param {Object} config - Field configuration
+ * @returns {Object} Field preset
+ *
+ * @example
+ * // In modules/gym-plan/gym-plan.fields.js
+ * import { createFieldPreset } from '#common/utils/field-selection.js';
+ *
+ * export const gymPlanFieldPreset = createFieldPreset({
+ *   public: ['id', 'name', 'price'],
+ *   authenticated: ['features', 'description'],
+ *   admin: ['createdAt', 'updatedAt', 'internalNotes']
+ * });
+ *
+ * // Then in controller:
+ * import { gymPlanFieldPreset } from './gym-plan.fields.js';
+ * super(gymPlanRepository, { fieldPreset: gymPlanFieldPreset });
+ */
+export const createFieldPreset = (config) => {
+  return {
+    public: config.public || [],
+    authenticated: config.authenticated || [],
+    admin: config.admin || [],
+  };
+};

package/src/utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Utility Functions for MongoKit
+ * Reusable helpers for field selection, filtering, and more
+ */
+
+export {
+  getFieldsForUser,
+  getMongooseProjection,
+  filterResponseData,
+  createFieldPreset,
+} from './field-selection.js';
+

package/types/actions/index.d.ts

@@ -0,0 +1,113 @@
+import { Model, Document, FilterQuery, UpdateQuery, ClientSession } from 'mongoose';
+
+export interface ActionOptions {
+  session?: ClientSession;
+  [key: string]: any;
+}
+
+// Create actions
+export function create<T extends Document>(
+  Model: Model<T>,
+  data: Partial<T>,
+  options?: ActionOptions
+): Promise<T>;
+
+export function createMany<T extends Document>(
+  Model: Model<T>,
+  dataArray: Partial<T>[],
+  options?: ActionOptions
+): Promise<T[]>;
+
+export function createDefault<T extends Document>(
+  Model: Model<T>,
+  overrides?: Partial<T>,
+  options?: ActionOptions
+): Promise<T>;
+
+export function upsert<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  data: Partial<T>,
+  options?: ActionOptions
+): Promise<T>;
+
+// Read actions
+export function getById<T extends Document>(
+  Model: Model<T>,
+  id: string,
+  options?: ActionOptions
+): Promise<T | null>;
+
+export function getByQuery<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  options?: ActionOptions
+): Promise<T | null>;
+
+export function getOrCreate<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  createData: Partial<T>,
+  options?: ActionOptions
+): Promise<T>;
+
+export function count<T extends Document>(
+  Model: Model<T>,
+  query?: FilterQuery<T>,
+  options?: ActionOptions
+): Promise<number>;
+
+export function exists<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  options?: ActionOptions
+): Promise<boolean>;
+
+// Update actions
+export function update<T extends Document>(
+  Model: Model<T>,
+  id: string,
+  data: UpdateQuery<T>,
+  options?: ActionOptions
+): Promise<T | null>;
+
+export function updateMany<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  data: UpdateQuery<T>,
+  options?: ActionOptions
+): Promise<any>;
+
+// Delete actions
+export function deleteById<T extends Document>(
+  Model: Model<T>,
+  id: string,
+  options?: ActionOptions
+): Promise<T | null>;
+
+export function deleteMany<T extends Document>(
+  Model: Model<T>,
+  query: FilterQuery<T>,
+  options?: ActionOptions
+): Promise<any>;
+
+// Aggregate actions
+export function aggregate<T extends Document>(
+  Model: Model<T>,
+  pipeline: any[],
+  options?: ActionOptions
+): Promise<any[]>;
+
+export function aggregatePaginate<T extends Document>(
+  Model: Model<T>,
+  pipeline: any[],
+  options?: ActionOptions
+): Promise<any>;
+
+export function distinct<T extends Document>(
+  Model: Model<T>,
+  field: string,
+  query?: FilterQuery<T>,
+  options?: ActionOptions
+): Promise<any[]>;
+

package/types/index.d.ts

@@ -0,0 +1,96 @@
+import { Model, Document, ClientSession, PaginateOptions, PaginateResult, FilterQuery, UpdateQuery, AggregateOptions } from 'mongoose';
+
+export interface RepositoryOptions {
+  session?: ClientSession;
+  populate?: string | string[] | any;
+  select?: string | any;
+  lean?: boolean;
+  throwOnNotFound?: boolean;
+}
+
+export interface QueryParams {
+  pagination?: {
+    page: number;
+    limit: number;
+  };
+  search?: string;
+  sort?: string;
+  filters?: Record<string, any>;
+}
+
+export interface RepositoryContext {
+  operation: string;
+  model: string;
+  data?: any;
+  dataArray?: any[];
+  id?: string;
+  query?: any;
+  queryParams?: QueryParams;
+  context?: any;
+  user?: any;
+  organizationId?: string;
+  [key: string]: any;
+}
+
+export type EventListener = (data: any) => void | Promise<void>;
+
+export interface Plugin {
+  name: string;
+  apply(repository: Repository<any>): void;
+}
+
+export type PluginFactory = (options?: any) => Plugin;
+
+export class Repository<T extends Document> {
+  Model: Model<T>;
+  model: string;
+  protected _hooks: Map<string, EventListener[]>;
+
+  constructor(Model: Model<T>, plugins?: (Plugin | PluginFactory)[]);
+
+  // Plugin system
+  use(plugin: Plugin | PluginFactory): this;
+  on(event: string, listener: EventListener): this;
+  emit(event: string, data: any): void;
+
+  // CRUD operations
+  create(data: Partial<T>, options?: RepositoryOptions): Promise<T>;
+  createMany(dataArray: Partial<T>[], options?: RepositoryOptions): Promise<T[]>;
+  
+  getById(id: string, options?: RepositoryOptions): Promise<T | null>;
+  getByQuery(query: FilterQuery<T>, options?: RepositoryOptions): Promise<T | null>;
+  getAll(queryParams?: QueryParams, options?: RepositoryOptions): Promise<PaginateResult<T>>;
+  getOrCreate(query: FilterQuery<T>, createData: Partial<T>, options?: RepositoryOptions): Promise<T>;
+  
+  count(query?: FilterQuery<T>, options?: RepositoryOptions): Promise<number>;
+  exists(query: FilterQuery<T>, options?: RepositoryOptions): Promise<boolean>;
+  
+  update(id: string, data: UpdateQuery<T>, options?: RepositoryOptions): Promise<T | null>;
+  delete(id: string, options?: RepositoryOptions): Promise<T | null>;
+
+  // Aggregation
+  aggregate(pipeline: any[], options?: AggregateOptions): Promise<any[]>;
+  aggregatePaginate(pipeline: any[], options?: PaginateOptions): Promise<any>;
+  distinct(field: string, query?: FilterQuery<T>, options?: RepositoryOptions): Promise<any[]>;
+
+  // Transaction support
+  withTransaction<R>(callback: (session: ClientSession) => Promise<R>): Promise<R>;
+
+  // Internal methods
+  protected _executeQuery(buildQuery: (model: Model<T>) => Promise<any>): Promise<any>;
+  protected _buildContext(operation: string, options: any): Promise<RepositoryContext>;
+  protected _parseSort(sort: string | object): object;
+  protected _parsePopulate(populate: string | string[] | any): any[];
+  protected _handleError(error: any): Error;
+}
+
+export function createRepository<T extends Document>(
+  Model: Model<T>,
+  plugins?: (Plugin | PluginFactory)[]
+): Repository<T>;
+
+// Plugin exports
+export * from './plugins/index.js';
+export * from './utils/index.js';
+export * as actions from './actions/index.js';
+

package/types/plugins/index.d.ts

@@ -0,0 +1,88 @@
+import { Plugin, PluginFactory, Repository, RepositoryContext } from '../index.js';
+import { Document } from 'mongoose';
+
+// Field Filter Plugin
+export interface FieldPreset {
+  public?: string[];
+  authenticated?: string[];
+  admin?: string[];
+}
+
+export function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
+
+// Soft Delete Plugin
+export interface SoftDeleteOptions {
+  deletedField?: string;
+  deletedByField?: string;
+}
+
+export function softDeletePlugin(options?: SoftDeleteOptions): Plugin;
+
+// Timestamp Plugin
+export interface TimestampOptions {
+  createdAtField?: string;
+  updatedAtField?: string;
+}
+
+export function timestampPlugin(options?: TimestampOptions): Plugin;
+
+// Audit Log Plugin
+export interface Logger {
+  info(message: string, meta?: any): void;
+  error(message: string, meta?: any): void;
+  warn(message: string, meta?: any): void;
+}
+
+export function auditLogPlugin(logger: Logger): Plugin;
+
+// Validation Chain Plugin
+export interface Validator {
+  name: string;
+  operations?: string[];
+  validate(context: RepositoryContext, repo: Repository<any>): void | Promise<void>;
+}
+
+export interface ValidationChainOptions {
+  stopOnFirstError?: boolean;
+}
+
+export function validationChainPlugin(
+  validators: Validator[],
+  options?: ValidationChainOptions
+): Plugin;
+
+// Validator helpers
+export function blockIf(
+  name: string,
+  operations: string[],
+  condition: (context: RepositoryContext) => boolean,
+  errorMessage: string
+): Validator;
+
+export function requireField(field: string, operations?: string[]): Validator;
+
+export function autoInject(
+  field: string,
+  getter: (context: RepositoryContext) => any,
+  operations?: string[]
+): Validator;
+
+export function immutableField(field: string): Validator;
+
+export function uniqueField(field: string, errorMessage?: string): Validator;
+
+// Method Registry Plugin
+export function methodRegistryPlugin(): Plugin;
+
+// Mongo Operations Plugin
+export function mongoOperationsPlugin(): Plugin;
+
+// Batch Operations Plugin
+export function batchOperationsPlugin(): Plugin;
+
+// Aggregate Helpers Plugin
+export function aggregateHelpersPlugin(): Plugin;
+
+// Subdocument Plugin
+export function subdocumentPlugin(): Plugin;
+

package/types/utils/index.d.ts

@@ -0,0 +1,24 @@
+import { FieldPreset } from '../plugins/index.js';
+
+export interface User {
+  roles?: string | string[];
+  [key: string]: any;
+}
+
+// Field Selection utilities
+export function getFieldsForUser(user: User | null, preset: FieldPreset): string[];
+
+export function getMongooseProjection(user: User | null, preset: FieldPreset): string;
+
+export function filterResponseData<T>(
+  data: T | T[],
+  preset: FieldPreset,
+  user?: User | null
+): T | T[];
+
+export function createFieldPreset(config: {
+  public?: string[];
+  authenticated?: string[];
+  admin?: string[];
+}): FieldPreset;
+