Complex retry policies implemented

Author: gkoos

README.md

@@ -1,6 +1,6 @@
 # @gkoos/ffetch
 
-**A TypeScript-first fetch wrapper that adds production-grade resilience in <4 kB.**
+**A production-ready TypeScript-first drop-in replacement for native fetch.**
 
 - **Timeouts** – per-request or global
 - **Retries** – exponential back-off + jitter
@@ -24,13 +24,15 @@ import createClient from '@gkoos/ffetch'
 const f = createClient({
   timeout: 5000,
   retries: 3,
-  retryDelay: (n) => 2 ** n * 100 + Math.random() * 100,
+  retryDelay: ({ attempt }) => 2 ** attempt * 100 + Math.random() * 100,
 })
 
 const res = await f('https://api.example.com/v1/users')
 const data = await res.json()
 ```
 
+---
+
 ## API
 
 createClient(options?)
@@ -39,7 +41,7 @@ createClient(options?)
 | ------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
 | `timeout`    | `number` (ms)                                                                                                             | whole-request timeout                      |
 | `retries`    | `number` (0)                                                                                                              | max retry attempts                         |
-| `retryDelay` | `number \| fn` (exponential backoff + jitter)                                                                             | delay between retries                      |
+| `retryDelay` | `number \| (ctx: { attempt, request, response, error }) => number` (exponential backoff + jitter)                         | delay between retries                      |
 | `circuit`    | `{ threshold, reset }`                                                                                                    | circuit-breaker rules                      |
 | `hooks`      | `{ before, after, onError, onRetry, onTimeout, onAbort, onCircuitOpen, onComplete, transformRequest, transformResponse }` | lifecycle hooks/interceptors, transformers |
 
@@ -52,6 +54,22 @@ type FFetch = (
 ) => Promise<Response>
 ```
 
+### Defaults
+
+| Option        | Default Value / Logic                                                                                |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| `timeout`     | `5000` ms (5 seconds)                                                                                |
+| `retries`     | `0` (no retries)                                                                                     |
+| `retryDelay`  | Exponential backoff + jitter: <br>`({ attempt }) => 2 ** attempt * 200 + Math.random() * 100`        |
+| `shouldRetry` | Retries on network errors, HTTP 5xx, or 429. <br>Does not retry on 4xx (except 429) or abort/timeout |
+| `circuit`     | `undefined` (circuit breaker disabled by default)                                                    |
+| `hooks`       | `{}` (no hooks by default)                                                                           |
+
+**Note:**
+
+- The first retry attempt uses `attempt = 2` (i.e., the first call is attempt 1, first retry is 2).
+- `shouldRetry` default logic: retries on network errors, HTTP 5xx, or 429; does not retry on 4xx (except 429), abort, or timeout errors.
+
 ## Advanced
 
 ### Per-request overrides
