bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/guides/write-file/stream.md

@@ -1,17 +0,0 @@
----
-name: Write a ReadableStream to a file
----
-
-To write a `ReadableStream` to disk, first create a `Response` instance from the stream. This `Response` can then be written to disk using [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).
-
-```ts
-const stream: ReadableStream = ...;
-const path = "./file.txt";
-const response = new Response(stream);
-
-await Bun.write(path, response);
-```
-
----
-
-See [Docs > API > File I/O](https://bun.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

package/docs/guides/write-file/unlink.md

@@ -1,16 +0,0 @@
----
-name: Delete a file
----
-
-The `Bun.file()` function accepts a path and returns a `BunFile` instance. Use the `.delete()` method to delete the file.
-
-```ts
-const path = "/path/to/file.txt";
-const file = Bun.file(path);
-
-await file.delete();
-```
-
----
-
-See [Docs > API > File I/O](https://bun.com/docs/api/file-io#reading-files-bun-file) for complete documentation of `Bun.file()`.

package/docs/index.md

@@ -1,77 +0,0 @@
-Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called `bun`.
-
-At its core is the _Bun runtime_, a fast JavaScript runtime designed as **a drop-in replacement for Node.js**. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.
-
-```bash
-$ bun run index.tsx  # TS and JSX supported out of the box
-```
-
-The `bun` command-line tool also implements a test runner, script runner, and Node.js-compatible package manager, all significantly faster than existing tools and usable in existing Node.js projects with little to no changes necessary.
-
-```bash
-$ bun run start                 # run the `start` script
-$ bun install <pkg>             # install a package
-$ bun build ./index.tsx         # bundle a project for browsers
-$ bun test                      # run tests
-$ bunx cowsay 'Hello, world!'   # execute a package
-```
-
-Get started with one of the quick links below, or read on to learn more about Bun.
-
-{% block className="gap-2 grid grid-flow-row grid-cols-1 md:grid-cols-2" %}
-{% arrowbutton href="/docs/installation" text="Install Bun" /%}
-{% arrowbutton href="/docs/quickstart" text="Do the quickstart" /%}
-{% arrowbutton href="/docs/cli/install" text="Install a package" /%}
-{% arrowbutton href="/docs/cli/bun-create" text="Use a project template" /%}
-{% arrowbutton href="/docs/bundler" text="Bundle code for production" /%}
-{% arrowbutton href="/docs/api/http" text="Build an HTTP server" /%}
-{% arrowbutton href="/docs/api/websockets" text="Build a Websocket server" /%}
-{% arrowbutton href="/docs/api/file-io" text="Read and write files" /%}
-{% arrowbutton href="/docs/api/sqlite" text="Run SQLite queries" /%}
-{% arrowbutton href="/docs/cli/test" text="Write and run tests" /%}
-{% /block %}
-
-## What is a runtime?
-
-JavaScript (or, more formally, ECMAScript) is just a _specification_ for a programming language. Anyone can write a JavaScript _engine_ that ingests a valid JavaScript program and executes it. The two most popular engines in use today are V8 (developed by Google)
-and JavaScriptCore (developed by Apple). Both are open source.
-
-But most JavaScript programs don't run in a vacuum. They need a way to access the outside world to perform useful tasks. This is where _runtimes_ come in. They implement additional APIs that are then made available to the JavaScript programs they execute.
-
-### Browsers
-
-Notably, browsers ship with JavaScript runtimes that implement a set of Web-specific APIs that are exposed via the global `window` object. Any JavaScript code executed by the browser can use these APIs to implement interactive or dynamic behavior in the context of the current webpage.
-
-<!-- JavaScript runtime that exposes  JavaScript engines are designed to run "vanilla" JavaScript programs, but it's often JavaScript _runtimes_ use an engine internally to execute the code and implement additional APIs that are then made available to executed programs.
-JavaScript was [initially designed](https://en.wikipedia.org/wiki/JavaScript) as a language to run in web browsers to implement interactivity and dynamic behavior in web pages. Browsers are the first JavaScript runtimes. JavaScript programs that are executed in browsers have access to a set of Web-specific global APIs on the `window` object. -->
-
-### Node.js
-
-Similarly, Node.js is a JavaScript runtime that can be used in non-browser environments, like servers. JavaScript programs executed by Node.js have access to a set of Node.js-specific [globals](https://nodejs.org/api/globals.html) like `Buffer`, `process`, and `__dirname` in addition to built-in modules for performing OS-level tasks like reading/writing files (`node:fs`) and networking (`node:net`, `node:http`). Node.js also implements a CommonJS-based module system and resolution algorithm that pre-dates JavaScript's native module system.
-
-<!-- Bun.js prefers Web API compatibility instead of designing new APIs when possible. Bun.js also implements some Node.js APIs. -->
-
-Bun is designed as a faster, leaner, more modern replacement for Node.js.
-
-<!-- ## Why a new runtime?
-
-Bun is designed as a faster, leaner, more modern replacement for Node.js. Node.js is burdened by ingrained performance issues, backwards compatibility concerns, and slow development velocity—inevitable issues for a project of its age and magnitude. -->
-
-## Design goals
-
-Bun is designed from the ground-up with today's JavaScript ecosystem in mind.
-
-- **Speed**. Bun processes start [4x faster than Node.js](https://twitter.com/jarredsumner/status/1499225725492076544) currently (try it yourself!)
-- **TypeScript & JSX support**. You can directly execute `.jsx`, `.ts`, and `.tsx` files; Bun's transpiler converts these to vanilla JavaScript before execution.
-- **ESM & CommonJS compatibility**. The world is moving towards ES modules (ESM), but millions of packages on npm still require CommonJS. Bun recommends ES modules, but supports CommonJS.
-- **Web-standard APIs**. Bun implements standard Web APIs like `fetch`, `WebSocket`, and `ReadableStream`. Bun is powered by the JavaScriptCore engine, which is developed by Apple for Safari, so some APIs like [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) directly use [Safari's implementation](https://github.com/oven-sh/bun/blob/HEAD/src/bun.js/bindings/webcore/JSFetchHeaders.cpp).
-- **Node.js compatibility**. In addition to supporting Node-style module resolution, Bun aims for full compatibility with built-in Node.js globals (`process`, `Buffer`) and modules (`path`, `fs`, `http`, etc.) _This is an ongoing effort that is not complete._ Refer to the [compatibility page](https://bun.com/docs/runtime/nodejs-apis) for the current status.
-
-Bun is more than a runtime. The long-term goal is to be a cohesive, infrastructural toolkit for building apps with JavaScript/TypeScript, including a package manager, transpiler, bundler, script runner, test runner, and more.
-
-<!-- - tsconfig.json `"paths"` is natively supported, along with `"exports"` in package.json
-- `fs`, `path`, and `process` from Node.js are partially implemented
-- Web APIs like [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) and more are built-in
-- [`HTMLRewriter`](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/) makes it easy to transform HTML in Bun.js
-- `.env` files automatically load into `process.env` and `Bun.env`
-- top level await -->

package/docs/install/audit.md

@@ -1,57 +0,0 @@
-`bun audit` checks your installed packages for known security vulnerabilities.
-
-Run the command in a project with a `bun.lock` file:
-
-```bash
-$ bun audit
-```
-
-Bun sends the list of installed packages and versions to NPM, and prints a report of any vulnerabilities that were found. Packages installed from registries other than the default registry are skipped.
-
-If no vulnerabilities are found, the command prints:
-
-```
-No vulnerabilities found
-```
-
-When vulnerabilities are detected, each affected package is listed along with the severity, a short description and a link to the advisory. At the end of the report Bun prints a summary and hints for updating:
-
-```
-3 vulnerabilities (1 high, 2 moderate)
-To update all dependencies to the latest compatible versions:
-  bun update
-To update all dependencies to the latest versions (including breaking changes):
-  bun update --latest
-```
-
-### Filtering options
-
-**`--audit-level=<low|moderate|high|critical>`** - Only show vulnerabilities at this severity level or higher:
-
-```bash
-bun audit --audit-level=high
-```
-
-**`--prod`** - Audit only production dependencies (excludes devDependencies):
-
-```bash
-bun audit --prod
-```
-
-**`--ignore <CVE>`** - Ignore specific CVEs (can be used multiple times):
-
-```bash
-bun audit --ignore CVE-2022-25883 --ignore CVE-2023-26136
-```
-
-### `--json`
-
-Use the `--json` flag to print the raw JSON response from the registry instead of the formatted report:
-
-```bash
-$ bun audit --json
-```
-
-### Exit code
-
-`bun audit` will exit with code `0` if no vulnerabilities are found and `1` if the report lists any vulnerabilities. This will still happen even if `--json` is passed.

package/docs/install/cache.md

@@ -1,59 +0,0 @@
-All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`, or the path defined by the environment variable `BUN_INSTALL_CACHE_DIR`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
-
-{% details summary="Configuring cache behavior (bunfig.toml)" %}
-
-```toml
-[install.cache]
-# the directory to use for the cache
-dir = "~/.bun/install/cache"
-
-# when true, don't load from the global cache.
-# Bun may still write to node_modules/.cache
-disable = false
-
-# when true, always resolve the latest versions from the registry
-disableManifest = false
-```
-
-{% /details %}
-
-## Minimizing re-downloads
-
-Bun strives to avoid re-downloading packages multiple times. When installing a package, if the cache already contains a version in the range specified by `package.json`, Bun will use the cached package instead of downloading it again.
-
-{% details summary="Installation details" %}
-If the semver version has pre-release suffix (`1.0.0-beta.0`) or a build suffix (`1.0.0+20220101`), it is replaced with a hash of that value instead, to reduce the chances of errors associated with long file paths.
-
-When the `node_modules` folder exists, before installing, Bun checks that `node_modules` contains all expected packages with appropriate versions. If so `bun install` completes. Bun uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`.
-
-If a package is missing or has a version incompatible with the `package.json`, Bun checks for a compatible module in the cache. If found, it is installed into `node_modules`. Otherwise, the package will be downloaded from the registry then installed.
-{% /details %}
-
-## Fast copying
-
-Once a package is downloaded into the cache, Bun still needs to copy those files into `node_modules`. Bun uses the fastest syscalls available to perform this task. On Linux, it uses hardlinks; on macOS, it uses `clonefile`.
-
-## Saving disk space
-
-Since Bun uses hardlinks to "copy" a module into a project's `node_modules` directory on Linux and Windows, the contents of the package only exist in a single location on disk, greatly reducing the amount of disk space dedicated to `node_modules`.
-
-This benefit also applies to macOS, but there are exceptions. It uses `clonefile` which is copy-on-write, meaning it will not occupy disk space, but it will count towards drive's limit. This behavior is useful if something attempts to patch `node_modules/*`, so it's impossible to affect other installations.
-
-{% details summary="Installation strategies" %}
-This behavior is configurable with the `--backend` flag, which is respected by all of Bun's package management commands.
-
-- **`hardlink`**: Default on Linux and Windows.
-- **`clonefile`** Default on macOS.
-- **`clonefile_each_dir`**: Similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`.
-- **`copyfile`**: The fallback used when any of the above fail. It is the slowest option. On macOS, it uses `fcopyfile()`; on Linux it uses `copy_file_range()`.
-- **`symlink`**: Currently used only `file:` (and eventually `link:`) dependencies. 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
-$ bun install --backend symlink
-$ node --preserve-symlinks ./foo.js
-$ bun --preserve-symlinks ./foo.js
-```
-
-{% /details %}

package/docs/install/catalogs.md

@@ -1,298 +0,0 @@
-Catalogs in Bun provide a straightforward way to share common dependency versions across multiple packages in a monorepo. Rather than specifying the same versions repeatedly in each workspace package, you define them once in the root package.json and reference them consistently throughout your project.
-
-## Overview
-
-Unlike traditional dependency management where each workspace package needs to independently specify versions, catalogs let you:
-
-1. Define version catalogs in the root package.json
-2. Reference these versions with a simple `catalog:` protocol
-3. Update all packages simultaneously by changing the version in just one place
-
-This is especially useful in large monorepos where dozens of packages need to use the same version of key dependencies.
-
-## How to Use Catalogs
-
-### Directory Structure Example
-
-Consider a monorepo with the following structure:
-
-```
-my-monorepo/
-├── package.json
-├── bun.lock
-└── packages/
-    ├── app/
-    │   └── package.json
-    ├── ui/
-    │   └── package.json
-    └── utils/
-        └── package.json
-```
-
-### 1. Define Catalogs in Root package.json
-
-In your root-level `package.json`, add a `catalog` or `catalogs` field within the `workspaces` object:
-
-```json
-{
-  "name": "my-monorepo",
-  "workspaces": {
-    "packages": ["packages/*"],
-    "catalog": {
-      "react": "^19.0.0",
-      "react-dom": "^19.0.0"
-    },
-    "catalogs": {
-      "testing": {
-        "jest": "30.0.0",
-        "testing-library": "14.0.0"
-      }
-    }
-  }
-}
-```
-
-If you put `catalog` or `catalogs` at the top level of the `package.json` file, that will work too.
-
-### 2. Reference Catalog Versions in Workspace Packages
-
-In your workspace packages, use the `catalog:` protocol to reference versions:
-
-**packages/app/package.json**
-
-```json
-{
-  "name": "app",
-  "dependencies": {
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "jest": "catalog:testing"
-  }
-}
-```
-
-**packages/ui/package.json**
-
-```json
-{
-  "name": "ui",
-  "dependencies": {
-    "react": "catalog:",
-    "react-dom": "catalog:"
-  },
-  "devDependencies": {
-    "jest": "catalog:testing",
-    "testing-library": "catalog:testing"
-  }
-}
-```
-
-### 3. Run Bun Install
-
-Run `bun install` to install all dependencies according to the catalog versions.
-
-## Catalog vs Catalogs
-
-Bun supports two ways to define catalogs:
-
-1. **`catalog`** (singular): A single default catalog for commonly used dependencies
-
-   ```json
-   "catalog": {
-     "react": "^19.0.0",
-     "react-dom": "^19.0.0"
-   }
-   ```
-
-   Reference with simply `catalog:`:
-
-   ```json
-   "dependencies": {
-     "react": "catalog:"
-   }
-   ```
-
-2. **`catalogs`** (plural): Multiple named catalogs for grouping dependencies
-
-   ```json
-   "catalogs": {
-     "testing": {
-       "jest": "30.0.0"
-     },
-     "ui": {
-       "tailwind": "4.0.0"
-     }
-   }
-   ```
-
-   Reference with `catalog:<name>`:
-
-   ```json
-   "dependencies": {
-     "jest": "catalog:testing",
-     "tailwind": "catalog:ui"
-   }
-   ```
-
-## Benefits of Using Catalogs
-
-- **Consistency**: Ensures all packages use the same version of critical dependencies
-- **Maintenance**: Update a dependency version in one place instead of across multiple package.json files
-- **Clarity**: Makes it obvious which dependencies are standardized across your monorepo
-- **Simplicity**: No need for complex version resolution strategies or external tools
-
-## Real-World Example
-
-Here's a more comprehensive example for a React application:
-
-**Root package.json**
-
-```json
-{
-  "name": "react-monorepo",
-  "workspaces": {
-    "packages": ["packages/*"],
-    "catalog": {
-      "react": "^19.0.0",
-      "react-dom": "^19.0.0",
-      "react-router-dom": "^6.15.0"
-    },
-    "catalogs": {
-      "build": {
-        "webpack": "5.88.2",
-        "babel": "7.22.10"
-      },
-      "testing": {
-        "jest": "29.6.2",
-        "react-testing-library": "14.0.0"
-      }
-    }
-  },
-  "devDependencies": {
-    "typescript": "5.1.6"
-  }
-}
-```
-
-**packages/app/package.json**
-
-```json
-{
-  "name": "app",
-  "dependencies": {
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "react-router-dom": "catalog:",
-    "@monorepo/ui": "workspace:*",
-    "@monorepo/utils": "workspace:*"
-  },
-  "devDependencies": {
-    "webpack": "catalog:build",
-    "babel": "catalog:build",
-    "jest": "catalog:testing",
-    "react-testing-library": "catalog:testing"
-  }
-}
-```
-
-**packages/ui/package.json**
-
-```json
-{
-  "name": "@monorepo/ui",
-  "dependencies": {
-    "react": "catalog:",
-    "react-dom": "catalog:"
-  },
-  "devDependencies": {
-    "jest": "catalog:testing",
-    "react-testing-library": "catalog:testing"
-  }
-}
-```
-
-**packages/utils/package.json**
-
-```json
-{
-  "name": "@monorepo/utils",
-  "dependencies": {
-    "react": "catalog:"
-  },
-  "devDependencies": {
-    "jest": "catalog:testing"
-  }
-}
-```
-
-## Updating Versions
-
-To update versions across all packages, simply change the version in the root package.json:
-
-```json
-"catalog": {
-  "react": "^19.1.0",  // Updated from ^19.0.0
-  "react-dom": "^19.1.0"  // Updated from ^19.0.0
-}
-```
-
-Then run `bun install` to update all packages.
-
-## Lockfile Integration
-
-Bun's lockfile tracks catalog versions, making it easy to ensure consistent installations across different environments. The lockfile includes:
-
-- The catalog definitions from your package.json
-- The resolution of each cataloged dependency
-
-```
-// bun.lock (excerpt)
-{
-  "lockfileVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "react-monorepo",
-    },
-    "packages/app": {
-      "name": "app",
-      "dependencies": {
-        "react": "catalog:",
-        "react-dom": "catalog:",
-        ...
-      },
-    },
-    ...
-  },
-  "catalog": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    ...
-  },
-  "catalogs": {
-    "build": {
-      "webpack": "5.88.2",
-      ...
-    },
-    ...
-  },
-  "packages": {
-    ...
-  }
-}
-```
-
-## Limitations and Edge Cases
-
-- Catalog references must match a dependency defined in either `catalog` or one of the named `catalogs`
-- Empty strings and whitespace in catalog names are ignored (treated as default catalog)
-- Invalid dependency versions in catalogs will fail to resolve during `bun install`
-- Catalogs are only available within workspaces; they cannot be used outside the monorepo
-
-Bun's catalog system provides a powerful yet simple way to maintain consistency across your monorepo without introducing additional complexity to your workflow.
-
-## Publishing
-
-When you run `bun publish` or `bun pm pack`, Bun automatically replaces
-`catalog:` references in your `package.json` with the resolved version numbers.
-The published package includes regular semver strings and no longer depends on
-your catalog definitions.