bun-types 1.2.19 → 1.2.20-canary.20250721T140723

package/docs/api/fetch.md

@@ -337,7 +337,7 @@ This will print the request and response headers to your terminal:
 ```sh
 [fetch] > HTTP/1.1 GET http://example.com/
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.19
+[fetch] > User-Agent: Bun/1.2.20-canary.20250721T140723
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/spawn.md

@@ -140,7 +140,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
 ```ts
 const proc = Bun.spawn(["bun", "--version"]);
 const text = await proc.stdout.text();
-console.log(text); // => "1.2.19\n"
+console.log(text); // => "1.2.20-canary.20250721T140723\n"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/cli/install.md

@@ -183,6 +183,30 @@ Bun supports installing dependencies from Git, GitHub, and local or remotely-hos
 }
 ```
 
+## Installation strategies
+
+Bun supports two package installation strategies that determine how dependencies are organized in `node_modules`:
+
+### Hoisted installs (default for single projects)
+
+The traditional npm/Yarn approach that flattens dependencies into a shared `node_modules` directory:
+
+```bash
+$ bun install --linker hoisted
+```
+
+### Isolated installs
+
+A pnpm-like approach that creates strict dependency isolation to prevent phantom dependencies:
+
+```bash
+$ bun install --linker isolated
+```
+
+Isolated installs create a central package store in `node_modules/.bun/` with symlinks in the top-level `node_modules`. This ensures packages can only access their declared dependencies.
+
+For complete documentation on isolated installs, refer to [Package manager > Isolated installs](https://bun.com/docs/install/isolated).
+
 ## Configuration
 
 The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
@@ -213,11 +237,15 @@ dryRun = false
 
 # equivalent to `--concurrent-scripts` flag
 concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
+
+# installation strategy: "hoisted" or "isolated"
+# default: "hoisted"
+linker = "hoisted"
 ```
 
 ## CI/CD
 
-Looking to speed up your CI? Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline.
+Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline:
 
 ```yaml#.github/workflows/release.yml
 name: bun-types
@@ -236,4 +264,31 @@ jobs:
         run: bun run build
 ```
 
+For CI/CD environments that want to enforce reproducible builds, use `bun ci` to fail the build if the package.json is out of sync with the lockfile:
+
+```bash
+$ bun ci
+```
+
+This is equivalent to `bun install --frozen-lockfile`. It installs exact versions from `bun.lock` and fails if `package.json` doesn't match the lockfile. To use `bun ci` or `bun install --frozen-lockfile`, you must commit `bun.lock` to version control.
+
+And instead of running `bun install`, run `bun ci`.
+
+```yaml#.github/workflows/release.yml
+name: bun-types
+jobs:
+  build:
+    name: build-app
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+      - name: Install dependencies
+        run: bun ci
+      - name: Build app
+        run: bun run build
+```
+
 {% bunCLIUsage command="install" /%}

package/docs/cli/pm.md

@@ -213,7 +213,7 @@ To display current package version and help:
 
 ```bash
 $ bun pm version
-bun pm version v1.2.19 (ca7428e9)
+bun pm version v1.2.20-canary.20250721T140723 (ca7428e9)
 Current package version: v1.0.0
 
 Increment:

package/docs/cli/publish.md

@@ -7,7 +7,7 @@ Use `bun publish` to publish a package to the npm registry.
 $ bun publish
 
 ## Output
-bun publish v1.2.19 (ca7428e9)
+bun publish v1.2.20-canary.20250721T140723 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md

package/docs/cli/update.md

@@ -10,6 +10,86 @@ To update a specific dependency to the latest version:
 $ bun update [package]
 ```
 
