@auldrant/api

@auldrant/api is a client-side library that makes REST API calls simple and correct. It wraps the Fetch API with ergonomic method helpers, automatic JSON serialization, and a discriminated union response type so you always know whether a request succeeded.

We recommend using Bun to work with @auldrant/api.

bun install

Quick start

import { createApi } from '@auldrant/api';

const api = createApi();

const result = await api.get<User[]>('/api/users');
if (result.ok && !result.empty) {
  console.log(result.data); // User[] — no null check needed
} else if (!result.ok) {
  console.error(result.status); // HTTP status code, or 0 for network errors
}

Configured instance

Pass options to createApi to set defaults that apply to every request:

const api = createApi({
  baseUrl: 'https://api.example.com',
  headers: { Authorization: `Bearer ${token}` },
  timeout: 5000,
});

// Relative paths are resolved against baseUrl
const users = await api.get<User[]>('/users');

Per-request options always override instance defaults.

Method helpers

All helpers are methods on the instance returned by createApi. Most return Promise<ApiResponse<T>>; .head returns Promise<HeadResponse> (HEAD responses are always empty).

Method	Signature
.get	(url, options?)
.post	(url, body?, options?)
.put	(url, body?, options?)
.patch	(url, body?, options?)
.delete	(url, options?)
.head	(url, options?)
.options	(url, options?)

Plain objects passed as body are automatically serialized to JSON.

ApiResponse

type ApiResponse<T> =
  | { ok: true;  empty: false; data: T;    status: number }
  | { ok: true;  empty: true;  data: null; status: number }
  | { ok: false;               data: null; status: number };

Three variants, discriminated by ok and empty:

Check	data type	When
r.ok && !r.empty	T	Success with body — the common case, no null check needed
r.ok && r.empty	null	204 No Content, or HEAD response
!r.ok	null	Network failure, timeout, parse error, or non-2xx status

Status 0 means a network error, timeout, or aborted request. head() returns a narrower HeadResponse type — the non-empty success variant is omitted because HEAD responses never carry a body (RFC 9110 §9.3.5).

Options reference

RequestOptions (GET, DELETE, HEAD, OPTIONS)

Field	Type	Default	Description
accept	MimeType	MimeType.JSON	Expected response MIME type
headers	HeadersInit	—	Additional headers
signal	AbortSignal	—	Cancel the request
timeout	number	—	Abort after N milliseconds
retry	number	0	Max additional attempts on network failure
retryDelay	number	0	Milliseconds to wait between retries

RequestBodyOptions (POST, PUT, PATCH)

Extends RequestOptions with:

Field	Type	Default	Description
contentType	MimeType	MimeType.JSON	Request body content type
compression	CompressionMethod	—	Compress the request body

ApiConfig (createApi)

Field	Type	Default	Description
baseUrl	string | URL	—	Prepended to all relative request paths
headers	HeadersInit	—	Default headers for every request
accept	MimeType	MimeType.JSON	Default Accept type for every request
timeout	number	—	Default timeout for every request

Timeout

// Per-request
const result = await api.get('/data', { timeout: 3000 });

// Or set a default for all requests
const api = createApi({ timeout: 5000 });
const result = await api.get('/data'); // uses 5s timeout

Timed-out requests return { ok: false, status: 0 }.

Retry

Retries apply only to network failures (status 0). Server responses (4xx, 5xx) are never retried. The wait between attempts doubles on each retry (exponential backoff).

const result = await api.get('/data', {
  retry: 3,         // up to 3 additional attempts
  retryDelay: 500,  // 500ms → 1000ms → 2000ms
});

Abort

const controller = new AbortController();

const result = await api.get('/slow', { signal: controller.signal });

// Cancel from elsewhere
controller.abort();

Aborted requests return { ok: false, status: 0 }.

Credentials and cross-origin requests

Headers set in ApiConfig.headers are sent with every request — including absolute URLs that point to a different origin than baseUrl. If you put an Authorization token in config headers, that token travels with any absolute URL you pass to the client.

Best practice: keep Authorization at the call site for requests to trusted origins only, or validate URLs before calling the client. This matches how fetch behaves by default — no library-level stripping.

Compression

Compress request bodies before sending (useful for large payloads):

const data = largeJsonPayload;

await api.post('/ingest', data, {
  compression: CompressionMethod.GZIP,
});

FormData and URLSearchParams bodies are always passed through unchanged — the browser manages their encoding. Small payloads (under 1 KB) are skipped automatically.

Exports

Export	Kind	Description
createApi	function	Creates a configured API instance
ApiConfig	type	Config object for createApi
ApiInstance	type	Return type of createApi
ApiResponse	type	Discriminated union response type
HeadResponse	type	Response shape for HEAD requests (always empty: true on success)
RequestOptions	type	Options for GET/DELETE/HEAD/OPTIONS
RequestBodyOptions	type	Options for POST/PUT/PATCH
HttpMethod	enum	GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
HttpStatus	enum	Common HTTP status codes
MimeType	enum	Common MIME type strings
CompressionMethod	enum	gzip, deflate