## Summary
- Adds detailed documentation explaining JSRef's intended usage
- Includes a complete example showing common patterns
- Explains the three states (weak, strong, finalized)
- Provides guidelines on when to use strong vs weak references
- References real examples from the codebase (ServerWebSocket,
UDPSocket, MySQLConnection, ValkeyClient)
## Motivation
JSRef is a critical type for managing JavaScript object references from
native code, but it lacked comprehensive documentation explaining its
usage patterns and lifecycle management. This makes it clearer how to
properly use JSRef to:
- Safely maintain references to JS objects from native code
- Control whether references prevent garbage collection
- Manage the upgrade/downgrade pattern based on object activity
## Test plan
Documentation-only change, no functional changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
Previously, `JSC__JSPromise__wrap` would call
`JSC::JSPromise::resolvedPromise(globalObject, result)` without checking
if an exception was thrown during promise resolution. This
could happen in certain edge cases, such as when the result value is a
thenable that triggers stack overflow, or when the promise resolution
mechanism itself encounters an error.
When such exceptions occurred, they would escape back to the Zig code,
causing the CatchScope assertion to fail with "ASSERTION FAILED:
Unexpected exception observed on thread"
instead of being properly handled.
This PR adds an exception check immediately after calling
`JSC::JSPromise::resolvedPromise()` and before the `RELEASE_AND_RETURN`
macro. If an exception is detected, the function
now clears it and returns a rejected promise with the exception value,
ensuring consistent error handling behavior. This matches the pattern
already used earlier in the function
for the initial function call exception handling.
### How did you verify your code works?
new and existing tests
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
Fixes#23133
This PR fixes a bug where lifecycle hooks (`beforeAll`, `beforeEach`,
`afterAll`, `afterEach`) would throw an error when called with a
function and options object:
```typescript
beforeAll(() => {
console.log("beforeAll")
}, { timeout: 10_000 })
```
Previously, this would throw: `error: beforeAll() expects a function as
the second argument`
## Root Cause
The issue was in `ScopeFunctions.parseArguments()` at
`src/bun.js/test/ScopeFunctions.zig:342`. When parsing two arguments, it
always treated them as `(description, callback)` instead of checking if
they could be `(callback, options)`.
## Solution
Updated the two-argument parsing logic to check if the first argument is
a function and the second is not a function. In that case, treat them as
`(callback, options)` instead of `(description, callback)`.
## Changes
- Modified `src/bun.js/test/ScopeFunctions.zig` to handle `(callback,
options)` case
- Added regression test at `test/regression/issue/23133.test.ts`
## Testing
✅ Verified the fix works with the reproduction case from the issue
✅ Added comprehensive regression test covering all lifecycle hooks with
both object and numeric timeout options
✅ All existing jest-hooks tests still pass
✅ Test fails with `USE_SYSTEM_BUN=1` and passes with the fixed build
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: pfg <pfg@pfg.pw>
## Summary
Fixes#20689
Previously, `@layer` blocks were not being processed through the CSS
minifier, which meant that `color-scheme` properties inside `@layer`
blocks would not get the required `--buncss-light`/`--buncss-dark`
variable injections needed for browsers that don't support the
`light-dark()` function.
## Changes
- Implemented proper minification for `LayerBlockRule` in
`src/css/rules/rules.zig:218-221`
- Added recursive call to `minify()` on nested rules, matching the
behavior of other at-rules like `@media` and `@supports`
- Added comprehensive tests for `color-scheme` inside `@layer` blocks
## Test Plan
Added three new test cases in `test/js/bun/css/css.test.ts`:
1. Simple `@layer` with `color-scheme: dark`
2. Named layers (`@layer shm.colors`) with multiple rules
3. Anonymous `@layer` with `color-scheme: light dark` (generates media
query)
All tests pass:
```bash
bun bd test test/js/bun/css/css.test.ts -t "color-scheme"
```
## Before
```css
/* Input */
@layer shm.colors {
body.theme-dark {
color-scheme: dark;
}
}
/* Output (broken - no variables) */
@layer shm.colors {
body.theme-dark {
color-scheme: dark;
}
}
```
## After
```css
/* Input */
@layer shm.colors {
body.theme-dark {
color-scheme: dark;
}
}
/* Output (fixed - variables injected) */
@layer shm.colors {
body.theme-dark {
--buncss-light: ;
--buncss-dark: initial;
color-scheme: dark;
}
}
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
## Summary
Implements `onTestFinished()` for `bun:test`, which runs after all
`afterEach` hooks have completed.
## Implementation
- Added `onTestFinished` export to the test module in `jest.zig`
- Modified `genericHook` in `bun_test.zig` to handle `onTestFinished` as
a special case that:
- Can only be called inside a test (not in describe blocks or preload)
- Appends hooks at the very end of the execution sequence
- Added comprehensive tests covering basic ordering, multiple callbacks,
async callbacks, and interaction with other hooks
## Execution Order
When called inside a test:
1. Test body executes
2. `afterAll` hooks (if added inside the test)
3. `afterEach` hooks
4. `onTestFinished` hooks ✨
## Test Plan
- ✅ All new tests pass with `bun bd test`
- ✅ Tests correctly fail with `USE_SYSTEM_BUN=1` (feature not in
released version)
- ✅ Verifies correct ordering with `afterEach`, `afterAll`, and multiple
`onTestFinished` calls
- ✅ Tests async `onTestFinished` callbacks
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: pfg <pfg@pfg.pw>
### What does this PR do?
This PR adds documentation comments to `src/env_var.zig` that explain
the silent error handling behavior for environment variable
deserialization, based on the documentation from the closed PR #24036.
The comments clarify:
1. **Module-level documentation**: Environment variables may fail to
parse silently. When they do, the default behavior is to show a debug
warning and treat them as not set. This is intentional to avoid panics
from environment variable pollution.
2. **Inline documentation**: Deserialization errors cannot panic. Users
needing more robust configuration mechanisms should consider
alternatives to environment variables.
This documentation complements the behavior change introduced in commit
0dd6aa47ea which replaced panic with debug_warn.
### How did you verify your code works?
Ran `bun bd` successfully - the build completed without errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
When `process.nextTick` is overwritten, segv will be occured via
internal `processTick` call.
This patch fixes it.
### How did you verify your code works?
Tests.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
When using `fs.watch()` with `recursive: true`, the callback receives a
relative path from the watched directory (e.g., `'subdir/file.txt'`),
not just a filename.
Renaming the parameter from `filename` to `relativePath` makes this
behavior immediately clear to developers.
**Before:**
```ts
(event, filename) => {
console.log(`Detected ${event} in ${filename}`);
}
```
**After:**
```ts
(event, relativePath) => {
console.log(`Detected ${event} in ${relativePath}`);
}
```
This is a documentation-only change that improves clarity without
altering any functionality.
Co-authored-by: Braden Wong <git@bradenwong.com>
### Description
This PR fixes a crash caused by integer underflow in
`OKPacket.decodeInternal`.
Previously, when `read_size` exceeded `packet_size`, the subtraction
`packet_size - read_size` wrapped around, producing a huge `count` value
passed into `reader.read()`. This led to an integer overflow panic at
runtime.
### What does this PR do
- Added a safe subtraction guard in `decodeInternal` to clamp
`remaining` to `0`
when `read_size >= packet_size`.
- Ensures empty or truncated OK packets no longer cause crashes.
- Behavior for valid packets remains unchanged.
### Impact
Prevents integer overflow panics in MySQL OK packet parsing, improving
stability when handling short or empty responses (e.g., queries that
return no rows or minimal metadata).
### How did you verify your code works?
Tested with proof of concept:
https://github.com/Lillious/Bun-MySql-Integer-Overflow-PoC
---------
Co-authored-by: Ciro Spaciari <ciro.spaciari@gmail.com>
`ZigString.Slice.cloneIfNeeded` does *not* guarantee that the returned
slice will have been allocated by the provided allocator, which makes it
very easy to use this method incorrectly.
(For internal tracking: fixes ENG-21284)
### What does this PR do?
Adds missing null checking for `Bun.CookieMap#delete`.
### How did you verify your code works?
Tests
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
fixes: oven-sh/bun#23717
### What does this PR do?
- Align ProxyTunnel.onClose with
[HTTPClient.onClose](https://github.com/oven-sh/bun/blob/bun-v1.3.0/src/http.zig#L223-L241):
when a tunneled HTTPS response is in-progress and either
- parsing chunked trailers (trailer-line states), or
- transfer-encoding is identity with content_length == null while in
.body,
treat EOF as end-of-message and complete the request, rather than
ECONNRESET.
- Schedule proxy deref instead of deref inside callbacks to avoid
lifetime hazards.
### How did you verify your code works?
- `test/js/bun/http/proxy.test.ts`: raw TLS origin returns
close-delimited 200 OK; verified no ECONNRESET and body delivered.
- Test suite passes under bun bd test.
## Risk/compat
- Only affects CONNECT/TLS path. Direct HTTP/HTTPS unchanged. Behavior
mirrors existing
[HTTPClient.onClose](https://github.com/oven-sh/bun/blob/bun-v1.3.0/src/http.zig#L223-L241).
## Repro (minimal)
See issue; core condition is no Content-Length and no Transfer-Encoding
(close-delimited).
Co-authored-by: Ciro Spaciari <ciro.spaciari@gmail.com>
## Summary
This PR refactors `NapiEnv` to use `bun.ptr.ExternalShared` instead of
manual `ref()`/`deref()` calls, fixing a use-after-free bug in the NAPI
implementation.
## Bug Fixed
The original issue was in `ThreadSafeFunction.deinit()`:
1. `maybeQueueFinalizer()` schedules a task that holds a pointer to
`this` (which includes `this.env`)
2. The task will eventually call `onDispatch()` → `deinit()`
3. But `deinit()` immediately calls `this.env.deref()` before the task
completes
4. This could cause the `NapiEnv` reference count to go to 0 while the
pointer is still in use
## Changes
### Core Changes
- Added `NapiEnv.external_shared_descriptor` and `NapiEnv.EnvRef` type
alias
- Changed struct fields from `*NapiEnv` to `NapiEnv.EnvRef` where
ownership is required:
- `ThreadSafeFunction.env`
- `napi_async_work.env`
- `Finalizer.env` (now `NapiEnv.EnvRef.Optional`)
### API Changes
- Use `.get()` to access the raw `*NapiEnv` pointer from `EnvRef`
- Use `.cloneFromRaw(env)` when storing `env` in long-lived structs
- Use `EnvRef.deinit()` instead of manual `env.deref()`
- Removed manual `env.ref()` calls (now handled automatically by
`cloneFromRaw`)
### Safety Improvements
- Reference counting is now managed by the `ExternalShared` wrapper
- Prevents manual ref/deref mistakes
- Ensures proper cleanup even when operations are cancelled or fail
- No more use-after-free risks from premature deref
## Testing
Built successfully with `bun bd`. NAPI tests pass (66/83 tests, with 17
timeouts that appear to be pre-existing issues).
## Implementation Notes
Following the pattern from `Blob.zig` and `array_buffer.zig`, structs
that own a reference use `NapiEnv.EnvRef`, while functions that only
borrow temporarily continue to use `*NapiEnv` parameters.
The `ExternalShared` interface ensures:
- `.clone()` increments the ref count
- `.deinit()` decrements the ref count
- No direct access to the internal ref/deref functions
This makes the ownership semantics explicit and type-safe.
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: taylor.fish <contact@taylor.fish>
## Summary
Fixes `Buffer.isEncoding('')` to return `false` instead of `true`,
matching Node.js behavior.
## Description
Previously, `Buffer.isEncoding('')` incorrectly returned `true` in Bun,
while Node.js correctly returns `false`. This was caused by
`parseEnumerationFromView` in `JSBufferEncodingType.cpp` treating empty
strings (length 0) as valid utf8 encoding.
The fix modifies the switch statement to return `std::nullopt` for empty
strings, along with other invalid short strings.
## Changes
- Modified `src/bun.js/bindings/JSBufferEncodingType.cpp` to return
`std::nullopt` for empty strings
- Added regression test `test/regression/issue23966.test.ts`
## Test Plan
- [x] Test fails with `USE_SYSTEM_BUN=1 bun test
test/regression/issue23966.test.ts` (confirms bug exists)
- [x] Test passes with `bun bd test test/regression/issue23966.test.ts`
(confirms fix works)
- [x] Verified behavior matches Node.js v24.3.0
- [x] All test cases for valid/invalid encodings pass
Fixes#23966🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
Replaces raw napi_env pointers with WTF::Ref<NapiEnv> for improved
memory management and safety. Updates related classes, function
signatures, and finalizer handling to use reference counting. Adds
ref/deref methods to NapiEnv and integrates them in Zig and C++ code
paths, ensuring proper lifecycle management for N-API environments.
### How did you verify your code works?
found with https://github.com/oven-sh/bun/pull/21663 again
case found in `test/js/bun/net/socket.test.ts`
test `"should throw when a socket from a file descriptor has a bad file
descriptor"`
## Summary
Fixed a bug in the Windows bunx fast path code where UTF-8 byte length
was incorrectly used instead of UTF-16 code unit length when calculating
buffer offsets.
## Details
In `run_command.zig:1565`, the code was using `target_name.len` (UTF-8
byte length) instead of `encoded.len` (UTF-16 code unit length) when
calculating the total path length. This caused an index out of bounds
panic when package names contained multi-byte UTF-8 characters.
**Example scenario:**
- Package name contains character "中" (U+4E2D)
- UTF-8: 3 bytes (0xE4 0xB8 0xAD) → `target_name.len` counts as 3
- UTF-16: 1 code unit (0x4E2D) → `encoded.len` counts as 1
- Using the wrong length led to: `panic: index out of bounds: index 62,
len 60`
## Changes
- Changed line 1565 from `target_name.len` to `encoded.len`
## Test plan
- [x] Build compiles successfully
- [x] Code review confirms the fix addresses the root cause
- [ ] Windows-specific testing (if available)
Fixes the panic reported in Sentry/crash reports.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
toSlice has a bug
### How did you verify your code works?
---------
Co-authored-by: taylor.fish <contact@taylor.fish>
Co-authored-by: Dylan Conway <dylan.conway567@gmail.com>
`bun.String.toOwnedSliceReturningAllASCII` is supposed to return a
boolean indicating whether or not the string is entirely composed of
ASCII characters. However, the current implementation frequently
produces incorrect results:
* If the string is a `ZigString`, it always returns true, even though
`ZigString`s can be UTF-16 or Latin-1.
* If the string is a `StaticZigString`, it always returns false, even
though `StaticZigStrings` can be all ASCII.
* If the string is a 16-bit `WTFStringImpl`, it always returns false,
even though 16-bit `WTFString`s can be all ASCII.
* If the string is empty, it always returns false, even though empty
strings are valid ASCII strings.
`toOwnedSliceReturningAllASCII` is currently used in two places, both of
which assume its answer is accurate:
* `bun.webcore.Blob.fromJSWithoutDeferGC`
* `bun.api.ServerConfig.fromJS`
(For internal tracking: fixes ENG-21249)
### What does this PR do?
Adds missing exception check for ReadableStream.
### How did you verify your code works?
Tests
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
### How did you verify your code works?
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
Fixes a small bug I found in https://github.com/oven-sh/bun/pull/23107
which caused `SlicedString` not to correctly provide us with subslices.
This would have been a **killer** use-case for the interval utility we
decided to reject in https://github.com/oven-sh/bun/pull/23882. Consider
how nice the code could've been:
```zig
pub inline fn sub(this: SlicedString, input: string) SlicedString {
const buf_r = bun.math.interval.fromSlice(this.buf);
const inp_r = bun.math.interval.fromSlice(this.input);
if (Environment.allow_assert) {
if (!buf_r.superset(inp_r)) {
bun.Output.panic("SlicedString.sub input [{}, {}) is not a substring of the " ++
"slice [{}, {})", .{ start_i, end_i, start_buf, end_buf });
}
}
return SlicedString{ .buf = this.buf, .slice = input };
}
```
That's a lot more readable than the middle-school algebra we have here,
but here we are.
### How did you verify your code works?
CI
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
### What does this PR do?
msvc doesn't support c23 yet
### How did you verify your code works?
---------
Co-authored-by: Marko Vejnovic <marko@bun.com>
## Summary
This PR adds a Claude Code-powered issue deduplication system to help
reduce duplicate issues in the Bun repository.
### What's included:
1. **`/dedupe` slash command** (`.claude/commands/dedupe.md`)
- Claude Code command to find up to 3 duplicate issues for a given
GitHub issue
- Uses parallel agent searches with diverse keywords
- Filters out false positives
2. **Automatic dedupe on new issues**
(`.github/workflows/claude-dedupe-issues.yml`)
- Runs automatically when a new issue is opened
- Can also be triggered manually via workflow_dispatch
- Uses the Claude Code base action to run the `/dedupe` command
3. **Auto-close workflow**
(`.github/workflows/auto-close-duplicates.yml`)
- Runs daily to close issues marked as duplicates after 3 days
- Only closes if:
- Issue has a duplicate detection comment from bot
- Comment is 3+ days old
- No comments or activity after duplicate comment
- Author hasn't reacted with 👎 to the duplicate comment
4. **Auto-close script** (`scripts/auto-close-duplicates.ts`)
- TypeScript script that handles the auto-closing logic
- Fetches open issues and checks for duplicate markers
- Closes issues with proper labels and notifications
### How it works:
1. When a new issue is opened, the workflow runs Claude Code to analyze
it
2. Claude searches for duplicates and comments on the issue if any are
found
3. Users have 3 days to respond if they disagree
4. After 3 days with no activity, the issue is automatically closed
### Requirements:
- `ANTHROPIC_API_KEY` secret needs to be set in the repository settings
for the dedupe workflow to run
## Test plan
- [x] Verified workflow files have correct syntax
- [x] Verified script references correct repository (oven-sh/bun)
- [x] Verified slash command matches claude-code implementation
- [ ] Test workflow manually with workflow_dispatch (requires
ANTHROPIC_API_KEY)
- [ ] Monitor initial runs to ensure proper behavior
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
## Summary
Fixes a bug where the `Bun.build()` API with `compile: true` did not
properly apply sourcemaps, even when `sourcemap: "inline"` was
specified. This resulted in error stack traces showing bundled virtual
paths (`/$bunfs/root/`) instead of actual source file names and line
numbers.
## Problem
The CLI `bun build --compile --sourcemap` worked correctly, but the
equivalent API call did not:
```javascript
// This did NOT work (before fix)
await Bun.build({
entrypoints: ['./app.js'],
compile: true,
sourcemap: "inline" // <-- Was ignored/broken
});
```
Error output showed bundled paths:
```
error: Error from helper module
at helperFunction (/$bunfs/root/app.js:4:9) // ❌ Wrong path
at main (/$bunfs/root/app.js:9:17) // ❌ Wrong line numbers
```
## Root Cause
The CLI explicitly overrides any sourcemap type to `.external` when
compile mode is enabled (in `/workspace/bun/src/cli/Arguments.zig`):
```zig
// when using --compile, only `external` works
if (ctx.bundler_options.compile) {
opts.source_map = .external;
}
```
The API implementation in `JSBundler.zig` was missing this override.
## Solution
Added the same sourcemap override logic to `JSBundler.zig` when compile
mode is enabled:
```zig
// When using --compile, only `external` sourcemaps work, as we do not
// look at the source map comment. Override any other sourcemap type.
if (this.source_map != .none) {
this.source_map = .external;
}
```
Now error output correctly shows source file names:
```
error: Error from helper module
at helperFunction (helper.js:2:9) // ✅ Correct file
at main (app.js:4:3) // ✅ Correct line numbers
```
## Tests
Added comprehensive test coverage in
`/workspace/bun/test/bundler/bun-build-compile-sourcemap.test.ts`:
- ✅ `sourcemap: "inline"` works
- ✅ `sourcemap: true` works
- ✅ `sourcemap: "external"` works
- ✅ Multiple source files show correct file names
- ✅ Without sourcemap, bundled paths are shown (expected behavior)
All tests:
- ✅ Fail with `USE_SYSTEM_BUN=1` (confirms bug exists)
- ✅ Pass with `bun bd test` (confirms fix works)
- ✅ Use `tempDir()` to avoid disk space issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
### What does this PR do?
Adds support for `publicHoistPattern` in `bunfig.toml` and
`public-hoist-pattern` from `.npmrc`. This setting allows you to select
transitive packages to hoist to the root node_modules making them
available for all workspace packages.
```toml
[install]
# can be a string
publicHoistPattern = "@types*"
# or an array
publicHoistPattern = [ "@types*", "*eslint*" ]
```
`publicHoistPattern` only affects the isolated linker.
---
Adds `hoistPattern`. `hoistPattern` is the same as `publicHoistPattern`,
but applies to the `node_modules/.bun/node_modules` directory instead of
the root node_modules. Also the default value of `hoistPattern` is `*`
(everything is hoisted to `node_modules/.bun/node_modules` by default).
---
Fixes a determinism issue constructing the
`node_modules/.bun/node_modules` directory.
---
closes#23481closes#6160closes#23548
### How did you verify your code works?
Added tests for
- [x] only include patterns
- [x] only exclude patterns
- [x] mix of include and exclude
- [x] errors for unexpected expression types
- [x] excluding direct dependency (should still include)
- [x] match all with `*`
- [x] string and array expression types
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
`short` is signed in C++ by default and not unsigned. Switched to
`uint16_t` so it's unambiguous.
### How did you verify your code works?
There is a test
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
