@plyaz/types 1.7.18 → 1.7.20

package/dist/api/client/enum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Event constants
+ */
+export declare const EVENT_CONSTANTS: {
+    readonly DEBUG_INFO_INTERVAL_MULTIPLIER: 5;
+    readonly IMPACT_THRESHOLDS: {
+        readonly NONE: 90;
+        readonly LOW: 70;
+        readonly MEDIUM: 50;
+        readonly HIGH: 30;
+    };
+};

package/dist/api/client/index.d.ts

@@ -3,3 +3,4 @@
  * Re-exports all client-related types for the API package
  */
 export type * from './types';
+export * from './enum';

package/dist/api/client/types.d.ts

@@ -2,6 +2,8 @@
  * API Client Types
  * Defines the client interface and options
  */
+import type { ApiConfig } from '../config';
+import type { ConfigUpdateStrategy, HandlerStrategy } from '../events';
 /**
  * Options for creating an API client
  * Endpoints are automatically included from src/api/endpoints
@@ -29,3 +31,115 @@ export type ApiClientOptions = Record<string, unknown>;
  * Note: Full type definition requires EndpointTypes and endpoints from api package
  */
 export type ApiClientInstance = Record<string, unknown>;
+/**
+ * Event handler registration options
+ */
+export interface HandlerOptions {
+    strategy?: HandlerStrategy;
+    priority?: number;
+    namespace?: string;
+}
+/**
+ * Config update options
+ */
+export interface UpdateConfigOptions {
+    strategy?: ConfigUpdateStrategy;
+    priority?: number;
+    namespace?: string;
+    scope?: string;
+    preserveFields?: (keyof ApiConfig)[];
+}
+/**
+ * Client event configuration - uses ApiConfig directly
+ * This ensures we never miss any event configuration if ApiConfig is updated
+ */
+export type ClientEventConfig = Partial<ApiConfig>;
+/**
+ * Monitoring state for a client instance
+ */
+export interface ClientMonitoringState {
+    intervals: Array<ReturnType<typeof globalThis.setInterval>>;
+    subscriptions: Array<() => void>;
+    monitoring: boolean;
+}
+/**
+ * Type for fetchff client with internal config
+ * Using index signature to avoid naming convention issues
+ */
+export type FetchffClientWithConfig = Record<string, unknown> & {
+    [key: string]: unknown;
+};
+/**
+ * Validation result for configuration updates
+ * Indicates whether the config update is valid and provides error details if not
+ *
+ * @example
+ * ```typescript
+ * const validation: TrackValidation = {
+ *   valid: false,
+ *   errors: ['Invalid timeout value', 'Cache strategy not found']
+ * };
+ * ```
+ */
+export interface TrackValidation {
+    /** Whether the configuration is valid */
+    valid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+}
+/**
+ * Represents a single configuration property change
+ * Tracks what changed, from what value, to what value
+ *
+ * @example
+ * ```typescript
+ * const change: AnalyzeConfigChanges = {
+ *   property: 'timeout',
+ *   oldValue: 30000,
+ *   newValue: 60000,
+ *   changed: true
+ * };
+ * ```
+ */
+export interface AnalyzeConfigChanges {
+    /** Name of the configuration property that changed */
+    property: string;
+    /** Previous value before the change */
+    oldValue: unknown;
+    /** New value after the change */
+    newValue: unknown;
+    /** Whether the value actually changed */
+    changed: boolean;
+}
+/**
+ * Parameters for tracking configuration updates
+ * Contains all information needed to debug and monitor config changes
+ *
+ * @example
+ * ```typescript
+ * const params: TrackConfigUpdateParams = {
+ *   updates: { timeout: 60000, retry: { attempts: 5 } },
+ *   updateOptions: { strategy: 'merge' },
+ *   configChanges: [
+ *     { property: 'timeout', oldValue: 30000, newValue: 60000, changed: true }
+ *   ],
+ *   eventImpact: { handlersUpdated: 2, scopesAffected: ['client', 'request'] },
+ *   validation: { valid: true, errors: [] },
+ *   startTime: Date.now()
+ * };
+ * ```
+ */
+export interface TrackConfigUpdateParams {
+    /** Configuration updates being applied */
+    updates: Partial<ApiClientOptions>;
+    /** Options controlling how the update is applied */
+    updateOptions: UpdateConfigOptions | undefined;
+    /** Detailed list of configuration changes */
+    configChanges: Array<AnalyzeConfigChanges>;
+    /** Impact on event handlers and scopes */
+    eventImpact: Record<string, unknown>;
+    /** Validation result for the update */
+    validation: TrackValidation;
+    /** Timestamp when the update started */
+    startTime: number;
+}

package/dist/api/config/types.d.ts

@@ -9,17 +9,13 @@ import type { CacheStrategyName } from '../cache';
 import type { RetryConfig, RetryStrategyName } from '../retry';
 import type { PerformancePresetName } from '../performance';
 import type { RevalidationStrategyName } from '../revalidation';
-import type { ApiHeaders } from '../headers';
+import type { ApiHeaders, EnrichedHeadersOptions, HeaderBuilderLike, HeaderPresetName } from '../headers';
 import type { ErrorEventHandlers } from '../errors';
 import type { ConfigUpdateStrategy, HandlerStrategy, EventScopeWithTemporary } from '../events';
 import type { NETWORK_QUALITY } from '../network';
 import type { HeaderEventHandlers, NetworkEventHandlers, ConfigEventHandlers, ClientEventHandlers, CacheEventHandlers, PerformanceEventHandlers } from '../events';
 import type { ApiClientOptions } from '../client';
-type HeaderBuilder = unknown;
-type HeaderPresetName = string;
-type DebugEventsConfig = Record<string, unknown>;
-type EnrichedHeadersOptions = Record<string, unknown>;
-export type { ConfigUpdateStrategy } from '../events';
+import type { DebugEventsConfig } from '../debugger';
 /**
  * HTTP Methods - extend from fetchff but uppercase
  */
@@ -54,7 +50,7 @@ export type RetryInterceptor = NonNullable<FetchffRequestConfig['onRetry']>;
  * Extends fetchff's RequestConfig with our abstraction layer
  * Supports ALL fetchff configuration options
  */
-export interface ApiConfig<TApiPackageError = unknown> extends Partial<Omit<FetchffRequestConfig, 'retry' | 'cache' | 'cacheTime' | 'staleTime' | 'skipCache' | 'cacheErrors' | 'cacheKey' | 'cacheBuster' | 'pollingInterval' | 'pollingDelay' | 'maxPollingAttempts' | 'shouldStopPolling' | 'data' | 'headers' | 'onRequest' | 'onResponse' | 'onError' | 'onRetry'>> {
+export interface ApiConfig extends Partial<Omit<FetchffRequestConfig, 'retry' | 'cache' | 'cacheTime' | 'staleTime' | 'skipCache' | 'cacheErrors' | 'cacheKey' | 'cacheBuster' | 'pollingInterval' | 'pollingDelay' | 'maxPollingAttempts' | 'shouldStopPolling' | 'data' | 'headers' | 'onRequest' | 'onResponse' | 'onError' | 'onRetry'>> {
     /** Base URL for all requests */
     baseURL?: string;
     /** Default HTTP method */
@@ -154,7 +150,7 @@ export interface ApiConfig<TApiPackageError = unknown> extends Partial<Omit<Fetc
         /** Dynamic headers computed at request time */
         dynamic?: () => ApiHeaders | Promise<ApiHeaders>;
         /** Header builder for complex logic */
-        builder?: (builder: HeaderBuilder) => HeaderBuilder;
+        builder?: (builder: HeaderBuilderLike) => HeaderBuilderLike;
         /** Auto-detect network conditions and add Client Hints */
         autoDetectNetwork?: boolean;
         /** Request Client Hints from browser */
@@ -325,7 +321,7 @@ export interface ApiConfig<TApiPackageError = unknown> extends Partial<Omit<Fetc
      * });
      * ```
      */
-    errorHandlers?: ErrorEventHandlers<TApiPackageError>;
+    errorHandlers?: ErrorEventHandlers;
     /**
      * Configuration event handlers for monitoring config changes and updates
      * Track when global config is updated, reset, or when presets are applied
@@ -632,3 +628,54 @@ export interface ApiResponse<TData = DefaultPayload, TBody = DefaultPayload, TPa
  */
 export interface ApiError<TData = DefaultPayload, TBody = DefaultPayload, TParams = DefaultParams, TPathParams = UrlPathParams> extends ResponseError<TData, TBody, TParams, TPathParams> {
 }
+/**
+ * Configuration state that tracks base config and temporary overrides separately
+ */
+export interface ConfigState {
+    /** Base configuration (persisted across requests) */
+    baseConfig: ApiConfig;
+    /** Temporary overrides (can be cleared without affecting base) */
+    temporaryOverrides: Partial<ApiConfig>;
+    /** Metadata about the configuration */
+    metadata: {
+        createdAt: string;
+        lastUpdatedAt: string;
+        updateCount: number;
+    };
+}
+/**
+ * Options for applying configuration updates
+ */
+export interface ConfigUpdateOptions {
+    /** Strategy for how to apply the update */
+    strategy?: ConfigUpdateStrategy;
+    /** Essential fields that should be preserved even during replace */
+    preserveFields?: (keyof ApiConfig)[];
+    /** Whether to track this update in metadata */
+    trackUpdate?: boolean;
+}
+/**
+ * Result of a configuration update operation
+ */
+export interface ConfigUpdateResult {
+    /** Updated configuration state */
+    state: ConfigState;
+    /** Effective configuration (base + temporary merged) */
+    effectiveConfig: ApiConfig;
+    /** Fields that were modified */
+    modifiedFields: string[];
+    /** Whether the update resulted in any changes */
+    hasChanges: boolean;
+}
+/**
+ * Parameters for tracking global config update
+ */
+export interface TrackGlobalConfigParams {
+    currentConfig: ApiConfig;
+    mergedConfig: ApiConfig;
+    config: ApiConfig;
+    eventImpact: Record<string, unknown>;
+    scopesChanged: boolean;
+    startTime: number;
+    configEntries: Array<[string, unknown]>;
+}

package/dist/api/debugger/enums.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Debugger Event Namespaces and Constants
+ * Centralized definition of all debugger tracking operations and event types
+ */
+/**
+ * Factory operation types for tracking
+ * Used when tracking factory-related operations
+ */
+export declare const FACTORY_OPERATIONS: {
+    readonly FACTORY_CREATED: "factory_created";
+    readonly FACTORY_ACCESSED: "factory_accessed";
+    readonly FACTORY_INITIALIZED: "factory_initialized";
+    readonly FACTORIES_RESET: "factories_reset";
+    readonly FACTORY_REGISTER: "factory_register";
+    readonly HANDLER_REGISTERED: "handler_registered";
+    readonly HANDLER_UNREGISTERED: "handler_unregistered";
+    readonly SCOPE_LISTENERS_CLEARED: "scope_listeners_cleared";
+};
+/**
+ * Event system operation types
+ * Used when tracking event system operations
+ */
+export declare const EVENT_OPERATIONS: {
+    readonly ON: "on";
+    readonly ONCE: "once";
+    readonly OFF: "off";
+    readonly EMIT: "emit";
+    readonly EMIT_ACROSS_SCOPES: "emit_across_scopes";
+    readonly REMOVE_ALL_LISTENERS: "removeAllListeners";
+    readonly ONCE_EXECUTED: "once_executed";
+    readonly CONFIG_UPDATE: "config_update";
+    readonly CONFIG_UPDATE_FAILED: "config_update_failed";
+    readonly GLOBAL_CONFIG_UPDATE: "global_config_update";
+    readonly GLOBAL_CONFIG_RESET: "global_config_reset";
+    readonly SCOPE_CHANGE: "scope_change";
+    readonly FACTORY_CREATE: "factory_create";
+    readonly FACTORY_COORDINATION: "factory_coordination";
+    readonly HANDLER_STRATEGY: "handler_strategy";
+    readonly HANDLER_STRATEGY_APPLIED: "handler_strategy_applied";
+};
+/**
+ * Queue operation types
+ * Used when tracking queue operations
+ */
+export declare const QUEUE_OPERATIONS: {
+    readonly QUEUE_CREATED: "queue_created";
+    readonly QUEUE_PROCESSED: "queue_processed";
+    readonly QUEUE_CLEARED: "queue_cleared";
+    readonly QUEUE_ERROR: "queue_error";
+    readonly BATCH_PROCESSED: "batch_processed";
+    readonly ITEM_ENQUEUED: "item_enqueued";
+    readonly ITEM_DEQUEUED: "item_dequeued";
+    readonly PRIORITY_CHANGED: "priority_changed";
+};
+/**
+ * Config tracking sources
+ * Used to identify the source of configuration changes
+ */
+export declare const DEBUGGER_CONFIG_SOURCES: {
+    readonly DEFAULT: "default";
+    readonly DIRECT: "direct";
+    readonly CLIENT: "client";
+    readonly UNIFIED_STRATEGY: "unifiedStrategy";
+    readonly PERFORMANCE_PRESET: "performancePreset";
+    readonly DATA_PATTERN: "dataPattern";
+    readonly CACHE_STRATEGY: "cacheStrategy";
+    readonly RETRY_STRATEGY: "retryStrategy";
+    readonly REVALIDATION_STRATEGY: "revalidationStrategy";
+    readonly ADAPTIVE_CONFIG: "adaptiveConfig";
+    readonly MONITORING_CONFIG: "monitoringConfig";
+    readonly POLLING_CONFIG: "pollingConfig";
+    readonly NETWORK_PRESET: "networkPreset";
+    readonly NETWORK_AWARE: "networkAware";
+    readonly NETWORK_QUALITY: "networkQuality";
+    readonly USER_PREFERENCE: "userPreference";
+    readonly TEMPORARY_OVERRIDE: "temporaryOverride";
+    readonly AUTO_OPTIMIZATION: "autoOptimization";
+    readonly NETWORK_CLIENT_HINTS: "networkClientHints";
+    readonly HEADER_PRESET: "headerPreset";
+    readonly ENRICHED_HEADERS: "enrichedHeaders";
+    readonly USER_HEADERS: "userHeaders";
+    readonly INTERCEPTOR: "interceptor";
+    readonly CONTEXT_HEADERS: "contextHeaders";
+};
+/**
+ * Debug history entry types
+ * Used to categorize history entries
+ */
+export declare const HISTORY_TYPES: {
+    readonly CONFIG: "config";
+    readonly HEADER: "header";
+    readonly NETWORK: "network";
+    readonly PERFORMANCE: "performance";
+    readonly EVENT: "event";
+    readonly EVENT_OPERATION: "event_operation";
+};
+/**
+ * Header transformation stages
+ * Used to track header changes through the pipeline
+ */
+export declare const HEADER_STAGES: {
+    readonly BASE: "base";
+    readonly ENRICHED: "enriched";
+    readonly INTERCEPTOR: "interceptor";
+    readonly FINAL: "final";
+};
+/**
+ * Config update strategies
+ * Used when updating configuration
+ */
+export declare const UPDATE_STRATEGIES: {
+    readonly MERGE: "merge";
+    readonly REPLACE: "replace";
+    readonly TEMPORARY: "temporary";
+};
+/**
+ * Combined operation types for unified tracking
+ */
+export declare const UNIFIED_OPERATIONS: {
+    readonly QUEUE_CREATED: "queue_created";
+    readonly QUEUE_PROCESSED: "queue_processed";
+    readonly QUEUE_CLEARED: "queue_cleared";
+    readonly QUEUE_ERROR: "queue_error";
+    readonly BATCH_PROCESSED: "batch_processed";
+    readonly ITEM_ENQUEUED: "item_enqueued";
+    readonly ITEM_DEQUEUED: "item_dequeued";
+    readonly PRIORITY_CHANGED: "priority_changed";
+    readonly ON: "on";
+    readonly ONCE: "once";
+    readonly OFF: "off";
+    readonly EMIT: "emit";
+    readonly EMIT_ACROSS_SCOPES: "emit_across_scopes";
+    readonly REMOVE_ALL_LISTENERS: "removeAllListeners";
+    readonly ONCE_EXECUTED: "once_executed";
+    readonly CONFIG_UPDATE: "config_update";
+    readonly CONFIG_UPDATE_FAILED: "config_update_failed";
+    readonly GLOBAL_CONFIG_UPDATE: "global_config_update";
+    readonly GLOBAL_CONFIG_RESET: "global_config_reset";
+    readonly SCOPE_CHANGE: "scope_change";
+    readonly FACTORY_CREATE: "factory_create";
+    readonly FACTORY_COORDINATION: "factory_coordination";
+    readonly HANDLER_STRATEGY: "handler_strategy";
+    readonly HANDLER_STRATEGY_APPLIED: "handler_strategy_applied";
+    readonly FACTORY_CREATED: "factory_created";
+    readonly FACTORY_ACCESSED: "factory_accessed";
+    readonly FACTORY_INITIALIZED: "factory_initialized";
+    readonly FACTORIES_RESET: "factories_reset";
+    readonly FACTORY_REGISTER: "factory_register";
+    readonly HANDLER_REGISTERED: "handler_registered";
+    readonly HANDLER_UNREGISTERED: "handler_unregistered";
+    readonly SCOPE_LISTENERS_CLEARED: "scope_listeners_cleared";
+};
+export type DebuggerConfigSource = (typeof DEBUGGER_CONFIG_SOURCES)[keyof typeof DEBUGGER_CONFIG_SOURCES];

package/dist/api/debugger/factories/index.d.ts

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

package/dist/api/debugger/factories/types.d.ts

@@ -0,0 +1,191 @@
+import type { DEBUGGER_CONFIG_SOURCES, UnifiedOperationType } from '..';
+import type { HandlerStrategy } from '../..';
+/**
+ * Use the proper operation types from debugger/types.ts
+ */
+export type EventOperation = UnifiedOperationType;
+/**
+ * Event tracking metadata interface
+ */
+export interface EventTrackingMetadata {
+    operation: EventOperation;
+    event: string;
+    timestamp: number;
+    source: 'pubsub' | 'eventManager' | 'clientEventManager' | 'factory' | 'config';
+    module: string;
+    listenerCount?: number;
+    totalEvents?: number;
+    totalListeners?: number;
+    eventPattern?: {
+        isWildcard: boolean;
+        namespace: string | null;
+        scope: string | null;
+    };
+    operationMetadata?: {
+        wasNewEvent?: boolean;
+        previousListenerCount?: number;
+        newListenerCount?: number;
+        callbackType?: string;
+        addedSuccessfully?: boolean;
+        isUnsubscribe?: boolean;
+        beforeRemoveCount?: number;
+        afterRemoveCount?: number;
+        eventDeleted?: boolean;
+        isOneTimeListener?: boolean;
+        executionTime?: number;
+        autoUnsubscribed?: boolean;
+        directListeners?: number;
+        wildcardListeners?: number;
+        globalWildcardListeners?: number;
+        totalTriggered?: number;
+        dataType?: string;
+        dataSize?: number;
+        hasWildcardMatches?: boolean;
+        strategy?: HandlerStrategy | 'prioritize';
+        configSource?: keyof typeof DEBUGGER_CONFIG_SOURCES;
+        previousConfig?: unknown;
+        newConfig?: unknown;
+        impactedEvents?: string[];
+        factoryType?: string;
+        registeredEvents?: string[];
+        mergedFactories?: string[];
+        replacedFactories?: string[];
+        conflicts?: Array<{
+            property: string;
+        }>;
+        source?: string;
+        quality?: string;
+    };
+    performance?: {
+        operationDuration?: number;
+        memoryUsage?: number;
+        cpuUsage?: number;
+    };
+    context?: {
+        stackTrace?: string;
+        userAgent?: string;
+        sessionId?: string;
+        requestId?: string;
+    };
+}
+/**
+ * Event tracking summary for reporting
+ */
+export interface EventTrackingSummary {
+    totalOperations: number;
+    operationsByType: Record<EventOperation, number>;
+    operationsBySource: Record<string, number>;
+    operationsByModule: Record<string, number>;
+    mostActiveEvents: Array<{
+        event: string;
+        operations: number;
+    }>;
+    averageListenerCount: number;
+    peakListenerCount: number;
+    memoryImpact: number;
+    performanceMetrics: {
+        averageOperationTime: number;
+        slowestOperations: Array<{
+            operation: EventOperation;
+            duration: number;
+            event: string;
+        }>;
+    };
+    configImpacts: Array<{
+        strategy: string;
+        impactedEvents: string[];
+        timestamp: number;
+    }>;
+}
+/**
+ * Header event analysis result
+ */
+export interface HeaderEventAnalysis {
+    totalHeaderEvents: number;
+    headerOperations: Record<string, number>;
+    conflictsByHeader: Record<string, number>;
+    overridesBySource: Record<string, number>;
+    averageHeaderProcessingTime: number;
+}
+/**
+ * Network event analysis result
+ */
+export interface NetworkEventAnalysis {
+    totalNetworkEvents: number;
+    qualityChanges: number;
+    configOverrides: number;
+    presetApplications: number;
+    qualityDistribution: Record<string, number>;
+    averageQualityChangeTime: number;
+}
+/**
+ * Config event analysis result
+ */
+export interface ConfigEventAnalysis {
+    totalConfigEvents: number;
+    updatesBySource: Record<string, number>;
+    strategiesUsed: Record<string, number>;
+    conflictsByProperty: Record<string, number>;
+    averageConfigUpdateTime: number;
+    impactedEventsByUpdate: number;
+}
+/**
+ * Factory event analysis result
+ */
+export interface FactoryEventAnalysis {
+    totalFactoryEvents: number;
+    factoryOperations: Record<string, number>;
+    factoriesByType: Record<string, number>;
+    registrationPatterns: Record<string, number>;
+    averageFactoryOperationTime: number;
+}
+/**
+ * PubSub event analysis result
+ */
+export interface PubSubEventAnalysis {
+    totalPubSubEvents: number;
+    operationsByType: Record<string, number>;
+    mostActiveEvents: Array<{
+        event: string;
+        operations: number;
+    }>;
+    listenerTrends: {
+        averageListenerCount: number;
+        peakListenerCount: number;
+        listenerCountByEvent: Record<string, number>;
+    };
+    wildCardUsage: {
+        totalWildcardEvents: number;
+        wildcardPatterns: Record<string, number>;
+    };
+    performanceMetrics: {
+        averageEmitTime: number;
+        slowestOperations: Array<{
+            operation: string;
+            duration: number;
+            event: string;
+        }>;
+    };
+}
+/**
+ * Combined tracking analysis for all event types
+ */
+export interface EventTrackingAnalysis {
+    headers: HeaderEventAnalysis;
+    network: NetworkEventAnalysis;
+    config: ConfigEventAnalysis;
+    factory: FactoryEventAnalysis;
+    pubsub: PubSubEventAnalysis;
+}
+/**
+ * Impact tracking state for performance calculations
+ */
+export interface ImpactState {
+    ux: number;
+    bandwidth: number;
+    latency: number;
+    latencyImpact: number;
+    bandwidthImpact: number;
+    cacheEfficiencyImpact: number;
+    recommendations: string[];
+}

package/dist/api/debugger/index.d.ts

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