up-fetch Documentation

upfetch is compatible with the following environments:

• Browsers (Chrome, Firefox, Safari, Edge)
• Node.js (18.0+)
• Bun
• Deno
• Cloudflare Workers
• Vercel Edge Runtime

up-fetch is compatible with a wide range of JavaScript/TypeScript runtimes, including browsers and modern server-side environments. It supports:

• Browsers: Chrome, Firefox, Safari, Edge
• Runtimes:
  • Node.js (version 18.0 or higher)
  • Bun
  • Deno
• Edge Runtimes:
  • Cloudflare Workers
  • Vercel Edge Runtime

Timeouts in up-fetch are applied per attempt. If you have multiple retries configured, the timeout duration applies to each individual request attempt rather than the total duration of all attempts combined.

When using withTimeout(), the library combines the provided signal and timeout using AbortSignal.any (on runtimes that support it). Note that AbortError and TimeoutError are treated as distinct error types.

By default, up-fetch handles responses as follows:

• Success responses: Attempts to parse as JSON first, then as text. If both fail, it returns null.
• Rejected responses: These are wrapped in a ResponseError.

The reject(response) function determines whether the library executes parseRejected or parseResponse for a given response.

The upfetch library uses a factory pattern to create reusable clients. The core mental model consists of three parts:

1. Client Creation: up(fetchFn, getDefaultOptions?) creates a reusable client instance.
2. Default Options Factory: The getDefaultOptions(input, fetcherOpts, ctx) function runs automatically for every request made by that client. This allows you to inject logic that determines configuration based on the request input.
3. Execution: upfetch(input, options?, ctx?) performs a single request using the provided input and options.

Important Note on Bodies: The default body defined in the client setup is ignored. You must pass the request body directly to the upfetch() call to ensure it is sent.

When making a request, upfetch applies specific merging logic between the default configuration and the individual request options:

• headers: Default headers are merged with request-specific headers. If a key exists in both, the request values win.
• params: Default parameters are merged with input URL parameters and request parameters.
• URL Parameter Preservation: Input URL parameters are preserved and are not passed into the serializeParams function.

upfetch provides hooks for monitoring upload and download progress:

• onRequestStreaming: Instruments upload progress.
• onResponseStreaming: Instruments download progress.

Important details for the streaming model:

• The first callback execution receives an empty chunk and the initial byte counters.
• The totalBytes value may be undefined if the server does not provide a Content-Length header. To handle this, you can default totalBytes to transferredBytes within the callback.
• Empty request or response bodies do not guarantee that streaming callbacks will be triggered.

await upfetch('/download', {
   onResponseStreaming({ chunk, transferredBytes, totalBytes = transferredBytes }) {
      console.log(chunk, transferredBytes, totalBytes)
   },
})

The execution flow of an up-fetch request follows this specific order:

1. Build defaults: getDefaultOptions is called.
2. Merge options: Fallback options, defaults, and request-specific options are merged.
3. Serialization: Request body and headers are serialized.
4. Construction: URL is resolved and the Request object is constructed.
5. onRequest: The request hook runs (can mutate the Request).
6. Execution: The actual fetch is executed.
7. Retry Logic: The retry policy is evaluated and onRetry is called if needed.
8. onResponse: Runs exactly once after all retry attempts have finished.
9. Rejection: reject is run if the request failed.
10. Parsing: parseRejected or parseResponse is run.
11. Validation: The schema is validated if provided.
12. Final Hooks: onSuccess or onError is run.

By default, upfetch throws a ResponseError when a request fails. To switch to a pattern where errors are returned as values (e.g., { data, error }), set the reject option to return false. When reject returns false, you must provide a parseResponse function to define how both successful and error responses are structured.

const upfetch = up(fetch, () => ({
   reject: () => false,
   parseResponse: async (response) => {
      const json = await response.json()
      return response.ok
         ? { data: json, error: null }
         : { data: null, error: json }
   },
}))

// Usage:
const { data, error } = await upfetch('/users/1')

To use up-fetch, import the up function and pass the native fetch implementation to it. This creates an enhanced fetch client.

import { up } from 'up-fetch'

export const upfetch = up(fetch)