@zerolith/client 0.1.0-alpha.5 → 0.1.0-alpha.6

package/src/index.ts

@@ -6,19 +6,25 @@
  */
 import { PROBLEM_MEDIA_TYPE, type Problem, type Resource, isProblem, resource } from "zerolith";
 
-/** The HTTP methods an operation can use; `query` is the HTTP QUERY method. */
-export type Method = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace" | "query";
+/**
+ * The HTTP method of an operation, in lowercase: one OpenAPI names, `query`
+ * being the HTTP QUERY method, or any other method token, as an OpenAPI 3.2
+ * `additionalOperations` entry such as `copy` gives.
+ */
+export type Method = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "query" | (string & {});
 
 /** One operation as the generated `Api` interface describes it. */
 export interface Operation
 {
+    /** The HTTP method in lowercase, such as `get`; the request sends it uppercased. */
     readonly method: Method;
+    /** The path template, such as `/notes/{id}`, whose placeholders the client fills from `params` with URI-encoded values. */
     readonly path: string;
     /** Path parameters, by the name inside the braces. */
     readonly params?: Record<string, string | number | boolean>;
     /** Query parameters; arrays repeat the key, objects are JSON. */
     readonly query?: Record<string, unknown>;
-    /** The request body; JSON unless it is a `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, or string. */
+    /** The request body; JSON unless it is a `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, `ReadableStream`, or string, which are sent as they are. */
     readonly body?: unknown;
     /** What a successful call resolves to. */
     readonly output: unknown;
@@ -39,7 +45,9 @@ export type Output<Op extends Operation> = Op["output"];
 /** Per-call options. */
 export interface CallOptions
 {
+    /** Becomes the request's `signal`, so aborting it rejects the call under `fetch` or `portTransport`; `query` replaces it with the resource's own signal. */
     signal?: AbortSignal;
+    /** Headers for this call, set over the client's `headers` so that a name in both takes this value. */
     headers?: HeadersInit;
 }
 
@@ -53,6 +61,7 @@ export interface ClientOptions
 {
     /** Prepended to every path. Defaults to "", the page's origin in a browser; pass an absolute URL elsewhere. */
     baseUrl?: string;
+    /** Sends every request the client builds and resolves with the response. Defaults to the global `fetch`, looked up on each call. */
     transport?: Transport;
     /** Headers sent with every request, or a function returning them, for values such as a bearer token. */
     headers?: HeadersInit | (() => HeadersInit);
@@ -61,9 +70,12 @@ export interface ClientOptions
 /** 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. */
     readonly problem: Problem;
+    /** The response outside 2xx, for its status and headers; its body has already been read when the content type is JSON. */
     readonly response: 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: Problem, response: Response)
     {
         super(problem.title ?? `HTTP ${response.status}`);
@@ -122,7 +134,12 @@ function buildRequest(route: { method: Method; path: string }, input: LooseInput
         {
             throw new TypeError(`zerolith/client: ${route.method.toUpperCase()} ${route.path} needs the path parameter "${name}"`);
         }
-        return encodeURIComponent(String(value));
+        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);
@@ -141,6 +158,10 @@ function buildRequest(route: { method: Method; path: string }, input: LooseInput
         if (isRawBody(input.body))
         {
             init.body = input.body;
+            if (input.body instanceof ReadableStream)
+            {
+                (init as RequestInit & { duplex: "half" }).duplex = "half";
+            }
         }
         else
         {
@@ -154,19 +175,50 @@ function buildRequest(route: { method: Method; path: string }, input: LooseInput
     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: Response): Promise<unknown>
 {
     if (response.status === 204 || response.status === 205)
     {
         return undefined;
     }
-    const type = response.headers.get("content-type") ?? "";
+    const type = (response.headers.get("content-type") ?? "").toLowerCase();
     if (type.includes("json"))
     {
         return response.json();
     }
-    const text = await response.text();
-    return text === "" ? undefined : text;
+    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<T>(own: AbortSignal, caller: AbortSignal | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T>
+{
+    if (caller === undefined)
+    {
+        return run(own);
+    }
+    const combined = new AbortController();
+    const abort = (): void => 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: Response): Promise<unknown>
@@ -217,7 +269,7 @@ export function createClient<A extends Contract<A>>(routes: RouteTable<A>, optio
         {
             return resource<Input<A[K]>, Output<A[K]>>({
                 params: input,
-                loader: ({ params, abort }) => call(name, params as LooseInput, { ...callOptions, signal: abort }) as Promise<Output<A[K]>>
+                loader: ({ params, abort }) => withSignals(abort, callOptions.signal, (signal) => call(name, params as LooseInput, { ...callOptions, signal }) as Promise<Output<A[K]>>)
             });
         },
         request<K extends keyof A>(name: K, ...args: InputArgs<A[K]>): Request

package/src/port.ts

@@ -9,31 +9,47 @@ 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;
 }
 
@@ -128,8 +144,15 @@ export function servePort(port: PortLike, handler: (request: Request) => Respons
             }
             catch (error)
             {
-                const title = error instanceof Error ? error.message : String(error);
-                response = new Response(JSON.stringify({ title, status: 500 }), { status: 500, headers: { "content-type": "application/problem+json" } });
+                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: PortResponse = { kind: "zerolith:response", id, status: response.status, statusText: response.statusText, headers: [...response.headers], body: text === "" ? null : text };