bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/guides/http/hot.mdx

@@ -0,0 +1,28 @@
+---
+title: Hot reload an HTTP server
+sidebarTitle: Hot reload an HTTP server
+mode: center
+---
+
+Bun supports the [`--hot`](https://bun.com/docs/runtime/hot#hot-mode) flag to run a file with hot reloading enabled. When any module or file changes, Bun re-runs the file.
+
+```sh terminal icon="terminal"
+bun --hot run index.ts
+```
+
+---
+
+Bun detects when you are running an HTTP server with `Bun.serve()`. It reloads your fetch handler when source files change, _without_ restarting the `bun` process. This makes hot reloads nearly instantaneous.
+
+<Note>
+Note that this doesn't reload the page on your browser.
+</Note>
+ 
+```ts index.ts icon="/icons/typescript.svg"
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response("Hello world");
+  },
+});
+```

package/docs/guides/http/proxy.mdx

@@ -0,0 +1,26 @@
+---
+title: Proxy HTTP requests using fetch()
+sidebarTitle: Proxy HTTP requests using fetch()
+mode: center
+---
+
+In Bun, `fetch` supports sending requests through an HTTP or HTTPS proxy. This is useful on corporate networks or when you need to ensure a request is sent through a specific IP address.
+
+```ts proxy.ts icon="/icons/typescript.svg"
+await fetch("https://example.com", {
+  // The URL of the proxy server
+  proxy: "https://usertitle:password@proxy.example.com:8080",
+});
+```
+
+---
+
+The `proxy` option is a URL string that specifies the proxy server. It can include the username and password if the proxy requires authentication. It can be `http://` or `https://`.
+
+---
+
+You can also set the `$HTTP_PROXY` or `$HTTPS_PROXY` environment variable to the proxy URL. This is useful when you want to use the same proxy for all requests.
+
+```sh terminal icon="terminal"
+HTTPS_PROXY=https://usertitle:password@proxy.example.com:8080 bun run index.ts
+```

package/docs/guides/http/server.mdx

@@ -0,0 +1,48 @@
+---
+title: Common HTTP server usage
+sidebarTitle: HTTP Server with Bun
+mode: center
+---
+
+This starts an HTTP server listening on port `3000`. It demonstrates basic routing with a number of common responses and also handles POST data from standard forms or as JSON.
+
+See [`Bun.serve`](https://bun.com/docs/api/http) for details.
+
+```ts server.ts icon="/icons/typescript.svg"
+const server = Bun.serve({
+  async fetch(req) {
+    const path = new URL(req.url).pathname;
+
+    // respond with text/html
+    if (path === "/") return new Response("Welcome to Bun!");
+
+    // redirect
+    if (path === "/abc") return Response.redirect("/source", 301);
+
+    // send back a file (in this case, *this* file)
+    if (path === "/source") return new Response(Bun.file(import.meta.path));
+
+    // respond with JSON
+    if (path === "/api") return Response.json({ some: "buns", for: "you" });
+
+    // receive JSON data to a POST request
+    if (req.method === "POST" && path === "/api/post") {
+      const data = await req.json();
+      console.log("Received JSON:", data);
+      return Response.json({ success: true, data });
+    }
+
+    // receive POST data from a form
+    if (req.method === "POST" && path === "/form") {
+      const data = await req.formData();
+      console.log(data.get("someField"));
+      return new Response("Success");
+    }
+
+    // 404s
+    return new Response("Page not found", { status: 404 });
+  },
+});
+
+console.log(`Listening on ${server.url}`);
+```

package/docs/guides/http/simple.mdx

@@ -0,0 +1,20 @@
+---
+title: Write a simple HTTP server
+sidebarTitle: Simple HTTP Server with Bun
+mode: center
+---
+
+This starts an HTTP server listening on port `3000`. It responds to all requests with a `Response` with status `200` and body `"Welcome to Bun!"`.
+
+See [`Bun.serve`](https://bun.com/docs/api/http) for details.
+
+```ts server.ts icon="/icons/typescript.svg"
+const server = Bun.serve({
+  port: 3000,
+  fetch(request) {
+    return new Response("Welcome to Bun!");
+  },
+});
+
+console.log(`Listening on ${server.url}`);
+```

package/docs/guides/http/stream-file.mdx

@@ -0,0 +1,50 @@
+---
+title: Stream a file as an HTTP Response
+sidebarTitle: Stream file response
+mode: center
+---
+
+This snippet reads a file from disk using [`Bun.file()`](https://bun.com/docs/api/file-io#reading-files-bun-file). This returns a `BunFile` instance, which can be passed directly into the `new Response` constructor.
+
+```ts server.ts icon="/icons/typescript.svg"
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
+const resp = new Response(file);
+```
+
+---
+
+The `Content-Type` is read from the file and automatically set on the `Response`.
+
+```ts server.ts icon="/icons/typescript.svg"
+new Response(Bun.file("./package.json")).headers.get("Content-Type");
+// => application/json;charset=utf-8
+
+new Response(Bun.file("./test.txt")).headers.get("Content-Type");
+// => text/plain;charset=utf-8
+
+new Response(Bun.file("./index.tsx")).headers.get("Content-Type");
+// => text/javascript;charset=utf-8
+
+new Response(Bun.file("./img.png")).headers.get("Content-Type");
+// => image/png
+```
+
+---
+
+Putting it all together with [`Bun.serve()`](https://bun.com/docs/api/http#bun-serve).
+
+```ts server.ts icon="/icons/typescript.svg"
+// static file server
+Bun.serve({
+  async fetch(req) {
+    const path = new URL(req.url).pathname;
+    const file = Bun.file(path);
+    return new Response(file);
+  },
+});
+```
+
+---
+
+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/http/stream-iterator.mdx

@@ -0,0 +1,49 @@
+---
+title: Streaming HTTP Server with Async Iterators
+sidebarTitle: Stream with iterators
+mode: center
+---
+
+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 stream-iterator.ts icon="/icons/typescript.svg"
+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 stream-iterator.ts icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,22 @@
+---
+title: Streaming HTTP Server with Node.js Streams
+sidebarTitle: Stream with Node.js
+mode: center
+---
+
+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 server.ts icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,32 @@
+---
+title: Configure TLS on an HTTP server
+sidebarTitle: Configure TLS
+mode: center
+---
+
+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.com/docs/api/file-io#reading-files-bun-file) to read the contents.
+
+```ts server.ts icon="/icons/typescript.svg"
+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 server.ts icon="/icons/typescript.svg"
+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/index.mdx

@@ -0,0 +1,10 @@
+---
+title: Guides
+description: A collection of code samples and walkthroughs for performing common tasks with Bun.
+contextual: false
+mode: center
+---
+
+import { GuidesList } from "/snippets/guides.jsx";
+
+<GuidesList />

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

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

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

@@ -0,0 +1,38 @@
+---
+title: Add a Git dependency
+sidebarTitle: Add a Git dependency
+mode: center
+---
+
+Bun supports directly adding GitHub repositories as dependencies of your project.
+
+```sh terminal icon="terminal"
+bun add github:lodash/lodash
+```
+
+---
+
+This will add the following line to your `package.json`:
+
+```json package.json icon="file-json"
+{
+  "dependencies": {
+    "lodash": "github:lodash/lodash"
+  }
+}
+```
+
+---
+
+Bun supports a number of protocols for specifying Git dependencies.
+
+```sh terminal icon="terminal"
+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.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,27 @@
+---
+title: Add an optional dependency
+sidebarTitle: Add an optional dependency
+mode: center
+---
+
+To add an npm package as an optional dependency, use the `--optional` flag.
+
+```sh terminal icon="terminal"
+bun add zod --optional
+```
+
+---
+
+This will add the package to `optionalDependencies` in `package.json`.
+
+```json package.json icon="file-json"
+{
+  "optionalDependencies": {
+    "zod": "^3.0.0" // [!code ++]
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,45 @@
+---
+title: Add a peer dependency
+sidebarTitle: Add a peer dependency
+mode: center
+---
+
+To add an npm package as a peer dependency, use the `--peer` flag.
+
+```sh terminal icon="terminal"
+bun add @types/bun --peer
+```
+
+---
+
+This will add the package to `peerDependencies` in `package.json`.
+
+```json package.json icon="file-json"
+{
+  "peerDependencies": {
+    "@types/bun": "^1.3.1" // [!code ++]
+  }
+}
+```
+
+---
+
+Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
+
+```json package.json icon="file-json"
+{
+  "peerDependencies": {
+    "@types/bun": "^1.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@types/bun": {
+      // [!code ++]
+      "optional": true // [!code ++]
+    } // [!code ++]
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,35 @@
+---
+title: Add a tarball dependency
+sidebarTitle: Add a tarball dependency
+mode: center
+---
+
+Bun's package manager can install any publicly available tarball URL as a dependency of your project.
+
+```sh terminal icon="terminal"
+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 package.json icon="file-json"
+{
+  "dependencies": {
+    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz" // [!code ++]
+  }
+}
+```
+
+---
+
+The package `"zod"` can now be imported as usual.
+
+```ts
+import { z } from "zod";
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/add.mdx

@@ -0,0 +1,44 @@
+---
+title: Add a dependency
+sidebarTitle: Add a dependency
+mode: center
+---
+
+To add an npm package as a dependency, use `bun add`.
+
+```sh terminal icon="terminal"
+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 package.json icon="file-json"
+{
+  "dependencies": {
+    "zod": "^3.0.0" // [!code ++]
+  }
+}
+```
+
+---
+
+To "pin" to an exact 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 terminal icon="terminal"
+bun add zod --exact
+```
+
+---
+
+To specify an exact version or a tag:
+
+```sh terminal icon="terminal"
+bun add zod@3.0.0
+bun add zod@next
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,76 @@
+---
+title: Using bun install with an Azure Artifacts npm registry
+sidebarTitle: Azure Artifacts with Bun
+mode: center
+---
+
+<Note>
+  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.
+</Note>
+
+[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 icon="settings"
+[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.com/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 icon="settings"
+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 terminal icon="terminal"
+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.
+
+<Note>**Tip** — If it ends with `==`, it probably is base64 encoded.</Note>
+
+---
+
+To decode a base64-encoded password, open your browser console and run:
+
+```js browser icon="computer"
+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 terminal icon="terminal"
+echo "base64-encoded-password" | base64 --decode
+```

package/docs/guides/install/cicd.mdx

@@ -0,0 +1,43 @@
+---
+title: Install dependencies with Bun in GitHub Actions
+sidebarTitle: Install Bun in GitHub Actions
+mode: center
+---
+
+Use the official [`setup-bun`](https://github.com/oven-sh/setup-bun) GitHub Action to install `bun` in your GitHub Actions runner.
+
+```yaml workflow.yml icon="file-code"
+title: my-workflow
+jobs:
+  my-job:
+    title: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2 // [!code ++]
+
+      # run any `bun` or `bunx` command
+      - run: bun install // [!code ++]
+```
+
+---
+
+To specify a version of Bun to install:
+
+```yaml workflow.yml icon="file-code"
+title: my-workflow
+jobs:
+  my-job:
+    title: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: oven-sh/setup-bun@v2
+         with: # [!code ++]
+          version: "latest" # or "canary" # [!code ++]
+```
+
+---
+
+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.mdx

@@ -0,0 +1,32 @@
+---
+title: Override the default npm registry for bun install
+sidebarTitle: Override the default npm registry
+mode: center
+---
+
+The default registry is `registry.npmjs.org`. This can be globally configured in `bunfig.toml`.
+
+```toml bunfig.toml icon="settings"
+[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://usertitle: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.com/docs/runtime/env) for more information.
+
+```toml bunfig.toml icon="settings"
+[install]
+registry = { url = "https://registry.npmjs.org", token = "$npm_token" }
+```
+
+---
+
+See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.