httix-http 1.0.0

package/dist/esm/types-DkChbb42.d.ts

@@ -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 };

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "httix-http",
+  "version": "1.0.0",
+  "description": "Ultra-lightweight, type-safe, zero-dependency HTTP client built on native Fetch — modern axios replacement.",
+  "author": "Avinashvelu03 <avinashvelu03@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Avinashvelu03/httix"
+  },
+  "homepage": "https://github.com/Avinashvelu03/httix#readme",
+  "bugs": {
+    "url": "https://github.com/Avinashvelu03/httix/issues"
+  },
+  "keywords": [
+    "http",
+    "client",
+    "fetch",
+    "request",
+    "ajax",
+    "api",
+    "rest",
+    "axios",
+    "got",
+    "ky",
+    "http-client",
+    "fetch-wrapper",
+    "typescript",
+    "type-safe",
+    "zero-dependency",
+    "lightweight",
+    "interceptors",
+    "retry",
+    "timeout",
+    "abort",
+    "streaming",
+    "sse",
+    "ndjson",
+    "rate-limit",
+    "dedup",
+    "cache",
+    "pagination",
+    "middleware",
+    "auth",
+    "bearer",
+    "api-key",
+    "universal",
+    "node",
+    "browser",
+    "edge",
+    "deno",
+    "bun",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./plugins": {
+      "import": {
+        "types": "./dist/esm/plugins/index.d.ts",
+        "default": "./dist/esm/plugins/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/plugins/index.d.cts",
+        "default": "./dist/cjs/plugins/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ tests/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "audit": "npm run lint && npm run typecheck && npm run test:coverage && npm run build",
+    "prepublishOnly": "npm run audit",
+    "clean": "rm -rf dist coverage",
+    "benchmark": "vitest run tests/benchmarks/"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "eslint": "^9.16.0",
+    "globals": "^17.4.0",
+    "prettier": "^3.4.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}