@classytic/mongokit 2.0.0 → 2.1.0

package/dist/plugins/index.d.ts

@@ -0,0 +1,275 @@
+import { F as FieldPreset, p as Plugin, L as Logger, B as SoftDeleteOptions, r as RepositoryInstance, y as ValidatorDefinition, z as ValidationChainOptions, R as RepositoryContext, Q as CacheOptions } from '../types-Nxhmi1aI.js';
+import 'mongoose';
+
+/**
+ * Field Filter Plugin
+ * Automatically filters response fields based on user roles
+ */
+
+/**
+ * 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;
+
+/**
+ * Timestamp Plugin
+ * Auto-injects createdAt/updatedAt timestamps on create/update
+ */
+
+/**
+ * Timestamp plugin that auto-injects timestamps
+ *
+ * @example
+ * const repo = new Repository(Model, [timestampPlugin()]);
+ */
+declare function timestampPlugin(): Plugin;
+
+/**
+ * Audit Log Plugin
+ * Logs repository operations for auditing purposes
+ */
+
+/**
+ * Audit log plugin that logs all repository operations
+ *
+ * @example
+ * const repo = new Repository(Model, [auditLogPlugin(console)]);
+ */
+declare function auditLogPlugin(logger: Logger): Plugin;
+
+/**
+ * Soft Delete Plugin
+ * Implements soft delete pattern - marks documents as deleted instead of removing
+ */
+
+/**
+ * Soft delete plugin
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   softDeletePlugin({ deletedField: 'deletedAt' })
+ * ]);
+ */
+declare function softDeletePlugin(options?: SoftDeleteOptions): Plugin;
+
+/**
+ * Method Registry Plugin
+ *
+ * Enables plugins to dynamically add methods to repository instances.
+ * Foundation for extensibility - allows other plugins to extend repositories
+ * with custom methods while maintaining type safety and proper binding.
+ *
+ * @example
+ * ```typescript
+ * const repo = new Repository(User, [methodRegistryPlugin()]);
+ *
+ * // Now you can register custom methods
+ * repo.registerMethod('findActive', async function() {
+ *   return this.getAll({ filters: { status: 'active' } });
+ * });
+ * ```
+ */
+
+/**
+ * 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;
+
+/**
+ * Validation Chain Plugin
+ *
+ * Composable validation for repository operations with customizable rules.
+ */
+
+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;
+
+/**
+ * MongoDB Operations Plugin
+ *
+ * Adds MongoDB-specific operations to repositories.
+ * Requires method-registry.plugin.js to be loaded first.
+ */
+
+/**
+ * MongoDB operations plugin
+ *
+ * @example
+ * const repo = new Repository(Model, [
+ *   methodRegistryPlugin(),
+ *   mongoOperationsPlugin(),
+ * ]);
+ *
+ * await repo.increment(productId, 'views', 1);
+ * await repo.pushToArray(productId, 'tags', 'featured');
+ */
+declare function mongoOperationsPlugin(): Plugin;
+
+/**
+ * Batch Operations Plugin
+ * Adds bulk update/delete operations with proper event emission
+ */
+
+/**
+ * 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;
+
+/**
+ * Aggregate Helpers Plugin
+ * Adds common aggregation helper methods
+ */
+
+/**
+ * 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;
+
+/**
+ * Subdocument Plugin
+ * Adds subdocument array operations
+ */
+
+/**
+ * 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;
+
+/**
+ * Cache Plugin
+ *
+ * Optional caching layer for MongoKit with automatic invalidation.
+ * Bring-your-own cache adapter (Redis, Memcached, in-memory, etc.)
+ *
+ * Features:
+ * - Cache-aside (read-through) pattern with configurable TTLs
+ * - Automatic invalidation on create/update/delete
+ * - Collection version tags for efficient list cache invalidation
+ * - Manual invalidation methods for microservice scenarios
+ * - Skip cache per-operation with `skipCache: true`
+ *
+ * @example
+ * ```typescript
+ * import { Repository, cachePlugin } from '@classytic/mongokit';
+ * import Redis from 'ioredis';
+ *
+ * const redis = new Redis();
+ *
+ * const userRepo = new Repository(UserModel, [
+ *   cachePlugin({
+ *     adapter: {
+ *       async get(key) { return JSON.parse(await redis.get(key) || 'null'); },
+ *       async set(key, value, ttl) { await redis.setex(key, ttl, JSON.stringify(value)); },
+ *       async del(key) { await redis.del(key); },
+ *       async clear(pattern) {
+ *         const keys = await redis.keys(pattern || '*');
+ *         if (keys.length) await redis.del(...keys);
+ *       }
+ *     },
+ *     ttl: 60, // 1 minute default
+ *   })
+ * ]);
+ *
+ * // Reads check cache first
+ * const user = await userRepo.getById(id); // cached
+ *
+ * // Skip cache for fresh data
+ * const fresh = await userRepo.getById(id, { skipCache: true });
+ *
+ * // Mutations auto-invalidate
+ * await userRepo.update(id, { name: 'New Name' }); // invalidates cache
+ *
+ * // Manual invalidation for microservice sync
+ * await userRepo.invalidateCache(id); // invalidate single doc
+ * await userRepo.invalidateAllCache(); // invalidate all for this model
+ * ```
+ */
+
+/**
+ * Cache plugin factory
+ *
+ * @param options - Cache configuration
+ * @returns Plugin instance
+ */
+declare function cachePlugin(options: CacheOptions): Plugin;
+
+export { type MethodRegistryRepository, aggregateHelpersPlugin, auditLogPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, fieldFilterPlugin, immutableField, methodRegistryPlugin, mongoOperationsPlugin, requireField, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };