@plyaz/types 1.3.2 → 1.3.3

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

@@ -0,0 +1,701 @@
+/**
+ * Factory Types
+ *
+ * Type definitions for factory utilities.
+ */
+import type * as Vitest from 'vitest';
+/**
+ * Test user interface for user-related testing
+ *
+ * @example
+ * ```typescript
+ * const user: TestUser = {
+ *   id: 'user-123',
+ *   email: 'test@example.com',
+ *   name: 'Test User',
+ *   roles: ['user', 'admin'],
+ *   permissions: ['read', 'write'],
+ *   metadata: { source: 'test' },
+ *   createdAt: new Date(),
+ *   updatedAt: new Date()
+ * };
+ * ```
+ */
+export interface TestUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+    /** User display name */
+    name: string;
+    /** User roles */
+    roles: string[];
+    /** User permissions */
+    permissions: string[];
+    /** Additional user metadata */
+    metadata?: Record<string, unknown>;
+    /** User creation timestamp */
+    createdAt: Date;
+    /** User last update timestamp */
+    updatedAt: Date;
+}
+/**
+ * Test context interface for environment and user context
+ *
+ * @example
+ * ```typescript
+ * const context: TestContext = {
+ *   userId: 'user-123',
+ *   environment: 'test',
+ *   locale: 'en-US',
+ *   timezone: 'UTC',
+ *   userAgent: 'test-agent/1.0',
+ *   ip: '127.0.0.1',
+ *   country: 'US',
+ *   customField: 'custom-value'
+ * };
+ * ```
+ */
+export interface TestContext {
+    /** Current user ID */
+    userId?: string;
+    /** Runtime environment */
+    environment: string;
+    /** User locale */
+    locale?: string;
+    /** User timezone */
+    timezone?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Client IP address */
+    ip?: string;
+    /** Client country */
+    country?: string;
+    /** Client region */
+    region?: string;
+    /** Client city */
+    city?: string;
+    /** Additional context fields */
+    [key: string]: string | undefined;
+}
+/**
+ * Test API response interface for HTTP response testing
+ *
+ * @typeParam T - Type of the response data
+ *
+ * @example
+ * ```typescript
+ * const response: TestApiResponse<User> = {
+ *   data: { id: '123', name: 'John' },
+ *   status: 200,
+ *   statusText: 'OK',
+ *   headers: { 'content-type': 'application/json' },
+ *   timestamp: new Date(),
+ *   requestId: 'req-123'
+ * };
+ * ```
+ */
+export interface TestApiResponse<T = unknown> {
+    /** Response data payload */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response timestamp */
+    timestamp: Date;
+    /** Unique request identifier */
+    requestId: string;
+}
+/**
+ * Test error response interface for error handling testing
+ *
+ * @example
+ * ```typescript
+ * const errorResponse: TestErrorResponse = {
+ *   error: 'ValidationError',
+ *   message: 'Email is required',
+ *   statusCode: 400,
+ *   timestamp: new Date(),
+ *   path: '/api/users',
+ *   details: { field: 'email' }
+ * };
+ * ```
+ */
+export interface TestErrorResponse {
+    /** Error type/name */
+    error: string;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Error timestamp */
+    timestamp: Date;
+    /** Request path where error occurred */
+    path?: string;
+    /** Additional error details */
+    details?: unknown;
+}
+/**
+ * Test pagination data interface for paginated response testing
+ *
+ * @typeParam T - Type of the paginated items
+ *
+ * @example
+ * ```typescript
+ * const pagination: TestPaginationData<User> = {
+ *   items: [user1, user2, user3],
+ *   total: 100,
+ *   page: 2,
+ *   pageSize: 10,
+ *   totalPages: 10,
+ *   hasNext: true,
+ *   hasPrevious: true
+ * };
+ * ```
+ */
+export interface TestPaginationData<T> {
+    /** Items in current page */
+    items: T[];
+    /** Total number of items */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Number of items per page */
+    pageSize: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there's a next page */
+    hasNext: boolean;
+    /** Whether there's a previous page */
+    hasPrevious: boolean;
+}
+/**
+ * Test metadata interface for entity metadata testing
+ *
+ * @example
+ * ```typescript
+ * const metadata: TestMetadata = {
+ *   version: '1.2.3',
+ *   source: 'api',
+ *   createdBy: 'system',
+ *   updatedBy: 'admin',
+ *   tags: ['important', 'user-data'],
+ *   labels: { environment: 'production', tier: 'premium' },
+ *   annotations: { lastMigration: '2023-01-01' }
+ * };
+ * ```
+ */
+export interface TestMetadata {
+    /** Version string */
+    version: string;
+    /** Data source identifier */
+    source: string;
+    /** Creator identifier */
+    createdBy: string;
+    /** Last updater identifier */
+    updatedBy: string;
+    /** Metadata tags */
+    tags: string[];
+    /** Key-value labels */
+    labels: Record<string, string>;
+    /** Additional annotations */
+    annotations: Record<string, unknown>;
+}
+/**
+ * Test timestamps interface for entity lifecycle testing
+ *
+ * @example
+ * ```typescript
+ * const timestamps: TestTimestamps = {
+ *   createdAt: new Date('2023-01-01'),
+ *   updatedAt: new Date('2023-01-02'),
+ *   deletedAt: null,
+ *   expiresAt: new Date('2024-01-01'),
+ *   lastAccessedAt: new Date('2023-12-31')
+ * };
+ * ```
+ */
+export interface TestTimestamps {
+    /** Entity creation date */
+    createdAt: Date;
+    /** Entity last update date */
+    updatedAt: Date;
+    /** Entity deletion date (soft delete) */
+    deletedAt?: Date | null;
+    /** Entity expiration date */
+    expiresAt?: Date | null;
+    /** Entity last access date */
+    lastAccessedAt?: Date | null;
+}
+/**
+ * Test scenario interface for scenario-driven testing
+ *
+ * @typeParam TContext - Type of the test context
+ * @typeParam TInput - Type of the test input
+ * @typeParam TExpected - Type of the expected result
+ *
+ * @example
+ * ```typescript
+ * const scenario: TestScenario<UserService, CreateUserInput, User> = {
+ *   name: 'Create user with valid data',
+ *   description: 'Should create user when valid data is provided',
+ *   data: () => ({ userService: new UserService() }),
+ *   setup: async (context) => { await context.userService.initialize(); },
+ *   arrange: async () => ({ userService: mockUserService }),
+ *   act: async (context) => context.userService.create(validUserData),
+ *   assert: (result, context) => { expect(result).toBeDefined(); },
+ *   input: { name: 'John', email: 'john@test.com' },
+ *   expected: { id: '123', name: 'John', email: 'john@test.com' }
+ * };
+ * ```
+ */
+export interface TestScenario<TContext, TInput, TExpected> {
+    /** Test scenario name */
+    name: string;
+    /** Test scenario description */
+    description: string;
+    /** Test data or factory function */
+    data: TContext | (() => TContext);
+    /** Setup function executed before test */
+    setup?: (context?: TContext) => void | Promise<void>;
+    /** Teardown function executed after test */
+    teardown?: (context?: TContext) => void | Promise<void>;
+    /** Arrange phase - prepare test context */
+    arrange: () => TContext | Promise<TContext>;
+    /** Act phase - execute the action being tested */
+    act: (instance: TContext) => unknown | Promise<unknown>;
+    /** Assert phase - verify the results */
+    assert: (result: unknown, instance: TContext) => void | Promise<void>;
+    /** Cleanup function executed after assertions */
+    cleanup?: (context?: Awaited<TContext>) => void | Promise<void>;
+    /** Optional test context */
+    context?: TContext;
+    /** Test input data */
+    input: TInput;
+    /** Expected test result */
+    expected: TExpected;
+    /** Test timeout in milliseconds */
+    timeout?: number;
+    /** Skip this scenario */
+    skip?: boolean;
+    /** Run only this scenario */
+    only?: boolean;
+    /** Additional expectations */
+    expectations?: Array<(data: TContext) => void>;
+}
+/**
+ * Scenario test suite configuration for organizing related test scenarios
+ *
+ * @typeParam TContext - Type of the test context
+ * @typeParam TInput - Type of the test input
+ * @typeParam TExpected - Type of the expected result
+ *
+ * @example
+ * ```typescript
+ * const suite: ScenarioTestSuite<UserService, CreateUserInput, User> = {
+ *   suiteName: 'User Creation Tests',
+ *   beforeAll: async () => { await setupDatabase(); },
+ *   afterAll: async () => { await cleanupDatabase(); },
+ *   beforeEach: (scenario) => { console.log(`Running: ${scenario.name}`); },
+ *   scenarios: [scenario1, scenario2, scenario3],
+ *   testFn: (input, context) => context.userService.create(input),
+ *   assertFn: (actual, expected) => { expect(actual).toEqual(expected); }
+ * };
+ * ```
+ */
+export interface ScenarioTestSuite<TContext, TInput, TExpected> {
+    /** Test suite name */
+    suiteName: string;
+    /** Setup function executed before all scenarios */
+    beforeAll?: () => void | Promise<void>;
+    /** Cleanup function executed after all scenarios */
+    afterAll?: () => void | Promise<void>;
+    /** Setup function executed before each scenario */
+    beforeEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => void | Promise<void>;
+    /** Cleanup function executed after each scenario */
+    afterEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => void | Promise<void>;
+    /** Array of test scenarios */
+    scenarios: TestScenario<TContext, TInput, TExpected>[];
+    /** Function to execute for each scenario */
+    testFn: (input: TInput, context?: TContext) => Promise<TExpected> | TExpected;
+    /** Custom assertion function */
+    assertFn?: (actual: TExpected, expected: TExpected, scenario: TestScenario<TContext, TInput, TExpected>) => void;
+}
+/**
+ * Auto-mocked repository interface for database operation testing
+ *
+ * @example
+ * ```typescript
+ * const repository: AutoMockedRepository = {
+ *   find: vi.fn().mockResolvedValue([]),
+ *   findOne: vi.fn().mockResolvedValue(null),
+ *   save: vi.fn().mockImplementation(entity => entity),
+ *   create: vi.fn().mockImplementation(data => ({ id: '123', ...data })),
+ *   // ... other methods
+ * };
+ *
+ * // Use in tests
+ * repository.find.mockResolvedValue([user1, user2]);
+ * const users = await repository.find();
+ * ```
+ */
+export interface AutoMockedRepository {
+    /** Find entities matching criteria */
+    find: Vitest.Mock;
+    /** Find single entity */
+    findOne: Vitest.Mock;
+    /** Find single entity by criteria */
+    findOneBy: Vitest.Mock;
+    /** Find single entity or throw */
+    findOneOrFail: Vitest.Mock;
+    /** Find entities by criteria */
+    findBy: Vitest.Mock;
+    /** Find entities and get count */
+    findAndCount: Vitest.Mock;
+    /** Save entity */
+    save: Vitest.Mock;
+    /** Create entity instance */
+    create: Vitest.Mock;
+    /** Update entity */
+    update: Vitest.Mock;
+    /** Delete entity */
+    delete: Vitest.Mock;
+    /** Remove entity */
+    remove: Vitest.Mock;
+    /** Count entities */
+    count: Vitest.Mock;
+    /** Execute raw query */
+    query: Vitest.Mock;
+    /** Create query builder */
+    createQueryBuilder: Vitest.Mock;
+    /** Preload entity with relations */
+    preload: Vitest.Mock;
+    /** Merge entity changes */
+    merge: Vitest.Mock;
+    /** Soft delete entity */
+    softDelete: Vitest.Mock;
+    /** Restore soft deleted entity */
+    restore: Vitest.Mock;
+    /** Check if entity exists */
+    exist: Vitest.Mock;
+    /** Clear all entities */
+    clear: Vitest.Mock;
+    /** Increment field value */
+    increment: Vitest.Mock;
+    /** Decrement field value */
+    decrement: Vitest.Mock;
+}
+/**
+ * Auto-mocked HTTP service interface for HTTP client testing
+ *
+ * @example
+ * ```typescript
+ * const httpService: AutoMockedHttpService = {
+ *   get: vi.fn().mockResolvedValue({ data: {} }),
+ *   post: vi.fn().mockResolvedValue({ data: { id: '123' } }),
+ *   put: vi.fn().mockResolvedValue({ data: { updated: true } }),
+ *   // ... other methods
+ * };
+ *
+ * // Use in tests
+ * httpService.get.mockResolvedValue({ data: { users: [] } });
+ * const response = await httpService.get('/users');
+ * ```
+ */
+export interface AutoMockedHttpService {
+    /** HTTP GET request */
+    get: Vitest.Mock;
+    /** HTTP POST request */
+    post: Vitest.Mock;
+    /** HTTP PUT request */
+    put: Vitest.Mock;
+    /** HTTP PATCH request */
+    patch: Vitest.Mock;
+    /** HTTP DELETE request */
+    delete: Vitest.Mock;
+    /** HTTP HEAD request */
+    head: Vitest.Mock;
+    /** HTTP OPTIONS request */
+    options: Vitest.Mock;
+    /** Generic HTTP request */
+    request: Vitest.Mock;
+}
+/**
+ * Auto-mocked configuration service interface for config testing
+ *
+ * @example
+ * ```typescript
+ * const configService: AutoMockedConfigService = {
+ *   get: vi.fn().mockImplementation((key) => mockConfig[key]),
+ *   getOrThrow: vi.fn().mockImplementation((key) => {
+ *     const value = mockConfig[key];
+ *     if (value === undefined) throw new Error(`Config ${key} not found`);
+ *     return value;
+ *   }),
+ *   has: vi.fn().mockImplementation((key) => key in mockConfig),
+ *   set: vi.fn()
+ * };
+ * ```
+ */
+export interface AutoMockedConfigService {
+    /** Get configuration value */
+    get: Vitest.Mock;
+    /** Get configuration value or throw */
+    getOrThrow: Vitest.Mock;
+    /** Check if configuration key exists */
+    has: Vitest.Mock;
+    /** Set configuration value */
+    set: Vitest.Mock;
+}
+/**
+ * Database update operation result
+ *
+ * @example
+ * ```typescript
+ * const result: UpdateResult = {
+ *   affected: 3,
+ *   raw: { changedRows: 3 },
+ *   generatedMaps: []
+ * };
+ *
+ * expect(result.affected).toBe(3);
+ * ```
+ */
+export interface UpdateResult {
+    /** Number of affected rows */
+    affected: number;
+    /** Raw database response */
+    raw: Record<string, unknown>;
+    /** Generated entity maps */
+    generatedMaps: unknown[];
+}
+/**
+ * Database delete operation result
+ *
+ * @example
+ * ```typescript
+ * const result: DeleteResult = {
+ *   affected: 1,
+ *   raw: { deletedRows: 1 }
+ * };
+ *
+ * expect(result.affected).toBe(1);
+ * ```
+ */
+export interface DeleteResult {
+    /** Number of affected rows */
+    affected: number;
+    /** Raw database response */
+    raw: Record<string, unknown>;
+}
+/**
+ * HTTP HEAD response interface
+ *
+ * @example
+ * ```typescript
+ * const response: HeadResponse = {
+ *   headers: {
+ *     'content-length': '1024',
+ *     'last-modified': 'Wed, 21 Oct 2015 07:28:00 GMT'
+ *   }
+ * };
+ * ```
+ */
+export interface HeadResponse {
+    /** Response headers */
+    headers: Record<string, unknown>;
+}
+/**
+ * Generic data response interface
+ *
+ * @example
+ * ```typescript
+ * const response: DataResponse = {
+ *   data: {
+ *     users: [{ id: '1', name: 'John' }],
+ *     total: 1
+ *   }
+ * };
+ * ```
+ */
+export interface DataResponse {
+    /** Response data */
+    data: Record<string, unknown>;
+}
+/**
+ * Mock definition interface for configuring mock objects
+ *
+ * @typeParam T - Type being mocked
+ *
+ * @example
+ * ```typescript
+ * const definition: MockDefinition<UserService> = {
+ *   methods: ['create', 'update', 'delete'],
+ *   properties: { isInitialized: true },
+ *   defaultImplementations: {
+ *     create: vi.fn().mockResolvedValue({ id: '123' })
+ *   }
+ * };
+ * ```
+ */
+export interface MockDefinition<T> {
+    /** Methods to mock */
+    methods?: Array<keyof T | string>;
+    /** Properties to set */
+    properties?: Partial<T>;
+    /** Default method implementations */
+    defaultImplementations?: Partial<T>;
+}
+/**
+ * Auto mock schema for defining mock behavior
+ *
+ * @typeParam T - Type being mocked
+ *
+ * @example
+ * ```typescript
+ * const schema: AutoMockSchema<UserService> = {
+ *   create: 'promise',
+ *   update: { returns: { success: true } },
+ *   delete: 'function',
+ *   isActive: 'value'
+ * };
+ * ```
+ */
+export type AutoMockSchema<T> = {
+    [K in keyof T]: 'function' | 'promise' | 'value' | {
+        returns: unknown;
+    };
+};
+/**
+ * Conditional mock condition for dynamic mock behavior
+ *
+ * @typeParam TArgs - Function argument types
+ * @typeParam TReturn - Return type
+ *
+ * @example
+ * ```typescript
+ * const condition: ConditionalMockCondition<[string], User | null> = {
+ *   when: (id: string) => id === 'invalid',
+ *   then: null
+ * };
+ *
+ * // Apply condition to mock
+ * mock.findUser.mockImplementation((id) => {
+ *   if (condition.when(id)) return condition.then;
+ *   return defaultUser;
+ * });
+ * ```
+ */
+export interface ConditionalMockCondition<TArgs extends unknown[], TReturn> {
+    /** Condition function */
+    when: (...args: TArgs) => boolean;
+    /** Value to return when condition is met */
+    then: TReturn | Error;
+}
+/**
+ * Mock call expectation for verifying method calls
+ *
+ * @typeParam T - Type being mocked
+ *
+ * @example
+ * ```typescript
+ * const expectation: MockCallExpectation<UserService> = {
+ *   method: 'create',
+ *   args: [{ name: 'John', email: 'john@test.com' }],
+ *   times: 1,
+ *   returns: { id: '123', name: 'John' }
+ * };
+ *
+ * // Verify expectation
+ * expect(mockUserService.create).toHaveBeenCalledTimes(expectation.times);
+ * expect(mockUserService.create).toHaveBeenCalledWith(...expectation.args);
+ * ```
+ */
+export interface MockCallExpectation<T> {
+    /** Method name to expect */
+    method: keyof T;
+    /** Expected arguments */
+    args?: unknown[];
+    /** Expected number of calls */
+    times?: number;
+    /** Expected return value */
+    returns?: unknown;
+}
+/**
+ * Scenario group for organizing related test scenarios
+ *
+ * @typeParam TContext - Type of the test context
+ * @typeParam TInput - Type of the test input
+ * @typeParam TExpected - Type of the expected result
+ *
+ * @example
+ * ```typescript
+ * const userValidationGroup: ScenarioGroup<UserService, CreateUserInput, ValidationResult> = {
+ *   name: 'User Validation Tests',
+ *   scenarios: [
+ *     emailValidationScenario,
+ *     nameValidationScenario,
+ *     ageValidationScenario
+ *   ],
+ *   commonSetup: async (context) => {
+ *     await context.userService.initialize();
+ *   },
+ *   commonTeardown: async (context) => {
+ *     await context.userService.cleanup();
+ *   }
+ * };
+ * ```
+ */
+export interface ScenarioGroup<TContext, TInput, TExpected> {
+    /** Group name */
+    name: string;
+    /** Scenarios in this group */
+    scenarios: TestScenario<TContext, TInput, TExpected>[];
+    /** Common setup for all scenarios */
+    commonSetup?: (context?: TContext) => void | Promise<void>;
+    /** Common teardown for all scenarios */
+    commonTeardown?: (context?: TContext) => void | Promise<void>;
+}
+/**
+ * Scenario result tracker for complex assertions and reporting
+ *
+ * @typeParam T - Type of the result value
+ *
+ * @example
+ * ```typescript
+ * const result: ScenarioResult<User> = {
+ *   scenario: 'Create user with valid email',
+ *   passed: true,
+ *   actual: { id: '123', name: 'John', email: 'john@test.com' },
+ *   expected: { id: expect.any(String), name: 'John', email: 'john@test.com' },
+ *   duration: 45 // milliseconds
+ * };
+ *
+ * // Failed scenario
+ * const failedResult: ScenarioResult<User> = {
+ *   scenario: 'Create user with invalid email',
+ *   passed: false,
+ *   actual: null,
+ *   expected: { error: 'Invalid email format' },
+ *   error: new Error('Validation failed'),
+ *   duration: 12
+ * };
+ * ```
+ */
+export interface ScenarioResult<T> {
+    /** Scenario name */
+    scenario: string;
+    /** Whether scenario passed */
+    passed: boolean;
+    /** Actual result */
+    actual: T;
+    /** Expected result */
+    expected: T;
+    /** Error if scenario failed */
+    error?: Error;
+    /** Execution duration in milliseconds */
+    duration: number;
+}

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

@@ -0,0 +1,6 @@
+export type * from './assertions';
+export type * from './factories';
+export type * from './mocks';
+export type * from './patterns';
+export type * from './utils';
+export type * from './wrappers';

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

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