Skip to content
rhttp.io

Types

All types are exported from every entry point (rhttp.io, rhttp.io/client, rhttp.io/server, rhttp.io/react).

HttpRequestOptions

Options passed per-request to any HTTP method.

interface HttpRequestOptions extends Omit<RequestInit, "headers" | "cache"> {
  params?: Record<string, any>;
  headers?: Record<string, string>;
  cache?: boolean | Partial<CacheConfig> | { strategy?: CacheStrategy };
  retry?: boolean | Partial<RetryConfig>;
  timeout?: number;
  deduplicate?: boolean;
  csrf?: boolean;
  requestId?: string;
  hooks?: RequestHooks;
  cacheStrategy?: CacheStrategy;
  transformer?: (data: any, response: HttpResponse<any>) => any;
  polling?: Partial<PollingConfig>;
  validateResponse?: (data: any) => boolean;
}
FieldTypeDescription
paramsRecord<string, any>Query params (arrays → repeated keys, null/undefined skipped).
headersRecord<string, string>Per-request headers (highest priority).
cacheboolean | Partial<CacheConfig> | {strategy?}Override cache for this request. true = enabled with defaults.
retryboolean | Partial<RetryConfig>false disables retry for this request.
timeoutnumberOverride global timeout (ms).
deduplicatebooleanEnable/disable dedup (default: enabled for GET).
csrfbooleanfalse skips CSRF for this request.
requestIdstringCustom request ID (auto-generated if omitted).
hooksRequestHooksPer-request lifecycle hooks.
cacheStrategyCacheStrategyOverride cache strategy for this request.
transformer(data, response) => anyTransform response data before returning.
pollingPartial<PollingConfig>Polling options (used with poll()).
validateResponse(data: any) => booleanThrow HttpError("Response validation failed") if false.

HttpResponse<T>

The response object returned by every HTTP method.

interface HttpResponse<T> {
  data: T;
  status: number;
  statusText: string;
  headers: Record<string, string>;
  response: Response;       // native Fetch Response
  requestId: string;
  durationMs: number;
}

RetryConfig

interface RetryConfig {
  attempts: number;    // extra attempts after first failure
  strategy: "none" | "linear" | "exponential";
  delay: number;       // initial delay (ms)
  maxDelay: number;    // cap per-retry delay (ms)
  statusCodes: number[];
  shouldRetry?: (error: unknown, attemptNumber: number) => Promise<boolean> | boolean;
}

CacheConfig

interface CacheConfig {
  enabled: boolean;
  ttl: number;           // time-to-live (ms)
  strategy?: CacheStrategy;
  keyBuilder?: (url: string, options: any) => string;
}

CacheStrategy

type CacheStrategy =
  | "cache-only"
  | "network-first"
  | "cache-first"
  | "stale-while-revalidate"
  | "network-only";

CsrfConfig

interface CsrfConfig {
  enabled: boolean;
  fetchEndpoint: string;
  cookieName: string;       // default: "csrf-token"
  headerName: string;       // default: "X-CSRF-Token"
  methods: string[];        // default: ["POST","PUT","PATCH","DELETE"]
  prefetch: boolean;
}

AuthConfig

interface AuthConfig {
  forwardCookies: boolean;
  accessToken?: string;
  scheme: string;           // default: "Bearer"
  getToken?: () => Promise<string | null> | string | null;
}

ObservabilityConfig

interface ObservabilityConfig {
  logger: boolean | CustomLogger;
  tracing: boolean;         // injects x-request-id header
  metrics: boolean;          // collects HttpMetrics
}

CustomLogger

interface CustomLogger {
  debug: (...args: any[]) => void;
  info: (...args: any[]) => void;
  warn: (...args: any[]) => void;
  error: (...args: any[]) => void;
}

CircuitBreakerConfig

interface CircuitBreakerConfig {
  enabled: boolean;
  failureThreshold: number;   // failures before opening
  successThreshold: number;   // successes before closing
  timeout: number;            // ms before half-open
}

RequestPoolConfig

interface RequestPoolConfig {
  enabled: boolean;
  maxConcurrent: number;
  queueLimit?: number;
}

PollingConfig

interface PollingConfig {
  interval: number;               // ms between polls
  maxAttempts?: number;           // max polls before stopping
  stopCondition?: (result: any) => boolean;
}

ETagConfig

interface ETagConfig {
  enabled: boolean;
  storage?: "memory" | "localStorage";
}

RequestHooks

interface RequestHooks {
  onRequest?: (url: string, options: any) => void | Promise<void>;
  onSuccess?: (response: HttpResponse<any>) => void | Promise<void>;
  onError?: (error: any) => void | Promise<void>;
  onFinally?: () => void | Promise<void>;
}

PluginConfig

interface PluginConfig {
  name: string;
  beforeRequest?: (url: string, options: any) => any;
  afterResponse?: (response: HttpResponse<any>) => any;
  onError?: (error: any) => any;
}

HttpMetrics

interface HttpMetrics {
  totalRequests: number;
  successfulRequests: number;
  failedRequests: number;
  durations: number[];
  statusCodes: Record<number, number>;
}

InterceptorManager<T> / InterceptorHandler<T>

interface InterceptorManager<T> {
  use(
    onFulfilled: (value: T) => Promise<T> | T,
    onRejected?: (error: any) => Promise<any> | any,
  ): InterceptorHandler<T>;
  eject(id: number): void;
  clear(): void;
}
 
interface InterceptorHandler<T> {
  id: number;
  eject: () => void;
}
Suggest changes to this page