Architecture Overview

BoltFetch is engineered around a Pipeline Pattern, ensuring that every HTTP request and response flows through a predictable, observable, and interceptable sequence of steps. This architecture is what enables global configuration, automatic retries, and seamless error handling without cluttering your business logic.

The Request Lifecycle Pipeline

Below is a detailed representation of the exact flow a request takes from the moment you call client.get() to the moment you receive a BoltFetchResponse.

mermaid
COPY
flowchart TD
  subgraph Application Logic
    A[Developer calls client.get]
    Z[Receive BoltFetchResponse]
  end

  subgraph Request Phase
    B[Build Base Config & Headers]
    C{Global Request Interceptors}
    D[Apply Interceptor Mutations]
  end

  subgraph Network Execution Phase
    E[Native fetch Execution]
    F{Network Connectivity?}
    G{Automatic Retries Enabled?}
    H[Wait Exponential Backoff]
  end

  subgraph Response Phase
    I[Receive Response Stream]
    J{Is Response OK? 2xx/3xx}
    K[Parse JSON / Text]
    L[Parse Error Body]
    M{Global Response Interceptors}
    N[Package BoltFetchError]
    O[Package Success Data]
  end

  A --> B
  B --> C
  C -->|Modify Request| D
  C -->|Bypass| D
  D --> E
  
  E --> F
  F -- No --> G
  G -- Yes --> H
  H --> E
  G -- No --> N
  
  F -- Yes --> I
  I --> J
  
  J -- Yes --> K
  K --> M
  M --> O
  O --> Z
  
  J -- No --> L
  L --> M
  M --> N
  N --> Z

Native Web API Foundation

Unlike older libraries built on XMLHttpRequest (XHR) or Node's internal http module, BoltFetch is constructed entirely on top of the modern, native Web fetch API.

Why Native Fetch?

1. Environment Agnostic: The fetch API is now the standard across all modern JavaScript runtimes. By utilizing it directly, BoltFetch guarantees identical behavior whether it is running in Google Chrome, a Node.js 20 backend, a Bun server, or a Cloudflare Edge Worker.
2. Stream Processing: Native fetch utilizes ReadableStream under the hood. While BoltFetch primarily deals with JSON payloads out of the box, building on native fetch ensures that advanced use cases involving raw streams and buffers are possible and performant.
3. Non-Blocking IO: Because it leverages the native asynchronous I/O of the underlying V8 engine, BoltFetch will not block the main thread. It creates excellent continuous event loop operations, vital for high-throughput backend servers.

Immutability & State

BoltFetch instances are largely stateless beyond their initial configuration (baseUrl, defaultHeaders).

When a request is initiated, BoltFetch creates a localized Request context. Even when interceptors modify the request, they are modifying a cloned configuration object for that specific request lifecycle, preventing state leakage or race conditions during high-concurrency parallel requests.