jv-custom

Reliable Fetch requests for JavaScript and TypeScript in modern browsers and Node.js. Add bounded retries, per-attempt timeouts, cancellation, and consistent typed errors without replacing the standard fetch API.

Install

npm install jv-custom

Requires a runtime with the standard fetch, AbortController, and Response APIs (Node.js 18+ or a modern browser).

Quick start

import { requestJson } from 'jv-custom';

type User = { id: number; name: string };

const user = await requestJson<User>('https://api.example.com/users/42', {
  headers: { Accept: 'application/json' },
});

request returns a standard Response; requestJson<T> parses JSON and returns the typed body.

Retries and timeouts

import { createClient } from 'jv-custom';

const api = createClient({
  baseUrl: 'https://api.example.com/v1/',
  headers: { Authorization: 'Bearer token' },
  timeout: 5_000,
  retry: {
    attempts: 3, // includes the original request
    delay: 250,
    maxDelay: 2_000,
    methods: ['GET', 'POST'], // methods that are safe to repeat for this API
  },
});

const result = await api.requestJson<{ ok: boolean }>('status');

Client headers are merged with request headers; request-specific values win. baseUrl resolves relative paths such as status against the configured URL. Retries use exponential backoff and honor a server's Retry-After header. By default, only GET, HEAD, OPTIONS, PUT, and DELETE are retried, and only for network failures, timeouts, or temporary HTTP statuses (408, 425, 429, 500, 502, 503, and 504). Set retry.methods to choose methods that are safe to repeat for your API, or use retryUnsafe: true to include POST and PATCH.

Turn retries off with retry: false. Set timeout: 0 to disable the per-attempt timeout.

Cancellation

Pass a standard AbortSignal through RequestInit:

const controller = new AbortController();
const pending = api.request('/reports', { signal: controller.signal });

controller.abort();
await pending;

Cancellation stops the active attempt or retry wait. A cancelled request rejects with RequestError and code ABORTED.

Errors

import { RequestError } from 'jv-custom';

try {
  await api.requestJson('/users');
} catch (error) {
  if (error instanceof RequestError) {
    console.log(error.code, error.status);
  }
}

RequestError.code is one of TIMEOUT, ABORTED, NETWORK, HTTP, or INVALID_JSON. HTTP errors include status and response; network and parsing errors retain their original error in cause.