@classytic/mongokit 2.0.0 → 2.1.0

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 '../utils/error.js';
-
-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 '../utils/error.js';
-
-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 = /** @type {Error & {status: number, validationErrors: any[]}} */ (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/types.d.ts

@@ -1,87 +0,0 @@
-/**
- * Type definitions for MongoKit
- * Used for type checking and auto-completion
- */
-
-import { Model, Document, PopulateOptions, ClientSession, Types } from 'mongoose';
-
-// Re-export mongoose ObjectId
-export type ObjectId = Types.ObjectId;
-
-// Pagination configuration
-export interface PaginationConfig {
-  defaultLimit?: number;
-  maxLimit?: number;
-  maxPage?: number;
-  deepPageThreshold?: number;
-  cursorVersion?: number;
-  useEstimatedCount?: boolean;
-}
-
-// Pagination options
-export interface OffsetPaginationOptions {
-  filters?: Record<string, any>;
-  sort?: Record<string, 1 | -1>;
-  page?: number;
-  limit?: number;
-  select?: string | string[];
-  populate?: string | string[] | PopulateOptions | PopulateOptions[];
-  lean?: boolean;
-  session?: ClientSession;
-}
-
-export interface KeysetPaginationOptions {
-  filters?: Record<string, any>;
-  sort: Record<string, 1 | -1>;
-  after?: string;
-  limit?: number;
-  select?: string | string[] | Record<string, any>;
-  populate?: string | string[] | PopulateOptions | PopulateOptions[];
-  lean?: boolean;
-  session?: ClientSession;
-}
-
-export interface AggregatePaginationOptions {
-  pipeline?: any[];
-  page?: number;
-  limit?: number;
-  session?: ClientSession;
-}
-
-// Pagination result types
-export interface OffsetPaginationResult<T = any> {
-  method: 'offset';
-  docs: T[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  warning?: string;
-}
-
-export interface KeysetPaginationResult<T = any> {
-  method: 'keyset';
-  docs: T[];
-  limit: number;
-  hasMore: boolean;
-  next: string | null;
-}
-
-export interface AggregatePaginationResult<T = any> {
-  method: 'aggregate';
-  docs: T[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-  warning?: string;
-}
-
-export type PaginationResult<T = any> =
-  | OffsetPaginationResult<T>
-  | KeysetPaginationResult<T>
-  | AggregatePaginationResult<T>;

package/src/utils/error.js

@@ -1,12 +0,0 @@
-/**
- * Creates an error with HTTP status code
- *
- * @param {number} status - HTTP status code
- * @param {string} message - Error message
- * @returns {Error & {status: number}} Error with status property
- */
-export function createError(status, message) {
-  const error = /** @type {Error & {status: number}} */ (new Error(message));
-  error.status = status;
-  return error;
-}

package/src/utils/field-selection.js

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

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

package/types/Repository.d.ts

@@ -1,95 +0,0 @@
-/**
- * @typedef {import('./types.js').OffsetPaginationResult} OffsetPaginationResult
- * @typedef {import('./types.js').KeysetPaginationResult} KeysetPaginationResult
- * @typedef {import('./types.js').AggregatePaginationResult} AggregatePaginationResult
- * @typedef {import('./types.js').ObjectId} ObjectId
- */
-export class Repository {
-    constructor(Model: any, plugins?: any[], paginationConfig?: {});
-    Model: any;
-    model: any;
-    _hooks: Map<any, any>;
-    _pagination: PaginationEngine;
-    use(plugin: any): this;
-    on(event: any, listener: any): this;
-    emit(event: any, data: any): void;
-    create(data: any, options?: {}): Promise<any>;
-    createMany(dataArray: any, options?: {}): Promise<any>;
-    getById(id: any, options?: {}): Promise<any>;
-    getByQuery(query: any, options?: {}): Promise<any>;
-    /**
-     * Unified pagination - auto-detects offset vs keyset based on params
-     *
-     * Auto-detection logic:
-     * - If params has 'cursor' or 'after' → uses keyset pagination (stream)
-     * - If params has 'pagination' or 'page' → uses offset pagination (paginate)
-     * - Else → defaults to offset pagination with page=1
-     *
-     * @param {Object} params - Query and pagination parameters
-     * @param {Object} [params.filters] - MongoDB query filters
-     * @param {string|Object} [params.sort] - Sort specification
-     * @param {string} [params.cursor] - Cursor token for keyset pagination
-     * @param {string} [params.after] - Alias for cursor
-     * @param {number} [params.page] - Page number for offset pagination
-     * @param {Object} [params.pagination] - Pagination config { page, limit }
-     * @param {number} [params.limit] - Documents per page
-     * @param {string} [params.search] - Full-text search query
-     * @param {Object} [options] - Additional options (select, populate, lean, session)
-     * @returns {Promise<OffsetPaginationResult|KeysetPaginationResult>} Discriminated union based on method
-     *
-     * @example
-     * // Offset pagination (page-based)
-     * await repo.getAll({ page: 1, limit: 50, filters: { status: 'active' } });
-     * await repo.getAll({ pagination: { page: 2, limit: 20 } });
-     *
-     * // Keyset pagination (cursor-based)
-     * await repo.getAll({ cursor: 'eyJ2Ij...', limit: 50 });
-     * await repo.getAll({ after: 'eyJ2Ij...', sort: { createdAt: -1 } });
-     *
-     * // Simple query (defaults to page 1)
-     * await repo.getAll({ filters: { status: 'active' } });
-     */
-    getAll(params?: {
-        filters?: any;
-        sort?: string | any;
-        cursor?: string;
-        after?: string;
-        page?: number;
-        pagination?: any;
-        limit?: number;
-        search?: string;
-    }, options?: any): Promise<OffsetPaginationResult | KeysetPaginationResult>;
-    getOrCreate(query: any, createData: any, options?: {}): Promise<any>;
-    count(query?: {}, options?: {}): Promise<number>;
-    exists(query: any, options?: {}): Promise<{
-        _id: any;
-    }>;
-    update(id: any, data: any, options?: {}): Promise<any>;
-    delete(id: any, options?: {}): Promise<{
-        success: boolean;
-        message: string;
-    }>;
-    aggregate(pipeline: any, options?: {}): Promise<any[]>;
-    /**
-     * Aggregate pipeline with pagination
-     * Best for: Complex queries, grouping, joins
-     *
-     * @param {Object} options - Aggregate pagination options
-     * @returns {Promise<AggregatePaginationResult>}
-     */
-    aggregatePaginate(options?: any): Promise<AggregatePaginationResult>;
-    distinct(field: any, query?: {}, options?: {}): Promise<any>;
-    withTransaction(callback: any): Promise<any>;
-    _executeQuery(buildQuery: any): Promise<any>;
-    _buildContext(operation: any, options: any): Promise<any>;
-    _parseSort(sort: any): any;
-    _parsePopulate(populate: any): any[];
-    _handleError(error: any): any;
-}
-export default Repository;
-export type OffsetPaginationResult = import("./types.js").OffsetPaginationResult;
-export type KeysetPaginationResult = import("./types.js").KeysetPaginationResult;
-export type AggregatePaginationResult = import("./types.js").AggregatePaginationResult;
-export type ObjectId = import("./types.js").ObjectId;
-import { PaginationEngine } from './pagination/PaginationEngine.js';
-//# sourceMappingURL=Repository.d.ts.map

package/types/Repository.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Repository.d.ts","sourceRoot":"","sources":["../src/Repository.js"],"names":[],"mappings":"AASA;;;;;GAKG;AAEH;IACE,gEAMC;IALC,WAAkB;IAClB,WAA4B;IAC5B,sBAAuB;IACvB,8BAAgE;IAIlE,uBAOC;IAED,oCAMC;IAED,kCAGC;IAED,8CAWC;IAED,uDAWC;IAED,6CAGC;IAED,mDAGC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,gBAvBG;QAAwB,OAAO;QACA,IAAI,GAA3B,MAAM,MAAO;QACG,MAAM,GAAtB,MAAM;QACU,KAAK,GAArB,MAAM;QACU,IAAI,GAApB,MAAM;QACU,UAAU;QACV,KAAK,GAArB,MAAM;QACU,MAAM,GAAtB,MAAM;KACd,kBACU,OAAO,CAAC,sBAAsB,GAAC,sBAAsB,CAAC,CAgElE;IAED,qEAEC;IAED,iDAEC;IAED;;OAEC;IAED,uDAWC;IAED;;;OAWC;IAED,uDAEC;IAED;;;;;;OAMG;IACH,kCAFa,OAAO,CAAC,yBAAyB,CAAC,CAK9C;IAED,6DAEC;IAED,6CAaC;IAED,6CAYC;IAED,0DAUC;IAED,2BAOC;IAED,qCAKC;IAED,8BAUC;CACF;;qCA3RY,OAAO,YAAY,EAAE,sBAAsB;qCAC3C,OAAO,YAAY,EAAE,sBAAsB;wCAC3C,OAAO,YAAY,EAAE,yBAAyB;uBAC9C,OAAO,YAAY,EAAE,QAAQ;iCANT,kCAAkC"}