@classytic/mongokit 3.1.1 → 3.1.3

package/README.md

@@ -297,6 +297,94 @@ const repo = new Repository(UserModel, [
 ]);
 ```
 
+### MongoDB Operations Plugin
+
+The `mongoOperationsPlugin` adds MongoDB-specific atomic operations like `increment`, `upsert`, `pushToArray`, etc.
+
+#### Basic Usage (No TypeScript Autocomplete)
+
+```javascript
+import { Repository, methodRegistryPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
+
+const repo = new Repository(ProductModel, [
+  methodRegistryPlugin(),  // Required first
+  mongoOperationsPlugin()
+]);
+
+// Works at runtime but TypeScript doesn't provide autocomplete
+await repo.increment(productId, 'views', 1);
+await repo.upsert({ sku: 'ABC' }, { name: 'Product', price: 99 });
+```
+
+#### With TypeScript Type Safety (Recommended)
+
+For full TypeScript autocomplete and type checking, use the `MongoOperationsMethods` type:
+
+```typescript
+import { Repository, methodRegistryPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
+import type { MongoOperationsMethods } from '@classytic/mongokit';
+
+// 1. Create your repository class
+class ProductRepo extends Repository<IProduct> {
+  // Add custom methods here
+  async findBySku(sku: string) {
+    return this.getByQuery({ sku });
+  }
+}
+
+// 2. Create type helper for autocomplete
+type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;
+
+// 3. Instantiate with type assertion
+const repo = new ProductRepo(ProductModel, [
+  methodRegistryPlugin(),
+  mongoOperationsPlugin()
+]) as ProductRepoWithPlugins;
+
+// 4. Now TypeScript provides full autocomplete and type checking!
+await repo.increment(productId, 'views', 1);           // ✅ Autocomplete works
+await repo.upsert({ sku: 'ABC' }, { name: 'Product' }); // ✅ Type-safe
+await repo.pushToArray(productId, 'tags', 'featured'); // ✅ Validated
+await repo.findBySku('ABC');                           // ✅ Custom methods too
+```
+
+**Available operations:**
+- `upsert(query, data, opts)` - Create or find document
+- `increment(id, field, value, opts)` - Atomically increment field
+- `decrement(id, field, value, opts)` - Atomically decrement field
+- `pushToArray(id, field, value, opts)` - Add to array
+- `pullFromArray(id, field, value, opts)` - Remove from array
+- `addToSet(id, field, value, opts)` - Add unique value to array
+- `setField(id, field, value, opts)` - Set field value
+- `unsetField(id, fields, opts)` - Remove field(s)
+- `renameField(id, oldName, newName, opts)` - Rename field
+- `multiplyField(id, field, multiplier, opts)` - Multiply numeric field
+- `setMin(id, field, value, opts)` - Set to min (if current > value)
+- `setMax(id, field, value, opts)` - Set to max (if current < value)
+
+### Plugin Type Safety
+
+Plugin methods are added at runtime. Use `WithPlugins<TDoc, TRepo>` for TypeScript autocomplete:
+
+```typescript
+import type { WithPlugins } from '@classytic/mongokit';
+
+class UserRepo extends Repository<IUser> {}
+
+const repo = new UserRepo(Model, [
+  methodRegistryPlugin(),
+  mongoOperationsPlugin(),
+  // ... other plugins
+]) as WithPlugins<IUser, UserRepo>;
+
+// Full TypeScript autocomplete!
+await repo.increment(id, 'views', 1);
+await repo.restore(id);
+await repo.invalidateCache(id);
+```
+
+**Individual plugin types:** `MongoOperationsMethods<T>`, `BatchOperationsMethods`, `AggregateHelpersMethods`, `SubdocumentMethods<T>`, `SoftDeleteMethods<T>`, `CacheMethods`
+
 ## Event System
 
 ```javascript

package/dist/actions/index.d.ts

@@ -1,3 +1,3 @@
-export { b as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-C2NCVxJK.js';
+export { b as aggregate, c as create, _ as deleteActions, r as read, u as update } from '../index-BXSSv1pW.js';
 import 'mongoose';
-import '../types-DA0rs2Jh.js';
+import '../types-B5Uv6Ak7.js';

package/dist/{index-C2NCVxJK.d.ts → index-BXSSv1pW.d.ts}

@@ -1,5 +1,5 @@
 import { PipelineStage, ClientSession, Model } from 'mongoose';
-import { A as AnyDocument, y as CreateOptions, k as ObjectId, x as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, l as UpdateOptions, E as UpdateWithValidationResult, B as UpdateManyResult, z as DeleteResult, a6 as GroupResult, a7 as MinMaxResult } from './types-DA0rs2Jh.js';
+import { A as AnyDocument, y as CreateOptions, k as ObjectId, x as OperationOptions, S as SelectSpec, e as PopulateSpec, f as SortSpec, l as UpdateOptions, E as UpdateWithValidationResult, B as UpdateManyResult, z as DeleteResult, a6 as GroupResult, a7 as MinMaxResult } from './types-B5Uv6Ak7.js';
 
 /**
  * LookupBuilder - MongoDB $lookup Utility

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { i as PaginationResult, A as AnyDocument, j as PluginType, P as PaginationConfig, R as RepositoryOptions, k as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, l as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, m as RepositoryContext, H as HttpError } from './types-DA0rs2Jh.js';
-export { c as AggregatePaginationOptions, n as AnyModel, C as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, v as CreateInput, y as CreateOptions, h as CrudSchemas, $ as DecodedCursor, D as DeepPartial, z as DeleteResult, X as EventHandlers, Y as EventPayload, Q as EventPhase, F as FieldPreset, Z as FieldRules, a6 as GroupResult, p as HookMode, I as InferDocument, q as InferRawDoc, _ as JsonSchema, t as KeysOfType, K as KeysetPaginationOptions, a2 as Logger, a7 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, x as OperationOptions, r as PartialBy, G as Plugin, J as PluginFunction, T as RepositoryEvent, L as RepositoryInstance, M as RepositoryOperation, s as RequiredBy, g as SchemaBuilderOptions, a4 as SoftDeleteFilterMode, a3 as SoftDeleteOptions, a5 as SoftDeleteRepository, o as SortDirection, u as Strict, w as UpdateInput, B as UpdateManyResult, E as UpdateWithValidationResult, U as UserContext, a1 as ValidationChainOptions, V as ValidationResult, a0 as ValidatorDefinition } from './types-DA0rs2Jh.js';
+import { i as PaginationResult, A as AnyDocument, j as PluginType, P as PaginationConfig, R as RepositoryOptions, k as ObjectId, S as SelectSpec, e as PopulateSpec, f as SortSpec$2, a as OffsetPaginationResult, b as KeysetPaginationResult, l as UpdateOptions, d as AggregatePaginationResult, W as WithTransactionOptions, m as RepositoryContext, H as HttpError } from './types-B5Uv6Ak7.js';
+export { c as AggregatePaginationOptions, ad as AllPluginMethods, n as AnyModel, C as CacheAdapter, a9 as CacheOperationOptions, a8 as CacheOptions, aa as CacheStats, ac as CascadeOptions, ab as CascadeRelation, v as CreateInput, y as CreateOptions, h as CrudSchemas, $ as DecodedCursor, D as DeepPartial, z as DeleteResult, X as EventHandlers, Y as EventPayload, Q as EventPhase, F as FieldPreset, Z as FieldRules, a6 as GroupResult, p as HookMode, I as InferDocument, q as InferRawDoc, _ as JsonSchema, t as KeysOfType, K as KeysetPaginationOptions, a2 as Logger, a7 as MinMaxResult, N as NonNullableFields, O as OffsetPaginationOptions, x as OperationOptions, r as PartialBy, G as Plugin, J as PluginFunction, T as RepositoryEvent, L as RepositoryInstance, M as RepositoryOperation, s as RequiredBy, g as SchemaBuilderOptions, a4 as SoftDeleteFilterMode, a3 as SoftDeleteOptions, a5 as SoftDeleteRepository, o as SortDirection, u as Strict, w as UpdateInput, B as UpdateManyResult, E as UpdateWithValidationResult, U as UserContext, a1 as ValidationChainOptions, V as ValidationResult, a0 as ValidatorDefinition, ae as WithPlugins } from './types-B5Uv6Ak7.js';
 import * as mongoose from 'mongoose';
 import { PipelineStage, Expression, Model, ClientSession, PopulateOptions } from 'mongoose';
 import { PaginationEngine } from './pagination/PaginationEngine.js';
-import { L as LookupOptions, a as LookupBuilder } from './index-C2NCVxJK.js';
-export { i as actions } from './index-C2NCVxJK.js';
-export { aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
-export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from './mongooseToJsonSchema-BKMxPbPp.js';
+import { L as LookupOptions, a as LookupBuilder } from './index-BXSSv1pW.js';
+export { i as actions } from './index-BXSSv1pW.js';
+export { AggregateHelpersMethods, BatchOperationsMethods, CacheMethods, MongoOperationsMethods, SoftDeleteMethods, SubdocumentMethods, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin } from './plugins/index.js';
+export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from './mongooseToJsonSchema-Cc5AwuDu.js';
 
 /**
  * Framework-Agnostic Controller Interfaces

package/dist/index.js

@@ -1073,7 +1073,7 @@ var Repository = class {
         if (typeof options.onFallback === "function") {
           options.onFallback(err);
         }
-        if (started && session.inTransaction()) {
+        if (started) {
           try {
             await session.abortTransaction();
           } catch {
@@ -1081,8 +1081,11 @@ var Repository = class {
         }
         return await callback(null);
       }
-      if (started && session.inTransaction()) {
-        await session.abortTransaction();
+      if (started) {
+        try {
+          await session.abortTransaction();
+        } catch {
+        }
       }
       throw err;
     } finally {

package/dist/{mongooseToJsonSchema-BKMxPbPp.d.ts → mongooseToJsonSchema-Cc5AwuDu.d.ts}

@@ -1,4 +1,4 @@
-import { U as UserContext, F as FieldPreset, H as HttpError, C as CacheAdapter, g as SchemaBuilderOptions, h as CrudSchemas, V as ValidationResult } from './types-DA0rs2Jh.js';
+import { U as UserContext, F as FieldPreset, H as HttpError, C as CacheAdapter, g as SchemaBuilderOptions, h as CrudSchemas, V as ValidationResult } from './types-B5Uv6Ak7.js';
 import mongoose__default, { Schema } from 'mongoose';
 
 /**

package/dist/pagination/PaginationEngine.d.ts

@@ -1,5 +1,5 @@
 import { Model } from 'mongoose';
-import { A as AnyDocument, P as PaginationConfig, O as OffsetPaginationOptions, a as OffsetPaginationResult, K as KeysetPaginationOptions, b as KeysetPaginationResult, c as AggregatePaginationOptions, d as AggregatePaginationResult } from '../types-DA0rs2Jh.js';
+import { A as AnyDocument, P as PaginationConfig, O as OffsetPaginationOptions, a as OffsetPaginationResult, K as KeysetPaginationOptions, b as KeysetPaginationResult, c as AggregatePaginationOptions, d as AggregatePaginationResult } from '../types-B5Uv6Ak7.js';
 
 /**
  * Pagination Engine

package/dist/plugins/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FieldPreset, G as Plugin, a2 as Logger, a3 as SoftDeleteOptions, L as RepositoryInstance, a0 as ValidatorDefinition, a1 as ValidationChainOptions, m as RepositoryContext, a8 as CacheOptions, ac as CascadeOptions } from '../types-DA0rs2Jh.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 };

package/dist/{types-DA0rs2Jh.d.ts → types-B5Uv6Ak7.d.ts}

@@ -646,5 +646,128 @@ interface HttpError extends Error {
         error: string;
     }>;
 }
+/**
+ * Combines all plugin method types into a single type
+ * Useful when you're using all plugins and want full type safety
+ *
+ * @example
+ * ```typescript
+ * import { Repository } from '@classytic/mongokit';
+ * import type { AllPluginMethods } from '@classytic/mongokit';
+ *
+ * class UserRepo extends Repository<IUser> {}
+ *
+ * const repo = new UserRepo(Model, [...allPlugins]) as UserRepo & AllPluginMethods<IUser>;
+ *
+ * // TypeScript knows about all plugin methods!
+ * await repo.increment(id, 'views', 1);
+ * await repo.restore(id);
+ * await repo.invalidateCache(id);
+ * ```
+ *
+ * Note: Import the individual plugin method types if you need them:
+ * ```typescript
+ * import type {
+ *   MongoOperationsMethods,
+ *   BatchOperationsMethods,
+ *   AggregateHelpersMethods,
+ *   SubdocumentMethods,
+ *   SoftDeleteMethods,
+ *   CacheMethods,
+ * } from '@classytic/mongokit';
+ * ```
+ */
+type AllPluginMethods<TDoc> = {
+    upsert(query: Record<string, unknown>, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+    increment(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+    decrement(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+    pushToArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    pullFromArray(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    addToSet(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    setField(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    unsetField(id: string | ObjectId, fields: string | string[], options?: Record<string, unknown>): Promise<TDoc>;
+    renameField(id: string | ObjectId, oldName: string, newName: string, options?: Record<string, unknown>): Promise<TDoc>;
+    multiplyField(id: string | ObjectId, field: string, multiplier: number, options?: Record<string, unknown>): Promise<TDoc>;
+    setMin(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    setMax(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+    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;
+    }>;
+    deleteMany(query: Record<string, unknown>, options?: Record<string, unknown>): Promise<{
+        acknowledged: boolean;
+        deletedCount: number;
+    }>;
+    groupBy(field: string, options?: {
+        limit?: number;
+        session?: unknown;
+    }): Promise<Array<{
+        _id: unknown;
+        count: number;
+    }>>;
+    sum(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    average(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    min(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    max(field: string, query?: Record<string, unknown>, options?: Record<string, unknown>): Promise<number>;
+    addSubdocument(parentId: string | ObjectId, arrayPath: string, subData: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+    getSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: {
+        lean?: boolean;
+        session?: unknown;
+    }): Promise<Record<string, unknown>>;
+    updateSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, updateData: Record<string, unknown>, options?: {
+        session?: unknown;
+    }): Promise<TDoc>;
+    deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
+    restore(id: string | ObjectId, options?: {
+        session?: ClientSession;
+    }): Promise<TDoc>;
+    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>>;
+    invalidateCache(id: string): Promise<void>;
+    invalidateListCache(): Promise<void>;
+    invalidateAllCache(): Promise<void>;
+    getCacheStats(): CacheStats;
+    resetCacheStats(): void;
+};
+/**
+ * Helper type to add all plugin methods to a repository class
+ * Cleaner than manually typing the intersection
+ *
+ * @example
+ * ```typescript
+ * import { Repository } from '@classytic/mongokit';
+ * import type { WithPlugins } from '@classytic/mongokit';
+ *
+ * class OrderRepo extends Repository<IOrder> {
+ *   async getCustomerOrders(customerId: string) {
+ *     return this.getAll({ filters: { customerId } });
+ *   }
+ * }
+ *
+ * const orderRepo = new OrderRepo(Model, [
+ *   ...allPlugins
+ * ]) as WithPlugins<IOrder, OrderRepo>;
+ *
+ * // Works: custom methods + plugin methods
+ * await orderRepo.getCustomerOrders('123');
+ * await orderRepo.increment(orderId, 'total', 100);
+ * ```
+ */
+type WithPlugins<TDoc, TRepo extends RepositoryInstance = RepositoryInstance> = TRepo & AllPluginMethods<TDoc>;
 
-export type { DecodedCursor as $, AnyDocument as A, UpdateManyResult as B, CacheAdapter as C, DeepPartial as D, UpdateWithValidationResult as E, FieldPreset as F, Plugin as G, HttpError as H, InferDocument as I, PluginFunction as J, KeysetPaginationOptions as K, RepositoryInstance as L, RepositoryOperation as M, NonNullableFields as N, OffsetPaginationOptions as O, PaginationConfig as P, EventPhase as Q, RepositoryOptions as R, SelectSpec as S, RepositoryEvent as T, UserContext as U, ValidationResult as V, WithTransactionOptions as W, EventHandlers as X, EventPayload as Y, FieldRules as Z, JsonSchema as _, OffsetPaginationResult as a, ValidatorDefinition as a0, ValidationChainOptions as a1, Logger as a2, SoftDeleteOptions as a3, SoftDeleteFilterMode as a4, SoftDeleteRepository as a5, GroupResult as a6, MinMaxResult as a7, CacheOptions as a8, CacheOperationOptions as a9, CacheStats as aa, CascadeRelation as ab, CascadeOptions as ac, KeysetPaginationResult as b, AggregatePaginationOptions as c, AggregatePaginationResult as d, PopulateSpec as e, SortSpec as f, SchemaBuilderOptions as g, CrudSchemas as h, PaginationResult as i, PluginType as j, ObjectId as k, UpdateOptions as l, RepositoryContext as m, AnyModel as n, SortDirection as o, HookMode as p, InferRawDoc as q, PartialBy as r, RequiredBy as s, KeysOfType as t, Strict as u, CreateInput as v, UpdateInput as w, OperationOptions as x, CreateOptions as y, DeleteResult as z };
+export type { DecodedCursor as $, AnyDocument as A, UpdateManyResult as B, CacheAdapter as C, DeepPartial as D, UpdateWithValidationResult as E, FieldPreset as F, Plugin as G, HttpError as H, InferDocument as I, PluginFunction as J, KeysetPaginationOptions as K, RepositoryInstance as L, RepositoryOperation as M, NonNullableFields as N, OffsetPaginationOptions as O, PaginationConfig as P, EventPhase as Q, RepositoryOptions as R, SelectSpec as S, RepositoryEvent as T, UserContext as U, ValidationResult as V, WithTransactionOptions as W, EventHandlers as X, EventPayload as Y, FieldRules as Z, JsonSchema as _, OffsetPaginationResult as a, ValidatorDefinition as a0, ValidationChainOptions as a1, Logger as a2, SoftDeleteOptions as a3, SoftDeleteFilterMode as a4, SoftDeleteRepository as a5, GroupResult as a6, MinMaxResult as a7, CacheOptions as a8, CacheOperationOptions as a9, CacheStats as aa, CascadeRelation as ab, CascadeOptions as ac, AllPluginMethods as ad, WithPlugins as ae, KeysetPaginationResult as b, AggregatePaginationOptions as c, AggregatePaginationResult as d, PopulateSpec as e, SortSpec as f, SchemaBuilderOptions as g, CrudSchemas as h, PaginationResult as i, PluginType as j, ObjectId as k, UpdateOptions as l, RepositoryContext as m, AnyModel as n, SortDirection as o, HookMode as p, InferRawDoc as q, PartialBy as r, RequiredBy as s, KeysOfType as t, Strict as u, CreateInput as v, UpdateInput as w, OperationOptions as x, CreateOptions as y, DeleteResult as z };

package/dist/utils/index.d.ts

@@ -1,5 +1,5 @@
-export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from '../mongooseToJsonSchema-BKMxPbPp.js';
-import { S as SelectSpec, e as PopulateSpec, f as SortSpec } from '../types-DA0rs2Jh.js';
+export { d as buildCrudSchemasFromModel, b as buildCrudSchemasFromMongooseSchema, j as createError, c as createFieldPreset, k as createMemoryCache, f as filterResponseData, g as getFieldsForUser, e as getImmutableFields, a as getMongooseProjection, h as getSystemManagedFields, i as isFieldUpdateAllowed, v as validateUpdateBody } from '../mongooseToJsonSchema-Cc5AwuDu.js';
+import { S as SelectSpec, e as PopulateSpec, f as SortSpec } from '../types-B5Uv6Ak7.js';
 import 'mongoose';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,