@zerolith/client 0.0.0-canary.20261102.g8292c77

package/dist/index.js

@@ -0,0 +1,155 @@
+/**
+ * @zerolith/client: a typed HTTP client over a neutral contract. The route
+ * table and the types come from `@zerolith/client/generate`, which reads an
+ * OpenAPI document; the client itself knows nothing about the server beyond
+ * its paths. Failures are RFC 9457 problems, thrown as `ProblemError`.
+ */
+import { PROBLEM_MEDIA_TYPE, isProblem, resource } from "zerolith";
+/** Thrown for a response outside 2xx, carrying the problem the server sent or one built from the status line. */
+export class ProblemError extends Error {
+    /** The problem the server sent, with `status` filled from the response when the body omits it; a body that is not a JSON problem yields `status` and a `title` from the status line. */
+    problem;
+    /** The response outside 2xx, for its status and headers; its body has already been read when the content type is JSON. */
+    response;
+    /** Wraps `problem` and the `response` it came from; the message is the problem's `title`, or `HTTP <status>` when it has none. */
+    constructor(problem, response) {
+        super(problem.title ?? `HTTP ${response.status}`);
+        this.name = "ProblemError";
+        this.problem = problem;
+        this.response = response;
+    }
+}
+function isRawBody(body) {
+    return typeof body === "string" || body instanceof FormData || body instanceof URLSearchParams || body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof ReadableStream;
+}
+function searchOf(query) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        for (const item of Array.isArray(value) ? value : [value]) {
+            search.append(key, typeof item === "object" && item !== null ? JSON.stringify(item) : String(item));
+        }
+    }
+    return search.size > 0 ? `?${search.toString()}` : "";
+}
+function buildRequest(route, input, options, client) {
+    const path = route.path.replace(/\{([^{}]+)\}/g, (_match, name) => {
+        const value = input.params?.[name];
+        if (value === undefined) {
+            throw new TypeError(`zerolith/client: ${route.method.toUpperCase()} ${route.path} needs the path parameter "${name}"`);
+        }
+        const segment = encodeURIComponent(String(value));
+        if (segment === "." || segment === "..") {
+            throw new TypeError(`zerolith/client: ${route.method.toUpperCase()} ${route.path} got "${segment}" for the path parameter "${name}", which would move the request to another path`);
+        }
+        return segment;
+    });
+    const base = (client.baseUrl ?? "").replace(/\/$/, "");
+    const headers = new Headers(typeof client.headers === "function" ? client.headers() : client.headers);
+    new Headers(options.headers).forEach((value, key) => headers.set(key, value));
+    if (!headers.has("accept")) {
+        headers.set("accept", `application/json, ${PROBLEM_MEDIA_TYPE}`);
+    }
+    const init = { method: route.method.toUpperCase(), headers };
+    if (options.signal !== undefined) {
+        init.signal = options.signal;
+    }
+    if (input.body !== undefined) {
+        if (isRawBody(input.body)) {
+            init.body = input.body;
+            if (input.body instanceof ReadableStream) {
+                init.duplex = "half";
+            }
+        }
+        else {
+            init.body = JSON.stringify(input.body);
+            if (!headers.has("content-type")) {
+                headers.set("content-type", "application/json");
+            }
+        }
+    }
+    return new Request(`${base}${path}${searchOf(input.query ?? {})}`, init);
+}
+/** A successful response's body: JSON parsed, text for `text/*` or no type, a `Blob` for any other type, such as an image, and `undefined` when it is empty. */
+async function readBody(response) {
+    if (response.status === 204 || response.status === 205) {
+        return undefined;
+    }
+    const type = (response.headers.get("content-type") ?? "").toLowerCase();
+    if (type.includes("json")) {
+        return response.json();
+    }
+    if (type === "" || type.startsWith("text/")) {
+        const text = await response.text();
+        return text === "" ? undefined : text;
+    }
+    return response.blob();
+}
+/** Calls `run` with a signal that aborts when either `own` or `caller` does, and stops listening to the caller once the call settles. */
+async function withSignals(own, caller, run) {
+    if (caller === undefined) {
+        return run(own);
+    }
+    const combined = new AbortController();
+    const abort = () => combined.abort();
+    if (own.aborted || caller.aborted) {
+        combined.abort();
+    }
+    own.addEventListener("abort", abort);
+    caller.addEventListener("abort", abort);
+    try {
+        return await run(combined.signal);
+    }
+    finally {
+        own.removeEventListener("abort", abort);
+        caller.removeEventListener("abort", abort);
+    }
+}
+async function settle(response) {
+    if (response.ok) {
+        return readBody(response);
+    }
+    let problem;
+    if ((response.headers.get("content-type") ?? "").includes("json")) {
+        const body = await response.json().catch(() => undefined);
+        if (isProblem(body)) {
+            problem = { status: response.status, ...body };
+        }
+    }
+    throw new ProblemError(problem ?? { status: response.status, title: response.statusText === "" ? `HTTP ${response.status}` : response.statusText }, response);
+}
+/**
+ * Creates a client for a generated route table. `routes` and the `Api`
+ * type parameter come from the same generated module, so an operation
+ * name, its parameters, its body, and its output are checked together.
+ */
+export function createClient(routes, options = {}) {
+    const transport = options.transport ?? ((request) => fetch(request));
+    const request = (name, input, callOptions) => {
+        const route = routes[name];
+        if (route === undefined) {
+            throw new TypeError(`zerolith/client: unknown operation "${String(name)}"`);
+        }
+        return buildRequest(route, input ?? {}, callOptions ?? {}, options);
+    };
+    const call = async (name, input, callOptions) => {
+        return settle(await transport(request(name, input, callOptions)));
+    };
+    return {
+        call(name, ...args) {
+            return call(name, args[0], args[1]);
+        },
+        query(name, input, callOptions = {}) {
+            return resource({
+                params: input,
+                loader: ({ params, abort }) => withSignals(abort, callOptions.signal, (signal) => call(name, params, { ...callOptions, signal }))
+            });
+        },
+        request(name, ...args) {
+            return request(name, args[0], args[1]);
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/port.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A transport over a message port, for the places `fetch` cannot reach the
+ * server: an Electron renderer behind `contextBridge`, a worker, a test.
+ * `portTransport` runs where the client runs; `servePort` runs where the
+ * handler runs. Bodies travel as text, which covers JSON and encoded forms.
+ */
+import type { Transport } from "./index.js";
+/** The port shapes supported: a DOM `MessagePort`, Node's, or Electron's `MessagePortMain`. */
+export interface PortLike {
+    /** Sends a message to the other end; `portTransport` posts each `PortRequest` through it and `servePort` each `PortResponse`. */
+    postMessage(message: unknown): void;
+    /** Starts delivering messages; called, when present, right after the listener is attached, since a DOM `MessagePort` and Electron's `MessagePortMain` queue messages until it runs. */
+    start?(): void;
+    /** Receives messages the `EventTarget` way, as a DOM `MessagePort` does; used in preference to `on` when both exist. */
+    addEventListener?(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    /** Receives messages the `EventEmitter` way, as Electron's `MessagePortMain` does; used when `addEventListener` is absent, and a port with neither throws a `TypeError`. */
+    on?(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+/** What crosses the port for a request. */
+export interface PortRequest {
+    /** Tags the message as a request, so `servePort` ignores other traffic on the port. */
+    kind: "zerolith:request";
+    /** Pairs the request with its response; each `portTransport` numbers its requests from 1. */
+    id: number;
+    /** The request's absolute URL, from which `servePort` builds the `Request` its handler receives. */
+    url: string;
+    /** The request method as `Request.method` reports it, such as `POST`. */
+    method: string;
+    /** The request headers as `[name, value]` pairs with lowercase names, as iterating a `Headers` yields them. */
+    headers: [string, string][];
+    /** The body as UTF-8 text, or `null` for a `GET` or `HEAD` request or an empty body. */
+    body: string | null;
+}
+/** What crosses the port for a response. */
+export interface PortResponse {
+    /** Tags the message as a response, so `portTransport` ignores other traffic on the port. */
+    kind: "zerolith:response";
+    /** The `id` of the request this answers; an answer with no pending request, such as one whose call was aborted, is dropped. */
+    id: number;
+    /** The status code of the handler's response, or 500 when the handler threw. */
+    status: number;
+    /** The status text of the handler's response, empty when none was set. */
+    statusText: string;
+    /** The response headers as `[name, value]` pairs with lowercase names, as iterating a `Headers` yields them. */
+    headers: [string, string][];
+    /** The body as UTF-8 text, or `null` when it is empty, as for a 204. */
+    body: string | null;
+}
+/**
+ * A `Transport` that sends each request over the port as a message and
+ * resolves with the response that comes back under the same id. Aborting
+ * the request's signal rejects the call; the message already sent is
+ * answered and ignored.
+ */
+export declare function portTransport(port: PortLike): Transport;
+/**
+ * Answers the requests `portTransport` sends by building a `Request`,
+ * calling `handler`, and posting the response back. A handler that throws
+ * answers with a 500 problem so the client sees a `ProblemError`.
+ */
+export declare function servePort(port: PortLike, handler: (request: Request) => Response | Promise<Response>): void;
+//# sourceMappingURL=port.d.ts.map

package/dist/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IAErB,iIAAiI;IACjI,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,uLAAuL;IACvL,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,wHAAwH;IACxH,gBAAgB,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,4KAA4K;IAC5K,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAC5E;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAExB,uFAAuF;IACvF,IAAI,EAAE,kBAAkB,CAAC;IACzB,6FAA6F;IAC7F,EAAE,EAAE,MAAM,CAAC;IACX,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,+GAA+G;IAC/G,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAEzB,4FAA4F;IAC5F,IAAI,EAAE,mBAAmB,CAAC;IAC1B,+HAA+H;IAC/H,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gHAAgH;IAChH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAmBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CA0CvD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAmC3G"}

package/dist/port.js

@@ -0,0 +1,86 @@
+function listen(port, handler) {
+    if (typeof port.addEventListener === "function") {
+        port.addEventListener("message", (event) => handler(event.data));
+    }
+    else if (typeof port.on === "function") {
+        port.on("message", (event) => handler(event.data));
+    }
+    else {
+        throw new TypeError("zerolith/client: the port has neither addEventListener nor on");
+    }
+    port.start?.();
+}
+/**
+ * A `Transport` that sends each request over the port as a message and
+ * resolves with the response that comes back under the same id. Aborting
+ * the request's signal rejects the call; the message already sent is
+ * answered and ignored.
+ */
+export function portTransport(port) {
+    const pending = new Map();
+    let next = 1;
+    listen(port, (data) => {
+        const message = data;
+        if (message === null || typeof message !== "object" || message.kind !== "zerolith:response" || typeof message.id !== "number") {
+            return;
+        }
+        const waiting = pending.get(message.id);
+        if (waiting === undefined) {
+            return;
+        }
+        pending.delete(message.id);
+        waiting.resolve(new Response(message.body ?? null, { status: message.status ?? 200, statusText: message.statusText ?? "", headers: message.headers ?? [] }));
+    });
+    return async (request) => {
+        const id = next++;
+        const body = request.method === "GET" || request.method === "HEAD" ? null : await request.text();
+        const message = { kind: "zerolith:request", id, url: request.url, method: request.method, headers: [...request.headers], body: body === "" ? null : body };
+        return new Promise((resolve, reject) => {
+            if (request.signal.aborted) {
+                reject(request.signal.reason ?? new DOMException("The request was aborted", "AbortError"));
+                return;
+            }
+            pending.set(id, { resolve, reject });
+            request.signal.addEventListener("abort", () => {
+                if (pending.delete(id)) {
+                    reject(request.signal.reason ?? new DOMException("The request was aborted", "AbortError"));
+                }
+            });
+            port.postMessage(message);
+        });
+    };
+}
+/**
+ * Answers the requests `portTransport` sends by building a `Request`,
+ * calling `handler`, and posting the response back. A handler that throws
+ * answers with a 500 problem so the client sees a `ProblemError`.
+ */
+export function servePort(port, handler) {
+    listen(port, (data) => {
+        const message = data;
+        if (message === null || typeof message !== "object" || message.kind !== "zerolith:request" || typeof message.id !== "number" || typeof message.url !== "string") {
+            return;
+        }
+        const id = message.id;
+        const answer = async () => {
+            let response;
+            try {
+                response = await handler(new Request(message.url ?? "", { method: message.method ?? "GET", headers: message.headers ?? [], body: message.body ?? null }));
+            }
+            catch (error) {
+                if (typeof reportError === "function") {
+                    reportError(error);
+                }
+                else {
+                    console.error("zerolith/client: a servePort handler threw", error);
+                }
+                response = new Response(JSON.stringify({ title: "The handler failed", status: 500 }), { status: 500, headers: { "content-type": "application/problem+json" } });
+            }
+            const text = await response.text();
+            const reply = { kind: "zerolith:response", id, status: response.status, statusText: response.statusText, headers: [...response.headers], body: text === "" ? null : text };
+            port.postMessage(reply);
+        };
+        void answer();
+    });
+}
+//# sourceMappingURL=port.js.map

package/dist/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"AAuDA,SAAS,MAAM,CAAC,IAAc,EAAE,OAAgC;IAE5D,IAAI,OAAO,IAAI,CAAC,gBAAgB,KAAK,UAAU,EAC/C,CAAC;QACG,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;SACI,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,UAAU,EACtC,CAAC;QACG,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;SAED,CAAC;QACG,MAAM,IAAI,SAAS,CAAC,+DAA+D,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAc;IAExC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwF,CAAC;IAChH,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QAElB,MAAM,OAAO,GAAG,IAAoC,CAAC;QACrD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,mBAAmB,IAAI,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ,EAC7H,CAAC;YACG,OAAO;QACX,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,SAAS,EACzB,CAAC;YACG,OAAO;QACX,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,OAAO,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACjK,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QAErB,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;QACjG,MAAM,OAAO,GAAgB,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxK,OAAO,IAAI,OAAO,CAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAE7C,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAC1B,CAAC;gBACG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,YAAY,CAAC,yBAAyB,EAAE,YAAY,CAAC,CAAC,CAAC;gBAC3F,OAAO;YACX,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBAE1C,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EACtB,CAAC;oBACG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,YAAY,CAAC,yBAAyB,EAAE,YAAY,CAAC,CAAC,CAAC;gBAC/F,CAAC;YACL,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,OAA2D;IAEjG,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QAElB,MAAM,OAAO,GAAG,IAAmC,CAAC;QACpD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,kBAAkB,IAAI,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,EAC/J,CAAC;YACG,OAAO;QACX,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;YAErC,IAAI,QAAkB,CAAC;YACvB,IACA,CAAC;gBACG,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;YAC9J,CAAC;YACD,OAAO,KAAK,EACZ,CAAC;gBACG,IAAI,OAAO,WAAW,KAAK,UAAU,EACrC,CAAC;oBACG,WAAW,CAAC,KAAK,CAAC,CAAC;gBACvB,CAAC;qBAED,CAAC;oBACG,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,KAAK,CAAC,CAAC;gBACvE,CAAC;gBACD,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE,EAAE,CAAC,CAAC;YACpK,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,KAAK,GAAiB,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACzL,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,KAAK,MAAM,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@zerolith/client",
+    "version": "0.0.0-canary.20261102.g8292c77",
+    "description": "A typed HTTP client for zerolith over a neutral contract: generate the route table and types from an OpenAPI document, call operations with checked inputs, and read failures as RFC 9457 problems",
+    "license": "Apache-2.0",
+    "author": "molexxxx",
+    "homepage": "https://zerolith.dev/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/molexxxx/zerolith.git",
+        "directory": "packages/client"
+    },
+    "bugs": {
+        "url": "https://github.com/molexxxx/zerolith/issues"
+    },
+    "keywords": [
+        "zerolith",
+        "openapi",
+        "typed-client",
+        "problem-details"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "bin": {
+        "zerolith-client": "dist/cli.js"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./generate": {
+            "types": "./dist/generate.d.ts",
+            "default": "./dist/generate.js"
+        },
+        "./port": {
+            "types": "./dist/port.d.ts",
+            "default": "./dist/port.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json"
+    },
+    "peerDependencies": {
+        "zerolith": "^0.0.0-canary.20261102.g8292c77"
+    },
+    "devDependencies": {
+        "zerolith": "^0.0.0-canary.20261102.g8292c77"
+    }
+}

package/src/cli.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * `zerolith-client <openapi.json> [--out <file.ts>]`: writes the contract
+ * module for an OpenAPI document to a file, or to standard output.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { type OpenApiDocument, generateClient } from "./generate.js";
+
+const USAGE = "usage: zerolith-client <openapi.json> [--out <file.ts>] [--name <Api>]\n";
+
+interface Arguments
+{
+    input: string | undefined;
+    out: string | undefined;
+    name: string | undefined;
+}
+
+function parse(argv: readonly string[]): Arguments
+{
+    const parsed: Arguments = { input: undefined, out: undefined, name: undefined };
+    for (let index = 0; index < argv.length; index++)
+    {
+        const argument = argv[index] ?? "";
+        if (argument === "--out" || argument === "--name")
+        {
+            const value = argv[index + 1];
+            if (value === undefined)
+            {
+                throw new Error(`${argument} needs a value`);
+            }
+            parsed[argument === "--out" ? "out" : "name"] = value;
+            index++;
+        }
+        else if (argument.startsWith("--"))
+        {
+            throw new Error(`unknown option ${argument}`);
+        }
+        else if (parsed.input === undefined)
+        {
+            parsed.input = argument;
+        }
+        else
+        {
+            throw new Error(`unexpected argument ${argument}`);
+        }
+    }
+    return parsed;
+}
+
+/** Runs the command with the given arguments and returns the exit code. */
+export async function main(argv: readonly string[]): Promise<number>
+{
+    let parsed: Arguments;
+    try
+    {
+        parsed = parse(argv);
+    }
+    catch (error)
+    {
+        process.stderr.write(`zerolith-client: ${error instanceof Error ? error.message : String(error)}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.input === undefined)
+    {
+        process.stderr.write(USAGE);
+        return 2;
+    }
+    try
+    {
+        const document = JSON.parse(await readFile(parsed.input, "utf8")) as OpenApiDocument;
+        const code = generateClient(document, parsed.name === undefined ? {} : { apiName: parsed.name });
+        if (parsed.out === undefined)
+        {
+            process.stdout.write(code);
+        }
+        else
+        {
+            await writeFile(parsed.out, code);
+        }
+    }
+    catch (error)
+    {
+        process.stderr.write(`zerolith-client: ${error instanceof Error ? error.message.replace(/^zerolith\/client: /, "") : String(error)}\n`);
+        return 1;
+    }
+    return 0;
+}
+
+/** True when node started this module, directly or through the bin link npm installs, which it resolves the way node resolves its entry. */
+function started(): boolean
+{
+    const entry = process.argv[1];
+    try
+    {
+        return entry !== undefined && pathToFileURL(realpathSync(entry)).href === import.meta.url;
+    }
+    catch
+    {
+        return false;
+    }
+}
+
+if (started())
+{
+    process.exitCode = await main(process.argv.slice(2));
+}