@plyaz/types 1.3.7 → 1.3.8

package/dist/features/feature-flag/types.d.ts

@@ -331,6 +331,24 @@ export interface FeatureFlagHelpers<FeatureFlagKey extends string = string> {
     isAllEnabled: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<boolean>;
     whenEnabled: <T>(key: FeatureFlagKey, callback: () => T | Promise<T>, fallback?: () => T | Promise<T>, context?: FeatureFlagContext) => Promise<T | undefined>;
 }
+/**
+ * Response structure for fetching feature flag data.
+ * Contains both flags and their associated rules.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const response: FetchFeatureFlagDataResponse<AppFeatures> = {
+ *   flags: [
+ *     { key: 'newUI', name: 'New UI', value: true, isEnabled: true }
+ *   ],
+ *   rules: [
+ *     { flagKey: 'newUI', conditions: { userRole: 'beta' }, value: true }
+ *   ]
+ * };
+ * ```
+ */
 export interface FetchFeatureFlagDataResponse<FeatureFlagKey extends string> {
     flags: FeatureFlag<FeatureFlagKey>[];
     rules: FeatureFlagRule<FeatureFlagKey>[];
@@ -460,66 +478,257 @@ export interface ModuleConfigurationTestInput {
     config: Record<string, unknown>;
     expectedConfig: Record<string, unknown>;
 }
+/**
+ * Input for provider type test cases.
+ * Tests different provider implementations.
+ *
+ * @example
+ * ```typescript
+ * const input: ProviderTypeTestInput = {
+ *   provider: 'LaunchDarklyProvider'
+ * };
+ * ```
+ */
 export interface ProviderTypeTestInput {
+    /** Name or type of the provider to test */
     provider: string;
 }
+/**
+ * Input for feature flag operation test cases.
+ * Tests CRUD and evaluation operations on flags.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const input: FlagOperationTestInput<'darkMode'> = {
+ *   operation: 'evaluate',
+ *   flagKey: 'darkMode',
+ *   context: { userId: '123', userRole: 'admin' },
+ *   expectedResult: true
+ * };
+ * ```
+ */
 export interface FlagOperationTestInput<FeatureFlagKey extends string> {
+    /** Type of operation to perform */
     operation: 'create' | 'update' | 'delete' | 'evaluate';
+    /** Key of the flag to operate on */
     flagKey: FeatureFlagKey;
+    /** Data for create/update operations */
     data?: unknown;
+    /** Context for evaluation operations */
     context?: FeatureFlagContext;
+    /** Expected result of the operation */
     expectedResult?: unknown;
 }
+/**
+ * Input for permission test cases.
+ * Tests role-based access control for operations.
+ *
+ * @example
+ * ```typescript
+ * const input: PermissionTestInput = {
+ *   role: 'editor',
+ *   operation: 'update',
+ *   resource: 'feature-flag',
+ *   expected: true
+ * };
+ * ```
+ */
 export interface PermissionTestInput {
+    /** User role to test */
     role: string;
+    /** Operation being performed */
     operation: string;
+    /** Resource being accessed */
     resource: string;
+    /** Expected permission result */
     expected: boolean;
 }
+/**
+ * Input for cache operation test cases.
+ * Tests caching behavior for feature flags.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const input: CacheOperationTestInput<'apiLimit'> = {
+ *   operation: 'refresh',
+ *   flagKey: 'apiLimit',
+ *   expectedBehavior: 'Cache should be updated with new value'
+ * };
+ * ```
+ */
 export interface CacheOperationTestInput<FeatureFlagKey extends string> {
+    /** Cache operation to perform */
     operation: 'set' | 'get' | 'refresh' | 'clear';
+    /** Flag key for operations (optional for 'clear') */
     flagKey?: FeatureFlagKey;
+    /** Description of expected cache behavior */
     expectedBehavior: string;
 }
+/**
+ * Input for rule evaluation test cases.
+ * Tests conditional flag value evaluation based on rules.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const input: RuleEvaluationTestInput<'discount'> = {
+ *   flagKey: 'discount',
+ *   rules: [
+ *     { conditions: { userType: 'premium' }, value: 0.2 },
+ *     { conditions: { userType: 'regular' }, value: 0.1 }
+ *   ],
+ *   context: { userType: 'premium' },
+ *   expectedValue: 0.2
+ * };
+ * ```
+ */
 export interface RuleEvaluationTestInput<FeatureFlagKey extends string> {
+    /** Flag key to evaluate */
     flagKey: FeatureFlagKey;
+    /** Array of rules with conditions and values */
     rules: Array<{
+        /** Conditions that must be met */
         conditions: Record<string, unknown>;
+        /** Value to return if conditions match */
         value: FeatureFlagValue;
     }>;
+    /** Context for rule evaluation */
     context: FeatureFlagContext;
+    /** Expected evaluated value */
     expectedValue: FeatureFlagValue;
 }
+/**
+ * Input for batch operation test cases.
+ * Tests multiple flag operations executed together.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const input: BatchOperationTestInput<AppFeatures> = {
+ *   operations: [
+ *     { type: 'create', flagKey: 'feature1', data: { value: true } },
+ *     { type: 'update', flagKey: 'feature2', data: { isEnabled: false } },
+ *     { type: 'delete', flagKey: 'feature3' }
+ *   ],
+ *   expectedResults: [true, true, true]
+ * };
+ * ```
+ */
 export interface BatchOperationTestInput<FeatureFlagKey extends string> {
+    /** Array of operations to execute in batch */
     operations: Array<{
+        /** Type of operation */
         type: 'create' | 'update' | 'delete';
+        /** Flag key to operate on */
         flagKey: FeatureFlagKey;
+        /** Operation data (for create/update) */
         data?: unknown;
     }>;
+    /** Expected results for each operation */
     expectedResults: unknown[];
 }
+/**
+ * Input for validation test cases.
+ * Tests input validation for various fields.
+ *
+ * @example
+ * ```typescript
+ * const input: ValidationTestInput = {
+ *   input: 'invalid-email',
+ *   field: 'email',
+ *   expectedError: 'Invalid email format',
+ *   isValid: false
+ * };
+ * ```
+ */
 export interface ValidationTestInput {
+    /** Input value to validate */
     input: unknown;
+    /** Field name being validated */
     field: string;
+    /** Expected error message if validation fails */
     expectedError?: string;
+    /** Whether the input should be valid */
     isValid: boolean;
 }
+/**
+ * Input for dynamic module configuration test cases.
+ * Tests module setup with different configurations.
+ *
+ * @example
+ * ```typescript
+ * const input: DynamicModuleTestInput = {
+ *   config: { apiKey: 'test-key', environment: 'staging' },
+ *   expectedProviders: ['ConfigService', 'FeatureFlagService'],
+ *   expectedImports: ['HttpModule'],
+ *   expectedExports: ['FeatureFlagService']
+ * };
+ * ```
+ */
 export interface DynamicModuleTestInput {
+    /** Module configuration object */
     config: Record<string, unknown>;
+    /** Expected providers to be registered */
     expectedProviders?: string[];
+    /** Expected modules to be imported */
     expectedImports?: string[];
+    /** Expected services to be exported */
     expectedExports?: string[];
 }
+/**
+ * Input for async module configuration test cases.
+ * Tests asynchronous module setup with factory functions.
+ *
+ * @example
+ * ```typescript
+ * const input: AsyncModuleConfigTestInput = {
+ *   imports: ['ConfigModule'],
+ *   inject: ['ConfigService'],
+ *   useFactory: (config) => ({ apiKey: config.get('API_KEY') }),
+ *   expectedImports: ['ConfigModule', 'HttpModule'],
+ *   expectedProviders: ['FeatureFlagService']
+ * };
+ * ```
+ */
 export interface AsyncModuleConfigTestInput {
+    /** Modules to import */
     imports?: string[];
+    /** Services to inject into factory */
     inject?: string[];
+    /** Factory function for configuration */
     useFactory?: (...args: unknown[]) => Record<string, unknown>;
+    /** Expected modules in result */
     expectedImports?: string[];
+    /** Expected providers in result */
     expectedProviders?: string[];
 }
+/**
+ * Input for repository operation test cases.
+ * Tests data persistence operations for feature flags.
+ *
+ * @example
+ * ```typescript
+ * const input: RepositoryOperationTestInput = {
+ *   operation: 'create',
+ *   data: { key: 'newFeature', value: true },
+ *   expectedResult: { id: 1, key: 'newFeature', value: true },
+ *   shouldThrow: false
+ * };
+ * ```
+ */
 export interface RepositoryOperationTestInput {
+    /** Repository operation to test */
     operation: 'create' | 'update' | 'delete' | 'find';
+    /** Data for the operation */
     data?: unknown;
+    /** Expected operation result */
     expectedResult?: unknown;
+    /** Whether operation should throw an error */
     shouldThrow?: boolean;
 }

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

@@ -411,3 +411,164 @@ export interface CreateTableDrivenTestOptions<TInput, TExpected> {
         expected?: TExpected;
     }) => void | Promise<void>;
 }
