@plyaz/types 1.6.0 → 1.7.1

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

@@ -3,7 +3,9 @@
  *
  * Type definitions for factory utilities.
  */
+import type { Promisable, UnknownRecord, UnknownArray, SetOptional } from 'type-fest';
 import type * as Vitest from 'vitest';
+import type { Entity, Named, WithMetadata, Timestamped, SoftDeletable, Describable, Authored, WithTags, Versioned, WithSource, WithLabels, WithAnnotations, Tracked, WithDuration, WithExpiration, WithLastAccessed, NavigablePaginatedCollection, WithTimestamp, WithEmail, WithRoles, WithPermissions, WithUserId, WithLocale, WithTimezone, WithUserAgent, WithIpAddress, WithCountry, WithEnvironment, WithHttpStatus, WithRequestId, WithHeaders, WithErrorDetailed } from '../../../common/types';
 /**
  * Test user interface for user-related testing
  *
@@ -21,23 +23,7 @@ import type * as Vitest from 'vitest';
  * };
  * ```
  */
-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;
+export interface TestUser extends Entity, Named, WithMetadata, WithEmail, WithRoles, WithPermissions {
 }
 /**
  * Test context interface for environment and user context
@@ -56,28 +42,14 @@ export interface TestUser {
  * };
  * ```
  */
-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;
+export type TestContext = SetOptional<WithUserId & WithEnvironment & WithLocale & WithTimezone & WithUserAgent & WithIpAddress & WithCountry, 'userId' | 'locale' | 'timezone' | 'userAgent' | 'ip' | 'country'> & {
     /** Client region */
     region?: string;
     /** Client city */
     city?: string;
     /** Additional context fields */
     [key: string]: string | undefined;
-}
+};
 /**
  * Test API response interface for HTTP response testing
  *
@@ -95,19 +67,9 @@ export interface TestContext {
  * };
  * ```
  */
-export interface TestApiResponse<T = unknown> {
+export interface TestApiResponse<T = unknown> extends WithTimestamp<Date>, WithHeaders, WithRequestId, WithHttpStatus {
     /** 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
@@ -124,20 +86,7 @@ export interface TestApiResponse<T = unknown> {
  * };
  * ```
  */
-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;
-}
+export type TestErrorResponse = WithErrorDetailed;
 /**
  * Test pagination data interface for paginated response testing
  *
@@ -156,22 +105,7 @@ export interface TestErrorResponse {
  * };
  * ```
  */
-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;
-}
+export type TestPaginationData<T> = NavigablePaginatedCollection<T>;
 /**
  * Test metadata interface for entity metadata testing
  *
@@ -188,22 +122,7 @@ export interface TestPaginationData<T> {
  * };
  * ```
  */
-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>;
-}
+export type TestMetadata = Versioned & WithSource & Authored & WithTags & WithLabels & WithAnnotations;
 /**
  * Test timestamps interface for entity lifecycle testing
  *
@@ -218,18 +137,7 @@ export interface TestMetadata {
  * };
  * ```
  */
-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;
-}
+export type TestTimestamps = Timestamped<Date, Date> & SoftDeletable & WithExpiration<Date | null> & WithLastAccessed<Date | null>;
 /**
  * Test scenario interface for scenario-driven testing
  *
@@ -252,25 +160,21 @@ export interface TestTimestamps {
  * };
  * ```
  */
