kinetex - v1.4.0
    Preparing search index...

    Interface KinetexConfig

    Global configuration for a Kinetex client instance.

    interface KinetexConfig {
        baseURL?: string;
        headers?: HeadersInit;
        params?: QueryParams;
        timeout?: number;
        retry?: Partial<RetryConfig>;
        auth?: AuthConfig;
        proxy?: ProxyConfig;
        cache?: CacheConfig;
        logger?: false | LoggerConfig;
        throwOnError?: boolean;
        maxResponseSize?: number;
        maxRequestSize?: number;
        followRedirects?: boolean;
        maxRedirects?: number;
        httpsOnly?: boolean;
        httpVersion?: HTTPVersion;
        sessionPool?: SessionPoolConfig;
        concurrencyLimit?: ConcurrencyLimitConfig;
        fetch?: {
            (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
            (input: string | URL | Request, init?: RequestInit): Promise<Response>;
        };
        dispatcher?: unknown;
        interceptors?: {
            request?: RequestInterceptor[];
            response?: ResponseInterceptor[];
            error?: ErrorInterceptor[];
        };
        hooks?: LifecycleHooks;
        cookieJar?: boolean
        | CookieJar;
        har?: boolean;
        transformResponse?: <T>(
            data: unknown,
            response: KinetexResponse<unknown>,
        ) => T;
        transformRequest?: (
            req: KinetexRequest,
        ) => KinetexRequest<HTTPMethod> | Promise<KinetexRequest<HTTPMethod>>;
        strictHeaders?: boolean;
        rateLimit?: {
            limit?: number;
            windowMs?: number;
            queue?: boolean;
            maxQueue?: number;
        };
        ws?: {
            highWaterMark?: number;
            lowWaterMark?: number;
            maxSendRate?: number;
            keepRooms?: boolean;
        };
        circuitBreakerKeyFn?: (req: KinetexRequest) => string;
        awsSigning?: SigningConfig;
        onPipelineTrace?: (step: PipelineStep) => void;
        onSWRError?: (error: unknown, req: KinetexRequest) => void;
    }
    Index
    baseURL? headers? params? timeout? retry? auth? proxy? cache? logger? throwOnError? maxResponseSize? maxRequestSize? followRedirects? maxRedirects? httpsOnly? httpVersion? sessionPool? concurrencyLimit? fetch? dispatcher? interceptors? hooks? cookieJar? har? transformResponse? transformRequest? strictHeaders? rateLimit? ws? circuitBreakerKeyFn? awsSigning? onPipelineTrace? onSWRError?
    baseURL?: string

    Base URL prepended to all relative request URLs.

    "https://api.example.com/v1"
    headers?: HeadersInit

    Default headers sent with every request.

    params?: QueryParams

    Default query parameters appended to every request URL.

    timeout?: number

    Default request timeout in ms. 0 = no timeout. Default: 30_000

    retry?: Partial<RetryConfig>

    Default retry policy.

    auth?: AuthConfig

    Default authentication.

    proxy?: ProxyConfig

    Proxy configuration.

    cache?: CacheConfig

    HTTP cache configuration.

    logger?: false | LoggerConfig

    Logging configuration.

    throwOnError?: boolean

    Whether to throw on HTTP error status codes (4xx/5xx). Default: true

    maxResponseSize?: number

    Maximum response body size in bytes. 0 = no limit. Default: 0

    maxRequestSize?: number

    Maximum request body size in bytes. 0 = no limit. Default: 0

    followRedirects?: boolean

    Follow redirects. Default: true

    maxRedirects?: number

    Maximum number of redirects to follow. Default: 10

    httpsOnly?: boolean

    Enforce HTTPS-only requests. Rejects HTTP URLs. Default: false

    httpVersion?: HTTPVersion

    Preferred HTTP version. Default: "HTTP/2"

    sessionPool?: SessionPoolConfig

    HTTP/2 session pool tuning. Node.js only, and ignored when a custom fetch is supplied (that forces FetchTransport, which cannot use a session pool). See SessionPoolConfig.

    concurrencyLimit?: ConcurrencyLimitConfig

    Bound how many requests may be in flight at once (a bulkhead).

    Distinct from KinetexConfig.rateLimit, which bounds requests per unit of time and releases its token at dispatch — so rateLimit: 100 per minute still permits 100 simultaneous sockets. A permit here is held for the whole request, including its retries, and returned when it settles.

    const client = kinetex({
      concurrencyLimit: { maxConcurrent: 8 },
    });
    fetch?: {
        (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
        (input: string | URL | Request, init?: RequestInit): Promise<Response>;
    }

    Custom fetch implementation (useful for testing).

    Type Declaration

      • (input: URL | RequestInfo, init?: RequestInit): Promise<Response>

      • MDN Reference

        Parameters

        • input: URL | RequestInfo
        • Optionalinit: RequestInit

        Returns Promise<Response>

      • (input: string | URL | Request, init?: RequestInit): Promise<Response>

      • MDN Reference

        Parameters

        • input: string | URL | Request
        • Optionalinit: RequestInit

        Returns Promise<Response>

    dispatcher?: unknown

    A fetch implementation extension forwarded verbatim to the runtime — most usefully an undici dispatcher (Agent, ProxyAgent, MockAgent), which is the only way to control HTTP/1.1 connection pooling, route through an HTTP(S) proxy, or inject mock responses.

    Typed as unknown to keep kinetex dependency-free. Node's fetch reads init.dispatcher; Deno and Bun ignore it.

    Supplying this forces the fetch transport, since the Node HTTP/2 transport has no notion of a dispatcher — see SessionPoolConfig.

    import { Agent } from "undici";

    const client = kinetex({
      dispatcher: new Agent({ connections: 32, keepAliveTimeout: 10_000 }),
    });
    interceptors?: {
        request?: RequestInterceptor[];
        response?: ResponseInterceptor[];
        error?: ErrorInterceptor[];
    }

    Interceptors registered at construction time.

    Type Declaration

    • Optionalrequest?: RequestInterceptor[]

      Request interceptors run before the request is sent.

    • Optionalresponse?: ResponseInterceptor[]

      Response interceptors run after the response is received.

    • Optionalerror?: ErrorInterceptor[]

      Error interceptors run when an error occurs in the pipeline.

    hooks?: LifecycleHooks

    Lifecycle hooks registered at construction time.

    cookieJar?: boolean | CookieJar

    Cookie jar instance. Pass true to auto-create one, or a pre-existing instance.

    har?: boolean

    HAR recording. Pass true to enable with defaults.

    transformResponse?: <T>(data: unknown, response: KinetexResponse<unknown>) => T

    Global response transform applied after parsing.

    transformRequest?: (
        req: KinetexRequest,
    ) => KinetexRequest<HTTPMethod> | Promise<KinetexRequest<HTTPMethod>>

    Global request transform applied before sending.

    strictHeaders?: boolean

    Enforce strict header validation.

    When true, requests with invalid header names or values throw a KinetexError with code "EVALIDATION" instead of silently dropping the offending header. Recommended for production services where silent data loss is unacceptable.

    Default: false — emit console.warn and drop.

    Architecture Risk C: Silent Header Dropping

    rateLimit?: {
        limit?: number;
        windowMs?: number;
        queue?: boolean;
        maxQueue?: number;
    }

    Built-in token-bucket rate limiter applied to all outgoing requests.

    Registered automatically as the highest-priority request interceptor so it runs before auth, cache, and dedup.

    Type Declaration

    • Optionallimit?: number

      Maximum requests per window. Default: 60

    • OptionalwindowMs?: number

      Window size in ms. Default: 60_000 (1 minute)

    • Optionalqueue?: boolean

      If true, queue excess requests; if false, reject immediately. Default: true

    • OptionalmaxQueue?: number

      Max number of queued requests before rejecting. Default: 100

    const client = kinetex({
      rateLimit: { limit: 100, windowMs: 60_000 }, // 100 req/min
    });

    Enterprise Hardening #6: Centralized Rate Limit Enforcer

    ws?: {
        highWaterMark?: number;
        lowWaterMark?: number;
        maxSendRate?: number;
        keepRooms?: boolean;
    }

    Default WebSocket client configuration inherited by client.ws(). These values are merged with per-call options.

    Type Declaration

    • OptionalhighWaterMark?: number

      High-water mark in bytes for backpressure. Default: 65536

    • OptionallowWaterMark?: number

      Low-water mark in bytes for backpressure release. Default: 16384

    • OptionalmaxSendRate?: number

      Max outbound messages per second (0 = unlimited). Default: 0

    • OptionalkeepRooms?: boolean

      Automatically re-join subscribed rooms after reconnect. Default: true

    circuitBreakerKeyFn?: (req: KinetexRequest) => string

    Custom function to compute the circuit-breaker key for a request.

    Default behavior: key = request origin (https://api.example.com). Override to scope breakers per-method, per-route, or per-tenant.

    const client = kinetex({
      circuitBreakerKeyFn: (req) =>
        `${new URL(req.url).origin}:${req.method}`,
    });

    Enterprise Hardening #2: Circuit Breaker Per-Method

    awsSigning?: SigningConfig

    AWS SigV4 request signing applied automatically to every outgoing request.

    When set, a SigV4Signer is registered as a request interceptor that signs headers (Authorization, x-amz-date, x-amz-content-sha256) before the request is sent. Compatible with all AWS services and API Gateway.

    const client = kinetex({
      baseURL: "https://execute-api.us-east-1.amazonaws.com",
      awsSigning: {
        credentials: { accessKeyId: "...", secretAccessKey: "..." },
        region: "us-east-1",
        service: "execute-api",
      },
    });

    Enterprise Hardening #3: Optional Request Signing

    onPipelineTrace?: (step: PipelineStep) => void

    Pipeline trace callback — called at the start and end of each pipeline stage for every request.

    Use this for detailed observability without adding interceptors: structured logging, distributed tracing, or performance profiling.

    The callback is synchronous and must not throw.

    const client = kinetex({
      onPipelineTrace: (step) => {
        tracer.addEvent(step.stage, { elapsedMs: step.elapsedMs });
      },
    });

    Architecture Risk A: Unclear Responsibility Separation

    onSWRError?: (error: unknown, req: KinetexRequest) => void

    Called when a background stale-while-revalidate (SWR) fetch fails.

    Without this callback, SWR revalidation errors are silently swallowed and stale data continues to be served. Use this hook to monitor revalidation health, increment error counters, or trigger alerts.

    Type Declaration

      • (error: unknown, req: KinetexRequest): void

      • Parameters

        • error: unknown

          The error that caused the revalidation to fail.

        • req: KinetexRequest

          The request that was being revalidated.

        Returns void

    const client = kinetex({
      cache: { ... },
      onSWRError: (err, req) => {
        metrics.increment("cache.swr_error");
        logger.warn("SWR revalidation failed", { url: req.url, error: err });
      },
    });

    Settings
    Member Visibility

    On This Page
    Properties