@plyaz/types 1.7.14 → 1.7.16

package/dist/errors/types.d.ts

@@ -45,8 +45,8 @@ export type ErrorDetail<ValueGiven, AllowedValues, Constraints> = WithValidation
  */
 export type ErrorDetailsList = readonly ErrorDetail<string | number | boolean, Record<string, string>, Record<string, string>>[];
 export type ErrorCodeKey = keyof typeof ERRORS_CODES;
-export type ErrorCodeValue = typeof ERRORS_CODES[ErrorCodeKey];
-export type ErrorCodeMsg = typeof ERRORS_CODES[ErrorCodeKey];
+export type ErrorCodeValue = (typeof ERRORS_CODES)[ErrorCodeKey];
+export type ErrorCodeMsg = (typeof ERRORS_CODES)[ErrorCodeKey];
 export interface ReturnResponseType<T = unknown> {
     codeStatus: number;
     message: string;
@@ -62,3 +62,11 @@ export interface ValidationErrorResponse {
     message: string;
     timestamp: string;
 }
+export interface BaseErrorResponse {
+    /** Category of the error. */
+    type: 'form' | 'auth' | 'server' | 'network' | 'runtime';
+    /** Human-readable error message. */
+    message: string;
+    /** ISO timestamp when the error occurred. */
+    timestamp: string;
+}

package/dist/logger/index.d.ts

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

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

@@ -335,3 +335,69 @@ export interface ErrorDeduplicatorOptions {
     /** Time window in ms for considering errors as duplicates */
     windowMs?: number;
 }
+/**
+ * Generic event payload type for testing event-driven systems
+ * Represents arbitrary data that can be passed with events
+ *
+ * @example
+ * ```typescript
+ * const payload: EventPayload = {
+ *   userId: '123',
+ *   action: 'login',
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
+export interface EventPayload {
+    [key: string]: unknown;
+}
+/**
+ * Event bus interface for testing event-driven architectures
+ * Provides methods for subscribing to, emitting, and managing events
+ *
+ * @typeParam T - Type of data passed to event handlers
+ *
+ * @example
+ * ```typescript
+ * const eventBus: EventBusLike<EventPayload> = {
+ *   on: (event, handler) => { subscribe(event, handler); },
+ *   off: (event, handler) => { unsubscribe(event, handler); },
+ *   emit: (event, ...args) => { emitEvent(event, ...args); }
+ * };
+ * ```
+ */
+export interface EventBusLike<T = unknown> {
+    /** Subscribe to an event */
+    on: (event: string, handler: (...args: T[]) => void) => void;
+    /** Unsubscribe from an event */
+    off: (event: string, handler: (...args: T[]) => void) => void;
+    /** Emit an event with optional data */
+    emit: (event: string, ...args: T[]) => void;
+    /** Subscribe to an event for one-time execution */
+    once?: (event: string, handler: (...args: T[]) => void) => void;
+    /** Get all listeners for an event */
+    listeners?: (event: string) => Function[];
+    /** Remove all listeners for specific event or all events */
+    removeAllListeners?: (event?: string) => void;
+}
+/**
+ * Options for event emission assertions in tests
+ * Controls how event emissions are validated and waited for
+ *
+ * @example
+ * ```typescript
+ * const options: EmissionAssertionOptions = {
+ *   times: 3,
+ *   timeout: 5000,
+ *   partial: true
+ * };
+ * ```
+ */
+export interface EmissionAssertionOptions {
+    /** Expected number of times the event should be emitted */
+    times?: number;
+    /** Timeout in milliseconds to wait for the event */
+    timeout?: number;
+    /** Whether to match the payload exactly or partially */
+    partial?: boolean;
+}

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

@@ -655,6 +655,8 @@ export interface MockFetch {
  * ```
  */
 export interface MockLocalStorage {
+    /** Internal storage object holding key-value pairs */
+    store?: Record<string, string>;
     /** Get item from storage */
     getItem: Vitest.Mock;
     /** Set item in storage */
@@ -667,6 +669,71 @@ export interface MockLocalStorage {
     length: number;
     /** Get key at index */
     key: Vitest.Mock;
+    /** Function to update the length property dynamically */
+    setLength?: (value: number) => void;
+}
+/**
+ * Test context for storage mocks
+ * Contains both original and mocked storage implementations for testing
+ *
+ * @example
+ * ```typescript
+ * const context: StorageTestContext = {
+ *   originalSessionStorage: window.sessionStorage,
+ *   originalLocalStorage: window.localStorage,
+ *   mockSessionStorage: createMockLocalStorage(),
+ *   mockLocalStorage: createMockLocalStorage()
+ * };
+ * ```
+ */
+export interface StorageTestContext {
+    /** Original sessionStorage instance before mocking */
+    originalSessionStorage: Storage | undefined;
+    /** Original localStorage instance before mocking */
+    originalLocalStorage: Storage | undefined;
+    /** Mocked sessionStorage instance */
+    mockSessionStorage: MockLocalStorage;
+    /** Mocked localStorage instance */
+    mockLocalStorage: MockLocalStorage;
+}
+/**
+ * Mock geolocation interface for testing location-based features
+ * Provides a mocked implementation of the browser's Geolocation API
+ *
+ * @example
+ * ```typescript
+ * const mockGeolocation: MockGeolocationReturn = {
+ *   getCurrentPosition: vi.fn().mockImplementation((success) => {
+ *     success({ coords: { latitude: 40.7128, longitude: -74.0060 } });
+ *   })
+ * };
+ * ```
+ */
+export interface MockGeolocationReturn {
+    /** Mock function for getting current position */
+    getCurrentPosition: ReturnType<Vitest.Mock>;
+}
+/**
+ * Extended test context for regional detection testing
+ * Includes storage mocks plus global objects needed for testing internationalization and geolocation
+ *
+ * @example
+ * ```typescript
+ * const context: RegionalTestContext = {
+ *   ...storageContext,
+ *   originalNavigator: window.navigator,
+ *   originalIntl: Intl,
+ *   originalGeolocation: navigator.geolocation
+ * };
+ * ```
+ */
+export interface RegionalTestContext extends StorageTestContext {
+    /** Original Navigator instance before mocking */
+    originalNavigator: globalThis.Navigator;
+    /** Original Intl object before mocking */
+    originalIntl: typeof Intl;
+    /** Original Geolocation instance before mocking */
+    originalGeolocation: globalThis.Geolocation;
 }
 /**
  * Mock IntersectionObserver instance interface

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

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

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

@@ -0,0 +1,140 @@
+import type * as Vitest from 'vitest';
+/**
+ * Options for setupApiTest helper
+ */
+export interface SetupApiTestOptions {
+    /**
+     * EventManager singleton to reset between tests
+     * Pass the EventManager class if you want automatic reset
+     * @default undefined
+     */
+    eventManager?: {
+        reset: () => void;
+    };
+    /**
+     * Whether to use fake timers in tests
+     * @default false
+     */
+    useFakeTimers?: boolean;
+    /**
+     * Whether to clear all mocks before each test
+     * @default true
+     */
+    clearMocks?: boolean;
+    /**
+     * Whether to clear all spies before each test
+     * Requires spies utility that has clearAll method
+     * @default false
+     */
+    clearSpies?: boolean | {
+        clearAll: () => void;
+    };
+    /**
+     * Custom setup function to run before each test
+     * Runs after built-in setup
+     * @default undefined
+     */
+    beforeEach?: () => void | Promise<void>;
+    /**
+     * Custom teardown function to run after each test
+     * Runs before built-in teardown
+     * @default undefined
+     */
+    afterEach?: () => void | Promise<void>;
+}
+/**
+ * Creates tracked spies for fetchff module
+ */
+export interface FetchffSpies {
+    createApiFetcher: Vitest.Mock;
+    isSlowConnection: Vitest.Mock;
+    fetchf: Vitest.Mock;
+    mutate: Vitest.Mock;
+    revalidate: Vitest.Mock;
+    getCache: Vitest.Mock;
+    setCache: Vitest.Mock;
+    deleteCache: Vitest.Mock;
+}
+/**
+ * Return type for setupFetchffMocks utility
+ * Provides spies and setup functions for testing fetchff module
+ */
+export interface SetupFetchffMocksReturn {
+    spies: ApiMockSpies;
+    setupMocks: {
+        fetchff: () => FetchffSpies;
+        adapter: () => ConfigAdapterSpies;
+        builder: () => ConfigBuilderSpies;
+    };
+}
+/**
+ * Combined API mock spies for convenience
+ */
+export interface ApiMockSpies {
+    fetchff: FetchffSpies;
+    adapter: ConfigAdapterSpies;
+    builder: ConfigBuilderSpies;
+}
+/**
+ * Config builder spies
+ */
+export interface ConfigBuilderSpies {
+    mergeConfigs: Vitest.Mock;
+    buildApiConfig: Vitest.Mock;
+    applyDefaults: Vitest.Mock;
+    validateConfig: Vitest.Mock;
+}
+/**
+ * Config adapter spies
+ */
+export interface ConfigAdapterSpies {
+    toFetchffConfig: Vitest.Mock;
+    fromFetchffResponse: Vitest.Mock;
+    mergeHeaders: Vitest.Mock;
+    parseRetryConfig: Vitest.Mock;
+    parseCacheConfig: Vitest.Mock;
+}
+/**
+ * Connection types based on Network Information API
+ */
+export type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
+/**
+ * Effective connection types (quality assessment)
+ */
+export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'unknown';
+/**
+ * Network connection information
+ */
+export interface NetworkInfo {
+    type: ConnectionType;
+    effectiveType: EffectiveConnectionType;
+    downlink: number | null;
+    downlinkMax: number | null;
+    rtt: number | null;
+    saveData: boolean;
+    online: boolean;
+    deviceMemory?: number | null;
+}
+/**
+ * Network connection information interface
+ * Represents the connection property of navigator for testing
+ */
+export interface NetworkInfoConnection {
+    type: ConnectionType;
+    effectiveType: EffectiveConnectionType;
+    downlink: number | null;
+    downlinkMax: number | null;
+    rtt: number | null;
+    saveData: boolean;
+}
+/**
+ * Mock navigator interface for testing network information
+ * Includes connection details and language settings
+ */
+export interface NetworkInfoNavigatorMock {
+    type?: ConnectionType;
+    onLine: boolean;
+    connection: NetworkInfoConnection;
+    language: string;
+    languages: string[];
+}

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

@@ -1,2 +1,3 @@
 export type * from './cache';
 export type * from './feature-flags';
+export type * from './api';

package/package.json

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