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

package/docs/guides/ecosystem/systemd.mdx

@@ -0,0 +1,114 @@
+---
+title: Run Bun as a daemon with systemd
+sidebarTitle: "systemd with Bun"
+mode: center
+---
+
+[systemd](https://systemd.io) is an init system and service manager for Linux operating systems that manages the startup and control of system processes and services.
+
+---
+
+To run a Bun application as a daemon using **systemd** you'll need to create a _service file_ in `/lib/systemd/system/`.
+
+```sh terminal icon="terminal"
+cd /lib/systemd/system
+touch my-app.service
+```
+
+---
+
+Here is a typical service file that runs an application on system start. You can use this as a template for your own service. Replace `YOUR_USER` with the name of the user you want to run the application as. To run as `root`, replace `YOUR_USER` with `root`, though this is generally not recommended for security reasons.
+
+Refer to the [systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html) for more information on each setting.
+
+```ini my-app.service icon="file-code"
+[Unit]
+# describe the app
+Description=My App
+# start the app after the network is available
+After=network.target
+
+[Service]
+# usually you'll use 'simple'
+# one of https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=
+Type=simple
+# which user to use when starting the app
+User=YOUR_USER
+# path to your application's root directory
+WorkingDirectory=/home/YOUR_USER/path/to/my-app
+# the command to start the app
+# requires absolute paths
+ExecStart=/home/YOUR_USER/.bun/bin/bun run index.ts
+# restart policy
+# one of {no|on-success|on-failure|on-abnormal|on-watchdog|on-abort|always}
+Restart=always
+
+[Install]
+# start the app automatically
+WantedBy=multi-user.target
+```
+
+---
+
+If your application starts a webserver, note that non-`root` users are not able to listen on ports 80 or 443 by default. To permanently allow Bun to listen on these ports when executed by a non-`root` user, use the following command. This step isn't necessary when running as `root`.
+
+```bash terminal icon="terminal"
+setcap CAP_NET_BIND_SERVICE=+eip ~/.bun/bin/bun
+```
+
+---
+
+With the service file configured, you can now _enable_ the service. Once enabled, it will start automatically on reboot. This requires `sudo` permissions.
+
+```bash terminal icon="terminal"
+systemctl enable my-app
+```
+
+---
+
+To start the service without rebooting, you can manually _start_ it.
+
+```bash terminal icon="terminal"
+systemctl start my-app
+```
+
+---
+
+Check the status of your application with `systemctl status`. If you've started your app successfully, you should see something like this:
+
+```bash terminal icon="terminal"
+systemctl status my-app
+```
+
+```txt
+● my-app.service - My App
+     Loaded: loaded (/lib/systemd/system/my-app.service; enabled; preset: enabled)
+     Active: active (running) since Thu 2023-10-12 11:34:08 UTC; 1h 8min ago
+   Main PID: 309641 (bun)
+      Tasks: 3 (limit: 503)
+     Memory: 40.9M
+        CPU: 1.093s
+     CGroup: /system.slice/my-app.service
+             └─309641 /home/YOUR_USER/.bun/bin/bun run /home/YOUR_USER/application/index.ts
+```
+
+---
+
+To update the service, edit the contents of the service file, then reload the daemon.
+
+```bash terminal icon="terminal"
+systemctl daemon-reload
+```
+
+---
+
+For a complete guide on the service unit configuration, you can check [this page](https://www.freedesktop.org/software/systemd/man/systemd.service.html). Or refer to this cheatsheet of common commands:
+
+```bash terminal icon="terminal"
+systemctl daemon-reload # tell systemd that some files got changed
+systemctl enable my-app # enable the app (to allow auto-start)
+systemctl disable my-app # disable the app (turns off auto-start)
+systemctl start my-app # start the app if is stopped
+systemctl stop my-app # stop the app
+systemctl restart my-app # restart the app
+```

package/docs/guides/ecosystem/upstash.mdx

@@ -0,0 +1,87 @@
+---
+title: Bun Redis with Upstash
+sidebarTitle: Upstash with Bun
+mode: center
+---
+
+[Upstash](https://upstash.com/) is a fully managed Redis database as a service. Upstash works with the Redis® API, which means you can use Bun's native Redis client to connect to your Upstash database.
+
+<Note>TLS is enabled by default for all Upstash Redis databases.</Note>
+
+---
+
+<Steps>
+  <Step title="Create a new project">
+    Create a new project by running `bun init`:
+    
+    ```sh terminal icon="terminal"
+    bun init bun-upstash-redis
+    cd bun-upstash-redis
+    ```
+  </Step>
+  <Step title="Create an Upstash Redis database">
+    Go to the [Upstash dashboard](https://console.upstash.com/) and create a new Redis database. After completing the [getting started guide](https://upstash.com/docs/redis/overall/getstarted), you'll see your database page with connection information.
+
+    The database page displays two connection methods; HTTP and TLS. For Bun's Redis client, you need the **TLS** connection details. This URL starts with `rediss://`.
+
+    	<Frame>
+    		![Upstash Redis database page](/images/guides/upstash-1.png)
+    	</Frame>
+
+  </Step>
+  <Step title="Connect using Bun's Redis client">
+		You can connect to Upstash by setting environment variables with Bun's default `redis` client.
+
+    Set the `REDIS_URL` environment variable in your `.env` file using the Redis endpoint (not the REST URL):
+
+    ```env .env icon="settings"
+    REDIS_URL=rediss://********@********.upstash.io:6379
+    ```
+
+    Bun's Redis client reads connection information from `REDIS_URL` by default:
+
+    ```ts index.ts icon="/icons/typescript.svg"
+    import { redis } from "bun";
+
+    // Reads from process.env.REDIS_URL automatically
+    await redis.set("counter", "0"); // [!code ++]
+    ```
+
+    Alternatively, you can create a custom client using `RedisClient`:
+
+    ```ts index.ts icon="/icons/typescript.svg"
+    import { RedisClient } from "bun";
+
+    const redis = new RedisClient(process.env.REDIS_URL); // [!code ++]
+    ```
+
+  </Step>
+	<Step title="Use the Redis client">
+		You can now use the Redis client to interact with your Upstash Redis database:
+
+    	```ts index.ts icon="/icons/typescript.svg"
+    	import { redis } from "bun";
+
+    	// Get a value
+    	let counter = await redis.get("counter");
+
+    	// Set a value if it doesn't exist
+    	if (!counter) {
+    		await redis.set("counter", "0");
+    	}
+
+    	// Increment the counter
+    	await redis.incr("counter");
+
+    	// Get the updated value
+    	counter = await redis.get("counter");
+    	console.log(counter);
+    	```
+    	```txt
+    	1
+    	```
+
+    	The Redis client automatically handles connections in the background. No need to manually connect or disconnect for basic operations.
+    </Step>
+
+</Steps>

package/docs/guides/ecosystem/vite.mdx

@@ -0,0 +1,77 @@
+---
+title: Build a frontend using Vite and Bun
+sidebarTitle: "Vite with Bun"
+mode: center
+---
+
+<Note>
+  You can use Vite with Bun, but many projects get faster builds & drop hundreds of dependencies by switching to [HTML
+  imports](/bundler/html-static).
+</Note>
+
+---
+
+Vite works out of the box with Bun. Get started with one of Vite's templates.
+
+```bash terminal icon="terminal"
+bun create vite my-app
+```
+
+```txt
+✔ Select a framework: › React
+✔ Select a variant: › TypeScript + SWC
+Scaffolding project in /path/to/my-app...
+```
+
+---
+
+Then `cd` into the project directory and install dependencies.
+
+```bash terminal icon="terminal"
+cd my-app
+bun install
+```
+
+---
+
+Start the development server with the `vite` CLI using `bunx`.
+
+The `--bun` flag tells Bun to run Vite's CLI using `bun` instead of `node`; by default Bun respects Vite's `#!/usr/bin/env node` [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>).
+
+```bash terminal icon="terminal"
+bunx --bun vite
+```
+
+---
+
+To simplify this command, update the `"dev"` script in `package.json` to the following.
+
+```json package.json icon="file-json"
+  "scripts": {
+    "dev": "vite", // [!code --]
+    "dev": "bunx --bun vite", // [!code ++]
+    "build": "vite build",
+    "serve": "vite preview"
+  },
+  // ...
+```
+
+---
+
+Now you can start the development server with `bun run dev`.
+
+```bash terminal icon="terminal"
+bun run dev
+```
+
+---
+
+The following command will build your app for production.
+
+```sh terminal icon="terminal"
+bunx --bun vite build
+```
+
+---
+
+This is a stripped down guide to get you started with Vite + Bun. For more information, see the [Vite documentation](https://vitejs.dev/guide/).

package/docs/guides/html-rewriter/extract-links.mdx

@@ -0,0 +1,72 @@
+---
+title: Extract links from a webpage using HTMLRewriter
+sidebarTitle: Extract links using HTMLRewriter
+mode: center
+---
+
+## Extract links from a webpage
+
+Bun's [HTMLRewriter](https://bun.com/docs/api/html-rewriter) API can be used to efficiently extract links from HTML content. It works by chaining together CSS selectors to match the elements, text, and attributes you want to process. This is a simple example of how to extract links from a webpage. You can pass `.transform` a `Response`, `Blob`, or `string`.
+
+```ts extract-links.ts icon="/icons/typescript.svg"
+async function extractLinks(url: string) {
+  const links = new Set<string>();
+  const response = await fetch(url);
+
+  const rewriter = new HTMLRewriter().on("a[href]", {
+    element(el) {
+      const href = el.getAttribute("href");
+      if (href) {
+        links.add(href);
+      }
+    },
+  });
+
+  // Wait for the response to be processed
+  await rewriter.transform(response).blob();
+  console.log([...links]); // ["https://bun.com", "/docs", ...]
+}
+
+// Extract all links from the Bun website
+await extractLinks("https://bun.com");
+```
+
+---
+
+## Convert relative URLs to absolute
+
+When scraping websites, you often want to convert relative URLs (like `/docs`) to absolute URLs. Here's how to handle URL resolution:
+
+```ts extract-links.ts icon="/icons/typescript.svg"
+async function extractLinksFromURL(url: string) {
+  const response = await fetch(url);
+  const links = new Set<string>();
+
+  const rewriter = new HTMLRewriter().on("a[href]", {
+    element(el) {
+      const href = el.getAttribute("href");
+      if (href) {
+        // Convert relative URLs to absolute // [!code ++]
+        try {
+          // [!code ++]
+          const absoluteURL = new URL(href, url).href; // [!code ++]
+          links.add(absoluteURL); // [!code ++]
+        } catch {
+          // [!code ++]
+          links.add(href);
+        } // [!code ++]
+      }
+    },
+  });
+
+  // Wait for the response to be processed
+  await rewriter.transform(response).blob();
+  return [...links];
+}
+
+const websiteLinks = await extractLinksFromURL("https://example.com");
+```
+
+---
+
+See [Docs > API > HTMLRewriter](https://bun.com/docs/api/html-rewriter) for complete documentation on HTML transformation with Bun.

package/docs/guides/html-rewriter/extract-social-meta.mdx

@@ -0,0 +1,97 @@
+---
+title: Extract social share images and Open Graph tags
+sidebarTitle: OpenGraph tags
+mode: center
+---
+
+## Extract social share images and Open Graph tags
+
+Bun's [HTMLRewriter](https://bun.com/docs/api/html-rewriter) API can be used to efficiently extract social share images and Open Graph metadata from HTML content. This is particularly useful for building link preview features, social media cards, or web scrapers. We can use HTMLRewriter to match CSS selectors to HTML elements, text, and attributes we want to process.
+
+```ts extract-social-meta.ts icon="/icons/typescript.svg"
+interface SocialMetadata {
+  title?: string;
+  description?: string;
+  image?: string;
+  url?: string;
+  siteName?: string;
+  type?: string;
+}
+
+async function extractSocialMetadata(url: string): Promise<SocialMetadata> {
+  const metadata: SocialMetadata = {};
+  const response = await fetch(url);
+
+  const rewriter = new HTMLRewriter()
+    // Extract Open Graph meta tags
+    .on('meta[property^="og:"]', {
+      element(el) {
+        const property = el.getAttribute("property");
+        const content = el.getAttribute("content");
+        if (property && content) {
+          // Convert "og:image" to "image" etc.
+          const key = property.replace("og:", "") as keyof SocialMetadata;
+          metadata[key] = content;
+        }
+      },
+    })
+    // Extract Twitter Card meta tags as fallback
+    .on('meta[name^="twitter:"]', {
+      element(el) {
+        const name = el.getAttribute("name");
+        const content = el.getAttribute("content");
+        if (name && content) {
+          const key = name.replace("twitter:", "") as keyof SocialMetadata;
+          // Only use Twitter Card data if we don't have OG data
+          if (!metadata[key]) {
+            metadata[key] = content;
+          }
+        }
+      },
+    })
+    // Fallback to regular meta tags
+    .on('meta[name="description"]', {
+      element(el) {
+        const content = el.getAttribute("content");
+        if (content && !metadata.description) {
+          metadata.description = content;
+        }
+      },
+    })
+    // Fallback to title tag
+    .on("title", {
+      text(text) {
+        if (!metadata.title) {
+          metadata.title = text.text;
+        }
+      },
+    });
+
+  // Process the response
+  await rewriter.transform(response).blob();
+
+  // Convert relative image URLs to absolute
+  if (metadata.image && !metadata.image.startsWith("http")) {
+    try {
+      metadata.image = new URL(metadata.image, url).href;
+    } catch {
+      // Keep the original URL if parsing fails
+    }
+  }
+
+  return metadata;
+}
+```
+
+```ts Example Usage icon="/icons/typescript.svg"
+// Example usage
+const metadata = await extractSocialMetadata("https://bun.com");
+console.log(metadata);
+// {
+//   title: "Bun — A fast all-in-one JavaScript runtime",
+//   description: "Bundle, transpile, install and run JavaScript & TypeScript projects — all in Bun. Bun is a fast all-in-one JavaScript runtime & toolkit designed for speed, complete with a bundler, test runner, and Node.js-compatible package manager.",
+//   image: "https://bun.com/share.jpg",
+//   type: "website",
+//   ...
+// }
+```

package/docs/guides/http/cluster.mdx

@@ -0,0 +1,69 @@
+---
+title: Start a cluster of HTTP servers
+description: Run multiple HTTP servers concurrently via the "reusePort" option to share the same port across multiple processes
+sidebarTitle: Start a cluster of HTTP servers
+mode: center
+---
+
+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 icon="/icons/typescript.svg"
+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");
+  },
+});
+```
+
+---
+
+<Note>
+  **Linux only** &mdash; Windows and macOS ignore the `reusePort` option. This is an operating system limitation with
+  `SO_REUSEPORT`, unfortunately.
+</Note>
+
+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 icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,35 @@
+---
+title: fetch with unix domain sockets in Bun
+sidebarTitle: Fetch with unix domain sockets
+mode: center
+---
+
+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 fetch-unix.ts icon="/icons/typescript.svg"
+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 fetch-unix.ts icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,26 @@
+---
+title: Send an HTTP request using fetch
+sidebarTitle: Fetch with Bun
+mode: center
+---
+
+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 fetch.ts icon="/icons/typescript.svg"
+const response = await fetch("https://bun.com");
+const html = await response.text(); // HTML string
+```
+
+---
+
+To send a `POST` request to an API endpoint.
+
+```ts fetch.ts icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,97 @@
+---
+title: Upload files via HTTP using FormData
+sidebarTitle: Upload files via HTTP using FormData
+mode: center
+---
+
+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 icon="/icons/typescript.svg"
+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 icon="file-code"
+<!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 index.ts icon="/icons/typescript.svg"
+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 // [!code ++]
+    if (url.pathname === "/action") {
+      // [!code ++]
+      const formdata = await req.formData(); // [!code ++]
+      const name = formdata.get("name"); // [!code ++]
+      const profilePicture = formdata.get("profilePicture"); // [!code ++]
+      if (!profilePicture) throw new Error("Must upload a profile picture."); // [!code ++]
+      // write profilePicture to disk // [!code ++]
+      await Bun.write("profilePicture.png", profilePicture); // [!code ++]
+      return new Response("Success"); // [!code ++]
+    } // [!code ++]
+
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```