httix-http 1.0.0

package/dist/cjs/plugins/index.d.cts

@@ -0,0 +1,154 @@
+import { r as HttixPlugin, f as HttixRequestConfig, H as HttixClient } from '../types-DkChbb42.cjs';
+
+/**
+ * httix — Logger plugin
+ *
+ * Logs request and response lifecycle events via configurable log levels.
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+interface LoggerPluginConfig {
+    /** Minimum log level (default: 'info') */
+    level?: LogLevel;
+    /** Custom logger function (default: console) */
+    logger?: {
+        debug: (...args: unknown[]) => void;
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+    /** Whether to log request body (default: false) */
+    logRequestBody?: boolean;
+    /** Whether to log response body (default: false) */
+    logResponseBody?: boolean;
+    /** Whether to log request headers (default: false) */
+    logRequestHeaders?: boolean;
+    /** Whether to log response headers (default: false) */
+    logResponseHeaders?: boolean;
+}
+declare function loggerPlugin(config?: LoggerPluginConfig): HttixPlugin;
+
+/**
+ * httix — Cache plugin
+ *
+ * LRU response cache with configurable TTL, size, stale-while-revalidate,
+ * and per-method caching control.
+ */
+
+interface CachePluginConfig {
+    /** Maximum cache entries (default: 100) */
+    maxSize?: number;
+    /** TTL in ms (default: 300000 = 5 minutes) */
+    ttl?: number;
+    /** Whether to enable stale-while-revalidate (default: false) */
+    staleWhileRevalidate?: boolean;
+    /** SWR window in ms (default: 60000 = 1 minute) */
+    swrWindow?: number;
+    /** Custom cache key function */
+    generateKey?: (config: HttixRequestConfig) => string;
+    /** Which methods to cache (default: ['GET']) */
+    methods?: string[];
+    /** Whether to respect Cache-Control headers (default: true) */
+    respectCacheControl?: boolean;
+}
+interface CacheEntry<T = unknown> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    timing: number;
+    timestamp: number;
+    config: HttixRequestConfig;
+    raw: Response;
+}
+declare class LRUCache<T = unknown> {
+    private cache;
+    private maxSize;
+    private ttl;
+    constructor(maxSize?: number, ttl?: number);
+    get(key: string): CacheEntry<T> | undefined;
+    /**
+     * Retrieve an entry even if it has expired (TTL exceeded).
+     * Returns undefined only when the key does not exist at all.
+     */
+    getAllowingStale(key: string): CacheEntry<T> | undefined;
+    set(key: string, entry: CacheEntry<T>): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    keys(): string[];
+}
+declare function cachePlugin(config?: CachePluginConfig): HttixPlugin & {
+    cache: LRUCache;
+    invalidate: (key?: string) => void;
+    invalidatePattern: (pattern: RegExp) => void;
+    clear: () => void;
+    getStats: () => {
+        size: number;
+        maxSize: number;
+        ttl: number;
+    };
+};
+
+/**
+ * httix — Mock plugin
+ *
+ * Replaces the global fetch with an in-memory mock adapter so tests can
+ * define request handlers and verify request history without hitting real
+ * endpoints.
+ */
+
+interface MockHistoryEntry {
+    method: string;
+    url: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    config: HttixRequestConfig;
+}
+declare class MockAdapter {
+    private handlers;
+    private history;
+    private originalFetch;
+    private isActive;
+    /** Activate the mock — replace global fetch. */
+    activate(_client: HttixClient): void;
+    /** Deactivate — restore the original fetch. */
+    deactivate(): void;
+    /** Internal mock fetch implementation. */
+    private mockFetch;
+    onGet(url: string | RegExp): {
+        reply: (status: number, data: unknown, headers?: Record<string, string>) => MockAdapter;
+    };
+    onPost(url: string | RegExp): {
+        reply: (status: number, data: unknown, headers?: Record<string, string>) => MockAdapter;
+    };
+    onPut(url: string | RegExp): {
+        reply: (status: number, data: unknown, headers?: Record<string, string>) => MockAdapter;
+    };
+    onPatch(url: string | RegExp): {
+        reply: (status: number, data: unknown, headers?: Record<string, string>) => MockAdapter;
+    };
+    onDelete(url: string | RegExp): {
+        reply: (status: number, data: unknown, headers?: Record<string, string>) => MockAdapter;
+    };
+    private on;
+    /** Access recorded request history. */
+    getHistory(): Record<string, MockHistoryEntry[]>;
+    /** Clear all handlers and history (adapter stays active). */
+    reset(): void;
+    /** Fully deactivate and reset. */
+    restore(): void;
+}
+declare function mockPlugin(): HttixPlugin & {
+    adapter: MockAdapter;
+    onGet: MockAdapter['onGet'];
+    onPost: MockAdapter['onPost'];
+    onPut: MockAdapter['onPut'];
+    onPatch: MockAdapter['onPatch'];
+    onDelete: MockAdapter['onDelete'];
+    getHistory: () => Record<string, MockHistoryEntry[]>;
+    restore: () => void;
+};
+
+export { type CachePluginConfig, LRUCache, type LogLevel, type LoggerPluginConfig, MockAdapter, type MockHistoryEntry, cachePlugin, loggerPlugin, mockPlugin };

