@optionfactory/fml 9.0.0-rc3 → 9.0.0-rc30

package/dist/httpc.mjs

@@ -1,4 +1,7 @@
 /**
+ * One problem of a failure: its `type` (a code such as `FIELD_ERROR` or
+ * `GENERIC_PROBLEM`), the `context` naming the field it belongs to or null, the
+ * human `reason`, and optional `details`.
  * @typedef {{ type: string; context: string?; reason: string; details: any?; }} Problem
  */
 /**
@@ -8,10 +11,9 @@
  */
 class Failure extends Error {
     /**
-     *
      * @param {string} message
      * @param {Problem[]} problems
-     * @param {*} cause
+     * @param {*} [cause]
      */
     constructor(message, problems, cause) {
         super(message, { cause });
@@ -28,6 +30,7 @@ class Failure extends Error {
         return new Failure(this.message, Failure.dropProblemsContext(this.problems, prefix), this);
     }
     /**
+     * Copies of the problems, each context losing the prefix where it starts with it.
      * @param {Problem[]} problems
      * @param {string} prefix
      * @returns {Problem[]}
@@ -38,21 +41,6 @@ class Failure extends Error {
             return { type, context: nctx, reason, details };
         });
     }
-    /**
-     * The one reading of a failure: its problems' reasons, one per line, or
-     * the fallback when the value carries none. An empty problems array
-     * carries nothing: the failure's own message reads instead.
-     *
-     * @param {any} cause
-     * @param {string|null} [fallback]
-     * @returns {string}
-     */
-    static problemsText(cause, fallback = null) {
-        if (cause?.problems?.length) {
-            return cause.problems.map((p) => `${p.reason}`).join('\n');
-        }
-        return fallback ?? `${cause?.message ?? cause}`;
-    }
 }
 
 /**
@@ -62,6 +50,10 @@ class Failure extends Error {
  * of corrupting silently.
  */
 class Base64 {
+    /** The RFC 4648 alphabet, with `+` and `/`. */
+    static STANDARD = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+    /** The RFC 4648 url and filename safe alphabet, with `-` and `_`. */
+    static URL_SAFE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
     /**
      * @param {ArrayBuffer} arrayBuffer
      * @param {string} [dialect] one of Base64.STANDARD or Base64.URL_SAFE, URL_SAFE by default
@@ -87,14 +79,14 @@ class Base64 {
         return res;
     }
     /**
-     * @param {string} str
+     * @param {string} str padded or unpadded
      * @param {string} [dialect] one of Base64.STANDARD or Base64.URL_SAFE, URL_SAFE by default
      * @returns {ArrayBuffer}
+     * @throws on padding anywhere but the tail or longer than two, on an
+     * impossible length, and on a character outside the dialect
      */
     static decode(str, dialect) {
         const d = dialect || Base64.URL_SAFE;
-        //padding belongs at the tail only, two at most, and nothing outside the
-        //dialect decodes: reject instead of corrupting silently
         let end = str.length;
         while (end > 0 && str.charAt(end - 1) === '=') {
             --end;
@@ -116,9 +108,6 @@ class Base64 {
 
         let vi = 0;
         let si = 0;
-        //every group yields three bytes, but a padded input stops short of the last
-        //one or two: writing them anyway would rely on typed arrays dropping writes
-        //past their length
         while (vi < nbytes) {
             const v1 = d.indexOf(unpadded.charAt(si++));
             const v2 = d.indexOf(unpadded.charAt(si++));
@@ -139,16 +128,14 @@ class Base64 {
     }
 }
 
-Base64.STANDARD = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-Base64.URL_SAFE = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
-
 /**
  * Hex encoding and decoding over byte sequences, lowercase by default.
  */
 class Hex {
     /**
-     * @param {string} hex
+     * @param {string} hex either case
      * @returns {Uint8Array}
+     * @throws on an odd length or a character that is not a hex digit
      */
     static decode(hex) {
         if (hex.length % 2 !== 0) {
@@ -165,12 +152,20 @@ class Hex {
         });
     }
     /**
-     * @param {Iterable<number>} bytes
-     * @param {boolean} [upper]
-     * @returns {string}
+     * @param {Iterable<number>|ArrayBuffer|ArrayBufferView} bytes octets, or
+     * a buffer or view read as its bytes
+     * @param {boolean} [upper] uppercase digits instead of lowercase
+     * @returns {string} two digits per byte
      */
     static encode(bytes, upper) {
-        return Array.from(bytes)
+        let octets = /** @type {Iterable<number>} */ (bytes);
+        if (bytes instanceof ArrayBuffer) {
+            octets = new Uint8Array(bytes);
+        }
+        if (ArrayBuffer.isView(bytes)) {
+            octets = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        }
+        return Array.from(octets)
             .map((b) => b.toString(16))
             .map((b) => (upper ? b.toUpperCase() : b))
             .map((o) => o.padStart(2, '0'))
@@ -186,19 +181,22 @@ class MediaType {
         this.#type = type;
         this.#subtype = subtype;
     }
+    /** @returns {string} `type/subtype`, lowercase */
     get normalized() {
         return `${this.#type}/${this.#subtype}`;
     }
+    /** @returns {string} */
     get type() {
         return this.#type;
     }
+    /** @returns {string} */
     get subtype() {
         return this.#subtype;
     }
     /**
      * Parses a Content-Type header value into its type/subtype pair, dropping any parameter.
      * @param {string|null|undefined} v
-     * @returns
+     * @returns {MediaType} `unknown/unknown` for a missing or malformed value
      */
     static parse(v) {
         if (!v) {
@@ -248,28 +246,36 @@ class HttpClientError extends Failure {
         return new HttpClientError(this.message, this.status, Failure.dropProblemsContext(this.problems, prefix), this);
     }
     /**
-     * One problem of the client's own making: the four the client mints are the
-     * same shape, and the server's arrive already shaped from the wire.
+     * A problem with no context and no details.
      * @param {string} type
      * @param {string} reason
+     * @returns {{ type: string; context: null; reason: string; details: null; }}
      */
     static problem(type, reason) {
         return { type, context: null, reason, details: null };
     }
     /**
-     * Creates a client failure carrying no status, wrapping the cause and its message.
+     * A failure with status 0 and one problem of the given type, whose reason is
+     * the cause's message.
      * @param {string} type
      * @param {any} cause
-     * @returns
+     * @returns {HttpClientError}
      */
     static of(type, cause) {
         const reason = String(cause?.message ?? cause ?? 'unknown failure');
         return new HttpClientError(reason, 0, [HttpClientError.problem(type, reason)], cause);
     }
     /**
-     * Creates an HttpClientError from a Response.
-     * @param {Response} response
-     * @returns an HttpClientError
+     * The failure an error response stands for, keeping its status. An
+     * `application/failures+json` body is the problems list; an
+     * `application/problem+json` body contributes its non-empty `problems`
+     * array, or one GENERIC_PROBLEM made of whichever of its title and detail
+     * it has. Any other body is one GENERIC_PROBLEM carrying the body text. A
+     * json body that does not decode, or decodes to the wrong shape or to an
+     * empty failures array, and a body that cannot be read at all, each
+     * become one GENERIC_PROBLEM saying so.
+     * @param {Response} response consumed
+     * @returns {Promise<HttpClientError>}
      */
     static async fromResponse(response) {
         switch (MediaType.parse(response.headers.get('Content-Type')).normalized) {
@@ -279,7 +285,10 @@ class HttpClientError extends Failure {
                     return HttpClientError.#undecodable(response);
                 }
                 if (!Array.isArray(data)) {
-                    return HttpClientError.#undecodable(response, 'as a failures array');
+                    return HttpClientError.#undecodable(response, 'does not decode as a failures array');
+                }
+                if (data.length === 0) {
+                    return HttpClientError.#undecodable(response, 'carries no failures');
                 }
                 const message = `${response.status} ${response.statusText}: ${data.length} failures`;
                 return new HttpClientError(message, response.status, data);
@@ -290,13 +299,18 @@ class HttpClientError extends Failure {
                     return HttpClientError.#undecodable(response);
                 }
                 if (typeof data !== 'object' || data === null || Array.isArray(data)) {
-                    return HttpClientError.#undecodable(response, 'as a problem object');
+                    return HttpClientError.#undecodable(response, 'does not decode as a problem object');
                 }
-                const message = `${response.status} ${response.statusText}: ${data.title} ${data.detail}`;
+                const text = [data.title, data.detail].filter((part) => part !== undefined && part !== null).join(' ');
+                const message = text
+                    ? `${response.status} ${response.statusText}: ${text}`
+                    : `${response.status} ${response.statusText}`;
                 return new HttpClientError(
                     message,
                     response.status,
-                    data.problems || [HttpClientError.problem('GENERIC_PROBLEM', message)],
+                    Array.isArray(data.problems) && data.problems.length > 0
+                        ? data.problems
+                        : [HttpClientError.problem('GENERIC_PROBLEM', message)],
                 );
             }
             default: {
@@ -304,24 +318,17 @@ class HttpClientError extends Failure {
             }
         }
     }
-    /** marks a body whose json() rejected, telling it apart from a body decoding to json null */
     static #unreadable = Symbol('unreadable body');
     /**
-     * A json body that failed to decode, or that decoded to something other than
-     * the declared contract, has consumed its stream: there is no text left to
-     * embed, the status, the declared media type and the shape are the report.
      * @param {Response} response
-     * @param {string} [as] - what the body does not decode as
+     * @param {string} [flaw] what is wrong with the body
      */
-    static #undecodable(response, as = 'as json') {
+    static #undecodable(response, flaw = 'does not decode as json') {
         const mediaType = MediaType.parse(response.headers.get('Content-Type')).normalized;
-        const message = `${response.status} ${response.statusText}: the ${mediaType} body does not decode ${as}`;
+        const message = `${response.status} ${response.statusText}: the ${mediaType} body ${flaw}`;
         return new HttpClientError(message, response.status, [HttpClientError.problem('GENERIC_PROBLEM', message)]);
     }
     static async #generic(response) {
-        //a body that cannot be read (the connection cut mid-body) must not
-        //masquerade as a connection problem: the response was served, its
-        //status is the report
         const text = await response.text().catch(() => null);
         const message =
             text === null
@@ -334,19 +341,14 @@ class HttpClientError extends Failure {
 const metaContent = (name) =>
     globalThis.document?.querySelector(`meta[name="${name}"]`)?.getAttribute('content') ?? undefined;
 
-/**
- * @implements {HttpInterceptor}
- */
 /**
  * Sends the csrf header named by the page's `_csrf_header` meta, with the token
  * from `_csrf`. Both are read per request, so metas replaced after the client
  * was built are honoured, and the header is sent to the page's own origin only.
+ * @implements {HttpInterceptor}
  */
 class CsrfTokenInterceptor {
     async intercept(url, request, chain) {
-        //the token is the page's own: it travels to the page's origin only, and it
-        //is read at request time, so metas landed after the client was built (a
-        //login flow) are honored without a rebuild
         if (url.origin !== (globalThis.window?.location?.origin ?? url.origin)) {
             return await chain.proceed(url, request);
         }
@@ -358,13 +360,12 @@ class CsrfTokenInterceptor {
         return await chain.proceed(url, request);
     }
 }
-/**
- * @implements {HttpInterceptor}
- */
 /**
  * Navigates to a login url when a response comes back 401. The promise it
  * returns never settles, so callers keep waiting while the page unloads
- * instead of showing a failure nobody will be present to read.
+ * instead of showing a failure; where the navigation is blocked, as by a
+ * beforeunload prompt, they stay pending until the page leaves.
+ * @implements {HttpInterceptor}
  */
 class RedirectOnUnauthorizedInterceptor {
     #redirectUri;
@@ -378,10 +379,6 @@ class RedirectOnUnauthorizedInterceptor {
         const response = await chain.proceed(url, request);
         if (response.status === 401) {
             window.location.href = this.#redirectUri;
-            //the page is navigating away: a promise that never settles keeps the
-            //callers' spinners up instead of flashing a failure nobody will read.
-            //Where the navigation is blocked (a beforeunload gate), they stay
-            //pending until the page actually leaves
             return new Promise(() => {});
         }
         return response;
@@ -397,38 +394,48 @@ class HttpClientBuilder {
     constructor() {
         this.#interceptors = [];
     }
+    /**
+     * Adds the CsrfTokenInterceptor.
+     * @returns {HttpClientBuilder} this builder
+     */
     withCsrfToken() {
         this.#interceptors.push(new CsrfTokenInterceptor());
         return this;
     }
+    /**
+     * Adds the RedirectOnUnauthorizedInterceptor.
+     * @param {string} redirectUri where a 401 navigates to
+     * @returns {HttpClientBuilder} this builder
+     */
     withRedirectOnUnauthorized(redirectUri) {
         this.#interceptors.push(new RedirectOnUnauthorizedInterceptor(redirectUri));
         return this;
     }
     /**
+     * Adds interceptors, run in the order given after the ones added before.
      * @param {...HttpInterceptor} interceptors
+     * @returns {HttpClientBuilder} this builder
      */
     withInterceptors(...interceptors) {
         this.#interceptors.push(...interceptors);
         return this;
     }
+    /** @returns {HttpClient} a client running the interceptors added so far */
     build() {
-        return new HttpClient(this.#interceptors);
+        return new HttpClient([...this.#interceptors]);
     }
 }
 
 /**
+ * The last interceptor in every chain, performing the request with fetch. A
+ * fetch rejection becomes an HttpClientError with a CONNECTION_PROBLEM.
  * @implements {HttpInterceptor}
  */
-/** The last interceptor in every chain: the one that performs the request. */
 class HttpCall {
     async intercept(url, request, chain) {
         try {
             return await fetch(url, request);
         } catch (ex) {
-            //the one place a connection problem is a connection problem: the
-            //transport itself refused to deliver. Everything above this is code,
-            //and code that throws has a different story to tell
             throw HttpClientError.of('CONNECTION_PROBLEM', ex);
         }
     }
@@ -439,19 +446,18 @@ class HttpInterceptorChain {
     #interceptors;
     #current;
     /**
-     *
      * @param {HttpInterceptor[]} interceptors
-     * @param {number} current
+     * @param {number} current the index of the interceptor `proceed` runs
      */
     constructor(interceptors, current) {
         this.#interceptors = interceptors;
         this.#current = current;
     }
     /**
-     *
+     * Runs the next interceptor.
      * @param {URL} url
      * @param {RequestInit} request
-     * @returns {Promise<Response>} the response
+     * @returns {Promise<Response>}
      */
     async proceed(url, request) {
         const interceptor = this.#interceptors[this.#current];
@@ -485,12 +491,14 @@ class HttpClient {
         this.#interceptors = interceptors || [];
     }
     /**
-     * Performs an HTTP exchange.
-     * @async
-     * @param {string} uri - the (possibly relative) request url
-     * @param {RequestInit|undefined} options - fetch options
-     * @param {HttpInterceptor[]|undefined} interceptors - the HttpInterceptors to be registered for this exchange.
-     * @returns {Promise<Response>} the response
+     * Performs an HTTP exchange through the client's interceptors, then the
+     * given ones.
+     * @param {string} uri the request url, relative to the page's
+     * @param {RequestInit|undefined} options fetch options
+     * @param {HttpInterceptor[]|undefined} interceptors run for this exchange only
+     * @returns {Promise<Response>} the response, whatever its status; rejecting
+     * with an HttpClientError CONNECTION_PROBLEM when the transport fails, or
+     * with what an interceptor throws
      */
     async exchange(uri, options, interceptors) {
         const is = [...this.#interceptors, ...(interceptors || []), new HttpCall()];
@@ -500,58 +508,58 @@ class HttpClient {
         return await chain.proceed(url, request);
     }
     /**
-     * Creates a request builder.
-     * @param {string} method - the HTTP method to be used
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a request with any method.
+     * @param {string} method
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     request(method, uri) {
         return HttpRequestBuilder.create(this, method, uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a GET request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     get(uri) {
         return HttpRequestBuilder.create(this, 'GET', uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a HEAD request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     head(uri) {
         return HttpRequestBuilder.create(this, 'HEAD', uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a POST request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     post(uri) {
         return HttpRequestBuilder.create(this, 'POST', uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a PUT request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     put(uri) {
         return HttpRequestBuilder.create(this, 'PUT', uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a PATCH request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     patch(uri) {
         return HttpRequestBuilder.create(this, 'PATCH', uri);
     }
     /**
-     * Creates a request builder.
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the request builder
+     * Starts a DELETE request.
+     * @param {string} uri the request url, relative to the page's; a query and a fragment in it are kept
+     * @returns {HttpRequestBuilder}
      */
     delete(uri) {
         return HttpRequestBuilder.create(this, 'DELETE', uri);
@@ -562,7 +570,7 @@ class HttpClient {
  * Reads the response body as the given type, wrapping a failed read as an UNMARSHALING_PROBLEM.
  * @param {Response} response
  * @param {'text'|'json'|'blob'|'arrayBuffer'} type
- * @returns
+ * @returns {Promise<any>}
  */
 const unmarshal = async (response, type) => {
     try {
@@ -573,9 +581,7 @@ const unmarshal = async (response, type) => {
 };
 
 /**
- * Yields the entries of a headers or params initializer preserving nullish values:
- * normalizing through `Headers`/`URLSearchParams` first would stringify them to
- * "null"/"undefined" instead of removing the key.
+ * The entries of a headers or params initializer with nullish values kept as they are.
  * @param {any} source
  * @returns {Iterable<[string, any]>}
  */
@@ -609,15 +615,14 @@ class HttpRequestBuilder {
     #interceptors;
     #fragment;
     /**
-     * Creates an HttpRequestBuilder.
+     * A builder for the url: its query becomes the initial params, split at the
+     * first `?`, and its fragment, from the first `#`, is kept for the final url.
      * @param {HttpClient} client
-     * @param {string} method - the HTTP method to be used
-     * @param {string} uri - the (possibly relative) request url
-     * @returns {HttpRequestBuilder} the builder
+     * @param {string} method
+     * @param {string} uri
+     * @returns {HttpRequestBuilder}
      */
     static create(client, method, uri) {
-        //'/a#frag?p=1' parses as hash '#frag?p=1' with an empty query, and a '?'
-        //may appear in a query itself: only the first of each splits
         const hashIndex = uri.indexOf('#');
         const fragment = hashIndex === -1 ? '' : uri.slice(hashIndex);
         const withoutFragment = hashIndex === -1 ? uri : uri.slice(0, hashIndex);
@@ -635,10 +640,9 @@ class HttpRequestBuilder {
         );
     }
     /**
-     * Creates an HttpRequestBuilder.
      * @param {HttpClient} client
-     * @param {string} method - the HTTP method to be used
-     * @param {string} uri - the (possibly relative) request url
+     * @param {string} method
+     * @param {string} uri the url without query and fragment
      * @param {URLSearchParams} params
      * @param {Headers} headers
      * @param {any} body
@@ -658,24 +662,20 @@ class HttpRequestBuilder {
         this.#fragment = fragment;
     }
     /**
-     * Add all passed headers to the request, overriding existing ones if that key already exists. Null and undefined values cause the key to be removed.
+     * Sets each header, replacing a header of the same name; a null or undefined value removes it.
      * @param {HeadersInit|Record<string,string|null|undefined>} hs
      * @returns {HttpRequestBuilder} this builder
      */
     headers(hs) {
         for (const [k, v] of rawEntries(hs)) {
-            if (v == null) {
-                this.#headers.delete(k);
-            } else {
-                this.#headers.set(k, v);
-            }
+            this.header(k, v);
         }
         return this;
     }
     /**
-     * Adds an header to the request, overriding it if it already exists. Null and undefined values cause the key to be removed
+     * Sets a header, replacing one of the same name; a null or undefined value removes it.
      * @param {string} k
-     * @param {string} v
+     * @param {string|null|undefined} v
      * @returns {HttpRequestBuilder} this builder
      */
     header(k, v) {
@@ -687,7 +687,7 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Add all query parameters to the request, overriding existing ones if that key already exists. Null and undefined values cause the key to be removed
+     * Sets each query parameter in place, replacing a parameter of the same name; a null or undefined value removes it.
      * @param {URLSearchParams|Record<string,string|null|undefined>|string[][]|string} ps
      * @returns {HttpRequestBuilder} this builder
      */
@@ -702,20 +702,14 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Adds a query parameter to the request, overriding it if it already exists. An empty list, or one carrying only null and undefined values, causes the key to be removed; nullish entries among real values are skipped.
+     * Sets a query parameter to the values given, as repeated entries moved to the end of the query; nullish values are skipped, and none left removes the parameter.
      * @param {string} k
      * @param {...string} vs
      * @returns {HttpRequestBuilder} this builder
      */
     param(k, ...vs) {
-        //overriding, as header, headers and params all do: pass every value in one
-        //call to get a multi valued parameter
         this.#params.delete(k);
-        const values = vs.filter((v) => v != null);
-        if (values.length === 0) {
-            return this;
-        }
-        for (const v of values) {
+        for (const v of vs.filter((v) => v != null)) {
             this.#params.append(k, v);
         }
         return this;
@@ -750,6 +744,7 @@ class HttpRequestBuilder {
      * Sets the request body as a FormData configured using the callback.
      * `Content-Type: multipart/form-data` header is automatically added by fetch if not explicitly set.
      * @param {(c: HttpMultipartRequestCustomizer) => void} callback
+     * @returns {HttpRequestBuilder} this builder
      */
     multipart(callback) {
         const formData = new FormData();
@@ -759,7 +754,7 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Sets a fetch options for the request.
+     * Merges fetch options into the request's.
      * @param {Omit<RequestInit,"headers"|"method"|"body">} kvs
      * @returns {HttpRequestBuilder} this builder
      */
@@ -780,8 +775,8 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Adds interceptors to the request.
-     * @param {[HttpInterceptor]} is - the interceptor to be registered
+     * Adds interceptors run for this request only, after the client's.
+     * @param {HttpInterceptor[]} is
      * @returns {HttpRequestBuilder} this builder
      */
     interceptors(is) {
@@ -791,8 +786,8 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Adds an interceptor to the request.
-     * @param {HttpInterceptor} i - the interceptor to be registered
+     * Adds one interceptor run for this request only, after the client's.
+     * @param {HttpInterceptor} i
      * @returns {HttpRequestBuilder} this builder
      */
     interceptor(i) {
@@ -800,8 +795,8 @@ class HttpRequestBuilder {
         return this;
     }
     /**
-     * Performs an HTTP exchange using the configured client, request and interceptors.
-     * @returns {Promise<Response>} the response
+     * Sends the request and answers the Response, whatever its status.
+     * @returns {Promise<Response>} rejecting as `HttpClient.exchange` does
      */
     async exchange() {
         const query = this.#params.size ? `?${this.#params}` : '';
@@ -814,8 +809,12 @@ class HttpRequestBuilder {
         return await this.#client.exchange(`${this.#uri}${query}${this.#fragment}`, opts, this.#interceptors);
     }
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptors throwing a failure when response status is not in the 200-299 range.
-     * @returns {Promise<Response>} the response
+     * Sends the request and answers the Response when its status is 200-299.
+     * Always rejects with an HttpClientError: `HttpClientError.fromResponse`
+     * for an error status, CONNECTION_PROBLEM for a transport failure, and
+     * UNEXPECTED_PROBLEM, carrying the error as its cause, for anything an
+     * interceptor throws that is not already a Failure.
+     * @returns {Promise<Response>}
      */
     async fetch() {
         try {
@@ -828,45 +827,40 @@ class HttpRequestBuilder {
             if (ex instanceof Failure) {
                 throw ex;
             }
-            //fetch() answers a Failure whatever happened, so a caller reading
-            //`problems` never has to test the shape first. What reaches here is
-            //not the transport, which labels its own failure below the chain: it
-            //is a throw from the chain's own code, carried as the cause
             throw HttpClientError.of('UNEXPECTED_PROBLEM', ex);
         }
     }
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptors throwing a failure when response status is not in the 200-299 range.
-     * @returns {Promise<string>} the response body, as text
+     * `fetch()`, then the body as text; a body that cannot be read rejects with UNMARSHALING_PROBLEM.
+     * @returns {Promise<string>}
      */
     async fetchText() {
         const response = await this.fetch();
         return await unmarshal(response, 'text');
     }
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptors throwing a failure when response status is not in the 200-299 range.
-     * A 204 yields null without reading the body; any other empty body is an unmarshaling failure.
-     * @returns {Promise<any>} the response body, deserialized as JSON
+     * `fetch()`, then the body parsed as json. A 204 yields null without reading
+     * the body; any other body that does not parse rejects with UNMARSHALING_PROBLEM.
+     * @returns {Promise<any>}
      */
     async fetchJson() {
         const response = await this.fetch();
         if (response.status === 204) {
-            //a 204 declares no content: there is no body to decode
             return null;
         }
         return await unmarshal(response, 'json');
     }
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptors throwing a failure when response status is not in the 200-299 range.
-     * @returns {Promise<Blob>} the response body, as a Blob
+     * `fetch()`, then the body as a Blob; a body that cannot be read rejects with UNMARSHALING_PROBLEM.
+     * @returns {Promise<Blob>}
      */
     async fetchBlob() {
         const response = await this.fetch();
         return await unmarshal(response, 'blob');
     }
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptors throwing a failure when response status is not in the 200-299 range.
-     * @returns {Promise<ArrayBuffer>} the response body, as an ArrayBuffer
+     * `fetch()`, then the body as an ArrayBuffer; a body that cannot be read rejects with UNMARSHALING_PROBLEM.
+     * @returns {Promise<ArrayBuffer>}
      */
     async fetchArrayBuffer() {
         const response = await this.fetch();
@@ -877,10 +871,7 @@ class HttpRequestBuilder {
 /** Builds a multipart body: text fields, json parts, and single or repeated blobs. */
 class HttpMultipartRequestCustomizer {
     #formData;
-    /**
-     *
-     * @param {FormData} formData
-     */
+    /** @param {FormData} formData the body being built */
     constructor(formData) {
         this.#formData = formData;
     }
@@ -888,33 +879,30 @@ class HttpMultipartRequestCustomizer {
      * Appends a value to the FormData.
      * @param {string} name
      * @param {*} value
-     * @returns this builder
+     * @returns {HttpMultipartRequestCustomizer} this builder
      */
     field(name, value) {
         this.#formData.append(name, value);
         return this;
     }
     /**
-     * Appends a Blob to the FormData.
-     * If `filename` is omitted, FormData defaults are applied:
-     * The default filename for Blob objects is "blob";
-     * The default filename for File objects is the file's filename.
+     * Appends a Blob to the FormData. Without a filename a File keeps its own
+     * and any other Blob is named "blob".
      * @param {string} name
      * @param {Blob} value
-     * @param {string|undefined} filename
-     * @returns this builder
+     * @param {string} [filename]
+     * @returns {HttpMultipartRequestCustomizer} this builder
      */
     blob(name, value, filename) {
         this.#formData.append(name, value, filename);
         return this;
     }
     /**
-     * Appends multiple Blobs to the FormData with the same name.
-     * The default filename for Blob objects is "blob";
-     * The default filename for File objects is the file's filename.
+     * Appends each Blob under the same name, a File keeping its own filename and
+     * any other Blob named "blob".
      * @param {string} name
      * @param {Blob[]} values
-     * @returns this builder
+     * @returns {HttpMultipartRequestCustomizer} this builder
      */
     blobs(name, values) {
         for (const v of values) {
@@ -923,11 +911,11 @@ class HttpMultipartRequestCustomizer {
         return this;
     }
     /**
-     * Appends a JSON serialized blob to the FormData.
+     * Appends the value serialized as an `application/json` blob.
      * @param {string} name
      * @param {any} value
-     * @param {string|undefined} filename
-     * @returns this builder
+     * @param {string} [filename]
+     * @returns {HttpMultipartRequestCustomizer} this builder
      */
     json(name, value, filename) {
         const blob = new Blob([JSON.stringify(value)], { type: 'application/json' });