bun-types: type Subprocess.stderr as undefined when the stderr option is undefined

[robobun]

Problem

• Bun.spawn(cmd, { stderr: undefined }) types proc.stderr as ReadableStream<Uint8Array<ArrayBuffer>>; at runtime (bun 1.4.0) it is undefined, so proc.stderr.text() type-checks and throws. The same happens with stdio: [.., .., undefined], with the Subprocess passed to onExit / ipc, with Subprocess<In, Out, "pipe" | undefined>["stderr"] (a plain ReadableStream, also what stderr: cond ? "pipe" : undefined infers under exactOptionalPropertyTypes), and with NullSubprocess["stderr"] (ReadableStream | undefined).
• Cause: Spawn.ReadableToIO (packages/bun-types/bun.d.ts:7439) maps the option type "pipe" | undefined to ReadableStream, and Subprocess uses it for both stdout and stderr (bun.d.ts:7548-7549). An undefined option means "use this slot's default", and the two slots have different defaults: the runtime starts from [Ignore, Pipe, Inherit] for spawn (src/runtime/api/bun/js_bun_spawn_bindings.rs:361-366), an undefined option leaves that default in place (spawn/stdio.rs:422-424), and an inherited stream reads back as undefined (subprocess/Readable.rs:266). The alias dates from when the declarations modelled the stderr default as "pipe" (bun-types: infer strict Subprocess from Bun.spawn() options #1501); bun-types: infer strict Subprocess from Bun.spawn() options, part 2 #2573 and later Improve types and autocomplete for Bun.spawn (fixes #17274) #19162 changed the omitted-option default to "inherit" without touching this arm.
• The JSDoc on the stdio, stdout and stderr options made the same claim ("pipe", undefined: the process has a ReadableStream).

Fix

• ReadableToIO<X, Default = "pipe">: an undefined X resolves to ReadableToIO<Default>; the other arms are unchanged. Subprocess.stdout and .readable pass "pipe", Subprocess.stderr passes "inherit". The option JSDoc lists undefined as "the default below" instead of grouping it with "pipe".
• Correct because a Subprocess only ever comes from Bun.spawn (js_bun_spawn_bindings.rs:1670 is the single construction site; spawnSync returns a plain object typed SyncSubprocess, the shell uses an internal type), so its stderr slot always defaults to "inherit". ReadableToSyncIO is untouched because spawnSync defaults both slots to "pipe"; WritableToIO is untouched because stdin's default ("ignore") already maps to undefined.
• Why it is worth having on its own: the declaration is unsound (it accepts code that throws), the correction is the one place in the declarations that can know the slot, and it costs nothing elsewhere. Default defaults to "pipe", so Bun.Spawn.ReadableToIO<X> in user code keeps its meaning, and the holder unions do not move (Subprocess["stdout"] / ["stderr"] and WritableSubprocess["stderr"] stay ReadableStream | number | undefined; pinned in the fixture). Type-checking test/, src/js and src/ against the changed declarations produces exactly the same diagnostics as before.
• Limit: stderr: cond ? "pipe" : undefined as a named option still infers Err = "pipe" under default compiler options, because TypeScript drops undefined when inferring through an optional property; no declaration shape changes that. It is fixed under exactOptionalPropertyTypes, and the same union through the stdio tuple or explicit type arguments is fixed under any options (both asserted).
• Verified: test/integration/bun-types/fixture/spawn.ts asserts stderr: undefined / stdout: undefined through both spawn overloads, the stdio tuple (literal undefined and "pipe" | undefined), the onExit / ipc argument, explicit Subprocess<...> arguments, NullSubprocess["stderr"], both forms of the alias, and spawnSync with undefined options (still Buffer). Against the unfixed bun.d.ts these lines produce 10 diagnostics (below; spawn.ts:241-302); with the fix bun test test/integration/bun-types/bun-types.test.ts passes all 16 cases (tsc with and without lib.dom, and tsgo). That file is what .github/workflows/bun-types.yml runs, so CI checks the new lines through the existing whole-fixture cases.
• bun-types.test.ts also gains a case running tsc over fixture/spawn.ts alone, because under a debug build (bun bd test) the whole-fixture cases are skipped and nothing else would exercise the fixture; it fails without the bun.d.ts change and passes with it. It is byte-identical to the block bun-types: type Subprocess stdio properties by what the runtime exposes for each stdio option #39283 carries (one hunk for git), and it is interim: test(bun-types): replace the tsgo and Bun.mmap spawns with one whole-fixture tsc run, enforced by a lint #39270 replaces this per-file pattern with one whole-fixture check that runs on debug builds too, plus a lint holding bun-types.test.ts to a single compiler spawn. If test(bun-types): replace the tsgo and Bun.mmap spawns with one whole-fixture tsc run, enforced by a lint #39270 lands first, this block is dropped from here on rebase and the fixture lines are covered by its case; if this lands first, test(bun-types): replace the tsgo and Bun.mmap spawns with one whole-fixture tsc run, enforced by a lint #39270's lint flags the block on its rebase and it goes out with the Bun.mmap block test(bun-types): replace the tsgo and Bun.mmap spawns with one whole-fixture tsc run, enforced by a lint #39270 already removes. Either way nothing from it survives.
• Overlap with bun-types: type Subprocess stdio properties by what the runtime exposes for each stdio option #39283, which rewrites the other arms of these aliases and explicitly leaves this arm out: git merge-tree of the two branches conflicts only in the alias declaration and the Subprocess.stdout / stderr members (where bun-types: type Subprocess stdio properties by what the runtime exposes for each stdio option #39283 adds JSDoc), and the changes compose. Whichever lands second resolves it by adding the Default parameter and the X extends undefined ? ReadableToIO<Default> arm in front of bun-types: type Subprocess stdio properties by what the runtime exposes for each stdio option #39283's arms, passing "pipe" / "inherit" on the three Subprocess members, and merging the two alias doc comments; the option JSDoc and the fixture additions (appended at the end of spawn.ts) merge on their own. The branch merges cleanly with bun-types: declare Subprocess.writable and lint interface Subprocess against the classes.ts table #39279 and test(bun-types): replace the tsgo and Bun.mmap spawns with one whole-fixture tsc run, enforced by a lint #39270.
• Adjacent declaration issues found while here and tracked separately, not changed by this PR: NullSubprocess / NullSyncSubprocess list undefined in parameters whose default is "pipe" (so NullSubprocess["stdout"] stays ReadableStream | undefined), and the terminal option makes all three stdio properties null at runtime, which none of the mapping types model.

Background

• Bun.spawn infers one type parameter per stdio slot (In, Out, Err) from the stdin / stdout / stderr options or the stdio tuple. A parameter whose option is omitted takes the declared default ("ignore", "pipe", "inherit"); an option that is present but undefined makes the parameter undefined itself. Subprocess<In, Out, Err> then derives each property's type with a conditional type alias, which is therefore the place where an undefined parameter has to be turned back into that slot's default.
• These aliases are distributive: applied to a union they map each member and union the results. That is why "pipe" | undefined becomes ReadableStream | undefined for stderr, and why the unconstrained holder type Subprocess (every option at once) still lists every possible value.

Diagnostics the new fixture lines produce against the unfixed bun.d.ts

spawn.ts(241,34): error TS2344: Type 'undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(245,34): error TS2344: Type 'undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(257,34): error TS2344: Type 'undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(265,34): error TS2344: Type 'ReadableStream<Uint8Array<ArrayBuffer>> | undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
  Type 'undefined' is not assignable to type 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(271,38): error TS2344: Type 'undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(274,38): error TS2344: Type 'undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(290,7): error TS2344: Type 'ReadableStream<Uint8Array<ArrayBuffer>> | undefined' does not satisfy the constraint 'ReadableStream<Uint8Array<ArrayBuffer>>'.
  Type 'undefined' is not assignable to type 'ReadableStream<Uint8Array<ArrayBuffer>>'.
spawn.ts(294,44): error TS2554: Expected 2 arguments, but got 0.
spawn.ts(300,16): error TS2314: Generic type 'ReadableToIO' requires 1 type argument(s).
spawn.ts(302,15): error TS2314: Generic type 'ReadableToIO' requires 1 type argument(s).

Runtime probe (bun 1.4.0, linux x64)

spawn     stderr: undefined                 -> undefined
spawn     stdout: undefined                 -> ReadableStream
spawn     stdio: [undefined x3]             -> stdin undefined, stdout ReadableStream, stderr undefined
spawnSync stdout/stderr: undefined          -> Buffer, Buffer
spawnSync stdio: ["ignore", undef, undef]   -> Buffer, Buffer

[robobun]

Reproduced at the type level against the current bun.d.ts (tsc 6.0.2 and tsgo): Bun.spawn(["cat"], { stderr: undefined }).stderr is typed ReadableStream<Uint8Array<ArrayBuffer>>, and at runtime (bun 1.4.0) it is undefined because an undefined option keeps the slot's default and spawn's stderr default is "inherit". The new assertions in test/integration/bun-types/fixture/spawn.ts produce 10 diagnostics without the bun.d.ts change and none with it, under both the release test cases and the debug-build tsc case (bun bd test test/integration/bun-types/bun-types.test.ts).

Fix is in this PR; see the description for the reasoning and the related open PRs (#39283, #39279, #39270) that touch the same lines.

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 5 minutes

Limit details: You’ve used all 5 included reviews currently available under your plan.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e8be2905-f359-4933-961b-08f9e538c5b3

📥 Commits

Reviewing files that changed from the base of the PR and between 83d65fa and e0e7b62.

📒 Files selected for processing (3)

• packages/bun-types/bun.d.ts
• test/integration/bun-types/bun-types.test.ts
• test/integration/bun-types/fixture/spawn.ts

---

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

[claude]

LGTM — types-only fix aligning Subprocess.stderr's type with runtime behavior when the option is undefined.

What was reviewed:

• ReadableToIO<X, Default> change: distributivity over unions, the Exclude<Readable, undefined> constraint on Default (prevents recursion), and backward compat of the single-arg form — all hold.
• Runtime defaults confirmed against js_bun_spawn_bindings.rs:361-366 ([Ignore, Pipe, Inherit]; sync overrides both to Pipe).
• Holder types Subprocess["stderr"] / WritableSubprocess["stderr"] stay ReadableStream | number | undefined; NullSubprocess["stderr"] narrowing to undefined is correct.
• New bun-types.test.ts case follows the existing Bun.mmap block pattern; fixture assertions cover both overloads, stdio tuple, onExit/ipc, spawnSync, and explicit type args.

Extended reasoning...

Overview

This PR fixes a type-vs-runtime mismatch in packages/bun-types/bun.d.ts: when stderr: undefined is passed to Bun.spawn, the runtime falls back to the slot default ("inherit"), so proc.stderr is undefined — but the types previously said ReadableStream. The fix adds a second Default type parameter to ReadableToIO so the undefined arm resolves to the slot's actual default; Subprocess.stderr passes "inherit", stdout/readable pass "pipe". JSDoc on the stdio/stdout/stderr options is updated to stop claiming undefined means pipe. Fixture assertions and a debug-build tsc case are added.

Security risks

None. This is a .d.ts-only change plus type-check test fixtures; no compiled runtime code is touched.

Level of scrutiny

Low-to-medium. Type declarations for a public API — the risk is breaking existing user code that type-checked before. I checked the specific concerns: the single-arg ReadableToIO<X> keeps its old meaning (Default defaults to "pipe"); the unconstrained Subprocess["stderr"] and WritableSubprocess["stderr"] unions are unchanged (pinned in the fixture); NullSubprocess["stderr"] narrows from ReadableStream | undefined to undefined, which is a strict correction (none of "ignore" | "inherit" | null | undefined produces a stream at runtime for stderr). The Default extends Exclude<Readable, undefined> constraint guarantees the recursive arm terminates.

Other factors

The runtime claim was verified directly against src/runtime/api/bun/js_bun_spawn_bindings.rs:361-366: async spawn starts from [Ignore, Pipe, Inherit] and spawnSync sets both output slots to Pipe, matching the PR's mapping (and why ReadableToSyncIO is left alone). The new test in bun-types.test.ts is byte-for-byte the same shape as the existing Bun.mmap debug-build check just above it. The fixture coverage is thorough — both spawn overloads, the stdio tuple with literal and union undefined, onExit/ipc, explicit Subprocess<...> args, spawnSync, and the alias itself — and the PR description documents that the fixture fails (10 diagnostics) against the unfixed declarations. No outstanding reviewer comments.

[robobun]

^{Updated 2:21 AM PT - Aug 16th, 2026}

✅ @robobun, your commit e0e7b620eaf69ba37b7f6b582a51b1f8ecb2d399 passed in Build #99365! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 39297

That installs a local version of the PR into your bun-39297 executable, so you can run:

bun-39297 --bun

[claude]

LGTM — types-only fix aligning Subprocess.stderr with runtime behavior when the option is undefined.

What was reviewed:

• ReadableToIO's new Default parameter distributes correctly over unions; NullSubprocess["stderr"], WritableSubprocess["stderr"] (the any path) and unconstrained Subprocess["stderr"] all resolve as the fixture asserts.
• Backward compat: one-arg ReadableToIO<X> keeps its old meaning via Default = "pipe"; ReadableToSyncIO and WritableToIO are correctly left alone.
• New fixture lines are appended, so the pinned spawn.ts:62/:107 diagnostics in the lib.dom case don't shift; the new Bun.spawn describe block mirrors the existing Bun.mmap block byte-for-byte in shape.

Extended reasoning...

Overview

This PR fixes a type-vs-runtime mismatch in packages/bun-types/bun.d.ts: Bun.spawn(cmd, { stderr: undefined }) typed proc.stderr as ReadableStream when the runtime returns undefined (because an explicit undefined option keeps the slot's default, and stderr's default for spawn is "inherit"). The fix adds a second Default parameter to Spawn.ReadableToIO so undefined recurses into the slot's actual default, and Subprocess.stderr passes "inherit" while stdout/readable pass "pipe". JSDoc on the stdio/stdout/stderr options is corrected to match. The test file gains a debug-build-friendly tsc case and the fixture gains ~75 lines of type assertions covering both spawn overloads, the stdio tuple, onExit/ipc callbacks, spawnSync, the holder unions, and the alias itself.

Security risks

None. This is a .d.ts type-declaration and JSDoc change plus type-check fixtures; nothing here executes at runtime or affects any security-sensitive path.

Level of scrutiny

Low-to-medium. Types-only changes cannot break runtime behavior; the risk is limited to (a) breaking existing user type-checks and (b) the new fixture assertions being wrong. For (a), Default defaults to "pipe", so the one-parameter form ReadableToIO<X> is unchanged, and I traced the distributive-conditional evaluation for NullSubprocess["stderr"] (all four union members → undefined), WritableSubprocess["stderr"] (any → both branches → ReadableStream | number | undefined), and unconstrained Subprocess["stderr"] (full Readable union → same) — each matches what the fixture pins. For (b), the assertions match the runtime probe in the PR description and the runtime source references ([Ignore, Pipe, Inherit] defaults for spawn, both "pipe" for spawnSync).

Other factors

• The new fixture lines are appended after the last existing block, so the line-pinned lib.dom diagnostics at spawn.ts:62:38 and spawn.ts:107:38 in bun-types.test.ts remain valid; the new assertions use the same expectType(...).is<ReadableStream<...>>() shape that already appears earlier in the fixture without producing lib.dom diagnostics.
• The new describe("Bun.spawn") block is structurally identical to the existing describe("Bun.mmap") block right above it (same tsconfig setup, same tsc spawn, same stdout/stderr/exitCode assertion order), and the PR notes it is byte-identical to the same block in two related open PRs so they merge cleanly.
• tsd.expectType<T>() (zero-arg) and .is<X> are both supported by fixture/utilities.ts, and Bun.Spawn is the real namespace name (SpawnOptions is an export import alias), so Bun.Spawn.ReadableToIO in the fixture resolves.
• No prior human reviews or unaddressed comments on the timeline; the bug-hunting pass found nothing.