@classytic/mongokit 3.2.0 → 3.2.2

package/dist/custom-id.plugin-BzZI4gnE.d.mts

@@ -0,0 +1,893 @@
+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-D-gploPr.mjs";
+import mongoose, { ClientSession } from "mongoose";
+
+//#region src/plugins/field-filter.plugin.d.ts
+/**
+ * Field filter plugin that restricts fields based on user context
+ *
+ * @example
+ * 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/timestamp.plugin.d.ts
+/**
+ * Timestamp plugin that auto-injects timestamps
+ *
+ * @example
+ * const repo = new Repository(Model, [timestampPlugin()]);
+ */
+declare function timestampPlugin(): Plugin;
+//#endregion
+//#region src/plugins/audit-log.plugin.d.ts
+/**
+ * Audit log plugin that logs all repository operations
+ *
+ * @example
+ * const repo = new Repository(Model, [auditLogPlugin(console)]);
+ */
+declare function auditLogPlugin(logger: Logger): Plugin;
+//#endregion
+//#region src/plugins/soft-delete.plugin.d.ts
+/**
+ * Soft delete plugin
+ *
+ * @example Basic usage
+ * ```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 });
+ * ```
+ *
+ * @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
+ *   })
+ * ]);
+ * ```
+ *
+ * @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
+ *
+ * @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>>;
+}
+//#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/validation-chain.plugin.d.ts
+type OperationType = 'create' | 'createMany' | 'update' | 'delete';
+/**
+ * Validation chain 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'),
+ *   ])
+ * ]);
+ */
+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
+ */
+declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
+//#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(),
+ *   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>;
+}
+//#endregion
+//#region src/plugins/batch-operations.plugin.d.ts
+/**
+ * Batch operations plugin
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   batchOperationsPlugin(),
+ * ]);
+ *
+ * await repo.updateMany({ status: 'pending' }, { status: 'active' });
+ * 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;
+  }>;
+}
+//#endregion
+//#region src/plugins/aggregate-helpers.plugin.d.ts
+/**
+ * Aggregate helpers plugin
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   aggregateHelpersPlugin(),
+ * ]);
+ *
+ * const groups = await repo.groupBy('category');
+ * 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>;
+}
+//#endregion
+//#region src/plugins/subdocument.plugin.d.ts
+/**
+ * Subdocument plugin for managing nested arrays
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   subdocumentPlugin(),
+ * ]);
+ *
+ * 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
+ *
+ * @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>;
+}
+//#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 {
+  /**
+   * 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;
+}
+//#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') */
+  tenantField?: string;
+  /** Context key to read tenant ID from (default: 'organizationId') */
+  contextKey?: string;
+  /** Throw if tenant ID is missing from context (default: true) */
+  required?: boolean;
+  /** Operations to skip tenant injection (e.g., for admin/system queries) */
+  skipOperations?: string[];
+  /**
+   * Dynamic skip — receives the context and operation name, returns true to
+   * bypass tenant scoping for this call. Use for role-based bypass (e.g.,
+   * super admin) without needing a separate repo instance.
+   *
+   * @example
+   * ```typescript
+   * skipWhen: (context) => context.role === 'superadmin'
+   * ```
+   */
+  skipWhen?: (context: RepositoryContext, operation: string) => boolean;
+  /**
+   * Resolve tenant ID from external source (e.g., AsyncLocalStorage, CLS).
+   * Called when tenant ID is not found in context. If it returns a value,
+   * that value is used as the tenant ID without requiring it in context.
+   *
+   * @example
+   * ```typescript
+   * resolveContext: () => asyncLocalStorage.getStore()?.tenantId
+   * ```
+   */
+  resolveContext?: () => string | undefined;
+}
+declare function multiTenantPlugin(options?: MultiTenantOptions): Plugin;
+//#endregion
+//#region src/plugins/observability.plugin.d.ts
+interface OperationMetric {
+  /** Operation name (e.g., 'create', 'getAll', 'update') */
+  operation: string;
+  /** Model/collection name */
+  model: string;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Timestamp when the operation started */
+  startedAt: Date;
+  /** User ID if available */
+  userId?: string;
+  /** Organization ID if available */
+  organizationId?: string;
+}
+interface ObservabilityOptions {
+  /** Callback invoked after every operation with timing data */
+  onMetric: (metric: OperationMetric) => void;
+  /** Operations to track (default: all) */
+  operations?: string[];
+  /** Threshold in ms — only report operations slower than this */
+  slowThresholdMs?: number;
+}
+declare function observabilityPlugin(options: ObservabilityOptions): 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/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 seq = await getNextSequence('invoices');
+ * // First call → 1, second → 2, ...
+ *
+ * @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 getNextSequence(counterKey: string, increment?: number): 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;
+}
+/**
+ * Generator: Simple sequential counter.
+ * Produces IDs like `INV-0001`, `INV-0002`, etc.
+ *
+ * Uses atomic MongoDB counters — safe under concurrency.
+ *
+ * @example
+ * ```typescript
+ * 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.
+ *
+ * Produces IDs like:
+ * - yearly:  `BILL-2026-0001`
+ * - monthly: `BILL-2026-02-0001`
+ * - daily:   `BILL-2026-02-20-0001`
+ *
+ * @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.
+ *
+ * Produces IDs like: `USR_a7b3xk9m2p1q`
+ *
+ * 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 }),
+ * })
+ * ```
+ */
+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
+export { blockIf as A, timestampPlugin as B, AggregateHelpersMethods as C, MongoOperationsMethods as D, batchOperationsPlugin as E, MethodRegistryRepository as F, methodRegistryPlugin as I, SoftDeleteMethods as L, requireField as M, uniqueField as N, mongoOperationsPlugin as O, validationChainPlugin as P, softDeletePlugin as R, subdocumentPlugin as S, BatchOperationsMethods as T, fieldFilterPlugin as V, multiTenantPlugin as _, SequentialIdOptions as a, cachePlugin as b, getNextSequence as c, ElasticSearchOptions as d, elasticSearchPlugin as f, MultiTenantOptions as g, observabilityPlugin as h, PrefixedIdOptions as i, immutableField as j, autoInject as k, prefixedId as l, OperationMetric as m, DateSequentialIdOptions as n, customIdPlugin as o, ObservabilityOptions as p, IdGenerator as r, dateSequentialId as s, CustomIdOptions as t, sequentialId as u, cascadePlugin as v, aggregateHelpersPlugin as w, SubdocumentMethods as x, CacheMethods as y, auditLogPlugin as z };