@alwatr/fetch

@alwatr/fetch

@alwatr/fetch is an enhanced, lightweight, and dependency-free wrapper for the native fetch API. It provides modern features like caching strategies, request retries, timeouts, and intelligent duplicate request handling, all in a compact package.

It's designed to be a drop-in replacement for the standard fetch to instantly upgrade your application's network layer.

Key Features

• Go-Style Error Handling: Returns a tuple [Response, null] on success or [null, FetchError] on failure—no exceptions thrown.
• Retry Pattern: Automatically retries failed requests on timeouts or server errors (5xx).
• Request Timeout: Aborts requests that take too long to complete.
• Duplicate Handling: Prevents sending identical parallel requests, returning a single response for all callers.
• Caching Strategies: Leverages the browser's Cache API with strategies like stale_while_revalidate.
• Simplified API: Send JSON and URL parameters with ease using bodyJson and queryParams.
• TypeScript First: Written entirely in TypeScript for a great developer experience.

Installation

Install the package using your preferred package manager:

# npm
npm i @alwatr/fetch

# yarn
yarn add @alwatr/fetch

# pnpm
pnpm add @alwatr/fetch

Quick Start

Import the fetch function and use it with tuple destructuring for elegant error handling. The function returns [Response, null] on success or [null, FetchError] on failure—no exceptions are thrown.

import {fetch} from '@alwatr/fetch';

async function fetchProducts() {
  console.log('Fetching product list...');

  const [response, error] = await fetch('/api/products', {
    queryParams: {limit: 10, category: 'electronics'},
    cacheStrategy: 'stale_while_revalidate',
    timeout: '5s',
  });

  if (error) {
    console.error('Failed to fetch products:', error.message);
    console.error('Error reason:', error.reason);
    return;
  }

  // At this point, response is guaranteed to be valid and ok
  const data = await response.json();
  console.log('Products:', data);
}

fetchProducts();

Error Handling

@alwatr/fetch uses a Go-style tuple return pattern instead of throwing exceptions. This provides explicit, type-safe error handling.

Return Type

type FetchResponse = Promise<[Response, null] | [null, FetchError]>;

• Success: [Response, null] - The response is guaranteed to have response.ok === true
• Failure: [null, FetchError] - Contains detailed information about what went wrong

FetchError Class

All errors are returned as FetchError instances, which provide rich context about the failure:

class FetchError extends Error {
  reason: FetchErrorReason; // Specific error reason
  response?: Response; // The HTTP response (if available)
  data?: unknown; // Parsed response body (if available)
}

Error Reasons

The reason property indicates why the request failed:

• 'http_error': HTTP error status (e.g., 404, 500)
• 'timeout': Request exceeded the timeout duration
• 'cache_not_found': Resource not found in cache (when using cache_only)
• 'network_error': Network-level error (e.g., DNS failure, connection refused)
• 'aborted': Request was aborted via AbortSignal
• 'unknown_error': Unspecified error

Error Handling Example

const [response, error] = await fetch('/api/user/profile', {
  bearerToken: 'jwt-token',
});

if (error) {
  switch (error.reason) {
    case 'http_error':
      console.error(`HTTP ${error.response?.status}:`, error.data);
      break;
    case 'timeout':
      console.error('Request timed out. Please try again.');
      break;
    case 'network_error':
      console.error('Network error. Check your connection.');
      break;
    case 'cache_not_found':
      console.error('Data not available offline.');
      break;
    default:
      console.error('Request failed:', error.message);
  }
  return;
}

// Safe to use response here
const userData = await response.json();

API and Options

The fetch function takes a url string and an options object. The options object extends the standard RequestInit and adds several custom options for enhanced control.

Option	Type	Default	Description
method	HttpMethod	'GET'	The HTTP request method.
headers	HttpRequestHeaders	{}	An object representing the request's headers.
timeout	Duration	8_000 (8s)	Request timeout in milliseconds or as a duration string (e.g., '5s'). Set to 0 to disable.
retry	number	3	Number of retries if the request fails with a server error (5xx) or times out.
retryDelay	Duration	1_000 (1s)	Delay between retry attempts in milliseconds or as a duration string.
removeDuplicate	'never' | 'always' | 'until_load' | 'auto'	'never'	Strategy for handling identical parallel requests. body is included for uniqueness.
cacheStrategy	'network_only' | 'network_first' | ...	'network_only'	Caching strategy using the browser's Cache API.
cacheStorageName	string	'fetch_cache'	Custom name for the CacheStorage instance.
revalidateCallback	(response: Response) => void	undefined	Callback executed with the new response when using stale_while_revalidate strategy.
bodyJson	Json	undefined	A JavaScript object sent as the request body. Sets Content-Type to application/json.
queryParams	Dictionary	undefined	An object of query parameters appended to the URL.
bearerToken	string	undefined	A bearer token added to the Authorization header.
alwatrAuth	{userId: string; userToken: string}	undefined	Alwatr-specific authentication credentials.