package/dist/cjs/types-DkChbb42.d.cts

@@ -0,0 +1,340 @@
+/**
+ * httix — Error class hierarchy
+ */
+
+/**
+ * Base error class for all httix errors.
+ */
+declare class HttixError extends Error {
+    readonly name: string;
+    readonly config?: HttixRequestConfig;
+    readonly cause?: Error;
+    constructor(message: string, options?: HttixErrorOptions);
+}
+/**
+ * Error thrown when a network-level request failure occurs
+ * (e.g., DNS failure, connection refused, CORS error).
+ */
+declare class HttixRequestError extends HttixError {
+    readonly name: string;
+    constructor(message: string, options?: HttixErrorOptions);
+}
+/**
+ * Error thrown when the server responds with a 4xx or 5xx status code.
+ */
+declare class HttixResponseError extends HttixError {
+    readonly name: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly data: unknown;
+    readonly headers?: Headers;
+    readonly config?: HttixRequestConfig;
+    constructor(status: number, statusText: string, data: unknown, headers?: Headers, config?: HttixRequestConfig);
+}
+/**
+ * Error thrown when a request exceeds its configured timeout.
+ */
+declare class HttixTimeoutError extends HttixError {
+    readonly name: string;
+    readonly timeout: number;
+    constructor(timeout: number, config?: HttixRequestConfig);
+}
+/**
+ * Error thrown when a request is cancelled via AbortController.
+ */
+declare class HttixAbortError extends HttixError {
+    readonly name: string;
+    readonly reason: string;
+    constructor(reason?: string, config?: HttixRequestConfig);
+}
+/**
+ * Error thrown when all retry attempts have been exhausted.
+ */
+declare class HttixRetryError extends HttixError {
+    readonly name: string;
+    readonly attempts: number;
+    readonly lastError: HttixError;
+    constructor(attempts: number, lastError: HttixError, config?: HttixRequestConfig);
+}
+
+/**
+ * httix — Core TypeScript types and interfaces
+ */
+
+/** Supported HTTP methods */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** Body types that can be sent in a request */
+type RequestBody = string | number | boolean | null | Record<string, unknown> | unknown[] | FormData | URLSearchParams | Blob | ArrayBuffer | ReadableStream<Uint8Array> | undefined;
+/** Query parameter value types */
+type QueryParamValue = string | number | boolean | null | undefined;
+/** Query parameters object */
+type QueryParams = Record<string, QueryParamValue | QueryParamValue[]>;
+/** Path parameters for URL interpolation */
+type PathParams = Record<string, string | number>;
+/** Headers representation */
+type HttixHeaders = Record<string, string> | Headers;
+/** Backoff strategy for retry */
+type BackoffStrategy = 'fixed' | 'linear' | 'exponential';
+/** Rate limit configuration */
+interface RateLimitConfig {
+    /** Maximum number of requests per interval */
+    maxRequests: number;
+    /** Interval in milliseconds */
+    interval: number;
+}
+/** Dedup configuration */
+interface DedupConfig {
+    /** Enable request deduplication */
+    enabled: boolean;
+    /** Custom key generation function */
+    generateKey?: (config: HttixRequestConfig) => string;
+    /** TTL for dedup cache in ms (default: 0 = only dedup in-flight) */
+    ttl?: number;
+}
+/** Retry configuration */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    attempts?: number;
+    /** Backoff strategy (default: 'exponential') */
+    backoff?: BackoffStrategy;
+    /** Base delay in ms (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelay?: number;
+    /** Add jitter to delay (default: true) */
+    jitter?: boolean;
+    /** HTTP status codes to retry on (default: [408, 429, 500, 502, 503, 504]) */
+    retryOn?: number[];
+    /** Whether to retry on network errors (default: true) */
+    retryOnNetworkError?: boolean;
+    /** Custom retry condition function */
+    retryCondition?: (error: HttixError) => boolean;
+    /** Whether to retry on POST/PUT/PATCH (default: false) */
+    retryOnSafeMethodsOnly?: boolean;
+    /** Callback called before each retry */
+    onRetry?: (attempt: number, error: HttixError, delay: number) => void;
+}
+/** Authentication configuration */
+type AuthConfig = BearerAuthConfig | BasicAuthConfig | ApiKeyAuthConfig;
+interface BearerAuthConfig {
+    type: 'bearer';
+    /** Static token or a function that returns a token */
+    token: string | (() => string | Promise<string>);
+    /** Function to refresh the token when a 401 is received */
+    refreshToken?: () => Promise<string>;
+    /** Callback to store a refreshed token */
+    onTokenRefresh?: (token: string) => void;
+}
+interface BasicAuthConfig {
+    type: 'basic';
+    username: string;
+    password: string;
+}
+interface ApiKeyAuthConfig {
+    type: 'apiKey';
+    /** Header name (e.g., "X-API-Key") */
+    key: string;
+    /** API key value */
+    value: string | (() => string | Promise<string>);
+    /** Where to place the API key */
+    in: 'header' | 'query';
+}
+/** Pagination style */
+type PaginationStyle = 'offset' | 'cursor' | 'link';
+/** Pagination configuration */
+interface PaginationConfig<T = unknown> {
+    /** Pagination style */
+    style: PaginationStyle;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Maximum number of pages to fetch (default: Infinity) */
+    maxPages?: number;
+    /** For offset style: query param names for offset and limit */
+    offsetParam?: string;
+    /** For offset style: query param name for limit */
+    limitParam?: string;
+    /** For cursor style: query param name for cursor */
+    cursorParam?: string;
+    /** For cursor style: extractor for next cursor from response */
+    cursorExtractor?: (data: T) => string | null | undefined;
+    /** For link style: extractor for next URL from Link header */
+    linkExtractor?: (headers: Headers) => string | null | undefined;
+    /** Response wrapper — extract the array from the response data */
+    dataExtractor?: (data: T) => T[];
+    /** Stop condition */
+    stopCondition?: (data: T) => boolean;
+}
+/** Download progress info */
+interface DownloadProgress {
+    loaded: number;
+    total?: number;
+    percent: number;
+}
+/** SSE event */
+interface SSEEvent {
+    type: string;
+    data: string;
+    id?: string;
+    retry?: number;
+}
+/** Stream configuration */
+interface StreamConfig {
+    /** SSE parser */
+    sse?: boolean;
+    /** NDJSON parser */
+    ndjson?: boolean;
+    /** Called for each chunk received */
+    onChunk?: (chunk: Uint8Array, index: number) => void;
+}
+/** Middleware context */
+interface MiddlewareContext<Req = HttixRequestConfig, Res = HttixResponse<unknown>> {
+    request: Req;
+    response?: Res;
+}
+/** Middleware function */
+type MiddlewareFn<T = unknown, Req = HttixRequestConfig, Res = HttixResponse<T>> = (ctx: MiddlewareContext<Req, Res>, next: () => Promise<void>) => Promise<void>;
+/** Interceptor functions */
+type RequestInterceptor = (config: HttixRequestConfig) => HttixRequestConfig | Promise<HttixRequestConfig>;
+type RequestErrorInterceptor = (error: HttixError) => HttixRequestConfig | Promise<HttixRequestConfig> | void;
+type ResponseInterceptor<T = unknown> = (response: HttixResponse<T>) => HttixResponse<T> | Promise<HttixResponse<T>>;
+type ResponseErrorInterceptor = (error: HttixError) => HttixResponse<unknown> | Promise<HttixResponse<unknown>> | void;
+/** Interceptor handler with id */
+interface InterceptorHandler<F, E> {
+    fulfilled: F;
+    rejected?: E;
+}
+/** Interceptor manager */
+interface InterceptorManager<F, E> {
+    handlers: InterceptorHandler<F, E>[];
+    use(fulfilled: F, rejected?: E): number;
+    eject(id: number): void;
+    clear(): void;
+}
+/** Full client configuration */
+interface HttixConfig extends HttixRequestConfig {
+    /** Enable request deduplication (default: false) */
+    dedup?: boolean | DedupConfig;
+    /** Rate limiting configuration */
+    rateLimit?: RateLimitConfig;
+    /** Authentication configuration */
+    auth?: AuthConfig;
+    /** Middleware functions */
+    middleware?: MiddlewareFn[];
+}
+/** Per-request configuration */
+interface HttixRequestConfig {
+    /** Request URL (relative or absolute) */
+    url: string;
+    /** HTTP method (default: 'GET') */
+    method?: HttpMethod;
+    /** Base URL for this request */
+    baseURL?: string;
+    /** Request headers */
+    headers?: HttixHeaders;
+    /** Request body */
+    body?: RequestBody;
+    /** Query parameters */
+    query?: QueryParams;
+    /** Path parameters for URL interpolation */
+    params?: PathParams;
+    /** Request timeout in ms (0 = no timeout) */
+    timeout?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Retry configuration for this request */
+    retry?: RetryConfig | false;
+    /** Response type override */
+    responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer';
+    /** Custom response type parser */
+    parseResponse?: (response: Response) => Promise<unknown>;
+    /** Download progress callback */
+    onDownloadProgress?: (progress: DownloadProgress) => void;
+    /** Stream configuration */
+    stream?: StreamConfig;
+    /** Custom request credentials mode */
+    credentials?: RequestCredentials;
+    /** Custom request mode */
+    mode?: RequestMode;
+    /** Custom cache mode */
+    cache?: RequestCache;
+    /** Custom redirect mode */
+    redirect?: RequestRedirect;
+    /** Custom referrer policy */
+    referrerPolicy?: ReferrerPolicy;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Whether to throw on non-2xx status (default: true) */
+    throwOnError?: boolean;
+}
+/** Httix response wrapper */
+interface HttixResponse<T = unknown> {
+    /** Parsed response body */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Headers;
+    /** Whether the status is 2xx */
+    ok: boolean;
+    /** Original Fetch Response object */
+    raw: Response;
+    /** Request duration in ms */
+    timing: number;
+    /** The request config that produced this response */
+    config: HttixRequestConfig;
+}
+/** Base error class for all httix errors */
+interface HttixErrorOptions {
+    message: string;
+    config?: HttixRequestConfig;
+    cause?: Error;
+}
+/** Plugin interface */
+interface HttixPlugin {
+    /** Plugin name */
+    name: string;
+    /** Install hook — called when plugin is registered */
+    install: (client: HttixClient) => void;
+    /** Cleanup hook — called when plugin is removed */
+    cleanup?: () => void;
+}
+/** HttixClient interface */
+interface HttixClient {
+    /** Default configuration */
+    defaults: HttixConfig;
+    /** Request interceptors */
+    interceptors: {
+        request: InterceptorManager<RequestInterceptor, RequestErrorInterceptor>;
+        response: InterceptorManager<ResponseInterceptor<unknown>, ResponseErrorInterceptor>;
+    };
+    /** HTTP methods */
+    get<T = unknown>(url: string, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<T>>;
+    post<T = unknown>(url: string, body?: RequestBody, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<T>>;
+    put<T = unknown>(url: string, body?: RequestBody, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<T>>;
+    patch<T = unknown>(url: string, body?: RequestBody, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<T>>;
+    delete<T = unknown>(url: string, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<T>>;
+    head(url: string, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<void>>;
+    options(url: string, config?: Partial<HttixRequestConfig>): Promise<HttixResponse<void>>;
+    request<T = unknown>(config: HttixRequestConfig): Promise<HttixResponse<T>>;
+    /** Stream support */
+    stream: {
+        sse(url: string, config?: Partial<HttixRequestConfig>): AsyncIterable<SSEEvent>;
+        ndjson<T = unknown>(url: string, config?: Partial<HttixRequestConfig>): AsyncIterable<T>;
+    };
+    /** Pagination */
+    paginate<T = unknown>(url: string, config?: Partial<HttixRequestConfig> & {
+        pagination?: PaginationConfig<T>;
+    }): AsyncIterable<T[]>;
+    /** Middleware registration */
+    use<T = unknown>(middleware: MiddlewareFn<T>): void;
+    /** Clone client with overrides */
+    create(overrides?: Partial<HttixConfig>): HttixClient;
+    /** Cancel all pending requests */
+    cancelAll(reason?: string): void;
+    /** Check if error is a cancellation error */
+    isCancel(error: unknown): error is HttixAbortError;
+}
+
+export { type AuthConfig as A, type BearerAuthConfig as B, type RateLimitConfig as C, type DownloadProgress as D, type StreamConfig as E, type HttixClient as H, type InterceptorManager as I, type MiddlewareFn as M, type PaginationConfig as P, type QueryParamValue as Q, type RequestInterceptor as R, type SSEEvent as S, type InterceptorHandler as a, type HttixConfig as b, type RequestErrorInterceptor as c, type ResponseInterceptor as d, type ResponseErrorInterceptor as e, type HttixRequestConfig as f, type HttixResponse as g, type RequestBody as h, HttixAbortError as i, type RetryConfig as j, type MiddlewareContext as k, type ApiKeyAuthConfig as l, type BackoffStrategy as m, type BasicAuthConfig as n, type DedupConfig as o, HttixError as p, type HttixHeaders as q, type HttixPlugin as r, HttixRequestError as s, HttixResponseError as t, HttixRetryError as u, HttixTimeoutError as v, type HttpMethod as w, type PaginationStyle as x, type PathParams as y, type QueryParams as z };