@plyaz/types 1.3.2 → 1.3.3

package/dist/testing/common/patterns/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/testing/common/patterns/types.d.ts

@@ -0,0 +1,397 @@
+/**
+ * @fileoverview Testing Pattern Types
+ *
+ * Type definitions for common testing patterns including batch operations,
+ * CRUD operations, and test result management. Provides standardized interfaces
+ * for building scalable and maintainable test suites.
+ *
+ * This module includes types for:
+ * - Operation types and interfaces (CRUD + custom)
+ * - Batch processing and operation results
+ * - Test helpers and mock handlers
+ * - Progress tracking and error handling
+ * - Concurrent operation management
+ * - Stream processing for large datasets
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   Operation,
+ *   BatchOperationResult,
+ *   CreateBatchProcessorReturn
+ * } from './types';
+ *
+ * // Define operations
+ * const operations: Operation<User>[] = [
+ *   { type: 'create', data: { name: 'John' } },
+ *   { type: 'update', data: { id: 1, name: 'Jane' } },
+ *   { type: 'delete', data: { id: 2 } }
+ * ];
+ *
+ * // Process operations in batch
+ * const processor: CreateBatchProcessorReturn<User> = createBatchProcessor({
+ *   batchSize: 10,
+ *   concurrency: 3
+ * });
+ *
+ * const result: BatchOperationResult<User> = await processor.process(operations);
+ * ```
+ *
+ * @module TestingPatternTypes
+ * @since 1.0.0
+ */
+import type * as Vitest from 'vitest';
+/**
+ * Base operation types for CRUD and custom operations
+ *
+ * Defines the standard operation types supported by the testing framework.
+ * Covers basic CRUD operations plus custom operations for specialized testing.
+ *
+ * @example
+ * ```typescript
+ * const userOperations: OperationType[] = ['create', 'read', 'update', 'delete'];
+ * const customOperation: OperationType = 'custom';
+ *
+ * // Use in operation definitions
+ * const createUser: Operation = { type: 'create', data: userData };
+ * const validateData: Operation = { type: 'custom', data: validationRules };
+ * ```
+ */
+export type OperationType = 'create' | 'update' | 'delete' | 'read' | 'custom';
+/**
+ * Generic operation interface for testing patterns
+ *
+ * Represents a single operation to be performed during testing. Supports
+ * any operation type with optional data payload and metadata for tracking.
+ *
+ * @typeParam T - Type of data associated with the operation
+ *
+ * @example
+ * ```typescript
+ * // User management operations
+ * const createUser: Operation<CreateUserData> = {
+ *   id: 'op-1',
+ *   type: 'create',
+ *   data: { name: 'John Doe', email: 'john@example.com' },
+ *   metadata: { timestamp: Date.now(), source: 'test-suite' }
+ * };
+ *
+ * const updateUser: Operation<UpdateUserData> = {
+ *   id: 'op-2',
+ *   type: 'update',
+ *   data: { id: 1, name: 'Jane Doe' },
+ *   metadata: { reason: 'name-change' }
+ * };
+ *
+ * const deleteUser: Operation<{ id: number }> = {
+ *   id: 'op-3',
+ *   type: 'delete',
+ *   data: { id: 1 }
+ * };
+ *
+ * // Custom validation operation
+ * const validateData: Operation<ValidationRules> = {
+ *   type: 'custom',
+ *   data: { rules: ['required', 'email'], field: 'userEmail' },
+ *   metadata: { validator: 'email-validator' }
+ * };
+ * ```
+ */
+export interface Operation<T = unknown> {
+    id?: string;
+    type: OperationType;
+    data?: T;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a single operation execution
+ *
+ * Contains the outcome of executing an operation, including success status,
+ * result data, error information, and performance metrics.
+ *
+ * @typeParam T - Type of data returned by the operation
+ *
+ * @example
+ * ```typescript
+ * // Successful operation result
+ * const successResult: OperationResult<User> = {
+ *   id: 'op-1',
+ *   success: true,
+ *   data: { id: 1, name: 'John Doe', email: 'john@example.com' },
+ *   duration: 250 // milliseconds
+ * };
+ *
+ * // Failed operation result
+ * const failureResult: OperationResult<User> = {
+ *   id: 'op-2',
+ *   success: false,
+ *   error: new Error('User validation failed'),
+ *   duration: 100
+ * };
+ *
+ * // Process results
+ * function handleResult(result: OperationResult<User>) {
+ *   if (result.success) {
+ *     console.log('Created user:', result.data?.name);
+ *   } else {
+ *     console.error('Operation failed:', result.error?.message);
+ *   }
+ *
+ *   if (result.duration && result.duration > 1000) {
+ *     console.warn('Slow operation detected:', result.duration, 'ms');
+ *   }
+ * }
+ * ```
+ */
+export interface OperationResult<T = unknown> {
+    id?: string;
+    success: boolean;
+    data?: T;
+    error?: Error;
+    duration?: number;
+}
+/**
+ * Result of batch operation processing
+ *
+ * Aggregates results from multiple operations processed as a batch,
+ * providing summary statistics, individual results, and error tracking.
+ *
+ * @typeParam T - Type of data processed in the batch operations
+ *
+ * @example
+ * ```typescript
+ * // Process a batch of user operations
+ * const batchResult: BatchOperationResult<User> = {
+ *   totalOperations: 100,
+ *   successCount: 95,
+ *   failureCount: 5,
+ *   results: [
+ *     { id: 'op-1', success: true, data: user1, duration: 150 },
+ *     { id: 'op-2', success: false, error: validationError, duration: 50 },
+ *     // ... more results
+ *   ],
+ *   totalDuration: 15000, // 15 seconds total
+ *   errors: [
+ *     new Error('Validation failed for op-2'),
+ *     new Error('Database timeout for op-47'),
+ *     // ... more errors
+ *   ]
+ * };
+ *
+ * // Analyze batch results
+ * function analyzeBatch(result: BatchOperationResult<User>) {
+ *   const successRate = (result.successCount / result.totalOperations) * 100;
+ *   const avgDuration = result.totalDuration / result.totalOperations;
+ *
+ *   console.log(`Batch completed: ${successRate}% success rate`);
+ *   console.log(`Average operation time: ${avgDuration}ms`);
+ *
+ *   if (result.errors.length > 0) {
+ *     console.log('Errors encountered:', result.errors.map(e => e.message));
+ *   }
+ * }
+ * ```
+ */
+export interface BatchOperationResult<T = unknown> {
+    totalOperations: number;
+    successCount: number;
+    failureCount: number;
+    results: OperationResult<T>[];
+    totalDuration: number;
+    errors: Error[];
+}
+/**
+ * Configuration options for batch operation processors
+ *
+ * Defines how batch operations should be processed, including performance
+ * tuning, error handling, retry logic, and progress tracking.
+ *
+ * @example
+ * ```typescript
+ * // High-throughput batch processing
+ * const highThroughputOptions: BatchProcessorOptions = {
+ *   batchSize: 50,
+ *   concurrency: 10,
+ *   retryCount: 3,
+ *   retryDelay: 1000,
+ *   continueOnError: true,
+ *   timeout: 30000,
+ *   onProgress: (progress) => {
+ *     const percent = (progress.completed / progress.total) * 100;
+ *     console.log(`Progress: ${percent.toFixed(1)}% (${progress.completed}/${progress.total})`);
+ *   }
+ * };
+ *
+ * // Conservative batch processing
+ * const conservativeOptions: BatchProcessorOptions = {
+ *   batchSize: 10,
+ *   concurrency: 2,
+ *   retryCount: 5,
+ *   retryDelay: 2000,
+ *   continueOnError: false,
+ *   timeout: 60000
+ * };
+ *
+ * // Quick testing batch
+ * const testOptions: BatchProcessorOptions = {
+ *   batchSize: 5,
+ *   concurrency: 1,
+ *   retryCount: 0,
+ *   continueOnError: true,
+ *   timeout: 5000
+ * };
+ * ```
+ */
+export interface BatchProcessorOptions {
+    batchSize?: number;
+    concurrency?: number;
+    retryCount?: number;
+    retryDelay?: number;
+    continueOnError?: boolean;
+    timeout?: number;
+    onProgress?: (progress: {
+        completed: number;
+        total: number;
+    }) => void;
+}
+/**
+ * Return type for batch processor factory functions
+ *
+ * Provides methods for processing operations in batches, supporting both
+ * array-based and stream-based operation processing.
+ *
+ * @typeParam T - Type of data being processed in operations
+ *
+ * @example
+ * ```typescript
+ * // Create a batch processor
+ * const processor: CreateBatchProcessorReturn<User> = createBatchProcessor({
+ *   batchSize: 25,
+ *   concurrency: 5,
+ *   retryCount: 3
+ * });
+ *
+ * // Process array of operations
+ * const operations: Operation<User>[] = generateUserOperations(100);
+ * const result = await processor.process(operations);
+ *
+ * console.log(`Processed ${result.totalOperations} operations`);
+ * console.log(`Success rate: ${(result.successCount / result.totalOperations) * 100}%`);
+ *
+ * // Process stream of operations (for large datasets)
+ * async function* operationGenerator(): AsyncGenerator<Operation<User>> {
+ *   for (let i = 0; i < 10000; i++) {
+ *     yield { type: 'create', data: generateUser() };
+ *   }
+ * }
+ *
+ * const streamResult = await processor.processStream(operationGenerator());
+ * console.log(`Stream processed ${streamResult.totalOperations} operations`);
+ * ```
+ */
+export interface CreateBatchProcessorReturn<T> {
+    process(operations: Operation<T>[]): Promise<BatchOperationResult<T>>;
+    processStream(operationStream: AsyncIterable<Operation<T>>): Promise<BatchOperationResult<T>>;
+}
+/**
+ * Return type for batch test helper factory functions
+ *
+ * Provides utilities for generating test operations, simulating failures,
+ * and asserting batch results. Essential for comprehensive batch testing.
+ *
+ * @typeParam T - Type of data used in test operations
+ *
+ * @example
+ * ```typescript
+ * // Create batch test helper
+ * const helper: CreateBatchTestHelperReturn<User> = createBatchTestHelper<User>();
+ *
+ * // Generate mixed operations for testing
+ * const operations = helper.generateOperations(100, {
+ *   create: 0.4,  // 40% create operations
+ *   update: 0.3,  // 30% update operations
+ *   delete: 0.2,  // 20% delete operations
+ *   read: 0.1     // 10% read operations
+ * });
+ *
+ * // Simulate failures in the processor
+ * const mockProcessor = vi.fn();
+ * helper.simulateFailures(mockProcessor, 0.1, new Error('Simulated failure'));
+ *
+ * // Process operations and assert results
+ * const processor = createBatchProcessor({ batchSize: 10 });
+ * const result = await processor.process(operations);
+ *
+ * await helper.assertBatchResult(result, {
+ *   minSuccessRate: 0.85,        // At least 85% success
+ *   maxDuration: 30000,          // Complete within 30 seconds
+ *   expectedErrors: ['Simulated failure', 'Network timeout']
+ * });
+ *
+ * console.log('Batch test completed successfully!');
+ * ```
+ */
+export interface CreateBatchTestHelperReturn<T> {
+    generateOperations(count: number, distribution?: Partial<Record<OperationType, number>>): Operation<T>[];
+    simulateFailures(processor: Vitest.Mock, failureRate: number, error?: Error): void;
+    assertBatchResult(result: BatchOperationResult<T>, expectations: {
+        minSuccessRate?: number;
+        maxDuration?: number;
+        expectedErrors?: string[];
+    }): Promise<void>;
+}
+/**
+ * Return type for mock batch handler factory functions
+ *
+ * Provides a mock handler for testing batch operations with tracking
+ * capabilities for processed operations, results, and state management.
+ *
+ * @typeParam T - Type of data returned by the mock handler
+ *
+ * @example
+ * ```typescript
+ * // Create mock batch handler for user operations
+ * const mockHandler: CreateMockBatchHandlerReturn<User> = createMockBatchHandler<User>();
+ *
+ * // Configure handler behavior
+ * mockHandler.handler.mockImplementation(async (operation) => {
+ *   switch (operation.type) {
+ *     case 'create':
+ *       return { id: Math.random(), ...operation.data };
+ *     case 'update':
+ *       return { ...operation.data };
+ *     case 'delete':
+ *       return operation.data;
+ *     default:
+ *       throw new Error(`Unsupported operation: ${operation.type}`);
+ *   }
+ * });
+ *
+ * // Process some operations
+ * const operations: Operation<User>[] = [
+ *   { type: 'create', data: { name: 'John' } },
+ *   { type: 'update', data: { id: 1, name: 'Jane' } }
+ * ];
+ *
+ * for (const op of operations) {
+ *   await mockHandler.handler(op);
+ * }
+ *
+ * // Inspect processed operations
+ * const processed = mockHandler.getProcessedOperations();
+ * console.log(`Processed ${processed.length} operations`);
+ *
+ * // Get results by operation ID
+ * const results = mockHandler.getResults();
+ * console.log('Results:', Object.fromEntries(results));
+ *
+ * // Clear for next test
+ * mockHandler.clear();
+ * ```
+ */
+export interface CreateMockBatchHandlerReturn<T> {
+    handler: Vitest.Mock<(operation: Operation<T>) => Promise<T>>;
+    getProcessedOperations: () => Operation<T>[];
+    getResults: () => Map<string, T>;
+    clear: () => void;
+}

package/dist/testing/common/utils/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';