bun-types 1.1.37-canary.20241123T140655 → 1.1.37-canary.20241125T140601

package/docs/guides/ecosystem/sveltekit.md

@@ -0,0 +1,125 @@
+---
+name: Build an app with SvelteKit and Bun
+---
+
+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
+┌  Welcome to the Svelte CLI! (v0.5.7)
+│
+◇  Which template would you like?
+│  SvelteKit demo
+│
+◇  Add type checking with Typescript?
+│  Yes, using Typescript syntax
+│
+◆  Project created
+│
+◇  What would you like to add to your project?
+│  none
+│
+◇  Which package manager do you want to install dependencies with?
+│  bun
+│
+◇  Successfully installed dependencies
+│
+◇  Project next steps ─────────────────────────────────────────────────────╮
+│                                                                          │
+│  1: cd my-app                                                            │
+│  2: git init && git add -A && git commit -m "Initial commit" (optional)  │
+│  3: bun run dev -- --open                                                │
+│                                                                          │
+│  To close the dev server, hit Ctrl-C                                     │
+│                                                                          │
+│  Stuck? Visit us at https://svelte.dev/chat                              │
+│                                                                          │
+├──────────────────────────────────────────────────────────────────────────╯
+│
+└  You're all set!
+```
+
+---
+
+Once the project is initialized, `cd` into the new project. You don't need to run 'bun install' since the dependencies are already installed.
+
+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
+  $ vite dev
+  Forced re-optimization of dependencies
+  
+    VITE v5.4.10  ready in 424 ms
+  
+    ➜  Local:   http://localhost:5173/
+    ➜  Network: use --host to expose
+    ➜  press h + enter to show help
+```
+
+---
+
+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" /%}
+
+---
+
+If you edit and save `src/routes/+page.svelte`, you should see your changes hot-reloaded in the browser.
+
+---
+
+To build for production, you'll need to add the right SvelteKit adapter. Currently we recommend the
+
+`bun add -D svelte-adapter-bun`.
+
+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;
+```
+
+---
+
+To build a production bundle:
+
+```sh
+$ bun --bun run build
+  $ 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".
+  ✓ 130 modules transformed.
+  vite v5.4.10 building for production...
+  ✓ 148 modules transformed.
+  ...
+  ✓ built in 231ms
+  ...
+  ✓ built in 899ms
+  
+  Run npm run preview to preview your production build locally.
+  
+  > Using svelte-adapter-bun
+    ✔ Start server with: bun ./build/index.js
+    ✔ done
+```

package/docs/guides/ecosystem/systemd.md

@@ -0,0 +1,113 @@
+---
+name: Run Bun as a daemon with systemd
+---
+
+[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
+```
+
+---
+
+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
+[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
+$ sudo 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
+```
+
+---
+
+To start the service without rebooting, you can manually _start_ it.
+
+```bash
+$ sudo 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
+● 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
+$ sudo 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
+```

package/docs/guides/ecosystem/vite.md

@@ -0,0 +1,70 @@
+---
+name: Build a frontend using Vite and Bun
+---
+
+{% callout %}
+While Vite currently works with Bun, it has not been heavily optimized, nor has Vite been adapted to use Bun's bundler, module resolver, or transpiler.
+{% /callout %}
+
+---
+
+Vite works out of the box with Bun. Get started with one of Vite's templates.
+
+```bash
+$ bun create vite my-app
+✔ 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
+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
+bunx --bun vite
+```
+
+---
+
+To simplify this command, update the `"dev"` script in `package.json` to the following.
+
+```json-diff#package.json
+  "scripts": {
+-   "dev": "vite",
++   "dev": "bunx --bun vite",
+    "build": "vite build",
+    "serve": "vite preview"
+  },
+  // ...
+```
+
+---
+
+Now you can start the development server with `bun run dev`.
+
+```bash
+bun run dev
+```
+
+---
+
+The following command will build your app for production.
+
+```sh
+$ 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/http/cluster.md

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

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

@@ -0,0 +1,24 @@
+---
+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.sh");
+const html = await response.text(); // HTML string
+```
+
+---
+
+To send a `POST` request to an API endpoint.
+
+```ts
+const response = await fetch("https://bun.sh/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

@@ -0,0 +1,94 @@
+---
+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.sh/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

@@ -0,0 +1,22 @@
+---
+name: Hot reload an HTTP server
+---
+
+Bun supports the [`--hot`](https://bun.sh/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.
+
+```ts
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response(`Hello world`);
+  },
+});
+```

package/docs/guides/http/proxy.md

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

@@ -0,0 +1,46 @@
+---
+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.sh/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

@@ -0,0 +1,18 @@
+---
+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.sh/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

@@ -0,0 +1,48 @@
+---
+name: Stream a file as an HTTP Response
+---
+
+This snippet reads a file from disk using [`Bun.file()`](https://bun.sh/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.sh/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.sh/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.