@happy-ts/fetch-t 1.3.2 → 1.4.0

package/docs/interfaces/FetchTask.md

@@ -1,46 +0,0 @@
-[**@happy-ts/fetch-t**](../README.md) • **Docs**
-
-***
-
-[@happy-ts/fetch-t](../README.md) / FetchTask
-
-# Interface: FetchTask\<T\>
-
-Defines the structure and behavior of a fetch task, including the ability to abort the task and check its status.
-
-## Type Parameters
-
-| Type Parameter | Description |
-| ------ | ------ |
-| `T` | The type of the data expected in the response. |
-
-## Properties
-
-| Property | Modifier | Type | Description | Defined in |
-| ------ | ------ | ------ | ------ | ------ |
-| `aborted` | `readonly` | `boolean` | Indicates whether the fetch task has been aborted. | [defines.ts:27](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/defines.ts#L27) |
-| `response` | `readonly` | [`FetchResponse`](../type-aliases/FetchResponse.md)\<`T`, `any`\> | The response of the fetch task, represented as an `AsyncResult`. | [defines.ts:32](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/defines.ts#L32) |
-
-## Methods
-
-### abort()
-
-```ts
-abort(reason?): void
-```
-
-Aborts the fetch task, optionally with a reason for the abortion.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `reason`? | `any` | An optional parameter to indicate why the task was aborted. |
-
-#### Returns
-
-`void`
-
-#### Defined in
-
-[defines.ts:22](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/defines.ts#L22)

package/docs/type-aliases/FetchResponse.md

@@ -1,24 +0,0 @@
-[**@happy-ts/fetch-t**](../README.md) • **Docs**
-
-***
-
-[@happy-ts/fetch-t](../README.md) / FetchResponse
-
-# Type Alias: FetchResponse\<T, E\>
-
-```ts
-type FetchResponse<T, E>: AsyncResult<T, E>;
-```
-
-Represents the response of a fetch operation, encapsulating the result data or any error that occurred.
-
-## Type Parameters
-
-| Type Parameter | Default type | Description |
-| ------ | ------ | ------ |
-| `T` | - | The type of the data expected in the response. |
-| `E` | `any` | - |
-
-## Defined in
-
-[defines.ts:9](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/defines.ts#L9)

package/docs/type-aliases/FetchResponseType.md

@@ -1,17 +0,0 @@
-[**@happy-ts/fetch-t**](../README.md) • **Docs**
-
-***
-
-[@happy-ts/fetch-t](../README.md) / FetchResponseType
-
-# Type Alias: FetchResponseType
-
-```ts
-type FetchResponseType: "text" | "arraybuffer" | "blob" | "json";
-```
-
-Specifies the expected response type of the fetch request.
-
-## Defined in
-
-[defines.ts:38](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/defines.ts#L38)

package/docs/variables/ABORT_ERROR.md

@@ -1,17 +0,0 @@
-[**@happy-ts/fetch-t**](../README.md) • **Docs**
-
-***
-
-[@happy-ts/fetch-t](../README.md) / ABORT\_ERROR
-
-# Variable: ABORT\_ERROR
-
-```ts
-const ABORT_ERROR: "AbortError";
-```
-
-Name of abort error;
-
-## Defined in
-
-[constants.ts:4](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/constants.ts#L4)

package/docs/variables/TIMEOUT_ERROR.md

@@ -1,17 +0,0 @@
-[**@happy-ts/fetch-t**](../README.md) • **Docs**
-
-***
-
-[@happy-ts/fetch-t](../README.md) / TIMEOUT\_ERROR
-
-# Variable: TIMEOUT\_ERROR
-
-```ts
-const TIMEOUT_ERROR: "TimeoutError";
-```
-
-Name of timeout error;
-
-## Defined in
-
-[constants.ts:9](https://github.com/JiangJie/fetch-t/blob/61346c95bab5342bcbd9e97bca747ef24af2eac6/src/fetch/constants.ts#L9)

package/src/fetch/constants.ts

@@ -1,9 +0,0 @@
-/**
- * Name of abort error;
- */
-export const ABORT_ERROR = 'AbortError' as const;
-
-/**
- * Name of timeout error;
- */
-export const TIMEOUT_ERROR = 'TimeoutError' as const;

package/src/fetch/defines.ts

@@ -1,104 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { AsyncResult, IOResult } from 'happy-rusty';
-
-/**
- * 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.
- */
-export 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.
- */
-export 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.
- */
-export type FetchResponseType = 'text' | 'arraybuffer' | 'blob' | 'json';
-
-/**
- * Represents the progress of a fetch operation.
- */
-export 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.
- */
-export 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.
- */
-export class FetchError extends Error {
-    /**
-     * The name of the error.
-     */
-    name = 'FetchError';
-    /**
-     * The status code of the response.
-     */
-    status = 0;
-
-    constructor(message: string, status: number) {
-        super(message);
-        this.status = status;
-    }
-}

package/src/fetch/fetch.ts

@@ -1,292 +0,0 @@
-import { Err, Ok } from 'happy-rusty';
-import invariant from 'tiny-invariant';
-import { TIMEOUT_ERROR } from './constants.ts';
-import { FetchError, type FetchInit, type FetchResponse, type FetchTask } from './defines.ts';
-
-/**
- * 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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`.
- */
-export 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.
- */
-export function fetchT(url: string | URL, init?: FetchInit): FetchResponse<Response>;
-
-/**
- * Fetches a resource from the network and returns either a `FetchTask` or `FetchResponse` 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 `FetchTask` or `FetchResponse` depending on the provided options in `init`.
- */
-export function fetchT<T>(url: string | URL, init?: FetchInit): FetchTask<T> | FetchResponse<T> {
-    // most cases
-    if (typeof url !== 'string') {
-        invariant(url instanceof URL, () => `Url must be a string or URL object but received ${ url }.`);
-    }
-
-    const {
-        // default not abort able
-        abortable = false,
-        responseType,
-        timeout,
-        onProgress,
-        onChunk,
-        ...rest
-    } = init ?? {};
-
-    const shouldWaitTimeout = timeout != null;
-    let cancelTimer: (() => void) | null;
-
-    if (shouldWaitTimeout) {
-        invariant(typeof timeout === 'number' && timeout > 0, () => `Timeout must be a number greater than 0 but received ${ timeout }.`);
-    }
-
-    let controller: AbortController;
-
-    if (abortable || shouldWaitTimeout) {
-        controller = new AbortController();
-        rest.signal = controller.signal;
-    }
-
-    const response: FetchResponse<T> = fetch(url, rest).then(async (res): FetchResponse<T> => {
-        cancelTimer?.();
-
-        if (!res.ok) {
-            await res.body?.cancel();
-            return Err(new FetchError(res.statusText, res.status));
-        }
-
-        if (res.body) {
-            // should notify progress or data chunk?
-            const shouldNotifyProgress = typeof onProgress === 'function';
-            const shouldNotifyChunk = typeof onChunk === 'function';
-
-            if ((shouldNotifyProgress || shouldNotifyChunk)) {
-                // tee the original stream to two streams, one for notify progress, another for response
-                const [stream1, stream2] = res.body.tee();
-
-                const reader = stream1.getReader();
-                // may has no  content-length
-                let totalByteLength: number | null = null;
-                let completedByteLength = 0;
-
-                if (shouldNotifyProgress) {
-                    // try to get content-length
-                    // compatible with http/2
-                    const contentLength = res.headers.get('content-length') ?? res.headers.get('Content-Length');
-                    if (contentLength == null) {
-                        // response headers has no content-length
-                        onProgress(Err(new Error('No content-length in response headers.')));
-                    } else {
-                        totalByteLength = parseInt(contentLength, 10);
-                    }
-                }
-
-                reader.read().then(function notify({ done, value }) {
-                    if (done) {
-                        return;
-                    }
-
-                    // notify chunk
-                    if (shouldNotifyChunk) {
-                        onChunk(value);
-                    }
-
-                    // notify progress
-                    if (shouldNotifyProgress && totalByteLength != null) {
-                        completedByteLength += value.byteLength;
-                        onProgress(Ok({
-                            totalByteLength,
-                            completedByteLength,
-                        }));
-                    }
-
-
-                    // continue to read
-                    reader.read().then(notify);
-                });
-
-                // replace the original response with the new one
-                res = new Response(stream2, {
-                    headers: res.headers,
-                    status: res.status,
-                    statusText: res.statusText,
-                });
-            }
-        }
-
-        switch (responseType) {
-            case 'arraybuffer': {
-                return Ok(await res.arrayBuffer() as T);
-            }
-            case 'blob': {
-                return Ok(await res.blob() as T);
-            }
-            case 'json': {
-                try {
-                    return Ok(await res.json() as T);
-                } catch {
-                    return Err(new Error('Response is invalid json while responseType is json'));
-                }
-            }
-            case 'text': {
-                return Ok(await res.text() as T);
-            }
-            default: {
-                // default return the Response object
-                return Ok(res as T);
-            }
-        }
-    }).catch((err) => {
-        cancelTimer?.();
-
-        return Err(err);
-    });
-
-    if (shouldWaitTimeout) {
-        const timer = setTimeout(() => {
-            if (!controller.signal.aborted) {
-                const error = new Error();
-                error.name = TIMEOUT_ERROR;
-                controller.abort(error);
-            }
-        }, timeout);
-
-        cancelTimer = (): void => {
-            if (timer) {
-                clearTimeout(timer);
-            }
-
-            cancelTimer = null;
-        };
-    }
-
-    if (abortable) {
-        return {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            abort(reason?: any): void {
-                cancelTimer?.();
-                controller.abort(reason);
-            },
-
-            get aborted(): boolean {
-                return controller.signal.aborted;
-            },
-
-            get response(): FetchResponse<T> {
-                return response;
-            },
-        };
-    } else {
-        return response;
-    }
-}

package/src/mod.ts

@@ -1,3 +0,0 @@
-export * from './fetch/constants.ts';
-export * from './fetch/defines.ts';
-export * from './fetch/fetch.ts';