@plyaz/types 1.7.18 → 1.7.20

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

@@ -15,6 +15,11 @@ export interface CacheEntry<T = unknown> extends Partial<WithMetadata<Record<str
     /** The cached data */
     data: T;
 }
+export interface GenericCacheEntry<T = unknown> {
+    value: T;
+    timestamp: number;
+    ttl: number;
+}
 /**
  * Cache statistics for monitoring and debugging.
  */

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

@@ -44,16 +44,39 @@ export interface SetupApiTestOptions {
     afterEach?: () => void | Promise<void>;
 }
 /**
- * Creates tracked spies for fetchff module
+ * Mock spies for fetchff module functions
+ * Provides tracked mock implementations for all fetchff API methods
+ *
+ * @example
+ * ```typescript
+ * const spies: FetchffSpies = {
+ *   createApiFetcher: vi.fn(),
+ *   isSlowConnection: vi.fn().mockReturnValue(false),
+ *   fetchf: vi.fn().mockResolvedValue({ data: {} }),
+ *   mutate: vi.fn().mockResolvedValue({ data: {} }),
+ *   revalidate: vi.fn().mockResolvedValue(undefined),
+ *   getCache: vi.fn().mockReturnValue(null),
+ *   setCache: vi.fn(),
+ *   deleteCache: vi.fn()
+ * };
+ * ```
  */
 export interface FetchffSpies {
+    /** Mock for createApiFetcher function */
     createApiFetcher: Vitest.Mock;
+    /** Mock for isSlowConnection network detection function */
     isSlowConnection: Vitest.Mock;
+    /** Mock for fetchf main fetching function */
     fetchf: Vitest.Mock;
+    /** Mock for mutate data mutation function */
     mutate: Vitest.Mock;
+    /** Mock for revalidate cache revalidation function */
     revalidate: Vitest.Mock;
+    /** Mock for getCache cache retrieval function */
     getCache: Vitest.Mock;
+    /** Mock for setCache cache storage function */
     setCache: Vitest.Mock;
+    /** Mock for deleteCache cache deletion function */
     deleteCache: Vitest.Mock;
 }
 /**
@@ -69,30 +92,79 @@ export interface SetupFetchffMocksReturn {
     };
 }
 /**
- * Combined API mock spies for convenience
+ * Combined collection of all API-related mock spies
+ * Aggregates fetchff, adapter, and builder spies in a single interface for easy access
+ *
+ * @example
+ * ```typescript
+ * const apiSpies: ApiMockSpies = {
+ *   fetchff: createFetchffSpies(),
+ *   adapter: createAdapterSpies(),
+ *   builder: createBuilderSpies()
+ * };
+ *
+ * // Use in tests
+ * apiSpies.fetchff.fetchf.mockResolvedValue({ data: 'test' });
+ * apiSpies.adapter.toFetchffConfig.mockReturnValue(config);
+ * ```
  */
 export interface ApiMockSpies {
+    /** Fetchff module spies */
     fetchff: FetchffSpies;
+    /** Config adapter spies */
     adapter: ConfigAdapterSpies;
+    /** Config builder spies */
     builder: ConfigBuilderSpies;
 }
 /**
- * Config builder spies
+ * Mock spies for configuration builder module
+ * Tracks calls to config construction and validation functions
+ *
+ * @example
+ * ```typescript
+ * const builderSpies: ConfigBuilderSpies = {
+ *   mergeConfigs: vi.fn().mockReturnValue(mergedConfig),
+ *   buildApiConfig: vi.fn().mockReturnValue(apiConfig),
+ *   applyDefaults: vi.fn().mockReturnValue(configWithDefaults),
+ *   validateConfig: vi.fn().mockReturnValue(true)
+ * };
+ * ```
  */
 export interface ConfigBuilderSpies {
+    /** Mock for mergeConfigs function that combines multiple configs */
     mergeConfigs: Vitest.Mock;
+    /** Mock for buildApiConfig function that constructs API configuration */
     buildApiConfig: Vitest.Mock;
+    /** Mock for applyDefaults function that applies default values */
     applyDefaults: Vitest.Mock;
+    /** Mock for validateConfig function that validates configuration */
     validateConfig: Vitest.Mock;
 }
 /**
- * Config adapter spies
+ * Mock spies for configuration adapter module
+ * Tracks configuration transformation and parsing operations
+ *
+ * @example
+ * ```typescript
+ * const adapterSpies: ConfigAdapterSpies = {
+ *   toFetchffConfig: vi.fn().mockReturnValue(fetchffConfig),
+ *   fromFetchffResponse: vi.fn().mockReturnValue(response),
+ *   mergeHeaders: vi.fn().mockReturnValue(mergedHeaders),
+ *   parseRetryConfig: vi.fn().mockReturnValue(retryConfig),
+ *   parseCacheConfig: vi.fn().mockReturnValue(cacheConfig)
+ * };
+ * ```
  */
 export interface ConfigAdapterSpies {
+    /** Mock for toFetchffConfig function that converts config to fetchff format */
     toFetchffConfig: Vitest.Mock;
+    /** Mock for fromFetchffResponse function that transforms fetchff responses */
     fromFetchffResponse: Vitest.Mock;
+    /** Mock for mergeHeaders function that combines header objects */
     mergeHeaders: Vitest.Mock;
+    /** Mock for parseRetryConfig function that parses retry configuration */
     parseRetryConfig: Vitest.Mock;
+    /** Mock for parseCacheConfig function that parses cache configuration */
     parseCacheConfig: Vitest.Mock;
 }
 /**
@@ -118,110 +190,389 @@ export interface NetworkInfoNavigatorMock {
     language: string;
     languages: string[];
 }
+/**
+ * Return type for generic event factory mocks
+ * Provides basic event emitter functionality for testing event-driven systems
+ *
+ * @example
+ * ```typescript
+ * const eventFactory: CreateMockEventFactoryReturn = {
+ *   on: vi.fn(),
+ *   off: vi.fn(),
+ *   emit: vi.fn(),
+ *   emitGeneric: vi.fn(),
+ *   onAny: vi.fn(),
+ *   offAny: vi.fn()
+ * };
+ *
+ * // Use in tests
+ * eventFactory.on('event', handler);
+ * eventFactory.emit('event', data);
+ * ```
+ */
 export interface CreateMockEventFactoryReturn {
+    /** Mock for subscribing to specific events */
     on: ReturnType<Vitest.Mock>;
+    /** Mock for unsubscribing from specific events */
     off: ReturnType<Vitest.Mock>;
+    /** Mock for emitting specific events */
     emit: ReturnType<Vitest.Mock>;
+    /** Mock for emitting generic events with any payload */
     emitGeneric: ReturnType<Vitest.Mock>;
+    /** Mock for subscribing to all events (wildcard listener) */
     onAny: ReturnType<Vitest.Mock>;
+    /** Mock for unsubscribing from all events */
     offAny: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for network-related events
+ * Provides spies for all network event emission methods
+ *
+ * @example
+ * ```typescript
+ * const networkFactory: CreateMockNetworkFactory = {
+ *   emitQualityChanged: vi.fn(),
+ *   emitQualityChange: vi.fn(),
+ *   emitConfigOverride: vi.fn(),
+ *   emitConfigRestored: vi.fn(),
+ *   emitInfoUpdate: vi.fn(),
+ *   emitPresetApplied: vi.fn(),
+ *   emitPresetChanged: vi.fn(),
+ *   emitHintsUpdated: vi.fn(),
+ *   emitAutoDetection: vi.fn(),
+ *   emitManualUpdate: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockNetworkFactory {
+    /** Mock for emitting network quality changed events */
     emitQualityChanged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network quality change events */
     emitQualityChange: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network config override events */
     emitConfigOverride: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network config restored events */
     emitConfigRestored: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network info update events */
     emitInfoUpdate: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network preset applied events */
     emitPresetApplied: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network preset changed events */
     emitPresetChanged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network hints updated events */
     emitHintsUpdated: ReturnType<Vitest.Mock>;
+    /** Mock for emitting auto-detection events */
     emitAutoDetection: ReturnType<Vitest.Mock>;
+    /** Mock for emitting manual network update events */
     emitManualUpdate: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for error-related events
+ * Provides spies for all error event emission methods
+ *
+ * @example
+ * ```typescript
+ * const errorFactory: CreateMockErrorFactory = {
+ *   emitError: vi.fn(),
+ *   emitNetworkError: vi.fn(),
+ *   emitTimeoutError: vi.fn(),
+ *   emitClientError: vi.fn(),
+ *   emitServerError: vi.fn(),
+ *   emitValidationError: vi.fn(),
+ *   emitHeadersError: vi.fn(),
+ *   emitCritical: vi.fn()
+ * };
+ *
+ * // Trigger error events in tests
+ * errorFactory.emitNetworkError({ message: 'Connection failed' });
+ * ```
+ */
 export interface CreateMockErrorFactory {
+    /** Mock for emitting generic error events */
     emitError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network-related error events */
     emitNetworkError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting timeout error events */
     emitTimeoutError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting client-side error events (4xx) */
     emitClientError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting server-side error events (5xx) */
     emitServerError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting validation error events */
     emitValidationError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting headers-related error events */
     emitHeadersError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting critical error events */
     emitCritical: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for header-related events
+ * Provides spies for all HTTP header event emission methods
+ *
+ * @example
+ * ```typescript
+ * const headerFactory: CreateMockHeaderFactory = {
+ *   emitChanged: vi.fn(),
+ *   emitEnriched: vi.fn(),
+ *   emitConflict: vi.fn(),
+ *   emitOverride: vi.fn(),
+ *   emitMerged: vi.fn(),
+ *   emitFiltered: vi.fn(),
+ *   emitValidated: vi.fn(),
+ *   emitCached: vi.fn(),
+ *   emitCacheHit: vi.fn(),
+ *   emitCacheMiss: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockHeaderFactory {
+    /** Mock for emitting header changed events */
     emitChanged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header enriched events */
     emitEnriched: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header conflict events */
     emitConflict: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header override events */
     emitOverride: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header merged events */
     emitMerged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header filtered events */
     emitFiltered: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header validated events */
     emitValidated: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header cached events */
     emitCached: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header cache hit events */
     emitCacheHit: ReturnType<Vitest.Mock>;
+    /** Mock for emitting header cache miss events */
     emitCacheMiss: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for debug and monitoring events
+ * Provides spies for all debugging and tracking event emission methods
+ *
+ * @example
+ * ```typescript
+ * const debugFactory: CreateMockDebugFactory = {
+ *   emitConfigConflict: vi.fn(),
+ *   emitConflict: vi.fn(),
+ *   emitConfigChange: vi.fn(),
+ *   emitHeadersTracked: vi.fn(),
+ *   emitNetworkOverride: vi.fn(),
+ *   emitNetworkStateChanged: vi.fn(),
+ *   emitNetworkDataCleared: vi.fn(),
+ *   emitDebugInfo: vi.fn(),
+ *   emitTracking: vi.fn(),
+ *   emitPerformance: vi.fn(),
+ *   emitMonitoringAlert: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockDebugFactory {
+    /** Mock for emitting config conflict debug events */
     emitConfigConflict: ReturnType<Vitest.Mock>;
+    /** Mock for emitting generic conflict events */
     emitConflict: ReturnType<Vitest.Mock>;
+    /** Mock for emitting config change debug events */
     emitConfigChange: ReturnType<Vitest.Mock>;
+    /** Mock for emitting headers tracked debug events */
     emitHeadersTracked: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network override debug events */
     emitNetworkOverride: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network state changed debug events */
     emitNetworkStateChanged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting network data cleared debug events */
     emitNetworkDataCleared: ReturnType<Vitest.Mock>;
+    /** Mock for emitting general debug information events */
     emitDebugInfo: ReturnType<Vitest.Mock>;
+    /** Mock for emitting tracking events */
     emitTracking: ReturnType<Vitest.Mock>;
+    /** Mock for emitting performance debug events */
     emitPerformance: ReturnType<Vitest.Mock>;
+    /** Mock for emitting monitoring alert events */
     emitMonitoringAlert: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for configuration-related events
+ * Provides spies for config lifecycle event emission methods
+ *
+ * @example
+ * ```typescript
+ * const configFactory: CreateMockConfigFactory = {
+ *   emitGlobalUpdated: vi.fn(),
+ *   emitConfigChanged: vi.fn(),
+ *   emitConfigOverride: vi.fn(),
+ *   emitConfigRestored: vi.fn(),
+ *   emitConfigValidated: vi.fn(),
+ *   emitPresetApplied: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockConfigFactory {
+    /** Mock for emitting global config updated events */
     emitGlobalUpdated: ReturnType<Vitest.Mock>;
+    /** Mock for emitting config changed events */
     emitConfigChanged: ReturnType<Vitest.Mock>;
+    /** Mock for emitting config override events */
     emitConfigOverride: ReturnType<Vitest.Mock>;
+    /** Mock for emitting config restored events */
     emitConfigRestored: ReturnType<Vitest.Mock>;
+    /** Mock for emitting config validated events */
     emitConfigValidated: ReturnType<Vitest.Mock>;
+    /** Mock for emitting preset applied events */
     emitPresetApplied: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for performance monitoring events
+ * Provides spies for all performance metric event emission methods
+ *
+ * @example
+ * ```typescript
+ * const perfFactory: CreateMockPerformanceFactory = {
+ *   emitMetric: vi.fn(),
+ *   emitTiming: vi.fn(),
+ *   emitThreshold: vi.fn(),
+ *   emitCacheHit: vi.fn(),
+ *   emitCacheMiss: vi.fn(),
+ *   emitRequestStart: vi.fn(),
+ *   emitRequestComplete: vi.fn(),
+ *   emitRetry: vi.fn(),
+ *   emitThresholdExceeded: vi.fn(),
+ *   emitOptimizationApplied: vi.fn(),
+ *   emitMetricRecorded: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockPerformanceFactory {
+    /** Mock for emitting performance metric events */
     emitMetric: ReturnType<Vitest.Mock>;
+    /** Mock for emitting performance timing events */
     emitTiming: ReturnType<Vitest.Mock>;
+    /** Mock for emitting performance threshold events */
     emitThreshold: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache hit performance events */
     emitCacheHit: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache miss performance events */
     emitCacheMiss: ReturnType<Vitest.Mock>;
+    /** Mock for emitting request start events */
     emitRequestStart: ReturnType<Vitest.Mock>;
+    /** Mock for emitting request complete events */
     emitRequestComplete: ReturnType<Vitest.Mock>;
+    /** Mock for emitting retry attempt events */
     emitRetry: ReturnType<Vitest.Mock>;
+    /** Mock for emitting threshold exceeded events */
     emitThresholdExceeded: ReturnType<Vitest.Mock>;
+    /** Mock for emitting optimization applied events */
     emitOptimizationApplied: ReturnType<Vitest.Mock>;
+    /** Mock for emitting metric recorded events */
     emitMetricRecorded: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for cache-related events
+ * Provides spies for all cache operation event emission methods
+ *
+ * @example
+ * ```typescript
+ * const cacheFactory: CreateMockCacheFactory = {
+ *   emitHit: vi.fn(),
+ *   emitMiss: vi.fn(),
+ *   emitSet: vi.fn(),
+ *   emitDelete: vi.fn(),
+ *   emitClear: vi.fn(),
+ *   emitExpire: vi.fn(),
+ *   emitCacheHit: vi.fn(),
+ *   emitCacheMiss: vi.fn(),
+ *   emitCacheSet: vi.fn(),
+ *   emitCacheDelete: vi.fn(),
+ *   emitCacheClear: vi.fn(),
+ *   emitCacheExpire: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockCacheFactory {
+    /** Mock for emitting cache hit events (short form) */
     emitHit: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache miss events (short form) */
     emitMiss: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache set events (short form) */
     emitSet: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache delete events (short form) */
     emitDelete: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache clear events (short form) */
     emitClear: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache expire events (short form) */
     emitExpire: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache hit events (full form) */
     emitCacheHit: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache miss events (full form) */
     emitCacheMiss: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache set events (full form) */
     emitCacheSet: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache delete events (full form) */
     emitCacheDelete: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache clear events (full form) */
     emitCacheClear: ReturnType<Vitest.Mock>;
+    /** Mock for emitting cache expire events (full form) */
     emitCacheExpire: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for base lifecycle events
+ * Provides spies for fundamental lifecycle event emission methods
+ *
+ * @example
+ * ```typescript
+ * const baseFactory: CreateMockBaseFactory = {
+ *   emitInitialized: vi.fn(),
+ *   emitDestroyed: vi.fn(),
+ *   emitReady: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockBaseFactory {
+    /** Mock for emitting initialized lifecycle events */
     emitInitialized: ReturnType<Vitest.Mock>;
+    /** Mock for emitting destroyed lifecycle events */
     emitDestroyed: ReturnType<Vitest.Mock>;
+    /** Mock for emitting ready state events */
     emitReady: ReturnType<Vitest.Mock>;
 }
+/**
+ * Mock factory for client-related events
+ * Provides spies for all API client event emission methods
+ *
+ * @example
+ * ```typescript
+ * const clientFactory: CreateMockClientFactory = {
+ *   emitRequest: vi.fn(),
+ *   emitResponse: vi.fn(),
+ *   emitError: vi.fn(),
+ *   emitRetry: vi.fn(),
+ *   emitTimeout: vi.fn(),
+ *   emitConflict: vi.fn(),
+ *   emitDebug: vi.fn(),
+ *   emitCreated: vi.fn(),
+ *   emitDestroyed: vi.fn()
+ * };
+ * ```
+ */
 export interface CreateMockClientFactory {
+    /** Mock for emitting API request events */
     emitRequest: ReturnType<Vitest.Mock>;
+    /** Mock for emitting API response events */
     emitResponse: ReturnType<Vitest.Mock>;
+    /** Mock for emitting client error events */
     emitError: ReturnType<Vitest.Mock>;
+    /** Mock for emitting retry attempt events */
     emitRetry: ReturnType<Vitest.Mock>;
+    /** Mock for emitting timeout events */
     emitTimeout: ReturnType<Vitest.Mock>;
+    /** Mock for emitting conflict events */
     emitConflict: ReturnType<Vitest.Mock>;
+    /** Mock for emitting debug events */
     emitDebug: ReturnType<Vitest.Mock>;
+    /** Mock for emitting client created events */
     emitCreated: ReturnType<Vitest.Mock>;
+    /** Mock for emitting client destroyed events */
     emitDestroyed: ReturnType<Vitest.Mock>;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.7.18",
+  "version": "1.7.20",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -182,11 +182,11 @@
     "@eslint/markdown": "^6.5.0",
     "@nestjs/common": "^11.1.3",
     "@next/eslint-plugin-next": "^15.0.3",
-    "@plyaz/config": "^1.5.2",
-    "fetchff": "^4.1.0",
+    "@plyaz/config": "^1.5.3",
     "@plyaz/devtools": "^1.9.4",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
+    "@types/express": "^5.0.3",
     "@types/node": "^22.14.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
@@ -221,6 +221,8 @@
     "eslint-plugin-testing-library": "^6.5.0",
     "eslint-plugin-unicorn": "^56.0.1",
     "eslint-plugin-unused-imports": "^4.1.4",
+    "express": "^5.1.0",
+    "fetchff": "^4.1.0",
     "jiti": "^2.4.2",
     "jsdom": "^26.1.0",
     "markdownlint": "^0.38.0",