@happy-ts/fetch-t 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-01-04
+
+### Added
+
+- Add automatic retry support with configurable strategies (`retry` option)
+  - `retries`: Number of retry attempts
+  - `delay`: Static delay or exponential backoff function
+  - `when`: Retry on specific HTTP status codes or custom condition
+  - `onRetry`: Callback before each retry attempt
+- Add `'stream'` responseType to return raw `ReadableStream<Uint8Array>`
+- Add runtime validation for `fetchT` options (responseType, timeout, callbacks, retry)
+- Add `examples/with-retry.ts` with comprehensive retry examples
+
+### Changed
+
+- Optimize timeout handling using native `AbortSignal.timeout()` and `AbortSignal.any()` APIs
+- Upgrade `happy-rusty` dependency to ^1.8.0
+- Upgrade `typescript-eslint` to ^8.51.0
+- Upgrade `msw` to ^2.12.7
+
+### Fixed
+
+- Fix abort reason always wrapped as Error with proper `ABORT_ERROR` name
+
 ## [1.4.1] - 2025-12-25
 
 ### Fixed
@@ -119,6 +143,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Timeout support
 - Rust-like Result type error handling via `happy-rusty` library
 
+[1.5.0]: https://github.com/JiangJie/fetch-t/compare/v1.4.1...v1.5.0
 [1.4.1]: https://github.com/JiangJie/fetch-t/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/JiangJie/fetch-t/compare/v1.3.3...v1.4.0
 [1.3.3]: https://github.com/JiangJie/fetch-t/compare/v1.3.2...v1.3.3

package/README.cn.md

