bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/install/npmrc.md

@@ -0,0 +1,75 @@
+Bun supports loading configuration options from [`.npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc) files, allowing you to reuse existing registry/scope configurations.
+
+{% callout %}
+
+**NOTE**: We recommend migrating your `.npmrc` file to Bun's [`bunfig.toml`](https://bun.sh/docs/runtime/bunfig) format, as it provides more flexible options and can let you configure Bun-specific options.
+
+{% /callout %}
+
+# Supported options
+
+### `registry`: Set the default registry
+
+The default registry is used to resolve packages, it's default value is `npm`'s official registry (`https://registry.npmjs.org/`).
+
+To change it, you can set the `registry` option in `.npmrc`:
+
+```ini
+registry=http://localhost:4873/
+```
+
+The equivalent `bunfig.toml` option is [`install.registry`](https://bun.sh/docs/runtime/bunfig#install-registry):
+
+```toml
+install.registry = "http://localhost:4873/"
+```
+
+### `@<scope>:registry`: Set the registry for a specific scope
+
+Allows you to set the registry for a specific scope:
+
+```ini
+@myorg:registry=http://localhost:4873/
+```
+
+The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](https://bun.sh/docs/runtime/bunfig#install-registry):
+
+```toml
+[install.scopes]
+myorg = "http://localhost:4873/"
+```
+
+### `//<registry_url>/:<key>=<value>`: Configure options for a specific registry
+
+Allows you to set options for a specific registry:
+
+```ini
+# set an auth token for the registry
+# ${...} is a placeholder for environment variables
+//http://localhost:4873/:_authToken=${NPM_TOKEN}
+
+
+# or you could set a username and password
+# note that the password is base64 encoded
+//http://localhost:4873/:username=myusername
+
+//http://localhost:4873/:_password=${NPM_PASSWORD}
+
+# or use _auth, which is your username and password
+# combined into a single string, which is then base 64 encoded
+//http://localhost:4873/:_auth=${NPM_AUTH}
+```
+
+The following options are supported:
+
+- `_authToken`
+- `username`
+- `_password` (base64 encoded password)
+- `_auth` (base64 encoded username:password, e.g. `btoa(username + ":" + password)`)
+
+The equivalent `bunfig.toml` option is to add a key in [`install.scopes`](https://bun.sh/docs/runtime/bunfig#install-registry):
+
+```toml
+[install.scopes]
+myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }
+```

package/docs/install/overrides.md

@@ -0,0 +1,73 @@
+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.
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
+  }
+```
+
+By default, Bun will install the latest version of all dependencies and metadependencies, according to the ranges specified in each package's `package.json`. Let's say you have a project with one dependency, `foo`, which in turn has a dependency on `bar`. This means `bar` is a _metadependency_ of our project.
+
+```json#package.json
+{
+  "name": "my-app",
+  "dependencies": {
+    "foo": "^2.0.0"
+  }
+}
+```
+
+When you run `bun install`, Bun will install the latest versions of each package.
+
+```
+# tree layout of node_modules
+node_modules
+├── foo@1.2.3
+└── bar@4.5.6
+```
+
+But what if a security vulnerability was introduced in `bar@4.5.6`? We may want a way to pin `bar` to an older version that doesn't have the vulnerability. This is where `"overrides"`/`"resolutions"` come in.
+
+## `"overrides"`
+
+Add `bar` to the `"overrides"` field in `package.json`. Bun will defer to the specified version range when determining which version of `bar` to install, whether it's a dependency or a metadependency.
+
+{% callout %}
+**Note** — Bun currently only supports top-level `"overrides"`. [Nested overrides](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) are not supported.
+{% /callout %}
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
+  }
+```
+
+## `"resolutions"`
+
+The syntax is similar for `"resolutions"`, which is Yarn's alternative to `"overrides"`. Bun supports this feature to make migration from Yarn easier.
+
+As with `"overrides"`, _nested resolutions_ are not currently supported.
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "resolutions": {
++     "bar": "~4.4.0"
++   }
+  }
+```

package/docs/install/patch.md

@@ -0,0 +1,57 @@
+`bun patch` lets you persistently patch node_modules in a maintainable, git-friendly way.
+
+Sometimes, you need to make a small change to a package in `node_modules/` to fix a bug or add a feature. `bun patch` makes it easy to do this without vendoring the entire package and reuse the patch across multiple installs, multiple projects, and multiple machines.
+
+Features:
+
+- Generates `.patch` files applied to dependencies in `node_modules` on install
+- `.patch` files can be committed to your repository, reused across multiple installs, projects, and machines
+- `"patchedDependencies"` in `package.json` keeps track of patched packages
+- `bun patch` lets you patch packages in `node_modules/` while preserving the integrity of Bun's [Global Cache](https://bun.sh/docs/install/cache)
+- Test your changes locally before committing them with `bun patch --commit <pkg>`
+- To preserve disk space and keep `bun install` fast, patched packages are committed to the Global Cache and shared across projects where possible
+
+#### Step 1. Prepare the package for patching
+
+To get started, use `bun patch <pkg>` to prepare the package for patching:
+
+```bash
+# you can supply the package name
+$ bun patch react
+
+# ...and a precise version in case multiple versions are installed
+$ bun patch react@17.0.2
+
+# or the path to the package
+$ bun patch node_modules/react
+```
+
+{% callout %}
+**Note** — Don't forget to call `bun patch <pkg>`! This ensures the package folder in `node_modules/` contains a fresh copy of the package with no symlinks/hardlinks to Bun's cache.
+
+If you forget to do this, you might end up editing the package globally in the cache!
+{% /callout %}
+
+#### Step 2. Test your changes locally
+
+`bun patch <pkg>` makes it safe to edit the `<pkg>` in `node_modules/` directly, while preserving the integrity of Bun's [Global Cache](https://bun.sh/docs/install/cache). This works by re-creating an unlinked clone of the package in `node_modules/` and diffing it against the original package in the Global Cache.
+
+#### Step 3. Commit your changes
+
+Once you're happy with your changes, run `bun patch --commit <path or pkg>`.
+
+Bun will generate a patch file in `patches/`, update your `package.json` and lockfile, and Bun will start using the patched package:
+
+```bash
+# you can supply the path to the patched package
+$ bun patch --commit node_modules/react
+
+# ... or the package name and optionally the version
+$ bun patch --commit react@17.0.2
+
+# choose the directory to store the patch files
+$ bun patch --commit react --patches-dir=mypatches
+
+# `patch-commit` is available for compatibility with pnpm
+$ bun patch-commit react
+```

package/docs/install/registries.md

@@ -0,0 +1,30 @@
+The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`:
+
+```toml
+[install]
+# set default registry as a string
+registry = "https://registry.npmjs.org"
+# set a token
+registry = { url = "https://registry.npmjs.org", token = "123456" }
+# set a username/password
+registry = "https://username:password@registry.npmjs.org"
+```
+
+To configure a private registry scoped to a particular organization:
+
+```toml
+[install.scopes]
+# registry as string
+"@myorg1" = "https://username:password@registry.myorg.com/"
+
+# registry with username/password
+# you can reference environment variables
+"@myorg2" = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" }
+
+# registry with token
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+### `.npmrc`
+
+Bun also reads `.npmrc` files, [learn more](https://bun.sh/docs/install/npmrc).

package/docs/install/workspaces.md

@@ -0,0 +1,70 @@
+Bun supports [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description) in `package.json`. Workspaces make it easy to develop complex software as a _monorepo_ consisting of several independent packages.
+
+It's common for a monorepo to have the following structure:
+
+```
+tree
+<root>
+├── README.md
+├── bun.lockb
+├── package.json
+├── tsconfig.json
+└── packages
+    ├── pkg-a
+    │   ├── index.ts
+    │   ├── package.json
+    │   └── tsconfig.json
+    ├── pkg-b
+    │   ├── index.ts
+    │   ├── package.json
+    │   └── tsconfig.json
+    └── pkg-c
+        ├── index.ts
+        ├── package.json
+        └── tsconfig.json
+```
+
+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
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "workspaces": ["packages/*"],
+  "devDependencies": {
+    "example-package-in-monorepo": "workspace:*"
+  }
+}
+```
+
+{% callout %}
+**Glob support** — Bun supports full glob syntax in `"workspaces"` (see [here](https://bun.sh/docs/api/glob#supported-glob-patterns) for a comprehensive list of supported syntax), _except_ for exclusions (e.g. `!**/excluded/**`), which are not implemented yet.
+{% /callout %}
+
+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
+{
+  "name": "pkg-a",
+  "version": "1.0.0",
+  "dependencies": {
+    "pkg-b": "workspace:*"
+  }
+}
+```
+
+Workspaces have a couple major benefits.
+
+- **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency in `package.json`. If package `b` depends on `a`, `bun install` will install your local `packages/a` directory into `node_modules` instead of downloading it from the npm registry.
+- **Dependencies can be de-duplicated.** If `a` and `b` share a common dependency, it will be _hoisted_ to the root `node_modules` directory. This reduces redundant disk usage and minimizes "dependency hell" issues associated with having multiple versions of a package installed simultaneously.
+- **Run scripts in multiple packages.** You can use the [`--filter` flag](https://bun.sh/docs/cli/filter) to easily run `package.json` scripts in multiple packages in your workspace.
+
+{% callout %}
+⚡️ **Speed** — Installs are fast, even for big monorepos. Bun installs the [Remix](https://github.com/remix-run/remix) monorepo in about `500ms` on Linux.
+
+- 28x faster than `npm install`
+- 12x faster than `yarn install` (v1)
+- 8x faster than `pnpm install`
+
+{% image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" /%}
+{% /callout %}

package/docs/installation.md

@@ -0,0 +1,289 @@
+Bun ships as a single executable with no dependencies that can be installed a few different ways.
+
+## Installing
+
+### macOS and Linux
+
+{% callout %}
+**Linux users** — The `unzip` package is required to install Bun. Use `sudo apt install unzip` to install `unzip` package.
+Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Use `uname -r` to check Kernel version.
+{% /callout %}
+
+{% codetabs %}
+
+```bash#macOS/Linux_(curl)
+$ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
+# to install a specific version
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.0.0"
+```
+
+```bash#npm
+$ npm install -g bun # the last `npm` command you'll ever need
+```
+
+```bash#Homebrew
+$ brew install oven-sh/bun/bun # for macOS and Linux
+```
+
+```bash#Docker
+$ docker pull oven/bun
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun
+```
+
+{% /codetabs %}
+
+### Windows
+
+To install, paste this into a terminal:
+
+{% codetabs %}
+
+```powershell#PowerShell/cmd.exe
+> powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+```powershell#npm
+> npm install -g bun # the last `npm` command you'll ever need
+```
+
+```powershell#Scoop
+> scoop install bun
+```
+
+{% /codetabs %}
+
+{% callout %}
+Bun requires a minimum of Windows 10 version 1809
+{% /callout %}
+
+For support and discussion, please join the [#windows channel on our Discord](http://bun.sh/discord).
+
+## Docker
+
+Bun provides a [Docker image](https://hub.docker.com/r/oven/bun/tags) that supports both Linux x64 and arm64.
+
+```bash
+$ docker pull oven/bun
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun
+```
+
+There are also image variants for different operating systems.
+
+```bash
+$ docker pull oven/bun:debian
+$ docker pull oven/bun:slim
+$ docker pull oven/bun:distroless
+$ docker pull oven/bun:alpine
+```
+
+## Checking installation
+
+To check that Bun was installed successfully, open a new terminal window and run `bun --version`.
+
+```sh
+$ bun --version
+1.x.y
+```
+
+To see the precise commit of [oven-sh/bun](https://github.com/oven-sh/bun) that you're using, run `bun --revision`.
+
+```sh
+$ bun --revision
+1.x.y+b7982ac13189
+```
+
+If you've installed Bun but are seeing a `command not found` error, you may have to manually add the installation directory (`~/.bun/bin`) to your `PATH`.
+
+{% details summary="How to add to your `PATH`" %}
+First, determine what shell you're using:
+
+```sh
+$ echo $SHELL
+/bin/zsh # or /bin/bash or /bin/fish
+```
+
+Then add these lines below to bottom of your shell's configuration file.
+
+{% codetabs %}
+
+```bash#~/.zshrc
+# add to ~/.zshrc
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+```
+
+```bash#~/.bashrc
+# add to ~/.bashrc
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+```
+
+```sh#~/.config/fish/config.fish
+# add to ~/.config/fish/config.fish
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+```
+
+{% /codetabs %}
+Save the file. You'll need to open a new shell/terminal window for the changes to take effect.
+
+{% /details %}
+
+## Upgrading
+
+Once installed, the binary can upgrade itself.
+
+```sh
+$ bun upgrade
+```
+
+{% callout %}
+**Homebrew users** — To avoid conflicts with Homebrew, use `brew upgrade bun` instead.
+
+**Scoop users** — To avoid conflicts with Scoop, use `scoop update bun` instead.
+
+{% /callout %}
+
+## Canary builds
+
+Bun automatically releases an (untested) canary build on every commit to `main`. To upgrade to the latest canary build:
+
+```sh
+$ bun upgrade --canary
+```
+
+The canary build is useful for testing new features and bug fixes before they're released in a stable build. To help the Bun team fix bugs faster, canary builds automatically upload crash reports to Bun's team.
+
+[View canary build](https://github.com/oven-sh/bun/releases/tag/canary)
+
+{% callout %}
+**Note** — To switch back to a stable release from canary, run `bun upgrade --stable`.
+{% /callout %}
+
+## Installing older versions of Bun
+
+Since Bun is a single binary, you can install older versions of Bun by re-running the installer script with a specific version.
+
+### 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.1.6` or `bun-v1.1.1`.
+
+```sh
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.1.6"
+```
+
+### Installing a specific version of Bun on Windows
+
+On Windows, you can install a specific version of Bun by passing the version number to the Powershell install script.
+
+```sh
+# PowerShell:
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.1.6"
+```
+
+## Downloading Bun binaries directly
+
+To download Bun binaries directly, you can visit the [releases page](https://github.com/oven-sh/bun/releases) page on GitHub.
+
+For convenience, here are download links for the latest version:
+
+- [`bun-linux-x64.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip)
+- [`bun-linux-x64-baseline.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip)
+- [`bun-windows-x64.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip)
+- [`bun-windows-x64-baseline.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip)
+- [`bun-darwin-aarch64.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-aarch64.zip)
+- [`bun-linux-aarch64.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip)
+- [`bun-darwin-x64.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip)
+- [`bun-darwin-x64-baseline.zip`](https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64-baseline.zip)
+
+The `baseline` binaries are built for older CPUs which may not support AVX2 instructions. If you run into an "Illegal Instruction" error when running Bun, try using the `baseline` binaries instead. Bun's install scripts automatically choose the correct binary for your system which helps avoid this issue. Baseline builds are slower than regular builds, so use them only if necessary.
+
+<!--
+## Native
+
+Works on macOS x64 & Silicon, Linux x64, Windows Subsystem for Linux.
+
+```sh
+$ curl -fsSL https://bun.sh/install | bash
+```
+
+Once installed, the binary can upgrade itself.
+
+```sh
+$ bun upgrade
+```
+
+Bun automatically releases an (untested) canary build on every commit to `main`. To upgrade to the latest canary build:
+
+```sh
+$ bun upgrade --canary
+```
+
+## Homebrew
+
+Works on macOS and Linux
+
+```sh
+$ brew tap oven-sh/bun
+$ brew install bun
+```
+
+Homebrew recommends using `brew upgrade <package>` to install newer versions.
+
+## Docker
+
+Works on Linux x64
+
+```sh
+# this is a comment
+$ docker pull oven/bun:edge
+this is some output
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
+$ docker run --rm --init --ulimit memlock=-1:-1 oven/bun:edge
+this is some output
+``` -->
+
+<!-- ## Completions
+
+Shell auto-completion should be configured automatically when Bun is installed!
+
+If not, run the following command. It uses `$SHELL` to determine which shell you're using and writes a completion file to the appropriate place on disk. It's automatically re-run on every `bun upgrade`.
+
+```bash
+$ bun completions
+```
+
+To write the completions to a custom location:
+
+```bash
+$ bun completions > path-to-file      # write to file
+$ bun completions /path/to/directory  # write into directory
+``` -->
+
+## Uninstall
+
+If you need to remove Bun from your system, use the following commands.
+
+{% codetabs %}
+
+```bash#macOS/Linux_(curl)
+$ rm -rf ~/.bun # for macOS, Linux, and WSL
+```
+
+```powershell#Windows
+> powershell -c ~\.bun\uninstall.ps1
+```
+
+```powershell#Scoop
+> scoop uninstall bun
+```
+
+```bash#npm
+$ npm uninstall -g bun
+```
+
+```bash#Homebrew
+$ brew uninstall bun
+```
+
+{% /codetabs %}