API Reference

new HttpClient({
  adapter, // HttpAdapter — required
  baseURL, // string?
  headers, // HeadersInput?
  timeout, // number?
  credentials, // 'omit' | 'same-origin' | 'include'?
  responseType, // ResponseType?
  paramsSerializer, // (params) => string?
  fileSerializer, // FileSerializer? — default WebFileSerializer, see Serializers below
});

function resolve<TBody>(
  init: HttpRequestInit<TBody>,
  defaults?: ResolveDefaults,
): HttpRequest<TBody>;

function withHeaders(request: HttpRequest, headers: HeadersInput): HttpRequest;
function withMeta(request: HttpRequest, meta: HttpMeta): HttpRequest;
function metaOptOut(key: keyof HttpMeta): (request: HttpRequest) => boolean;

import { fetchAdapter } from '@lamstack/http-client/adapters/fetch';
 
const client = new HttpClient({ adapter: fetchAdapter() });
 
// Inject a replacement (e.g. undici's fetch in older Node, or a test double):
const testClient = new HttpClient({ adapter: fetchAdapter({ fetch: myFetch }) });

import axios from 'axios';
import { axiosAdapter } from '@lamstack/http-client/adapters/axios';
 
const client = new HttpClient({ adapter: axiosAdapter(axios.create({ baseURL: '...' })) });

import type { HttpAdapter, HttpRequest, HttpResponse } from '@lamstack/http-client';
 
function myAdapter(): HttpAdapter {
  return {
    name: 'my-adapter',
    capabilities: { uploadProgress: false, downloadProgress: false, stream: false },
    async send<T>(request: HttpRequest) {
      // ...call your transport, then normalize into an HttpResponse...
      // Any non-2xx outcome (or a network/timeout/cancellation failure) must
      // throw an HttpError — that's the one contract every plugin relies on.
      return {} as HttpResponse<T>;
    },
  };
}

import { auth } from '@lamstack/http-client';
 
client.use(auth(myAuthenticator));
client.use(auth(myAuthenticator, { skip: (request) => request.url.startsWith('/public') }));

import { allOf, apiKey, basic, bearer, withHeaders } from '@lamstack/http-client';
 
// The common case — a Bearer token from any source with getAccessToken():
client.use(auth(bearer(session)));
client.use(auth(bearer(session, { header: 'x-api-key', scheme: '' }))); // custom header, no "Bearer " prefix
client.use(auth(bearer(() => currentToken))); // or a plain function
 
// A static or dynamically-resolved API key, as a header or a query parameter:
client.use(auth(apiKey({ in: 'header', name: 'x-api-key', value: process.env.API_KEY! })));
client.use(auth(apiKey({ in: 'query', name: 'key', value: async () => rotateKey() })));
 
// HTTP Basic auth:
client.use(auth(basic(username, password)));
 
// Compose several — e.g. a bearer token plus a request signature:
client.use(
  auth(
    allOf(bearer(session), async (request) =>
      withHeaders(request, { 'x-signature': await sign(request) }),
    ),
  ),
);

import { metaOptOut, onStatus, recover } from '@lamstack/http-client';
 
client.use(
  recover({
    recover: () => session.renew(), // required
    shouldRecover: onStatus(401, { exclude: ['/auth/login', '/auth/refresh'] }),
    skip: metaOptOut('recover'),
    canRecover: () => session.canRenew(),
    maxAttempts: 1,
    maxStaleRetries: 1,
    cooldownMs: 1000,
    events: recoveryEvents,
  }),
);

import { errorMapper, HttpError } from '@lamstack/http-client';
 
class ValidationError extends Error {
  constructor(public readonly fields: Record<string, string>) {
    super('Validation failed');
  }
}
 
client.use(
  errorMapper((error) => (error.status === 422 ? new ValidationError(error.data as never) : error)),
);
 
await client.get('/x', { meta: { mapError: false } }); // opt this one request out

class HttpError<T = unknown> extends Error {
  code: 'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'CANCELED' | 'PARSE_ERROR' | 'UNKNOWN';
  status: number; // 0 when there is no HTTP response at all
  data?: T; // the parsed error response body, when there is one
  request: HttpRequest;
  response?: HttpResponse<T>;
  cause?: unknown; // non-enumerable, matching native Error.cause
  get isNetworkError(): boolean; // code === 'NETWORK_ERROR'
  get isCanceled(): boolean; // code === 'CANCELED'
  static is(error: unknown): error is HttpError;
  static from(error: unknown, request: HttpRequest): HttpError; // wraps anything else, passes an existing HttpError through unchanged
}

try {
  await client.get('/x');
} catch (error) {
  if (HttpError.is(error)) {
    console.log(error.status, error.code, error.data);
  }
}

import { EventBus } from '@lamstack/http-client';
import type { RecoveryEventMap } from '@lamstack/http-client';
 
const recoveryEvents = new EventBus<RecoveryEventMap>();
 
const unsubscribe = recoveryEvents.on('recovery:failed', ({ error }) => {
  session.end();
  redirectToLogin();
});
// later: unsubscribe(); — or recoveryEvents.off('recovery:failed', listener)
 
recoveryEvents.on('recovery:succeeded', () => console.log('session renewed'));
recoveryEvents.on('recovery:unavailable', ({ error }) => reportToSentry(error));
 
client.use(recover({ recover: renewSession, events: recoveryEvents }));

import { NativeFileSerializer } from '@lamstack/http-client';
 
const client = new HttpClient({
  adapter: fetchAdapter(),
  fileSerializer: new NativeFileSerializer(),
});
 
await client.upload('/files', { avatar: { uri: 'file://photo.jpg' } });

await client.upload('/files', {
  title: 'Vacation photo',
  taken: new Date(), // -> ISO string
  tags: ['beach', 'sun'], // -> repeated form field
  metadata: { camera: 'Pixel' }, // -> JSON-stringified
  avatar: someFile, // File/Blob -> handled by the configured FileSerializer
});

const report = await client.download('/report.pdf'); // Blob

import { cancelable } from '@lamstack/http-client';
 
const { promise, cancel } = cancelable((signal) => client.get('/slow', { signal }));
 
cancel(); // rejects `promise` with an HttpError whose code is 'CANCELED'

import { withHeaders } from '@lamstack/http-client';
import type { HttpPlugin } from '@lamstack/http-client';
 
function clientIdPlugin(clientId: string): HttpPlugin {
  return {
    name: 'client-id',
    order: 50, // between recover and auth — see PluginOrder
    handler: async (request, next) => {
      return next(withHeaders(request, { 'x-client-id': clientId }));
    },
  };
}
 
client.use(clientIdPlugin('abc123'));

function loggingPlugin(): HttpPlugin {
  return {
    name: 'logging',
    order: PluginOrder.observe,
    handler: async (request, next) => {
      const start = Date.now();
      try {
        const response = await next(request);
        console.log(request.method, request.url, response.status, `${Date.now() - start}ms`);
        return response;
      } catch (error) {
        console.log(request.method, request.url, 'failed', `${Date.now() - start}ms`);
        throw error;
      }
    },
  };
}