@optionfactory/fml 8.0.3 → 9.0.0-rc1

package/dist/httpc.d.mts

@@ -7,6 +7,11 @@ export type Problem = {
 /**
  * @typedef {{ type: string; context: string?; reason: string; details: any?; }} Problem
  */
+/**
+ * An error carrying a list of problems rather than one message. A problem's
+ * `context` names the field it belongs to, which is what lets a form show each
+ * one beside its own input instead of in a banner.
+ */
 declare class Failure extends Error {
     problems: Problem[];
     /**
@@ -16,21 +21,71 @@ declare class Failure extends Error {
      * @param {*} cause
      */
     constructor(message: string, problems: Problem[], cause: any);
-    dropping(prefix: any): Failure;
-    static dropProblemsContext(problems: any, prefix: any): any;
+    /**
+     * Returns a copy whose problems' contexts have the prefix removed, so a
+     * caller can rethrow namespaced problems as its own.
+     * @param {string} prefix
+     * @returns {Failure}
+     */
+    dropping(prefix: string): Failure;
+    /**
+     * @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
+ * alphabets. The encoder never emits padding; the decoder accepts both padded
+ * and unpadded input, and rejects anything it cannot decode faithfully instead
+ * of corrupting silently.
+ */
 declare class Base64 {
-    static encode(arrayBuffer: any, dialect: any): string;
-    static decode(str: any, dialect: any): ArrayBuffer;
+    /**
+     * @param {ArrayBuffer} arrayBuffer
+     * @param {string} [dialect] one of Base64.STANDARD or Base64.URL_SAFE, URL_SAFE by default
+     * @returns {string} the unpadded encoding
+     */
+    static encode(arrayBuffer: ArrayBuffer, dialect?: string): string;
+    /**
+     * @param {string} str
+     * @param {string} [dialect] one of Base64.STANDARD or Base64.URL_SAFE, URL_SAFE by default
+     * @returns {ArrayBuffer}
+     */
+    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 {
-    static decode(hex: any): Uint8Array<ArrayBuffer>;
-    static encode(bytes: any, upper: any): string;
+    /**
+     * @param {string} hex
+     * @returns {Uint8Array}
+     */
+    static decode(hex: string): Uint8Array;
+    /**
+     * @param {Iterable<number>} bytes
+     * @param {boolean} [upper]
+     * @returns {string}
+     */
+    static encode(bytes: Iterable<number>, upper?: boolean): string;
 }
+/** A parsed `Content-Type`: the type and subtype without the parameters, so a comparison is not defeated by a charset. */
 declare class MediaType {
     #private;
     constructor(type: any, subtype: any);
@@ -38,7 +93,7 @@ declare class MediaType {
     get type(): any;
     get subtype(): any;
     /**
-     *
+     * Parses a Content-Type header value into its type/subtype pair, dropping any parameter.
      * @param {string|null|undefined} v
      * @returns
      */
@@ -55,7 +110,13 @@ export type HttpInterceptor = {
  * @typedef {object} HttpInterceptor
  * @property {(url: URL, init: RequestInit|undefined, chain: HttpInterceptorChain) => Promise<Response>} intercept
  */
+/**
+ * A Failure from an http exchange, carrying the status that was served. Status
+ * 0 means no response was served at all: the transport failed, or a body the
+ * server did send could not be read.
+ */
 declare class HttpClientError extends Failure {
+    #private;
     status: number;
     /**
      * @param {string} message
@@ -69,9 +130,27 @@ declare class HttpClientError extends Failure {
         reason: string;
         details: any | null;
     }[], cause?: Error | undefined);
-    dropping(prefix: any): HttpClientError;
     /**
-     *
+     * Returns a copy whose problems' contexts have the prefix removed, keeping
+     * this error's status.
+     * @param {string} prefix
+     * @returns {HttpClientError}
+     */
+    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.
+     * @param {string} type
+     * @param {string} reason
+     */
+    static problem(type: string, reason: string): {
+        type: string;
+        context: null;
+        reason: string;
+        details: null;
+    };
+    /**
+     * Creates a client failure carrying no status, wrapping the cause and its message.
      * @param {string} type
      * @param {any} cause
      * @returns
@@ -84,6 +163,7 @@ declare class HttpClientError extends Failure {
      */
     static fromResponse(response: Response): Promise<HttpClientError>;
 }
+/** Collects the interceptors an HttpClient will run, in the order they are added. */
 declare class HttpClientBuilder {
     #private;
     constructor();
@@ -95,6 +175,7 @@ declare class HttpClientBuilder {
     withInterceptors(...interceptors: HttpInterceptor[]): this;
     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;
     /**
@@ -111,6 +192,11 @@ declare class HttpInterceptorChain {
      */
     proceed(url: URL, request: RequestInit): Promise<Response>;
 }
+/**
+ * Performs http requests through a fixed list of interceptors. The verbs
+ * return a request builder; `exchange` is the lower-level entry that returns
+ * the Response itself without treating an error status as a failure.
+ */
 declare class HttpClient {
     #private;
     /**
@@ -176,6 +262,12 @@ declare class HttpClient {
      */
     delete(uri: string): HttpRequestBuilder;
 }
+/**
+ * One request under construction: method, url, parameters, headers and body,
+ * with a `fetch*` method per body type. Every configuration method returns the
+ * builder, and a `fetch*` rejects with an HttpClientError for any status
+ * outside 200-299.
+ */
 declare class HttpRequestBuilder {
     #private;
     /**
@@ -196,8 +288,9 @@ declare class HttpRequestBuilder {
      * @param {any} body
      * @param {Omit<RequestInit,"headers"|"method"|"body">} options
      * @param {HttpInterceptor[]} interceptors
+     * @param {string} [fragment]
      */
-    constructor(client: HttpClient, method: string, uri: string, params: URLSearchParams, headers: Headers, body: any, options: Omit<RequestInit, "headers" | "method" | "body">, interceptors: HttpInterceptor[]);
+    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.
      * @param {HeadersInit|Record<string,string|null|undefined>} hs
@@ -218,7 +311,7 @@ declare class HttpRequestBuilder {
      */
     params(ps: URLSearchParams | Record<string, string | null | undefined> | string[][] | string): HttpRequestBuilder;
     /**
-     * Adds a query parameter to the request, overriding it if it already exists. Empty vs, or a single null or undefined value cause the key to be removed.
+     * 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.
      * @param {string} k
      * @param {...string} vs
      * @returns {HttpRequestBuilder} this builder
@@ -260,13 +353,13 @@ 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 regisered
+     * @param {[HttpInterceptor]} is - the interceptor to be registered
      * @returns {HttpRequestBuilder} this builder
      */
     interceptors(is: [HttpInterceptor]): HttpRequestBuilder;
     /**
      * Adds an interceptor to the request.
-     * @param {HttpInterceptor} i - the interceptor to be regisered
+     * @param {HttpInterceptor} i - the interceptor to be registered
      * @returns {HttpRequestBuilder} this builder
      */
     interceptor(i: HttpInterceptor): HttpRequestBuilder;
@@ -276,31 +369,33 @@ declare class HttpRequestBuilder {
      */
     exchange(): Promise<Response>;
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptos throwing a failure when response status is not in the 200-299 range.
+     * 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
      */
     fetch(): Promise<Response>;
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptos throwing a failure when response status is not in the 200-299 range.
+     * 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
      */
     fetchText(): Promise<string>;
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptos throwing a failure when response status is not in the 200-299 range.
+     * 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
      */
     fetchJson(): Promise<any>;
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptos throwing a failure when response status is not in the 200-299 range.
+     * 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
      */
     fetchBlob(): Promise<Blob>;
     /**
-     * Performs an HTTP exchange using the configured client request, and interceptos throwing a failure when response status is not in the 200-299 range.
+     * 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
      */
     fetchArrayBuffer(): Promise<ArrayBuffer>;
 }
+/** Builds a multipart body: text fields, json parts, and single or repeated blobs. */
 declare class HttpMultipartRequestCustomizer {
     #private;
     /**
@@ -344,6 +439,6 @@ declare class HttpMultipartRequestCustomizer {
      */
     json(name: string, value: any, filename: string | undefined): this;
 }
-export { Base64, Failure, Hex, HttpClient, HttpClientError, MediaType };
+export { Base64, Failure, Hex, HttpClient, HttpClientBuilder, HttpClientError, HttpInterceptorChain, HttpMultipartRequestCustomizer, HttpRequestBuilder, MediaType };
 
 export as namespace httpc;