bun-types 1.3.3-canary.20251114T140703 → 1.3.3-canary.20251116T140533

package/docs/pm/overrides.mdx

@@ -5,14 +5,14 @@ description: "Control metadependency versions with npm overrides and Yarn resolu
 
 Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies.
 
+{/* prettier-ignore */}
 ```json package.json icon="file-json"
 {
   "name": "my-app",
   "dependencies": {
     "foo": "^2.0.0"
   },
-  "overrides": {
-    // [!code ++]
+  "overrides": { // [!code ++]
     "bar": "~4.4.0" // [!code ++]
   } // [!code ++]
 }
@@ -50,14 +50,14 @@ Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the sp
   overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported.
 </Note>
 
+{/* prettier-ignore */}
 ```json package.json icon="file-json"
 {
   "name": "my-app",
   "dependencies": {
     "foo": "^2.0.0"
   },
-  "overrides": {
-    // [!code ++]
+  "overrides": { // [!code ++]
     "bar": "~4.4.0" // [!code ++]
   } // [!code ++]
 }
@@ -69,14 +69,14 @@ The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"over
 
 As with `"overrides"`, _nested resolutions_ are not currently supported.
 
+{/* prettier-ignore */}
 ```json package.json icon="file-json"
 {
   "name": "my-app",
   "dependencies": {
     "foo": "^2.0.0"
   },
-  "resolutions": {
-    // [!code ++]
+  "resolutions": { // [!code ++]
     "bar": "~4.4.0" // [!code ++]
   } // [!code ++]
 }

package/docs/pm/workspaces.mdx

@@ -30,7 +30,7 @@ It's common for a monorepo to have the following structure:
 
 In the root `package.json`, the `"workspaces"` key is used to indicate which subdirectories should be considered packages/workspaces within the monorepo. It's conventional to place all the workspace in a directory called `packages`.
 
-```json
+```json package.json icon="file-json"
 {
   "name": "my-project",
   "version": "1.0.0",
@@ -42,14 +42,22 @@ In the root `package.json`, the `"workspaces"` key is used to indicate which sub
 ```
 
 <Note>
-  **Glob support** — Bun supports full glob syntax in `"workspaces"` (see [here](/runtime/glob#supported-glob-patterns)
-  for a comprehensive list of supported syntax), _except_ for exclusions (e.g. `!**/excluded/**`), which are not
-  implemented yet.
+  **Glob support** — Bun supports full glob syntax in `"workspaces"`, including negative patterns (e.g.
+  `!**/excluded/**`). See [here](https://bun.com/docs/api/glob#supported-glob-patterns) for a comprehensive list of
+  supported syntax.
 </Note>
 
+```json package.json icon="file-json"
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "workspaces": ["packages/**", "!packages/**/test/**", "!packages/**/template/**"]
+}
+```
+
 Each workspace has it's own `package.json`. When referencing other packages in the monorepo, semver or workspace protocols (e.g. `workspace:*`) can be used as the version field in your `package.json`.
 
-```json
+```json packages/pkg-a/package.json icon="file-json"
 {
   "name": "pkg-a",
   "version": "1.0.0",

package/docs/project/contributing.mdx

@@ -7,26 +7,40 @@ Configuring a development environment for Bun can take 10-30 minutes depending o
 
 If you are using Windows, please refer to [this guide](/project/building-windows)
 
-## Install Dependencies
+## Using Nix (Alternative)
+
+A Nix flake is provided as an alternative to manual dependency installation:
+
+```bash
+nix develop
+# or explicitly use the pure shell
+# nix develop .#pure
+export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
+bun bd
+```
+
+This provides all dependencies in an isolated, reproducible environment without requiring sudo.
+
+## Install Dependencies (Manual)
 
 Using your system's package manager, install Bun's dependencies:
 
 <CodeGroup>
 
 ```bash macOS (Homebrew)
-$ brew install automake ccache cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby
+$ brew install automake cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby sccache
 ```
 
 ```bash Ubuntu/Debian
-$ sudo apt install curl wget lsb-release software-properties-common cargo ccache cmake git golang libtool ninja-build pkg-config rustc ruby-full xz-utils
+$ sudo apt install curl wget lsb-release software-properties-common cargo cmake git golang libtool ninja-build pkg-config rustc ruby-full xz-utils
 ```
 
 ```bash Arch
-$ sudo pacman -S base-devel ccache cmake git go libiconv libtool make ninja pkg-config python rust sed unzip ruby
+$ sudo pacman -S base-devel cmake git go libiconv libtool make ninja pkg-config python rust sed unzip ruby
 ```
 
 ```bash Fedora
-$ sudo dnf install cargo ccache cmake git golang libtool ninja-build pkg-config rustc ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'
+$ sudo dnf install cargo clang19 llvm19 lld19 cmake git golang libtool ninja-build pkg-config rustc ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'
 ```
 
 ```bash openSUSE Tumbleweed
@@ -56,6 +70,46 @@ $ brew install bun
 
 </CodeGroup>
 
+### Optional: Install `sccache`
+
+sccache is used to cache compilation artifacts, significantly speeding up builds. It must be installed with S3 support:
+
+```bash
+# For macOS
+$ brew install sccache
+
+# For Linux. Note that the version in your package manager may not have S3 support.
+$ cargo install sccache --features=s3
+```
+
+This will install `sccache` with S3 support. Our build scripts will automatically detect and use `sccache` with our shared S3 cache. **Note**: Not all versions of `sccache` are compiled with S3 support, hence we recommend installing it via `cargo`.
+
+#### Registering AWS Credentials for `sccache` (Core Developers Only)
+
+Core developers have write access to the shared S3 cache. To enable write access, you must log in with AWS credentials. The easiest way to do this is to use the [`aws` CLI](https://aws.amazon.com/cli/) and invoke [`aws configure` to provide your AWS security info](https://docs.aws.amazon.com/cli/latest/reference/configure/).
+
+The `cmake` scripts should automatically detect your AWS credentials from the environment or the `~/.aws/credentials` file.
+
+<details>
+    <summary>Logging in to the `aws` CLI</summary>
+
+    1. Install the AWS CLI by following [the official guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+    2. Log in to your AWS account console. A team member should provide you with your credentials.
+    3. Click your name in the top right > Security credentials.
+    4. Scroll to "Access keys" and create a new access key.
+    5. Run `aws configure` in your terminal and provide the access key ID and secret access key when prompted.
+
+</details>
+
+<details>
+    <summary>Common Issues You May Encounter</summary>
+
+    - To confirm that the cache is being used, you can use the `sccache --show-stats` command right after a build. This will expose very useful statistics, including cache hits/misses.
+    - If you have multiple AWS profiles configured, ensure that the correct profile is set in the `AWS_PROFILE` environment variable.
+    - `sccache` follows a server-client model. If you run into weird issues where `sccache` refuses to use S3, even though you have AWS credentials configured, try killing any running `sccache` servers with `sccache --stop-server` and then re-running the build.
+
+</details>
+
 ## Install LLVM
 
 Bun requires LLVM 19 (`clang` is part of LLVM). This version requirement is to match WebKit (precompiled), as mismatching versions will cause memory allocation failures at runtime. In most cases, you can install LLVM through your system package manager:
@@ -156,7 +210,7 @@ Bun generally takes about 2.5 minutes to compile a debug build when there are Zi
 - Batch up your changes
 - Ensure zls is running with incremental watching for LSP errors (if you use VSCode and install Zig and run `bun run build` once to download Zig, this should just work)
 - Prefer using the debugger ("CodeLLDB" in VSCode) to step through the code.
-- Use debug logs. `BUN_DEBUG_<scope>=1` will enable debug logging for the corresponding `Output.scoped(.<scope>, false)` logs. You can also set `BUN_DEBUG_QUIET_LOGS=1` to disable all debug logging that isn't explicitly enabled. To dump debug lgos into a file, `BUN_DEBUG=<path-to-file>.log`. Debug logs are aggressively removed in release builds.
+- Use debug logs. `BUN_DEBUG_<scope>=1` will enable debug logging for the corresponding `Output.scoped(.<scope>, .hidden)` logs. You can also set `BUN_DEBUG_QUIET_LOGS=1` to disable all debug logging that isn't explicitly enabled. To dump debug logs into a file, `BUN_DEBUG=<path-to-file>.log`. Debug logs are aggressively removed in release builds.
 - src/js/\*\*.ts changes are pretty much instant to rebuild. C++ changes are a bit slower, but still much faster than the Zig code (Zig is one compilation unit, C++ is many).
 
 ## Code generation scripts
@@ -327,15 +381,6 @@ bun run build -DUSE_STATIC_LIBATOMIC=OFF
 
 The built version of Bun may not work on other systems if compiled this way.
 
-### ccache conflicts with building TinyCC on macOS
-
-If you run into issues with `ccache` when building TinyCC, try reinstalling ccache
-
-```bash
-brew uninstall ccache
-brew install ccache
-```
-
 ## Using bun-debug
 
 - Disable logging: `BUN_DEBUG_QUIET_LOGS=1 bun-debug ...` (to disable all debug logging)

package/docs/quickstart.mdx

@@ -219,16 +219,21 @@ Build a minimal HTTP server with `Bun.serve`, run it locally, then evolve it by
 
 Bun can also execute `"scripts"` from your `package.json`. Add the following script:
 
+{/* prettier-ignore */}
 ```json package.json icon="file-code"
 {
   "name": "quickstart",
   "module": "index.ts",
   "type": "module",
-  "scripts": {
-    "start": "bun run index.ts"
-  },
+  "private": true,
+  "scripts": { // [!code ++]
+    "start": "bun run index.ts" // [!code ++]
+  }, // [!code ++]
   "devDependencies": {
     "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
   }
 }
 ```

package/docs/runtime/bunfig.mdx

@@ -276,6 +276,58 @@ This is useful for catching flaky tests or non-deterministic behavior. Each test
 
 The `--rerun-each` CLI flag will override this setting when specified.
 
+### `test.concurrentTestGlob`
+
+Specify a glob pattern to automatically run matching test files with concurrent test execution enabled. Test files matching this pattern will behave as if the `--concurrent` flag was passed, running all tests within those files concurrently.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+concurrentTestGlob = "**/concurrent-*.test.ts"
+```
+
+This is useful for:
+
+- Gradually migrating test suites to concurrent execution
+- Running integration tests concurrently while keeping unit tests sequential
+- Separating fast concurrent tests from tests that require sequential execution
+
+The `--concurrent` CLI flag will override this setting when specified.
+
+### `test.onlyFailures`
+
+When enabled, only failed tests are displayed in the output. This helps reduce noise in large test suites by hiding passing tests. Default `false`.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+onlyFailures = true
+```
+
+This is equivalent to using the `--only-failures` flag when running `bun test`.
+
+### `test.reporter`
+
+Configure the test reporter settings.
+
+#### `test.reporter.dots`
+
+Enable the dots reporter, which displays a compact output showing a dot for each test. Default `false`.
+
+```toml title="bunfig.toml" icon="settings"
+[test.reporter]
+dots = true
+```
+
+#### `test.reporter.junit`
+
+Enable JUnit XML reporting and specify the output file path.
+
+```toml title="bunfig.toml" icon="settings"
+[test.reporter]
+junit = "test-results.xml"
+```
+
+This generates a JUnit XML report that can be consumed by CI systems and other tools.
+
 ## Package manager
 
 Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured under the `[install]` section.
@@ -551,7 +603,7 @@ For more details see [Minimum release age](/pm/cli/install#minimum-release-age)
 
 The `bun run` command can be configured under the `[run]` section. These apply to the `bun run` command and the `bun` command when running a file or executable or script.
 
-Currently, `bunfig.toml` isn't always automatically loaded for `bun run` in a local project (it does check for a global `bunfig.toml`), so you might still need to pass `-c` or `-c=bunfig.toml` to use these settings.
+Currently, `bunfig.toml` is only automatically loaded for `bun run` in a local project (it doesn't check for a global `.bunfig.toml`).
 
 ### `run.shell` - use the system shell or Bun's shell
 

package/docs/runtime/html-rewriter.mdx

@@ -46,29 +46,22 @@ console.log(result);
 
 This replaces all images with a thumbnail of Rick Astley and wraps each `<img>` in a link, producing a diff like this:
 
+{/* prettier-ignore */}
 ```html
 <html>
   <body>
-    <img src="/cat.jpg" /> // [!code --] <img src="dog.png" /> // [!code --]
-    <img src="https://example.com/bird.webp" /> // [!code --]
-    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
-      // [!code ++]
-      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
-      // [!code ++]
-    </a>
-    // [!code ++]
-    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
-      // [!code ++]
-      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
-      // [!code ++]
-    </a>
-    // [!code ++]
-    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
-      // [!code ++]
-      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
-      // [!code ++]
-    </a>
-    // [!code ++]
+    <img src="/cat.jpg" /> <!-- [!code --] -->
+    <img src="dog.png" /> <!-- [!code --] -->
+    <img src="https://example.com/bird.webp" /> <!-- [!code --] -->
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> <!-- [!code ++] -->
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" /> <!-- [!code ++] -->
+    </a> <!-- [!code ++] -->
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> <!-- [!code ++] -->
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" /> <!-- [!code ++] -->
+    </a> <!-- [!code ++] -->
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank"> <!-- [!code ++] -->
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" /> <!-- [!code ++] -->
+    </a> <!-- [!code ++] -->
   </body>
 </html>
 ```

package/docs/runtime/http/routing.mdx

@@ -283,7 +283,7 @@ You can also access the `Server` object from the `fetch` handler. It's the secon
 const server = Bun.serve({
   fetch(req, server) {
     const ip = server.requestIP(req);
-    return new Response(`Your IP is ${ip}`);
+    return new Response(`Your IP is ${ip.address}`);
   },
 });
 ```

package/docs/runtime/http/websockets.mdx

@@ -107,13 +107,13 @@ Bun.serve({
 
 Once the upgrade succeeds, Bun will send a `101 Switching Protocols` response per the [spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism). Additional `headers` can be attached to this `Response` in the call to `server.upgrade()`.
 
+{/* prettier-ignore */}
 ```ts server.ts icon="/icons/typescript.svg"
 Bun.serve({
   fetch(req, server) {
     const sessionId = await generateSessionId();
     server.upgrade(req, {
-      headers: {
-        // [!code ++]
+      headers: { // [!code ++]
         "Set-Cookie": `SessionId=${sessionId}`, // [!code ++]
       }, // [!code ++]
     });
@@ -126,6 +126,8 @@ Bun.serve({
 
 Contextual `data` can be attached to a new WebSocket in the `.upgrade()` call. This data is made available on the `ws.data` property inside the WebSocket handlers.
 
+To strongly type `ws.data`, add a `data` property to the `websocket` handler object. This types `ws.data` across all lifecycle hooks.
+
 ```ts server.ts icon="/icons/typescript.svg"
 type WebSocketData = {
   createdAt: number;
@@ -166,6 +168,10 @@ Bun.serve({
 });
 ```
 
+<Info>
+**Note:** Previously, you could specify the type of `ws.data` using a type parameter on `Bun.serve`, like `Bun.serve<MyData>({...})`. This pattern was removed due to [a limitation in TypeScript](https://github.com/microsoft/TypeScript/issues/26242) in favor of the `data` property shown above.
+</Info>
+
 To connect to this server from the browser, create a new `WebSocket`.
 
 ```ts browser.js icon="file-code"

package/docs/runtime/module-resolution.mdx

@@ -183,6 +183,29 @@ import { stuff } from "foo";
 
 The full specification of this algorithm are officially documented in the [Node.js documentation](https://nodejs.org/api/modules.html); we won't rehash it here. Briefly: if you import `from "foo"`, Bun scans up the file system for a `node_modules` directory containing the package `foo`.
 
+### NODE_PATH
+
+Bun supports `NODE_PATH` for additional module resolution directories:
+
+```bash
+NODE_PATH=./packages bun run src/index.js
+```
+
+```ts
+// packages/foo/index.js
+export const hello = "world";
+
+// src/index.js
+import { hello } from "foo";
+```
+
+Multiple paths use the platform's delimiter (`:` on Unix, `;` on Windows):
+
+```bash
+NODE_PATH=./packages:./lib bun run src/index.js  # Unix/macOS
+NODE_PATH=./packages;./lib bun run src/index.js  # Windows
+```
+
 Once it finds the `foo` package, Bun reads the `package.json` to determine how the package should be imported. To determine the package's entrypoint, Bun first reads the `exports` field and checks for the following conditions.
 
 ```json package.json icon="file-json"

package/docs/runtime/redis.mdx

@@ -51,6 +51,7 @@ await client.incr("counter");
 By default, the client reads connection information from the following environment variables (in order of precedence):
 
 - `REDIS_URL`
+- `VALKEY_URL`
 - If not set, defaults to `"redis://localhost:6379"`
 
 ### Connection Lifecycle

package/docs/runtime/utils.mdx

@@ -234,8 +234,8 @@ Bun.openInEditor(currentFile);
 You can override this via the `debug.editor` setting in your [`bunfig.toml`](/runtime/bunfig).
 
 ```toml bunfig.toml
-[debug] // [!code ++]
-editor = "code" // [!code ++]
+[debug] # [!code ++]
+editor = "code" # [!code ++]
 ```
 
 Or specify an editor with the `editor` param. You can also specify a line and column number.

package/docs/test/configuration.mdx

@@ -184,6 +184,53 @@ This is useful for:
 - Large test suites that consume significant memory
 - Development environments with memory constraints
 
+## Test execution
+
+### concurrentTestGlob
+
+Automatically run test files matching a glob pattern with concurrent test execution enabled. This is useful for gradually migrating test suites to concurrent execution or for running specific test types concurrently.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+concurrentTestGlob = "**/concurrent-*.test.ts"  # Run files matching this pattern concurrently
+```
+
+Test files matching this pattern will behave as if the `--concurrent` flag was passed, running all tests within those files concurrently. This allows you to:
+
+- Gradually migrate your test suite to concurrent execution
+- Run integration tests concurrently while keeping unit tests sequential
+- Separate fast concurrent tests from tests that require sequential execution
+
+The `--concurrent` CLI flag will override this setting when specified, forcing all tests to run concurrently regardless of the glob pattern.
+
+#### randomize
+
+Run tests in random order to identify tests with hidden dependencies:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+randomize = true
+```
+
+#### seed
+
+Specify a seed for reproducible random test order. Requires `randomize = true`:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+randomize = true
+seed = 2444615283
+```
+
+#### rerunEach
+
+Re-run each test file multiple times to identify flaky tests:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+rerunEach = 3
+```
+
 ## Coverage Options
 
 ### Basic Coverage Settings

package/docs/test/reporters.mdx

@@ -41,6 +41,15 @@ test/package-json-lint.test.ts:
 Ran 4 tests across 1 files. [0.66ms]
 ```
 
+### Dots Reporter
+
+The dots reporter shows `.` for passing tests and `F` for failures—useful for large test suites.
+
+```sh terminal icon="terminal"
+bun test --dots
+bun test --reporter=dots
+```
+
 ### JUnit XML Reporter
 
 For CI/CD environments, Bun supports generating JUnit XML reports. JUnit XML is a widely-adopted format for test results that can be parsed by many CI/CD systems, including GitLab, Jenkins, and others.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.3-canary.20251114T140703",
+  "version": "1.3.3-canary.20251116T140533",
   "name": "bun-types",
   "license": "MIT",
   "types": "./index.d.ts",