@devmoods/fetch

Feature-rich, type-safe and delightful Fetch API wrapper

pnpm install @devmoods/fetch

Features

• Assume JSON responses and always make it available as response.jsonData - no need to await response.json()
• Create fetch instances with pre-configured options and root URLs.
• Type argument fetch<T> to specify response types, optionally inferred via Standard Schema validators
• Throw a HttpError when status < 200 or status >= 400 (containing error.response)
• Timeout after x seconds
• Automatic retries with configurable behaviour
• Request and Response interceptors
• Attach X-Request-ID to all requests. Retried requests have the same ID
• Camel to snake and snake to camel property transformers

Examples

Setup a configured fetch instance

import { createFetch, TimeoutError } from '@devmoods/fetch';

const fetch = createFetch({
  getRootUrl: () => 'http://localhost:3000/api',
  timeout: 1000,
  retryOn: () => (error) => error instanceof TimeoutError,
});

fetch.intercept({
  request: (request) => console.log(request),
  response: (response) => console.log(response),
});

Basic usage

type User = Record<string, any>;

const response = await fetch<User>('/users/1');
console.log(response.jsonData);

await fetch<User[]>('/users', {
  timeout: 5000,
  credentials: 'include',
  retryOn: () = false
});

Transforms

Some APIs return snake_case when your app uses camelCase and vice-versa. Use the built-in transforms to convert. They are fully TypeScript-compatible and provides automatic type inference.

import { createFetch, snakeToCamelCase } from '@devmoods/fetch';

const fetch = createFetch({ transform: snakeToCamelCase });

await fetch('/users');

Standard Schema

Validates the transformed data (see above) using a Standard Schema compatible validation library like ArkType or Zod.

import { type } from 'arktype';

const post = type({ name: 'string', body: 'string' });

await fetch('/names', { schema: post.array() });

createRetryOn

Network issues will eventually occur. This library has built-in support for retries. Use the exported createRetryOn to create functions you can pass to retryOn. This utility makes it easy to limit amount of attempts, determine what errors to retry and setting a backoff strategy (e.g. linear or exponential).

import {
  createFetch,
  createRetryOn,
  TimeoutError,
  HttpError,
} from '@devmoods/fetch';

const fetch = createFetch({
  getRootUrl: () => 'http://localhost:3000/api',
  timeout: 20000,
  retryOn: () =>
    createRetryOn({
      max: 5,
      isRetriable: (error) =>
        error instanceof HttpError
          ? error.response.status === 503
          : error instanceof TimeoutError,
      getDelay: (n) => 500 * n,
    }),
});

License

MIT