@classytic/mongokit 3.3.2 → 3.4.0

package/dist/{custom-id.plugin-BJ3FSnzt.d.mts → validation-chain.plugin-DxqiHv-E.d.mts}

@@ -1,29 +1,90 @@
-import { F as ObjectId, G as PopulateSpec, H as Plugin, L as OffsetPaginationResult, M as Logger, Y as RepositoryInstance, at as SortSpec, c as CacheOptions, et as SelectSpec, ft as ValidationChainOptions, l as CacheStats, mt as ValidatorDefinition, nt as SoftDeleteOptions, q as RepositoryContext, u as CascadeOptions, x as FieldPreset } from "./types-pVY0w1Pp.mjs";
+import { F as ObjectId, G as PopulateSpec, H as Plugin, L as OffsetPaginationResult, M as Logger, Y as RepositoryInstance, at as SortSpec, c as CacheOptions, et as SelectSpec, ft as ValidationChainOptions, l as CacheStats, mt as ValidatorDefinition, nt as SoftDeleteOptions, q as RepositoryContext, u as CascadeOptions, x as FieldPreset } from "./types-BlCwDszq.mjs";
 import mongoose, { ClientSession } from "mongoose";
 
-//#region src/plugins/field-filter.plugin.d.ts
+//#region src/plugins/aggregate-helpers.plugin.d.ts
 /**
- * Field filter plugin that restricts fields based on user context
+ * Aggregate helpers plugin
  *
  * @example
- * const fieldPreset = {
- *   public: ['id', 'name'],
- *   authenticated: ['email'],
- *   admin: ['createdAt', 'internalNotes']
- * };
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   aggregateHelpersPlugin(),
+ * ]);
  *
- * const repo = new Repository(Model, [fieldFilterPlugin(fieldPreset)]);
+ * const groups = await repo.groupBy('category');
+ * const total = await repo.sum('amount', { status: 'completed' });
  */
-declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
-//#endregion
-//#region src/plugins/timestamp.plugin.d.ts
+declare function aggregateHelpersPlugin(): Plugin;
 /**
- * Timestamp plugin that auto-injects timestamps
+ * Type interface for repositories using aggregateHelpersPlugin
  *
  * @example
- * const repo = new Repository(Model, [timestampPlugin()]);
+ * ```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');
+ * ```
  */
-declare function timestampPlugin(): Plugin;
+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>;
+}
 //#endregion
 //#region src/plugins/audit-log.plugin.d.ts
 /**
@@ -34,688 +95,711 @@ declare function timestampPlugin(): Plugin;
  */
 declare function auditLogPlugin(logger: Logger): Plugin;
 //#endregion
