bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/cli/bun-completions.md

@@ -1,3 +0,0 @@
-This command installs completions for `zsh` and/or `fish`. It runs automatically on every `bun upgrade` and on install. It reads from `$SHELL` to determine which shell to install for. It tries several common shell completion directories for your shell and OS.
-
-If you want to copy the completions manually, run `bun completions > path-to-file`. If you know the completions directory to install them to, run `bun completions /path/to/directory`.

package/docs/cli/bun-install.md

@@ -1,349 +0,0 @@
-### `bun install`
-
-bun install is a fast package manager & npm client.
-
-bun install can be configured via `bunfig.toml`, environment variables, and CLI flags.
-
-#### 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.
-
-```toml
-# Using scoped packages with bun install
-[install.scopes]
-
-# Scope name      The value can be a URL string or an object
-"@mybigcompany" = { token = "123456", url = "https://registry.mybigcompany.com" }
-# URL is optional and falls back to the default registry
-
-# The "@" in the scope is optional
-mybigcompany2 = { token = "123456" }
-
-# Environment variables can be referenced as a string that starts with $ and it will be replaced
-mybigcompany3 = { token = "$npm_config_token" }
-
-# Setting username and password turns it into a Basic Auth header by taking base64("username:password")
-mybigcompany4 = { username = "myusername", password = "$npm_config_password", url = "https://registry.yarnpkg.com/" }
-# You can set username and password in the registry URL. This is the same as above.
-mybigcompany5 = "https://username:password@registry.yarnpkg.com/"
-
-# You can set a token for a registry URL:
-mybigcompany6 = "https://:$NPM_CONFIG_TOKEN@registry.yarnpkg.com/"
-
-[install]
-# Default registry
-# can be a URL string or an object
-registry = "https://registry.yarnpkg.com/"
-# as an object
-#registry = { url = "https://registry.yarnpkg.com/", token = "123456" }
-
-# Install for production? This is the equivalent to the "--production" CLI argument
-production = false
-
-# Save a text-based lockfile? This is equivalent to the "--save-text-lockfile" CLI argument
-saveTextLockfile = false
-
-# Disallow changes to lockfile? This is the equivalent to the "--frozen-lockfile" CLI argument
-frozenLockfile = false
-
-# Don't actually install
-dryRun = true
-
-# Install optionalDependencies (default: true)
-# Setting this to false is equivalent to the `--omit=optional` CLI argument
-optional = true
-
-# Install local devDependencies (default: true)
-# Setting this to false is equivalent to the `--omit=dev` CLI argument
-dev = true
-
-# Install peerDependencies (default: true)
-# Setting this to false is equivalent to the `--omit=peer` CLI argument
-peer = true
-
-# Max number of concurrent lifecycle scripts (default: (cpu count or GOMAXPROCS) x2)
-concurrentScripts = 16
-
-# When using `bun install -g`, install packages here
-globalDir = "~/.bun/install/global"
-
-# When using `bun install -g`, link package bins here
-globalBinDir = "~/.bun/bin"
-
-# cache-related configuration
-[install.cache]
-# The directory to use for the cache
-dir = "~/.bun/install/cache"
-
-# Don't load from the global cache.
-# Note: Bun may still write to node_modules/.cache
-disable = false
-
-
-# Always resolve the latest versions from the registry
-disableManifest = false
-
-
-# Lockfile-related configuration
-[install.lockfile]
-
-# Print a yarn v1 lockfile
-# Note: it does not load the lockfile, it just converts bun.lock into a yarn.lock
-print = "yarn"
-
-# Save the lockfile to disk
-save = true
-
-```
-
-If it's easier to read as TypeScript types:
-
-```ts
-export interface Root {
-  install: Install;
-}
-
-export interface Install {
-  scopes: Scopes;
-  registry: Registry;
-  production: boolean;
-  saveTextLockfile: boolean;
-  frozenLockfile: boolean;
-  dryRun: boolean;
-  optional: boolean;
-  dev: boolean;
-  peer: boolean;
-  globalDir: string;
-  globalBinDir: string;
-  cache: Cache;
-  lockfile: Lockfile;
-  logLevel: "debug" | "error" | "warn";
-}
-
-type Registry =
-  | string
-  | {
-      url?: string;
-      token?: string;
-      username?: string;
-      password?: string;
-    };
-
-type Scopes = Record<string, Registry>;
-
-export interface Cache {
-  dir: string;
-  disable: boolean;
-  disableManifest: boolean;
-}
-
-export interface Lockfile {
-  print?: "yarn";
-  save: boolean;
-}
-```
-
-## 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.
-
-## 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
-$ 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.
-
-```bash
-bun install
-```
-
-**Note**: Migration only runs when `bun.lock` is absent. There is currently no opt-out flag for pnpm migration.
-
-The migration process handles:
-
-### Lockfile Migration
-
-- Converts `pnpm-lock.yaml` to `bun.lock` format
-- Preserves package versions and resolution information
-- Maintains dependency relationships and peer dependencies
-- Handles patched dependencies with integrity hashes
-
-### Workspace Configuration
-
-When a `pnpm-workspace.yaml` file exists, Bun migrates workspace settings to your root `package.json`:
-
-```yaml
-# pnpm-workspace.yaml
-packages:
-  - "apps/*"
-  - "packages/*"
-
-catalog:
-  react: ^18.0.0
-  typescript: ^5.0.0
-
-catalogs:
-  build:
-    webpack: ^5.0.0
-    babel: ^7.0.0
-```
-
-The workspace packages list and catalogs are moved to the `workspaces` field in `package.json`:
-
-```json
-{
-  "workspaces": {
-    "packages": ["apps/*", "packages/*"],
-    "catalog": {
-      "react": "^18.0.0",
-      "typescript": "^5.0.0"
-    },
-    "catalogs": {
-      "build": {
-        "webpack": "^5.0.0",
-        "babel": "^7.0.0"
-      }
-    }
-  }
-}
-```
-
-### Catalog Dependencies
-
-Dependencies using pnpm's `catalog:` protocol are preserved:
-
-```json
-{
-  "dependencies": {
-    "react": "catalog:",
-    "webpack": "catalog:build"
-  }
-}
-```
-
-### Configuration Migration
-
-The following pnpm configuration is migrated from both `pnpm-lock.yaml` and `pnpm-workspace.yaml`:
-
-- **Overrides**: Moved from `pnpm.overrides` to root-level `overrides` in `package.json`
-- **Patched Dependencies**: Moved from `pnpm.patchedDependencies` to root-level `patchedDependencies` in `package.json`
-- **Workspace Overrides**: Applied from `pnpm-workspace.yaml` to root `package.json`
-
-### Requirements
-
-- Requires pnpm lockfile version 7 or higher
-- Workspace packages must have a `name` field in their `package.json`
-- All catalog entries referenced by dependencies must exist in the catalogs definition
-
-After migration, you can safely remove `pnpm-lock.yaml` and `pnpm-workspace.yaml` files.