+/**
+ * Statistics collected for operation performance tracking.
+ * Provides detailed metrics about operation execution.
+ *
+ * @example
+ * ```typescript
+ * const stats: OperationStats = {
+ *   count: 1000,
+ *   totalDuration: 45000,
+ *   avgDuration: 45,
+ *   minDuration: 10,
+ *   maxDuration: 250,
+ *   errorCount: 3,
+ *   errors: [new Error('Timeout'), new Error('Connection failed')]
+ * };
+ *
+ * console.log(`Average operation time: ${stats.avgDuration}ms`);
+ * console.log(`Error rate: ${(stats.errorCount / stats.count * 100).toFixed(2)}%`);
+ * ```
+ *
+ * @public
+ */
+export interface OperationStats {
+    /** Total number of operations executed */
+    count: number;
+    /** Total duration of all operations in milliseconds */
+    totalDuration: number;
+    /** Average duration per operation in milliseconds */
+    avgDuration: number;
+    /** Minimum operation duration in milliseconds */
+    minDuration: number;
+    /** Maximum operation duration in milliseconds */
+    maxDuration: number;
+    /** Number of operations that resulted in errors */
+    errorCount: number;
+    /** Array of errors encountered during operations */
+    errors: Error[];
+}
+/**
+ * Interface for tracking and measuring operation performance.
+ * Collects timing and error statistics for named operations.
+ *
+ * @example
+ * ```typescript
+ * const tracker: OperationTracker = createOperationTracker();
+ *
+ * // Track an operation
+ * const result = await tracker.track('createUser', async () => {
+ *   return await userService.create({ name: 'John' });
+ * });
+ *
+ * // Get statistics
+ * const stats = tracker.getStats();
+ * console.log(stats.createUser.avgDuration);
+ *
+ * // Reset tracking data
+ * tracker.reset();
+ * ```
+ *
+ * @public
+ */
+export interface OperationTracker {
+    /** Track execution of a named operation */
+    track: <T>(operationName: string, operation: () => Promise<T>) => Promise<T>;
+    /** Get statistics for all tracked operations */
+    getStats: () => Record<string, OperationStats>;
+    /** Reset all tracking data */
+    reset: () => void;
+}
+/**
+ * Test operation for stress testing
+ *
+ * @public
+ */
+export interface TestOperation {
+    name: string;
+    operation: () => unknown | Promise<unknown>;
+    weight?: number;
+}
+/**
+ * Context information for worker threads in stress testing.
+ * Tracks the state and configuration for individual worker processes.
+ *
+ * @template TestOperation - Type of test operations being executed
+ *
+ * @example
+ * ```typescript
+ * const context: WorkerContext<TestOperation> = {
+ *   workerId: 1,
+ *   operationsPerWorker: 1000,
+ *   operations: [createOp, updateOp, deleteOp],
+ *   totalWeight: 10,
+ *   operationCounts: { create: 400, update: 400, delete: 200 },
+ *   errors: [],
+ *   delayBetweenOps: 50
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface WorkerContext<TestOperation> {
+    /** Unique identifier for this worker thread */
+    workerId: number;
+    /** Number of operations this worker should execute */
+    operationsPerWorker: number;
+    /** Available operations to execute */
+    operations: TestOperation[];
+    /** Total weight sum for weighted random selection */
+    totalWeight: number;
+    /** Tracking counts for each operation type */
+    operationCounts: Record<string, number>;
+    /** Errors encountered during execution */
+    errors: Array<{
+        operation: string;
+        error: Error;
+    }>;
+    /** Delay in milliseconds between operations */
+    delayBetweenOps: number;
+}
+/**
+ * Resolved configuration for worker-based stress testing.
+ * Contains the final computed values after applying defaults.
+ *
+ * @example
+ * ```typescript
+ * const config: ResolvedWorkerConfig = {
+ *   workerCount: 4,
+ *   operationsPerWorker: 1000,
+ *   operations: [
+ *     { name: 'create', operation: createUser, weight: 2 },
+ *     { name: 'read', operation: readUser, weight: 5 },
+ *     { name: 'update', operation: updateUser, weight: 2 },
+ *     { name: 'delete', operation: deleteUser, weight: 1 }
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface ResolvedWorkerConfig {
+    /** Number of worker threads to spawn */
+    workerCount: number;
+    /** Operations each worker should perform */
+    operationsPerWorker: number;
+    /** Test operations to be distributed among workers */
+    operations: TestOperation[];
+}
+/**
+ * Stress test configuration
+ *
+ * @public
+ */
+export interface StressTestConfig {
+    workerCount?: number;
+    operationsPerWorker?: number;
+    delayBetweenOps?: number;
+    operations?: TestOperation[];
+    operationCount?: number;
+    concurrency?: number;
+    operationMix?: Record<string, number>;
+}

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

