docs: make the Bun.peek test samples pass under bun test

[robobun]

Problem

• The two Bun.peek test samples in docs/runtime/utils.mdx fail when run with bun test as printed. The output is error: Successfully tested promise rejection, (fail) peek and error: oh nooo, (fail) peek.status.
• Each sample creates a rejected promise and never handles it. Bun.peek and peek.status do not mark a promise as handled, so bun test reports the unhandled rejection as the failure of the test.
• The first sample also does not type-check: Property 'message' does not exist on type 'Promise<never>'.

Fix

• Add rejected.catch(() => {}); after the assertions in both samples, with a comment that gives the reason.
• Replace expect(peek(rejected).message) with toBeInstanceOf(Error) and toHaveProperty("message", ...). These assertions need no cast.
• Verified: both samples, extracted from the page and run as printed, pass on 1.4.2 and on 1.4.3-canary.1 (c6b7fcb). tsc against packages/bun-types reports no errors. test/js/bun/util/peek.test.ts already handles its rejection the same way.

Background

• Bun.peek(promise) reads the result of a settled promise without await. For a rejected promise it returns the rejection reason.
• A rejected promise that has no rejection handler is an unhandled rejection. bun test attributes it to the test that runs at that time and fails that test (docs/test/runtime-behavior.mdx, "Promise Rejections").
• TypeScript has no type for a rejection reason. The declaration is peek<T>(promise: T | Promise<T>): Promise<T> | T, so the result for Promise.reject(...) has the type Promise<never>.

Notes

Before, the two samples as printed on main, on bun 1.4.2 (744846f):

error: Successfully tested promise rejection
(fail) peek [0.31ms]
error: oh nooo
(fail) peek.status [0.11ms]
 0 pass
 2 fail

1.4.3-canary.1 (c6b7fcb) gives the same result, so the failure is not new. The samples date from #2148.

After, the two samples as printed on this branch, on both builds:

(pass) peek
(pass) peek.status
 2 pass
 0 fail
 9 expect() calls

Type check. I linked packages/bun-types into a scratch project ("types": ["bun-types"], strict) and ran the repository's tsc (6.0.2). Before: error TS2339: Property 'message' does not exist on type 'Promise<never>' on the first sample. The second sample already type-checked. After: no errors.

Placement of the .catch. It is after the assertions, the same as in test/js/bun/util/peek.test.ts. This order shows that peek left the rejection unhandled. The samples also pass with the .catch before the assertions.

Other shapes I tried for the first sample. expect(peek(rejected)).toBe(error) and .toEqual(new Error(...)) run correctly but do not type-check, because toBe and toEqual take the type of the expect argument (Promise<never>). Promise.reject<Error>(...) plus as Error type-checks and is what the test file does, but the type argument of Promise.reject is the fulfilled type, which misleads a reader of the docs.

The peek implementation is src/js/builtins/Peek.ts. It reads the promise state and the settled value through JSC intrinsics and does not touch the handled flag.

prettier --check docs/runtime/utils.mdx passes.

---

no test proof · iteration 0 · docs-only change; test-proof not applicable

[robobun]

Status

• Reproduced: I extracted the two Bun.peek samples from docs/runtime/utils.mdx and ran them with bun test as printed. Both fail on 1.4.2 and on 1.4.3-canary.1 (error: Successfully tested promise rejection, error: oh nooo).
• With this branch, both samples pass on the two builds, and tsc against packages/bun-types reports no errors.
• This PR changes the docs only.
• CI: buildkite/bun, Format, and Lint JavaScript pass. The automated reviews found no issues. The red claude-find-issues check is a helper workflow that does not run this diff. It fails on most pull requests at present, and ci: do not fail a pull request when the find-issues helper fails #42827 covers it.
• The PR is ready for a maintainer review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: 5dced743-053c-4ceb-aeb0-026d9997c7fc

📥 Commits

Reviewing files that changed from the base of the PR and between 630e921 and 14e1e36.

📒 Files selected for processing (1)

• docs/runtime/utils.mdx

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

Walkthrough

The documentation updates Bun.peek() rejection examples. The examples now verify Error values, check the expected message, and handle rejected promises after status inspection.

Changes

Bun.peek rejection documentation

Layer / File(s)	Summary
Update rejection examples docs/runtime/utils.mdx	The examples separately verify the rejected Error and its message. They attach catch handlers because peeking does not mark the rejection as handled. The peek.status example preserves the "rejected" assertion and handles the promise.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 14e1e

The documentation examples address rejected promises and type-checking issues without introducing merge-blocking risk.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: updating Bun.peek documentation test samples so they pass under bun test.
Description check	✅ Passed	The description explains the problem, the fix, and verification results. It does not use the template headings exactly, but it includes the required information and remains focused on the pull request…

---

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Code review found no issues

No high-confidence issues detected in this change.

One verified lower-impact observation (a convention, logging or cleanup point) was not posted.