@classytic/mongokit 1.0.2 → 2.1.0

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/actions/index.d.ts

@@ -1,121 +0,0 @@
-import { Model, Document, UpdateQuery, ClientSession } from 'mongoose';
-
-// Compatibility alias: QueryFilter was introduced in Mongoose 9 and replaces FilterQuery.
-// @ts-ignore - QueryFilter only exists in mongoose >= 9
-type QueryFilterV9<T> = import('mongoose').QueryFilter<T>;
-// @ts-ignore - FilterQuery was removed in mongoose >= 9
-type QueryFilterV8<T> = import('mongoose').FilterQuery<T>;
-type CompatibleQueryFilter<T> = QueryFilterV9<T> | QueryFilterV8<T>;
-
-export interface ActionOptions {
-  session?: ClientSession;
-  updatePipeline?: boolean;
-  [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: CompatibleQueryFilter<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: CompatibleQueryFilter<T>,
-  options?: ActionOptions
-): Promise<T | null>;
-
-export function getOrCreate<T extends Document>(
-  Model: Model<T>,
-  query: CompatibleQueryFilter<T>,
-  createData: Partial<T>,
-  options?: ActionOptions
-): Promise<T>;
-
-export function count<T extends Document>(
-  Model: Model<T>,
-  query?: CompatibleQueryFilter<T>,
-  options?: ActionOptions
-): Promise<number>;
-
-export function exists<T extends Document>(
-  Model: Model<T>,
-  query: CompatibleQueryFilter<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: CompatibleQueryFilter<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: CompatibleQueryFilter<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?: CompatibleQueryFilter<T>,
-  options?: ActionOptions
-): Promise<any[]>;
-

package/types/index.d.ts

@@ -1,104 +0,0 @@
-import { Model, Document, ClientSession, PaginateOptions, PaginateResult, UpdateQuery, AggregateOptions } from 'mongoose';
-
-// Compatibility alias: QueryFilter was introduced in Mongoose 9 and replaces FilterQuery.
-// @ts-ignore - QueryFilter only exists in mongoose >= 9
-type QueryFilterV9<T> = import('mongoose').QueryFilter<T>;
-// @ts-ignore - FilterQuery was removed in mongoose >= 9
-type QueryFilterV8<T> = import('mongoose').FilterQuery<T>;
-type CompatibleQueryFilter<T> = QueryFilterV9<T> | QueryFilterV8<T>;
-
-export interface RepositoryOptions {
-  session?: ClientSession;
-  populate?: string | string[] | any;
-  select?: string | any;
-  lean?: boolean;
-  throwOnNotFound?: boolean;
-  updatePipeline?: 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: CompatibleQueryFilter<T>, options?: RepositoryOptions): Promise<T | null>;
-  getAll(queryParams?: QueryParams, options?: RepositoryOptions): Promise<PaginateResult<T>>;
-  getOrCreate(query: CompatibleQueryFilter<T>, createData: Partial<T>, options?: RepositoryOptions): Promise<T>;
-  
-  count(query?: CompatibleQueryFilter<T>, options?: RepositoryOptions): Promise<number>;
-  exists(query: CompatibleQueryFilter<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?: CompatibleQueryFilter<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

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

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