@plyaz/types 1.3.2 → 1.3.4

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

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

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

@@ -0,0 +1,373 @@
+/**
+ * @fileoverview Wrapper Component Types
+ *
+ * Comprehensive type definitions for React wrapper components used in testing.
+ * Provides type safety for provider wrappers, error boundaries, mock providers,
+ * and testing compositions. Essential for creating reusable test environments.
+ *
+ * This module includes types for:
+ * - Wrapper component interfaces and options
+ * - React provider testing utilities
+ * - Error boundary testing components
+ * - Mock and tracked provider implementations
+ * - Async data provider patterns
+ * - Context composition and stacking
+ * - Time travel and subscribable providers
+ * - API mocking provider utilities
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   WrapperComponent,
+ *   MockProviderReturn,
+ *   ProviderStack,
+ *   TimeTravelProviderReturn
+ * } from './types';
+ *
+ * // Create wrapper component
+ * const TestWrapper: WrapperComponent = ({ children }) => (
+ *   <ThemeProvider theme={testTheme}>
+ *     <AuthProvider user={mockUser}>
+ *       {children}
+ *     </AuthProvider>
+ *   </ThemeProvider>
+ * );
+ *
+ * // Mock provider for testing
+ * const { Provider, useValue }: MockProviderReturn<User> = createMockProvider({
+ *   defaultValue: mockUser
+ * });
+ *
+ * // Provider stack composition
+ * const stack: ProviderStack = createProviderStack()
+ *   .add({ provider: ThemeProvider, value: theme })
+ *   .add({ provider: AuthProvider, value: user });
+ * ```
+ *
+ * @module WrapperTypes
+ * @since 1.0.0
+ */
+import type * as React from 'react';
+import type { RenderOptions, RenderHookOptions, MockNextRouter } from '..';
+import type * as TestingLibraryReact from '@testing-library/react';
+/**
+ * React wrapper component interface for test utilities
+ *
+ * Defines the contract for wrapper components used in testing environments.
+ * Wrapper components typically provide context, state, or other dependencies
+ * needed by components under test.
+ *
+ * @example
+ * ```typescript
+ * const TestWrapper: WrapperComponent = ({ children }) => (
+ *   <QueryClient client={testQueryClient}>
+ *     <ThemeProvider theme={lightTheme}>
+ *       <AuthProvider user={mockUser}>
+ *         {children}
+ *       </AuthProvider>
+ *     </ThemeProvider>
+ *   </QueryClient>
+ * );
+ *
+ * TestWrapper.displayName = 'TestWrapper';
+ *
+ * // Use in tests
+ * render(<MyComponent />, { wrapper: TestWrapper });
+ * ```
+ */
+export interface WrapperComponent {
+    (props: {
+        children: React.ReactNode;
+    }): React.ReactNode;
+    displayName?: string;
+}
+/**
+ * Common props interface for components that accept children
+ *
+ * Standard interface for React components that render child elements.
+ * Used throughout the testing library for consistent props typing.
+ *
+ * @example
+ * ```typescript
+ * const Container: React.FC<ChildrenProps> = ({ children }) => (
+ *   <div className="test-container">{children}</div>
+ * );
+ *
+ * function ProviderWrapper({ children }: ChildrenProps) {
+ *   return <TestProvider>{children}</TestProvider>;
+ * }
+ * ```
+ */
+export interface ChildrenProps {
+    children: React.ReactNode;
+}
+export interface WrapperOptions {
+    providers?: Array<React.ComponentType<{
+        children: React.ReactNode;
+    }>>;
+    providerProps?: Record<string, unknown>;
+}
+export interface GenericRenderOptions extends Omit<RenderOptions, 'wrapper'>, WrapperOptions {
+}
+export interface GenericRenderHookOptions<TProps> extends Omit<RenderHookOptions<TProps>, 'wrapper'>, WrapperOptions {
+}
+/**
+ * Type definition for the enhanced render function
+ *
+ * @param ui - React element to render
+ * @param options - Render options including providers
+ * @returns Render result from testing library
+ */
+export type RenderFunction = (ui: React.ReactElement, options?: GenericRenderOptions) => TestingLibraryReact.RenderResult;
+/**
+ * Type definition for the enhanced renderHook function
+ *
+ * @typeParam TResult - Type of the hook's return value
+ * @typeParam TProps - Type of the hook's props
+ * @param hook - Hook function to test
+ * @param options - Render hook options including providers
+ * @returns Render hook result from testing library
+ */
+export type RenderHookFunction = <TResult, TProps>(hook: (props: TProps) => TResult, options?: GenericRenderHookOptions<TProps>) => TestingLibraryReact.RenderHookResult<TResult, TProps>;
+export interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Type definition for render result with Next.js router
+ */
+export type RenderWithRouterResult = TestingLibraryReact.RenderResult & {
+    router: MockNextRouter;
+};
+export interface ErrorBoundaryProps {
+    children: React.ReactNode;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+/**
+ * Context value interface for mock providers
+ *
+ * Defines the structure of context values provided by mock providers,
+ * including methods for updating and resetting the mock state.
+ *
+ * @typeParam T - Type of the value being provided
+ *
+ * @example
+ * ```typescript
+ * // User context mock
+ * const userContext: MockProviderContextValue<User> = {
+ *   value: { id: 1, name: 'John', email: 'john@example.com' },
+ *   setValue: (newUser) => console.log('User updated:', newUser),
+ *   reset: () => console.log('User context reset')
+ * };
+ *
+ * // Theme context mock
+ * const themeContext: MockProviderContextValue<Theme> = {
+ *   value: lightTheme,
+ *   setValue: (theme) => document.body.className = theme.name,
+ *   reset: () => document.body.className = 'default'
+ * };
+ * ```
+ */
+export interface MockProviderContextValue<T> {
+    value: T;
+    setValue: (value: T) => void;
+    reset: () => void;
+}
+export interface MockProviderProps<T> {
+    children: React.ReactNode;
+    initialValue?: T;
+}
+export interface MockProviderReturn<T> {
+    Provider: React.FC<MockProviderProps<T>>;
+    useValue: () => MockProviderContextValue<T>;
+    Context: React.Context<MockProviderContextValue<T> | null>;
+}
+export interface TrackedProviderProps<T> {
+    children: React.ReactNode;
+    value: T;
+    onRender?: (count: number) => void;
+}
+export interface TrackedProviderReturn<T> {
+    Provider: React.FC<TrackedProviderProps<T>>;
+    getRenderCount: () => number;
+    getUpdateHistory: () => Array<UpdateHistoryEntry<T>>;
+    reset: () => void;
+}
+export interface AsyncProviderContextValue<T> {
+    data: T | undefined;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+export interface AsyncProviderProps {
+    children: React.ReactNode;
+}
+export interface AsyncProviderReturn<T> {
+    Provider: React.FC<AsyncProviderProps>;
+    useAsyncValue: () => AsyncProviderContextValue<T>;
+    Context: React.Context<AsyncProviderContextValue<T> | null>;
+}
+export interface SuspenseWrapperProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}
+export interface AllProvidersOptions {
+    includeErrorBoundary?: boolean;
+    includeSuspense?: boolean;
+    includeStrictMode?: boolean;
+    errorBoundaryProps?: {
+        onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    };
+    suspenseProps?: {
+        fallback?: React.ReactNode;
+    };
+    additionalProviders?: Array<React.ComponentType<{
+        children: React.ReactNode;
+    }>>;
+}
+export interface ContextProvider<T = unknown> {
+    Provider: React.ComponentType<{
+        value: T;
+        children: React.ReactNode;
+    }>;
+    Consumer: React.ComponentType<{
+        children: (value: T) => React.ReactNode;
+    }>;
+    displayName?: string;
+}
+export interface ProviderConfigOptions<T = unknown> {
+    provider: ContextProvider<T>;
+    value: T;
+    name?: string;
+    dependencies?: string[];
+}
+/**
+ * Provider stack interface for composing multiple providers
+ *
+ * Provides a fluent API for building complex provider hierarchies in tests.
+ * Allows adding, removing, and organizing providers in a dependency-aware manner.
+ *
+ * @example
+ * ```typescript
+ * // Build a provider stack
+ * const testStack: ProviderStack = createProviderStack()
+ *   .add({
+ *     provider: QueryClientProvider,
+ *     value: testQueryClient,
+ *     name: 'query'
+ *   })
+ *   .add({
+ *     provider: ThemeProvider,
+ *     value: darkTheme,
+ *     name: 'theme',
+ *     dependencies: ['query']
+ *   })
+ *   .add({
+ *     provider: AuthProvider,
+ *     value: mockUser,
+ *     name: 'auth'
+ *   });
+ *
+ * // Build the wrapper component
+ * const TestWrapper = testStack.build();
+ *
+ * // Use in tests
+ * render(<App />, { wrapper: TestWrapper });
+ *
+ * // Remove a provider
+ * const reducedStack = testStack.remove('auth');
+ *
+ * // Clear all providers
+ * testStack.clear();
+ * ```
+ */
+export interface ProviderStack {
+    providers: ProviderConfigOptions[];
+    add: <T>(config: ProviderConfigOptions<T>) => ProviderStack;
+    remove: (name: string) => ProviderStack;
+    build: () => WrapperComponent;
+    clear: () => ProviderStack;
+}
+export interface WrapperComposition {
+    components: WrapperComponent[];
+    add: (component: WrapperComponent) => WrapperComposition;
+    remove: (displayName: string) => WrapperComposition;
+    build: () => WrapperComponent;
+    clear: () => WrapperComposition;
+    clone: () => WrapperComposition;
+}
+export interface MockProviderOptions<T> {
+    defaultValue: T;
+    onValueChange?: (newValue: T) => void;
+}
+export interface TrackedProviderOptions {
+    name: string;
+    logRenders?: boolean;
+}
+export interface AsyncProviderOptions<T> {
+    loadData: () => Promise<T>;
+    fallback?: T;
+    onError?: (error: Error) => void;
+}
+export interface SubscribableProviderOptions<T> {
+    initialValue: T;
+    name: string;
+}
+export interface TimeTravelProviderOptions<T> {
+    initialState: T;
+    maxHistory?: number;
+    name: string;
+}
+export interface MockApiProviderOptions {
+    endpoints: Record<string, () => Promise<unknown> | unknown>;
+    delay?: number;
+    name: string;
+}
+export interface UpdateHistoryEntry<T> {
+    timestamp: number;
+    updates: Partial<T>;
+}
+export interface ProviderChainItem {
+    provider: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    props?: Record<string, unknown>;
+}
+export interface SubscribableContextValue<T> {
+    value: T;
+    subscribe: (callback: (value: T) => void) => () => void;
+    update: (value: T) => void;
+}
+export interface SubscribableProviderReturn<T> {
+    Provider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    useSubscribable: () => SubscribableContextValue<T>;
+    getSubscriberCount: () => number;
+    clearSubscribers: () => void;
+}
+export type Subscriber<T> = (value: T) => void;
+export interface TimeTravelContextValue<T> {
+    state: T;
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    update: (newState: T) => void;
+    reset: () => void;
+    getHistory: () => T[];
+}
+export interface TimeTravelProviderReturn<T> {
+    Provider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    useTimeTravel: () => TimeTravelContextValue<T>;
+}
+export interface MockApiProviderReturn<T extends Record<string, unknown>> {
+    Provider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    useApi: () => T;
+    mockApi: T;
+    resetMocks: () => void;
+}

package/dist/testing/features/cache/index.d.ts

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

package/dist/testing/features/cache/types.d.ts

@@ -0,0 +1,43 @@
+import type { CacheStrategy } from '../../../features';
+/**
+ * Configuration for cache strategy test suite
+ *
+ * @interface CacheStrategyTestConfig
+ * @property name - Display name for the test suite
+ * @property createStrategy - Factory function to create strategy instance
+ * @property supportsExpiration - Whether strategy supports TTL/expiration (default: true)
+ * @property supportsStats - Whether strategy tracks statistics (default: true)
+ * @property cleanup - Optional cleanup function called after each test
+ *
+ * @example
+ * ```typescript
+ * const memoryConfig: CacheStrategyTestConfig = {
+ *   name: 'MemoryCache',
+ *   createStrategy: () => new MemoryCache(),
+ *   supportsExpiration: true,
+ *   supportsStats: true
+ * };
+ *
+ * const redisConfig: CacheStrategyTestConfig = {
+ *   name: 'RedisCache',
+ *   createStrategy: async () => {
+ *     const redis = new RedisCache(redisClient);
+ *     await redis.connect();
+ *     return redis;
+ *   },
+ *   cleanup: async (strategy) => {
+ *     await strategy.dispose();
+ *     await redisClient.quit();
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface CacheStrategyTestConfig {
+    name: string;
+    createStrategy: () => CacheStrategy | Promise<CacheStrategy>;
+    supportsExpiration?: boolean;
+    supportsStats?: boolean;
+    cleanup?: (strategy: CacheStrategy) => Promise<void>;
+}

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

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