+## `--interactive`
+
+For a more controlled update experience, use the `--interactive` flag to select which packages to update:
+
+```sh
+$ bun update --interactive
+$ bun update -i
+```
+
+This launches an interactive terminal interface that shows all outdated packages with their current and target versions. You can then select which packages to update.
+
+### Interactive Interface
+
+The interface displays packages grouped by dependency type:
+
+```
+? Select packages to update - Space to toggle, Enter to confirm, a to select all, n to select none, i to invert, l to toggle latest
+
+  dependencies                Current  Target   Latest
+    □ react                   17.0.2   18.2.0   18.3.1
+    □ lodash                  4.17.20  4.17.21  4.17.21
+
+  devDependencies             Current  Target   Latest
+    □ typescript              4.8.0    5.0.0    5.3.3
+    □ @types/node             16.11.7  18.0.0   20.11.5
+
+  optionalDependencies        Current  Target   Latest
+    □ some-optional-package   1.0.0    1.1.0    1.2.0
+```
+
+**Sections:**
+
+- Packages are grouped under section headers: `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`
+- Each section shows column headers aligned with the package data
+
+**Columns:**
+
+- **Package**: Package name (may have suffix like ` dev`, ` peer`, ` optional` for clarity)
+- **Current**: Currently installed version
+- **Target**: Version that would be installed (respects semver constraints)
+- **Latest**: Latest available version
+
+### Keyboard Controls
+
+**Selection:**
+
+- **Space**: Toggle package selection
+- **Enter**: Confirm selections and update
+- **a/A**: Select all packages
+- **n/N**: Select none
+- **i/I**: Invert selection
+
+**Navigation:**
+
+- **↑/↓ Arrow keys** or **j/k**: Move cursor
+- **l/L**: Toggle between target and latest version for current package
+
+**Exit:**
+
+- **Ctrl+C** or **Ctrl+D**: Cancel without updating
+
+### Visual Indicators
+
+- **☑** Selected packages (will be updated)
+- **□** Unselected packages
+- **>** Current cursor position
+- **Colors**: Red (major), yellow (minor), green (patch) version changes
+- **Underlined**: Currently selected update target
+
+### Package Grouping
+
+Packages are organized in sections by dependency type:
+
+- **dependencies** - Regular runtime dependencies
+- **devDependencies** - Development dependencies
+- **peerDependencies** - Peer dependencies
+- **optionalDependencies** - Optional dependencies
+
+Within each section, individual packages may have additional suffixes (` dev`, ` peer`, ` optional`) for extra clarity.
+
 ## `--latest`
 
 By default, `bun update` will update to the latest version of a dependency that satisfies the version range specified in your `package.json`.
@@ -20,6 +100,8 @@ To update to the latest version, regardless of if it's compatible with the curre
 $ bun update --latest
 ```
 
+In interactive mode, you can toggle individual packages between their target version (respecting semver) and latest version using the **l** key.
+
 For example, with the following `package.json`:
 
 ```json

package/docs/guides/ecosystem/nuxt.md

@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
 ✔ Which package manager would you like to use?
 bun
 ◐ Installing dependencies...
-bun install v1.2.19 (16b4bf34)
+bun install v1.2.20-canary.20250721T140723 (16b4bf34)
  + @nuxt/devtools@0.8.2
  + nuxt@3.7.0
  785 packages installed [2.67s]

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

@@ -15,7 +15,7 @@ This will add the package to `peerDependencies` in `package.json`.
 ```json-diff
 {
   "peerDependencies": {
-+   "@types/bun": "^1.2.19"
++   "@types/bun": "^1.2.20-canary.20250721T140723"
   }
 }
 ```
