webrequest/ts/webrequest.types.ts

/**
 * Core type definitions for @push.rocks/webrequest v4
 */

// ==================
// Cache Types
// ==================

export type TCacheStrategy =
  | 'network-first'
  | 'cache-first'
  | 'stale-while-revalidate'
  | 'network-only'
  | 'cache-only';

export type TStandardCacheMode =
  | 'default'
  | 'no-store'
  | 'reload'
  | 'no-cache'
  | 'force-cache'
  | 'only-if-cached';

export interface ICacheEntry {
  response: ArrayBuffer;
  headers: Record<string, string>;
  timestamp: number;
  etag?: string;
  lastModified?: string;
  maxAge?: number;
  url: string;
  status: number;
  statusText: string;
}

export interface ICacheOptions {
  /** Standard cache mode (fetch API compatible) */
  cache?: TStandardCacheMode;
  /** Advanced cache strategy */
  cacheStrategy?: TCacheStrategy;
  /** Maximum age in milliseconds */
  cacheMaxAge?: number;
  /** Custom cache key generator */
  cacheKey?: string | ((request: Request) => string);
  /** Force revalidation even if cached */
  revalidate?: boolean;
}

// ==================
// Retry Types
// ==================

export type TBackoffStrategy = 'exponential' | 'linear' | 'constant';

export interface IRetryOptions {
  /** Maximum number of retry attempts (default: 3) */
  maxAttempts?: number;
  /** Backoff strategy (default: 'exponential') */
  backoff?: TBackoffStrategy;
  /** Initial delay in milliseconds (default: 1000) */
  initialDelay?: number;
  /** Maximum delay in milliseconds (default: 30000) */
  maxDelay?: number;
  /** Status codes or function to determine if retry should occur */
  retryOn?: number[] | ((response: Response, error?: Error) => boolean);
  /** Callback on each retry attempt */
  onRetry?: (attempt: number, error: Error, nextDelay: number) => void;
}

// ==================
// Interceptor Types
// ==================

export type TRequestInterceptor = (
  request: Request,
) => Request | Promise<Request>;
export type TResponseInterceptor = (
  response: Response,
) => Response | Promise<Response>;

export interface IInterceptors {
  request?: TRequestInterceptor[];
  response?: TResponseInterceptor[];
}

// ==================
// Main Options
// ==================

export interface IWebrequestOptions extends Omit<RequestInit, 'cache'> {
  // Caching
  cache?: TStandardCacheMode;
  cacheStrategy?: TCacheStrategy;
  cacheMaxAge?: number;
  cacheKey?: string | ((request: Request) => string);
  revalidate?: boolean;

  // Retry & Fault Tolerance
  retry?: boolean | IRetryOptions;
  fallbackUrls?: string[];
  timeout?: number;

  // Interceptors
  interceptors?: IInterceptors;

  // Deduplication
  deduplicate?: boolean;

  // Logging
  logging?: boolean;
}

// ==================
// Result Types
// ==================

export interface IWebrequestSuccess<T> {
  ok: true;
  data: T;
  response: Response;
}

export interface IWebrequestError {
  ok: false;
  error: Error;
  response?: Response;
}

export type TWebrequestResult<T> = IWebrequestSuccess<T> | IWebrequestError;

// ==================
// Internal Types
// ==================

export interface ICacheMetadata {
  maxAge: number;
  etag?: string;
  lastModified?: string;
  immutable: boolean;
  noCache: boolean;
  noStore: boolean;
  mustRevalidate: boolean;
}