@classytic/mongokit 3.1.0 → 3.1.2

package/dist/plugins/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FieldPreset, u as Plugin, L as Logger, I as SoftDeleteOptions, w as RepositoryInstance, B as ValidatorDefinition, G as ValidationChainOptions, m as RepositoryContext, X as CacheOptions, $ as CascadeOptions } from '../types-CrSoCuWu.js';
-import 'mongoose';
+import { F as FieldPreset, G as Plugin, a2 as Logger, a3 as SoftDeleteOptions, k as ObjectId, f as SortSpec, S as SelectSpec, e as PopulateSpec, a as OffsetPaginationResult, L as RepositoryInstance, a0 as ValidatorDefinition, a1 as ValidationChainOptions, m as RepositoryContext, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions } from '../types-B5Uv6Ak7.js';
+import { ClientSession } from 'mongoose';
 
 /**
  * Field Filter Plugin
@@ -92,6 +92,53 @@ declare function auditLogPlugin(logger: Logger): Plugin;
  * ```
  */
 declare function softDeletePlugin(options?: SoftDeleteOptions): Plugin;
+/**
+ * TypeScript interface for soft delete plugin methods
+ *
+ * @example
+ * ```typescript
+ * import type { SoftDeleteMethods } from '@classytic/mongokit';
+ *
+ * type UserRepoWithSoftDelete = UserRepo & SoftDeleteMethods<IUser>;
+ *
+ * const userRepo = new UserRepo(UserModel, [
+ *   methodRegistryPlugin(),
+ *   softDeletePlugin({ deletedField: 'deletedAt' }),
+ * ]) as UserRepoWithSoftDelete;
+ *
+ * // TypeScript autocomplete for soft delete methods
+ * await userRepo.restore(userId);
+ * const deleted = await userRepo.getDeleted({ page: 1, limit: 20 });
+ * ```
+ */
+interface SoftDeleteMethods<TDoc> {
+    /**
+     * Restore a soft-deleted document
+     * @param id - Document ID to restore
+     * @param options - Optional restore options
+     * @returns Restored document
+     */
+    restore(id: string | ObjectId, options?: {
+        session?: ClientSession;
+    }): Promise<TDoc>;
+    /**
+     * Get paginated list of soft-deleted documents
+     * @param params - Query parameters (filters, sort, pagination)
+     * @param options - Query options (select, populate, lean, session)
+     * @returns Paginated result of deleted documents
+     */
+    getDeleted(params?: {
+        filters?: Record<string, unknown>;
+        sort?: SortSpec | string;
+        page?: number;
+        limit?: number;
+    }, options?: {
+        select?: SelectSpec;
+        populate?: PopulateSpec;
+        lean?: boolean;
+        session?: ClientSession;
+    }): Promise<OffsetPaginationResult<TDoc>>;
+}
 
 /**
  * Method Registry Plugin
@@ -178,16 +225,189 @@ declare function uniqueField(field: string, errorMessage?: string): ValidatorDef
 /**
  * MongoDB operations plugin
  *
- * @example
- * const repo = new Repository(Model, [
+ * Adds MongoDB-specific atomic operations to repositories:
+ * - upsert: Create or update document
+ * - increment/decrement: Atomic numeric operations
+ * - pushToArray/pullFromArray/addToSet: Array operations
+ * - setField/unsetField/renameField: Field operations
+ * - multiplyField: Multiply numeric field
+ * - setMin/setMax: Conditional min/max updates
+ *
+ * @example Basic usage (no TypeScript autocomplete)
+ * ```typescript
+ * const repo = new Repository(ProductModel, [
  *   methodRegistryPlugin(),
  *   mongoOperationsPlugin(),
  * ]);
  *
+ * // Works at runtime but TypeScript doesn't know about these methods
+ * await (repo as any).increment(productId, 'views', 1);
+ * await (repo as any).pushToArray(productId, 'tags', 'featured');
+ * ```
+ *
+ * @example With TypeScript type safety (recommended)
+ * ```typescript
+ * import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
+ * import type { MongoOperationsMethods } from '@classytic/mongokit';
+ *
+ * class ProductRepo extends Repository<IProduct> {
+ *   // Add your custom methods here
+ * }
+ *
+ * // Create with type assertion to get autocomplete for plugin methods
+ * type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;
+ *
+ * const repo = new ProductRepo(ProductModel, [
+ *   methodRegistryPlugin(),
+ *   mongoOperationsPlugin(),
+ * ]) as ProductRepoWithPlugins;
+ *
+ * // Now TypeScript provides autocomplete and type checking!
  * await repo.increment(productId, 'views', 1);
+ * await repo.upsert({ sku: 'ABC' }, { name: 'Product', price: 99 });
  * await repo.pushToArray(productId, 'tags', 'featured');
+ * ```
  */
 declare function mongoOperationsPlugin(): Plugin;