-export interface TestScenario<TContext, TInput, TExpected> {
-    /** Test scenario name */
-    name: string;
-    /** Test scenario description */
-    description: string;
+export interface TestScenario<TContext, TInput, TExpected> extends Named, Describable {
     /** Test data or factory function */
     data: TContext | (() => TContext);
     /** Setup function executed before test */
-    setup?: (context?: TContext) => void | Promise<void>;
+    setup?: (context?: TContext) => Promisable<void>;
     /** Teardown function executed after test */
-    teardown?: (context?: TContext) => void | Promise<void>;
+    teardown?: (context?: TContext) => Promisable<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>;
+    assert: (result: unknown, instance: TContext) => Promisable<void>;
     /** Cleanup function executed after assertions */
-    cleanup?: (context?: Awaited<TContext>) => void | Promise<void>;
+    cleanup?: (context?: Awaited<TContext>) => Promisable<void>;
     /** Optional test context */
     context?: TContext;
     /** Test input data */
@@ -310,17 +214,17 @@ export interface ScenarioTestSuite<TContext, TInput, TExpected> {
     /** Test suite name */
     suiteName: string;
     /** Setup function executed before all scenarios */
-    beforeAll?: () => void | Promise<void>;
+    beforeAll?: () => Promisable<void>;
     /** Cleanup function executed after all scenarios */
-    afterAll?: () => void | Promise<void>;
+    afterAll?: () => Promisable<void>;
     /** Setup function executed before each scenario */
-    beforeEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => void | Promise<void>;
+    beforeEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => Promisable<void>;
     /** Cleanup function executed after each scenario */
-    afterEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => void | Promise<void>;
+    afterEach?: (scenario: TestScenario<TContext, TInput, TExpected>) => Promisable<void>;
     /** Array of test scenarios */
     scenarios: TestScenario<TContext, TInput, TExpected>[];
     /** Function to execute for each scenario */
-    testFn: (input: TInput, context?: TContext) => Promise<TExpected> | TExpected;
+    testFn: (input: TInput, context?: TContext) => Promisable<TExpected>;
     /** Custom assertion function */
     assertFn?: (actual: TExpected, expected: TExpected, scenario: TestScenario<TContext, TInput, TExpected>) => void;
 }
@@ -468,9 +372,9 @@ export interface UpdateResult {
     /** Number of affected rows */
     affected: number;
     /** Raw database response */
-    raw: Record<string, unknown>;
+    raw: UnknownRecord;
     /** Generated entity maps */
-    generatedMaps: unknown[];
+    generatedMaps: UnknownArray;
 }
 /**
  * Database delete operation result
@@ -489,7 +393,7 @@ export interface DeleteResult {
     /** Number of affected rows */
     affected: number;
     /** Raw database response */
-    raw: Record<string, unknown>;
+    raw: UnknownRecord;
 }
 /**
  * HTTP HEAD response interface
@@ -504,10 +408,7 @@ export interface DeleteResult {
  * };
  * ```
  */
-export interface HeadResponse {
-    /** Response headers */
-    headers: Record<string, unknown>;
-}
+export type HeadResponse = WithHeaders;
 /**
  * Generic data response interface
  *
@@ -523,7 +424,7 @@ export interface HeadResponse {
  */
 export interface DataResponse {
     /** Response data */
-    data: Record<string, unknown>;
+    data: UnknownRecord;
 }
 /**
  * Mock definition interface for configuring mock objects
@@ -618,7 +519,7 @@ export interface MockCallExpectation<T> {
     /** Method name to expect */
     method: keyof T;
     /** Expected arguments */
-    args?: unknown[];
+    args?: UnknownArray;
     /** Expected number of calls */
     times?: number;
     /** Expected return value */
@@ -649,15 +550,13 @@ export interface MockCallExpectation<T> {
  * };
  * ```
  */
-export interface ScenarioGroup<TContext, TInput, TExpected> {
-    /** Group name */
-    name: string;
+export interface ScenarioGroup<TContext, TInput, TExpected> extends Named {
     /** Scenarios in this group */
     scenarios: TestScenario<TContext, TInput, TExpected>[];
     /** Common setup for all scenarios */
-    commonSetup?: (context?: TContext) => void | Promise<void>;
+    commonSetup?: (context?: TContext) => Promisable<void>;
     /** Common teardown for all scenarios */
-    commonTeardown?: (context?: TContext) => void | Promise<void>;
+    commonTeardown?: (context?: TContext) => Promisable<void>;
 }
 /**
  * Scenario result tracker for complex assertions and reporting
@@ -724,17 +623,9 @@ export interface ScenarioResult<T> {
  * };
  * ```
  */
-export interface TrackedCallRecord<TArgs extends unknown[], TReturn> {
+export interface TrackedCallRecord<TArgs extends unknown[], TReturn, TTimestamp = Date> extends Omit<Tracked<TReturn>, 'timestamp'>, WithDuration, WithTimestamp<TTimestamp> {
     /** Function arguments */
     args: TArgs;
-    /** Call timestamp */
-    timestamp: Date;
-    /** Return value */
-    result?: TReturn;
-    /** Error if thrown */
-    error?: Error;
-    /** Call duration in milliseconds */
-    duration?: number;
 }
 /**
  * Enhanced mock function with call tracking and filtering capabilities.
@@ -766,16 +657,16 @@ export interface TrackedCallRecord<TArgs extends unknown[], TReturn> {
  * trackedFn.resetCalls();
  * ```
  */
-export interface TrackedMockFunction<TArgs extends unknown[], TReturn> extends Vitest.Mock<(...args: TArgs) => TReturn> {
+export interface TrackedMockFunction<TArgs extends unknown[], TReturn, TTimestamp = Date> extends Vitest.Mock<(...args: TArgs) => TReturn> {
     /** Array of all call records with metadata */
-    calls: Array<TrackedCallRecord<TArgs, TReturn>>;
+    calls: Array<TrackedCallRecord<TArgs, TReturn, TTimestamp>>;
     /** Get a specific call by index */
-    getCall: (index: number) => TrackedCallRecord<TArgs, TReturn> | undefined;
+    getCall: (index: number) => TrackedCallRecord<TArgs, TReturn, TTimestamp> | undefined;
     /** Find calls matching a predicate */
     findCalls: (predicate: (call: {
         args: TArgs;
-        timestamp: Date;
-    }) => boolean) => Array<TrackedCallRecord<TArgs, TReturn>>;
+        timestamp: TTimestamp;
+    }) => boolean) => Array<TrackedCallRecord<TArgs, TReturn, TTimestamp>>;
     /** Reset all tracked calls */
     resetCalls: () => void;
 }

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