@@ -8,9 +8,13 @@
 [![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)
 
+类型安全的 Fetch API 封装，支持可中止请求、超时、进度追踪、自动重试和 Rust 风格的 Result 错误处理。
+
+---
+
 [English](README.md) | [API 文档](https://jiangjie.github.io/fetch-t/)
 
-类型安全的 Fetch API 封装，支持可中止请求、超时、进度追踪和 Rust 风格的 Result 错误处理。
+---
 
 ## 特性
 
@@ -19,6 +23,7 @@
 - **超时支持** - 指定毫秒数后自动中止请求
 - **进度追踪** - 通过 `onProgress` 回调监控下载进度
 - **数据流处理** - 通过 `onChunk` 回调访问原始数据块
+- **自动重试** - 通过 `retry` 选项配置失败重试策略
 - **Result 错误处理** - Rust 风格的 `Result` 类型实现显式错误处理
 - **跨平台** - 支持 Deno、Node.js、Bun 和浏览器
 
@@ -76,94 +81,27 @@ setTimeout(() => {
 const result = await task.response;
 ```
 
-### 超时控制
+### 自动重试
 
 ```ts
 const result = await fetchT('https://api.example.com/data', {
-    responseType: 'json',
-    timeout: 3000, // 3 秒后自动中止
-});
-```
-
-### 进度追踪
-
-```ts
-const result = await fetchT('https://api.example.com/large-file', {
-    responseType: 'blob',
-    onProgress(progressResult) {
-        progressResult.inspect(progress => {
-            const percent = (progress.completedByteLength / progress.totalByteLength * 100).toFixed(1);
-            console.log(`下载进度: ${percent}%`);
-        });
+    retry: {
+        retries: 3,
+        delay: (attempt) => Math.min(1000 * Math.pow(2, attempt - 1), 10000),
+        when: [500, 502, 503, 504],
+        onRetry: (error, attempt) => console.log(`重试 ${attempt}: ${error.message}`),
     },
-});
-```
-
-### 错误处理
-
-```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());
-}
 ```
 
-## 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/) 目录。
+- [基础用法](examples/basic.ts) - 基本请求示例
+- [进度追踪](examples/with-progress.ts) - 下载进度和数据流处理
+- [可中止请求](examples/abortable.ts) - 取消和超时请求
+- [自动重试](examples/with-retry.ts) - 自动重试策略
+- [错误处理](examples/error-handling.ts) - 错误处理模式
 
 ## 许可证
 

package/README.md

@@ -8,9 +8,13 @@
 [![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)
 
+Type-safe Fetch API wrapper with abortable requests, timeout support, progress tracking, automatic retry, and Rust-like Result error handling.
+
+---
+
 [中文](README.cn.md) | [API Documentation](https://jiangjie.github.io/fetch-t/)
 
-Type-safe Fetch API wrapper with abortable requests, timeout support, progress tracking, and Rust-like Result error handling.
+---
 
 ## Features
 
@@ -19,6 +23,7 @@ Type-safe Fetch API wrapper with abortable requests, timeout support, progress t
 - **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
+- **Automatic Retry** - Configurable retry strategies with `retry` option
 - **Result Error Handling** - Rust-like `Result` type for explicit error handling
 - **Cross-platform** - Works with Deno, Node.js, Bun, and browsers
 
@@ -76,94 +81,27 @@ setTimeout(() => {
 const result = await task.response;
 ```
 
-### With Timeout
+### Automatic Retry
 
 ```ts
 const result = await fetchT('https://api.example.com/data', {
-    responseType: 'json',
-    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 => {
-            const percent = (progress.completedByteLength / progress.totalByteLength * 100).toFixed(1);
-            console.log(`Download: ${percent}%`);
-        });
+    retry: {
+        retries: 3,
+        delay: (attempt) => Math.min(1000 * Math.pow(2, attempt - 1), 10000),
+        when: [500, 502, 503, 504],
+        onRetry: (error, attempt) => console.log(`Retry ${attempt}: ${error.message}`),
     },
-});
-```
-
-### Error Handling
-
-```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());
-}
 ```
 
-## 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.
+- [Basic](examples/basic.ts) - Basic fetch requests
+- [Progress Tracking](examples/with-progress.ts) - Download progress and chunk streaming
+- [Abortable](examples/abortable.ts) - Cancel and timeout requests
+- [Retry](examples/with-retry.ts) - Automatic retry strategies
+- [Error Handling](examples/error-handling.ts) - Error handling patterns
 
 ## License
 

package/dist/main.cjs

@@ -31,8 +31,15 @@ class FetchError extends Error {
 
 function fetchT(url, init) {
   if (typeof url !== "string") {
-    invariant(url instanceof URL, () => `Url must be a string or URL object but received ${url}.`);
+    invariant(url instanceof URL, () => `Url must be a string or URL object but received ${url}`);
   }
+  const fetchInit = init ?? {};
+  const {
+    retries,
+    delay: retryDelay,
+    when: retryWhen,
+    onRetry
+  } = validateOptions(fetchInit);
   const {
     // default not abortable
     abortable = false,
@@ -41,118 +48,167 @@ function fetchT(url, init) {
     onProgress,
     onChunk,
     ...rest
-  } = init ?? {};
-  const shouldWaitTimeout = timeout != null;
-  let cancelTimer;
-  if (shouldWaitTimeout) {
-    invariant(typeof timeout === "number" && timeout > 0, () => `Timeout must be a number greater than 0 but received ${timeout}.`);
-  }
-  let controller;
-  if (abortable || shouldWaitTimeout) {
-    controller = new AbortController();
-    rest.signal = controller.signal;
+  } = fetchInit;
+  let userController;
+  if (abortable) {
+    userController = new AbortController();
   }
-  const response = fetch(url, rest).then(async (res) => {
-    cancelTimer?.();
-    if (!res.ok) {
-      await res.body?.cancel();
-      return happyRusty.Err(new FetchError(res.statusText, res.status));
+  const shouldRetry = (error, attempt) => {
+    if (error.name === ABORT_ERROR) {
+      return false;
+    }
+    if (!retryWhen) {
+      return !(error instanceof FetchError);
+    }
+    if (Array.isArray(retryWhen)) {
+      return error instanceof FetchError && retryWhen.includes(error.status);
+    }
+    return retryWhen(error, attempt);
+  };
+  const getRetryDelay = (attempt) => {
+    return typeof retryDelay === "function" ? retryDelay(attempt) : retryDelay;
+  };
+  const doFetch = async () => {
+    const signals = [];
+    if (userController) {
+      signals.push(userController.signal);
     }
-    if (res.body) {
-      const shouldNotifyProgress = typeof onProgress === "function";
-      const shouldNotifyChunk = typeof onChunk === "function";
-      if (shouldNotifyProgress || shouldNotifyChunk) {
-        const [stream1, stream2] = res.body.tee();
-        const reader = stream1.getReader();
-        let totalByteLength = null;
-        let completedByteLength = 0;
-        if (shouldNotifyProgress) {
-          const contentLength = res.headers.get("content-length");
-          if (contentLength == null) {
-            try {
-              onProgress(happyRusty.Err(new Error("No content-length in response headers.")));
-            } catch {
-            }
-          } else {
-            totalByteLength = parseInt(contentLength, 10);
+    if (typeof timeout === "number") {
+      signals.push(AbortSignal.timeout(timeout));
+    }
+    if (signals.length > 0) {
+      rest.signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+    }
+    try {
+      const res = await fetch(url, rest);
+      if (!res.ok) {
+        await res.body?.cancel();
+        return happyRusty.Err(new FetchError(res.statusText, res.status));
+      }
+      return await processResponse(res);
+    } catch (err) {
+      return happyRusty.Err(
+        err instanceof Error ? err : wrapAbortReason(err)
+      );
+    }
+  };
+  const processResponse = async (res) => {
+    let response2 = res;
+    if (res.body && (onProgress || onChunk)) {
+      const [stream1, stream2] = res.body.tee();
+      const reader = stream1.getReader();
+      let totalByteLength = null;
+      let completedByteLength = 0;
+      if (onProgress) {
+        const contentLength = res.headers.get("content-length");
+        if (contentLength == null) {
+          try {
+            onProgress(happyRusty.Err(new Error("No content-length in response headers.")));
+          } catch {
           }
+        } else {
+          totalByteLength = parseInt(contentLength, 10);
         }
-        reader.read().then(function notify({ done, value }) {
-          if (done) {
-            return;
-          }
-          if (shouldNotifyChunk) {
-            try {
-              onChunk(value);
-            } catch {
-            }
+      }
+      reader.read().then(function notify({ done, value }) {
+        if (done) {
+          return;
+        }
+        if (onChunk) {
+          try {
+            onChunk(value);
+          } catch {
           }
-          if (shouldNotifyProgress && totalByteLength != null) {
-            completedByteLength += value.byteLength;
-            try {
-              onProgress(happyRusty.Ok({
-                totalByteLength,
-                completedByteLength
-              }));
-            } catch {
-            }
+        }
+        if (onProgress && totalByteLength != null) {
+          completedByteLength += value.byteLength;
+          try {
+            onProgress(happyRusty.Ok({
+              totalByteLength,
+              completedByteLength
+            }));
+          } catch {
           }
-          reader.read().then(notify).catch(() => {
-          });
-        }).catch(() => {
-        });
-        res = new Response(stream2, {
-          headers: res.headers,
-          status: res.status,
-          statusText: res.statusText
+        }
+        reader.read().then(notify).catch(() => {
         });
-      }
+      }).catch(() => {
+      });
+      response2 = new Response(stream2, {
+        headers: res.headers,
+        status: res.status,
+        statusText: res.statusText
+      });
     }
     switch (responseType) {
       case "arraybuffer": {
-        return happyRusty.Ok(await res.arrayBuffer());
+        return happyRusty.Ok(await response2.arrayBuffer());
       }
       case "blob": {
-        return happyRusty.Ok(await res.blob());
+        return happyRusty.Ok(await response2.blob());
       }
       case "json": {
         try {
-          return happyRusty.Ok(await res.json());
+          return happyRusty.Ok(await response2.json());
         } catch {
           return happyRusty.Err(new Error("Response is invalid json while responseType is json"));
         }
       }
+      case "stream": {
+        return happyRusty.Ok(response2.body);
+      }
       case "text": {
-        return happyRusty.Ok(await res.text());
+        return happyRusty.Ok(await response2.text());
       }
       default: {
-        return happyRusty.Ok(res);
+        return happyRusty.Ok(response2);
       }
     }
-  }).catch((err) => {
-    cancelTimer?.();
-    return happyRusty.Err(err);
-  });
-  if (shouldWaitTimeout) {
-    const timer = setTimeout(() => {
-      const error = new Error();
-      error.name = TIMEOUT_ERROR;
-      controller.abort(error);
-    }, timeout);
-    cancelTimer = () => {
-      clearTimeout(timer);
-      cancelTimer = null;
-    };
-  }
-  if (abortable) {
+  };
+  const fetchWithRetry = async () => {
+    let lastError;
+    let attempt = 0;
+    do {
+      if (attempt > 0) {
+        if (userController?.signal.aborted) {
+          return happyRusty.Err(userController.signal.reason);
+        }
+        const delayMs = getRetryDelay(attempt);
+        if (delayMs > 0) {
+          await delay(delayMs);
+          if (userController?.signal.aborted) {
+            return happyRusty.Err(userController.signal.reason);
+          }
+        }
+        try {
+          onRetry?.(lastError, attempt);
+        } catch {
+        }
+      }
+      const result = await doFetch();
+      if (result.isOk()) {
+        return result;
+      }
+      lastError = result.unwrapErr();
+      attempt++;
+    } while (attempt <= retries && shouldRetry(lastError, attempt));
+    return happyRusty.Err(lastError);
+  };
+  const response = fetchWithRetry();
+  if (abortable && userController) {
     return {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       abort(reason) {
-        cancelTimer?.();
-        controller.abort(reason);
+        if (reason instanceof Error) {
+          userController.abort(reason);
+        } else if (reason != null) {
+          userController.abort(wrapAbortReason(reason));
+        } else {
+          userController.abort();
+        }
       },
       get aborted() {
-        return controller.signal.aborted;
+        return userController.signal.aborted;
       },
       get response() {
         return response;
@@ -161,6 +217,62 @@ function fetchT(url, init) {
   }
   return response;
 }
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function wrapAbortReason(reason) {
+  const error = new Error(typeof reason === "string" ? reason : String(reason));
+  error.name = ABORT_ERROR;
+  error.cause = reason;
+  return error;
+}
+function validateOptions(init) {
+  const {
+    responseType,
+    timeout,
+    retry: retryOptions = 0,
+    onProgress,
+    onChunk
+  } = init;
+  if (responseType != null) {
+    const validTypes = ["text", "arraybuffer", "blob", "json", "stream"];
+    invariant(validTypes.includes(responseType), () => `responseType must be one of ${validTypes.join(", ")} but received ${responseType}`);
+  }
+  if (timeout != null) {
+    invariant(typeof timeout === "number" && timeout > 0, () => `timeout must be a number greater than 0 but received ${timeout}`);
+  }
+  if (onProgress != null) {
+    invariant(typeof onProgress === "function", () => `onProgress callback must be a function but received ${typeof onProgress}`);
+  }
+  if (onChunk != null) {
+    invariant(typeof onChunk === "function", () => `onChunk callback must be a function but received ${typeof onChunk}`);
+  }
+  let retries = 0;
+  let delay2 = 0;
+  let when;
+  let onRetry;
+  if (typeof retryOptions === "number") {
+    retries = retryOptions;
+  } else if (retryOptions && typeof retryOptions === "object") {
+    retries = retryOptions.retries ?? 0;
+    delay2 = retryOptions.delay ?? 0;
+    when = retryOptions.when;
+    onRetry = retryOptions.onRetry;
+  }
+  invariant(Number.isInteger(retries) && retries >= 0, () => `Retry count must be a non-negative integer but received ${retries}`);
+  if (typeof delay2 === "number") {
+    invariant(delay2 >= 0, () => `Retry delay must be a non-negative number but received ${delay2}`);
+  } else {
+    invariant(typeof delay2 === "function", () => `Retry delay must be a number or a function but received ${typeof delay2}`);
+  }
+  if (when != null) {
+    invariant(Array.isArray(when) || typeof when === "function", () => `Retry when condition must be an array of status codes or a function but received ${typeof when}`);
+  }
+  if (onRetry != null) {
+    invariant(typeof onRetry === "function", () => `Retry onRetry callback must be a function but received ${typeof onRetry}`);
+  }
+  return { retries, delay: delay2, when, onRetry };
+}
 
 exports.ABORT_ERROR = ABORT_ERROR;
 exports.FetchError = FetchError;