@@ -101,14 +101,62 @@ export interface WrapperComponent {
 export interface ChildrenProps {
     children: React.ReactNode;
 }
+/**
+ * Options for configuring test wrapper components.
+ * Allows specifying providers and their props for test setup.
+ *
+ * @example
+ * ```typescript
+ * const options: WrapperOptions = {
+ *   providers: [ThemeProvider, AuthProvider],
+ *   providerProps: {
+ *     theme: darkTheme,
+ *     user: mockUser
+ *   }
+ * };
+ * ```
+ */
 export interface WrapperOptions {
+    /** Array of provider components to wrap tests with */
     providers?: Array<React.ComponentType<{
         children: React.ReactNode;
     }>>;
+    /** Props to pass to the providers */
     providerProps?: Record<string, unknown>;
 }
+/**
+ * Extended render options combining RTL options with wrapper configuration.
+ * Provides a unified interface for rendering components with providers.
+ *
+ * @example
+ * ```typescript
+ * const options: GenericRenderOptions = {
+ *   providers: [QueryClientProvider],
+ *   providerProps: { client: queryClient },
+ *   container: document.body
+ * };
+ *
+ * const { getByText } = render(<MyComponent />, options);
+ * ```
+ */
 export interface GenericRenderOptions extends Omit<RenderOptions, 'wrapper'>, WrapperOptions {
 }
+/**
+ * Extended render hook options combining RTL hook options with wrapper configuration.
+ * Provides a unified interface for rendering hooks with providers.
+ *
+ * @template TProps - Type of props passed to the hook
+ *
+ * @example
+ * ```typescript
+ * const options: GenericRenderHookOptions<UseCounterProps> = {
+ *   providers: [CounterProvider],
+ *   initialProps: { initialValue: 10 }
+ * };
+ *
+ * const { result } = renderHook(() => useCounter(props), options);
+ * ```
+ */
 export interface GenericRenderHookOptions<TProps> extends Omit<RenderHookOptions<TProps>, 'wrapper'>, WrapperOptions {
 }
 /**
@@ -139,8 +187,25 @@ export interface ErrorBoundaryState {
 export type RenderWithRouterResult = TestingLibraryReact.RenderResult & {
     router: MockNextRouter;
 };
+/**
+ * Props for error boundary components in testing.
+ * Catches errors in child components during rendering.
+ *
+ * @example
+ * ```typescript
+ * const props: ErrorBoundaryProps = {
+ *   children: <ComponentThatMightThrow />,
+ *   onError: (error, errorInfo) => {
+ *     console.error('Component error:', error);
+ *     console.log('Error stack:', errorInfo.componentStack);
+ *   }
+ * };
+ * ```
+ */
 export interface ErrorBoundaryProps {
+    /** Child components to wrap */
     children: React.ReactNode;
+    /** Callback when error is caught */
     onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
 }
 /**
@@ -173,72 +238,284 @@ export interface MockProviderContextValue<T> {
     setValue: (value: T) => void;
     reset: () => void;
 }
+/**
+ * Props for mock provider components.
+ * Allows setting initial values for testing contexts.
+ *
+ * @template T - Type of the provided value
+ *
+ * @example
+ * ```typescript
+ * const props: MockProviderProps<User> = {
+ *   children: <UserProfile />,
+ *   initialValue: { id: 1, name: 'Test User' }
+ * };
+ * ```
+ */
 export interface MockProviderProps<T> {
+    /** Child components to provide context to */
     children: React.ReactNode;
+    /** Initial value for the mock context */
     initialValue?: T;
 }
+/**
+ * Return type for createMockProvider function.
+ * Provides components and hooks for testing with mock contexts.
+ *
+ * @template T - Type of the provided value
+ *
+ * @example
+ * ```typescript
+ * const mockAuth: MockProviderReturn<AuthState> = createMockProvider();
+ *
+ * // Use in tests
+ * render(
+ *   <mockAuth.Provider initialValue={testAuth}>
+ *     <AuthenticatedComponent />
+ *   </mockAuth.Provider>
+ * );
+ *
+ * // Access context in tests
+ * const { value, setValue } = mockAuth.useValue();
+ * ```
+ */
 export interface MockProviderReturn<T> {
+    /** Mock provider component */
     Provider: React.FC<MockProviderProps<T>>;
+    /** Hook to access mock context value */
     useValue: () => MockProviderContextValue<T>;
+    /** The React context instance */
     Context: React.Context<MockProviderContextValue<T> | null>;
 }
+/**
+ * Props for tracked provider components.
+ * Monitors render counts and value changes for performance testing.
+ *
+ * @template T - Type of the provided value
+ *
+ * @example
+ * ```typescript
+ * const props: TrackedProviderProps<Config> = {
+ *   children: <ConfigConsumer />,
+ *   value: { theme: 'dark', locale: 'en' },
+ *   onRender: (count) => console.log(`Rendered ${count} times`)
+ * };
+ * ```
+ */
 export interface TrackedProviderProps<T> {
+    /** Child components to track */
     children: React.ReactNode;
+    /** Value to provide and track */
     value: T;
+    /** Callback on each render with count */
     onRender?: (count: number) => void;
 }
+/**
+ * Return type for createTrackedProvider function.
+ * Provides tracking capabilities for renders and updates.
+ *
+ * @template T - Type of the tracked value
+ *
+ * @example
+ * ```typescript
+ * const tracker: TrackedProviderReturn<State> = createTrackedProvider();
+ *
+ * // Check render performance
+ * expect(tracker.getRenderCount()).toBeLessThan(3);
+ *
+ * // Verify update history
+ * const history = tracker.getUpdateHistory();
+ * expect(history[0].value).toEqual(initialState);
+ * ```
+ */
 export interface TrackedProviderReturn<T> {
+    /** Tracked provider component */
     Provider: React.FC<TrackedProviderProps<T>>;
+    /** Get total render count */
     getRenderCount: () => number;
+    /** Get history of value updates */
     getUpdateHistory: () => Array<UpdateHistoryEntry<T>>;
+    /** Reset tracking data */
     reset: () => void;
 }
+/**
+ * Context value for async data providers.
+ * Manages loading states and error handling for async operations.
+ *
+ * @template T - Type of the async data
+ *
+ * @example
+ * ```typescript
+ * const context: AsyncProviderContextValue<User[]> = {
+ *   data: undefined,
+ *   loading: true,
+ *   error: null,
+ *   refetch: async () => {
+ *     // Refetch user data
+ *   }
+ * };
+ * ```
+ */
 export interface AsyncProviderContextValue<T> {
+    /** The loaded data (undefined while loading) */
     data: T | undefined;
+    /** Loading state indicator */
     loading: boolean;
+    /** Error from failed async operation */
     error: Error | null;
+    /** Function to refetch the data */
     refetch: () => Promise<void>;
 }
+/**
+ * Props for async provider components.
+ * Simple wrapper for components that need async data.
+ *
+ * @example
+ * ```typescript
+ * const props: AsyncProviderProps = {
+ *   children: <DataConsumer />
+ * };
+ * ```
+ */
 export interface AsyncProviderProps {
+    /** Child components that will consume async data */
     children: React.ReactNode;
 }
+/**
+ * Return type for createAsyncProvider function.
+ * Provides components and hooks for async data management.
+ *
+ * @template T - Type of the async data
+ *
+ * @example
+ * ```typescript
+ * const asyncData: AsyncProviderReturn<Products> = createAsyncProvider();
+ *
+ * // Use in component
+ * const { data, loading, error } = asyncData.useAsyncValue();
+ * if (loading) return <Spinner />;
+ * if (error) return <ErrorMessage error={error} />;
+ * return <ProductList products={data} />;
+ * ```
+ */
 export interface AsyncProviderReturn<T> {
+    /** Async provider component */
     Provider: React.FC<AsyncProviderProps>;
+    /** Hook to access async data state */
     useAsyncValue: () => AsyncProviderContextValue<T>;
+    /** The React context instance */
     Context: React.Context<AsyncProviderContextValue<T> | null>;
 }
+/**
+ * Props for Suspense wrapper components.
+ * Wraps components with React Suspense for async rendering.
+ *
+ * @example
+ * ```typescript
+ * const props: SuspenseWrapperProps = {
+ *   children: <LazyComponent />,
+ *   fallback: <LoadingSpinner />
+ * };
+ * ```
+ */
 export interface SuspenseWrapperProps {
+    /** Components that might suspend */
     children: React.ReactNode;
+    /** Fallback UI while suspended */
     fallback?: React.ReactNode;
 }
+/**
+ * Options for creating a comprehensive test wrapper.
+ * Combines multiple common testing wrappers in one.
+ *
+ * @example
+ * ```typescript
+ * const options: AllProvidersOptions = {
+ *   includeErrorBoundary: true,
+ *   includeSuspense: true,
+ *   includeStrictMode: process.env.NODE_ENV === 'test',
+ *   errorBoundaryProps: {
+ *     onError: (error) => console.error('Test error:', error)
+ *   },
+ *   suspenseProps: {
+ *     fallback: <div>Loading...</div>
+ *   },
+ *   additionalProviders: [ThemeProvider, I18nProvider]
+ * };
+ * ```
+ */
 export interface AllProvidersOptions {
+    /** Include error boundary wrapper */
     includeErrorBoundary?: boolean;
+    /** Include Suspense wrapper */
     includeSuspense?: boolean;
+    /** Include React StrictMode */
     includeStrictMode?: boolean;
+    /** Props for error boundary */
     errorBoundaryProps?: {
         onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
     };
+    /** Props for Suspense wrapper */
     suspenseProps?: {
         fallback?: React.ReactNode;
     };
+    /** Additional provider components */
     additionalProviders?: Array<React.ComponentType<{
         children: React.ReactNode;
     }>>;
 }
+/**
+ * Generic context provider interface.
+ * Represents the structure of React context providers.
+ *
+ * @template T - Type of the context value
+ *
+ * @example
+ * ```typescript
+ * const AuthContext: ContextProvider<AuthState> = {
+ *   Provider: AuthProvider,
+ *   Consumer: AuthConsumer,
+ *   displayName: 'AuthContext'
+ * };
+ * ```
+ */
 export interface ContextProvider<T = unknown> {
+    /** Provider component that supplies the value */
     Provider: React.ComponentType<{
         value: T;
         children: React.ReactNode;
     }>;
+    /** Consumer component for render prop pattern */
     Consumer: React.ComponentType<{
         children: (value: T) => React.ReactNode;
     }>;
+    /** Optional display name for debugging */
     displayName?: string;
 }
+/**
+ * Configuration options for providers in a stack.
+ * Defines how providers are organized and their dependencies.
+ *
+ * @template T - Type of the provider's value
+ *
+ * @example
+ * ```typescript
+ * const config: ProviderConfigOptions<ThemeConfig> = {
+ *   provider: ThemeContext,
+ *   value: { mode: 'dark', colors: darkColors },
+ *   name: 'theme',
+ *   dependencies: ['i18n'] // Depends on i18n provider
+ * };
+ * ```
+ */
 export interface ProviderConfigOptions<T = unknown> {
+    /** The context provider to configure */
     provider: ContextProvider<T>;
+    /** Value to provide through the context */
     value: T;
+    /** Optional name for identification */
     name?: string;
+    /** Names of providers this depends on */
     dependencies?: string[];
 }
 /**
@@ -296,78 +573,394 @@ export interface WrapperComposition {
     clear: () => WrapperComposition;
     clone: () => WrapperComposition;
 }
+/**
+ * Options for creating mock providers.
+ * Configures initial state and change handlers.
+ *
+ * @template T - Type of the mock value
+ *
+ * @example
+ * ```typescript
+ * const options: MockProviderOptions<User> = {
+ *   defaultValue: { id: 1, name: 'John' },
+ *   onValueChange: (newUser) => {
+ *     console.log('User changed:', newUser);
+ *   }
+ * };
+ * ```
+ */
 export interface MockProviderOptions<T> {
+    /** Default value for the mock provider */
     defaultValue: T;
+    /** Callback when value changes */
     onValueChange?: (newValue: T) => void;
 }
+/**
+ * Options for tracked providers.
+ * Configures render tracking and logging.
+ *
+ * @example
+ * ```typescript
+ * const options: TrackedProviderOptions = {
+ *   name: 'UserProvider',
+ *   logRenders: true // Log each render to console
+ * };
+ * ```
+ */
 export interface TrackedProviderOptions {
+    /** Name for identification in logs */
     name: string;
+    /** Whether to log renders to console */
     logRenders?: boolean;
 }
+/**
+ * Options for async data providers.
+ * Configures data loading and error handling.
+ *
+ * @template T - Type of the async data
+ *
+ * @example
+ * ```typescript
+ * const options: AsyncProviderOptions<Products[]> = {
+ *   loadData: () => fetchProducts(),
+ *   fallback: [],
+ *   onError: (error) => console.error('Failed to load:', error)
+ * };
+ * ```
+ */
 export interface AsyncProviderOptions<T> {
+    /** Function to load async data */
     loadData: () => Promise<T>;
+    /** Fallback value while loading */
     fallback?: T;
+    /** Error handler callback */
     onError?: (error: Error) => void;
 }
+/**
+ * Options for subscribable providers.
+ * Configures providers that support subscription patterns.
+ *
+ * @template T - Type of the subscribable value
+ *
+ * @example
+ * ```typescript
+ * const options: SubscribableProviderOptions<Settings> = {
+ *   initialValue: { theme: 'light', lang: 'en' },
+ *   name: 'SettingsProvider'
+ * };
+ * ```
+ */
 export interface SubscribableProviderOptions<T> {
+    /** Initial value for subscribers */
     initialValue: T;
+    /** Provider name for debugging */
     name: string;
 }
+/**
+ * Options for time-travel providers.
+ * Configures state history and undo/redo functionality.
+ *
+ * @template T - Type of the state to track
+ *
+ * @example
+ * ```typescript
+ * const options: TimeTravelProviderOptions<EditorState> = {
+ *   initialState: { content: '', cursor: 0 },
+ *   maxHistory: 50, // Keep last 50 states
+ *   name: 'EditorHistory'
+ * };
+ * ```
+ */
 export interface TimeTravelProviderOptions<T> {
+    /** Initial state value */
     initialState: T;
+    /** Maximum history entries to keep */
     maxHistory?: number;
+    /** Provider name for debugging */
     name: string;
 }
+/**
+ * Options for mock API providers.
+ * Configures endpoints and response behaviors.
+ *
+ * @example
+ * ```typescript
+ * const options: MockApiProviderOptions = {
+ *   endpoints: {
+ *     getUser: () => ({ id: 1, name: 'John' }),
+ *     getPosts: async () => [
+ *       { id: 1, title: 'First Post' }
+ *     ]
+ *   },
+ *   delay: 100, // Simulate network delay
+ *   name: 'MockAPI'
+ * };
+ * ```
+ */
 export interface MockApiProviderOptions {
+    /** Mock endpoint implementations */
     endpoints: Record<string, () => Promise<unknown> | unknown>;
+    /** Artificial delay in ms */
     delay?: number;
+    /** Provider name for debugging */
     name: string;
 }
+/**
+ * Entry in the update history for tracked providers.
+ * Records state changes over time.
+ *
+ * @template T - Type of the tracked state
+ *
+ * @example
+ * ```typescript
+ * const entry: UpdateHistoryEntry<UserProfile> = {
+ *   timestamp: Date.now(),
+ *   updates: { name: 'Jane', email: 'jane@example.com' }
+ * };
+ * ```
+ */
 export interface UpdateHistoryEntry<T> {
+    /** When the update occurred */
     timestamp: number;
+    /** Partial state updates applied */
     updates: Partial<T>;
 }
+/**
+ * Item in a provider chain.
+ * Represents a single provider with its props.
+ *
+ * @example
+ * ```typescript
+ * const chainItem: ProviderChainItem = {
+ *   provider: ThemeProvider,
+ *   props: { theme: darkTheme }
+ * };
+ * ```
+ */
 export interface ProviderChainItem {
+    /** Provider component */
     provider: React.ComponentType<{
         children: React.ReactNode;
     }>;
+    /** Props to pass to provider */
     props?: Record<string, unknown>;
 }
+/**
+ * Context value for subscribable providers.
+ * Implements pub/sub pattern for state updates.
+ *
+ * @template T - Type of the subscribable value
+ *
+ * @example
+ * ```typescript
+ * const context: SubscribableContextValue<Config> = {
+ *   value: currentConfig,
+ *   subscribe: (callback) => {
+ *     subscribers.add(callback);
+ *     return () => subscribers.delete(callback);
+ *   },
+ *   update: (newConfig) => {
+ *     currentConfig = newConfig;
+ *     subscribers.forEach(cb => cb(newConfig));
+ *   }
+ * };
+ * ```
+ */
 export interface SubscribableContextValue<T> {
+    /** Current value */
     value: T;
+    /** Subscribe to value changes */
     subscribe: (callback: (value: T) => void) => () => void;
+    /** Update the value and notify subscribers */
     update: (value: T) => void;
 }
+/**
+ * Return type for createSubscribableProvider.
+ * Provides subscription-based state management.
+ *
+ * @template T - Type of the subscribable value
+ *
+ * @example
+ * ```typescript
+ * const store: SubscribableProviderReturn<AppState> = createSubscribableProvider();
+ *
+ * // Check subscriber count
+ * expect(store.getSubscriberCount()).toBe(3);
+ *
+ * // Clear all subscriptions
+ * store.clearSubscribers();
+ * ```
+ */
 export interface SubscribableProviderReturn<T> {
+    /** Subscribable provider component */
     Provider: React.FC<{
         children: React.ReactNode;
     }>;
+    /** Hook to access subscribable context */
     useSubscribable: () => SubscribableContextValue<T>;
+    /** Get current subscriber count */
     getSubscriberCount: () => number;
+    /** Clear all active subscriptions */
     clearSubscribers: () => void;
 }
+/**
+ * Callback function type for subscribing to value changes.
+ * Invoked whenever the subscribed value is updated.
+ *
+ * @template T - Type of the value being subscribed to
+ *
+ * @param value - The new value after an update
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to user state changes
+ * const userSubscriber: Subscriber<User> = (user) => {
+ *   console.log('User updated:', user);
+ *   updateUI(user);
+ * };
+ *
+ * // Subscribe to theme changes
+ * const themeSubscriber: Subscriber<Theme> = (theme) => {
+ *   document.body.className = theme.mode;
+ * };
+ * ```
+ */
 export type Subscriber<T> = (value: T) => void;
+/**
+ * Context value for time-travel providers.
+ * Provides undo/redo functionality with state history management.
+ *
+ * @template T - Type of the state being tracked
+ *
+ * @example
+ * ```typescript
+ * const context: TimeTravelContextValue<EditorState> = {
+ *   state: { content: 'Hello', cursor: 5 },
+ *   canUndo: true,
+ *   canRedo: false,
+ *   undo: () => {
+ *     // Restore previous state
+ *   },
+ *   redo: () => {
+ *     // Restore next state
+ *   },
+ *   update: (newState) => {
+ *     // Add to history and update current
+ *   },
+ *   reset: () => {
+ *     // Clear all history
+ *   },
+ *   getHistory: () => [
+ *     { content: '', cursor: 0 },
+ *     { content: 'Hello', cursor: 5 }
+ *   ]
+ * };
+ * ```
+ */
 export interface TimeTravelContextValue<T> {
+    /** Current state value */
     state: T;
+    /** Whether undo operation is available */
     canUndo: boolean;
+    /** Whether redo operation is available */
     canRedo: boolean;
+    /** Restore the previous state from history */
     undo: () => void;
+    /** Restore the next state from history */
     redo: () => void;
+    /** Update state and add to history */
     update: (newState: T) => void;
+    /** Clear all history and reset to initial state */
     reset: () => void;
+    /** Get the complete state history */
     getHistory: () => T[];
 }
+/**
+ * Return type for createTimeTravelProvider.
+ * Provides components and hooks for time-travel state management.
+ *
+ * @template T - Type of the state with history tracking
+ *
+ * @example
+ * ```typescript
+ * const editor: TimeTravelProviderReturn<EditorState> = createTimeTravelProvider();
+ *
+ * // Use in component
+ * function Editor() {
+ *   const { state, canUndo, undo, update } = editor.useTimeTravel();
+ *
+ *   return (
+ *     <div>
+ *       <button disabled={!canUndo} onClick={undo}>Undo</button>
+ *       <textarea
+ *         value={state.content}
+ *         onChange={(e) => update({ ...state, content: e.target.value })}
+ *       />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Wrap with provider
+ * <editor.Provider>
+ *   <Editor />
+ * </editor.Provider>
+ * ```
+ */
 export interface TimeTravelProviderReturn<T> {
+    /** Time-travel provider component */
     Provider: React.FC<{
         children: React.ReactNode;
     }>;
+    /** Hook to access time-travel functionality */
     useTimeTravel: () => TimeTravelContextValue<T>;
 }
+/**
+ * Return type for createMockApiProvider.
+ * Provides mock API endpoints for testing API interactions.
+ *
+ * @template T - Type of the API interface as a record of endpoint methods
+ *
+ * @example
+ * ```typescript
+ * interface UserAPI {
+ *   getUser: (id: number) => Promise<User>;
+ *   createUser: (data: CreateUserData) => Promise<User>;
+ *   updateUser: (id: number, data: UpdateUserData) => Promise<User>;
+ *   deleteUser: (id: number) => Promise<void>;
+ * }
+ *
+ * const api: MockApiProviderReturn<UserAPI> = createMockApiProvider();
+ *
+ * // Configure mock responses
+ * api.mockApi.getUser = vi.fn().mockResolvedValue({ id: 1, name: 'John' });
+ *
+ * // Use in component
+ * function UserProfile() {
+ *   const { getUser } = api.useApi();
+ *   const [user, setUser] = useState<User>();
+ *
+ *   useEffect(() => {
+ *     getUser(1).then(setUser);
+ *   }, []);
+ *
+ *   return <div>{user?.name}</div>;
+ * }
+ *
+ * // Reset mocks between tests
+ * afterEach(() => {
+ *   api.resetMocks();
+ * });
+ * ```
+ */
 export interface MockApiProviderReturn<T extends Record<string, unknown>> {
+    /** Mock API provider component */
     Provider: React.FC<{
         children: React.ReactNode;
     }>;
+    /** Hook to access mock API methods */
     useApi: () => T;
+    /** Direct access to mock API implementations for configuration */
     mockApi: T;
+    /** Reset all mock implementations to their default state */
     resetMocks: () => void;
 }

package/dist/testing/features/feature-flags/types.d.ts

@@ -1291,33 +1291,81 @@ export interface FeatureFlagFileData<FeatureFlagKey extends string> {
  *
  * @public
  */
-export interface FeatureFlagFileTestContext {
+export interface FileTestContext {
     testDir: string;
     jsonFile: string;
     yamlFile: string;
     cleanup: () => Promise<void>;
 }
 /**
- * Provider test operation for stress testing
+ * Provider interface that supports dynamic rule addition.
+ * Used for testing providers that allow runtime rule configuration.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const provider: ProviderWithRules<MyFlags> = createTestProvider();
+ *
+ * // Add a targeting rule
+ * provider.addRule({
+ *   id: 'premium-users',
+ *   flagKey: 'premium-feature',
+ *   name: 'Target premium users',
+ *   conditions: [{ field: 'userRole', operator: 'equals', value: 'premium' }],
+ *   value: true,
+ *   priority: 1,
+ *   isEnabled: true
+ * });
+ *
+ * // Evaluate flag with rules
+ * const evaluation = await provider.getFlag('premium-feature');
+ * ```
  *
  * @public
  */
-export interface ProviderTestOperation {
-    name: string;
-    operation: () => unknown | Promise<unknown>;
-    weight?: number;
+export interface ProviderWithRules<FeatureFlagKey extends string> {
+    /** Add a new rule to the provider */
+    addRule: (rule: FeatureFlagRule<FeatureFlagKey>) => void;
+    /** Evaluate a flag considering all rules */
+    getFlag: (key: FeatureFlagKey) => Promise<FeatureFlagEvaluation<FeatureFlagKey>>;
 }
 /**
- * Provider stress test configuration
+ * Test scenario interface for file-based feature flag providers.
+ * Extends FileTestContext to provide file-specific testing utilities.
+ *
+ * @template FeatureFlagKey - Type of feature flag keys
+ *
+ * @example
+ * ```typescript
+ * const scenario: FileProviderTestScenario<'feature1' | 'feature2'> = {
+ *   testDir: '/tmp/test-flags',
+ *   jsonFile: '/tmp/test-flags/flags.json',
+ *   yamlFile: '/tmp/test-flags/flags.yaml',
+ *   filePath: '/tmp/test-flags/flags.json',
+ *   format: 'json',
+ *   cleanup: async () => {
+ *     await fs.rmdir(testDir, { recursive: true });
+ *   },
+ *   updateFile: async (updates) => {
+ *     const current = await readFile(filePath);
+ *     await writeFile(filePath, { ...current, ...updates });
+ *   },
+ *   waitForFileChange: async (ms = 100) => {
+ *     await new Promise(resolve => setTimeout(resolve, ms));
+ *   }
+ * };
+ * ```
  *
  * @public
  */
-export interface ProviderStressTestConfig {
-    workerCount?: number;
-    operationsPerWorker?: number;
-    delayBetweenOps?: number;
-    operations?: ProviderTestOperation[];
-    operationCount?: number;
-    concurrency?: number;
-    operationMix?: Record<string, number>;
+export interface FileProviderTestScenario<FeatureFlagKey extends string> extends FileTestContext {
+    /** Path to the active test file */
+    filePath: string;
+    /** Format of the feature flag file */
+    format: 'json' | 'yaml';
+    /** Update flag values in the test file */
+    updateFile: (updates: Record<FeatureFlagKey, FeatureFlagValue>) => Promise<void>;
+    /** Wait for file system changes to propagate */
+    waitForFileChange: (ms?: number) => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",