Skip to content

docs: document function form of retryDelay#593

Open
Ruby-Leung wants to merge 1 commit into
unjs:mainfrom
Ruby-Leung:docs/retry-delay-function
Open

docs: document function form of retryDelay#593
Ruby-Leung wants to merge 1 commit into
unjs:mainfrom
Ruby-Leung:docs/retry-delay-function

Conversation

@Ruby-Leung
Copy link
Copy Markdown

@Ruby-Leung Ruby-Leung commented Jun 4, 2026

retryDelay can be a function (context: FetchContext) => number, supported since #372, but the Auto Retry section of the README only documents the numeric form.

This PR adds a short note that retryDelay can be a function receiving the fetch context, plus an example that honors a server's Retry-After response header.

Docs-only; no code changes.

Summary by CodeRabbit

  • Documentation
    • Added guidance for configuring dynamic retry delays, showing how to provide a retry delay as a function that inspects the request/response context.
    • Included an example demonstrating how to derive retry timing from a server's Retry-After header to improve retry behavior and resiliency.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Jun 4, 2026

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: adbed1e0-7df8-4d22-bae7-63c31317f60d

📥 Commits

Reviewing files that changed from the base of the PR and between 3d9f00e and cef9355.

📒 Files selected for processing (1)
  • README.md

📝 Walkthrough

Walkthrough

This PR updates README.md to document that retryDelay may be a function receiving the fetch context (request, options, response, error) and includes a TypeScript example computing delay from the Retry-After response header.

Changes

Documentation

Layer / File(s) Summary
Dynamic retry delay function documentation
README.md
Added documentation explaining retryDelay can be a function receiving request, options, response, and error, with a TypeScript example deriving delay from the server's Retry-After response header and falling back to a default.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

I nibble docs with carrot delight,
A retryDelay that reads the night,
Headers hum when to try once more,
Milliseconds gently restore,
Hop, retry—happy request flight! 🐰✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: document function form of retryDelay' directly and clearly describes the main change: documenting the function form of the retryDelay option in the README.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 134-142: The retryDelay example uses
Number(context.response?.headers.get("retry-after")) which treats null as 0;
change retryDelay to first read the header into a variable (e.g.,
retryAfterHeader = context.response?.headers.get("retry-after")), then only
convert it to a number if the header is non-null (or use parseInt and check
!isNaN), and finally use Number.isFinite(retryAfter) to decide between
retryAfter * 1000 and the 500ms fallback; update the example around ofetch's
retryDelay/context.response?.headers.get to implement this null-check before
numeric conversion.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ae56ac60-001a-4a37-b890-6713c3538df0

📥 Commits

Reviewing files that changed from the base of the PR and between dfbe3ca and 3d9f00e.

📒 Files selected for processing (1)
  • README.md

Comment thread README.md
Comment on lines +134 to +142
```ts
await ofetch("/api", {
retry: 3,
retryDelay: (context) => {
const retryAfter = Number(context.response?.headers.get("retry-after"));
return Number.isFinite(retryAfter) ? retryAfter * 1000 : 500;
},
});
```
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix the null-handling edge case in the example.

When the Retry-After header is absent, headers.get("retry-after") returns null. Since Number(null) evaluates to 0 (which is finite), the current example returns a 0ms delay instead of the intended 500ms fallback.

🛡️ Proposed fix to handle missing header correctly
   retryDelay: (context) => {
-    const retryAfter = Number(context.response?.headers.get("retry-after"));
-    return Number.isFinite(retryAfter) ? retryAfter * 1000 : 500;
+    const retryAfterHeader = context.response?.headers.get("retry-after");
+    const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : NaN;
+    return Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500;
   },
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 134 - 142, The retryDelay example uses
Number(context.response?.headers.get("retry-after")) which treats null as 0;
change retryDelay to first read the header into a variable (e.g.,
retryAfterHeader = context.response?.headers.get("retry-after")), then only
convert it to a number if the header is non-null (or use parseInt and check
!isNaN), and finally use Number.isFinite(retryAfter) to decide between
retryAfter * 1000 and the 500ms fallback; update the example around ofetch's
retryDelay/context.response?.headers.get to implement this null-check before
numeric conversion.

The function form retryDelay(context) => number has been supported since unjs#372 but the Auto Retry section only documents the numeric form. Adds a note and a Retry-After example. Docs-only.
@Ruby-Leung Ruby-Leung force-pushed the docs/retry-delay-function branch from 3d9f00e to cef9355 Compare June 4, 2026 10:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant