@optionfactory/fml 9.0.0-rc3 → 9.0.0-rc31

package/dist/httpc.iife.js

@@ -2,6 +2,9 @@ var httpc = (function (exports) {
     'use strict';
 
     /**
+     * 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
      */
     /**
@@ -11,10 +14,9 @@ var httpc = (function (exports) {
      */
     class Failure extends Error {
         /**
-         *
          * @param {string} message
          * @param {Problem[]} problems
-         * @param {*} cause
+         * @param {*} [cause]
          */
         constructor(message, problems, cause) {
             super(message, { cause });
@@ -31,6 +33,7 @@ var httpc = (function (exports) {
             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[]}
@@ -41,21 +44,6 @@ var httpc = (function (exports) {
                 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}`;
-        }
     }
 
     /**
@@ -65,6 +53,10 @@ var httpc = (function (exports) {
      * 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
@@ -90,14 +82,14 @@ var httpc = (function (exports) {
             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;
@@ -119,9 +111,6 @@ var httpc = (function (exports) {
 
             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++));
@@ -142,16 +131,14 @@ var httpc = (function (exports) {
         }
     }
 
-    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) {
@@ -168,12 +155,20 @@ var httpc = (function (exports) {
             });
         }
         /**
-         * @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'))
@@ -189,19 +184,22 @@ var httpc = (function (exports) {
             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) {
@@ -251,28 +249,36 @@ var httpc = (function (exports) {
             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) {
@@ -282,7 +288,10 @@ var httpc = (function (exports) {
                         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);
@@ -293,13 +302,18 @@ var httpc = (function (exports) {
                         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: {
@@ -307,24 +321,17 @@ var httpc = (function (exports) {
                 }
             }
         }
-        /** 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
@@ -337,19 +344,14 @@ var httpc = (function (exports) {
     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);
             }
@@ -361,13 +363,12 @@ var httpc = (function (exports) {
             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;
@@ -381,10 +382,6 @@ var httpc = (function (exports) {
             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;
@@ -400,38 +397,48 @@ var httpc = (function (exports) {
         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);
             }
         }
@@ -442,19 +449,18 @@ var httpc = (function (exports) {
         #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];
@@ -488,12 +494,14 @@ var httpc = (function (exports) {
             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()];
@@ -503,58 +511,58 @@ var httpc = (function (exports) {
             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);
@@ -565,7 +573,7 @@ var httpc = (function (exports) {
      * 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 {
@@ -576,9 +584,7 @@ var httpc = (function (exports) {
     };
 
     /**
-     * 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]>}
      */
@@ -612,15 +618,14 @@ var httpc = (function (exports) {
         #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);
@@ -638,10 +643,9 @@ var httpc = (function (exports) {
             );
         }
         /**
-         * 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
@@ -661,24 +665,20 @@ var httpc = (function (exports) {
             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) {
@@ -690,7 +690,7 @@ var httpc = (function (exports) {
             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
          */
@@ -705,20 +705,14 @@ var httpc = (function (exports) {
             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;
@@ -753,6 +747,7 @@ var httpc = (function (exports) {
          * 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();
@@ -762,7 +757,7 @@ var httpc = (function (exports) {
             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
          */
@@ -783,8 +778,8 @@ var httpc = (function (exports) {
             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) {
@@ -794,8 +789,8 @@ var httpc = (function (exports) {
             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) {
@@ -803,8 +798,8 @@ var httpc = (function (exports) {
             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}` : '';
@@ -817,8 +812,12 @@ var httpc = (function (exports) {
             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 {
@@ -831,45 +830,40 @@ var httpc = (function (exports) {
                 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();
@@ -880,10 +874,7 @@ var httpc = (function (exports) {
     /** 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;
         }
@@ -891,33 +882,30 @@ var httpc = (function (exports) {
          * 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) {
@@ -926,11 +914,11 @@ var httpc = (function (exports) {
             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' });