Typed client

zerolith does not know your server. What it knows is the contract the server publishes, an OpenAPI 3.x document, and @zerolith/client builds on that alone:

1. The server publishes its contract, such as openapi.json.
2. zerolith-client turns the contract into one TypeScript module, src/api.ts, with the types and a route table.
3. createClient over that module checks every call against the contract: the operation's name, its parameters, its body, and what it returns.

Renaming a field on the server then fails tsc on the client, whatever language the server is written in.

Generate the contract module

npx zerolith-client openapi.json --out src/api.ts

The command writes three things: a type for every schema under components.schemas, an Api interface with one entry per operation, and a routes table with the method and path of each. Without --out it prints the module, and --name gives the interface another name. A schema whose type name would clash is written under the next free name with a number added, as Record2, with a comment that says why, and every reference to it follows: one that another schema takes first, as note-item and note_item both give NoteItem, one named like the interface or RouteTable, and one named like a built-in type the module writes, such as Record for an object of free keys or Blob for a binary response. A schema named like a built-in the module does not write keeps its name. One entry looks like this:

getNote: {
    method: "get";
    path: "/notes/{id}";
    params: {
        id: string;
    };
    output: Note;
};

An operation is named by its operationId in camel case, or by its method and path when it has none, so GET /notes/{id}/tags becomes getNotesByIdTags. Two operations that resolve to the same name fail the generator, which asks for distinct operationId values.

How the document maps to types

Call operations

import { createClient } from "@zerolith/client";
import { type Api, routes } from "./notes.api.ts";

const api = createClient<Api>(routes, { baseUrl: "https://notes.example" });

const note = await api.call("getNote", { params: { id: "1" } });
const page = await api.call("listNotes", { query: { q: "rout", limit: 10 } });

call resolves with the operation's output. Its second argument holds the operation's params, query, and body, exactly as optional as the contract makes them, and it is omitted when the operation takes nothing. The request is built this way:

• The path, with each parameter encoded; a missing one throws a TypeError that names it, and so does a parameter of . or .., which the URL would otherwise read as a step to another path.
• The query, with an array repeating its key, an object sent as JSON, and undefined and null left out, whatever style and explode the document declares for the parameter, which the client does not read yet.
• The body as JSON with its content type, unless it is already a FormData, URLSearchParams, Blob, ArrayBuffer or typed array, string, or stream, which goes as it is.
• An Accept header asking for JSON or a problem, unless a header sets one.

A successful response resolves to its JSON, its text, or undefined when it has no content.

Read failures as problems

A response outside 2xx rejects with a ProblemError, so one catch handles every failure the server reports:

import { signal } from "zerolith";
import { ProblemError } from "@zerolith/client";

const notice = signal("");
try
{
    await api.call("getNote", { params: { id: "missing" } });
}
catch (error)
{
    if (!(error instanceof ProblemError))
    {
        throw error;
    }
    notice.set(error.problem.title ?? "Request failed");    // "No such note"
}

The same Problem type is what forms show and what the core exports, so one error shape runs through the whole application.

Query with signals

query wraps an operation in a resource. The function you pass is tracked: when a signal it reads changes, the operation is called again, the previous request is aborted, and a stale result is dropped. Returning undefined keeps the resource idle.

import { signal } from "zerolith";

const search = signal("rout");
const results = api.query("listNotes", () => ({ query: { q: search.get() } }));

results is a resource like any other, as the signals guide describes: results.get() is the latest output, kept while the next request runs, results.pending is true while a request is in flight, and results.error holds the ProblemError of a failed call.

Options

Each call also takes options of its own as its last argument, a signal and headers that override the client's. request takes the same arguments as call and returns the Request a call would send, without sending it.

Over a message port

Where fetch cannot reach the server, the same client runs over a message port: an Electron renderer behind contextBridge, a worker, or a test. servePort, from @zerolith/client/port, answers requests where the handler lives; portTransport sends them from where the client lives.

import { createClient } from "@zerolith/client";
import { portTransport, servePort } from "@zerolith/client/port";
import { type Api, routes } from "./notes.api.ts";

const { port1, port2 } = new MessageChannel();

// Where the handler runs, such as the Electron main process:
servePort(port2, (request) =>
{
    const id = new URL(request.url).pathname.split("/").at(-1);
    const note = { id, title: "From main", tags: [], visibility: "private" };
    return Response.json(note);
});

// Where the page runs, with port1 handed over through the preload script:
const api = createClient<Api>(routes, {
    baseUrl: "app://notes",
    transport: portTransport(port1)
});
const note = await api.call("getNote", { params: { id: "7" } });

In Electron, the main process creates a MessageChannelMain, keeps one port for servePort, and posts the other to the renderer, whose preload script forwards it to the page with window.postMessage; Electron's MessagePortMain and the page's MessagePort are both accepted. Problems cross unchanged, a handler that throws answers with a 500 problem, and aborting a call rejects it at once, so the client's error handling is the same on every transport.