@@ -42,6 +42,8 @@ import type * as Next from 'next';
 import type * as NextRouter from 'next/router';
 import type * as NextImage from 'next/image';
 import type * as NextLink from 'next/link';
+import type { UnknownRecord, UnknownArray, Arrayable } from 'type-fest';
+import type { Named, WithStatusCode, WithStatusMessage, WithUrl, WithHttpMethod, WithHeaders, WithQueryParams, WithBody, WithCookies, WithParams, Resettable, WithStatus, Identifiable } from '../../../common/types';
 /**
  * Mock file system interface matching Node.js fs module
  *
@@ -442,9 +444,7 @@ export interface MockTestingModule {
  * };
  * ```
  */
-export type HttpExceptionError = Error & {
-    /** HTTP status code */
-    status: number;
+export type HttpExceptionError = Error & WithStatus<number> & {
     /** Error response data */
     response: string | object;
     /** Get HTTP status code */
@@ -465,9 +465,7 @@ export type HttpExceptionError = Error & {
  * };
  * ```
  */
-export type SimpleExceptionError = Error & {
-    /** Error status code */
-    status: number;
+export type SimpleExceptionError = Error & WithStatus & {
     /** Error response data */
     response: unknown;
 };
@@ -544,7 +542,7 @@ export interface MockProvider<T = unknown> {
  * expect(router.push).toHaveBeenCalledWith('/users/456');
  * ```
  */
-export interface MockRouter {
+export interface MockRouter extends WithQueryParams {
     /** Navigate to new route */
     push: Vitest.Mock;
     /** Replace current route */
@@ -559,8 +557,6 @@ export interface MockRouter {
     prefetch: Vitest.Mock;
     /** Current pathname */
     pathname: string;
-    /** Query parameters */
-    query: Record<string, string | string[]>;
     /** Full path with query */
     asPath: string;
     /** Navigate by delta in history */
@@ -783,7 +779,6 @@ export interface MockNextRouter extends Omit<NextRouter.NextRouter, 'push' | 're
     };
     pathname: string;
     route: string;
-    query: Record<string, string | string[]>;
     asPath: string;
     basePath: string;
     locale?: string;
@@ -825,15 +820,7 @@ export type MockNextLink = NextLink.LinkProps & {
  * };
  * ```
  */
-export type MockNextApiRequest = Partial<Next.NextApiRequest> & {
-    /** Request headers */
-    headers: Record<string, string | string[]>;
-    /** Query parameters */
-    query: Record<string, string | string[]>;
-    /** Request body */
-    body: unknown;
-    /** Request cookies */
-    cookies: Record<string, string>;
+export type MockNextApiRequest = Partial<Next.NextApiRequest> & WithHeaders & WithQueryParams & WithBody & WithCookies & {
     /** Environment variables */
     env: Record<string, string | undefined>;
 };
@@ -853,7 +840,7 @@ export type MockNextApiRequest = Partial<Next.NextApiRequest> & {
  * expect(res.statusCode).toBe(200);
  * ```
  */
-export interface MockNextApiResponse {
+export interface MockNextApiResponse extends WithStatusMessage, WithStatusCode {
     /** Set response status */
     status: Vitest.Mock;
     /** Send JSON response */
@@ -872,10 +859,6 @@ export interface MockNextApiResponse {
     write: Vitest.Mock;
     /** End response */
     end: Vitest.Mock;
-    /** Current status code */
-    statusCode: number;
-    /** Current status message */
-    statusMessage: string;
 }
 /**
  * Mock Next.js Next.GetServerSidePropsContext with mock request/response
@@ -1015,21 +998,7 @@ export interface HttpMockOptions {
  * };
  * ```
  */
-export interface MockHttpRequest {
-    /** HTTP method */
-    method: string;
-    /** Request URL */
-    url: string;
-    /** Request headers */
-    headers: Record<string, string | string[]>;
-    /** Query parameters */
-    query: Record<string, string | string[]>;
-    /** Route parameters */
-    params: Record<string, string>;
-    /** Request body */
-    body: unknown;
-    /** Request cookies */
-    cookies?: Record<string, string>;
+export interface MockHttpRequest extends WithUrl, WithHttpMethod, WithHeaders, WithQueryParams, WithBody, WithParams, Partial<WithCookies> {
     /** Environment variables */
     env?: Record<string, string | undefined>;
     /** Socket information */
@@ -1070,11 +1039,7 @@ export interface MockHttpRequest {
  * expect(response.statusCode).toBe(200);
  * ```
  */
-export interface MockHttpResponse {
-    /** Current status code */
-    statusCode: number;
-    /** Current status message */
-    statusMessage: string;
+export interface MockHttpResponse extends WithStatusCode, WithStatusMessage, WithHeaders {
     /** Set status code */
     status: Vitest.Mock;
     /** Send JSON response */
@@ -1105,8 +1070,6 @@ export interface MockHttpResponse {
     finished?: boolean;
     /** Whether headers are sent */
     headersSent?: boolean;
-    /** Response headers */
-    headers?: Record<string, string | string[]>;
 }
 /**
  * Browser history entry interface
@@ -1224,15 +1187,13 @@ export interface NextLinkChildProps {
  * };
  * ```
  */
-export interface ErrorHandlerMock {
+export interface ErrorHandlerMock extends Resettable {
     /** Error event handler */
     onError: Vitest.Mock;
     /** Catch block handler */
     onCatch: Vitest.Mock;
     /** Finally block handler */
     onFinally: Vitest.Mock;
-    /** Reset all handlers */
-    reset: () => void;
 }
 /**
  * Generic value wrapper interface
@@ -1272,9 +1233,7 @@ export interface ValueWrapper<T> {
  * };
  * ```
  */
-export interface HttpTestScenario {
-    /** Descriptive name for the test scenario */
-    name: string;
+export interface HttpTestScenario extends Named {
     /** Target framework for the test */
     framework?: 'node' | 'express' | 'nextjs';
     /** Mock request configuration */
@@ -1284,7 +1243,7 @@ export interface HttpTestScenario {
     /** Expected response body */
     expectedBody?: unknown;
     /** Expected response headers */
-    expectedHeaders?: Record<string, string | string[]>;
+    expectedHeaders?: Record<string, Arrayable<string>>;
     /** Expected redirect URL */
     expectedRedirect?: string;
 }
@@ -1303,7 +1262,7 @@ export interface TimerCallbackEntry {
     /** Function to be called */
     callback: Function;
     /** Arguments to pass to callback */
-    args: unknown[];
+    args: UnknownArray;
 }
 /**
  * Mock HTTP server interface for testing server operations
@@ -1536,7 +1495,7 @@ export interface StatefulMock<TState, TMethods> {
     /** History of method calls with arguments and timestamps */
     history: Array<{
         method: string;
-        args: unknown[];
+        args: UnknownArray;
         timestamp: number;
     }>;
     /** Clear the call history */
@@ -1575,8 +1534,7 @@ export type CreateMockUseRouterReturn = Vitest.Mock;
 /**
  * Type definition for createMockWebSocket function return
  */
-export interface CreateMockWebSocketReturn {
-    url: string;
+export interface CreateMockWebSocketReturn extends WithUrl {
     protocol: string;
     extensions: string;
     readyState: number;
@@ -1587,7 +1545,7 @@ export interface CreateMockWebSocketReturn {
     ping: Vitest.Mock;
     pong: Vitest.Mock;
     terminate: Vitest.Mock;
-    messages: unknown[];
+    messages: UnknownArray;
     simulateMessage: (data: unknown) => void;
     simulateError: (error: Error) => void;
     simulateClose: (code?: number, reason?: string) => void;
@@ -1678,7 +1636,7 @@ export interface AdvancedConsoleMock {
     debugs: string[];
     all: Array<{
         type: string;
-        args: unknown[];
+        args: UnknownArray;
     }>;
     install: () => void;
     uninstall: () => void;
@@ -1885,7 +1843,7 @@ export interface MockCookie {
  * await mockSession.save();
  * ```
  */
-export interface MockSession {
+export interface MockSession extends Identifiable {
     get: Vitest.Mock;
     set: Vitest.Mock;
     delete: Vitest.Mock;
@@ -1896,8 +1854,7 @@ export interface MockSession {
     regenerate: Vitest.Mock;
     touch: Vitest.Mock;
     reload: Vitest.Mock;
-    id: string;
-    _data: Record<string, unknown>;
+    _data: UnknownRecord;
     _dirty: boolean;
     _destroyed: boolean;
 }
@@ -1971,7 +1928,7 @@ export interface MockInterceptor {
 export interface MockOS {
     platform: Vitest.Mock<() => string>;
     arch: Vitest.Mock<() => string>;
-    cpus: Vitest.Mock<() => unknown[]>;
+    cpus: Vitest.Mock<() => UnknownArray>;
     totalmem: Vitest.Mock<() => number>;
     freemem: Vitest.Mock<() => number>;
     uptime: Vitest.Mock<() => number>;
@@ -2104,11 +2061,11 @@ export interface ConsoleMockParams {
     storage: string[];
     all: Array<{
         type: string;
-        args: unknown[];
+        args: UnknownArray;
     }>;
     originalFn: Function;
     suppressTypes: string[];
-    formatArguments: (args: unknown[]) => string;
+    formatArguments: (args: readonly unknown[]) => string;
     captureStackTrace?: boolean;
 }
 /**
@@ -2170,7 +2127,7 @@ export interface MockWorkerThreads {
     parentPort: unknown;
     workerData: unknown;
     threadId: number;
-    resourceLimits: Record<string, unknown>;
+    resourceLimits: UnknownRecord;
     getEnvironmentData: Vitest.Mock<() => unknown>;
     setEnvironmentData: Vitest.Mock<(key: string, value: unknown) => void>;
     SHARE_ENV: symbol;