Core Concepts

BoltFetch is built around a few fundamental paradigms designed to make network requests predictable, type-safe, and enjoyable.

1. The "No Exceptions" Paradigm

The most defining feature of BoltFetch is its approach to error handling. Standard fetch (and libraries like axios) rely heavily on throwing exceptions. This forces developers into defensive programming, scattering try/catch blocks throughout their codebase, making the control flow hard to follow and errors difficult to type.

BoltFetch borrows from modern language patterns: Expected failures are values, not exceptions.

The Old Way: Defensive Try/Catch

In traditional setups, a network request could throw for multiple reasons.

typescript
COPY
// ❌ The old, fragmented way
async function fetchUserData(userId: string) {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) {
      throw new Error("HTTP error " + response.status);
    }
    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Failed to fetch user", error);
    return null;
  }
}

The BoltFetch Way: Result Objects

BoltFetch encapsulates every outcome—success or failure—into a predictable, strongly-typed result object.

typescript
COPY
// ✅ The BoltFetch way
import { boltfetch } from "boltfetch";

async function fetchUserData(userId: string) {
  const response = await boltfetch.get<User>(`/api/users/${userId}`);

  // Checking success narrows the type of the response object
  if (!response.success) {
    // Control flow is linear. 'response' is strongly typed as BoltFetchError.
    console.error(`Failed: [${response.status}] ${response.message}`);
    return null;
  }

  // If success is true, TypeScript knows 'data' is available and matches <User>.
  return response.data;
}

2. End-to-End Type Safety

BoltFetch treats TypeScript as a first-class citizen.

When you pass a generic type to a request method (boltfetch.get<MyType>(...)), BoltFetch links that type directly to the data property of the BoltFetchResponse object. Because of discriminated unions, checking if (!response.success) automatically narrows the type so that data is guaranteed to be available in the success branch.

3. Native Fetch Under the Hood

BoltFetch is completely dependency-free. It is a thin, intelligent wrapper over the native Web fetch API.

• Minimal Overhead: It adds virtually zero bloat to your application.
• Universal Compatibility: It works natively in modern Browsers, Node.js (18+), Deno, Bun, and Edge environments (like Cloudflare Workers) without polyfills.

4. Query Parameter Serialization

BoltFetch makes it incredibly easy to append query strings to your URLs via the params configuration object. It automatically serializes numbers, booleans, and strings into a clean query string.

typescript
COPY
const response = await boltfetch.get('/users', {
  params: {
    role: 'admin',
    active: true,
    page: 2
  }
});
// Results in: GET /users?role=admin&active=true&page=2