-//#region src/plugins/soft-delete.plugin.d.ts
+//#region src/plugins/audit-trail.plugin.d.ts
+interface AuditTrailOptions {
+  /** Operations to track (default: ['create', 'update', 'delete']) */
+  operations?: AuditOperation[];
+  /** Store field-level before/after diff on updates (default: true) */
+  trackChanges?: boolean;
+  /** Store full document snapshot on create (default: false — can be heavy) */
+  trackDocument?: boolean;
+  /** Auto-purge after N days via MongoDB TTL index (default: undefined — keep forever) */
+  ttlDays?: number;
+  /** MongoDB collection name (default: 'audit_trails') */
+  collectionName?: string;
+  /**
+   * Extract custom metadata from the repository context.
+   * Returned object is stored on the audit entry as `metadata`.
+   */
+  metadata?: (context: RepositoryContext) => Record<string, unknown>;
+  /**
+   * Fields to exclude from change tracking (e.g., passwords, tokens).
+   * These fields are redacted in the `changes` diff.
+   */
+  excludeFields?: string[];
+}
+type AuditOperation = 'create' | 'update' | 'delete';
+interface AuditEntry {
+  model: string;
+  operation: AuditOperation;
+  documentId: unknown;
+  userId?: unknown;
+  orgId?: unknown;
+  changes?: Record<string, {
+    from: unknown;
+    to: unknown;
+  }>;
+  document?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  timestamp: Date;
+}
+declare function auditTrailPlugin(options?: AuditTrailOptions): Plugin;
+interface AuditQueryOptions {
+  model?: string;
+  documentId?: string | ObjectId;
+  userId?: string | ObjectId;
+  orgId?: string | ObjectId;
+  operation?: AuditOperation;
+  from?: Date;
+  to?: Date;
+  page?: number;
+  limit?: number;
+}
+interface AuditQueryResult {
+  docs: AuditEntry[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
 /**
- * Soft delete plugin
+ * Standalone audit trail query utility.
+ * Use this to query audits across all models — e.g., admin dashboards, audit APIs.
  *
- * @example Basic usage
+ * @example
  * ```typescript
- * const repo = new Repository(Model, [
- *   softDeletePlugin({ deletedField: 'deletedAt' })
- * ]);
- *
- * // Delete (soft)
- * await repo.delete(id);
- *
- * // Restore
- * await repo.restore(id);
- *
- * // Get deleted documents
- * await repo.getDeleted({ page: 1, limit: 20 });
- * ```
+ * import { AuditTrailQuery } from '@classytic/mongokit';
  *
- * @example With null filter mode (for schemas with default: null)
- * ```typescript
- * // Schema: { deletedAt: { type: Date, default: null } }
- * const repo = new Repository(Model, [
- *   softDeletePlugin({
- *     deletedField: 'deletedAt',
- *     filterMode: 'null', // default - works with default: null
- *   })
- * ]);
- * ```
+ * const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
  *
- * @example With TTL for auto-cleanup
- * ```typescript
- * const repo = new Repository(Model, [
- *   softDeletePlugin({
- *     deletedField: 'deletedAt',
- *     ttlDays: 30, // Auto-delete after 30 days
- *   })
- * ]);
- * ```
- */
-declare function softDeletePlugin(options?: SoftDeleteOptions): Plugin;
-/**
- * TypeScript interface for soft delete plugin methods
+ * // All audits for an org
+ * const orgAudits = await auditQuery.query({ orgId: '...' });
  *
- * @example
- * ```typescript
- * import type { SoftDeleteMethods } from '@classytic/mongokit';
+ * // All updates by a user
+ * const userUpdates = await auditQuery.query({
+ *   userId: '...',
+ *   operation: 'update',
+ * });
  *
- * type UserRepoWithSoftDelete = UserRepo & SoftDeleteMethods<IUser>;
+ * // All audits for a specific document
+ * const docHistory = await auditQuery.query({
+ *   model: 'Job',
+ *   documentId: '...',
+ * });
  *
- * const userRepo = new UserRepo(UserModel, [
- *   methodRegistryPlugin(),
- *   softDeletePlugin({ deletedField: 'deletedAt' }),
- * ]) as UserRepoWithSoftDelete;
+ * // Date range
+ * const recent = await auditQuery.query({
+ *   from: new Date('2025-01-01'),
+ *   to: new Date(),
+ *   page: 1,
+ *   limit: 50,
+ * });
  *
- * // TypeScript autocomplete for soft delete methods
- * await userRepo.restore(userId);
- * const deleted = await userRepo.getDeleted({ page: 1, limit: 20 });
+ * // Direct model access for custom queries
+ * const model = auditQuery.getModel();
+ * const count = await model.countDocuments({ operation: 'delete' });
  * ```
  */
-interface SoftDeleteMethods<TDoc> {
+declare class AuditTrailQuery {
+  private model;
+  constructor(collectionName?: string, ttlDays?: number);
   /**
-   * Restore a soft-deleted document
-   * @param id - Document ID to restore
-   * @param options - Optional restore options
-   * @returns Restored document
+   * Get the underlying Mongoose model for custom queries
    */
-  restore(id: string | ObjectId, options?: {
-    session?: ClientSession;
-  }): Promise<TDoc>;
+  getModel(): mongoose.Model<AuditEntry>;
   /**
-   * 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
+   * Query audit entries with filters and pagination
    */
-  getDeleted(params?: {
-    filters?: Record<string, unknown>;
-    sort?: SortSpec | string;
+  query(options?: AuditQueryOptions): Promise<AuditQueryResult>;
+  /**
+   * Get audit trail for a specific document
+   */
+  getDocumentTrail(model: string, documentId: string | ObjectId, options?: {
     page?: number;
     limit?: number;
-  }, options?: {
-    select?: SelectSpec;
-    populate?: PopulateSpec;
-    lean?: boolean;
-    session?: ClientSession;
-  }): Promise<OffsetPaginationResult<TDoc>>;
+    operation?: AuditOperation;
+  }): Promise<AuditQueryResult>;
+  /**
+   * Get all audits for a user
+   */
+  getUserTrail(userId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+    orgId?: string | ObjectId;
+  }): Promise<AuditQueryResult>;
+  /**
+   * Get all audits for an organization
+   */
+  getOrgTrail(orgId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+    model?: string;
+  }): Promise<AuditQueryResult>;
 }
-//#endregion
-//#region src/plugins/method-registry.plugin.d.ts
-/**
- * Extended repository interface with method registry
- */
-interface MethodRegistryRepository extends RepositoryInstance {
-  registerMethod(name: string, fn: Function): void;
-  hasMethod(name: string): boolean;
-  getRegisteredMethods(): string[];
+interface AuditTrailMethods {
+  /**
+   * Get paginated audit trail for a document
+   */
+  getAuditTrail(documentId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+  }): Promise<AuditQueryResult>;
 }
-/**
- * Method registry plugin that enables dynamic method registration
- */
-declare function methodRegistryPlugin(): Plugin;
 //#endregion
-//#region src/plugins/validation-chain.plugin.d.ts
-type OperationType = 'create' | 'createMany' | 'update' | 'delete';
+//#region src/plugins/batch-operations.plugin.d.ts
 /**
- * Validation chain plugin
+ * Batch operations plugin
  *
  * @example
  * const repo = new Repository(Model, [
- *   validationChainPlugin([
- *     requireField('email'),
- *     uniqueField('email', 'Email already exists'),
- *     blockIf('no-delete-admin', ['delete'], ctx => ctx.data?.role === 'admin', 'Cannot delete admin'),
- *   ])
+ *   methodRegistryPlugin(),
+ *   batchOperationsPlugin(),
  * ]);
- */
-declare function validationChainPlugin(validators?: ValidatorDefinition[], options?: ValidationChainOptions): Plugin;
-/**
- * Block operation if condition is true
  *
- * @example
- * blockIf('block-library', ['delete'], ctx => ctx.data?.managed, 'Cannot delete managed records')
- */
-declare function blockIf(name: string, operations: OperationType[], condition: (context: RepositoryContext) => boolean, errorMessage: string): ValidatorDefinition;
-/**
- * Require a field to be present
- */
-declare function requireField(field: string, operations?: OperationType[]): ValidatorDefinition;
-/**
- * Auto-inject a value if not present
- */
-declare function autoInject(field: string, getter: (context: RepositoryContext) => unknown, operations?: OperationType[]): ValidatorDefinition;
-/**
- * Make a field immutable (cannot be updated)
- */
-declare function immutableField(field: string): ValidatorDefinition;
-/**
- * Ensure field value is unique
+ * await repo.updateMany({ status: 'pending' }, { status: 'active' });
+ * await repo.deleteMany({ status: 'deleted' });
  */
-declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
-//#endregion
-//#region src/plugins/mongo-operations.plugin.d.ts
+declare function batchOperationsPlugin(): Plugin;
 /**
- * MongoDB operations plugin
- *
- * 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');
- * ```
+ * Type interface for repositories using batchOperationsPlugin
  *
- * @example With TypeScript type safety (recommended)
+ * @example
  * ```typescript
- * import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
- * import type { MongoOperationsMethods } from '@classytic/mongokit';
+ * import { Repository, methodRegistryPlugin, batchOperationsPlugin } from '@classytic/mongokit';
+ * import type { BatchOperationsMethods } from '@classytic/mongokit';
  *
- * class ProductRepo extends Repository<IProduct> {
- *   // Add your custom methods here
- * }
+ * class ProductRepo extends Repository<IProduct> {}
  *
- * // Create with type assertion to get autocomplete for plugin methods
- * type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;
+ * type ProductRepoWithBatch = ProductRepo & BatchOperationsMethods;
  *
  * const repo = new ProductRepo(ProductModel, [
  *   methodRegistryPlugin(),
- *   mongoOperationsPlugin(),
- * ]) as ProductRepoWithPlugins;
+ *   batchOperationsPlugin(),
+ * ]) as ProductRepoWithBatch;
  *
- * // 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');
+ * // TypeScript autocomplete works!
+ * await repo.updateMany({ status: 'pending' }, { status: 'active' });
+ * await repo.deleteMany({ status: 'archived' });
  * ```
  */
-declare function mongoOperationsPlugin(): Plugin;
+/** Bulk write result */
+interface BulkWriteResult {
+  ok: number;
+  insertedCount: number;
+  upsertedCount: number;
+  matchedCount: number;
+  modifiedCount: number;
+  deletedCount: number;
+  insertedIds: Record<number, unknown>;
+  upsertedIds: Record<number, unknown>;
+}
+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;
+  }>;
+  /**
+   * Execute heterogeneous bulk write operations in a single database call.
+   * Supports insertOne, updateOne, updateMany, deleteOne, deleteMany, replaceOne.
+   *
+   * @param operations - Array of bulk write operations
+   * @param options - Options (session, ordered)
+   * @returns Bulk write result with counts per operation type
+   *
+   * @example
+   * const result = await repo.bulkWrite([
+   *   { insertOne: { document: { name: 'Item', price: 10 } } },
+   *   { updateOne: { filter: { _id: id }, update: { $inc: { views: 1 } } } },
+   *   { deleteOne: { filter: { _id: oldId } } },
+   * ]);
+   * console.log(result.insertedCount, result.modifiedCount, result.deletedCount);
+   */
+  bulkWrite(operations: Record<string, unknown>[], options?: {
+    session?: ClientSession;
+    ordered?: boolean;
+  }): Promise<BulkWriteResult>;
+}
+//#endregion
+//#region src/plugins/cache.plugin.d.ts
 /**
- * Type interface for repositories using mongoOperationsPlugin
+ * Cache plugin factory
  *
- * Use this interface to get TypeScript autocomplete and type safety
- * for the methods added by mongoOperationsPlugin.
+ * @param options - Cache configuration
+ * @returns Plugin instance
+ */
+declare function cachePlugin(options: CacheOptions): Plugin;
+/**
+ * TypeScript interface for cache plugin methods
  *
  * @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
- * }
+ * import type { CacheMethods } from '@classytic/mongokit';
  *
- * // With type safety for plugin methods
- * class ProductRepo extends Repository<IProduct> implements MongoOperationsMethods<IProduct> {
- *   // TypeScript knows about upsert, increment, decrement, etc.
- * }
+ * type ProductRepoWithCache = ProductRepo & CacheMethods;
  *
- * const repo = new ProductRepo(ProductModel, [
+ * const productRepo = new ProductRepo(ProductModel, [
  *   methodRegistryPlugin(),
- *   mongoOperationsPlugin(),
- * ]);
+ *   cachePlugin({ adapter: redisAdapter, ttl: 60 }),
+ * ]) as ProductRepoWithCache;
  *
- * // Now TypeScript provides autocomplete and type checking
- * await repo.increment(productId, 'views', 1);
- * await repo.upsert({ sku: 'ABC' }, { name: 'Product' });
+ * // TypeScript autocomplete for cache methods
+ * await productRepo.invalidateCache(productId);
+ * await productRepo.invalidateListCache();
+ * await productRepo.invalidateAllCache();
+ * const stats = productRepo.getCacheStats();
+ * productRepo.resetCacheStats();
  * ```
  */
