bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/guides/http/cluster.md

@@ -1,66 +0,0 @@
----
-name: Start a cluster of HTTP servers
-description: Run multiple HTTP servers concurrently via the "reusePort" option to share the same port across multiple processes
----
-
-To run multiple HTTP servers concurrently, use the `reusePort` option in `Bun.serve()` which shares the same port across multiple processes.
-
-This automatically load balances incoming requests across multiple instances of Bun.
-
-```ts#server.ts
-import { serve } from "bun";
-
-const id = Math.random().toString(36).slice(2);
-
-serve({
-  port: process.env.PORT || 8080,
-  development: false,
-
-  // Share the same port across multiple processes
-  // This is the important part!
-  reusePort: true,
-
-  async fetch(request) {
-    return new Response("Hello from Bun #" + id + "!\n");
-  }
-});
-```
-
----
-
-{% callout %}
-**Linux only** — Windows and macOS ignore the `reusePort` option. This is an operating system limitation with `SO_REUSEPORT`, unfortunately.
-{% /callout %}
-
-After saving the file, start your servers on the same port.
-
-Under the hood, this uses the Linux `SO_REUSEPORT` and `SO_REUSEADDR` socket options to ensure fair load balancing across multiple processes. [Learn more about `SO_REUSEPORT` and `SO_REUSEADDR`](https://lwn.net/Articles/542629/)
-
-```ts#cluster.ts
-import { spawn } from "bun";
-
-const cpus = navigator.hardwareConcurrency; // Number of CPU cores
-const buns = new Array(cpus);
-
-for (let i = 0; i < cpus; i++) {
-  buns[i] = spawn({
-    cmd: ["bun", "./server.ts"],
-    stdout: "inherit",
-    stderr: "inherit",
-    stdin: "inherit",
-  });
-}
-
-function kill() {
-  for (const bun of buns) {
-    bun.kill();
-  }
-}
-
-process.on("SIGINT", kill);
-process.on("exit", kill);
-```
-
----
-
-Bun has also implemented the `node:cluster` module, but this is a faster, simple, and limited alternative.

package/docs/guides/http/fetch-unix.md

@@ -1,33 +0,0 @@
----
-name: fetch with unix domain sockets in Bun
----
-
-In Bun, the `unix` option in `fetch()` lets you send HTTP requests over a [unix domain socket](https://en.wikipedia.org/wiki/Unix_domain_socket).
-
-```ts
-const unix = "/var/run/docker.sock";
-
-const response = await fetch("http://localhost/info", { unix });
-
-const body = await response.json();
-console.log(body); // { ... }
-```
-
----
-
-The `unix` option is a string that specifies the local file path to a unix domain socket. The `fetch()` function will use the socket to send the request to the server instead of using a TCP network connection. `https` is also supported by using the `https://` protocol in the URL instead of `http://`.
-
-To send a `POST` request to an API endpoint over a unix domain socket:
-
-```ts
-const response = await fetch("https://hostname/a/path", {
-  unix: "/var/run/path/to/unix.sock",
-  method: "POST",
-  body: JSON.stringify({ message: "Hello from Bun!" }),
-  headers: {
-    "Content-Type": "application/json",
-  },
-});
-
-const body = await response.json();
-```

package/docs/guides/http/fetch.md

@@ -1,24 +0,0 @@
----
-name: Send an HTTP request using fetch
----
-
-Bun implements the Web-standard [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API for sending HTTP requests. To send a simple `GET` request to a URL:
-
-```ts
-const response = await fetch("https://bun.com");
-const html = await response.text(); // HTML string
-```
-
----
-
-To send a `POST` request to an API endpoint.
-
-```ts
-const response = await fetch("https://bun.com/api", {
-  method: "POST",
-  body: JSON.stringify({ message: "Hello from Bun!" }),
-  headers: { "Content-Type": "application/json" },
-});
-
-const body = await response.json();
-```

package/docs/guides/http/file-uploads.md

@@ -1,94 +0,0 @@
----
-name: Upload files via HTTP using FormData
----
-
-To upload files via HTTP with Bun, use the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API. Let's start with a HTTP server that serves a simple HTML web form.
-
-```ts#index.ts
-const server = Bun.serve({
-  port: 4000,
-  async fetch(req) {
-    const url = new URL(req.url);
-
-    // return index.html for root path
-    if (url.pathname === "/")
-      return new Response(Bun.file("index.html"), {
-        headers: {
-          "Content-Type": "text/html",
-        },
-      });
-
-    return new Response("Not Found", { status: 404 });
-  },
-});
-
-console.log(`Listening on http://localhost:${server.port}`);
-```
-
----
-
-We can define our HTML form in another file, `index.html`.
-
-```html#index.html
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <title>Form</title>
-  </head>
-  <body>
-    <form action="/action" method="post" enctype="multipart/form-data">
-      <input type="text" name="name" placeholder="Name" />
-      <input type="file" name="profilePicture" />
-      <input type="submit" value="Submit" />
-    </form>
-  </body>
-</html>
-```
-
----
-
-At this point, we can run the server and visit [`localhost:4000`](http://localhost:4000) to see our form.
-
-```bash
-$ bun run index.ts
-Listening on http://localhost:4000
-```
-
----
-
-Our form will send a `POST` request to the `/action` endpoint with the form data. Let's handle that request in our server.
-
-First we use the [`.formData()`](https://developer.mozilla.org/en-US/docs/Web/API/Request/formData) method on the incoming `Request` to asynchronously parse its contents to a `FormData` instance. Then we can use the [`.get()`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/get) method to extract the value of the `name` and `profilePicture` fields. Here `name` corresponds to a `string` and `profilePicture` is a `Blob`.
-
-Finally, we write the `Blob` to disk using [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).
-
-```ts-diff#index.ts
-const server = Bun.serve({
-  port: 4000,
-  async fetch(req) {
-    const url = new URL(req.url);
-
-    // return index.html for root path
-    if (url.pathname === "/")
-      return new Response(Bun.file("index.html"), {
-        headers: {
-          "Content-Type": "text/html",
-        },
-      });
-
-+   // parse formdata at /action
-+   if (url.pathname === '/action') {
-+     const formdata = await req.formData();
-+     const name = formdata.get('name');
-+     const profilePicture = formdata.get('profilePicture');
-+     if (!profilePicture) throw new Error('Must upload a profile picture.');
-+     // write profilePicture to disk
-+     await Bun.write('profilePicture.png', profilePicture);
-+     return new Response("Success");
-+   }
-
-    return new Response("Not Found", { status: 404 });
-  },
-});
-```

package/docs/guides/http/hot.md

@@ -1,26 +0,0 @@
----
-name: Hot reload an HTTP server
----
-
-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
-$ 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.
-
-{% callout %}
-Note that this doesn't reload the page on your browser.
-{% /callout %}
-
-```ts
-Bun.serve({
-  port: 3000,
-  fetch(req) {
-    return new Response("Hello world");
-  },
-});
-```

package/docs/guides/http/proxy.md

@@ -1,24 +0,0 @@
----
-name: Proxy HTTP requests using fetch()
----
-
-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
-await fetch("https://example.com", {
-  // The URL of the proxy server
-  proxy: "https://username: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
-HTTPS_PROXY=https://username:password@proxy.example.com:8080 bun run index.ts
-```

package/docs/guides/http/server.md

@@ -1,46 +0,0 @@
----
-name: Common HTTP server usage
----
-
-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
-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.md

@@ -1,18 +0,0 @@
----
-name: Write a simple HTTP server
----
-
-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
-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.md

@@ -1,48 +0,0 @@
----
-name: Stream a file as an HTTP Response
----
-
-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
-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
-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
-// 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.md

@@ -1,47 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,30 +0,0 @@
----
-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.com/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

@@ -1,26 +0,0 @@
----
-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.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -1,36 +0,0 @@
----
-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.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -1,25 +0,0 @@
----
-name: Add an optional dependency
----
-
-To add an npm package as an optional 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.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -1,43 +0,0 @@
----
-name: Add a peer dependency
----
-
-To add an npm package as a peer dependency, use the `--peer` flag.
-
-```sh
-$ bun add @types/bun --peer
-```
-
----
-
-This will add the package to `peerDependencies` in `package.json`.
-
-```json-diff
-{
-  "peerDependencies": {
-+   "@types/bun": "^1.3.2-canary.20251104T140728"
-  }
-}
-```
-
----
-
-Running `bun install` will install peer dependencies by default, unless marked optional in `peerDependenciesMeta`.
-
-```json-diff
-{
-  "peerDependencies": {
-    "@types/bun": "^1.3.2-canary.20251104T140728"
-  },
-  "peerDependenciesMeta": {
-+   "@types/bun": {
-+     "optional": true
-+   }
-  }
-
-}
-```
-
----
-
-See [Docs > Package manager](https://bun.com/docs/cli/install) for complete documentation of Bun's package manager.

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

@@ -1,33 +0,0 @@
----
-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.com/docs/cli/install) for complete documentation of Bun's package manager.