kinetex - v1.0.0-rc.1
    Preparing search index...

    Class Kinetex

    The main HTTP client class.

    import { kinetex } from "kinetex";

    const client = kinetex({ baseURL: "https://api.example.com" });

    // Fluent chain
    const user = await client.get("/users/1").json<User>();

    // Standard send
    const res = await client.send<User>({ url: "/users/1", method: "GET" });
    Index

    Constructors

    constructor

    Accessors

    dedupMetrics circuitSnapshots

    Methods

    useRequest attachHookRegistry useResponse useError getHAR clearHAR getCache getCookieJar extend setTracer enableDedup disableDedup enableCircuitBreaker disableCircuitBreaker tripCircuit resetCircuit ws send get post put patch delete head options request GET POST PUT PATCH DELETE sse graphql paginate destroy

    Constructors

    Accessors

    • get dedupMetrics(): | { hits: number; misses: number; inFlightCount: number }
      | null

      Returns deduplication metrics.

      Returns { hits: number; misses: number; inFlightCount: number } | null

      An object with hits (coalesced request count), misses (actual network request count), and inFlightCount (currently in-flight requests), or null if dedup is not enabled.

      • { hits: number; misses: number; inFlightCount: number }
        • hits: number

          Number of requests that shared an in-flight or windowed response.

        • misses: number

          Number of requests that triggered a real network call.

        • inFlightCount: number

          Number of currently in-flight requests.

      • null

    Methods

    • Attach a HookRegistry (from lifecycle.ts) to this client.

      The registry's beforeRequest hooks run as request interceptors and its onError hooks run as error interceptors, so the full priority / once / conditional system from lifecycle.ts is available alongside kinetex's native interceptor API.

      Parameters

      Returns () => void

      A single eject function that removes all three bridge interceptors.

      import { HookRegistry, createLoggingHooks } from "kinetex/lifecycle";

      const registry = new HookRegistry();
      const { beforeRequest, afterResponse, onError } = createLoggingHooks();
      registry.addBeforeRequest(beforeRequest);
      registry.addAfterResponse(afterResponse);
      registry.addOnError(onError);

      const client = kinetex({ baseURL: "https://api.example.com" });
      client.attachHookRegistry(registry);

    • Get the recorded HAR log.

      Returns HARLog

      The full HAR log object.

      If HAR recording was not enabled in config.

    • Access the underlying cache instance. Returns null if no cache is configured. Protected by initialization lock to prevent concurrent creation.

      Returns Promise<HTTPCache | null>

      The cache instance, or null if not configured.

    • Access the cookie jar instance. Returns null if no cookie jar is configured. Protected by initialization lock to prevent concurrent creation.

      Returns Promise<CookieJar | null>

      The cookie jar, or null if not configured.

    • Set an OpenTelemetry-compatible tracer. When set, kinetex automatically injects traceparent and tracestate headers (W3C Trace Context) into every outgoing request, and creates a child span for each request with standard HTTP semantic attributes.

      Parameters

      Returns this

      This instance for chaining.

      import { trace } from "@opentelemetry/api";
      const client = kinetex({ baseURL: "https://api.example.com" });
      client.setTracer(trace.getTracer("my-service"));

    • Enable in-flight request deduplication.

      When multiple concurrent requests target the same URL with the same method, they are coalesced into a single network call. All callers receive the same response object once the request completes.

      Only applies to safe methods (GET and HEAD by default).

      Parameters

      Returns this

      This instance for chaining.

      const client = kinetex({ baseURL: "https://api.example.com" });
      client.enableDedup({ windowMs: 50 }); // also dedupe for 50ms after completion

      // These three calls make exactly ONE network request:
      const [a, b, c] = await Promise.all([
        client.get("/users"),
        client.get("/users"),
        client.get("/users"),
      ]);

    • Disable in-flight request deduplication.

      Returns this

      This instance for chaining.

    • Enable circuit breaker protection.

      The circuit breaker tracks failures per origin. When failures exceed the threshold, the circuit opens and requests are rejected immediately with a CircuitOpenError — preventing cascading failures to struggling services.

      Parameters

      Returns this

      This instance for chaining.

      const client = kinetex({ baseURL: "https://api.example.com" });
      client.enableCircuitBreaker({
        failureThreshold: 5,
        resetTimeoutMs:   15_000,
        onOpen:  (s) => logger.warn("Circuit opened", s),
        onClose: (s) => logger.info("Circuit recovered", s),
      });

    • Disable circuit breaker protection.

      Returns this

      This instance for chaining.

    • Manually trip the circuit breaker for a given origin. Useful during maintenance windows.

      Parameters

      • origin: string

      Returns this

      This instance for chaining.

    • Manually reset the circuit breaker for a given origin.

      Parameters

      • origin: string

      Returns this

      This instance for chaining.

    • Open a WebSocket connection that inherits this client's headers and auth.

      Parameters

      • url: string

        WebSocket endpoint URL (ws:// or wss://).

      • options: Partial<WSClientConfig> = {}

        WebSocket client configuration overrides.

      Returns Promise<WSClient>

      A connected WSClient instance.

      const ws = await client.ws("wss://api.example.com/live", {
        onMessage: (msg) => console.log(msg.json),
      });
      ws.sendJSON({ type: "subscribe", channel: "prices" });
      for await (const msg of ws) {
        console.log(msg.data);
      }

    • Execute an HTTP request.

      This is the lowest-level public method. All convenience helpers (get, post, etc.) delegate to this.

      Type Parameters

      • T = unknown

        Expected parsed response body type.

      Parameters

      • url: string

        Request URL (relative to baseURL or absolute).

      • method: HTTPMethod

        HTTP method.

      • options: SendOptions<T> = {}

        Per-request options.

      Returns Promise<KinetexResponse<T>>

      A promise resolving to the parsed response.

    post

    POST

    • Open a Server-Sent Events stream.

      Parameters

      • url: string

        SSE endpoint URL.

      • options: Partial<SSEClientConfig> = {}

        SSE client configuration overrides.

      Returns Promise<SSEClient>

      An SSEClient instance connected via the full kinetex pipeline.

    • Create a page-based paginator.

      Type Parameters

      • T

      Parameters

      • url: string

        API endpoint URL.

      • options: Omit<PagePaginationOptions, "url" | "fetch">

        Paginator configuration.

      Returns Promise<AsyncGenerator<Page<T>, any, any>>

      An async generator yielding pages.

    • Clean up all resources held by this client instance. Call this when the client is no longer needed to prevent memory leaks.

      Returns Promise<void>

      A promise that resolves when cleanup is complete.

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods