@optionfactory/fml 9.0.0-rc2 → 9.0.0-rc21

package/dist/httpc.d.mts

@@ -5,6 +5,9 @@ export type Problem = {
     details: any | null;
 };
 /**
+ * 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
  */
 /**
@@ -15,12 +18,11 @@ export type Problem = {
 declare class Failure extends Error {
     problems: Problem[];
     /**
-     *
      * @param {string} message
      * @param {Problem[]} problems
-     * @param {*} cause
+     * @param {*} [cause]
      */
-    constructor(message: string, problems: Problem[], cause: any);
+    constructor(message: string, problems: Problem[], cause?: any);
     /**
      * Returns a copy whose problems' contexts have the prefix removed, so a
      * caller can rethrow namespaced problems as its own.
@@ -29,21 +31,12 @@ declare class Failure extends Error {
      */
     dropping(prefix: string): Failure;
     /**
+     * Copies of the problems, each context losing the prefix where it starts with it.
      * @param {Problem[]} problems
      * @param {string} prefix
      * @returns {Problem[]}
      */
     static dropProblemsContext(problems: Problem[], prefix: string): Problem[];
-    /**
-     * 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: any, fallback?: string | null): string;
 }
 /**
  * Base64 encoding and decoding over ArrayBuffers, in the STANDARD and URL_SAFE
@@ -52,6 +45,10 @@ declare class Failure extends Error {
  * of corrupting silently.
  */
 declare class Base64 {
+    /** The RFC 4648 alphabet, with `+` and `/`. */
+    static STANDARD: string;
+    /** The RFC 4648 url and filename safe alphabet, with `-` and `_`. */
+    static URL_SAFE: string;
     /**
      * @param {ArrayBuffer} arrayBuffer
      * @param {string} [dialect] one of Base64.STANDARD or Base64.URL_SAFE, URL_SAFE by default
@@ -59,29 +56,28 @@ declare class Base64 {
      */
     static encode(arrayBuffer: ArrayBuffer, dialect?: string): string;
     /**
-     * @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: string, dialect?: string): ArrayBuffer;
 }
-declare namespace Base64 {
-    var STANDARD: string;
-    var URL_SAFE: string;
-}
 /**
  * Hex encoding and decoding over byte sequences, lowercase by default.
  */
 declare 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: string): Uint8Array;
     /**
      * @param {Iterable<number>} bytes
-     * @param {boolean} [upper]
-     * @returns {string}
+     * @param {boolean} [upper] uppercase digits instead of lowercase
+     * @returns {string} two digits per byte
      */
     static encode(bytes: Iterable<number>, upper?: boolean): string;
 }
@@ -89,13 +85,16 @@ declare class Hex {
 declare class MediaType {
     #private;
     constructor(type: any, subtype: any);
+    /** @returns {string} `type/subtype`, lowercase */
     get normalized(): string;
-    get type(): any;
-    get subtype(): any;
+    /** @returns {string} */
+    get type(): string;
+    /** @returns {string} */
+    get subtype(): string;
     /**
      * 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: string | null | undefined): MediaType;
 }
@@ -138,10 +137,10 @@ declare class HttpClientError extends Failure {
      */
     dropping(prefix: string): HttpClientError;
     /**
-     * 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: string, reason: string): {
         type: string;
@@ -150,16 +149,23 @@ declare class HttpClientError extends Failure {
         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: string, cause: any): HttpClientError;
     /**
-     * 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 `problems`, or one
+     * GENERIC_PROBLEM made of its title and detail. Any other body is one
+     * GENERIC_PROBLEM carrying the body text. A json body that does not decode,
+     * or decodes to the wrong shape, and a body that cannot be read at all,
+     * each become one GENERIC_PROBLEM saying so.
+     * @param {Response} response consumed
+     * @returns {Promise<HttpClientError>}
      */
     static fromResponse(response: Response): Promise<HttpClientError>;
 }
@@ -167,28 +173,39 @@ declare class HttpClientError extends Failure {
 declare class HttpClientBuilder {
     #private;
     constructor();
-    withCsrfToken(): this;
-    withRedirectOnUnauthorized(redirectUri: any): this;
     /**
+     * Adds the CsrfTokenInterceptor.
+     * @returns {HttpClientBuilder} this builder
+     */
+    withCsrfToken(): HttpClientBuilder;
+    /**
+     * Adds the RedirectOnUnauthorizedInterceptor.
+     * @param {string} redirectUri where a 401 navigates to
+     * @returns {HttpClientBuilder} this builder
+     */
+    withRedirectOnUnauthorized(redirectUri: string): HttpClientBuilder;
+    /**
+     * Adds interceptors, run in the order given after the ones added before.
      * @param {...HttpInterceptor} interceptors
+     * @returns {HttpClientBuilder} this builder
      */
-    withInterceptors(...interceptors: HttpInterceptor[]): this;
+    withInterceptors(...interceptors: HttpInterceptor[]): HttpClientBuilder;
+    /** @returns {HttpClient} a client running the interceptors added so far */
     build(): HttpClient;
 }
 /** One request's position in the interceptor list: `proceed` runs the next interceptor, the last of which performs the request. */
 declare class HttpInterceptorChain {
     #private;
     /**
-     *
      * @param {HttpInterceptor[]} interceptors
-     * @param {number} current
+     * @param {number} current the index of the interceptor `proceed` runs
      */
     constructor(interceptors: HttpInterceptor[], current: number);
     /**
-     *
+     * Runs the next interceptor.
      * @param {URL} url
      * @param {RequestInit} request
-     * @returns {Promise<Response>} the response
+     * @returns {Promise<Response>}
      */
     proceed(url: URL, request: RequestInit): Promise<Response>;
 }
@@ -210,55 +227,57 @@ declare class HttpClient {
      */
     constructor(interceptors: HttpInterceptor[] | undefined);
     /**
-     * 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
      */
     exchange(uri: string, options: RequestInit | undefined, interceptors: HttpInterceptor[] | undefined): Promise<Response>;
     /**
-     * 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: string, uri: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
     /**
-     * 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: string): HttpRequestBuilder;
 }
@@ -271,18 +290,18 @@ declare class HttpClient {
 declare class HttpRequestBuilder {
     #private;
     /**
-     * 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: HttpClient, method: string, uri: string): 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
@@ -292,26 +311,26 @@ declare class HttpRequestBuilder {
      */
     constructor(client: HttpClient, method: string, uri: string, params: URLSearchParams, headers: Headers, body: any, options: Omit<RequestInit, "headers" | "method" | "body">, interceptors: HttpInterceptor[], fragment?: string);
     /**
-     * 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: HeadersInit | Record<string, string | null | undefined>): HttpRequestBuilder;
     /**
-     * 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: string, v: string): HttpRequestBuilder;
+    header(k: string, v: string | null | undefined): HttpRequestBuilder;
     /**
-     * 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
      */
     params(ps: URLSearchParams | Record<string, string | null | undefined> | string[][] | string): HttpRequestBuilder;
     /**
-     * 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
@@ -336,10 +355,11 @@ declare 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: (c: HttpMultipartRequestCustomizer) => void): this;
+    multipart(callback: (c: HttpMultipartRequestCustomizer) => void): HttpRequestBuilder;
     /**
-     * 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
      */
@@ -352,92 +372,90 @@ declare class HttpRequestBuilder {
      */
     option(k: keyof Omit<RequestInit, "headers" | "method" | "body">, v: any): HttpRequestBuilder;
     /**
-     * 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: [HttpInterceptor]): HttpRequestBuilder;
+    interceptors(is: HttpInterceptor[]): HttpRequestBuilder;
     /**
-     * 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: HttpInterceptor): HttpRequestBuilder;
     /**
-     * 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
      */
     exchange(): Promise<Response>;
     /**
-     * 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>}
      */
     fetch(): Promise<Response>;
     /**
-     * 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>}
      */
     fetchText(): Promise<string>;
     /**
-     * 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>}
      */
     fetchJson(): Promise<any>;
     /**
-     * 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>}
      */
     fetchBlob(): Promise<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>}
      */
     fetchArrayBuffer(): Promise<ArrayBuffer>;
 }
 /** Builds a multipart body: text fields, json parts, and single or repeated blobs. */
 declare class HttpMultipartRequestCustomizer {
     #private;
-    /**
-     *
-     * @param {FormData} formData
-     */
+    /** @param {FormData} formData the body being built */
     constructor(formData: FormData);
     /**
      * Appends a value to the FormData.
      * @param {string} name
      * @param {*} value
-     * @returns this builder
+     * @returns {HttpMultipartRequestCustomizer} this builder
      */
-    field(name: string, value: any): this;
+    field(name: string, value: any): HttpMultipartRequestCustomizer;
     /**
-     * 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: string, value: Blob, filename: string | undefined): this;
+    blob(name: string, value: Blob, filename?: string): HttpMultipartRequestCustomizer;
     /**
-     * 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: string, values: Blob[]): this;
+    blobs(name: string, values: Blob[]): HttpMultipartRequestCustomizer;
     /**
-     * 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: string, value: any, filename: string | undefined): this;
+    json(name: string, value: any, filename?: string): HttpMultipartRequestCustomizer;
 }
 export { Base64, Failure, Hex, HttpClient, HttpClientBuilder, HttpClientError, HttpInterceptorChain, HttpMultipartRequestCustomizer, HttpRequestBuilder, MediaType };