bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/guides/ecosystem/{sveltekit.md → sveltekit.mdx}

@@ -1,11 +1,16 @@
 ---
-name: Build an app with SvelteKit and Bun
+title: Build an app with SvelteKit and Bun
+sidebarTitle: "SvelteKit with Bun"
+mode: center
 ---
 
 Use `sv create my-app` to create a SvelteKit project with SvelteKit CLI. Answer the prompts to select a template and set up your development environment.
 
-```sh
-$ bunx sv create my-app
+```sh terminal icon="terminal"
+bunx sv create my-app
+```
+
+```txt
 ┌  Welcome to the Svelte CLI! (v0.5.7)
 │
 ◇  Which template would you like?
@@ -47,9 +52,12 @@ Then start the development server with `bun --bun run dev`.
 
 To run the dev server with Node.js instead of Bun, you can omit the `--bun` flag.
 
-```sh
-$ cd my-app
-$ bun --bun run dev
+```sh terminal icon="terminal"
+cd my-app
+bun --bun run dev
+```
+
+```txt
   $ vite dev
   Forced re-optimization of dependencies
 
@@ -64,7 +72,9 @@ $ bun --bun run dev
 
 Visit [http://localhost:5173](http://localhost:5173/) in a browser to see the template app.
 
-{% image src="https://github.com/oven-sh/bun/assets/3084745/7c76eae8-78f9-44fa-9f15-1bd3ca1a47c0" /%}
+<Frame>
+  ![SvelteKit app running](https://github.com/oven-sh/bun/assets/3084745/7c76eae8-78f9-44fa-9f15-1bd3ca1a47c0)
+</Frame>
 
 ---
 
@@ -78,34 +88,37 @@ To build for production, you'll need to add the right SvelteKit adapter. Current
 
 Now, make the following changes to your `svelte.config.js`.
 
-```ts-diff
-- import adapter from "@sveltejs/adapter-auto";
-+ import adapter from "svelte-adapter-bun";
-  import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
-
-  /** @type {import('@sveltejs/kit').Config} */
-  const config = {
-  	// Consult https://svelte.dev/docs/kit/integrations#preprocessors
-  	// for more information about preprocessors
-  	preprocess: vitePreprocess(),
-
-  	kit: {
-  		// adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
-  		// If your environment is not supported, or you settled on a specific environment, switch out the adapter.
-  		// See https://svelte.dev/docs/kit/adapters for more information about adapters.
-  		adapter: adapter()
-  	}
-  };
-
-  export default config;
+```ts svelte.config.js icon="file-code"
+import adapter from "@sveltejs/adapter-auto"; // [!code --]
+import adapter from "svelte-adapter-bun"; // [!code ++]
+import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  // Consult https://svelte.dev/docs/kit/integrations#preprocessors
+  // for more information about preprocessors
+  preprocess: vitePreprocess(),
+
+  kit: {
+    // adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
+    // If your environment is not supported, or you settled on a specific environment, switch out the adapter.
+    // See https://svelte.dev/docs/kit/adapters for more information about adapters.
+    adapter: adapter(),
+  },
+};
+
+export default config;
 ```
 
 ---
 
 To build a production bundle:
 
-```sh
-$ bun --bun run build
+```sh terminal icon="terminal"
+bun --bun run build
+```
+
+```txt
   $ vite build
   vite v5.4.10 building SSR bundle for production...
   "confetti" is imported from external module "@neoconfetti/svelte" but never used in "src/routes/sverdle/+page.svelte".

package/docs/guides/ecosystem/{systemd.md → systemd.mdx}

@@ -1,20 +1,18 @@
 ---
-name: Run Bun as a daemon with systemd
+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.
 
-<!-- systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and auto mount points, and implements an elaborate transactional dependency-based service control logic. systemd supports SysV and LSB init scripts and works as a replacement for sysvinit. -->
-
-<!-- Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution. -->
-
 ---
 
 To run a Bun application as a daemon using **systemd** you'll need to create a _service file_ in `/lib/systemd/system/`.
 
-```sh
-$ cd /lib/systemd/system
-$ touch my-app.service
+```sh terminal icon="terminal"
+cd /lib/systemd/system
+touch my-app.service
 ```
 
 ---
@@ -23,7 +21,7 @@ Here is a typical service file that runs an application on system start. You can
 
 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
+```ini my-app.service icon="file-code"
 [Unit]
 # describe the app
 Description=My App
@@ -54,32 +52,35 @@ 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
-$ sudo setcap CAP_NET_BIND_SERVICE=+eip ~/.bun/bin/bun
+```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
-$ sudo systemctl enable my-app
+```bash terminal icon="terminal"
+systemctl enable my-app
 ```
 
 ---
 
 To start the service without rebooting, you can manually _start_ it.
 
-```bash
-$ sudo systemctl start my-app
+```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
-$ sudo systemctl status my-app
+```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
@@ -95,19 +96,19 @@ $ sudo systemctl status my-app
 
 To update the service, edit the contents of the service file, then reload the daemon.
 
-```bash
-$ sudo systemctl daemon-reload
+```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
-$ sudo systemctl daemon-reload # tell systemd that some files got changed
-$ sudo systemctl enable my-app # enable the app (to allow auto-start)
-$ sudo systemctl disable my-app # disable the app (turns off auto-start)
-$ sudo systemctl start my-app # start the app if is stopped
-$ sudo systemctl stop my-app # stop the app
-$ sudo systemctl restart my-app # restart the app
+```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.md → vite.mdx}

