@vielzeug/courier

Type-safe HTTP, query cache, mutations, SSE, and streaming built on native fetch.

Package: @vielzeug/courier  ·  Category: Http

Key exports: createApi, createCourier, createQuery, createMutation, createStream, CourierError, HttpError, NetworkError, TimeoutError, AbortError

When to use: Typed HTTP, caching, mutations, SSE, and readable streaming with a shared interceptor pipeline.

Related: @vielzeug/spell · @vielzeug/ripple · @vielzeug/vault

@vielzeug/courier is part of Vielzeug and ships as a zero-dependency TypeScript package with ESM+CJS output.

Installation

pnpm add @vielzeug/courier
npm install @vielzeug/courier
yarn add @vielzeug/courier

Quick Start

import { createCourier } from '@vielzeug/courier';

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

const client = createCourier({
  baseUrl: 'https://api.example.com',
  query: { staleTime: 5_000 },
});

// observe() returns a SyncStore and triggers a background fetch if stale
const store = client.query.observe({
  key: ['users', 1],
  fn: ({ signal }) => client.api.get<User>('/users/{id}', { params: { id: 1 }, signal }),
  staleTime: 5_000,
});

const createUser = client.mutation((input: NewUser, signal) =>
  client.api.post<User>('/users', { body: input, signal }),
);

const nextUser = await createUser.mutate({ name: 'Alice' });
client.query.set(['users', nextUser.id], nextUser);
client.query.invalidate(['users']);

Documentation

Full docs: https://vielzeug.dev/courier/

• Overview
• Usage Guide
• API Reference
• Examples

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.