@plyaz/types 1.7.16 → 1.7.18

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

@@ -0,0 +1,5 @@
+/**
+ * Header Types
+ * Re-exports all header-related types for the API package
+ */
+export type * from './types';

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

@@ -0,0 +1,59 @@
+/**
+ * Header Management Type Definitions
+ * Comprehensive types for HTTP headers, following TASK-016 specification
+ */
+/**
+ * Headers that affect cache key generation (based on fetchff behavior)
+ * These headers will be included in cache key computation
+ */
+export interface CacheAffectingHeaders {
+    accept?: string;
+    'accept-language'?: string;
+    'accept-encoding'?: string;
+    authorization?: string;
+    'x-api-key'?: string;
+    cookie?: string;
+    'content-type'?: string;
+    origin?: string;
+    referer?: string;
+    'user-agent'?: string;
+}
+/**
+ * Common custom headers for API requests
+ */
+export interface CustomHeaders {
+    'x-requested-with'?: string;
+    'x-client-id'?: string;
+    'x-tenant-id'?: string;
+    'x-user-id'?: string;
+    'x-app-version'?: string;
+    'x-feature-flag'?: string;
+    'x-device-id'?: string;
+    'x-platform'?: 'ios' | 'android' | 'web' | string;
+    'x-session-id'?: string;
+    'x-locale'?: string;
+    'x-correlation-id'?: string;
+    'x-request-id'?: string;
+    'x-trace-id'?: string;
+    'x-span-id'?: string;
+}
+/**
+ * All supported headers - combines cache-affecting, custom, and allows additional headers
+ */
+export type ApiHeaders = CacheAffectingHeaders & CustomHeaders & Record<string, string>;
+/**
+ * Content types for common API scenarios
+ */
+export type ContentType = 'json' | 'form' | 'multipart' | 'xml' | 'html' | 'text' | string;
+/**
+ * Accept types for API responses
+ */
+export type AcceptType = 'json' | 'xml' | 'html' | 'text' | 'stream' | string;
+/**
+ * Authentication schemes
+ */
+export type AuthType = 'Bearer' | 'Basic' | 'ApiKey' | 'Custom';
+/**
+ * Platform types for client identification
+ */
+export type PlatformType = 'ios' | 'android' | 'web' | 'desktop' | 'mobile' | string;

package/dist/api/index.d.ts

@@ -1 +1,19 @@
-export type * from './types';
+/**
+ * API Package Types
+ * Re-exports all API-related types (events, errors, etc.)
+ */
+export type * from './events';
+export type * from './errors';
+export type * from './queue';
+export type * from './headers';
+export type * from './network';
+export type * from './regional';
+export type * from './cache';
+export type * from './retry';
+export type * from './polling';
+export type * from './revalidation';
+export type * from './strategies';
+export type * from './client';
+export type * from './performance';
+export type * from './config';
+export type * from './utils';

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

@@ -0,0 +1,14 @@
+/**
+ * Network Quality Enum
+ */
+/**
+ * Network quality levels enum
+ */
+export declare enum NETWORK_QUALITY {
+    EXCELLENT = "excellent",
+    GOOD = "good",
+    FAIR = "fair",
+    POOR = "poor",
+    OFFLINE = "offline",
+    UNKNOWN = "unknown"
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Network Types
+ * Re-exports all network-related types for the API package
+ */
+export type * from './enums';
+export type * from './types';

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

@@ -0,0 +1,121 @@
+/**
+ * Network Information API types
+ * Properly typed definitions for browser and Node.js navigator
+ */
+/**
+ * Network Information interface (partial for what we use)
+ */
+export interface NetworkInformation {
+    type?: string;
+    effectiveType?: string;
+    downlink?: number;
+    downlinkMax?: number;
+    rtt?: number;
+    saveData?: boolean;
+    addEventListener?: (type: string, listener: EventListener) => void;
+    removeEventListener?: (type: string, listener: EventListener) => void;
+}
+/**
+ * Navigator-like interface with necessary properties
+ * Avoids directly extending Navigator which is experimental in Node
+ */
+interface NavigatorLike {
+    userAgent?: string;
+    platform?: string;
+    product?: string;
+    language?: string;
+    languages?: readonly string[];
+    onLine?: boolean;
+    hardwareConcurrency?: number;
+    deviceMemory?: number;
+    maxTouchPoints?: number;
+    doNotTrack?: string | null;
+    vendor?: string;
+    appVersion?: string;
+}
+/**
+ * Extended Navigator interface with Network Information API
+ * Extends our Navigator-like interface with network connection properties
+ */
+export interface NavigatorWithConnection extends NavigatorLike {
+    onLine?: boolean;
+    connection?: NetworkInformation;
+    mozConnection?: NetworkInformation;
+    webkitConnection?: NetworkInformation;
+}
+/**
+ * Global object with navigator property
+ */
+export interface GlobalWithNavigator {
+    navigator: NavigatorWithConnection;
+    [key: string]: unknown;
+}
+/**
+ * Connection types for adaptive behavior
+ */
+export type ConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | '5g' | 'wifi' | 'ethernet' | 'unknown';
+/**
+ * Effective connection type
+ */
+export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
+/**
+ * Network information details
+ */
+export interface NetworkInfo {
+    type?: ConnectionType;
+    effectiveType?: EffectiveConnectionType;
+    downlink?: number;
+    rtt?: number;
+    saveData?: boolean;
+    onLine: boolean;
+}
+/**
+ * Quality thresholds for network assessment
+ */
+export interface QualityThresholds {
+    good?: {
+        rtt?: number;
+        downlink?: number;
+    };
+    fair?: {
+        rtt?: number;
+        downlink?: number;
+    };
+    poor?: {
+        rtt?: number;
+        downlink?: number;
+    };
+}
+/**
+ * Network status callback
+ */
+export type NetworkStatusCallback = (online: boolean) => void;
+/**
+ * Adaptive configuration based on network
+ */
+export interface AdaptiveConfig {
+    timeout?: number;
+    retry?: number;
+    prefetch?: boolean;
+    autoRefresh?: boolean;
+    batchSize?: number;
+    pageSize?: number;
+}
+/**
+ * Network client hints
+ */
+export interface NetworkClientHints {
+    downlink?: string;
+    rtt?: string;
+    ect?: string;
+    saveData?: string;
+}
+/**
+ * Network preset names
+ */
+export type NetworkPresetName = 'fast' | 'good' | 'moderate' | 'slow' | 'offline';
+/**
+ * Network event listener
+ */
+export type NetworkEventListener = (event: Event) => void;
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Performance Types
+ * Re-exports all performance-related types for the API package
+ */
+export type * from './types';

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

@@ -0,0 +1,137 @@
+/**
+ * Performance Optimization Types
+ * Types for performance configuration and monitoring
+ */
+/**
+ * Performance preset names for optimized configurations
+ */
+export type PerformancePresetName = 'minimal' | 'balanced' | 'aggressive' | 'realtime' | 'offline' | 'mobile' | 'desktop';
+/**
+ * Helper type for performance configuration in API client options
+ * Allows string preset names, full config objects, or false to disable
+ */
+export type PerformanceOption = PerformancePresetName | PerformanceConfig | false;
+/**
+ * Performance metrics for monitoring
+ */
+export interface ApiPerformanceMetrics {
+    requestCount: number;
+    cacheHits: number;
+    cacheMisses: number;
+    averageResponseTime: number;
+    errorRate: number;
+    dedupeCount: number;
+    cacheHitRate?: number;
+    networkRequests: number;
+    cancelledRequests: number;
+    retriedRequests: number;
+}
+/**
+ * Data pattern types for optimization
+ */
+export type DataPatternType = 'static' | 'user' | 'list' | 'realtime' | 'mutations' | 'media' | 'analytics';
+/**
+ * Performance configuration with API config properties
+ * Represents a configuration object that can have any ApiConfig properties
+ * plus additional performance-specific options
+ */
+export interface PerformanceConfig {
+    enableMetrics?: boolean;
+    enableAdaptive?: boolean;
+    enableProgressive?: boolean;
+    maxCacheSize?: number;
+    compressionThreshold?: number;
+    cacheTime?: number;
+    staleTime?: number;
+    dedupeTime?: number;
+    strategy?: string;
+    retry?: unknown;
+    cancellable?: boolean;
+    skipCache?: boolean;
+    cacheErrors?: boolean;
+    refetchOnFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    immediate?: boolean;
+    timeout?: number;
+    flattenResponse?: boolean;
+}
+/**
+ * Performance optimization options
+ */
+export interface PerformanceOptions {
+    preset?: PerformancePresetName;
+    dataPattern?: DataPatternType;
+    adaptive?: boolean;
+    monitoring?: boolean;
+    progressive?: boolean;
+}
+/**
+ * Bundle size optimization levels
+ */
+export type BundleSizeLevel = 'minimal' | 'standard' | 'full';
+/**
+ * Performance timing information
+ */
+export interface PerformanceTiming {
+    startTime: number;
+    dnsLookup?: number;
+    tcpConnection?: number;
+    tlsHandshake?: number;
+    requestSent?: number;
+    responseReceived?: number;
+    responseProcessed?: number;
+    totalDuration: number;
+}
+/**
+ * Request performance data
+ */
+export interface RequestPerformance {
+    url: string;
+    method: string;
+    timing: PerformanceTiming;
+    fromCache: boolean;
+    wasDeduplicated: boolean;
+    wasRetried: boolean;
+    retryCount?: number;
+    error?: Error;
+}
+/**
+ * Extended Request Config for Performance Monitoring
+ * Adds performance tracking fields to the base RequestConfig
+ */
+export interface PerformanceRequestConfig {
+    __perfMonitorId?: string;
+    fromCache?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Extended Fetch Response for Performance Monitoring
+ * Adds performance tracking fields to the base FetchResponse
+ */
+export interface PerformanceFetchResponse {
+    fromCache?: boolean;
+    deduplicated?: boolean;
+    retried?: boolean;
+    retryCount?: number;
+    config: PerformanceRequestConfig;
+    [key: string]: unknown;
+}
+/**
+ * Extended Response Error for Performance Monitoring
+ */
+export interface PerformanceResponseError {
+    config: PerformanceRequestConfig;
+    code?: string;
+    status: number;
+    statusText: string;
+    isCancelled: boolean;
+    request: PerformanceRequestConfig;
+    response: PerformanceFetchResponse | null;
+    [key: string]: unknown;
+}
+/**
+ * Type guards for performance monitoring
+ */
+export declare function isPerformanceRequestConfig(config: unknown): config is PerformanceRequestConfig;
+export declare function isPerformanceFetchResponse(response: unknown): response is PerformanceFetchResponse;
+export declare function isPerformanceResponseError(error: unknown): error is PerformanceResponseError;

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

@@ -0,0 +1,5 @@
+/**
+ * Polling Types
+ * Re-exports all polling-related types for the API package
+ */
+export type * from './types';

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

@@ -0,0 +1,74 @@
+/**
+ * Polling Configuration Types
+ * Provides type definitions for polling functionality
+ */
+/**
+ * Polling configuration for repeated requests
+ * Uses generic types to work with any response data
+ */
+export interface PollingConfig<T = unknown> {
+    /**
+     * Interval in milliseconds between polling attempts
+     * Set to 0 to disable polling
+     * @default 0
+     */
+    interval?: number;
+    /**
+     * Delay in milliseconds before each polling attempt begins
+     * Useful for throttling or staggering requests
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Maximum number of polling attempts before stopping
+     * Set to 0 or negative for unlimited attempts
+     * @default 0 (unlimited)
+     */
+    maxAttempts?: number;
+    /**
+     * Function to determine if polling should stop
+     * Return true to stop, false to continue
+     */
+    shouldStop?: (response: T) => boolean | Promise<boolean>;
+}
+/**
+ * Result of a polling operation
+ */
+export interface PollingResult<T> {
+    /** The final data received */
+    data: T;
+    /** Total number of attempts made */
+    attempts: number;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Whether polling was stopped */
+    stopped: boolean;
+    /** Reason for stopping */
+    reason?: 'condition' | 'max-attempts' | 'error' | 'cancelled';
+}
+/**
+ * Options for progressive polling
+ */
+export interface ProgressivePollingOptions {
+    /** Base interval in milliseconds */
+    baseInterval?: number;
+    /** Maximum interval in milliseconds */
+    maxInterval?: number;
+    /** Multiplier for interval increase */
+    multiplier?: number;
+}
+/**
+ * Options for conditional polling
+ */
+export interface ConditionalPollingOptions<T = unknown> {
+    /** Function to check if polling succeeded */
+    successCondition?: (response: T) => boolean;
+    /** Function to check if polling should error */
+    errorCondition?: (response: T) => boolean;
+    /** Maximum time to poll in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Polling strategy names
+ */
+export type PollingStrategyName = 'jobStatus' | 'healthCheck' | 'liveData' | 'longProcess' | 'resourceWait';

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

@@ -0,0 +1,31 @@
+/**
+ * Queue System Enums
+ */
+/**
+ * Priority levels for queue operations
+ * @description Defines the priority order for queued operations, from highest (CRITICAL) to lowest (IDLE)
+ *
+ * @example
+ * ```typescript
+ * import { PRIORITY_LEVEL } from '@plyaz/types';
+ *
+ * const priority = PRIORITY_LEVEL.HIGH; // 1
+ * if (priority <= PRIORITY_LEVEL.HIGH) {
+ *   // Handle high-priority request
+ * }
+ * ```
+ */
+export declare const PRIORITY_LEVEL: {
+    /** Critical priority - highest urgency (0) */
+    readonly CRITICAL: 0;
+    /** High priority (1) */
+    readonly HIGH: 1;
+    /** Medium priority (2) */
+    readonly MEDIUM: 2;
+    /** Normal priority (3) */
+    readonly NORMAL: 3;
+    /** Low priority (4) */
+    readonly LOW: 4;
+    /** Idle priority - lowest urgency (5) */
+    readonly IDLE: 5;
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Queue Types
+ * Re-exports all queue-related types for the API package
+ */
+export type * from './enums';
+export type * from './types';

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

@@ -0,0 +1,65 @@
+/**
+ * Queue System Type Definitions
+ */
+import type { PRIORITY_LEVEL } from './enums';
+/**
+ * Processing strategy for queue operations
+ */
+export type ProcessingStrategy = 'immediate' | 'batch' | 'throttle' | 'debounce';
+/**
+ * Base queue operation interface
+ */
+export interface QueueOperation<T = unknown> {
+    id: string;
+    timestamp: number;
+    priority?: typeof PRIORITY_LEVEL;
+    data: T;
+    metadata?: Record<string, unknown>;
+    retryCount?: number;
+}
+/**
+ * Queue configuration
+ */
+export interface QueueConfig {
+    /** Queue name for identification */
+    name: string;
+    /** Maximum queue size (prevent memory leaks) */
+    maxSize?: number;
+    /** Processing strategy */
+    strategy?: ProcessingStrategy;
+    /** Batch size for batch processing */
+    batchSize?: number;
+    /** Processing interval in ms */
+    processingInterval?: number;
+    /** Enable priority queue */
+    enablePriority?: boolean;
+    /** Enable performance tracking */
+    enableMetrics?: boolean;
+    /** Throttle rate in operations per second */
+    throttleRate?: number;
+    /** Debounce delay in ms */
+    debounceDelay?: number;
+}
+/**
+ * Queue statistics
+ */
+export interface QueueStats {
+    name: string;
+    size: number;
+    processed: number;
+    failed: number;
+    avgProcessingTime: number;
+    throughput: number;
+    isReady: boolean;
+    strategy: ProcessingStrategy;
+    totalEnqueued: number;
+    totalProcessed: number;
+}
+/**
+ * Queue processor function
+ */
+export type QueueProcessor<T> = (operation: QueueOperation<T>) => void | Promise<void>;
+/**
+ * Batch processor function
+ */
+export type BatchQueueProcessor<T> = (operations: QueueOperation<T>[]) => void | Promise<void>;

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

@@ -0,0 +1,5 @@
+/**
+ * Regional Types
+ * Re-exports all regional-related types for the API package
+ */
+export type * from './types';

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

@@ -0,0 +1,50 @@
+/**
+ * Regional detection and compliance types
+ */
+/**
+ * Regional information with compliance data
+ */
+export interface RegionInfo {
+    region: string;
+    country?: string;
+    state?: string;
+    city?: string;
+    confidence: number;
+    source?: 'timezone' | 'locale' | 'cdn-header' | 'geolocation' | 'fallback' | 'config' | 'cached';
+    restrictions?: RegionalCompliance;
+}
+/**
+ * Regional compliance configuration
+ */
+export interface RegionalCompliance {
+    code: string;
+    regulations: string[];
+    requirements: Record<string, boolean>;
+    allowedHeaders?: string[] | 'all';
+    blockedHeaders?: string[];
+    additionalHeaders?: Record<string, string>;
+}
+/**
+ * Cache configuration for regional detection
+ */
+export interface RegionalCacheConfig {
+    enabled?: boolean;
+    ttl?: number;
+    storage?: 'memory' | 'session' | 'local';
+    key?: string;
+}
+/**
+ * Detection options
+ */
+export interface RegionDetectionOptions {
+    useCachedValue?: boolean;
+    useTimezone?: boolean;
+    useLocale?: boolean;
+    useCDNHeaders?: boolean;
+    useIPDetection?: boolean;
+    useGeolocation?: boolean;
+    headers?: Record<string, unknown>;
+    cacheExpiry?: number;
+    fallbackRegion?: string;
+    cache?: RegionalCacheConfig;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Retry Types
+ * Re-exports all retry-related types for the API package
+ */
+export type * from './types';

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

@@ -0,0 +1,26 @@
+/**
+ * Retry Configuration Types
+ * Defines retry mechanism configuration options
+ *
+ * @module retry/types
+ */
+import type { RetryConfig as FetchffRetryConfig } from 'fetchff';
+/**
+ * Retry configuration options
+ * Maps to fetchff's retry mechanism
+ */
+export interface RetryConfig extends Partial<FetchffRetryConfig> {
+    /**
+     * Number of retry attempts (default: 0)
+     * Set to 0 to disable retries
+     */
+    attempts?: number;
+}
+/**
+ * Retry strategy names for type-safe access
+ */
+export type RetryStrategyName = 'none' | 'conservative' | 'standard' | 'aggressive' | 'exponential' | 'linear' | 'apiRate';
+/**
+ * Helper type for retry configuration in API client options
+ */
+export type RetryOption = RetryStrategyName | RetryConfig | false;

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

@@ -0,0 +1,5 @@
+/**
+ * Revalidation Types
+ * Re-exports all revalidation-related types for the API package
+ */
+export type * from './types';