@@ -27,7 +27,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.19"
+    "@types/bun": "^1.2.20-canary.20250721T140723"
   },
   "peerDependenciesMeta": {
 +   "@types/bun": {

package/docs/guides/install/from-npm-install-to-bun-install.md

@@ -97,7 +97,7 @@ $ bun update
 $ bun update @types/bun --latest
 
 # Update a dependency to a specific version
-$ bun update @types/bun@1.2.19
+$ bun update @types/bun@1.2.20-canary.20250721T140723
 
 # Update all dependencies to the latest versions
 $ bun update --latest

package/docs/guides/test/run-tests.md

@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
 
 ```sh
 $ bun test
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test.test.js:
 ✓ add [0.87ms]
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
 
 ```sh
 $ bun test test3
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test3.test.js:
 ✓ add [1.40ms]
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
 
 ```sh
 $ bun test -t add
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test.test.js:
 ✓ add [1.79ms]

package/docs/guides/test/snapshot.md

@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
 
 ```sh
 $ bun test test/snap
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.48ms]
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
 
 ```sh
 $ bun test
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.05ms]
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/test/update-snapshots.md

@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.19 (9c68abdb)
+bun test v1.2.20-canary.20250721T140723 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/util/version.md

@@ -5,7 +5,7 @@ name: Get the current Bun version
 Get the current version of Bun in a semver format.
 
 ```ts#index.ts
-Bun.version; // => "1.2.19"
+Bun.version; // => "1.2.20-canary.20250721T140723"
 ```
 
 ---

package/docs/install/index.md

@@ -81,6 +81,14 @@ $ bun install --verbose # debug logging
 $ bun install --silent  # no logging
 ```
 
+To use isolated installs instead of the default hoisted strategy:
+
+```bash
+$ bun install --linker isolated
+```
+
+Isolated installs create strict dependency isolation similar to pnpm, preventing phantom dependencies and ensuring more deterministic builds. For complete documentation, see [Isolated installs](https://bun.com/docs/install/isolated).
+
 {% details summary="Configuring behavior" %}
 The default behavior of `bun install` can be configured in `bunfig.toml`:
 
@@ -110,6 +118,10 @@ dryRun = false
 
 # equivalent to `--concurrent-scripts` flag
 concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
+
+# installation strategy: "hoisted" or "isolated"
+# default: "hoisted"
+linker = "hoisted"
 ```
 
 {% /details %}

package/docs/install/isolated.md

@@ -0,0 +1,195 @@
+Bun provides an alternative package installation strategy called **isolated installs** that creates strict dependency isolation similar to pnpm's approach. This mode prevents phantom dependencies and ensures reproducible, deterministic builds.
+
+## What are isolated installs?
+
+Isolated installs create a non-hoisted dependency structure where packages can only access their explicitly declared dependencies. This differs from the traditional "hoisted" installation strategy used by npm and Yarn, where dependencies are flattened into a shared `node_modules` directory.
+
+### Key benefits
+
+- **Prevents phantom dependencies** — Packages cannot accidentally import dependencies they haven't declared
+- **Deterministic resolution** — Same dependency tree regardless of what else is installed
+- **Better for monorepos** — Workspace isolation prevents cross-contamination between packages
+- **Reproducible builds** — More predictable resolution behavior across environments
+
+## Using isolated installs
+
+### Command line
+
+Use the `--linker` flag to specify the installation strategy:
+
+```bash
+# Use isolated installs
+$ bun install --linker isolated
+
+# Use traditional hoisted installs
+$ bun install --linker hoisted
+```
+
+### Configuration file
+
+Set the default linker strategy in your `bunfig.toml`:
+
+```toml
+[install]
+linker = "isolated"
+```
+
+### Default behavior
+
+By default, Bun uses the **hoisted** installation strategy for all projects. To use isolated installs, you must explicitly specify the `--linker isolated` flag or set it in your configuration file.
+
+## How isolated installs work
+
+### Directory structure
+
+Instead of hoisting dependencies, isolated installs create a two-tier structure:
+
+```
+node_modules/
+├── .bun/                          # Central package store
+│   ├── package@1.0.0/             # Versioned package installations
+│   │   └── node_modules/
+│   │       └── package/           # Actual package files
+│   ├── @scope+package@2.1.0/      # Scoped packages (+ replaces /)
+│   │   └── node_modules/
+│   │       └── @scope/
+│   │           └── package/
+│   └── ...
+└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlinks
+```
+
+### Resolution algorithm
+
+1. **Central store** — All packages are installed in `node_modules/.bun/package@version/` directories
+2. **Symlinks** — Top-level `node_modules` contains symlinks pointing to the central store
+3. **Peer resolution** — Complex peer dependencies create specialized directory names
+4. **Deduplication** — Packages with identical package IDs and peer dependency sets are shared
+
+### Workspace handling
+
+In monorepos, workspace dependencies are handled specially:
+
+- **Workspace packages** — Symlinked directly to their source directories, not the store
+- **Workspace dependencies** — Can access other workspace packages in the monorepo
+- **External dependencies** — Installed in the isolated store with proper isolation
+
+## Comparison with hoisted installs
+
+| Aspect                    | Hoisted (npm/Yarn)                         | Isolated (pnpm-like)                    |
+| ------------------------- | ------------------------------------------ | --------------------------------------- |
+| **Dependency access**     | Packages can access any hoisted dependency | Packages only see declared dependencies |
+| **Phantom dependencies**  | ❌ Possible                                | ✅ Prevented                            |
+| **Disk usage**            | ✅ Lower (shared installs)                 | ✅ Similar (uses symlinks)              |
+| **Determinism**           | ❌ Less deterministic                      | ✅ More deterministic                   |
+| **Node.js compatibility** | ✅ Standard behavior                       | ✅ Compatible via symlinks              |
+| **Best for**              | Single projects, legacy code               | Monorepos, strict dependency management |
+
+## Advanced features
+
+### Peer dependency handling
+
+Isolated installs handle peer dependencies through sophisticated resolution:
+
+```bash
+# Package with peer dependencies creates specialized paths
+node_modules/.bun/package@1.0.0_react@18.2.0/
+```
+
+The directory name encodes both the package version and its peer dependency versions, ensuring each unique combination gets its own installation.
+
+### Backend strategies
+
+Bun uses different file operation strategies for performance:
+
+- **Clonefile** (macOS) — Copy-on-write filesystem clones for maximum efficiency
+- **Hardlink** (Linux/Windows) — Hardlinks to save disk space
+- **Copyfile** (fallback) — Full file copies when other methods aren't available
+
+### Debugging isolated installs
+
+Enable verbose logging to understand the installation process:
+
+```bash
+$ bun install --linker isolated --verbose
+```
+
+This shows:
+
+- Store entry creation
+- Symlink operations
+- Peer dependency resolution
+- Deduplication decisions
+
+## Troubleshooting
+
+### Compatibility issues
+
+Some packages may not work correctly with isolated installs due to:
+
+- **Hardcoded paths** — Packages that assume a flat `node_modules` structure
+- **Dynamic imports** — Runtime imports that don't follow Node.js resolution
+- **Build tools** — Tools that scan `node_modules` directly
+
+If you encounter issues, you can:
+
+1. **Switch to hoisted mode** for specific projects:
+
+   ```bash
+   $ bun install --linker hoisted
+   ```
+
+2. **Report compatibility issues** to help improve isolated install support
+
+### Performance considerations
+
+- **Install time** — May be slightly slower due to symlink operations
+- **Disk usage** — Similar to hoisted (uses symlinks, not file copies)
+- **Memory usage** — Higher during install due to complex peer resolution
+
+## Migration guide
+
+### From npm/Yarn
+
+```bash
+# Remove existing node_modules and lockfiles
+$ rm -rf node_modules package-lock.json yarn.lock
+
+# Install with isolated linker
+$ bun install --linker isolated
+```
+
+### From pnpm
+
+Isolated installs are conceptually similar to pnpm, so migration should be straightforward:
+
+```bash
+# Remove pnpm files
+$ rm -rf node_modules pnpm-lock.yaml
+
+# Install with Bun's isolated linker
+$ bun install --linker isolated
+```
+
+The main difference is that Bun uses symlinks in `node_modules` while pnpm uses a global store with symlinks.
+
+## When to use isolated installs
+
+**Use isolated installs when:**
+
+- Working in monorepos with multiple packages
+- Strict dependency management is required
+- Preventing phantom dependencies is important
+- Building libraries that need deterministic dependencies
+
+**Use hoisted installs when:**
+
+- Working with legacy code that assumes flat `node_modules`
+- Compatibility with existing build tools is required
+- Working in environments where symlinks aren't well supported
+- You prefer the simpler traditional npm behavior
+
+## Related documentation
+
+- [Package manager > Workspaces](https://bun.com/docs/install/workspaces) — Monorepo workspace management
+- [Package manager > Lockfile](https://bun.com/docs/install/lockfile) — Understanding Bun's lockfile format
+- [CLI > install](https://bun.com/docs/cli/install) — Complete `bun install` command reference

package/docs/installation.md

@@ -14,7 +14,7 @@ Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Us
 ```bash#macOS/Linux_(curl)
 $ curl -fsSL https://bun.com/install | bash # for macOS, Linux, and WSL
 # to install a specific version
-$ curl -fsSL https://bun.com/install | bash -s "bun-v1.2.19"
+$ curl -fsSL https://bun.com/install | bash -s "bun-v1.2.20-canary.20250721T140723"
 ```
 
 ```bash#npm
@@ -189,10 +189,10 @@ Since Bun is a single binary, you can install older versions of Bun by re-runnin
 
 ### Installing a specific version of Bun on Linux/Mac
 
-To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.19`.
+To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.20-canary.20250721T140723`.
 
 ```sh
-$ curl -fsSL https://bun.com/install | bash -s "bun-v1.2.19"
+$ curl -fsSL https://bun.com/install | bash -s "bun-v1.2.20-canary.20250721T140723"
 ```
 
 ### Installing a specific version of Bun on Windows
@@ -201,7 +201,7 @@ On Windows, you can install a specific version of Bun by passing the version num
 
 ```sh
 # PowerShell:
-$ iex "& {$(irm https://bun.com/install.ps1)} -Version 1.2.19"
+$ iex "& {$(irm https://bun.com/install.ps1)} -Version 1.2.20-canary.20250721T140723"
 ```
 
 ## Downloading Bun binaries directly

package/docs/runtime/debugger.md

@@ -124,11 +124,11 @@ await fetch("https://example.com", {
 This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
 
 ```sh
-[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.19" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.20-canary.20250721T140723" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.19
+[fetch] > User-Agent: Bun/1.2.20-canary.20250721T140723
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -170,7 +170,7 @@ This prints the following to the console:
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.19
+[fetch] > User-Agent: Bun/1.2.20-canary.20250721T140723
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test v1.2.19
+bun test v1.2.20-canary.20250721T140723
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.19",
+  "version": "1.2.20-canary.20250721T140723",
   "name": "bun-types",
   "license": "MIT",
   "types": "./index.d.ts",