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

package/docs/guides/html-rewriter/extract-links.mdx

@@ -37,6 +37,7 @@ await extractLinks("https://bun.com");
 
 When scraping websites, you often want to convert relative URLs (like `/docs`) to absolute URLs. Here's how to handle URL resolution:
 
+{/* prettier-ignore */}
 ```ts extract-links.ts icon="/icons/typescript.svg"
 async function extractLinksFromURL(url: string) {
   const response = await fetch(url);
@@ -47,13 +48,11 @@ async function extractLinksFromURL(url: string) {
       const href = el.getAttribute("href");
       if (href) {
         // Convert relative URLs to absolute // [!code ++]
-        try {
-          // [!code ++]
+        try { // [!code ++]
           const absoluteURL = new URL(href, url).href; // [!code ++]
-          links.add(absoluteURL); // [!code ++]
-        } catch {
-          // [!code ++]
-          links.add(href);
+          links.add(absoluteURL);
+        } catch { // [!code ++]
+          links.add(href); // [!code ++]
         } // [!code ++]
       }
     },

package/docs/guides/http/file-uploads.mdx

@@ -65,6 +65,7 @@ First we use the [`.formData()`](https://developer.mozilla.org/en-US/docs/Web/AP
 
 Finally, we write the `Blob` to disk using [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).
 
+{/* prettier-ignore */}
 ```ts index.ts icon="/icons/typescript.svg"
 const server = Bun.serve({
   port: 4000,
@@ -80,8 +81,7 @@ const server = Bun.serve({
       });
 
     // parse formdata at /action // [!code ++]
-    if (url.pathname === "/action") {
-      // [!code ++]
+    if (url.pathname === "/action") { // [!code ++]
       const formdata = await req.formData(); // [!code ++]
       const name = formdata.get("name"); // [!code ++]
       const profilePicture = formdata.get("profilePicture"); // [!code ++]

package/docs/guides/install/add-peer.mdx

@@ -26,14 +26,14 @@ This will add the package to `peerDependencies` in `package.json`.
 
 Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
 
+{/* prettier-ignore */}
 ```json package.json icon="file-json"
 {
   "peerDependencies": {
     "@types/bun": "^1.3.2"
   },
   "peerDependenciesMeta": {
-    "@types/bun": {
-      // [!code ++]
+    "@types/bun": { // [!code ++]
       "optional": true // [!code ++]
     } // [!code ++]
   }

package/docs/guides/read-file/watch.mdx

@@ -23,8 +23,8 @@ To listen to changes in subdirectories, pass the `recursive: true` option to `fs
 ```ts
 import { watch } from "fs";
 
-const watcher = watch(import.meta.dir, { recursive: true }, (event, filename) => {
-  console.log(`Detected ${event} in ${filename}`);
+const watcher = watch(import.meta.dir, { recursive: true }, (event, relativePath) => {
+  console.log(`Detected ${event} in ${relativePath}`);
 });
 ```
 

package/docs/guides/runtime/cicd.mdx

@@ -15,12 +15,12 @@ jobs:
     steps:
       # ...
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2 // [!code ++]
+      - uses: oven-sh/setup-bun@v2 # [!code ++]
 
       # run any `bun` or `bunx` command
-      - run: bun install // [!code ++]
-      - run: bun index.ts // [!code ++]
-      - run: bun run build // [!code ++]
+      - run: bun install # [!code ++]
+      - run: bun index.ts # [!code ++]
+      - run: bun run build # [!code ++]
 ```
 
 ---
@@ -36,8 +36,8 @@ jobs:
     steps:
       # ...
       - uses: oven-sh/setup-bun@v2
-        with: // [!code ++]
-          bun-version: 1.2.0 # or "latest", "canary", <sha> // [!code ++]
+        with: # [!code ++]
+          bun-version: 1.2.0 # or "latest", "canary", <sha> # [!code ++]
 ```
 
 ---

package/docs/guides/runtime/define-constant.mdx

@@ -27,9 +27,9 @@ if (process.env.NODE_ENV === "production") {
 
 Before the code reaches the JavaScript engine, Bun replaces `process.env.NODE_ENV` with `"production"`.
 
+{/* prettier-ignore */}
 ```ts
-if ("production" === "production") {
-  // [!code ++]
+if ("production" === "production") { // [!code ++]
   console.log("Production mode");
 } else {
   console.log("Development mode");
@@ -42,9 +42,9 @@ It doesn't stop there. Bun's optimizing transpiler is smart enough to do some ba
 
 Since `"production" === "production"` is always `true`, Bun replaces the entire expression with the `true` value.
 
+{/* prettier-ignore */}
 ```ts
-if (true) {
-  // [!code ++]
+if (true) { // [!code ++]
   console.log("Production mode");
 } else {
   console.log("Development mode");

package/docs/guides/test/concurrent-test-glob.mdx

@@ -0,0 +1,143 @@
+---
+title: Selectively run tests concurrently with glob patterns
+sidebarTitle: Concurrent test glob
+mode: center
+---
+
+This guide demonstrates how to use the `concurrentTestGlob` option to selectively run tests concurrently based on file naming patterns.
+
+## Project Structure
+
+```sh title="Project Structure" icon="folder-tree"
+my-project/
+├── bunfig.toml
+├── tests/
+│   ├── unit/
+│   │   ├── math.test.ts          # Sequential
+│   │   └── utils.test.ts         # Sequential
+│   └── integration/
+│       ├── concurrent-api.test.ts     # Concurrent
+│       └── concurrent-database.test.ts # Concurrent
+```
+
+## Configuration
+
+Configure your `bunfig.toml` to run test files with "concurrent-" prefix concurrently:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Run all test files with "concurrent-" prefix concurrently
+concurrentTestGlob = "**/concurrent-*.test.ts"
+```
+
+## Test Files
+
+### Unit Test (Sequential)
+
+Sequential tests are good for tests that share state or have specific ordering requirements:
+
+```ts title="tests/unit/math.test.ts" icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+// These tests run sequentially by default
+let sharedState = 0;
+
+test("addition", () => {
+  sharedState = 5 + 3;
+  expect(sharedState).toBe(8);
+});
+
+test("uses previous state", () => {
+  // This test depends on the previous test's state
+  expect(sharedState).toBe(8);
+});
+```
+
+### Integration Test (Concurrent)
+
+Tests in files matching the glob pattern automatically run concurrently:
+
+```ts title="tests/integration/concurrent-api.test.ts" icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+// These tests automatically run concurrently due to filename matching the glob pattern.
+// Using test() is equivalent to test.concurrent() when the file matches concurrentTestGlob.
+// Each test is independent and can run in parallel.
+
+test("fetch user data", async () => {
+  const response = await fetch("/api/user/1");
+  expect(response.ok).toBe(true);
+});
+
+test("fetch posts", async () => {
+  const response = await fetch("/api/posts");
+  expect(response.ok).toBe(true);
+});
+
+test("fetch comments", async () => {
+  const response = await fetch("/api/comments");
+  expect(response.ok).toBe(true);
+});
+```
+
+## Running Tests
+
+```bash terminal icon="terminal"
+# Run all tests - concurrent-*.test.ts files will run concurrently
+bun test
+
+# Override: Force ALL tests to run concurrently
+# Note: This overrides bunfig.toml and runs all tests concurrently, regardless of glob
+bun test --concurrent
+
+# Run only unit tests (sequential)
+bun test tests/unit
+
+# Run only integration tests (concurrent due to glob pattern)
+bun test tests/integration
+```
+
+## Benefits
+
+1. **Gradual Migration**: Migrate to concurrent tests file by file by renaming them
+2. **Clear Organization**: File naming convention indicates execution mode
+3. **Performance**: Integration tests run faster in parallel
+4. **Safety**: Unit tests remain sequential where needed
+5. **Flexibility**: Easy to change execution mode by renaming files
+
+## Migration Strategy
+
+To migrate existing tests to concurrent execution:
+
+1. **Start with independent integration tests** - These typically don't share state
+2. **Rename files to match the glob pattern**: `mv api.test.ts concurrent-api.test.ts`
+3. **Verify tests still pass** - Run `bun test` to ensure no race conditions
+4. **Monitor for shared state issues** - Watch for flaky tests or unexpected failures
+5. **Continue migrating stable tests incrementally** - Don't rush the migration
+
+## Tips
+
+- **Use descriptive prefixes**: `concurrent-`, `parallel-`, `async-`
+- **Keep related sequential tests together** in the same directory
+- **Document why certain tests must remain sequential** with comments
+- **Use `test.concurrent()` for fine-grained control** in sequential files
+  (Note: In files matched by `concurrentTestGlob`, plain `test()` already runs concurrently)
+
+## Multiple Patterns
+
+You can specify multiple patterns for different test categories:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+concurrentTestGlob = [
+  "**/integration/*.test.ts",
+  "**/e2e/*.test.ts",
+  "**/concurrent-*.test.ts"
+]
+```
+
+This configuration will run tests concurrently if they match any of these patterns:
+
+- All tests in `integration/` directories
+- All tests in `e2e/` directories
+- All tests with `concurrent-` prefix anywhere in the project

package/docs/guides/test/spy-on.mdx

@@ -23,6 +23,7 @@ const spy = spyOn(leo, "sayHi");
 
 Once the spy is created, it can be used to write `expect` assertions relating to method calls.
 
+{/* prettier-ignore */}
 ```ts
 import { test, expect, spyOn } from "bun:test";
 
@@ -35,8 +36,7 @@ const leo = {
 
 const spy = spyOn(leo, "sayHi");
 
-test("turtles", () => {
-  // [!code ++]
+test("turtles", () => { // [!code ++]
   expect(spy).toHaveBeenCalledTimes(0); // [!code ++]
   leo.sayHi("pizza"); // [!code ++]
   expect(spy).toHaveBeenCalledTimes(1); // [!code ++]

package/docs/guides/websocket/context.mdx

@@ -9,7 +9,7 @@ When building a WebSocket server, it's typically necessary to store some identif
 With [Bun.serve()](https://bun.com/docs/api/websockets contextual-data), this "contextual data" is set when the connection is initially upgraded by passing a `data` parameter in the `server.upgrade()` call.
 
 ```ts server.ts icon="/icons/typescript.svg"
-Bun.serve<{ socketId: number }>({
+Bun.serve({
   fetch(req, server) {
     const success = server.upgrade(req, {
       data: {
@@ -22,6 +22,9 @@ Bun.serve<{ socketId: number }>({
     // ...
   },
   websocket: {
+    // TypeScript: specify the type of ws.data like this
+    data: {} as { socketId: number },
+
     // define websocket handlers
     async message(ws, message) {
       // the contextual data is available as the `data` property
@@ -43,8 +46,7 @@ type WebSocketData = {
   userId: string;
 };
 
-// TypeScript: specify the type of `data`
-Bun.serve<WebSocketData>({
+Bun.serve({
   async fetch(req, server) {
     // use a library to parse cookies
     const cookies = parseCookies(req.headers.get("Cookie"));
@@ -62,6 +64,9 @@ Bun.serve<WebSocketData>({
     if (upgraded) return undefined;
   },
   websocket: {
+    // TypeScript: specify the type of ws.data like this
+    data: {} as WebSocketData,
+
     async message(ws, message) {
       // save the message to a database
       await saveMessageToDatabase({

package/docs/guides/websocket/pubsub.mdx

@@ -9,7 +9,7 @@ Bun's server-side `WebSocket` API provides a native pub-sub API. Sockets can be
 This code snippet implements a simple single-channel chat server.
 
 ```ts server.ts icon="/icons/typescript.svg"
-const server = Bun.serve<{ username: string }>({
+const server = Bun.serve({
   fetch(req, server) {
     const cookies = req.headers.get("cookie");
     const username = getUsernameFromCookies(cookies);
@@ -19,6 +19,9 @@ const server = Bun.serve<{ username: string }>({
     return new Response("Hello world");
   },
   websocket: {
+    // TypeScript: specify the type of ws.data like this
+    data: {} as { username: string },
+
     open(ws) {
       const msg = `${ws.data.username} has entered the chat`;
       ws.subscribe("the-group-chat");

package/docs/guides/websocket/simple.mdx

@@ -9,7 +9,7 @@ Start a simple WebSocket server using [`Bun.serve`](https://bun.com/docs/api/htt
 Inside `fetch`, we attempt to upgrade incoming `ws:` or `wss:` requests to WebSocket connections.
 
 ```ts server.ts icon="/icons/typescript.svg"
-const server = Bun.serve<{ authToken: string }>({
+const server = Bun.serve({
   fetch(req, server) {
     const success = server.upgrade(req);
     if (success) {
@@ -22,6 +22,9 @@ const server = Bun.serve<{ authToken: string }>({
     return new Response("Hello world!");
   },
   websocket: {
+    // TypeScript: specify the type of ws.data like this
+    data: {} as { authToken: string },
+
     // this is called when a message is received
     async message(ws, message) {
       console.log(`Received ${message}`);

package/docs/pm/cli/info.mdx

@@ -0,0 +1,70 @@
+---
+title: "bun info"
+description: "Display package metadata from the npm registry"
+---
+
+`bun info` displays package metadata from the npm registry.
+
+## Usage
+
+```bash terminal icon="terminal"
+bun info react
+```
+
+This will display information about the `react` package, including its latest version, description, homepage, dependencies, and more.
+
+## Viewing specific versions
+
+To view information about a specific version:
+
+```bash terminal icon="terminal"
+bun info react@18.0.0
+```
+
+## Viewing specific properties
+
+You can also query specific properties from the package metadata:
+
+```bash terminal icon="terminal"
+bun info react version
+bun info react dependencies
+bun info react repository.url
+```
+
+## JSON output
+
+To get the output in JSON format, use the `--json` flag:
+
+```bash terminal icon="terminal"
+bun info react --json
+```
+
+## Alias
+
+`bun pm view` is an alias for `bun info`:
+
+```bash terminal icon="terminal"
+bun pm view react  # equivalent to: bun info react
+```
+
+## Examples
+
+```bash terminal icon="terminal"
+# View basic package information
+bun info is-number
+
+# View a specific version
+bun info is-number@7.0.0
+
+# View all available versions
+bun info is-number versions
+
+# View package dependencies
+bun info express dependencies
+
+# View package homepage
+bun info lodash homepage
+
+# Get JSON output
+bun info react --json
+```

package/docs/pm/cli/install.mdx

@@ -134,14 +134,14 @@ For more information on filtering with `bun install`, refer to [Package Manager
 
 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. Refer to [Package manager > Overrides and resolutions](/pm/overrides) for complete documentation.
 
+{/* prettier-ignore */}
 ```json package.json file="file-json"
 {
   "name": "my-app",
   "dependencies": {
     "foo": "^2.0.0"
   },
-  "overrides": {
-    // [!code ++]
+  "overrides": { // [!code ++]
     "bar": "~4.4.0" // [!code ++]
   } // [!code ++]
 }
@@ -304,7 +304,16 @@ For more advanced security scanning, including integration with services & custo
 
 ## Configuration
 
-The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
+### Configuring `bun install` with `bunfig.toml`
+
+`bunfig.toml` is searched for in the following paths on `bun install`, `bun remove`, and `bun add`:
+
+1. `$XDG_CONFIG_HOME/.bunfig.toml` or `$HOME/.bunfig.toml`
+2. `./bunfig.toml`
+
+If both are found, the results are merged together.
+
+Configuring with `bunfig.toml` is optional. Bun tries to be zero configuration in general, but that's not always possible. The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
 
 ```toml bunfig.toml icon="settings"
 [install]
@@ -345,7 +354,29 @@ minimumReleaseAge = 259200 # seconds
 minimumReleaseAgeExcludes = ["@types/node", "typescript"]
 ```
 
----
+### Configuring with environment variables
+
+Environment variables have a higher priority than `bunfig.toml`.
+
+| Name                               | Description                                                   |
+| ---------------------------------- | ------------------------------------------------------------- |
+| `BUN_CONFIG_REGISTRY`              | Set an npm registry (default: https://registry.npmjs.org)     |
+| `BUN_CONFIG_TOKEN`                 | Set an auth token (currently does nothing)                    |
+| `BUN_CONFIG_YARN_LOCKFILE`         | Save a Yarn v1-style yarn.lock                                |
+| `BUN_CONFIG_LINK_NATIVE_BINS`      | Point `bin` in package.json to a platform-specific dependency |
+| `BUN_CONFIG_SKIP_SAVE_LOCKFILE`    | Don’t save a lockfile                                         |
+| `BUN_CONFIG_SKIP_LOAD_LOCKFILE`    | Don’t load a lockfile                                         |
+| `BUN_CONFIG_SKIP_INSTALL_PACKAGES` | Don’t install any packages                                    |
+
+Bun always tries to use the fastest available installation method for the target platform. On macOS, that’s `clonefile` and on Linux, that’s `hardlink`. You can change which installation method is used with the `--backend` flag. When unavailable or on error, `clonefile` and `hardlink` fallsback to a platform-specific implementation of copying files.
+
+Bun stores installed packages from npm in `~/.bun/install/cache/${name}@${version}`. Note that if the semver version has a `build` or a `pre` tag, it is replaced with a hash of that value instead. This is to reduce the chances of errors from long file paths, but unfortunately complicates figuring out where a package was installed on disk.
+
+When the `node_modules` folder exists, before installing, Bun checks if the `"name"` and `"version"` in `package/package.json` in the expected node_modules folder matches the expected `name` and `version`. This is how it determines whether it should install. It uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`.
+
+When a `bun.lock` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving.
+
+When a `bun.lock` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball.
 
 ## CI/CD
 
@@ -395,6 +426,94 @@ jobs:
         run: bun run build
 ```
 
+## Platform-specific dependencies?
+
+bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won't change between platforms/architectures even if the packages ultimately installed do change.
+
+### `--cpu` and `--os` flags
+
+You can override the target platform for package selection:
+
+```bash
+bun install --cpu=x64 --os=linux
+```
+
+This installs packages for the specified platform instead of the current system. Useful for cross-platform builds or when preparing deployments for different environments.
+
+**Accepted values for `--cpu`**: `arm64`, `x64`, `ia32`, `ppc64`, `s390x`
+
+**Accepted values for `--os`**: `linux`, `darwin`, `win32`, `freebsd`, `openbsd`, `sunos`, `aix`
+
+## Peer dependencies?
+
+Peer dependencies are handled similarly to yarn. `bun install` will automatically install peer dependencies. If the dependency is marked optional in `peerDependenciesMeta`, an existing dependency will be chosen if possible.
+
+## Lockfile
+
+`bun.lock` is Bun’s lockfile format. See [our blogpost about the text lockfile](https://bun.com/blog/bun-lock-text-lockfile).
+
+Prior to Bun 1.2, the lockfile was binary and called `bun.lockb`. Old lockfiles can be upgraded to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only`, and then deleting `bun.lockb`.
+
+## Cache
+
+To delete the cache:
+
+```bash
+bun pm cache rm
+# or
+rm -rf ~/.bun/install/cache
+```
+
+## Platform-specific backends
+
+`bun install` uses different system calls to install dependencies depending on the platform. This is a performance optimization. You can force a specific backend with the `--backend` flag.
+
+**`hardlink`** is the default backend on Linux. Benchmarking showed it to be the fastest on Linux.
+
+```bash
+rm -rf node_modules
+bun install --backend hardlink
+```
+
+**`clonefile`** is the default backend on macOS. Benchmarking showed it to be the fastest on macOS. It is only available on macOS.
+
+```bash
+rm -rf node_modules
+bun install --backend clonefile
+```
+
+**`clonefile_each_dir`** is similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`. Unlike `clonefile`, this does not recursively clone subdirectories in one system call.
+
+```bash
+rm -rf node_modules
+bun install --backend clonefile_each_dir
+```
+
+**`copyfile`** is the fallback used when any of the above fail, and is the slowest. on macOS, it uses `fcopyfile()` and on linux it uses `copy_file_range()`.
+
+```bash
+rm -rf node_modules
+bun install --backend copyfile
+```
+
+**`symlink`** is typically only used for `file:` dependencies (and eventually `link:`) internally. To prevent infinite loops, it skips symlinking the `node_modules` folder.
+
+If you install with `--backend=symlink`, Node.js won't resolve node_modules of dependencies unless each dependency has its own node_modules folder or you pass `--preserve-symlinks` to `node` or `bun`. See [Node.js documentation on `--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks).
+
+```bash
+rm -rf node_modules
+bun install --backend symlink
+bun --preserve-symlinks ./my-file.js
+node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks
+```
+
+## npm registry metadata
+
+Bun uses a binary format for caching NPM registry responses. This loads much faster than JSON and tends to be smaller on disk.
+You will see these files in `~/.bun/install/cache/*.npm`. The filename pattern is `${hash(packageName)}.npm`. It’s a hash so that extra directories don’t need to be created for scoped packages.
+
+Bun's usage of `Cache-Control` ignores `Age`. This improves performance, but means bun may be about 5 minutes out of date to receive the latest package version metadata from npm.
+
 ## pnpm migration
 
 Bun automatically migrates projects from pnpm to bun. When a `pnpm-lock.yaml` file is detected and no `bun.lock` file exists, Bun will automatically migrate the lockfile to `bun.lock` during installation. The original `pnpm-lock.yaml` file remains unmodified.

package/docs/pm/cli/link.mdx

@@ -43,6 +43,19 @@ In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencie
 }
 ```
 
+## Unlinking
+
+Use `bun unlink` in the root directory to unregister a local package.
+
+```bash terminal icon="terminal"
+cd /path/to/cool-pkg
+bun unlink
+```
+
+```txt
+bun unlink v1.x (7416672e)
+```
+
 ---
 
 <Link />

package/docs/pm/cli/publish.mdx

@@ -89,6 +89,14 @@ The `--dry-run` flag can be used to simulate the publish process without actuall
 bun publish --dry-run
 ```
 
+### `--tolerate-republish`
+
+Exit with code 0 instead of 1 if the package version already exists. Useful in CI/CD where jobs may be re-run.
+
+```sh terminal icon="terminal"
+bun publish --tolerate-republish
+```
+
 ### `--gzip-level`
 
 Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`).