bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/http/stream-iterator.md

@@ -0,0 +1,47 @@
+---
+name: Streaming HTTP Server with Async Iterators
+---
+
+In Bun, [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects can accept an async generator function as their body. This allows you to stream data to the client as it becomes available, rather than waiting for the entire response to be ready.
+
+```ts
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response(
+      // An async generator function
+      async function* () {
+        yield "Hello, ";
+        await Bun.sleep(100);
+        yield "world!";
+
+        // you can also yield a TypedArray or Buffer
+        yield new Uint8Array(["\n".charCodeAt(0)]);
+      },
+      { headers: { "Content-Type": "text/plain" } },
+    );
+  },
+});
+```
+
+---
+
+You can pass any async iterable directly to `Response`:
+
+```ts
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response(
+      {
+        [Symbol.asyncIterator]: async function* () {
+          yield "Hello, ";
+          await Bun.sleep(100);
+          yield "world!";
+        },
+      },
+      { headers: { "Content-Type": "text/plain" } },
+    );
+  },
+});
+```

package/docs/guides/http/stream-node-streams-in-bun.md

@@ -0,0 +1,20 @@
+---
+name: Streaming HTTP Server with Node.js Streams
+---
+
+In Bun, [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects can accept a Node.js [`Readable`](https://nodejs.org/api/stream.html#stream_readable_streams).
+
+This works because Bun's `Response` object allows any async iterable as its body. Node.js streams are async iterables, so you can pass them directly to `Response`.
+
+```ts
+import { Readable } from "stream";
+import { serve } from "bun";
+serve({
+  port: 3000,
+  fetch(req) {
+    return new Response(Readable.from(["Hello, ", "world!"]), {
+      headers: { "Content-Type": "text/plain" },
+    });
+  },
+});
+```

package/docs/guides/http/tls.md

@@ -0,0 +1,30 @@
+---
+name: Configure TLS on an HTTP server
+---
+
+Set the `tls` key to configure TLS. Both `key` and `cert` are required. The `key` should be the contents of your private key; `cert` should be the contents of your issued certificate. Use [`Bun.file()`](https://bun.sh/docs/api/file-io#reading-files-bun-file) to read the contents.
+
+```ts
+const server = Bun.serve({
+  fetch: request => new Response("Welcome to Bun!"),
+  tls: {
+    cert: Bun.file("cert.pem"),
+    key: Bun.file("key.pem"),
+  },
+});
+```
+
+---
+
+By default Bun trusts the default Mozilla-curated list of well-known root CAs. To override this list, pass an array of certificates as `ca`.
+
+```ts
+const server = Bun.serve({
+  fetch: request => new Response("Welcome to Bun!"),
+  tls: {
+    cert: Bun.file("cert.pem"),
+    key: Bun.file("key.pem"),
+    ca: [Bun.file("ca1.pem"), Bun.file("ca2.pem")],
+  },
+});
+```

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

@@ -0,0 +1,26 @@
+---
+name: Add a development dependency
+---
+
+To add an npm package as a development dependency, use `bun add --development`.
+
+```sh
+$ bun add zod --dev
+$ bun add zod -d # shorthand
+```
+
+---
+
+This will add the package to `devDependencies` in `package.json`.
+
+```json-diff
+{
+  "devDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,36 @@
+---
+name: Add a Git dependency
+---
+
+Bun supports directly adding GitHub repositories as dependencies of your project.
+
+```sh
+$ bun add github:lodash/lodash
+```
+
+---
+
+This will add the following line to your `package.json`:
+
+```json-diff#package.json
+{
+  "dependencies": {
++   "lodash": "github:lodash/lodash"
+  }
+}
+```
+
+---
+
+Bun supports a number of protocols for specifying Git dependencies.
+
+```sh
+$ bun add git+https://github.com/lodash/lodash.git
+$ bun add git+ssh://github.com/lodash/lodash.git#4.17.21
+$ bun add git@github.com:lodash/lodash.git
+$ bun add github:colinhacks/zod
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,25 @@
+---
+name: Add an optional dependency
+---
+
+To add an npm package as a peer dependency, use the `--optional` flag.
+
+```sh
+$ bun add zod --optional
+```
+
+---
+
+This will add the package to `optionalDependencies` in `package.json`.
+
+```json-diff
+{
+  "optionalDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,17 @@
+---
+name: Add a peer dependency
+---
+
+To add an npm package as a peer dependency, directly modify the `peerDependencies` object in your package.json. Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
+
+```json-diff
+{
+  "peerDependencies": {
++   "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,33 @@
+---
+name: Add a tarball dependency
+---
+
+Bun's package manager can install any publicly available tarball URL as a dependency of your project.
+
+```sh
+$ bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
+```
+
+---
+
+Running this command will download, extract, and install the tarball to your project's `node_modules` directory. It will also add the following line to your `package.json`:
+
+```json-diff#package.json
+{
+  "dependencies": {
++   "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
+  }
+}
+```
+
+---
+
+The package `"zod"` can now be imported as usual.
+
+```ts
+import { z } from "zod";
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/add.md

@@ -0,0 +1,42 @@
+---
+name: Add a dependency
+---
+
+To add an npm package as a dependency, use `bun add`.
+
+```sh
+$ bun add zod
+```
+
+---
+
+This will add the package to `dependencies` in `package.json`. By default, the `^` range specifier will be used, to indicate that any future minor or patch versions are acceptable.
+
+```json-diff
+{
+  "dependencies": {
++     "zod": "^3.0.0"
+  }
+}
+```
+
+---
+
+To "pin" to the `latest` version of the package, use `--exact`. This will add the package to `dependencies` without the `^`, pinning your project to the exact version you installed.
+
+```sh
+$ bun add zod --exact
+```
+
+---
+
+To specify an exact version or a tag:
+
+```sh
+$ bun add zod@3.0.0
+$ bun add zod@next
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/azure-artifacts.md

@@ -0,0 +1,73 @@
+---
+name: Using bun install with an Azure Artifacts npm registry
+---
+
+{% callout %}
+In [Azure Artifact's](https://learn.microsoft.com/en-us/azure/devops/artifacts/npm/npmrc?view=azure-devops&tabs=windows%2Cclassic) instructions for `.npmrc`, they say to base64 encode the password. Do not do this for `bun install`. Bun will automatically base64 encode the password for you if needed.
+{% /callout %}
+
+[Azure Artifacts](https://azure.microsoft.com/en-us/products/devops/artifacts) is a package management system for Azure DevOps. It allows you to host your own private npm registry, npm packages, and other types of packages as well.
+
+---
+
+### Configure with bunfig.toml
+
+---
+
+To use it with `bun install`, add a `bunfig.toml` file to your project with the following contents. Make sure to replace `my-azure-artifacts-user` with your Azure Artifacts username, such as `jarred1234`.
+
+```toml#bunfig.toml
+[install.registry]
+url = "https://pkgs.dev.azure.com/my-azure-artifacts-user/_packaging/my-azure-artifacts-user/npm/registry"
+username = "my-azure-artifacts-user"
+# Bun v1.0.3+ supports using an environment variable here
+password = "$NPM_PASSWORD"
+```
+
+---
+
+Then assign your Azure Personal Access Token to the `NPM_PASSWORD` environment variable. Bun [automatically reads](https://bun.sh/docs/runtime/env) `.env` files, so create a file called `.env` in your project root. There is no need to base-64 encode this token! Bun will do this for you.
+
+```txt#.env
+NPM_PASSWORD=<paste token here>
+```
+
+---
+
+### Configure with environment variables
+
+---
+
+To configure Azure Artifacts without `bunfig.toml`, you can set the `NPM_CONFIG_REGISTRY` environment variable. The URL should include `:username` and `:_password` as query parameters. Replace `<USERNAME>` and `<PASSWORD>` with the apprropriate values.
+
+```bash#shell
+NPM_CONFIG_REGISTRY=https://pkgs.dev.azure.com/my-azure-artifacts-user/_packaging/my-azure-artifacts-user/npm/registry/:username=<USERNAME>:_password=<PASSWORD>
+```
+
+---
+
+### Don't base64 encode the password
+
+---
+
+In [Azure Artifact's](https://learn.microsoft.com/en-us/azure/devops/artifacts/npm/npmrc?view=azure-devops&tabs=windows%2Cclassic) instructions for `.npmrc`, they say to base64 encode the password. Do not do this for `bun install`. Bun will automatically base64 encode the password for you if needed.
+
+{% callout %}
+**Tip** — If it ends with `==`, it probably is base64 encoded.
+{% /callout %}
+
+---
+
+To decode a base64-encoded password, open your browser console and run:
+
+```js
+atob("<base64-encoded password>");
+```
+
+---
+
+Alternatively, use the `base64` command line tool, but doing so means it may be saved in your terminal history which is not recommended:
+
+```bash
+echo "base64-encoded-password" | base64 --decode
+```

package/docs/guides/install/cicd.md

@@ -0,0 +1,41 @@
+---
+name: Install dependencies with Bun in GitHub Actions
+---
+
+Use the official [`setup-bun`](https://github.com/oven-sh/setup-bun) GitHub Action to install `bun` in your GitHub Actions runner.
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: actions/checkout@v4
++     - uses: oven-sh/setup-bun@v1
+
+      # run any `bun` or `bunx` command
++     - run: bun install
+```
+
+---
+
+To specify a version of Bun to install:
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: oven-sh/setup-bun@v1
++       with:
++         version: 0.7.0 # or "canary"
+```
+
+---
+
+Refer to the [README.md](https://github.com/oven-sh/setup-bun) for complete documentation of the `setup-bun` GitHub Action.

package/docs/guides/install/custom-registry.md

@@ -0,0 +1,30 @@
+---
+name: Override the default npm registry for bun install
+---
+
+The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`.
+
+```toml#bunfig.toml
+[install]
+# set default registry as a string
+registry = "https://registry.npmjs.org"
+
+# if needed, set a token
+registry = { url = "https://registry.npmjs.org", token = "123456" }
+
+# if needed, set a username/password
+registry = "https://username:password@registry.npmjs.org"
+```
+
+---
+
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](https://bun.sh/docs/runtime/env) for more information.
+
+```toml#bunfig.toml
+[install]
+registry = { url = "https://registry.npmjs.org", token = "$npm_token" }
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,214 @@
+---
+name: Migrate from npm install to bun install
+---
+
+`bun install` is a Node.js compatible npm client designed to be an incredibly fast successor to npm.
+
+We've put a lot of work into making sure that the migration path from `npm install` to `bun install` is as easy as running `bun install` instead of `npm install`.
+
+- **Designed for Node.js & Bun**: `bun install` installs a Node.js compatible `node_modules` folder. You can use it in place of `npm install` for Node.js projects without any code changes and without using Bun's runtime.
+- **Automatically converts `package-lock.json`** to bun's `bun.lockb` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing.
+- **`.npmrc` compatible**: bun install reads npm registry configuration from npm's `.npmrc`, so you can use the same configuration for both npm and Bun.
+- **Hardlinks**: On Windows and Linux, `bun install` uses hardlinks to conserve disk space and install times.
+
+```bash
+# It only takes one command to migrate
+$ bun i
+
+# To add dependencies:
+$ bun i @types/bun
+
+# To add devDependencies:
+$ bun i -d @types/bun
+
+# To remove a dependency:
+$ bun rm @types/bun
+```
+
+---
+
+## Run package.json scripts faster
+
+Run scripts from package.json, executables from `node_modules/.bin` (sort of like `npx`), and JavaScript/TypeScript files (just like `node`) - all from a single simple command.
+
+| NPM                | Bun              |
+| ------------------ | ---------------- |
+| `npm run <script>` | `bun <script>`   |
+| `npm exec <bin>`   | `bun <bin>`      |
+| `node <file>`      | `bun <file>`     |
+| `npx <package>`    | `bunx <package>` |
+
+When you use `bun run <executable>`, it will choose the locally-installed executable
+
+```sh
+# Run a package.json script:
+$ bun my-script
+$ bun run my-script
+
+# Run an executable in node_modules/.bin:
+$ bun my-executable # such as tsc, esbuild, etc.
+$ bun run my-executable
+
+# Run a JavaScript/TypeScript file:
+$ bun ./index.ts
+```
+
+---
+
+## Workspaces? Yes.
+
+`bun install` supports workspaces similarly to npm, with more features.
+
+In package.json, you can set `"workspaces"` to an array of relative paths.
+
+```json#package.json
+{
+  "name": "my-app",
+  "workspaces": ["packages/*", "apps/*"]
+}
+```
+
+---
+
+### Filter scripts by workspace name
+
+In Bun, the `--filter` flag accepts a glob pattern, and will run the command concurrently for all workspace packages with a `name` that matches the pattern, respecting dependency order.
+
+```sh
+$ bun --filter 'lib-*' my-script
+# instead of:
+# npm run --workspace lib-foo --workspace lib-bar my-script
+```
+
+---
+
+## Update dependencies
+
+To update a dependency, you can use `bun update <package>`. This will update the dependency to the latest version that satisfies the semver range specified in package.json.
+
+```sh
+# Update a single dependency
+$ bun update @types/bun
+
+# Update all dependencies
+$ bun update
+
+# Ignore semver, update to the latest version
+$ bun update @types/bun --latest
+
+# Update a dependency to a specific version
+$ bun update @types/bun@1.1.10
+
+# Update all dependencies to the latest versions
+$ bun update --latest
+```
+
+---
+
+### View outdated dependencies
+
+To view outdated dependencies, run `bun outdated`. This is like `npm outdated` but with more compact output.
+
+```sh
+$ bun outdated
+┌────────────────────────────────────────┬─────────┬────────┬────────┐
+│ Package                                │ Current │ Update │ Latest │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @types/bun (dev)                       │ 1.1.6   │ 1.1.10 │ 1.1.10 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @types/react (dev)                     │ 18.3.3  │ 18.3.8 │ 18.3.8 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @typescript-eslint/eslint-plugin (dev) │ 7.16.1  │ 7.18.0 │ 8.6.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @typescript-eslint/parser (dev)        │ 7.16.1  │ 7.18.0 │ 8.6.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ @vscode/debugadapter (dev)             │ 1.66.0  │ 1.67.0 │ 1.67.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ esbuild (dev)                          │ 0.21.5  │ 0.21.5 │ 0.24.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ eslint (dev)                           │ 9.7.0   │ 9.11.0 │ 9.11.0 │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ mitata (dev)                           │ 0.1.11  │ 0.1.14 │ 1.0.2  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ prettier-plugin-organize-imports (dev) │ 4.0.0   │ 4.1.0  │ 4.1.0  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ source-map-js (dev)                    │ 1.2.0   │ 1.2.1  │ 1.2.1  │
+├────────────────────────────────────────┼─────────┼────────┼────────┤
+│ typescript (dev)                       │ 5.5.3   │ 5.6.2  │ 5.6.2  │
+└────────────────────────────────────────┴─────────┴────────┴────────┘
+```
+
+---
+
+## List installed packages
+
+To list installed packages, you can use `bun pm ls`. This will list all the packages that are installed in the `node_modules` folder using Bun's lockfile as the source of truth. You can pass the `-a` flag to list all installed packages, including transitive dependencies.
+
+```sh
+# List top-level installed packages:
+$ bun pm ls
+my-pkg node_modules (781)
+├── @types/node@20.16.5
+├── @types/react@18.3.8
+├── @types/react-dom@18.3.0
+├── eslint@8.57.1
+├── eslint-config-next@14.2.8
+
+# List all installed packages:
+$ bun pm ls -a
+my-pkg node_modules
+├── @alloc/quick-lru@5.2.0
+├── @isaacs/cliui@8.0.2
+│   └── strip-ansi@7.1.0
+│       └── ansi-regex@6.1.0
+├── @jridgewell/gen-mapping@0.3.5
+├── @jridgewell/resolve-uri@3.1.2
+...
+```
+
+---
+
+## Create a package tarball
+
+To create a package tarball, you can use `bun pm pack`. This will create a tarball of the package in the current directory.
+
+```sh
+# Create a tarball
+$ bun pm pack
+
+Total files: 46
+Shasum: 2ee19b6f0c6b001358449ca0eadead703f326216
+Integrity: sha512-ZV0lzWTEkGAMz[...]Gl4f8lA9sl97g==
+Unpacked size: 0.41MB
+Packed size: 117.50KB
+```
+
+---
+
+## Shebang
+
+If the package references `node` in the `#!/usr/bin/env node` shebang, `bun run` will by default respect it and use the system's `node` executable. You can force it to use Bun's `node` by passing `--bun` to `bun run`.
+
+When you pass `--bun` to `bun run`, we create a symlink to the locally-installed Bun executable named `"node"` in a temporary directory and add that to your `PATH` for the duration of the script's execution.
+
+```sh
+# Force using Bun's runtime instead of node
+$ bun --bun my-script
+
+# This also works:
+$ bun run --bun my-script
+```
+
+---
+
+## Global installs
+
+You can install packages globally using `bun i -g <package>`. This will install into a `.bun/install/global/node_modules` folder inside your home directory by default.
+
+```sh
+# Install a package globally
+$ bun i -g eslint
+
+# Run a globally-installed package without the `bun run` prefix
+$ eslint --init
+```

package/docs/guides/install/git-diff-bun-lockfile.md

@@ -0,0 +1,38 @@
+---
+name: Configure git to diff Bun's lockb lockfile
+---
+
+To teach `git` how to generate a human-readable diff of Bun's binary lockfile format (`.lockb`), add the following to your local or global `.gitattributes` file:
+
+```js
+*.lockb binary diff=lockb
+```
+
+---
+
+Then add the following to you local git config with:
+
+```sh
+$ git config diff.lockb.textconv bun
+$ git config diff.lockb.binary true
+```
+
+---
+
+To globally configure git to diff Bun's lockfile, add the following to your global git config with:
+
+```sh
+$ git config --global diff.lockb.textconv bun
+$ git config --global diff.lockb.binary true
+```
+
+---
+
+## How this works
+
+Why this works:
+
+- `textconv` tells git to run bun on the file before diffing
+- `binary` tells git to treat the file as binary (so it doesn't try to diff it line-by-line)
+
+In Bun, you can execute Bun's lockfile (`bun ./bun.lockb`) to generate a human-readable version of the lockfile and `git diff` can then use that to generate a human-readable diff.