@depup/bun-types 1.3.11-depup.0

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`](/docs/runtime/http/server) 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/sse.mdx

@@ -0,0 +1,91 @@
+---
+title: Server-Sent Events (SSE) with Bun
+sidebarTitle: Server-Sent Events
+mode: center
+---
+
+[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) let you push a stream of text events to the browser over a single HTTP response. The client consumes them via [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
+
+In Bun, you can implement an SSE endpoint by returning a `Response` whose body is a streaming source and setting the `Content-Type` header to `text/event-stream`.
+
+<Note>
+  `Bun.serve` closes idle connections after **10 seconds** by default. A quiet SSE stream counts as idle, so the
+  examples below call `server.timeout(req, 0)` to disable the timeout for the stream. See
+  [`idleTimeout`](/docs/runtime/http/server#idletimeout) for details.
+</Note>
+
+## Using an async generator
+
+In Bun, `new Response` accepts an async generator function directly. This is usually the simplest way to write an SSE endpoint — each `yield` flushes a chunk to the client, and if the client disconnects, the generator's `finally` block runs so you can clean up.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve({
+  port: 3000,
+  routes: {
+    "/events": (req, server) => {
+      // SSE streams are often quiet between events. By default,
+      // Bun.serve closes connections after 10 seconds of inactivity.
+      // Disable the idle timeout for this request so the stream
+      // stays open indefinitely.
+      server.timeout(req, 0);
+
+      return new Response(
+        async function* () {
+          yield `data: connected at ${Date.now()}\n\n`;
+
+          // Emit a tick every 5 seconds until the client disconnects.
+          // When the client goes away, the generator is returned
+          // (cancelled) and this loop stops automatically.
+          while (true) {
+            await Bun.sleep(5000);
+            yield `data: tick ${Date.now()}\n\n`;
+          }
+        },
+        {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+          },
+        },
+      );
+    },
+  },
+});
+```
+
+## Using a `ReadableStream`
+
+If your events originate from callbacks — message brokers, timers, external pushes — rather than a linear `await` flow, a `ReadableStream` often fits better. When the client disconnects, Bun calls the stream's `cancel()` method automatically, so you can release any resources you set up in `start()`.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve({
+  port: 3000,
+  routes: {
+    "/events": (req, server) => {
+      server.timeout(req, 0);
+
+      let timer: Timer;
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(`data: connected at ${Date.now()}\n\n`);
+
+          timer = setInterval(() => {
+            controller.enqueue(`data: tick ${Date.now()}\n\n`);
+          }, 5000);
+        },
+        cancel() {
+          // Called automatically when the client disconnects.
+          clearInterval(timer);
+        },
+      });
+
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+        },
+      });
+    },
+  },
+});
+```

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()`](/docs/runtime/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()`](/docs/runtime/http/server).
+
+```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](/docs/runtime/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()`](/docs/runtime/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](/docs/pm/cli/install) for complete documentation of Bun's package manager.

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

@@ -0,0 +1,40 @@
+---
+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
+```
+
+**Note:** GitHub dependencies download via HTTP tarball when possible for faster installation.
+
+---
+
+See [Docs > Package manager](/docs/pm/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](/docs/pm/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.3" // [!code ++]
+  }
+}
+```
+
+---
+
+Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
+
+{/* prettier-ignore */}
+```json package.json icon="file-json"
+{
+  "peerDependencies": {
+    "@types/bun": "^1.3.3"
+  },
+  "peerDependenciesMeta": {
+    "@types/bun": { // [!code ++]
+      "optional": true // [!code ++]
+    } // [!code ++]
+  }
+}
+```
+
+---
+
+See [Docs > Package manager](/docs/pm/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](/docs/pm/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](/docs/pm/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"
+# You can use an environment variable here
+password = "$NPM_PASSWORD"
+```
+
+---
+
+Then assign your Azure Personal Access Token to the `NPM_PASSWORD` environment variable. Bun [automatically reads](/docs/runtime/environment-variables) `.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.
+
+```ini .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 appropriate 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](/docs/runtime/environment-variables) for more information.
+
+```toml bunfig.toml icon="settings"
+[install]
+registry = { url = "https://registry.npmjs.org", token = "$npm_token" }
+```
+
+---
+
+See [Docs > Package manager](/docs/pm/cli/install) for complete documentation of Bun's package manager.