-interface MongoOperationsMethods<TDoc> {
+interface CacheMethods {
   /**
-   * 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
+   * Invalidate cache for a specific document
+   * Use when document was updated outside this service
+   * @param id - Document ID to invalidate
    */
-  upsert(query: Record<string, unknown>, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+  invalidateCache(id: string): Promise<void>;
   /**
-   * 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
+   * Invalidate all list caches for this model
+   * Use when bulk changes happened outside this service
    */
-  increment(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
+  invalidateListCache(): Promise<void>;
   /**
-   * 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
+   * Invalidate ALL cache entries for this model
+   * Nuclear option - use sparingly
    */
-  setMin(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  invalidateAllCache(): Promise<void>;
   /**
-   * 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
+   * Get cache statistics for monitoring
+   * @returns Cache statistics (hits, misses, sets, invalidations)
    */
-  setMax(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  getCacheStats(): CacheStats;
   /**
-   * Atomic update with multiple MongoDB operators in a single call.
-   * Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, etc.
-   *
-   * @param id - Document ID
-   * @param operators - MongoDB update operators (e.g. { $inc: { views: 1 }, $set: { lastViewed: new Date() } })
-   * @param options - Operation options (session, arrayFilters, etc.)
-   * @returns Updated document
-   *
-   * @example
-   * await repo.atomicUpdate(postId, {
-   *   $inc: { reactionCount: -1 },
-   *   $set: { lastActiveAt: new Date() },
-   *   $push: { history: { action: 'unreact', at: new Date() } }
-   * });
+   * Reset cache statistics
    */
-  atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
+  resetCacheStats(): void;
 }
 //#endregion
-//#region src/plugins/batch-operations.plugin.d.ts
+//#region src/plugins/cascade.plugin.d.ts
 /**
- * Batch operations plugin
+ * Cascade delete plugin
+ *
+ * Deletes related documents after the parent document is deleted.
+ * Works with both hard delete and soft delete scenarios.
+ *
+ * @param options - Cascade configuration
+ * @returns Plugin
+ */
+declare function cascadePlugin(options: CascadeOptions): Plugin;
+//#endregion
+//#region src/plugins/custom-id.plugin.d.ts
+/**
+ * Generator function that produces a unique ID.
+ * Receives the full repository context for conditional logic.
+ */
+type IdGenerator = (context: RepositoryContext) => string | Promise<string>;
+interface CustomIdOptions {
+  /** Field to store the custom ID (default: 'customId') */
+  field?: string;
+  /** Function to generate the ID. Can be async. */
+  generator: IdGenerator;
+  /** Only generate if the field is missing/empty (default: true) */
+  generateOnlyIfEmpty?: boolean;
+}
+/**
+ * Atomically increment and return the next sequence value for a given key.
+ * Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
+ * heavy concurrency.
+ *
+ * @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
+ * @param increment - Value to increment by (default: 1)
+ * @returns The next sequence number (after increment)
  *
  * @example
- * const repo = new Repository(Model, [
- *   methodRegistryPlugin(),
- *   batchOperationsPlugin(),
- * ]);
+ * const seq = await getNextSequence('invoices');
+ * // First call → 1, second → 2, ...
  *
- * await repo.updateMany({ status: 'pending' }, { status: 'active' });
- * await repo.deleteMany({ status: 'deleted' });
+ * @example Batch increment for createMany
+ * const startSeq = await getNextSequence('invoices', 5);
+ * // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
  */
-declare function batchOperationsPlugin(): Plugin;
+declare function getNextSequence(counterKey: string, increment?: number, connection?: mongoose.Connection): Promise<number>;
+interface SequentialIdOptions {
+  /** Prefix string (e.g., 'INV', 'ORD') */
+  prefix: string;
+  /** Mongoose model — used to derive the counter key from model name */
+  model: mongoose.Model<any>;
+  /** Number of digits to pad to (default: 4 → "0001") */
+  padding?: number;
+  /** Separator between prefix and number (default: '-') */
+  separator?: string;
+  /** Custom counter key override (default: model.modelName) */
+  counterKey?: string;
+}
 /**
- * Type interface for repositories using batchOperationsPlugin
+ * Generator: Simple sequential counter.
+ * Produces IDs like `INV-0001`, `INV-0002`, etc.
+ *
+ * Uses atomic MongoDB counters — safe under concurrency.
  *
  * @example
  * ```typescript
- * import { Repository, methodRegistryPlugin, batchOperationsPlugin } from '@classytic/mongokit';
- * import type { BatchOperationsMethods } from '@classytic/mongokit';
+ * customIdPlugin({
+ *   field: 'invoiceNumber',
+ *   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+ * })
+ * ```
+ */
+declare function sequentialId(options: SequentialIdOptions): IdGenerator;
+interface DateSequentialIdOptions {
+  /** Prefix string (e.g., 'BILL', 'INV') */
+  prefix: string;
+  /** Mongoose model — used to derive the counter key */
+  model: mongoose.Model<any>;
+  /**
+   * Partition granularity — counter resets each period.
+   * - 'yearly'  → BILL-2026-0001, resets every January
+   * - 'monthly' → BILL-2026-02-0001, resets every month
+   * - 'daily'   → BILL-2026-02-20-0001, resets every day
+   */
+  partition?: 'yearly' | 'monthly' | 'daily';
+  /** Number of digits to pad to (default: 4) */
+  padding?: number;
+  /** Separator (default: '-') */
+  separator?: string;
+}
+/**
+ * Generator: Date-partitioned sequential counter.
+ * Counter resets per period — great for invoice/bill numbering.
  *
- * class ProductRepo extends Repository<IProduct> {}
+ * Produces IDs like:
+ * - yearly:  `BILL-2026-0001`
+ * - monthly: `BILL-2026-02-0001`
+ * - daily:   `BILL-2026-02-20-0001`
  *
- * type ProductRepoWithBatch = ProductRepo & BatchOperationsMethods;
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'billNumber',
+ *   generator: dateSequentialId({
+ *     prefix: 'BILL',
+ *     model: BillModel,
+ *     partition: 'monthly',
+ *   }),
+ * })
+ * ```
+ */
+declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
+interface PrefixedIdOptions {
+  /** Prefix string (e.g., 'USR', 'TXN') */
+  prefix: string;
+  /** Separator (default: '_') */
+  separator?: string;
+  /** Length of the random suffix (default: 12) */
+  length?: number;
+}
+/**
+ * Generator: Prefix + random alphanumeric suffix.
+ * Does NOT require a database round-trip — purely in-memory.
  *
- * const repo = new ProductRepo(ProductModel, [
- *   methodRegistryPlugin(),
- *   batchOperationsPlugin(),
- * ]) as ProductRepoWithBatch;
+ * Produces IDs like: `USR_a7b3xk9m2p1q`
  *
- * // TypeScript autocomplete works!
- * await repo.updateMany({ status: 'pending' }, { status: 'active' });
- * await repo.deleteMany({ status: 'archived' });
+ * Good for: user-facing IDs where ordering doesn't matter.
+ * Not suitable for sequential numbering.
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'publicId',
+ *   generator: prefixedId({ prefix: 'USR', length: 10 }),
+ * })
  * ```
  */
-/** Bulk write result */
-interface BulkWriteResult {
-  ok: number;
-  insertedCount: number;
-  upsertedCount: number;
-  matchedCount: number;
-  modifiedCount: number;
-  deletedCount: number;
-  insertedIds: Record<number, unknown>;
-  upsertedIds: Record<number, unknown>;
-}
-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;
-  }>;
-  /**
-   * Execute heterogeneous bulk write operations in a single database call.
-   * Supports insertOne, updateOne, updateMany, deleteOne, deleteMany, replaceOne.
-   *
-   * @param operations - Array of bulk write operations
-   * @param options - Options (session, ordered)
-   * @returns Bulk write result with counts per operation type
-   *
-   * @example
-   * const result = await repo.bulkWrite([
-   *   { insertOne: { document: { name: 'Item', price: 10 } } },
-   *   { updateOne: { filter: { _id: id }, update: { $inc: { views: 1 } } } },
-   *   { deleteOne: { filter: { _id: oldId } } },
-   * ]);
-   * console.log(result.insertedCount, result.modifiedCount, result.deletedCount);
-   */
-  bulkWrite(operations: Record<string, unknown>[], options?: {
-    session?: ClientSession;
-    ordered?: boolean;
-  }): Promise<BulkWriteResult>;
+declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
+/**
+ * Custom ID plugin — injects generated IDs into documents before creation.
+ *
+ * @param options - Configuration for ID generation
+ * @returns Plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+ *
+ * const invoiceRepo = new Repository(InvoiceModel, [
+ *   customIdPlugin({
+ *     field: 'invoiceNumber',
+ *     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+ *   }),
+ * ]);
+ *
+ * const inv = await invoiceRepo.create({ amount: 100 });
+ * console.log(inv.invoiceNumber); // "INV-0001"
+ * ```
+ */
+declare function customIdPlugin(options: CustomIdOptions): Plugin;
+//#endregion
+//#region src/plugins/elastic.plugin.d.ts
+interface ElasticSearchOptions {
+  /** Elasticsearch or OpenSearch client instance */
+  client: any;
+  /** Index name to perform search against */
+  index: string;
+  /** Field to extract MongoDB ID from the indexed document (default: '_id') */
+  idField?: string;
 }
+declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
 //#endregion
-//#region src/plugins/aggregate-helpers.plugin.d.ts
+//#region src/plugins/field-filter.plugin.d.ts
 /**
- * Aggregate helpers plugin
+ * Field filter plugin that restricts fields based on user context
  *
  * @example
- * const repo = new Repository(Model, [
+ * const fieldPreset = {
+ *   public: ['id', 'name'],
+ *   authenticated: ['email'],
+ *   admin: ['createdAt', 'internalNotes']
+ * };
+ *
+ * const repo = new Repository(Model, [fieldFilterPlugin(fieldPreset)]);
+ */
+declare function fieldFilterPlugin(fieldPreset: FieldPreset): Plugin;
+//#endregion
+//#region src/plugins/method-registry.plugin.d.ts
+/**
+ * Extended repository interface with method registry
+ */
+interface MethodRegistryRepository extends RepositoryInstance {
+  registerMethod(name: string, fn: Function): void;
+  hasMethod(name: string): boolean;
+  getRegisteredMethods(): string[];
+}
+/**
+ * Method registry plugin that enables dynamic method registration
+ */
+declare function methodRegistryPlugin(): Plugin;
+//#endregion
+//#region src/plugins/mongo-operations.plugin.d.ts
+/**
+ * MongoDB operations plugin
+ *
+ * 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(),
- *   aggregateHelpersPlugin(),
+ *   mongoOperationsPlugin(),
  * ]);
  *
- * const groups = await repo.groupBy('category');
- * const total = await repo.sum('amount', { status: 'completed' });
- */
-declare function aggregateHelpersPlugin(): Plugin;
-/**
- * Type interface for repositories using aggregateHelpersPlugin
+ * // 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
+ * @example With TypeScript type safety (recommended)
  * ```typescript
- * import { Repository, methodRegistryPlugin, aggregateHelpersPlugin } from '@classytic/mongokit';
- * import type { AggregateHelpersMethods } from '@classytic/mongokit';
+ * import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
+ * import type { MongoOperationsMethods } from '@classytic/mongokit';
  *
- * class OrderRepo extends Repository<IOrder> {}
+ * class ProductRepo extends Repository<IProduct> {
+ *   // Add your custom methods here
+ * }
  *
- * type OrderRepoWithAggregates = OrderRepo & AggregateHelpersMethods;
+ * // Create with type assertion to get autocomplete for plugin methods
+ * type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;
  *
- * const repo = new OrderRepo(OrderModel, [
+ * const repo = new ProductRepo(ProductModel, [
  *   methodRegistryPlugin(),
- *   aggregateHelpersPlugin(),
- * ]) as OrderRepoWithAggregates;
+ *   mongoOperationsPlugin(),
+ * ]) as ProductRepoWithPlugins;
  *
- * // TypeScript autocomplete works!
- * const groups = await repo.groupBy('status');
- * const total = await repo.sum('amount', { status: 'completed' });
- * const avg = await repo.average('amount');
+ * // 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');
  * ```
  */
-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>;
-}
-//#endregion
-//#region src/plugins/subdocument.plugin.d.ts
+declare function mongoOperationsPlugin(): Plugin;
 /**
- * Subdocument plugin for managing nested arrays
- *
- * @example
- * const repo = new Repository(Model, [
- *   methodRegistryPlugin(),
- *   subdocumentPlugin(),
- * ]);
+ * Type interface for repositories using mongoOperationsPlugin
  *
- * await repo.addSubdocument(parentId, 'items', { name: 'Item 1' });
- * await repo.updateSubdocument(parentId, 'items', itemId, { name: 'Updated Item' });
- */
-declare function subdocumentPlugin(): Plugin;
-/**
- * Type interface for repositories using subdocumentPlugin
+ * Use this interface to get TypeScript autocomplete and type safety
+ * for the methods added by mongoOperationsPlugin.
  *
  * @example
  * ```typescript
- * import { Repository, methodRegistryPlugin, subdocumentPlugin } from '@classytic/mongokit';
- * import type { SubdocumentMethods } from '@classytic/mongokit';
+ * import { Repository, mongoOperationsPlugin, methodRegistryPlugin } from '@classytic/mongokit';
+ * import type { MongoOperationsMethods } from '@classytic/mongokit';
  *
- * class OrderRepo extends Repository<IOrder> {}
+ * // Without type safety (base is flexible)
+ * class ProductRepo extends Repository<IProduct> {
+ *   // Can add anything - fully flexible
+ * }
  *
- * type OrderRepoWithSubdocs = OrderRepo & SubdocumentMethods<IOrder>;
+ * // With type safety for plugin methods
+ * class ProductRepo extends Repository<IProduct> implements MongoOperationsMethods<IProduct> {
+ *   // TypeScript knows about upsert, increment, decrement, etc.
+ * }
  *
- * const repo = new OrderRepo(OrderModel, [
+ * const repo = new ProductRepo(ProductModel, [
  *   methodRegistryPlugin(),
- *   subdocumentPlugin(),
- * ]) as OrderRepoWithSubdocs;
+ *   mongoOperationsPlugin(),
+ * ]);
  *
- * // 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);
+ * // Now TypeScript provides autocomplete and type checking
+ * await repo.increment(productId, 'views', 1);
+ * await repo.upsert({ sku: 'ABC' }, { name: 'Product' });
  * ```
  */
-interface SubdocumentMethods<TDoc> {
+interface MongoOperationsMethods<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
+   * 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
    */
-  addSubdocument(parentId: string | ObjectId, arrayPath: string, subData: Record<string, unknown>, options?: Record<string, unknown>): Promise<TDoc>;
+  upsert(query: Record<string, unknown>, data: 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
+   * 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
    */
-  getSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: {
-    lean?: boolean;
-    session?: unknown;
-  }): Promise<Record<string, unknown>>;
+  increment(id: string | ObjectId, field: string, value?: number, options?: Record<string, unknown>): Promise<TDoc>;
   /**
-   * 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
+   * 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
    */
-  updateSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, updateData: Record<string, unknown>, options?: {
-    session?: unknown;
-  }): Promise<TDoc>;
+  decrement(id: string | ObjectId, field: string, value?: number, options?: Record<string, 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
+   * 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
    */
-  deleteSubdocument(parentId: string | ObjectId, arrayPath: string, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
-}
-//#endregion
-//#region src/plugins/cache.plugin.d.ts
-/**
- * Cache plugin factory
- *
- * @param options - Cache configuration
- * @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 {
+  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>;
   /**
-   * Invalidate cache for a specific document
-   * Use when document was updated outside this service
-   * @param id - Document ID to invalidate
+   * 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
    */
-  invalidateCache(id: string): Promise<void>;
+  unsetField(id: string | ObjectId, fields: string | string[], options?: Record<string, unknown>): Promise<TDoc>;
   /**
-   * Invalidate all list caches for this model
-   * Use when bulk changes happened outside this service
+   * 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
    */
-  invalidateListCache(): Promise<void>;
+  renameField(id: string | ObjectId, oldName: string, newName: string, options?: Record<string, unknown>): Promise<TDoc>;
   /**
-   * Invalidate ALL cache entries for this model
-   * Nuclear option - use sparingly
+   * 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
    */
-  invalidateAllCache(): Promise<void>;
+  multiplyField(id: string | ObjectId, field: string, multiplier: number, options?: Record<string, unknown>): Promise<TDoc>;
   /**
-   * Get cache statistics for monitoring
-   * @returns Cache statistics (hits, misses, sets, invalidations)
+   * 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
    */
-  getCacheStats(): CacheStats;
+  setMin(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
   /**
-   * Reset cache statistics
+   * 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
    */
-  resetCacheStats(): void;
+  setMax(id: string | ObjectId, field: string, value: unknown, options?: Record<string, unknown>): Promise<TDoc>;
+  /**
+   * Atomic update with multiple MongoDB operators in a single call.
+   * Combines $inc, $set, $push, $pull, $addToSet, $unset, $setOnInsert, etc.
+   *
+   * @param id - Document ID
+   * @param operators - MongoDB update operators (e.g. { $inc: { views: 1 }, $set: { lastViewed: new Date() } })
+   * @param options - Operation options (session, arrayFilters, etc.)
+   * @returns Updated document
+   *
+   * @example
+   * await repo.atomicUpdate(postId, {
+   *   $inc: { reactionCount: -1 },
+   *   $set: { lastActiveAt: new Date() },
+   *   $push: { history: { action: 'unreact', at: new Date() } }
+   * });
+   */
+  atomicUpdate(id: string | ObjectId, operators: Record<string, Record<string, unknown>>, options?: Record<string, unknown>): Promise<TDoc>;
 }
 //#endregion
-//#region src/plugins/cascade.plugin.d.ts
-/**
- * Cascade delete plugin
- *
- * Deletes related documents after the parent document is deleted.
- * Works with both hard delete and soft delete scenarios.
- *
- * @param options - Cascade configuration
- * @returns Plugin
- */
-declare function cascadePlugin(options: CascadeOptions): Plugin;
-//#endregion
 //#region src/plugins/multi-tenant.plugin.d.ts
 interface MultiTenantOptions {
   /** Field name used for tenant isolation (default: 'organizationId') */
@@ -780,308 +864,224 @@ interface ObservabilityOptions {
 }
 declare function observabilityPlugin(options: ObservabilityOptions): Plugin;
 //#endregion
-//#region src/plugins/audit-trail.plugin.d.ts
-interface AuditTrailOptions {
-  /** Operations to track (default: ['create', 'update', 'delete']) */
-  operations?: AuditOperation[];
-  /** Store field-level before/after diff on updates (default: true) */
-  trackChanges?: boolean;
-  /** Store full document snapshot on create (default: false — can be heavy) */
-  trackDocument?: boolean;
-  /** Auto-purge after N days via MongoDB TTL index (default: undefined — keep forever) */
-  ttlDays?: number;
-  /** MongoDB collection name (default: 'audit_trails') */
-  collectionName?: string;
-  /**
-   * Extract custom metadata from the repository context.
-   * Returned object is stored on the audit entry as `metadata`.
-   */
-  metadata?: (context: RepositoryContext) => Record<string, unknown>;
-  /**
-   * Fields to exclude from change tracking (e.g., passwords, tokens).
-   * These fields are redacted in the `changes` diff.
-   */
-  excludeFields?: string[];
-}
-type AuditOperation = 'create' | 'update' | 'delete';
-interface AuditEntry {
-  model: string;
-  operation: AuditOperation;
-  documentId: unknown;
-  userId?: unknown;
-  orgId?: unknown;
-  changes?: Record<string, {
-    from: unknown;
-    to: unknown;
-  }>;
-  document?: Record<string, unknown>;
-  metadata?: Record<string, unknown>;
-  timestamp: Date;
-}
-declare function auditTrailPlugin(options?: AuditTrailOptions): Plugin;
-interface AuditQueryOptions {
-  model?: string;
-  documentId?: string | ObjectId;
-  userId?: string | ObjectId;
-  orgId?: string | ObjectId;
-  operation?: AuditOperation;
-  from?: Date;
-  to?: Date;
-  page?: number;
-  limit?: number;
-}
-interface AuditQueryResult {
-  docs: AuditEntry[];
-  page: number;
-  limit: number;
-  total: number;
-  pages: number;
-  hasNext: boolean;
-  hasPrev: boolean;
-}
+//#region src/plugins/soft-delete.plugin.d.ts
 /**
- * Standalone audit trail query utility.
- * Use this to query audits across all models — e.g., admin dashboards, audit APIs.
+ * Soft delete plugin
  *
- * @example
+ * @example Basic usage
  * ```typescript
- * import { AuditTrailQuery } from '@classytic/mongokit';
+ * const repo = new Repository(Model, [
+ *   softDeletePlugin({ deletedField: 'deletedAt' })
+ * ]);
  *
- * const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
+ * // Delete (soft)
+ * await repo.delete(id);
  *
- * // All audits for an org
- * const orgAudits = await auditQuery.query({ orgId: '...' });
+ * // Restore
+ * await repo.restore(id);
  *
- * // All updates by a user
- * const userUpdates = await auditQuery.query({
- *   userId: '...',
- *   operation: 'update',
- * });
+ * // Get deleted documents
+ * await repo.getDeleted({ page: 1, limit: 20 });
+ * ```
  *
- * // All audits for a specific document
- * const docHistory = await auditQuery.query({
- *   model: 'Job',
- *   documentId: '...',
- * });
+ * @example With null filter mode (for schemas with default: null)
+ * ```typescript
+ * // Schema: { deletedAt: { type: Date, default: null } }
+ * const repo = new Repository(Model, [
+ *   softDeletePlugin({
+ *     deletedField: 'deletedAt',
+ *     filterMode: 'null', // default - works with default: null
+ *   })
+ * ]);
+ * ```
  *
- * // Date range
- * const recent = await auditQuery.query({
- *   from: new Date('2025-01-01'),
- *   to: new Date(),
- *   page: 1,
- *   limit: 50,
- * });
+ * @example With TTL for auto-cleanup
+ * ```typescript
+ * const repo = new Repository(Model, [
+ *   softDeletePlugin({
+ *     deletedField: 'deletedAt',
+ *     ttlDays: 30, // Auto-delete after 30 days
+ *   })
+ * ]);
+ * ```
+ */
+declare function softDeletePlugin(options?: SoftDeleteOptions): Plugin;
+/**
+ * TypeScript interface for soft delete plugin methods
  *
- * // Direct model access for custom queries
- * const model = auditQuery.getModel();
- * const count = await model.countDocuments({ operation: 'delete' });
+ * @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 });
  * ```
  */
-declare class AuditTrailQuery {
-  private model;
-  constructor(collectionName?: string, ttlDays?: number);
-  /**
-   * Get the underlying Mongoose model for custom queries
-   */
-  getModel(): mongoose.Model<AuditEntry>;
-  /**
-   * Query audit entries with filters and pagination
-   */
-  query(options?: AuditQueryOptions): Promise<AuditQueryResult>;
-  /**
-   * Get audit trail for a specific document
-   */
-  getDocumentTrail(model: string, documentId: string | ObjectId, options?: {
-    page?: number;
-    limit?: number;
-    operation?: AuditOperation;
-  }): Promise<AuditQueryResult>;
-  /**
-   * Get all audits for a user
-   */
-  getUserTrail(userId: string | ObjectId, options?: {
-    page?: number;
-    limit?: number;
-    operation?: AuditOperation;
-    orgId?: string | ObjectId;
-  }): Promise<AuditQueryResult>;
+interface SoftDeleteMethods<TDoc> {
   /**
-   * Get all audits for an organization
-   */
-  getOrgTrail(orgId: string | ObjectId, options?: {
-    page?: number;
-    limit?: number;
-    operation?: AuditOperation;
-    model?: string;
-  }): Promise<AuditQueryResult>;
-}
-interface AuditTrailMethods {
+   * 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 audit trail for a document
+   * 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
    */
-  getAuditTrail(documentId: string | ObjectId, options?: {
+  getDeleted(params?: {
+    filters?: Record<string, unknown>;
+    sort?: SortSpec | string;
     page?: number;
     limit?: number;
-    operation?: AuditOperation;
-  }): Promise<AuditQueryResult>;
-}
-//#endregion
-//#region src/plugins/elastic.plugin.d.ts
-interface ElasticSearchOptions {
-  /** Elasticsearch or OpenSearch client instance */
-  client: any;
-  /** Index name to perform search against */
-  index: string;
-  /** Field to extract MongoDB ID from the indexed document (default: '_id') */
-  idField?: string;
+  }, options?: {
+    select?: SelectSpec;
+    populate?: PopulateSpec;
+    lean?: boolean;
+    session?: ClientSession;
+  }): Promise<OffsetPaginationResult<TDoc>>;
 }
-declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
 //#endregion
-//#region src/plugins/custom-id.plugin.d.ts
-/**
- * Generator function that produces a unique ID.
- * Receives the full repository context for conditional logic.
- */
-type IdGenerator = (context: RepositoryContext) => string | Promise<string>;
-interface CustomIdOptions {
-  /** Field to store the custom ID (default: 'customId') */
-  field?: string;
-  /** Function to generate the ID. Can be async. */
-  generator: IdGenerator;
-  /** Only generate if the field is missing/empty (default: true) */
-  generateOnlyIfEmpty?: boolean;
-}
+//#region src/plugins/subdocument.plugin.d.ts
 /**
- * Atomically increment and return the next sequence value for a given key.
- * Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
- * heavy concurrency.
- *
- * @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
- * @param increment - Value to increment by (default: 1)
- * @returns The next sequence number (after increment)
+ * Subdocument plugin for managing nested arrays
  *
  * @example
- * const seq = await getNextSequence('invoices');
- * // First call → 1, second → 2, ...
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   subdocumentPlugin(),
+ * ]);
  *
- * @example Batch increment for createMany
- * const startSeq = await getNextSequence('invoices', 5);
- * // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
+ * await repo.addSubdocument(parentId, 'items', { name: 'Item 1' });
+ * await repo.updateSubdocument(parentId, 'items', itemId, { name: 'Updated Item' });
  */
-declare function getNextSequence(counterKey: string, increment?: number, connection?: mongoose.Connection): Promise<number>;
-interface SequentialIdOptions {
-  /** Prefix string (e.g., 'INV', 'ORD') */
-  prefix: string;
-  /** Mongoose model — used to derive the counter key from model name */
-  model: mongoose.Model<any>;
-  /** Number of digits to pad to (default: 4 → "0001") */
-  padding?: number;
-  /** Separator between prefix and number (default: '-') */
-  separator?: string;
-  /** Custom counter key override (default: model.modelName) */
-  counterKey?: string;
-}
+declare function subdocumentPlugin(): Plugin;
 /**
- * Generator: Simple sequential counter.
- * Produces IDs like `INV-0001`, `INV-0002`, etc.
- *
- * Uses atomic MongoDB counters — safe under concurrency.
+ * Type interface for repositories using subdocumentPlugin
  *
  * @example
  * ```typescript
- * customIdPlugin({
- *   field: 'invoiceNumber',
- *   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
- * })
+ * 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);
  * ```
  */
-declare function sequentialId(options: SequentialIdOptions): IdGenerator;
-interface DateSequentialIdOptions {
-  /** Prefix string (e.g., 'BILL', 'INV') */
-  prefix: string;
-  /** Mongoose model — used to derive the counter key */
-  model: mongoose.Model<any>;
+interface SubdocumentMethods<TDoc> {
   /**
-   * Partition granularity — counter resets each period.
-   * - 'yearly'  → BILL-2026-0001, resets every January
-   * - 'monthly' → BILL-2026-02-0001, resets every month
-   * - 'daily'   → BILL-2026-02-20-0001, resets every day
+   * 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
    */
-  partition?: 'yearly' | 'monthly' | 'daily';
-  /** Number of digits to pad to (default: 4) */
-  padding?: number;
-  /** Separator (default: '-') */
-  separator?: string;
+  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>;
 }
+//#endregion
+//#region src/plugins/timestamp.plugin.d.ts
 /**
- * Generator: Date-partitioned sequential counter.
- * Counter resets per period — great for invoice/bill numbering.
- *
- * Produces IDs like:
- * - yearly:  `BILL-2026-0001`
- * - monthly: `BILL-2026-02-0001`
- * - daily:   `BILL-2026-02-20-0001`
+ * Timestamp plugin that auto-injects timestamps
  *
  * @example
- * ```typescript
- * customIdPlugin({
- *   field: 'billNumber',
- *   generator: dateSequentialId({
- *     prefix: 'BILL',
- *     model: BillModel,
- *     partition: 'monthly',
- *   }),
- * })
- * ```
+ * const repo = new Repository(Model, [timestampPlugin()]);
  */
-declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
-interface PrefixedIdOptions {
-  /** Prefix string (e.g., 'USR', 'TXN') */
-  prefix: string;
-  /** Separator (default: '_') */
-  separator?: string;
-  /** Length of the random suffix (default: 12) */
-  length?: number;
-}
+declare function timestampPlugin(): Plugin;
+//#endregion
+//#region src/plugins/validation-chain.plugin.d.ts
+type OperationType = 'create' | 'createMany' | 'update' | 'delete';
 /**
- * Generator: Prefix + random alphanumeric suffix.
- * Does NOT require a database round-trip — purely in-memory.
- *
- * Produces IDs like: `USR_a7b3xk9m2p1q`
- *
- * Good for: user-facing IDs where ordering doesn't matter.
- * Not suitable for sequential numbering.
+ * Validation chain plugin
  *
  * @example
- * ```typescript
- * customIdPlugin({
- *   field: 'publicId',
- *   generator: prefixedId({ prefix: 'USR', length: 10 }),
- * })
- * ```
+ * const repo = new Repository(Model, [
+ *   validationChainPlugin([
+ *     requireField('email'),
+ *     uniqueField('email', 'Email already exists'),
+ *     blockIf('no-delete-admin', ['delete'], ctx => ctx.data?.role === 'admin', 'Cannot delete admin'),
+ *   ])
+ * ]);
  */
-declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
+declare function validationChainPlugin(validators?: ValidatorDefinition[], options?: ValidationChainOptions): Plugin;
 /**
- * Custom ID plugin — injects generated IDs into documents before creation.
- *
- * @param options - Configuration for ID generation
- * @returns Plugin instance
+ * Block operation if condition is true
  *
  * @example
- * ```typescript
- * import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
- *
- * const invoiceRepo = new Repository(InvoiceModel, [
- *   customIdPlugin({
- *     field: 'invoiceNumber',
- *     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
- *   }),
- * ]);
- *
- * const inv = await invoiceRepo.create({ amount: 100 });
- * console.log(inv.invoiceNumber); // "INV-0001"
- * ```
+ * blockIf('block-library', ['delete'], ctx => ctx.data?.managed, 'Cannot delete managed records')
  */
-declare function customIdPlugin(options: CustomIdOptions): Plugin;
+declare function blockIf(name: string, operations: OperationType[], condition: (context: RepositoryContext) => boolean, errorMessage: string): ValidatorDefinition;
+/**
+ * Require a field to be present
+ */
+declare function requireField(field: string, operations?: OperationType[]): ValidatorDefinition;
+/**
+ * Auto-inject a value if not present
+ */
+declare function autoInject(field: string, getter: (context: RepositoryContext) => unknown, operations?: OperationType[]): ValidatorDefinition;
+/**
+ * Make a field immutable (cannot be updated)
+ */
+declare function immutableField(field: string): ValidatorDefinition;
+/**
+ * Ensure field value is unique
+ */
+declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { subdocumentPlugin as A, immutableField as B, observabilityPlugin as C, CacheMethods as D, cascadePlugin as E, batchOperationsPlugin as F, methodRegistryPlugin as G, uniqueField as H, MongoOperationsMethods as I, auditLogPlugin as J, SoftDeleteMethods as K, mongoOperationsPlugin as L, aggregateHelpersPlugin as M, BatchOperationsMethods as N, cachePlugin as O, BulkWriteResult as P, autoInject as R, OperationMetric as S, multiTenantPlugin as T, validationChainPlugin as U, requireField as V, MethodRegistryRepository as W, fieldFilterPlugin as X, timestampPlugin as Y, AuditTrailMethods as _, SequentialIdOptions as a, auditTrailPlugin as b, getNextSequence as c, ElasticSearchOptions as d, elasticSearchPlugin as f, AuditQueryResult as g, AuditQueryOptions as h, PrefixedIdOptions as i, AggregateHelpersMethods as j, SubdocumentMethods as k, prefixedId as l, AuditOperation as m, DateSequentialIdOptions as n, customIdPlugin as o, AuditEntry as p, softDeletePlugin as q, IdGenerator as r, dateSequentialId as s, CustomIdOptions as t, sequentialId as u, AuditTrailOptions as v, MultiTenantOptions as w, ObservabilityOptions as x, AuditTrailQuery as y, blockIf as z };
+export { dateSequentialId as A, AuditEntry as B, elasticSearchPlugin as C, PrefixedIdOptions as D, IdGenerator as E, CacheMethods as F, AuditTrailOptions as G, AuditQueryOptions as H, cachePlugin as I, auditLogPlugin as J, AuditTrailQuery as K, BatchOperationsMethods as L, prefixedId as M, sequentialId as N, SequentialIdOptions as O, cascadePlugin as P, BulkWriteResult as R, ElasticSearchOptions as S, DateSequentialIdOptions as T, AuditQueryResult as U, AuditOperation as V, AuditTrailMethods as W, aggregateHelpersPlugin as X, AggregateHelpersMethods as Y, MongoOperationsMethods as _, uniqueField as a, methodRegistryPlugin as b, SubdocumentMethods as c, softDeletePlugin as d, ObservabilityOptions as f, multiTenantPlugin as g, MultiTenantOptions as h, requireField as i, getNextSequence as j, customIdPlugin as k, subdocumentPlugin as l, observabilityPlugin as m, blockIf as n, validationChainPlugin as o, OperationMetric as p, auditTrailPlugin as q, immutableField as r, timestampPlugin as s, autoInject as t, SoftDeleteMethods as u, mongoOperationsPlugin as v, CustomIdOptions as w, fieldFilterPlugin as x, MethodRegistryRepository as y, batchOperationsPlugin as z };