feat(retry): add shouldRetry option (#1585)

* feat(retry): add shouldRetry option

Add shouldRetry option to control retry behavior based on error type.
This allows users to retry only on specific errors (e.g., 500+ status codes).

* Apply suggestions from code review

* [autofix.ci] apply automated fixes

* fix

---------

Co-authored-by: Sojin Park <raon0211@toss.im>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/ja/reference/function/retry.md

@@ -52,6 +52,33 @@ const data4 = await retry(
 );
 ```
 
+特定のエラーでのみ再試行したい場合は `shouldRetry` オプションを使用できます。
+
+```typescript
+import { retry } from 'es-toolkit/function';
+
+class NetworkError extends Error {
+  constructor(public status: number) {
+    super(`Network error: ${status}`);
+  }
+}
+
+// 500エラー以上でのみ再試行
+const data5 = await retry(
+  async () => {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new NetworkError(response.status);
+    }
+    return response.json();
+  },
+  {
+    retries: 3,
+    shouldRetry: (error, attempt) => error instanceof NetworkError && error.status >= 500,
+  }
+);
+```
+
 AbortSignal を使用して再試行をキャンセルすることもできます。
 
 ```typescript
@@ -86,6 +113,9 @@ try {
   - `retries` (`number`, オプション): 再試行する回数です。デフォルトは `Infinity` で無限に再試行します。
   - `delay` (`number | (attempts: number) => number`, オプション): 再試行間隔(ミリ秒)です。数値または関数を使用できます。デフォルトは `0` です。
   - `signal` (`AbortSignal`, オプション): 再試行をキャンセルできるシグナルです。
+  - `shouldRetry` (`(error: unknown, attempt: number) => boolean`, オプション): 再試行するかどうかを決定する関数です。`false` を返すと即座にエラーをスローします。
+    - `error`: 発生したエラーオブジェクトです。
+    - `attempt`: 現在の試行回数です (0から開始)。
 
 #### 戻り値
 

docs/ko/reference/function/retry.md

@@ -52,6 +52,33 @@ const data4 = await retry(
 );
 ```
 
+특정 에러에서만 재시도하고 싶을 때 `shouldRetry` 옵션을 사용할 수 있어요.
+
+```typescript
+import { retry } from 'es-toolkit/function';
+
+class NetworkError extends Error {
+  constructor(public status: number) {
+    super(`Network error: ${status}`);
+  }
+}
+
+// 500 에러 이상에서만 재시도
+const data5 = await retry(
+  async () => {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new NetworkError(response.status);
+    }
+    return response.json();
+  },
+  {
+    retries: 3,
+    shouldRetry: (error, attempt) => error instanceof NetworkError && error.status >= 500,
+  }
+);
+```
+
 AbortSignal을 사용해서 재시도를 취소할 수도 있어요.
 
 ```typescript
@@ -86,6 +113,9 @@ try {
   - `retries` (`number`, 선택): 재시도할 횟수예요. 기본값은 `Infinity`로 무한 재시도해요.
   - `delay` (`number | (attempts: number) => number`, 선택): 재시도 간격(밀리초)이에요. 숫자나 함수를 사용할 수 있어요. 기본값은 `0`이에요.
   - `signal` (`AbortSignal`, 선택): 재시도를 취소할 수 있는 시그널이에요.
+  - `shouldRetry` (`(error: unknown, attempt: number) => boolean`, 선택): 재시도 여부를 결정하는 함수예요. `false`를 반환하면 즉시 에러를 던져요.
+    - `error`: 발생한 에러 객체예요.
+    - `attempt`: 현재 시도 횟수예요 (0부터 시작).
 
 #### 반환 값
 

docs/reference/function/retry.md

@@ -52,6 +52,33 @@ const data4 = await retry(
 );
 ```
 
+You can use `shouldRetry` option when you want to retry only on specific errors.
+
+```typescript
+import { retry } from 'es-toolkit/function';
+
+class NetworkError extends Error {
+  constructor(public status: number) {
+    super(`Network error: ${status}`);
+  }
+}
+
+// Retry only on 500+ errors
+const data5 = await retry(
+  async () => {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new NetworkError(response.status);
+    }
+    return response.json();
+  },
+  {
+    retries: 3,
+    shouldRetry: (error, attempt) => error instanceof NetworkError && error.status >= 500,
+  }
+);
+```
+
 You can also cancel retries using AbortSignal.
 
 ```typescript
@@ -86,6 +113,9 @@ try {
   - `retries` (`number`, optional): The number of times to retry. Defaults to `Infinity` for infinite retries.
   - `delay` (`number | (attempts: number) => number`, optional): The retry interval (in milliseconds). Can be a number or a function. Defaults to `0`.
   - `signal` (`AbortSignal`, optional): A signal that can cancel retries.
+  - `shouldRetry` (`(error: unknown, attempt: number) => boolean`, optional): A function that determines whether to retry. If it returns `false`, the error is thrown immediately.
+    - `error`: The error object that occurred.
+    - `attempt`: The current attempt count (starting from 0).
 
 #### Returns
 

docs/zh_hans/reference/function/retry.md

@@ -52,6 +52,33 @@ const data4 = await retry(
 );
 ```
 
+当只想在特定错误时重试时,可以使用 `shouldRetry` 选项。
+
+```typescript
+import { retry } from 'es-toolkit/function';
+
+class NetworkError extends Error {
+  constructor(public status: number) {
+    super(`Network error: ${status}`);
+  }
+}
+
+// 仅在 500+ 错误时重试
+const data5 = await retry(
+  async () => {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new NetworkError(response.status);
+    }
+    return response.json();
+  },
+  {
+    retries: 3,
+    shouldRetry: (error, attempt) => error instanceof NetworkError && error.status >= 500,
+  }
+);
+```
+
 也可以使用 AbortSignal 取消重试。
 
 ```typescript