+/**
+ * Type interface for repositories using mongoOperationsPlugin
+ *
+ * Use this interface to get TypeScript autocomplete and type safety
+ * for the methods added by mongoOperationsPlugin.
+ *
+ * @example
+ * ```typescript
+ * import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
+ * import type { MongoOperationsMethods } from '@classytic/mongokit';
+ *
+ * // Without type safety (base is flexible)
+ * class ProductRepo extends Repository<IProduct> {
+ *   // Can add anything - fully flexible
+ * }
+ *
+ * // With type safety for plugin methods
+ * class ProductRepo extends Repository<IProduct> implements MongoOperationsMethods<IProduct> {
+ *   // TypeScript knows about upsert, increment, decrement, etc.
+ * }
+ *
+ * const repo = new ProductRepo(ProductModel, [
+ *   methodRegistryPlugin(),
+ *   mongoOperationsPlugin(),
+ * ]);
+ *
+ * // Now TypeScript provides autocomplete and type checking
+ * await repo.increment(productId, 'views', 1);
+ * await repo.upsert({ sku: 'ABC' }, { name: 'Product' });
+ * ```
+ */
+interface MongoOperationsMethods<TDoc> {
+    /**
+     * Update existing document or insert new one
+     * @param query - Query to find document
+     * @param data - Data to update or insert
+     * @param options - Operation options (session, etc.)
+     * @returns Created or updated document
+     */
+    upsert(query: Record<string, unknown>, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Atomically increment numeric field
+     * @param id - Document ID
+     * @param field - Field name to increment
+     * @param value - Value to increment by (default: 1)
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    increment(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Atomically decrement numeric field
+     * @param id - Document ID
+     * @param field - Field name to decrement
+     * @param value - Value to decrement by (default: 1)
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    decrement(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Push value to array field
+     * @param id - Document ID
+     * @param field - Array field name
+     * @param value - Value to push
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    pushToArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Remove value from array field
+     * @param id - Document ID
+     * @param field - Array field name
+     * @param value - Value to remove
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    pullFromArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Add value to array only if not already present (unique)
+     * @param id - Document ID
+     * @param field - Array field name
+     * @param value - Value to add
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    addToSet(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Set field value (alias for update with $set)
+     * @param id - Document ID
+     * @param field - Field name
+     * @param value - Value to set
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    setField(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Unset (remove) field from document
+     * @param id - Document ID
+     * @param fields - Field name or array of field names to remove
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    unsetField(id: string | ObjectId, fields: string | string[], options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Rename field in document
+     * @param id - Document ID
+     * @param oldName - Current field name
+     * @param newName - New field name
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    renameField(id: string | ObjectId, oldName: string, newName: string, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Multiply numeric field by value
+     * @param id - Document ID
+     * @param field - Field name
+     * @param multiplier - Multiplier value
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    multiplyField(id: string | ObjectId, field: string, multiplier: number, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Set field to minimum value (only if current value is greater)
+     * @param id - Document ID
+     * @param field - Field name
+     * @param value - Minimum value
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    setMin(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Set field to maximum value (only if current value is less)
+     * @param id - Document ID
+     * @param field - Field name
+     * @param value - Maximum value
+     * @param options - Operation options (session, etc.)
+     * @returns Updated document
+     */
+    setMax(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+}
 
 /**
  * Batch Operations Plugin
@@ -207,6 +427,57 @@ declare function mongoOperationsPlugin(): Plugin;
  * await repo.deleteMany({ status: 'deleted' });
  */
 declare function batchOperationsPlugin(): Plugin;
+/**
+ * Type interface for repositories using batchOperationsPlugin
+ *
+ * @example
+ * ```typescript
+ * import { Repository, methodRegistryPlugin, batchOperationsPlugin } from '@classytic/mongokit';
+ * import type { BatchOperationsMethods } from '@classytic/mongokit';
+ *
+ * class ProductRepo extends Repository<IProduct> {}
+ *
+ * type ProductRepoWithBatch = ProductRepo & BatchOperationsMethods;
+ *
+ * const repo = new ProductRepo(ProductModel, [
+ *   methodRegistryPlugin(),
+ *   batchOperationsPlugin(),
+ * ]) as ProductRepoWithBatch;
+ *
+ * // TypeScript autocomplete works!
+ * await repo.updateMany({ status: 'pending' }, { status: 'active' });
+ * await repo.deleteMany({ status: 'archived' });
+ * ```
+ */
+interface BatchOperationsMethods {
+    /**
+     * Update multiple documents matching the query
+     * @param query - Query to match documents
+     * @param data - Update data
+     * @param options - Operation options
+     * @returns Update result with matchedCount, modifiedCount, etc.
+     */
+    updateMany(query: Record<string, unknown>, data: Record<string, unknown>, options?: {
+        session?: ClientSession;
+        updatePipeline?: boolean;
+    }): Promise<{
+        acknowledged: boolean;
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedCount: number;
+        upsertedId: unknown;
+    }>;
+    /**
+     * Delete multiple documents matching the query
+     * @param query - Query to match documents
+     * @param options - Operation options
+     * @returns Delete result with deletedCount
+     */
+    deleteMany(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<{
+        acknowledged: boolean;
+        deletedCount: number;
+    }>;
+}
 
 /**
  * Aggregate Helpers Plugin
@@ -226,6 +497,76 @@ declare function batchOperationsPlugin(): Plugin;
  * const total = await repo.sum('amount', { status: 'completed' });
  */
 declare function aggregateHelpersPlugin(): Plugin;
+/**
+ * Type interface for repositories using aggregateHelpersPlugin
+ *
+ * @example
+ * ```typescript
+ * import { Repository, methodRegistryPlugin, aggregateHelpersPlugin } from '@classytic/mongokit';
+ * import type { AggregateHelpersMethods } from '@classytic/mongokit';
+ *
+ * class OrderRepo extends Repository<IOrder> {}
+ *
+ * type OrderRepoWithAggregates = OrderRepo & AggregateHelpersMethods;
+ *
+ * const repo = new OrderRepo(OrderModel, [
+ *   methodRegistryPlugin(),
+ *   aggregateHelpersPlugin(),
+ * ]) as OrderRepoWithAggregates;
+ *
+ * // TypeScript autocomplete works!
+ * const groups = await repo.groupBy('status');
+ * const total = await repo.sum('amount', { status: 'completed' });
+ * const avg = await repo.average('amount');
+ * ```
+ */
+interface AggregateHelpersMethods {
+    /**
+     * Group documents by field value and count occurrences
+     * @param field - Field to group by
+     * @param options - Operation options
+     * @returns Array of groups with _id and count
+     */
+    groupBy(field: string, options?: {
+        limit?: number;
+        session?: unknown;
+    }): Promise<Array<{
+        _id: unknown;
+        count: number;
+    }>>;
+    /**
+     * Calculate sum of field values
+     * @param field - Field to sum
+     * @param query - Filter query
+     * @param options - Operation options
+     * @returns Sum of field values
+     */
+    sum(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Calculate average of field values
+     * @param field - Field to average
+     * @param query - Filter query
+     * @param options - Operation options
+     * @returns Average of field values
+     */
+    average(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Get minimum field value
+     * @param field - Field to get minimum from
+     * @param query - Filter query
+     * @param options - Operation options
+     * @returns Minimum field value
+     */
+    min(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    /**
+     * Get maximum field value
+     * @param field - Field to get maximum from
+     * @param query - Filter query
+     * @param options - Operation options
+     * @returns Maximum field value
+     */
+    max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+}
 
 /**
  * Subdocument Plugin
@@ -245,6 +586,73 @@ declare function aggregateHelpersPlugin(): Plugin;
  * await repo.updateSubdocument(parentId, 'items', itemId, { name: 'Updated Item' });
  */
 declare function subdocumentPlugin(): Plugin;
+/**
+ * Type interface for repositories using subdocumentPlugin
+ *
+ * @example
+ * ```typescript
+ * import { Repository, methodRegistryPlugin, subdocumentPlugin } from '@classytic/mongokit';
+ * import type { SubdocumentMethods } from '@classytic/mongokit';
+ *
+ * class OrderRepo extends Repository<IOrder> {}
+ *
+ * type OrderRepoWithSubdocs = OrderRepo & SubdocumentMethods<IOrder>;
+ *
+ * const repo = new OrderRepo(OrderModel, [
+ *   methodRegistryPlugin(),
+ *   subdocumentPlugin(),
+ * ]) as OrderRepoWithSubdocs;
+ *
+ * // TypeScript autocomplete works!
+ * await repo.addSubdocument(orderId, 'items', { productId: '123', quantity: 2 });
+ * await repo.updateSubdocument(orderId, 'items', itemId, { quantity: 5 });
+ * await repo.deleteSubdocument(orderId, 'items', itemId);
+ * ```
+ */
+interface SubdocumentMethods<TDoc> {
+    /**
+     * Add subdocument to array field
+     * @param parentId - Parent document ID
+     * @param arrayPath - Path to array field (e.g., 'items', 'addresses')
+     * @param subData - Subdocument data
+     * @param options - Operation options
+     * @returns Updated parent document
+     */
+    addSubdocument(parentId: string | ObjectId, arrayPath: string, subData: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+    /**
+     * Get subdocument from array field
+     * @param parentId - Parent document ID
+     * @param arrayPath - Path to array field
+     * @param subId - Subdocument ID
+     * @param options - Operation options
+     * @returns Subdocument
+     */
+    getSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: {
+        lean?: boolean;
+        session?: unknown;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Update subdocument in array field
+     * @param parentId - Parent document ID
+     * @param arrayPath - Path to array field
+     * @param subId - Subdocument ID
+     * @param updateData - Update data
+     * @param options - Operation options
+     * @returns Updated parent document
+     */
+    updateSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, updateData: Record<string, unknown>, options?: {
+        session?: unknown;
+    }): Promise<TDoc>;
+    /**
+     * Delete subdocument from array field
+     * @param parentId - Parent document ID
+     * @param arrayPath - Path to array field
+     * @param subId - Subdocument ID
+     * @param options - Operation options
+     * @returns Updated parent document
+     */
+    deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
+}
 
 /**
  * Cache Plugin
@@ -303,6 +711,55 @@ declare function subdocumentPlugin(): Plugin;
  * @returns Plugin instance
  */
 declare function cachePlugin(options: CacheOptions): Plugin;
+/**
+ * TypeScript interface for cache plugin methods
+ *
+ * @example
+ * ```typescript
+ * import type { CacheMethods } from '@classytic/mongokit';
+ *
+ * type ProductRepoWithCache = ProductRepo & CacheMethods;
+ *
+ * const productRepo = new ProductRepo(ProductModel, [
+ *   methodRegistryPlugin(),
+ *   cachePlugin({ adapter: redisAdapter, ttl: 60 }),
+ * ]) as ProductRepoWithCache;
+ *
+ * // TypeScript autocomplete for cache methods
+ * await productRepo.invalidateCache(productId);
+ * await productRepo.invalidateListCache();
+ * await productRepo.invalidateAllCache();
+ * const stats = productRepo.getCacheStats();
+ * productRepo.resetCacheStats();
+ * ```
+ */
+interface CacheMethods {
+    /**
+     * Invalidate cache for a specific document
+     * Use when document was updated outside this service
+     * @param id - Document ID to invalidate
+     */
+    invalidateCache(id: string): Promise<void>;
+    /**
+     * Invalidate all list caches for this model
+     * Use when bulk changes happened outside this service
+     */
+    invalidateListCache(): Promise<void>;
+    /**
+     * Invalidate ALL cache entries for this model
+     * Nuclear option - use sparingly
+     */
+    invalidateAllCache(): Promise<void>;
+    /**
+     * Get cache statistics for monitoring
+     * @returns Cache statistics (hits, misses, sets, invalidations)
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Reset cache statistics
+     */
+    resetCacheStats(): void;
+}
 
 /**
  * Cascade Delete Plugin
@@ -339,4 +796,4 @@ declare function cachePlugin(options: CacheOptions): Plugin;
  */
 declare function cascadePlugin(options: CascadeOptions): Plugin;
 
-export { type MethodRegistryRepository, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };
+export { type AggregateHelpersMethods, type BatchOperationsMethods, type CacheMethods, type MethodRegistryRepository, type MongoOperationsMethods, type SoftDeleteMethods, type SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };