@plyaz/types 1.7.18 → 1.7.19

package/dist/api/events/factories/network/types.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Network Event Factory
+ * Creates and emits network-related events with type safety
+ */
+import { type BaseEvent, type EventOptions } from '..';
+import type { NetworkClientHints as NetworkHints, NETWORK_QUALITY, NetworkInfo } from '../../../network';
+import type { ConfigSource, NETWORK_EVENTS } from '../..';
+/**
+ * Base structure for network events
+ */
+export interface NetworkEvent extends BaseEvent {
+    type: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Network quality change event
+ */
+export interface NetworkQualityEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.QUALITY_CHANGE;
+    data: {
+        previous?: NETWORK_QUALITY;
+        current: NETWORK_QUALITY;
+        networkInfo: NetworkInfo;
+        score: number;
+        factors: {
+            downlink?: number;
+            rtt?: number;
+            effectiveType?: string;
+            saveData?: boolean;
+        };
+        recommendation: 'reduce_quality' | 'maintain' | 'increase_quality';
+    };
+}
+/**
+ * Network info update event
+ */
+export interface NetworkInfoEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.INFO_UPDATE;
+    data: {
+        previous?: NetworkInfo;
+        current: NetworkInfo;
+        changes: {
+            downlink?: boolean;
+            effectiveType?: boolean;
+            rtt?: boolean;
+            saveData?: boolean;
+            type?: boolean;
+        };
+    };
+}
+/**
+ * Network config override event
+ */
+export interface NetworkConfigOverrideEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.CONFIG_OVERRIDE | typeof NETWORK_EVENTS.CONFIG_RESTORED;
+    data: {
+        property: string;
+        previousValue: unknown;
+        newValue: unknown;
+        source: ConfigSource;
+        overrideReason: string;
+        temporaryOverride?: boolean;
+        duration?: number;
+    };
+}
+/**
+ * Network preset event
+ */
+export interface NetworkPresetEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.PRESET_APPLIED | typeof NETWORK_EVENTS.PRESET_CHANGED;
+    data: {
+        preset: string;
+        previousPreset?: string;
+        config: Record<string, unknown>;
+        quality: NETWORK_QUALITY;
+        auto: boolean;
+    };
+}
+/**
+ * Network client hints event
+ */
+export interface NetworkClientHintsEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.HINTS_UPDATED;
+    data: {
+        previous?: NetworkHints;
+        current: NetworkHints;
+        source: 'auto' | 'headers' | 'manual';
+    };
+}
+/**
+ * Network auto detection event
+ */
+export interface NetworkAutoDetectionEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.AUTO_DETECTION;
+    data: {
+        detected: NetworkInfo;
+        applied: boolean;
+        reason?: string;
+        confidence: 'high' | 'medium' | 'low';
+    };
+}
+/**
+ * Network manual update event
+ */
+export interface NetworkManualUpdateEvent extends NetworkEvent {
+    type: typeof NETWORK_EVENTS.MANUAL_UPDATE;
+    data: {
+        updates: Partial<NetworkInfo>;
+        source: 'user' | 'api' | 'config';
+        reason?: string;
+    };
+}
+/**
+ * Options for emitQualityChange method
+ */
+export interface EmitQualityChangeOptions extends EventOptions {
+    current: NETWORK_QUALITY;
+    networkInfo: NetworkInfo;
+    score: number;
+    recommendation: 'reduce_quality' | 'maintain' | 'increase_quality';
+    previous?: NETWORK_QUALITY;
+}
+/**
+ * Options for emitConfigOverride method
+ */
+export interface EmitConfigOverrideOptions extends EventOptions {
+    property: string;
+    previousValue: unknown;
+    newValue: unknown;
+    source: ConfigSource;
+    overrideReason: string;
+    temporaryOverride?: boolean;
+    duration?: number;
+}
+/**
+ * Options for emitConfigRestored method
+ */
+export interface EmitConfigRestoredOptions extends EventOptions {
+    property: string;
+    previousValue: unknown;
+    newValue: unknown;
+    source: ConfigSource;
+    reason: string;
+}
+/**
+ * Options for emitPresetApplied method
+ */
+export interface EmitPresetAppliedOptions extends EventOptions {
+    preset: string;
+    config: Record<string, unknown>;
+    quality: NETWORK_QUALITY;
+    auto?: boolean;
+    previousPreset?: string;
+}
+/**
+ * Options for emitPresetChanged method
+ */
+export interface EmitPresetChangedOptions extends EventOptions {
+    preset: string;
+    previousPreset: string;
+    config: Record<string, unknown>;
+    quality: NETWORK_QUALITY;
+    auto?: boolean;
+}
+/**
+ * Options for emitAutoDetection method
+ */
+export interface EmitAutoDetectionOptions extends EventOptions {
+    detected: NetworkInfo;
+    applied: boolean;
+    confidence: 'high' | 'medium' | 'low';
+    reason?: string;
+}
+/**
+ * Union type for all network event types
+ */
+export type NetworkEventType = NetworkQualityEvent | NetworkInfoEvent | NetworkConfigOverrideEvent | NetworkPresetEvent | NetworkClientHintsEvent | NetworkAutoDetectionEvent | NetworkManualUpdateEvent;
+/**
+ * Network event handlers interface
+ */
+export interface NetworkEventHandlers {
+    onNetworkQualityChange?: (event: NetworkQualityEvent) => void;
+    onNetworkInfoUpdate?: (event: NetworkInfoEvent) => void;
+    onNetworkConfigOverride?: (event: NetworkConfigOverrideEvent) => void;
+    onNetworkConfigRestored?: (event: NetworkConfigOverrideEvent) => void;
+    onNetworkPresetApplied?: (event: NetworkPresetEvent) => void;
+    onNetworkPresetChanged?: (event: NetworkPresetEvent) => void;
+    onClientHintsUpdated?: (event: NetworkClientHintsEvent) => void;
+    onAutoDetection?: (event: NetworkAutoDetectionEvent) => void;
+    onManualUpdate?: (event: NetworkManualUpdateEvent) => void;
+    onAnyNetworkEvent?: (event: NetworkEventType) => void;
+}
+/**
+ * Union type for all network event types
+ */
+export type NetworkEventData = NetworkQualityEvent | NetworkInfoEvent | NetworkConfigOverrideEvent | NetworkPresetEvent | NetworkClientHintsEvent | NetworkAutoDetectionEvent | NetworkManualUpdateEvent;

package/dist/api/events/factories/performance/index.d.ts

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

package/dist/api/events/factories/performance/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Performance Event Factory
+ * Factory for creating and emitting performance-related events
+ */
+import type { EventOptions } from '..';
+import type { PERFORMANCE_EVENTS } from '../..';
+/**
+ * Request start event
+ */
+export interface PerformanceRequestStartEvent {
+    type: typeof PERFORMANCE_EVENTS.REQUEST_START;
+    timestamp: number;
+    data: {
+        requestId: string;
+        url: string;
+        method: string;
+    };
+}
+/**
+ * Request complete event
+ */
+export interface PerformanceRequestCompleteEvent {
+    type: typeof PERFORMANCE_EVENTS.REQUEST_COMPLETE;
+    timestamp: number;
+    data: {
+        requestId: string;
+        url: string;
+        method: string;
+        status: number;
+        duration: number;
+        size?: number;
+    };
+}
+/**
+ * Retry event
+ */
+export interface PerformanceRetryEvent {
+    type: typeof PERFORMANCE_EVENTS.RETRY;
+    timestamp: number;
+    data: {
+        requestId: string;
+        attempt: number;
+        maxAttempts: number;
+        reason: string;
+        delay: number;
+    };
+}
+/**
+ * Threshold exceeded event
+ */
+export interface PerformanceThresholdExceededEvent {
+    type: typeof PERFORMANCE_EVENTS.THRESHOLD_EXCEEDED;
+    timestamp: number;
+    data: {
+        type: string;
+        threshold: number;
+        actual: number;
+        context?: Record<string, unknown>;
+    };
+}
+/**
+ * Optimization applied event
+ */
+export interface PerformanceOptimizationAppliedEvent {
+    type: typeof PERFORMANCE_EVENTS.OPTIMIZATION_APPLIED;
+    timestamp: number;
+    data: {
+        type: string;
+        reason: string;
+        impact?: string;
+        context?: Record<string, unknown>;
+    };
+}
+/**
+ * Metric recorded event
+ */
+export interface PerformanceMetricRecordedEvent {
+    type: typeof PERFORMANCE_EVENTS.METRIC_RECORDED;
+    timestamp: number;
+    data: {
+        type: string;
+        value: number | string;
+        unit?: string;
+        tags?: Record<string, string>;
+    };
+}
+/**
+ * All performance event types
+ */
+export type PerformanceEventData = PerformanceRequestStartEvent | PerformanceRequestCompleteEvent | PerformanceRetryEvent | PerformanceThresholdExceededEvent | PerformanceOptimizationAppliedEvent | PerformanceMetricRecordedEvent;
+/**
+ * Options for emitRequestComplete method
+ */
+export interface EmitRequestCompleteOptions extends EventOptions {
+    requestId: string;
+    url: string;
+    method: string;
+    status: number;
+    duration: number;
+    size?: number;
+}
+/**
+ * Options for emitRetry method
+ */
+export interface EmitRetryOptions extends EventOptions {
+    requestId: string;
+    attempt: number;
+    maxAttempts: number;
+    reason: string;
+    delay: number;
+}
+/**
+ * Options for emitThresholdExceeded method
+ */
+export interface EmitThresholdExceededOptions extends EventOptions {
+    type: string;
+    threshold: number;
+    actual: number;
+    context?: Record<string, unknown>;
+}
+/**
+ * Options for emitOptimizationApplied method
+ */
+export interface EmitOptimizationAppliedOptions extends EventOptions {
+    type: string;
+    reason: string;
+    impact?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Options for emitMetricRecorded method
+ */
+export interface EmitMetricRecordedOptions extends EventOptions {
+    type: string;
+    value: number | string;
+    unit?: string;
+    tags?: Record<string, string>;
+}
+/**
+ * Performance event handlers interface
+ */
+export interface PerformanceEventHandlers {
+    onRequestStart?: (event: PerformanceRequestStartEvent) => void;
+    onRequestComplete?: (event: PerformanceRequestCompleteEvent) => void;
+    onRetry?: (event: PerformanceRetryEvent) => void;
+    onMetricRecorded?: (event: PerformanceMetricRecordedEvent) => void;
+    onThresholdExceeded?: (event: PerformanceThresholdExceededEvent) => void;
+    onOptimizationApplied?: (event: PerformanceOptimizationAppliedEvent) => void;
+    onAnyPerformanceEvent?: (event: PerformanceEventData) => void;
+}

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

@@ -0,0 +1,84 @@
+import type { EventScope, EventScopeWithTemporary, HandlerStrategy } from '..';
+import type { EventEmitter, HandlerOptions } from '../..';
+/**
+ * Base structure for all events
+ */
+export interface BaseEvent {
+    /** Event type/name */
+    type: string;
+    /** Timestamp when event was created (milliseconds since epoch) */
+    timestamp: number;
+    /** Optional event source identifier */
+    source?: string;
+}
+/**
+ * Options for event creation
+ */
+export interface EventOptions {
+    /** Whether to emit immediately after creation */
+    emit?: boolean;
+    /** Additional metadata to attach */
+    metadata?: Record<string, unknown>;
+    /** Event source identifier */
+    source?: string;
+}
+/**
+ * Interface representing the public API of BaseEventFactory
+ * Useful for type-checking without requiring the actual class instance
+ *
+ * This interface allows for:
+ * - Duck typing compatibility
+ * - Easier mocking in tests
+ * - Type-safe function parameters without importing the class
+ * - Clearer documentation of the public API contract
+ *
+ * @example
+ * ```typescript
+ * function useEventFactory(factory: BaseEventFactoryLike<'headers'>): void {
+ *   factory.on('changed', (data) => console.log(data));
+ *   factory.emit('changed', { headers: {} });
+ * }
+ * ```
+ */
+export interface BaseEventFactoryLike<TNamespace extends string = string> {
+    readonly emitter: EventEmitter;
+    readonly namespace: TNamespace;
+    readonly scope: string;
+    emit<T = unknown>(event: string, data?: T): void;
+    emitAcrossScopes(eventType: string, eventName: string, data: unknown, scopes?: EventScopeWithTemporary[]): void;
+    emitGeneric(eventNameOrType: string, data?: unknown): void;
+    on<T = unknown>(eventName: string, handler: (data: T) => void): () => void;
+    onAny<T = unknown>(handler: (data: T) => void): () => void;
+    once<T = unknown>(eventName: string, handler: (data: T) => void): () => void;
+    onceAny<T = unknown>(handler: (data: T) => void): () => void;
+    onScoped<T = unknown>(scope: EventScope, eventName: string, handler: (data: T) => void): () => void;
+    onceScoped<T = unknown>(scope: EventScope, eventName: string, handler: (data: T) => void): () => void;
+    addScopedHandler<T = unknown>(scope: EventScope, eventName: string, handler: (data: T) => void, options?: HandlerOptions & {
+        originalHandler?: (data: T) => void;
+    }): () => void;
+    off(event: string, handler?: Function): void;
+    offNamespaced(eventName: string, handler?: (data: unknown) => void): void;
+    offAny(handler?: (data: unknown) => void): void;
+    removeAllListeners(event?: string): void;
+    removeAllListenersNamespaced(eventName?: string): void;
+    removeAllScopedListeners(scope: EventScope, eventName?: string): void;
+    listeners(event: string): Function[];
+    listenersNamespaced(eventName: string): Function[];
+    listenerCount(event: string): number;
+    listenerCountNamespaced(eventName: string): number;
+    getScopedHandlers(scope: EventScope): Map<string, Array<(data: unknown) => void>>;
+    getScopedEventHandlers(scope: EventScope, eventName: string): Array<(data: unknown) => void>;
+    getOriginalScopedHandlers(scope: EventScope): Map<string, Array<(data: unknown) => void>>;
+    getOriginalScopedEventHandlers(scope: EventScope, eventName: string): Array<(data: unknown) => void>;
+    clearScopedHandlers(scope: EventScope): void;
+    mergeHandlerGroup<T>(global?: T, client?: T, request?: T): T | T[] | undefined;
+    mergeHandlersByPriority<T>(global?: T, config?: T, client?: T, request?: T): T | undefined;
+    mergeHandlers<T extends object | Function | undefined>(options: {
+        strategy: HandlerStrategy;
+        usePriority: boolean;
+        global?: T;
+        client?: T;
+        request?: T;
+    }): T | undefined;
+    getNamespace(): string;
+}

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

@@ -2,4 +2,6 @@
  * API Events Types
  * Re-exports all event-related types for the API package
  */
+export type * from './factories';
 export type * from './types';
+export * from './enum';