... and all other standard RequestInit properties like signal, credentials, etc.

Features in Detail

Query Parameters

The queryParams option simplifies adding search parameters to your request URL.

// This will make a GET request to: /api/users?page=2&sort=asc
const [response, error] = await fetch('/api/users', {
  queryParams: {page: 2, sort: 'asc'},
});

if (error) {
  console.error('Failed to fetch users:', error.message);
  return;
}

const users = await response.json();

JSON Body

Use bodyJson to send a JavaScript object as a JSON payload. The Content-Type header is automatically set to application/json.

// This will make a POST request to /api/orders with a JSON body
const [response, error] = await fetch('/api/orders', {
  method: 'POST',
  bodyJson: {
    productId: 'xyz-123',
    quantity: 2,
  },
});

if (error) {
  console.error('Failed to create order:', error.message);
  return;
}

const order = await response.json();
console.log('Order created:', order);

Timeout

Set a timeout for your requests. If the request takes longer than the specified duration, it will be aborted and return a FetchError with reason: 'timeout'.

const [response, error] = await fetch('/api/slow-endpoint', {
  timeout: '2.5s', // You can use duration strings
});

if (error) {
  if (error.reason === 'timeout') {
    console.error('Request timed out after 2.5 seconds');
  }
  return;
}

Retry Pattern

The fetch operation will automatically retry on server errors (5xx status codes) or timeouts.

// Retry up to 5 times, with a 2-second delay between each attempt
const [response, error] = await fetch('/api/flaky-service', {
  retry: 5,
  retryDelay: '2s',
});

if (error) {
  console.error('Request failed after 5 retries:', error.message);
  return;
}

const data = await response.json();

Duplicate Request Handling

The removeDuplicate option prevents multiple identical requests from being sent simultaneously. The uniqueness of a request is determined by its method, URL, and body.

• 'never' (default): Does nothing.
• 'until_load': Caches the Promise of a request until it resolves. Subsequent identical requests will receive a clone of the first response.
• 'always': Caches the response indefinitely (for the lifetime of the application).
• 'auto': Uses 'until_load' if the Cache API is available, otherwise 'always'.

// Both calls will result in only ONE network request.
// The second call will receive the response from the first.
const results = await Promise.all([
  fetch('/api/data', {removeDuplicate: 'until_load'}),
  fetch('/api/data', {removeDuplicate: 'until_load'}),
]);

// Both results will have the same response or error
const [response1, error1] = results[0];
const [response2, error2] = results[1];

Cache Strategies

Leverage the browser's Cache API with cacheStrategy.

• 'network_only' (default): Standard fetch behavior; no caching.
• 'cache_first': Serves from cache if available. Otherwise, fetches from the network and caches the result.
• 'network_first': Fetches from the network first. If the network fails, it falls back to the cache.
• 'cache_only': Only serves from cache; returns an error if not found.
• 'update_cache': Fetches from network and updates the cache.
• 'stale_while_revalidate': The fastest strategy. It serves stale content from the cache immediately while sending a network request in the background to update the cache for the next time.

// Serve news from cache instantly, but update it in the background for the next visit.
const [response, error] = await fetch('/api/news', {
  cacheStrategy: 'stale_while_revalidate',
  revalidateCallback: (freshResponse) => {
    console.log('Cache updated with fresh data!');
    // You can use freshResponse to update the UI if needed
  },
});

if (error) {
  console.error('Failed to load news:', error.message);
  return;
}

const news = await response.json();

Authentication

Easily add authentication headers with bearerToken or the alwatrAuth scheme.

// Using a Bearer Token
const [response, error] = await fetch('/api/secure/data', {
  bearerToken: 'your-jwt-token-here',
});

if (error) {
  if (error.response?.status === 401) {
    console.error('Authentication failed. Please log in again.');
  }
  return;
}

const data = await response.json();

// Using Alwatr's authentication scheme
const [response2, error2] = await fetch('/api/secure/data', {
  alwatrAuth: {
    userId: 'user-id',
    userToken: 'user-auth-token',
  },
});

Sponsors

The following companies, organizations, and individuals support Nanolib's ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.

Contributing

Contributions are welcome! Please read our contribution guidelines before submitting a pull request.