@@ -86,6 +113,9 @@ try {
   - `retries` (`number`, 可选): 重试次数。默认值为 `Infinity`,无限重试。
   - `delay` (`number | (attempts: number) => number`, 可选): 重试间隔(毫秒)。可以使用数字或函数。默认值为 `0`。
   - `signal` (`AbortSignal`, 可选): 可以取消重试的信号。
+  - `shouldRetry` (`(error: unknown, attempt: number) => boolean`, 可选): 决定是否重试的函数。如果返回 `false`,则立即抛出错误。
+    - `error`: 发生的错误对象。
+    - `attempt`: 当前尝试次数 (从 0 开始)。
 
 #### 返回值
 

src/function/retry.spec.ts

@@ -75,4 +75,38 @@ describe('retry', () => {
     );
     expect(func).toHaveBeenCalledTimes(0);
   });
+
+  it('should retry when shouldRetry returns true', async () => {
+    const error = { status: 500, message: 'Server Error' };
+    const func = vi.fn().mockRejectedValueOnce(error).mockResolvedValue('success');
+    const shouldRetry = vi.fn((err: unknown) => (err as { status: number }).status >= 500);
+
+    const result = await retry(func, { retries: 3, shouldRetry });
+
+    expect(result).toBe('success');
+    expect(func).toHaveBeenCalledTimes(2);
+    expect(shouldRetry).toHaveBeenCalledWith(error, 0);
+  });
+
+  it('should not retry when shouldRetry returns false', async () => {
+    const error = { status: 400, message: 'Bad Request' };
+    const func = vi.fn().mockRejectedValue(error);
+    const shouldRetry = vi.fn((err: unknown) => (err as { status: number }).status >= 500);
+
+    await expect(retry(func, { retries: 3, shouldRetry })).rejects.toEqual(error);
+    expect(func).toHaveBeenCalledTimes(1);
+    expect(shouldRetry).toHaveBeenCalledWith(error, 0);
+  });
+
+  it('should pass attempt number to shouldRetry', async () => {
+    const error = new Error('failure');
+    const func = vi.fn().mockRejectedValue(error);
+    const shouldRetry = vi.fn((_err: unknown, attempt: number) => attempt < 2);
+
+    await expect(retry(func, { retries: 5, shouldRetry })).rejects.toThrow('failure');
+    expect(func).toHaveBeenCalledTimes(3);
+    expect(shouldRetry).toHaveBeenCalledWith(error, 0);
+    expect(shouldRetry).toHaveBeenCalledWith(error, 1);
+    expect(shouldRetry).toHaveBeenCalledWith(error, 2);
+  });
 });

src/function/retry.ts

@@ -21,10 +21,24 @@ interface RetryOptions {
    * An AbortSignal to cancel the retry operation.
    */
   signal?: AbortSignal;
+
+  /**
+   * A function that determines whether to retry based on the error and attempt number.
+   * If not provided, all errors will trigger a retry.
+   *
+   * @param {unknown} error - The error that occurred.
+   * @param {number} attempt - The current attempt number (0-indexed).
+   * @returns {boolean} Whether to retry.
+   *
+   * @example
+   * shouldRetry: (error, attempt) => error.status >= 500
+   */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
 }
 
 const DEFAULT_DELAY = 0;
 const DEFAULT_RETRIES = Number.POSITIVE_INFINITY;
+const DEFAULT_SHOULD_RETRY = () => true;
 
 /**
  * Retries a function that returns a promise until it resolves successfully.
@@ -62,6 +76,7 @@ export async function retry<T>(func: () => Promise<T>, retries: number): Promise
  * @param {number | ((attempts: number) => number)} [options.delay=0] - Delay(milliseconds) between retries.
  * @param {number} [options.retries=Infinity] - The number of retries to attempt.
  * @param {AbortSignal} [options.signal] - An AbortSignal to cancel the retry operation.
+ * @param {(error: unknown, attempt: number) => boolean} [options.shouldRetry] - A function that determines whether to retry.
  * @returns {Promise<T>} A promise that resolves with the value of the successful function call.
  *
  * @example
@@ -96,15 +111,18 @@ export async function retry<T>(func: () => Promise<T>, _options?: number | Retry
   let delay: number | ((attempts: number) => number);
   let retries: number;
   let signal: AbortSignal | undefined;
+  let shouldRetry: (error: unknown, attempt: number) => boolean;
 
   if (typeof _options === 'number') {
     delay = DEFAULT_DELAY;
     retries = _options;
     signal = undefined;
+    shouldRetry = DEFAULT_SHOULD_RETRY;
   } else {
     delay = _options?.delay ?? DEFAULT_DELAY;
     retries = _options?.retries ?? DEFAULT_RETRIES;
     signal = _options?.signal;
+    shouldRetry = _options?.shouldRetry ?? DEFAULT_SHOULD_RETRY;
   }
 
   let error;
@@ -119,6 +137,11 @@ export async function retry<T>(func: () => Promise<T>, _options?: number | Retry
     } catch (err) {
       error = err;
 
+      // Determine if we should retry based on the provided shouldRetry function
+      if (!shouldRetry(err, attempts)) {
+        throw err;
+      }
+
       const currentDelay = typeof delay === 'function' ? delay(attempts) : delay;
       await delayToolkit(currentDelay);
     }