package/docs/cli/bun-upgrade.md

@@ -1,39 +0,0 @@
-To upgrade Bun, run `bun upgrade`.
-
-It automatically downloads the latest version of Bun and overwrites the currently-running version.
-
-This works by checking the latest version of Bun in [bun-releases-for-updater](https://github.com/Jarred-Sumner/bun-releases-for-updater/releases) and unzipping it using the system-provided `unzip` library (so that Gatekeeper works on macOS)
-
-If for any reason you run into issues, you can also use the curl install script:
-
-```bash
-$ curl https://bun.com/install | bash
-```
-
-It will still work when Bun is already installed.
-
-Bun is distributed as a single binary file, so you can also do this manually:
-
-- Download the latest version of Bun for your platform in [bun-releases-for-updater](https://github.com/Jarred-Sumner/bun-releases-for-updater/releases/latest) (`darwin` == macOS)
-- Unzip the folder
-- Move the `bun` binary to `~/.bun/bin` (or anywhere)
-
-## `--canary`
-
-[Canary](https://github.com/oven-sh/bun/releases/tag/canary) builds are generated on every commit.
-
-To install a [canary](https://github.com/oven-sh/bun/releases/tag/canary) build of Bun, run:
-
-```bash
-$ bun upgrade --canary
-```
-
-This flag is not persistent (though that might change in the future). If you want to always run the canary build of Bun, set the `BUN_CANARY` environment variable to `1` in your shell's startup script.
-
-This will download the release zip from https://github.com/oven-sh/bun/releases/tag/canary.
-
-To revert to the latest published version of Bun, run:
-
-```bash
-$ bun upgrade
-```

package/docs/cli/info.md

@@ -1,65 +0,0 @@
-`bun info` displays package metadata from the npm registry.
-
-## Usage
-
-```bash
-$ 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
-$ bun info react@18.0.0
-```
-
-## Viewing specific properties
-
-You can also query specific properties from the package metadata:
-
-```bash
-$ 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
-$ bun info react --json
-```
-
-## Alias
-
-`bun pm view` is an alias for `bun info`:
-
-```bash
-$ bun pm view react  # equivalent to: bun info react
-```
-
-## Examples
-
-```bash
-# 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/cli/patch-commit.md

@@ -1,11 +0,0 @@
-An alias for `bun patch --commit` to maintain compatibility with pnpm.
-
-To get started with patch, first prepare the package for patching with [`bun patch <pkg>`](https://bun.com/docs/install/patch).
-
-### `--patches-dir`
-
-By default, `bun patch-commit` will use the `patches` directory in the temporary directory.
-
-You can specify a different directory with the `--patches-dir` flag.
-
-{% bunCLIUsage command="patch-commit" /%}

package/docs/cli/remove.md

@@ -1,7 +0,0 @@
-To remove a dependency:
-
-```bash
-$ bun remove ts-node
-```
-
-{% bunCLIUsage command="remove" /%}

package/docs/cli/unlink.md

@@ -1,9 +0,0 @@
-Use `bun unlink` in the root directory to unregister a local package.
-
-```bash
-$ cd /path/to/cool-pkg
-$ bun unlink
-bun unlink v1.x (7416672e)
-```
-
-{% bunCLIUsage command="unlink" /%}

package/docs/contributing/upgrading-webkit.md

@@ -1,57 +0,0 @@
-Bun uses [a fork](https://github.com/oven-sh/WebKit) of WebKit with a small number of changes.
-
-It's important to periodically update WebKit for many reasons:
-
-- Security
-- Performance
-- Compatibility
-- …and many more.
-
-To upgrade, first find the commit in **Bun's WebKit fork** (not Bun!) between when we last upgraded and now.
-
-```bash
-$ cd src/bun.js/WebKit # In the WebKit directory! not bun
-$ git checkout $COMMIT
-```
-
-This is the main command to run:
-
-```bash
-$ git merge upstream main
-# If you get an error saying histories are unrelated, run this and try again:
-$ git fetch --unshallow
-```
-
-Then, you will likely see some silly merge conflicts. Fix them and then run:
-
-```bash
-# You might have to run this multiple times.
-$ rm -rf WebKitBuild
-
-# Go to Bun's directory! Not WebKit.
-cd ../../../../
-make jsc-build-mac-compile
-```
-
-Make sure that JSC's CLI is able to load successfully. This verifies that the build is working.
-
-You know this worked when it printed help options. If it complains about symbols, crashes, or anything else that looks wrong, something is wrong.
-
-```bash
-src/bun.js/WebKit/WebKitBuild/Release/bin/jsc --help
-```
-
-Then, clear out our bindings and regenerate the C++<>Zig headers:
-
-```bash
-make clean-bindings headers builtins
-```
-
-Now update Bun's bindings wherever there are compiler errors:
-
-```bash
-# It will take awhile if you don't pass -j here
-make bindings -j10
-```
-
-This is the hard part. It might involve digging through WebKit's commit history to figure out what changed and why. Fortunately, WebKit contributors write great commit messages.

package/docs/ecosystem/elysia.md

@@ -1,24 +0,0 @@
-[Elysia](https://elysiajs.com) is a Bun-first performance focused web framework that takes full advantage of Bun's HTTP, file system, and hot reloading APIs.
-Designed with TypeScript in mind, you don't need to understand TypeScript to gain the benefit of TypeScript with Elysia. The library understands what you want and automatically infers the type from your code.
-
-⚡️ Elysia is [one of the fastest Bun web frameworks](https://github.com/SaltyAom/bun-http-framework-benchmark)
-
-```ts#server.ts
-import { Elysia } from 'elysia'
-
-const app = new Elysia()
-	.get('/', () => 'Hello Elysia')
-	.listen(8080)
-
-console.log(`🦊 Elysia is running at on port ${app.server.port}...`)
-```
-
-Get started with `bun create`.
-
-```bash
-$ bun create elysia ./myapp
-$ cd myapp
-$ bun run dev
-```
-
-Refer to the Elysia [documentation](https://elysiajs.com/quick-start.html) for more information.

package/docs/ecosystem/express.md

@@ -1,37 +0,0 @@
-Projects that use Express and other major Node.js HTTP libraries should work out of the box.
-
-{% callout %}
-If you run into bugs, [please file an issue](https://bun.com/issues) _in Bun's repo_, not the library. It is Bun's responsibility to address Node.js compatibility issues.
-{% /callout %}
-
-```ts
-import express from "express";
-
-const app = express();
-const port = 8080;
-
-app.get("/", (req, res) => {
-  res.send("Hello World!");
-});
-
-app.listen(port, () => {
-  console.log(`Listening on port ${port}...`);
-});
-```
-
-Bun implements the [`node:http`](https://nodejs.org/api/http.html) and [`node:https`](https://nodejs.org/api/https.html) modules that these libraries rely on. These modules can also be used directly, though [`Bun.serve`](https://bun.com/docs/api/http) is recommended for most use cases.
-
-{% callout %}
-**Note** — Refer to the [Runtime > Node.js APIs](https://bun.com/docs/runtime/nodejs-apis#node-http) page for more detailed compatibility information.
-{% /callout %}
-
-```ts
-import * as http from "node:http";
-
-http
-  .createServer(function (req, res) {
-    res.write("Hello World!");
-    res.end();
-  })
-  .listen(8080);
-```

package/docs/ecosystem/hono.md

@@ -1,18 +0,0 @@
-[Hono](https://github.com/honojs/hono) is a lightweight ultrafast web framework designed for the edge.
-
-```ts
-import { Hono } from "hono";
-const app = new Hono();
-
-app.get("/", c => c.text("Hono!"));
-
-export default app;
-```
-
-Get started with `bun create` or follow Hono's [Bun quickstart](https://hono.dev/getting-started/bun).
-
-```bash
-$ bun create hono ./myapp
-$ cd myapp
-$ bun run start
-```

package/docs/ecosystem/react.md

@@ -1,65 +0,0 @@
-Bun supports `.jsx` and `.tsx` files out of the box. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
-
-```tsx#react.tsx
-function Component(props: {message: string}) {
-  return (
-    <body>
-      <h1 style={{color: 'red'}}>{props.message}</h1>
-    </body>
-  );
-}
-
-console.log(<Component message="Hello world!" />);
-```
-
-Bun implements special logging for JSX to make debugging easier.
-
-```bash
-$ bun run react.tsx
-<Component message="Hello world!" />
-```
-
-### Prop punning
-
-The Bun runtime also supports "prop punning" for JSX. This is a shorthand syntax useful for assigning a variable to a prop with the same name.
-
-```tsx
-function Div(props: {className: string;}) {
-  const {className} = props;
-
-  // without punning
-  return <div className={className} />;
-  // with punning
-  return <div {className} />;
-}
-```
-
-### Server-side rendering
-
-To server-side render (SSR) React in an [HTTP server](https://bun.com/docs/api/http):
-
-```tsx#ssr.tsx
-import {renderToReadableStream} from 'react-dom/server';
-
-function Component(props: {message: string}) {
-  return (
-    <body>
-      <h1 style={{color: 'red'}}>{props.message}</h1>
-    </body>
-  );
-}
-
-Bun.serve({
-  port: 4000,
-  async fetch() {
-    const stream = await renderToReadableStream(
-      <Component message="Hello from server!" />
-    );
-    return new Response(stream, {
-      headers: {'Content-Type': 'text/html'},
-    });
-  },
-});
-```
-
-React `18.3` and later includes an [SSR optimization](https://github.com/facebook/react/pull/25597) that takes advantage of Bun's "direct" `ReadableStream` implementation.