@@ -1,17 +1,23 @@
 ---
-name: Build a frontend using Vite and Bun
+title: Build a frontend using Vite and Bun
+sidebarTitle: "Vite with Bun"
+mode: center
 ---
 
-{% callout %}
-You can use Vite with Bun, but many projects get faster builds & drop hundreds of dependencies by switching to [HTML imports](/docs/bundler/html).
-{% /callout %}
+<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
-$ bun create vite my-app
+```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...
@@ -21,7 +27,7 @@ Scaffolding project in /path/to/my-app...
 
 Then `cd` into the project directory and install dependencies.
 
-```bash
+```bash terminal icon="terminal"
 cd my-app
 bun install
 ```
@@ -32,7 +38,7 @@ 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
+```bash terminal icon="terminal"
 bunx --bun vite
 ```
 
@@ -40,10 +46,10 @@ bunx --bun vite
 
 To simplify this command, update the `"dev"` script in `package.json` to the following.
 
-```json-diff#package.json
+```json package.json icon="file-json"
   "scripts": {
--   "dev": "vite",
-+   "dev": "bunx --bun vite",
+    "dev": "vite", // [!code --]
+    "dev": "bunx --bun vite", // [!code ++]
     "build": "vite build",
     "serve": "vite preview"
   },
@@ -54,7 +60,7 @@ To simplify this command, update the `"dev"` script in `package.json` to the fol
 
 Now you can start the development server with `bun run dev`.
 
-```bash
+```bash terminal icon="terminal"
 bun run dev
 ```
 
@@ -62,8 +68,8 @@ bun run dev
 
 The following command will build your app for production.
 
-```sh
-$ bunx --bun vite build
+```sh terminal icon="terminal"
+bunx --bun vite build
 ```
 
 ---

package/docs/guides/html-rewriter/{extract-links.md → extract-links.mdx}

@@ -1,12 +1,14 @@
 ---
