@happy-ts/fetch-t 1.3.3 → 1.4.0

package/dist/types.d.ts

@@ -1,207 +1,432 @@
-import { AsyncResult, IOResult } from 'happy-rusty';
-
-/**
- * Name of abort error;
- */
-declare const ABORT_ERROR: "AbortError";
-/**
- * Name of timeout error;
- */
-declare const TIMEOUT_ERROR: "TimeoutError";
-
-/**
- * Represents the response of a fetch operation, encapsulating the result data or any error that occurred.
- *
- * @typeParam T - The type of the data expected in the response.
- */
-type FetchResponse<T, E = any> = AsyncResult<T, E>;
-/**
- * Defines the structure and behavior of a fetch task, including the ability to abort the task and check its status.
- *
- * @typeParam T - The type of the data expected in the response.
- */
-interface FetchTask<T> {
-    /**
-     * Aborts the fetch task, optionally with a reason for the abortion.
-     *
-     * @param reason - An optional parameter to indicate why the task was aborted.
-     */
-    abort(reason?: any): void;
-    /**
-     * Indicates whether the fetch task has been aborted.
-     */
-    readonly aborted: boolean;
-    /**
-     * The response of the fetch task, represented as an `AsyncResult`.
-     */
-    readonly response: FetchResponse<T>;
-}
-/**
- * Specifies the expected response type of the fetch request.
- */
-type FetchResponseType = 'text' | 'arraybuffer' | 'blob' | 'json';
-/**
- * Represents the progress of a fetch operation.
- */
-interface FetchProgress {
-    /**
-     * The total number of bytes to be received.
-     */
-    totalByteLength: number;
-    /**
-     * The number of bytes received so far.
-     */
-    completedByteLength: number;
-}
-/**
- * Extends the standard `RequestInit` interface from the Fetch API to include additional custom options.
- */
-interface FetchInit extends RequestInit {
-    /**
-     * Indicates whether the fetch request should be abortable.
-     */
-    abortable?: boolean;
-    /**
-     * Specifies the expected response type of the fetch request.
-     */
-    responseType?: FetchResponseType;
-    /**
-     * Specifies the maximum time in milliseconds to wait for the fetch request to complete.
-     */
-    timeout?: number;
-    /**
-     * Specifies a function to be called when the fetch request makes progress.
-     * @param progressResult - The progress of the fetch request.
-     */
-    onProgress?: (progressResult: IOResult<FetchProgress>) => void;
-    /**
-     * Specifies a function to be called when the fetch request receives a chunk of data.
-     * @param chunk - The chunk of data received.
-     */
-    onChunk?: (chunk: Uint8Array) => void;
-}
-/**
- * Represents an error that occurred during a fetch operation when the response is not ok.
- */
-declare class FetchError extends Error {
-    /**
-     * The name of the error.
-     */
-    name: string;
-    /**
-     * The status code of the response.
-     */
-    status: number;
-    constructor(message: string, status: number);
-}
-
-/**
- * Fetches a resource from the network as a text string and returns a `FetchTask` representing the operation.
- *
- * @typeParam T - The expected type of the response data.
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, including custom `FetchInit` properties.
- * @returns A `FetchTask` representing the operation with a `string` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    abortable: true;
-    responseType: 'text';
-}): FetchTask<string>;
-/**
- * Fetches a resource from the network as an ArrayBuffer and returns a `FetchTask` representing the operation.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, including custom `FetchInit` properties.
- * @returns A `FetchTask` representing the operation with an `ArrayBuffer` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    abortable: true;
-    responseType: 'arraybuffer';
-}): FetchTask<ArrayBuffer>;
-/**
- * Fetches a resource from the network as a Blob and returns a `FetchTask` representing the operation.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, including custom `FetchInit` properties.
- * @returns A `FetchTask` representing the operation with a `Blob` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    abortable: true;
-    responseType: 'blob';
-}): FetchTask<Blob>;
-/**
- * Fetches a resource from the network and parses it as JSON, returning a `FetchTask` representing the operation.
- *
- * @typeParam T - The expected type of the parsed JSON data.
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, including custom `FetchInit` properties.
- * @returns A `FetchTask` representing the operation with a response parsed as JSON.
- */
-declare function fetchT<T>(url: string | URL, init: FetchInit & {
-    abortable: true;
-    responseType: 'json';
-}): FetchTask<T>;
-/**
- * Fetches a resource from the network as a text string and returns a `FetchResponse` representing the operation.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, specifying the response type as 'text'.
- * @returns A `FetchResponse` representing the operation with a `string` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    responseType: 'text';
-}): FetchResponse<string, Error>;
-/**
- * Fetches a resource from the network as an ArrayBuffer and returns a `FetchResponse` representing the operation.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, specifying the response type as 'arraybuffer'.
- * @returns A `FetchResponse` representing the operation with an `ArrayBuffer` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    responseType: 'arraybuffer';
-}): FetchResponse<ArrayBuffer, Error>;
-/**
- * Fetches a resource from the network as a Blob and returns a `FetchResponse` representing the operation.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, specifying the response type as 'blob'.
- * @returns A `FetchResponse` representing the operation with a `Blob` response.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    responseType: 'blob';
-}): FetchResponse<Blob, Error>;
-/**
- * Fetches a resource from the network and parses it as JSON, returning a `FetchResponse` representing the operation.
- *
- * @typeParam T - The expected type of the parsed JSON data.
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, specifying the response type as 'json'.
- * @returns A `FetchResponse` representing the operation with a response parsed as JSON.
- */
-declare function fetchT<T>(url: string | URL, init: FetchInit & {
-    responseType: 'json';
-}): FetchResponse<T, Error>;
-/**
- * Fetches a resource from the network and returns a `FetchTask` representing the operation with a generic `Response`.
- *
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, indicating that the operation should be abortable.
- * @returns A `FetchTask` representing the operation with a generic `Response`.
- */
-declare function fetchT(url: string | URL, init: FetchInit & {
-    abortable: true;
-}): FetchTask<Response>;
-/**
- * Fetches a resource from the network and returns a `FetchResponse` or `FetchTask` based on the provided options.
- *
- * @typeParam T - The expected type of the response data when not using a specific `responseType`.
- * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
- * @param init - Additional options for the fetch operation, including custom `FetchInit` properties.
- * @returns A `FetchResponse` representing the operation with a `Response` object.
- */
-declare function fetchT(url: string | URL, init?: FetchInit): FetchResponse<Response>;
-
-export { ABORT_ERROR, FetchError, TIMEOUT_ERROR, fetchT };
-export type { FetchInit, FetchProgress, FetchResponse, FetchResponseType, FetchTask };
-//# sourceMappingURL=types.d.ts.map
+import { AsyncResult } from 'happy-rusty';
+import { IOResult } from 'happy-rusty';
+
+/**
+ * Error name for aborted fetch requests.
+ *
+ * This matches the standard `AbortError` name used by the Fetch API when a request
+ * is cancelled via `AbortController.abort()`.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, ABORT_ERROR } from '@happy-ts/fetch-t';
+ *
+ * const task = fetchT('https://api.example.com/data', { abortable: true });
+ * task.abort();
+ *
+ * const result = await task.response;
+ * result.inspectErr((err) => {
+ *     if (err.name === ABORT_ERROR) {
+ *         console.log('Request was aborted');
+ *     }
+ * });
+ * ```
+ */
+export declare const ABORT_ERROR: "AbortError";
+
+/**
+ * Custom error class for HTTP error responses (non-2xx status codes).
+ *
+ * Thrown when `Response.ok` is `false`. Contains the HTTP status code
+ * for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, FetchError } from '@happy-ts/fetch-t';
+ *
+ * const result = await fetchT('https://api.example.com/not-found', {
+ *     responseType: 'json',
+ * });
+ *
+ * result.inspectErr((err) => {
+ *     if (err instanceof FetchError) {
+ *         console.log('HTTP Status:', err.status);  // e.g., 404
+ *         console.log('Status Text:', err.message); // e.g., "Not Found"
+ *
+ *         // Handle specific status codes
+ *         switch (err.status) {
+ *             case 401:
+ *                 console.log('Unauthorized - please login');
+ *                 break;
+ *             case 404:
+ *                 console.log('Resource not found');
+ *                 break;
+ *             case 500:
+ *                 console.log('Server error');
+ *                 break;
+ *         }
+ *     }
+ * });
+ * ```
+ */
+export declare class FetchError extends Error {
+    /**
+     * The error name, always `'FetchError'`.
+     */
+    name: string;
+    /**
+     * The HTTP status code of the response (e.g., 404, 500).
+     */
+    status: number;
+    /**
+     * Creates a new FetchError instance.
+     *
+     * @param message - The status text from the HTTP response (e.g., "Not Found").
+     * @param status - The HTTP status code (e.g., 404).
+     */
+    constructor(message: string, status: number);
+}
+
+/**
+ * Extended fetch options that add additional capabilities to the standard `RequestInit`.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, type FetchInit } from '@happy-ts/fetch-t';
+ *
+ * const options: FetchInit = {
+ *     // Standard RequestInit options
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ key: 'value' }),
+ *
+ *     // Extended options
+ *     abortable: true,           // Return FetchTask for manual abort control
+ *     responseType: 'json',      // Auto-parse response as JSON
+ *     timeout: 10000,            // Abort after 10 seconds
+ *     onProgress: (result) => {  // Track download progress
+ *         result.inspect(({ completedByteLength, totalByteLength }) => {
+ *             console.log(`${completedByteLength}/${totalByteLength}`);
+ *         });
+ *     },
+ *     onChunk: (chunk) => {      // Receive raw data chunks
+ *         console.log('Received chunk:', chunk.byteLength, 'bytes');
+ *     },
+ * };
+ *
+ * const task = fetchT('https://api.example.com/upload', options);
+ * ```
+ */
+export declare interface FetchInit extends RequestInit {
+    /**
+     * When `true`, returns a `FetchTask` instead of `FetchResponse`.
+     *
+     * The `FetchTask` provides `abort()` method and `aborted` status.
+     *
+     * @default false
+     */
+    abortable?: boolean;
+    /**
+     * Specifies how the response body should be parsed.
+     *
+     * - `'text'` - Returns `string`
+     * - `'json'` - Returns parsed JSON (type `T`)
+     * - `'arraybuffer'` - Returns `ArrayBuffer`
+     * - `'blob'` - Returns `Blob`
+     * - `undefined` - Returns raw `Response` object
+     */
+    responseType?: FetchResponseType;
+    /**
+     * Maximum time in milliseconds to wait for the request to complete.
+     *
+     * If exceeded, the request is automatically aborted with a `TimeoutError`.
+     * Must be a positive number.
+     */
+    timeout?: number;
+    /**
+     * Callback invoked during download to report progress.
+     *
+     * Receives an `IOResult<FetchProgress>`:
+     * - `Ok(FetchProgress)` - Progress update with byte counts
+     * - `Err(Error)` - If `Content-Length` header is missing (called once)
+     *
+     * @param progressResult - The progress result, either success with progress data or error.
+     */
+    onProgress?: (progressResult: IOResult<FetchProgress>) => void;
+    /**
+     * Callback invoked when a chunk of data is received.
+     *
+     * Useful for streaming or processing data as it arrives.
+     * Each chunk is a `Uint8Array` containing the raw bytes.
+     *
+     * @param chunk - The raw data chunk received from the response stream.
+     */
+    onChunk?: (chunk: Uint8Array) => void;
+}
+
+/**
+ * Represents the download progress of a fetch operation.
+ *
+ * Passed to the `onProgress` callback when tracking download progress.
+ * Note: Progress tracking requires the server to send a `Content-Length` header.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, type FetchProgress } from '@happy-ts/fetch-t';
+ *
+ * await fetchT('https://example.com/file.zip', {
+ *     responseType: 'blob',
+ *     onProgress: (result) => {
+ *         result.inspect((progress: FetchProgress) => {
+ *             const percent = (progress.completedByteLength / progress.totalByteLength) * 100;
+ *             console.log(`Downloaded: ${percent.toFixed(1)}%`);
+ *         });
+ *     },
+ * });
+ * ```
+ */
+export declare interface FetchProgress {
+    /**
+     * The total number of bytes to be received (from Content-Length header).
+     */
+    totalByteLength: number;
+    /**
+     * The number of bytes received so far.
+     */
+    completedByteLength: number;
+}
+
+/**
+ * Represents the response of a fetch operation as an async Result type.
+ *
+ * This is an alias for `AsyncResult<T, E>` from the `happy-rusty` library,
+ * providing Rust-like error handling without throwing exceptions.
+ *
+ * @typeParam T - The type of the data expected in a successful response.
+ * @typeParam E - The type of the error (defaults to `any`). Typically `Error` or `FetchError`.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, type FetchResponse } from '@happy-ts/fetch-t';
+ *
+ * // FetchResponse is a Promise that resolves to Result<T, E>
+ * const response: FetchResponse<string> = fetchT('https://api.example.com', {
+ *     responseType: 'text',
+ * });
+ *
+ * const result = await response;
+ * result
+ *     .inspect((text) => console.log('Success:', text))
+ *     .inspectErr((err) => console.error('Error:', err));
+ * ```
+ */
+export declare type FetchResponse<T, E = any> = AsyncResult<T, E>;
+
+/**
+ * Specifies the expected response type for automatic parsing.
+ *
+ * - `'text'` - Parse response as string via `Response.text()`
+ * - `'json'` - Parse response as JSON via `Response.json()`
+ * - `'arraybuffer'` - Parse response as ArrayBuffer via `Response.arrayBuffer()`
+ * - `'blob'` - Parse response as Blob via `Response.blob()`
+ *
+ * If not specified, the raw `Response` object is returned.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, type FetchResponseType } from '@happy-ts/fetch-t';
+ *
+ * const responseType: FetchResponseType = 'json';
+ *
+ * const result = await fetchT('https://api.example.com/data', { responseType });
+ * ```
+ */
+export declare type FetchResponseType = 'text' | 'arraybuffer' | 'blob' | 'json';
+
+/**
+ * Fetches a resource from the network as a text string and returns an abortable `FetchTask`.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `abortable: true` and `responseType: 'text'`.
+ * @returns A `FetchTask` representing the abortable operation with a `string` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    abortable: true;
+    responseType: 'text';
+}): FetchTask<string>;
+
+/**
+ * Fetches a resource from the network as an ArrayBuffer and returns an abortable `FetchTask`.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `abortable: true` and `responseType: 'arraybuffer'`.
+ * @returns A `FetchTask` representing the abortable operation with an `ArrayBuffer` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    abortable: true;
+    responseType: 'arraybuffer';
+}): FetchTask<ArrayBuffer>;
+
+/**
+ * Fetches a resource from the network as a Blob and returns an abortable `FetchTask`.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `abortable: true` and `responseType: 'blob'`.
+ * @returns A `FetchTask` representing the abortable operation with a `Blob` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    abortable: true;
+    responseType: 'blob';
+}): FetchTask<Blob>;
+
+/**
+ * Fetches a resource from the network and parses it as JSON, returning an abortable `FetchTask`.
+ *
+ * @typeParam T - The expected type of the parsed JSON data.
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `abortable: true` and `responseType: 'json'`.
+ * @returns A `FetchTask` representing the abortable operation with a response parsed as type `T`.
+ */
+export declare function fetchT<T>(url: string | URL, init: FetchInit & {
+    abortable: true;
+    responseType: 'json';
+}): FetchTask<T>;
+
+/**
+ * Fetches a resource from the network as a text string.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `responseType: 'text'`.
+ * @returns A `FetchResponse` representing the operation with a `string` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    responseType: 'text';
+}): FetchResponse<string, Error>;
+
+/**
+ * Fetches a resource from the network as an ArrayBuffer.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `responseType: 'arraybuffer'`.
+ * @returns A `FetchResponse` representing the operation with an `ArrayBuffer` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    responseType: 'arraybuffer';
+}): FetchResponse<ArrayBuffer, Error>;
+
+/**
+ * Fetches a resource from the network as a Blob.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `responseType: 'blob'`.
+ * @returns A `FetchResponse` representing the operation with a `Blob` response.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    responseType: 'blob';
+}): FetchResponse<Blob, Error>;
+
+/**
+ * Fetches a resource from the network and parses it as JSON.
+ *
+ * @typeParam T - The expected type of the parsed JSON data.
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `responseType: 'json'`.
+ * @returns A `FetchResponse` representing the operation with a response parsed as type `T`.
+ */
+export declare function fetchT<T>(url: string | URL, init: FetchInit & {
+    responseType: 'json';
+}): FetchResponse<T, Error>;
+
+/**
+ * Fetches a resource from the network and returns an abortable `FetchTask` with a generic `Response`.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Additional options for the fetch operation, must include `abortable: true`.
+ * @returns A `FetchTask` representing the abortable operation with a `Response` object.
+ */
+export declare function fetchT(url: string | URL, init: FetchInit & {
+    abortable: true;
+}): FetchTask<Response>;
+
+/**
+ * Fetches a resource from the network and returns a `FetchResponse` with a generic `Response` object.
+ *
+ * @param url - The resource to fetch. Can be a URL object or a string representing a URL.
+ * @param init - Optional additional options for the fetch operation.
+ * @returns A `FetchResponse` representing the operation with a `Response` object.
+ */
+export declare function fetchT(url: string | URL, init?: FetchInit): FetchResponse<Response>;
+
+/**
+ * Represents an abortable fetch operation with control methods.
+ *
+ * Returned when `abortable: true` is set in the fetch options. Provides
+ * the ability to cancel the request and check its abort status.
+ *
+ * @typeParam T - The type of the data expected in the response.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, type FetchTask } from '@happy-ts/fetch-t';
+ *
+ * interface User {
+ *     id: number;
+ *     name: string;
+ * }
+ *
+ * const task: FetchTask<User> = fetchT<User>('https://api.example.com/user/1', {
+ *     abortable: true,
+ *     responseType: 'json',
+ * });
+ *
+ * // Check if aborted
+ * console.log('Is aborted:', task.aborted); // false
+ *
+ * // Abort with optional reason
+ * task.abort('User navigated away');
+ *
+ * // Access the response (will be an error after abort)
+ * const result = await task.response;
+ * result.inspectErr((err) => console.log('Aborted:', err.message));
+ * ```
+ */
+export declare interface FetchTask<T> {
+    /**
+     * Aborts the fetch task, optionally with a reason.
+     *
+     * Once aborted, the `response` promise will resolve to an `Err` containing
+     * an `AbortError`. The abort reason can be any value and will be passed
+     * to the underlying `AbortController.abort()`.
+     *
+     * @param reason - An optional value indicating why the task was aborted.
+     *                 This can be an Error, string, or any other value.
+     */
+    abort(reason?: any): void;
+    /**
+     * Indicates whether the fetch task has been aborted.
+     *
+     * Returns `true` if `abort()` was called or if the request timed out.
+     */
+    readonly aborted: boolean;
+    /**
+     * The response promise of the fetch task.
+     *
+     * Resolves to `Ok<T>` on success, or `Err<Error>` on failure (including abort).
+     */
+    readonly response: FetchResponse<T>;
+}
+
+/**
+ * Error name for timed out fetch requests.
+ *
+ * This is set on the `Error.name` property when a request exceeds the specified
+ * `timeout` duration and is automatically aborted.
+ *
+ * @example
+ * ```typescript
+ * import { fetchT, TIMEOUT_ERROR } from '@happy-ts/fetch-t';
+ *
+ * const result = await fetchT('https://api.example.com/slow-endpoint', {
+ *     timeout: 5000, // 5 seconds
+ * });
+ *
+ * result.inspectErr((err) => {
+ *     if (err.name === TIMEOUT_ERROR) {
+ *         console.log('Request timed out after 5 seconds');
+ *     }
+ * });
+ * ```
+ */
+export declare const TIMEOUT_ERROR: "TimeoutError";
+
+export { }