@classytic/mongokit 2.0.0 → 3.0.0

package/dist/index-CgOJ2pqz.d.ts

@@ -0,0 +1,337 @@
+import { Model, ClientSession, PipelineStage } from 'mongoose';
+import { A as AnyDocument, C as CreateOptions, l as OperationOptions, S as SelectSpec, f as PopulateSpec, g as SortSpec, U as UpdateOptions, n as UpdateWithValidationResult, m as UpdateManyResult, D as DeleteResult, I as GroupResult, G as LookupOptions, M as MinMaxResult } from './types-Nxhmi1aI.js';
+
+/**
+ * Create Actions
+ * Pure functions for document creation
+ */
+
+/**
+ * Create single document
+ */
+declare function create<TDoc = AnyDocument>(Model: Model<TDoc>, data: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
+/**
+ * Create multiple documents
+ */
+declare function createMany<TDoc = AnyDocument>(Model: Model<TDoc>, dataArray: Record<string, unknown>[], options?: CreateOptions): Promise<TDoc[]>;
+/**
+ * Create with defaults (useful for initialization)
+ */
+declare function createDefault<TDoc = AnyDocument>(Model: Model<TDoc>, overrides?: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
+/**
+ * Upsert (create or update)
+ */
+declare function upsert<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    updatePipeline?: boolean;
+}): Promise<TDoc | null>;
+
+declare const create$1_create: typeof create;
+declare const create$1_createDefault: typeof createDefault;
+declare const create$1_createMany: typeof createMany;
+declare const create$1_upsert: typeof upsert;
+declare namespace create$1 {
+  export { create$1_create as create, create$1_createDefault as createDefault, create$1_createMany as createMany, create$1_upsert as upsert };
+}
+
+/**
+ * Read Actions
+ * Pure functions for document retrieval
+ */
+
+/**
+ * Get document by ID
+ *
+ * @param Model - Mongoose model
+ * @param id - Document ID
+ * @param options - Query options
+ * @returns Document or null
+ * @throws Error if document not found and throwOnNotFound is true
+ */
+declare function getById<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, options?: OperationOptions): Promise<TDoc | null>;
+/**
+ * Get document by query
+ *
+ * @param Model - Mongoose model
+ * @param query - MongoDB query
+ * @param options - Query options
+ * @returns Document or null
+ * @throws Error if document not found and throwOnNotFound is true
+ */
+declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions): Promise<TDoc | null>;
+/**
+ * Get document by query without throwing (returns null if not found)
+ */
+declare function tryGetByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: Omit<OperationOptions, 'throwOnNotFound'>): Promise<TDoc | null>;
+/**
+ * Get all documents (basic query without pagination)
+ * For pagination, use Repository.paginate() or Repository.stream()
+ */
+declare function getAll<TDoc = AnyDocument>(Model: Model<TDoc>, query?: Record<string, unknown>, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    sort?: SortSpec;
+    limit?: number;
+    skip?: number;
+    lean?: boolean;
+    session?: ClientSession;
+}): Promise<TDoc[]>;
+/**
+ * Get or create document (upsert)
+ */
+declare function getOrCreate<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    updatePipeline?: boolean;
+}): Promise<TDoc | null>;
+/**
+ * Count documents matching query
+ */
+declare function count(Model: Model<any>, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<number>;
+/**
+ * Check if document exists
+ */
+declare function exists(Model: Model<any>, query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<{
+    _id: unknown;
+} | null>;
+
+declare const read_count: typeof count;
+declare const read_exists: typeof exists;
+declare const read_getAll: typeof getAll;
+declare const read_getById: typeof getById;
+declare const read_getByQuery: typeof getByQuery;
+declare const read_getOrCreate: typeof getOrCreate;
+declare const read_tryGetByQuery: typeof tryGetByQuery;
+declare namespace read {
+  export { read_count as count, read_exists as exists, read_getAll as getAll, read_getById as getById, read_getByQuery as getByQuery, read_getOrCreate as getOrCreate, read_tryGetByQuery as tryGetByQuery };
+}
+
+/**
+ * Update Actions
+ * Pure functions for document updates with optimizations
+ */
+
+/**
+ * Update by ID
+ */
+declare function update<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
+/**
+ * Update with query constraints (optimized)
+ * Returns null if constraints not met (not an error)
+ */
+declare function updateWithConstraints<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, data: Record<string, unknown>, constraints?: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
+/**
+ * Validation options for smart update
+ */
+interface ValidationOptions {
+    buildConstraints?: (data: Record<string, unknown>) => Record<string, unknown>;
+    validateUpdate?: (existing: Record<string, unknown>, data: Record<string, unknown>) => {
+        valid: boolean;
+        message?: string;
+        violations?: Array<{
+            field: string;
+            reason: string;
+        }>;
+    };
+}
+/**
+ * Update with validation (smart optimization)
+ * 1-query on success, 2-queries for detailed errors
+ */
+declare function updateWithValidation<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, data: Record<string, unknown>, validationOptions?: ValidationOptions, options?: UpdateOptions): Promise<UpdateWithValidationResult<TDoc>>;
+/**
+ * Update many documents
+ */
+declare function updateMany(Model: Model<unknown>, query: Record<string, unknown>, data: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    updatePipeline?: boolean;
+}): Promise<UpdateManyResult>;
+/**
+ * Update by query
+ */
+declare function updateByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
+/**
+ * Increment field
+ */
+declare function increment<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, field: string, value?: number, options?: UpdateOptions): Promise<TDoc>;
+/**
+ * Push to array
+ */
+declare function pushToArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
+/**
+ * Pull from array
+ */
+declare function pullFromArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
+
+declare const update$1_increment: typeof increment;
+declare const update$1_pullFromArray: typeof pullFromArray;
+declare const update$1_pushToArray: typeof pushToArray;
+declare const update$1_update: typeof update;
+declare const update$1_updateByQuery: typeof updateByQuery;
+declare const update$1_updateMany: typeof updateMany;
+declare const update$1_updateWithConstraints: typeof updateWithConstraints;
+declare const update$1_updateWithValidation: typeof updateWithValidation;
+declare namespace update$1 {
+  export { update$1_increment as increment, update$1_pullFromArray as pullFromArray, update$1_pushToArray as pushToArray, update$1_update as update, update$1_updateByQuery as updateByQuery, update$1_updateMany as updateMany, update$1_updateWithConstraints as updateWithConstraints, update$1_updateWithValidation as updateWithValidation };
+}
+
+/**
+ * Delete Actions
+ * Pure functions for document deletion
+ */
+
+/**
+ * Delete by ID
+ */
+declare function deleteById(Model: Model<any>, id: string, options?: {
+    session?: ClientSession;
+}): Promise<DeleteResult>;
+/**
+ * Delete many documents
+ */
+declare function deleteMany(Model: Model<any>, query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<DeleteResult>;
+/**
+ * Delete by query
+ */
+declare function deleteByQuery(Model: Model<any>, query: Record<string, unknown>, options?: {
+    session?: ClientSession;
+    throwOnNotFound?: boolean;
+}): Promise<DeleteResult>;
+/**
+ * Soft delete (set deleted flag)
+ */
+declare function softDelete<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, options?: {
+    session?: ClientSession;
+    userId?: string;
+}): Promise<DeleteResult>;
+/**
+ * Restore soft deleted document
+ */
+declare function restore<TDoc = AnyDocument>(Model: Model<TDoc>, id: string, options?: {
+    session?: ClientSession;
+}): Promise<DeleteResult>;
+
+declare const _delete_deleteById: typeof deleteById;
+declare const _delete_deleteByQuery: typeof deleteByQuery;
+declare const _delete_deleteMany: typeof deleteMany;
+declare const _delete_restore: typeof restore;
+declare const _delete_softDelete: typeof softDelete;
+declare namespace _delete {
+  export { _delete_deleteById as deleteById, _delete_deleteByQuery as deleteByQuery, _delete_deleteMany as deleteMany, _delete_restore as restore, _delete_softDelete as softDelete };
+}
+
+/**
+ * Aggregate Actions
+ * MongoDB aggregation pipeline operations
+ */
+
+/**
+ * Execute aggregation pipeline
+ */
+declare function aggregate<TResult = unknown>(Model: Model<any>, pipeline: PipelineStage[], options?: {
+    session?: ClientSession;
+}): Promise<TResult[]>;
+/**
+ * Aggregate with pagination using native MongoDB $facet
+ * WARNING: $facet results must be <16MB. For larger results (limit >1000),
+ * consider using Repository.aggregatePaginate() or splitting into separate queries.
+ */
+declare function aggregatePaginate<TDoc = AnyDocument>(Model: Model<TDoc>, pipeline: PipelineStage[], options?: {
+    page?: number;
+    limit?: number;
+    session?: ClientSession;
+}): Promise<{
+    docs: TDoc[];
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}>;
+/**
+ * Group documents by field value
+ */
+declare function groupBy(Model: Model<any>, field: string, options?: {
+    limit?: number;
+    session?: ClientSession;
+}): Promise<GroupResult[]>;
+/**
+ * Count by field values
+ */
+declare function countBy(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<GroupResult[]>;
+/**
+ * Lookup (join) with another collection
+ */
+declare function lookup<TDoc = AnyDocument>(Model: Model<TDoc>, lookupOptions: LookupOptions): Promise<TDoc[]>;
+/**
+ * Unwind array field
+ */
+declare function unwind<TDoc = AnyDocument>(Model: Model<TDoc>, field: string, options?: {
+    preserveEmpty?: boolean;
+    session?: ClientSession;
+}): Promise<TDoc[]>;
+/**
+ * Facet search (multiple aggregations in one query)
+ */
+declare function facet<TResult = Record<string, unknown[]>>(Model: Model<any>, facets: Record<string, PipelineStage[]>, options?: {
+    session?: ClientSession;
+}): Promise<TResult[]>;
+/**
+ * Get distinct values
+ */
+declare function distinct<T = unknown>(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<T[]>;
+/**
+ * Calculate sum
+ */
+declare function sum(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<number>;
+/**
+ * Calculate average
+ */
+declare function average(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<number>;
+/**
+ * Min/Max
+ */
+declare function minMax(Model: Model<any>, field: string, query?: Record<string, unknown>, options?: {
+    session?: ClientSession;
+}): Promise<MinMaxResult>;
+
+declare const aggregate$1_aggregate: typeof aggregate;
+declare const aggregate$1_aggregatePaginate: typeof aggregatePaginate;
+declare const aggregate$1_average: typeof average;
+declare const aggregate$1_countBy: typeof countBy;
+declare const aggregate$1_distinct: typeof distinct;
+declare const aggregate$1_facet: typeof facet;
+declare const aggregate$1_groupBy: typeof groupBy;
+declare const aggregate$1_lookup: typeof lookup;
+declare const aggregate$1_minMax: typeof minMax;
+declare const aggregate$1_sum: typeof sum;
+declare const aggregate$1_unwind: typeof unwind;
+declare namespace aggregate$1 {
+  export { aggregate$1_aggregate as aggregate, aggregate$1_aggregatePaginate as aggregatePaginate, aggregate$1_average as average, aggregate$1_countBy as countBy, aggregate$1_distinct as distinct, aggregate$1_facet as facet, aggregate$1_groupBy as groupBy, aggregate$1_lookup as lookup, aggregate$1_minMax as minMax, aggregate$1_sum as sum, aggregate$1_unwind as unwind };
+}
+
+/**
+ * Repository Actions
+ * Modular, composable data access operations
+ */
+
+declare const index_read: typeof read;
+declare namespace index {
+  export { aggregate$1 as aggregate, create$1 as create, _delete as deleteActions, index_read as read, update$1 as update };
+}
+
+export { _delete as _, aggregate$1 as a, create$1 as c, index as i, read as r, update$1 as u };

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+import { A as AnyDocument, e as PluginType, P as PaginationConfig, S as SelectSpec, f as PopulateSpec, g as SortSpec, a as OffsetPaginationResult, b as KeysetPaginationResult, d as AggregatePaginationResult, R as RepositoryContext, H as HttpError } from './types-Nxhmi1aI.js';
+export { c as AggregatePaginationOptions, i as AnyModel, N as CacheAdapter, T as CacheOperationOptions, Q as CacheOptions, W as CacheStats, C as CreateOptions, w as CrudSchemas, x as DecodedCursor, D as DeleteResult, E as EventPayload, F as FieldPreset, u as FieldRules, I as GroupResult, J as JsonSchema, K as KeysetPaginationOptions, L as Logger, G as LookupOptions, M as MinMaxResult, h as ObjectId, O as OffsetPaginationOptions, l as OperationOptions, k as PaginationResult, t as ParsedQuery, p as Plugin, q as PluginFunction, s as RepositoryEvent, r as RepositoryInstance, v as SchemaBuilderOptions, B as SoftDeleteOptions, j as SortDirection, m as UpdateManyResult, U as UpdateOptions, n as UpdateWithValidationResult, o as UserContext, z as ValidationChainOptions, V as ValidationResult, y as ValidatorDefinition } from './types-Nxhmi1aI.js';
+import * as mongoose from 'mongoose';
+import { Model, ClientSession, PipelineStage, PopulateOptions } from 'mongoose';
+import { PaginationEngine } from './pagination/PaginationEngine.js';
+export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
+export { b as createError, c as createFieldPreset, d as createMemoryCache, f as filterResponseData, g as getFieldsForUser, a as getMongooseProjection } from './memory-cache-DG2oSSbx.js';
+export { i as actions } from './index-CgOJ2pqz.js';
+
+/**
+ * Repository Pattern - Data Access Layer
+ *
+ * Event-driven, plugin-based abstraction for MongoDB operations
+ * Inspired by Meta & Stripe's repository patterns
+ *
+ * @example
+ * ```typescript
+ * const userRepo = new Repository(UserModel, [
+ *   timestampPlugin(),
+ *   softDeletePlugin(),
+ * ]);
+ *
+ * // Create
+ * const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
+ *
+ * // Read with pagination
+ * const users = await userRepo.getAll({ page: 1, limit: 20, filters: { status: 'active' } });
+ *
+ * // Update
+ * const updated = await userRepo.update(user._id, { name: 'John Doe' });
+ *
+ * // Delete
+ * await userRepo.delete(user._id);
+ * ```
+ */
+
+type HookListener = (data: any) => void | Promise<void>;
+/**
+ * Production-grade repository for MongoDB
+ * Event-driven, plugin-based, with smart pagination
+ */
+declare class Repository<TDoc = AnyDocument> {
+    readonly Model: Model<TDoc>;
+    readonly model: string;
+    readonly _hooks: Map<string, HookListener[]>;
+    readonly _pagination: PaginationEngine<TDoc>;
+    [key: string]: unknown;
+    constructor(Model: Model<TDoc>, plugins?: PluginType[], paginationConfig?: PaginationConfig);
+    /**
+     * Register a plugin
+     */
+    use(plugin: PluginType): this;
+    /**
+     * Register event listener
+     */
+    on(event: string, listener: HookListener): this;
+    /**
+     * Emit event
+     */
+    emit(event: string, data: unknown): void;
+    /**
+     * Create single document
+     */
+    create(data: Record<string, unknown>, options?: {
+        session?: ClientSession;
+    }): Promise<TDoc>;
+    /**
+     * Create multiple documents
+     */
+    createMany(dataArray: Record<string, unknown>[], options?: {
+        session?: ClientSession;
+        ordered?: boolean;
+    }): Promise<TDoc[]>;
+    /**
+     * Get document by ID
+     */
+    getById(id: string, options?: {
+        select?: SelectSpec;
+        populate?: PopulateSpec;
+        lean?: boolean;
+        session?: ClientSession;
+        throwOnNotFound?: boolean;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    }): Promise<TDoc | null>;
+    /**
+     * Get single document by query
+     */
+    getByQuery(query: Record<string, unknown>, options?: {
+        select?: SelectSpec;
+        populate?: PopulateSpec;
+        lean?: boolean;
+        session?: ClientSession;
+        throwOnNotFound?: boolean;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    }): Promise<TDoc | null>;
+    /**
+     * 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
+     *
+     * @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' } });
+     *
+     * // Skip cache for fresh data
+     * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
+     */
+    getAll(params?: {
+        filters?: Record<string, unknown>;
+        sort?: SortSpec | string;
+        cursor?: string;
+        after?: string;
+        page?: number;
+        pagination?: {
+            page?: number;
+            limit?: number;
+        };
+        limit?: number;
+        search?: string;
+    }, options?: {
+        select?: SelectSpec;
+        populate?: PopulateSpec;
+        lean?: boolean;
+        session?: ClientSession;
+        skipCache?: boolean;
+        cacheTtl?: number;
+    }): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc>>;
+    /**
+     * Get or create document
+     */
+    getOrCreate(query: Record<string, unknown>, createData: Record<string, unknown>, options?: {
+        session?: ClientSession;
+    }): Promise<TDoc | null>;
+    /**
+     * Count documents
+     */
+    count(query?: Record<string, unknown>, options?: {
+        session?: ClientSession;
+    }): Promise<number>;
+    /**
+     * Check if document exists
+     */
+    exists(query: Record<string, unknown>, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        _id: unknown;
+    } | null>;
+    /**
+     * Update document by ID
+     */
+    update(id: string, data: Record<string, unknown>, options?: {
+        select?: SelectSpec;
+        populate?: PopulateSpec;
+        lean?: boolean;
+        session?: ClientSession;
+    }): Promise<TDoc>;
+    /**
+     * Delete document by ID
+     */
+    delete(id: string, options?: {
+        session?: ClientSession;
+    }): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Execute aggregation pipeline
+     */
+    aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: {
+        session?: ClientSession;
+    }): Promise<TResult[]>;
+    /**
+     * Aggregate pipeline with pagination
+     * Best for: Complex queries, grouping, joins
+     */
+    aggregatePaginate(options?: {
+        pipeline?: PipelineStage[];
+        page?: number;
+        limit?: number;
+        session?: ClientSession;
+    }): Promise<AggregatePaginationResult<TDoc>>;
+    /**
+     * Get distinct values
+     */
+    distinct<T = unknown>(field: string, query?: Record<string, unknown>, options?: {
+        session?: ClientSession;
+    }): Promise<T[]>;
+    /**
+     * Execute callback within a transaction
+     */
+    withTransaction<T>(callback: (session: ClientSession) => Promise<T>): Promise<T>;
+    /**
+     * Execute custom query with event emission
+     */
+    _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
+    /**
+     * Build operation context and run before hooks
+     */
+    _buildContext(operation: string, options: Record<string, unknown>): Promise<RepositoryContext>;
+    /**
+     * Parse sort string or object
+     */
+    _parseSort(sort: SortSpec | string | undefined): SortSpec;
+    /**
+     * Parse populate specification
+     */
+    _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
+    /**
+     * Handle errors with proper HTTP status codes
+     */
+    _handleError(error: Error): HttpError;
+}
+
+/**
+ * Factory function to create a repository instance
+ *
+ * @param Model - Mongoose model
+ * @param plugins - Array of plugins to apply
+ * @returns Repository instance
+ *
+ * @example
+ * const userRepo = createRepository(UserModel, [timestampPlugin()]);
+ */
+declare function createRepository<TDoc>(Model: mongoose.Model<TDoc>, plugins?: PluginType[]): Repository<TDoc>;
+
+export { AggregatePaginationResult, AnyDocument, HttpError, KeysetPaginationResult, OffsetPaginationResult, PaginationConfig, PaginationEngine, PluginType, PopulateSpec, Repository, RepositoryContext, SelectSpec, SortSpec, createRepository, Repository as default };