@@ -69,7 +87,7 @@ await f('https://api.example.com/v1/users', {
 
 // Use a custom retry delay function for a single request
 await f('https://api.example.com/v1/data', {
-  retryDelay: (attempt) => 100 * attempt, // linear backoff for this request
+  retryDelay: ({ attempt }) => 100 * attempt, // linear backoff for this request
 })
 
 // Override hooks for a single request
@@ -80,6 +98,33 @@ await f('https://api.example.com/v1/metrics', {
 })
 ```
 
+### Retry/Backoff and Retry Policy
+
+#### retryDelay
+
+You can provide a function for `retryDelay` that receives a context object:
+
+```typescript
+retryDelay: ({ attempt, request, response, error }) => {
+  // attempt: number (starts at 2 for first retry)
+  // request: Request
+  // response: Response | undefined
+  // error: unknown
+  return 100 * attempt
+}
+```
+
+#### shouldRetry
+
+You can provide a function for `shouldRetry` that receives the same context object:
+
+```typescript
+shouldRetry: ({ attempt, request, response, error }) => {
+  // Retry only on 503
+  return response?.status === 503
+}
+```
+
 ### Custom Error Types
 
 `ffetch` throws custom error classes for robust error handling. You can catch and handle these errors as needed:
@@ -209,7 +254,7 @@ These hooks allow you to inject authentication, modify request/response bodies,
 
 ---
 
-### Note on Timeout vs Abort Errors
+## Note on Timeout vs Abort Errors
 
 In most environments, `ffetch` will throw a `TimeoutError` if a request times out, and an `AbortError` if the user aborts the request. However, due to differences in how abort signals are handled in Node.js, browsers, and CI environments, a timeout may sometimes surface as an `AbortError` instead of a `TimeoutError` (especially in automated test environments).
 
@@ -229,6 +274,11 @@ try {
 
 This is a pragmatic workaround for cross-environment compatibility.
 
-### License
+## Planned Features
+
+- Middleware support
+- Built-in caching
+
+## License
 
 MIT © 2025 gkoos

src/client.ts

@@ -76,11 +76,16 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
 
       // Wrap shouldRetry to call onRetry hook
       let attempt = 0
-      const shouldRetryWithHook = (err: unknown, res?: Response) => {
-        attempt++
-        const retrying = effectiveShouldRetry(err, res)
+      const shouldRetryWithHook = (ctx: import('./types').RetryContext) => {
+        attempt = ctx.attempt
+        const retrying = effectiveShouldRetry(ctx)
         if (retrying && attempt <= effectiveRetries) {
-          effectiveHooks.onRetry?.(request, attempt - 1, err, res)
+          effectiveHooks.onRetry?.(
+            request,
+            attempt - 1,
+            ctx.error,
+            ctx.response
+          )
         }
         return retrying
       }
@@ -132,7 +137,8 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
           },
           effectiveRetries,
           effectiveRetryDelay,
-          shouldRetryWithHook
+          shouldRetryWithHook,
+          request
         )
         clearTimeout(timeoutTimer)
         if (effectiveHooks.transformResponse) {

src/retry.ts

@@ -1,31 +1,42 @@
-export type RetryDelay = number | ((attempt: number) => number)
+import type { RetryContext } from './types.js'
 
-export const defaultDelay: RetryDelay = (n) =>
-  2 ** n * 200 + Math.random() * 100
+export type RetryDelay = number | ((ctx: RetryContext) => number)
 
-export async function retry<T>(
-  fn: () => Promise<T>,
+export const defaultDelay: RetryDelay = (ctx) =>
+  2 ** ctx.attempt * 200 + Math.random() * 100
+
+export async function retry(
+  fn: () => Promise<Response>,
   retries: number,
   delay: RetryDelay,
-  shouldRetry: (err: unknown, res?: T) => boolean = () => true
-): Promise<T> {
+  shouldRetry: (ctx: RetryContext) => boolean = () => true,
+  request: Request
+): Promise<Response> {
   let lastErr: unknown
-  let lastRes: T | undefined
+  let lastRes: Response | undefined
 
   for (let i = 0; i <= retries; i++) {
+    const ctx: RetryContext = {
+      attempt: i + 1,
+      request,
+      response: lastRes,
+      error: lastErr,
+    }
     try {
       lastRes = await fn()
-      // Check if we should retry based on the resolved value (e.g., HTTP status)
-      if (i < retries && shouldRetry(undefined, lastRes)) {
-        const wait = typeof delay === 'function' ? delay(i + 1) : delay
+      ctx.response = lastRes
+      ctx.error = undefined
+      if (i < retries && shouldRetry(ctx)) {
+        const wait = typeof delay === 'function' ? delay(ctx) : delay
         await new Promise((r) => setTimeout(r, wait))
         continue
       }
       return lastRes
     } catch (err) {
       lastErr = err
-      if (i === retries || !shouldRetry(err, lastRes)) throw err
-      const wait = typeof delay === 'function' ? delay(i + 1) : delay
+      ctx.error = err
+      if (i === retries || !shouldRetry(ctx)) throw err
+      const wait = typeof delay === 'function' ? delay(ctx) : delay
       await new Promise((r) => setTimeout(r, wait))
     }
   }

src/should-retry.ts

@@ -1,12 +1,14 @@
 import { AbortError, CircuitOpenError, TimeoutError } from './error.js'
+import type { RetryContext } from './types.js'
 
-export function shouldRetry(err: unknown, res?: Response): boolean {
+export function shouldRetry(ctx: RetryContext): boolean {
+  const { error, response } = ctx
   if (
-    err instanceof AbortError ||
-    err instanceof CircuitOpenError ||
-    err instanceof TimeoutError
+    error instanceof AbortError ||
+    error instanceof CircuitOpenError ||
+    error instanceof TimeoutError
   )
     return false
-  if (!res) return true // network error
-  return res.status >= 500 || res.status === 429
+  if (!response) return true // network error
+  return response.status >= 500 || response.status === 429
 }

src/types.ts

@@ -1,10 +1,17 @@
 import type { Hooks } from './hooks'
 
+export interface RetryContext {
+  attempt: number
+  request: Request
+  response?: Response
+  error?: unknown
+}
+
 export interface FFetchOptions {
   timeout?: number
   retries?: number
-  retryDelay?: number | ((attempt: number) => number)
-  shouldRetry?: (err: unknown, res?: Response) => boolean
+  retryDelay?: number | ((ctx: RetryContext) => number)
+  shouldRetry?: (ctx: RetryContext) => boolean
   circuit?: { threshold: number; reset: number }
   hooks?: Hooks
 }

test/client.override.test.ts

@@ -47,26 +47,29 @@ describe('FFetch per-request override', () => {
 
   it('overrides retryDelay per request', async () => {
     const delays: number[] = []
-    const client = createClient({ retryDelay: () => 1 })
+    const client = createClient({ retryDelay: ({ attempt: _attempt }) => 1 })
     mockFetchImpl(new Response('ok'), { failTimes: 2 })
     const origSetTimeout = globalThis.setTimeout
     vi.stubGlobal('setTimeout', (fn, ms) => {
       delays.push(ms)
       return origSetTimeout(fn, 0)
     })
-    await client('http://x', { retries: 2, retryDelay: (a) => 42 + a })
+    await client('http://x', {
+      retries: 2,
+      retryDelay: ({ attempt: _attempt }) => 43 + _attempt,
+    })
     // Only check retry delays (ignore timeout delay, which is >= 1000ms)
     const retryDelays = delays.filter((d) => d < 1000)
-    expect(retryDelays[0]).toBe(43)
-    expect(retryDelays[1]).toBe(44)
+    expect(retryDelays[0]).toBe(44)
+    expect(retryDelays[1]).toBe(45)
   })
 
   it('overrides shouldRetry per request', async () => {
     const client = createClient({ shouldRetry: () => false, retries: 2 })
     let called = false
     mockFetchImpl(new Response('ok'), { failTimes: 1 })
     await client('http://x', {
-      shouldRetry: (_err) => {
+      shouldRetry: (_ctx) => {
         called = true
         return true
       },

test/client.test.ts

@@ -72,9 +72,11 @@ describe('retry with shouldRetry', () => {
 describe('custom shouldRetry', () => {
   it('uses custom retry policy and retries only once', async () => {
     // custom policy that only retries on 503
-    const customShouldRetry = (err: unknown, res?: Response): boolean => {
-      if (res) {
-        return res.status === 503
+    const customShouldRetry = (
+      ctx: import('../src/types').RetryContext
+    ): boolean => {
+      if (ctx.response) {
+        return ctx.response.status === 503
       }
       return false
     }