@happy-ts/fetch-t 1.3.3 → 1.4.1

package/README.cn.md

@@ -1,82 +1,170 @@
 # fetchT
 
-[![NPM version](http://img.shields.io/npm/v/@happy-ts/fetch-t.svg)](https://npmjs.org/package/@happy-ts/fetch-t)
+[![License](https://img.shields.io/npm/l/@happy-ts/fetch-t.svg)](LICENSE)
+[![Build Status](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml/badge.svg)](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/JiangJie/fetch-t/graph/badge.svg)](https://codecov.io/gh/JiangJie/fetch-t)
+[![NPM version](https://img.shields.io/npm/v/@happy-ts/fetch-t.svg)](https://npmjs.org/package/@happy-ts/fetch-t)
+[![NPM downloads](https://badgen.net/npm/dm/@happy-ts/fetch-t)](https://npmjs.org/package/@happy-ts/fetch-t)
 [![JSR Version](https://jsr.io/badges/@happy-ts/fetch-t)](https://jsr.io/@happy-ts/fetch-t)
 [![JSR Score](https://jsr.io/badges/@happy-ts/fetch-t/score)](https://jsr.io/@happy-ts/fetch-t/score)
-[![Build Status](https://github.com/jiangjie/fetch-t/actions/workflows/test.yml/badge.svg)](https://github.com/jiangjie/fetch-t/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/JiangJie/fetch-t/graph/badge.svg)](https://codecov.io/gh/JiangJie/fetch-t)
-
----
-
-## 可终止 && 可预测
 
-fetchT 的返回值包含一个可以 abort 的方法。
+[English](README.md) | [API 文档](https://jiangjie.github.io/fetch-t/)
 
-fetchT 的返回数据是一个明确的类型，可以是 `string` `ArrayBuffer` `Blob` `<T>(泛型)`。
+类型安全的 Fetch API 封装，支持可中止请求、超时、进度追踪和 Rust 风格的 Result 错误处理。
 
-支持超时自动取消请求。
+## 特性
 
-支持进度回调。
+- **可中止请求** - 随时通过 `FetchTask.abort()` 取消请求
+- **类型安全响应** - 通过 `responseType` 参数指定返回类型
+- **超时支持** - 指定毫秒数后自动中止请求
+- **进度追踪** - 通过 `onProgress` 回调监控下载进度
+- **数据流处理** - 通过 `onChunk` 回调访问原始数据块
+- **Result 错误处理** - Rust 风格的 `Result` 类型实现显式错误处理
+- **跨平台** - 支持 Deno、Node.js、Bun 和浏览器
 
 ## 安装
 
 ```sh
-# via pnpm
-pnpm add @happy-ts/fetch-t
-# or via yarn
+# npm
+npm install @happy-ts/fetch-t
+
+# yarn
 yarn add @happy-ts/fetch-t
-# or just from npm
-npm install --save @happy-ts/fetch-t
-# via JSR
-jsr add @happy-ts/fetch-t
-# for deno
+
+# pnpm
+pnpm add @happy-ts/fetch-t
+
+# JSR (Deno)
 deno add @happy-ts/fetch-t
-# for bun
+
+# JSR (Bun)
 bunx jsr add @happy-ts/fetch-t
 ```
 
-## 为什么会有 fetchT
+## 快速开始
 
-fetchT 是对 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API 的简单封装，主要包括两点修改：
+### 基础用法
 
-* 增加 `abortable` 参数，如果传入 `abortable: true`，则 fetchT 会返回一个 `FetchTask`，可以通过调用 `FetchTask.abort()` 来终止请求。
-* 支持泛型返回值，增加 `responseType` 参数，可选值包括 `'text' | 'arraybuffer' | 'blob' | 'json'`，返回值根据参数不同，对应返回 `string | ArrayBuffer | Blob | T`，并且返回值都是 [Result](https://github.com/JiangJie/happy-rusty) 类型，便于错误处理。
+```ts
+import { fetchT } from '@happy-ts/fetch-t';
 
-如果你没有以上需求，推荐使用原版 [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)。
+// GET JSON 数据
+const result = await fetchT<{ id: number; title: string }>('https://api.example.com/data', {
+    responseType: 'json',
+});
 
-## 示例
+result.inspect(data => {
+    console.log(data.title);
+}).inspectErr(err => {
+    console.error('请求失败:', err.message);
+});
+```
 
-```ts
-import { fetchT } from '@happy-ts/fetch-t';
+### 可中止请求
 
-const fetchTask = fetchT('https://example.com', {
+```ts
+const task = fetchT('https://api.example.com/large-file', {
     abortable: true,
+    responseType: 'arraybuffer',
+});
+
+// 5 秒后中止
+setTimeout(() => {
+    task.abort('用户取消');
+}, 5000);
+
+const result = await task.response;
+```
+
+### 超时控制
+
+```ts
+const result = await fetchT('https://api.example.com/data', {
     responseType: 'json',
-    timeout: 3000,
-    onChunk(chunk): void {
-        console.assert(chunk instanceof Uint8Array);
-    },
-    onProgress(progressResult): void {
+    timeout: 3000, // 3 秒后自动中止
+});
+```
+
+### 进度追踪
+
+```ts
+const result = await fetchT('https://api.example.com/large-file', {
+    responseType: 'blob',
+    onProgress(progressResult) {
         progressResult.inspect(progress => {
-            console.log(`${ progress.completedByteLength }/${ progress.totalByteLength }`);
-        }).inspectErr(err => {
-            console.error(err);
+            const percent = (progress.completedByteLength / progress.totalByteLength * 100).toFixed(1);
+            console.log(`下载进度: ${percent}%`);
         });
     },
 });
+```
 
-somethingHappenAsync(() => {
-    fetchTask.abort('cancel');
-});
+### 错误处理
 
-const res = await fetchTask.response;
-res.inspect(data => {
-    console.log(data);
-}).inspectErr(err => {
-    console.assert(err === 'cancel');
+```ts
+import { fetchT, ABORT_ERROR, TIMEOUT_ERROR } from '@happy-ts/fetch-t';
+
+const result = await fetchT('https://api.example.com/data', {
+    responseType: 'json',
+    timeout: 3000,
 });
+
+if (result.isErr()) {
+    const err = result.unwrapErr();
+    if (err.name === TIMEOUT_ERROR) {
+        console.log('请求超时');
+    } else if (err.name === ABORT_ERROR) {
+        console.log('请求已中止');
+    } else {
+        console.log('请求失败:', err.message);
+    }
+} else {
+    console.log('数据:', result.unwrap());
+}
 ```
 
-更多示例可参见测试用例 <a href="tests/fetch.test.ts">fetch.test.ts</a>。
+## API
+
+### `fetchT(url, options?)`
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `url` | `string \| URL` | 请求 URL |
+| `options` | `FetchInit` | 扩展的 fetch 选项 |
+
+### `FetchInit` 选项
+
+继承标准 `RequestInit`，额外支持：
+
+| 选项 | 类型 | 描述 |
+|------|------|------|
+| `abortable` | `boolean` | 如为 `true`，返回 `FetchTask` 而非 `FetchResponse` |
+| `responseType` | `'text' \| 'arraybuffer' \| 'blob' \| 'json'` | 指定返回数据类型 |
+| `timeout` | `number` | 指定毫秒数后自动中止 |
+| `onProgress` | `(result: IOResult<FetchProgress>) => void` | 下载进度回调 |
+| `onChunk` | `(chunk: Uint8Array) => void` | 原始数据块回调 |
+
+### `FetchTask<T>`
+
+当 `abortable: true` 时返回：
+
+| 属性/方法 | 类型 | 描述 |
+|-----------|------|------|
+| `response` | `FetchResponse<T>` | 响应 Promise |
+| `abort(reason?)` | `void` | 中止请求 |
+| `aborted` | `boolean` | 请求是否已中止 |
+
+### 常量
+
+| 常量 | 描述 |
+|------|------|
+| `ABORT_ERROR` | 中止请求的错误名称 |
+| `TIMEOUT_ERROR` | 超时请求的错误名称 |
+
+## 示例
+
+更多示例请参见 [examples](examples/) 目录。
+
+## 许可证
 
-## [文档](docs/README.md)
+[MIT](LICENSE)

package/README.md

@@ -1,87 +1,170 @@
 # fetchT
 
+[![License](https://img.shields.io/npm/l/@happy-ts/fetch-t.svg)](LICENSE)
+[![Build Status](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml/badge.svg)](https://github.com/JiangJie/fetch-t/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/JiangJie/fetch-t/graph/badge.svg)](https://codecov.io/gh/JiangJie/fetch-t)
 [![NPM version](https://img.shields.io/npm/v/@happy-ts/fetch-t.svg)](https://npmjs.org/package/@happy-ts/fetch-t)
 [![NPM downloads](https://badgen.net/npm/dm/@happy-ts/fetch-t)](https://npmjs.org/package/@happy-ts/fetch-t)
 [![JSR Version](https://jsr.io/badges/@happy-ts/fetch-t)](https://jsr.io/@happy-ts/fetch-t)
 [![JSR Score](https://jsr.io/badges/@happy-ts/fetch-t/score)](https://jsr.io/@happy-ts/fetch-t/score)
-[![Build Status](https://github.com/jiangjie/fetch-t/actions/workflows/test.yml/badge.svg)](https://github.com/jiangjie/fetch-t/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/JiangJie/fetch-t/graph/badge.svg)](https://codecov.io/gh/JiangJie/fetch-t)
-
----
-
-## [中文](README.cn.md)
 
----
+[中文](README.cn.md) | [API Documentation](https://jiangjie.github.io/fetch-t/)
 
-## Abortable && Predictable
+Type-safe Fetch API wrapper with abortable requests, timeout support, progress tracking, and Rust-like Result error handling.
 
-The return value of fetchT includes an `abort` method.
+## Features
 
-The return data of fetchT is of a specific type, which can be either `string`, `ArrayBuffer`, `Blob`, or `<T>(generic)`.
-
-Support `timeout`.
-
-Support `progress`.
+- **Abortable Requests** - Cancel requests anytime via `FetchTask.abort()`
+- **Type-safe Responses** - Specify return type with `responseType` parameter
+- **Timeout Support** - Auto-abort requests after specified milliseconds
+- **Progress Tracking** - Monitor download progress with `onProgress` callback
+- **Chunk Streaming** - Access raw data chunks via `onChunk` callback
+- **Result Error Handling** - Rust-like `Result` type for explicit error handling
+- **Cross-platform** - Works with Deno, Node.js, Bun, and browsers
 
 ## Installation
 
 ```sh
-# via pnpm
-pnpm add @happy-ts/fetch-t
-# or via yarn
+# npm
+npm install @happy-ts/fetch-t
+
+# yarn
 yarn add @happy-ts/fetch-t
-# or just from npm
-npm install --save @happy-ts/fetch-t
-# via JSR
-jsr add @happy-ts/fetch-t
-# for deno
+
+# pnpm
+pnpm add @happy-ts/fetch-t
+
+# JSR (Deno)
 deno add @happy-ts/fetch-t
-# for bun
+
+# JSR (Bun)
 bunx jsr add @happy-ts/fetch-t
 ```
 
-## Why fetchT
+## Quick Start
 
-fetchT is a simple encapsulation of the [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API, with two main modifications:
+### Basic Usage
+
+```ts
+import { fetchT } from '@happy-ts/fetch-t';
 
--   It adds the `abortable` parameter. If `abortable: true` is passed, fetchT will return a `FetchTask` object that allows you to abort the request by calling `FetchTask.abort()`.
--   It supports generic return values by adding the responseType parameter. The optional values for `responseType` include `'text' | 'arraybuffer' | 'blob' | 'json'`. The return value corresponds to the parameter and can be either `string | ArrayBuffer | Blob | T`, where T is the generic type. All return values are of the [Result](https://github.com/JiangJie/happy-rusty) type, which facilitates error handling.
+// GET JSON data
+const result = await fetchT<{ id: number; title: string }>('https://api.example.com/data', {
+    responseType: 'json',
+});
 
-If you don't have these requirements, it is recommended to use the vanilla [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+result.inspect(data => {
+    console.log(data.title);
+}).inspectErr(err => {
+    console.error('Request failed:', err.message);
+});
+```
 
-## Examples
+### Abortable Request
 
 ```ts
-import { fetchT } from '@happy-ts/fetch-t';
-
-const fetchTask = fetchT('https://example.com', {
+const task = fetchT('https://api.example.com/large-file', {
     abortable: true,
+    responseType: 'arraybuffer',
+});
+
+// Abort after 5 seconds
+setTimeout(() => {
+    task.abort('User cancelled');
+}, 5000);
+
+const result = await task.response;
+```
+
+### With Timeout
+
+```ts
+const result = await fetchT('https://api.example.com/data', {
     responseType: 'json',
-    timeout: 3000,
-    onChunk(chunk): void {
-        console.assert(chunk instanceof Uint8Array);
-    },
-    onProgress(progressResult): void {
+    timeout: 3000, // Auto-abort after 3 seconds
+});
+```
+
+### Progress Tracking
+
+```ts
+const result = await fetchT('https://api.example.com/large-file', {
+    responseType: 'blob',
+    onProgress(progressResult) {
         progressResult.inspect(progress => {
-            console.log(`${ progress.completedByteLength }/${ progress.totalByteLength }`);
-        }).inspectErr(err => {
-            console.error(err);
+            const percent = (progress.completedByteLength / progress.totalByteLength * 100).toFixed(1);
+            console.log(`Download: ${percent}%`);
         });
     },
 });
+```
 
-somethingHappenAsync(() => {
-    fetchTask.abort('cancel');
-});
+### Error Handling
 
-const res = await fetchTask.response;
-res.inspect(data => {
-    console.log(data);
-}).inspectErr(err => {
-    console.assert(err === 'cancel');
+```ts
+import { fetchT, ABORT_ERROR, TIMEOUT_ERROR } from '@happy-ts/fetch-t';
+
+const result = await fetchT('https://api.example.com/data', {
+    responseType: 'json',
+    timeout: 3000,
 });
+
+if (result.isErr()) {
+    const err = result.unwrapErr();
+    if (err.name === TIMEOUT_ERROR) {
+        console.log('Request timed out');
+    } else if (err.name === ABORT_ERROR) {
+        console.log('Request was aborted');
+    } else {
+        console.log('Request failed:', err.message);
+    }
+} else {
+    console.log('Data:', result.unwrap());
+}
 ```
 
-For more examples, please refer to test case <a href="tests/fetch.test.ts">fetch.test.ts</a>.
+## API
+
+### `fetchT(url, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string \| URL` | Request URL |
+| `options` | `FetchInit` | Extended fetch options |
+
+### `FetchInit` Options
+
+Extends standard `RequestInit` with:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `abortable` | `boolean` | If `true`, returns `FetchTask` instead of `FetchResponse` |
+| `responseType` | `'text' \| 'arraybuffer' \| 'blob' \| 'json'` | Specifies return data type |
+| `timeout` | `number` | Auto-abort after milliseconds |
+| `onProgress` | `(result: IOResult<FetchProgress>) => void` | Download progress callback |
+| `onChunk` | `(chunk: Uint8Array) => void` | Raw data chunk callback |
+
+### `FetchTask<T>`
+
+Returned when `abortable: true`:
+
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `response` | `FetchResponse<T>` | The response promise |
+| `abort(reason?)` | `void` | Abort the request |
+| `aborted` | `boolean` | Whether request was aborted |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `ABORT_ERROR` | Error name for aborted requests |
+| `TIMEOUT_ERROR` | Error name for timed out requests |
+
+## Examples
+
+For more examples, see the [examples](examples/) directory.
+
+## License
 
-## [Docs](docs/README.md)
+[MIT](LICENSE)

package/dist/main.cjs

@@ -1,20 +1,28 @@
 'use strict';
 
-var happyRusty = require('happy-rusty');
-var invariant = require('tiny-invariant');
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const happyRusty = require('happy-rusty');
+const invariant = require('tiny-invariant');
 
 const ABORT_ERROR = "AbortError";
 const TIMEOUT_ERROR = "TimeoutError";
 
 class FetchError extends Error {
   /**
-   * The name of the error.
+   * The error name, always `'FetchError'`.
    */
   name = "FetchError";
   /**
-   * The status code of the response.
+   * The HTTP status code of the response (e.g., 404, 500).
    */
   status = 0;
+  /**
+   * 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, status) {
     super(message);
     this.status = status;
@@ -26,7 +34,7 @@ function fetchT(url, init) {
     invariant(url instanceof URL, () => `Url must be a string or URL object but received ${url}.`);
   }
   const {
-    // default not abort able
+    // default not abortable
     abortable = false,
     responseType,
     timeout,
@@ -59,9 +67,12 @@ function fetchT(url, init) {
         let totalByteLength = null;
         let completedByteLength = 0;
         if (shouldNotifyProgress) {
-          const contentLength = res.headers.get("content-length") ?? res.headers.get("Content-Length");
+          const contentLength = res.headers.get("content-length");
           if (contentLength == null) {
-            onProgress(happyRusty.Err(new Error("No content-length in response headers.")));
+            try {
+              onProgress(happyRusty.Err(new Error("No content-length in response headers.")));
+            } catch {
+            }
           } else {
             totalByteLength = parseInt(contentLength, 10);
           }
@@ -71,16 +82,24 @@ function fetchT(url, init) {
             return;
           }
           if (shouldNotifyChunk) {
-            onChunk(value);
+            try {
+              onChunk(value);
+            } catch {
+            }
           }
           if (shouldNotifyProgress && totalByteLength != null) {
             completedByteLength += value.byteLength;
-            onProgress(happyRusty.Ok({
-              totalByteLength,
-              completedByteLength
-            }));
+            try {
+              onProgress(happyRusty.Ok({
+                totalByteLength,
+                completedByteLength
+              }));
+            } catch {
+            }
           }
-          reader.read().then(notify);
+          reader.read().then(notify).catch(() => {
+          });
+        }).catch(() => {
         });
         res = new Response(stream2, {
           headers: res.headers,
@@ -116,16 +135,12 @@ function fetchT(url, init) {
   });
   if (shouldWaitTimeout) {
     const timer = setTimeout(() => {
-      if (!controller.signal.aborted) {
-        const error = new Error();
-        error.name = TIMEOUT_ERROR;
-        controller.abort(error);
-      }
+      const error = new Error();
+      error.name = TIMEOUT_ERROR;
+      controller.abort(error);
     }, timeout);
     cancelTimer = () => {
-      if (timer) {
-        clearTimeout(timer);
-      }
+      clearTimeout(timer);
       cancelTimer = null;
     };
   }
@@ -143,9 +158,8 @@ function fetchT(url, init) {
         return response;
       }
     };
-  } else {
-    return response;
   }
+  return response;
 }
 
 exports.ABORT_ERROR = ABORT_ERROR;