-name: Extract links from a webpage using HTMLRewriter
+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
+```ts extract-links.ts icon="/icons/typescript.svg"
 async function extractLinks(url: string) {
   const links = new Set<string>();
   const response = await fetch(url);
@@ -35,7 +37,7 @@ await extractLinks("https://bun.com");
 
 When scraping websites, you often want to convert relative URLs (like `/docs`) to absolute URLs. Here's how to handle URL resolution:
 
-```ts
+```ts extract-links.ts icon="/icons/typescript.svg"
 async function extractLinksFromURL(url: string) {
   const response = await fetch(url);
   const links = new Set<string>();
@@ -44,13 +46,15 @@ async function extractLinksFromURL(url: string) {
     element(el) {
       const href = el.getAttribute("href");
       if (href) {
-        // Convert relative URLs to absolute
+        // Convert relative URLs to absolute // [!code ++]
         try {
-          const absoluteURL = new URL(href, url).href;
-          links.add(absoluteURL);
+          // [!code ++]
+          const absoluteURL = new URL(href, url).href; // [!code ++]
+          links.add(absoluteURL); // [!code ++]
         } catch {
+          // [!code ++]
           links.add(href);
-        }
+        } // [!code ++]
       }
     },
   });

package/docs/guides/html-rewriter/{extract-social-meta.md → extract-social-meta.mdx}

@@ -1,12 +1,14 @@
 ---
-name: Extract social share images and Open Graph tags
+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
+```ts extract-social-meta.ts icon="/icons/typescript.svg"
 interface SocialMetadata {
   title?: string;
   description?: string;
@@ -79,7 +81,9 @@ async function extractSocialMetadata(url: string): Promise<SocialMetadata> {
 
   return metadata;
 }
+```
 
+```ts Example Usage icon="/icons/typescript.svg"
 // Example usage
 const metadata = await extractSocialMetadata("https://bun.com");
 console.log(metadata);

package/docs/guides/http/{cluster.md → cluster.mdx}

@@ -1,13 +1,15 @@
 ---
-name: Start a cluster of HTTP servers
+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
+```ts server.ts icon="/icons/typescript.svg"
 import { serve } from "bun";
 
 const id = Math.random().toString(36).slice(2);
@@ -22,21 +24,22 @@ serve({
 
   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 %}
+<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
+```ts cluster.ts icon="/icons/typescript.svg"
 import { spawn } from "bun";
 
 const cpus = navigator.hardwareConcurrency; // Number of CPU cores

package/docs/guides/http/{fetch-unix.md → fetch-unix.mdx}

@@ -1,10 +1,12 @@
 ---
-name: fetch with unix domain sockets in Bun
+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
+```ts fetch-unix.ts icon="/icons/typescript.svg"
 const unix = "/var/run/docker.sock";
 
 const response = await fetch("http://localhost/info", { unix });
@@ -19,7 +21,7 @@ The `unix` option is a string that specifies the local file path to a unix domai
 
 To send a `POST` request to an API endpoint over a unix domain socket:
 
-```ts
+```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",

package/docs/guides/http/{fetch.md → fetch.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Send an HTTP request using fetch
+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
+```ts fetch.ts icon="/icons/typescript.svg"
 const response = await fetch("https://bun.com");
 const html = await response.text(); // HTML string
 ```
@@ -13,7 +15,7 @@ const html = await response.text(); // HTML string
 
 To send a `POST` request to an API endpoint.
 
-```ts
+```ts fetch.ts icon="/icons/typescript.svg"
 const response = await fetch("https://bun.com/api", {
   method: "POST",
   body: JSON.stringify({ message: "Hello from Bun!" }),

package/docs/guides/http/{file-uploads.md → file-uploads.mdx}

@@ -1,10 +1,12 @@
 ---
-name: Upload files via HTTP using FormData
+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
+```ts index.ts icon="/icons/typescript.svg"
 const server = Bun.serve({
   port: 4000,
   async fetch(req) {
@@ -29,7 +31,7 @@ console.log(`Listening on http://localhost:${server.port}`);
 
 We can define our HTML form in another file, `index.html`.
 
-```html#index.html
+```html index.html icon="file-code"
 <!DOCTYPE html>
 <html>
   <head>
@@ -51,7 +53,7 @@ We can define our HTML form in another file, `index.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
+bun run index.ts
 Listening on http://localhost:4000
 ```
 
@@ -63,7 +65,7 @@ First we use the [`.formData()`](https://developer.mozilla.org/en-US/docs/Web/AP
 
 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
+```ts index.ts icon="/icons/typescript.svg"
 const server = Bun.serve({
   port: 4000,
   async fetch(req) {
@@ -77,16 +79,17 @@ const server = Bun.serve({
         },
       });
 
-+   // 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");
-+   }
+    // 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 });
   },

package/docs/guides/http/{hot.md → hot.mdx}

@@ -1,22 +1,24 @@
 ---
-name: Hot reload an HTTP server
+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
-$ bun --hot run index.ts
+```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.
 
-{% callout %}
+<Note>
 Note that this doesn't reload the page on your browser.
-{% /callout %}
-
-```ts
+</Note>
+ 
+```ts index.ts icon="/icons/typescript.svg"
 Bun.serve({
   port: 3000,
   fetch(req) {