bun-types 1.1.37-canary.20241124T140524 → 1.1.37-canary.20241125T140601

package/docs/guides/util/detect-bun.md

@@ -0,0 +1,23 @@
+---
+name: Detect when code is executed with Bun
+---
+
+The recommended way to conditionally detect when code is being executed with `bun` is to check for the existence of the `Bun` global.
+
+This is similar to how you'd check for the existence of the `window` variable to detect when code is being executed in a browser.
+
+```ts
+if (typeof Bun !== "undefined") {
+  // this code will only run when the file is run with Bun
+}
+```
+
+---
+
+In TypeScript environments, the previous approach will result in a type error unless `bun-types` is globally installed. To avoid this, you can check `process.versions` instead.
+
+```ts
+if (process.versions.bun) {
+  // this code will only run when the file is run with Bun
+}
+```

package/docs/guides/util/entrypoint.md

@@ -0,0 +1,17 @@
+---
+name: Check if the current file is the entrypoint
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.sh/docs/api/import-meta) object. Use `import.meta.main` to check if the current file is the entrypoint of the current process.
+
+```ts#index.ts
+if (import.meta.main) {
+  // this file is directly executed with `bun run`
+} else {
+  // this file is being imported by another file
+}
+```
+
+---
+
+See [Docs > API > import.meta](https://bun.sh/docs/api/import-meta) for complete documentation.

package/docs/guides/util/escape-html.md

@@ -0,0 +1,22 @@
+---
+name: Escape an HTML string
+---
+
+The `Bun.escapeHTML()` utility can be used to escape HTML characters in a string. The following replacements are made.
+
+- `"` becomes `"""`
+- `&` becomes `"&"`
+- `'` becomes `"'"`
+- `<` becomes `"&lt;"`
+- `>` becomes `"&gt;"`
+
+This function is optimized for large input. Non-string types will be converted to a string before escaping.
+
+```ts
+Bun.escapeHTML("<script>alert('Hello World!')</script>");
+// &lt;script&gt;alert(&#x27;Hello World!&#x27;)&lt;&#x2F;script&gt;
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/file-url-to-path.md

@@ -0,0 +1,14 @@
+---
+name: Convert a file URL to an absolute path
+---
+
+Use `Bun.fileURLToPath()` to convert a `file://` URL to an absolute path.
+
+```ts
+Bun.fileURLToPath("file:///path/to/file.txt");
+// => "/path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/gzip.md

@@ -0,0 +1,18 @@
+---
+name: Compress and decompress data with gzip
+---
+
+Use `Bun.gzipSync()` to compress a `Uint8Array` with gzip.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.gzipSync(data);
+// => Uint8Array
+
+const decompressed = Bun.gunzipSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/hash-a-password.md

@@ -0,0 +1,54 @@
+---
+name: Hash a password
+---
+
+The `Bun.password.hash()` function provides a fast, built-in mechanism for securely hashing passwords in Bun. No third-party dependencies are required.
+
+```ts
+const password = "super-secure-pa$$word";
+
+const hash = await Bun.password.hash(password);
+// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/...
+```
+
+---
+
+By default, this uses the [Argon2id](https://en.wikipedia.org/wiki/Argon2) algorithm. Pass a second argument to `Bun.password.hash()` to use a different algorithm or configure the hashing parameters.
+
+```ts
+const password = "super-secure-pa$$word";
+
+// use argon2 (default)
+const argonHash = await Bun.password.hash(password, {
+  memoryCost: 4, // memory usage in kibibytes
+  timeCost: 3, // the number of iterations
+});
+```
+
+---
+
+Bun also implements the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm. Specify `algorithm: "bcrypt"` to use it.
+
+```ts
+// use bcrypt
+const bcryptHash = await Bun.password.hash(password, {
+  algorithm: "bcrypt",
+  cost: 4, // number between 4-31
+});
+```
+
+---
+
+Use `Bun.password.verify()` to verify a password. The algorithm and its parameters are stored in the hash itself, so re-specifying configuration is unnecessary.
+
+```ts
+const password = "super-secure-pa$$word";
+const hash = await Bun.password.hash(password);
+
+const isMatch = await Bun.password.verify(password, hash);
+// => true
+```
+
+---
+
+See [Docs > API > Hashing](https://bun.sh/docs/api/hashing#bun-password) for complete documentation.

package/docs/guides/util/import-meta-dir.md

@@ -0,0 +1,13 @@
+---
+name: Get the directory of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.sh/docs/api/import-meta) object.
+
+```ts#/a/b/c.ts
+import.meta.dir; // => "/a/b"
+```
+
+---
+
+See [Docs > API > import.meta](https://bun.sh/docs/api/import-meta) for complete documentation.

package/docs/guides/util/import-meta-file.md

@@ -0,0 +1,13 @@
+---
+name: Get the file name of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.sh/docs/api/import-meta) object. Use `import.meta.file` to retrieve the name of the current file.
+
+```ts#/a/b/c.ts
+import.meta.file; // => "c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](https://bun.sh/docs/api/import-meta) for complete documentation.

package/docs/guides/util/import-meta-path.md

@@ -0,0 +1,13 @@
+---
+name: Get the absolute path of the current file
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.sh/docs/api/import-meta) object. Use `import.meta.path` to retrieve the absolute path of the current file.
+
+```ts#/a/b/c.ts
+import.meta.path; // => "/a/b/c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](https://bun.sh/docs/api/import-meta) for complete documentation.

package/docs/guides/util/main.md

@@ -0,0 +1,32 @@
+---
+name: Get the absolute path to the current entrypoint
+---
+
+The `Bun.main` property contains the absolute path to the current entrypoint.
+
+{% codetabs %}
+
+```ts#foo.ts
+console.log(Bun.main);
+```
+
+```ts#index.ts
+import "./foo.ts";
+```
+
+{% /codetabs %}
+
+---
+
+The printed path corresponds to the file that is executed with `bun run`.
+
+```sh
+$ bun run index.ts
+/path/to/index.ts
+$ bun run foo.ts
+/path/to/foo.ts
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/path-to-file-url.md

@@ -0,0 +1,14 @@
+---
+name: Convert an absolute path to a file URL
+---
+
+Use `Bun.pathToFileURL()` to convert an absolute path to a `file://` URL.
+
+```ts
+Bun.pathToFileURL("/path/to/file.txt");
+// => "file:///path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/sleep.md

@@ -0,0 +1,22 @@
+---
+name: Sleep for a fixed number of milliseconds
+---
+
+The `Bun.sleep` method provides a convenient way to create a void `Promise` that resolves in a fixed number of milliseconds.
+
+```ts
+// sleep for 1 second
+await Bun.sleep(1000);
+```
+
+---
+
+Internally, this is equivalent to the following snippet that uses [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout).
+
+```ts
+await new Promise(resolve => setTimeout(resolve, ms));
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/version.md

@@ -0,0 +1,21 @@
+---
+name: Get the current Bun version
+---
+
+Get the current version of Bun in a semver format.
+
+```ts#index.ts
+Bun.version; // => "0.6.15"
+```
+
+---
+
+Get the exact `git` commit of [`oven-sh/bun`](https://github.com/oven-sh/bun) that was compiled to produce this Bun binary.
+
+```ts#index.ts
+Bun.revision; // => "49231b2cb9aa48497ab966fc0bb6b742dacc4994"
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/which-path-to-executable-bin.md

@@ -0,0 +1,15 @@
+---
+name: Get the path to an executable bin file
+---
+
+`Bun.which` is a utility function to find the absolute path of an executable file. It is similar to the `which` command in Unix-like systems.
+
+```ts#foo.ts
+Bun.which("sh"); // => "/bin/sh"
+Bun.which("notfound"); // => null
+Bun.which("bun"); // => "/home/user/.bun/bin/bun"
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-which) for complete documentation.

package/docs/guides/websocket/compression.md

@@ -0,0 +1,31 @@
+---
+name: Enable compression for WebSocket messages
+---
+
+Per-message compression can be enabled with the `perMessageDeflate` parameter. When set, all messages will be compressed using the [permessage-deflate](https://tools.ietf.org/html/rfc7692) WebSocket extension.
+
+```ts
+Bun.serve({
+  // ...
+  websocket: {
+    // enable compression
+    perMessageDeflate: true,
+  },
+});
+```
+
+---
+
+To enable compression for individual messages, pass `true` as the second parameter to `ws.send()`.
+
+```ts
+Bun.serve({
+  // ...
+  websocket: {
+    async message(ws, message) {
+      // send a compressed message
+      ws.send(message, true);
+    },
+  },
+});
+```

package/docs/guides/websocket/context.md

@@ -0,0 +1,72 @@
+---
+name: Set per-socket contextual data on a WebSocket
+---
+
+When building a WebSocket server, it's typically necessary to store some identifying information or context associated with each connected client.
+
+With [Bun.serve()](https://bun.sh/docs/api/websockets#contextual-data), this "contextual data" is set when the connection is initially upgraded by passing a `data` parameter in the `server.upgrade()` call.
+
+```ts
+Bun.serve<{ socketId: number }>({
+  fetch(req, server) {
+    const success = server.upgrade(req, {
+      data: {
+        socketId: Math.random(),
+      },
+    });
+    if (success) return undefined;
+
+    // handle HTTP request normally
+    // ...
+  },
+  websocket: {
+    // define websocket handlers
+    async message(ws, message) {
+      // the contextual data is available as the `data` property
+      // on the WebSocket instance
+      console.log(`Received ${message} from ${ws.data.socketId}}`);
+    },
+  },
+});
+```
+
+---
+
+It's common to read cookies/headers from the incoming request to identify the connecting client.
+
+```ts
+type WebSocketData = {
+  createdAt: number;
+  token: string;
+  userId: string;
+};
+
+// TypeScript: specify the type of `data`
+Bun.serve<WebSocketData>({
+  async fetch(req, server) {
+    // use a library to parse cookies
+    const cookies = parseCookies(req.headers.get("Cookie"));
+    const token = cookies["X-Token"];
+    const user = await getUserFromToken(token);
+
+    const upgraded = server.upgrade(req, {
+      data: {
+        createdAt: Date.now(),
+        token: cookies["X-Token"],
+        userId: user.id,
+      },
+    });
+
+    if (upgraded) return undefined;
+  },
+  websocket: {
+    async message(ws, message) {
+      // save the message to a database
+      await saveMessageToDatabase({
+        message: String(message),
+        userId: ws.data.userId,
+      });
+    },
+  },
+});
+```

package/docs/guides/websocket/pubsub.md

@@ -0,0 +1,38 @@
+---
+name: Build a publish-subscribe WebSocket server
+---
+
+Bun's server-side `WebSocket` API provides a native pub-sub API. Sockets can be subscribed to a set of named channels using `socket.subscribe(<name>)`; messages can be published to a channel using `socket.publish(<name>, <message>)`.
+
+This code snippet implements a simple single-channel chat server.
+
+```ts
+const server = Bun.serve<{ username: string }>({
+  fetch(req, server) {
+    const cookies = req.headers.get("cookie");
+    const username = getUsernameFromCookies(cookies);
+    const success = server.upgrade(req, { data: { username } });
+    if (success) return undefined;
+
+    return new Response("Hello world");
+  },
+  websocket: {
+    open(ws) {
+      const msg = `${ws.data.username} has entered the chat`;
+      ws.subscribe("the-group-chat");
+      server.publish("the-group-chat", msg);
+    },
+    message(ws, message) {
+      // the server re-broadcasts incoming messages to everyone
+      server.publish("the-group-chat", `${ws.data.username}: ${message}`);
+    },
+    close(ws) {
+      const msg = `${ws.data.username} has left the chat`;
+      server.publish("the-group-chat", msg);
+      ws.unsubscribe("the-group-chat");
+    },
+  },
+});
+
+console.log(`Listening on ${server.hostname}:${server.port}`);
+```

package/docs/guides/websocket/simple.md

@@ -0,0 +1,33 @@
+---
+name: Build a simple WebSocket server
+---
+
+Start a simple WebSocket server using [`Bun.serve`](https://bun.sh/docs/api/http).
+
+Inside `fetch`, we attempt to upgrade incoming `ws:` or `wss:` requests to WebSocket connections.
+
+```ts
+const server = Bun.serve<{ authToken: string }>({
+  fetch(req, server) {
+    const success = server.upgrade(req);
+    if (success) {
+      // Bun automatically returns a 101 Switching Protocols
+      // if the upgrade succeeds
+      return undefined;
+    }
+
+    // handle HTTP request normally
+    return new Response("Hello world!");
+  },
+  websocket: {
+    // this is called when a message is received
+    async message(ws, message) {
+      console.log(`Received ${message}`);
+      // send back a message
+      ws.send(`You said: ${message}`);
+    },
+  },
+});
+
+console.log(`Listening on ${server.hostname}:${server.port}`);
+```

package/docs/guides/write-file/append.md

@@ -0,0 +1,52 @@
+---
+name: Append content to a file
+---
+
+Bun implements the `node:fs` module, which includes the `fs.appendFile` and `fs.appendFileSync` functions for appending content to files.
+
+---
+
+You can use `fs.appendFile` to asynchronously append data to a file, creating the file if it does not yet exist. The content can be a string or a `Buffer`.
+
+```ts
+import { appendFile } from "node:fs/promises";
+
+await appendFile("message.txt", "data to append");
+```
+
+---
+
+To use the non-`Promise` API:
+
+```ts
+import { appendFile } from "node:fs";
+
+appendFile("message.txt", "data to append", err => {
+  if (err) throw err;
+  console.log('The "data to append" was appended to file!');
+});
+```
+
+---
+
+To specify the encoding of the content:
+
+```js
+import { appendFile } from "node:fs";
+
+appendFile("message.txt", "data to append", "utf8", callback);
+```
+
+---
+
+To append the data synchronously, use `fs.appendFileSync`:
+
+```ts
+import { appendFileSync } from "node:fs";
+
+appendFileSync("message.txt", "data to append", "utf8");
+```
+
+---
+
+See the [Node.js documentation](https://nodejs.org/api/fs.html#fspromisesappendfilepath-data-options) for more information.

package/docs/guides/write-file/basic.md

@@ -0,0 +1,44 @@
+---
+name: Write a string to a file
+---
+
+This code snippet writes a string to disk at a particular _absolute path_.
+
+It uses the fast [`Bun.write()`](https://bun.sh/docs/api/file-io#writing-files-bun-write) API to efficiently write data to disk. The first argument is a _destination_; the second is the _data_ to write.
+
+```ts
+const path = "/path/to/file.txt";
+await Bun.write(path, "Lorem ipsum");
+```
+
+---
+
+Any relative paths will be resolved relative to the project root (the nearest directory containing a `package.json` file).
+
+```ts
+const path = "./file.txt";
+await Bun.write(path, "Lorem ipsum");
+```
+
+---
+
+You can pass a `BunFile` as the destination. `Bun.write()` will write the data to its associated path.
+
+```ts
+const path = Bun.file("./file.txt");
+await Bun.write(path, "Lorem ipsum");
+```
+
+---
+
+`Bun.write()` returns the number of bytes written to disk.
+
+```ts
+const path = "./file.txt";
+const bytes = await Bun.write(path, "Lorem ipsum");
+// => 11
+```
+
+---
+
+See [Docs > API > File I/O](https://bun.sh/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

package/docs/guides/write-file/blob.md

@@ -0,0 +1,28 @@
+---
+name: Write a Blob to a file
+---
+
+This code snippet writes a `Blob` to disk at a particular path.
+
+It uses the fast [`Bun.write()`](https://bun.sh/docs/api/file-io#writing-files-bun-write) API to efficiently write data to disk. The first argument is a _destination_, like an absolute path or `BunFile` instance. The second argument is the _data_ to write.
+
+```ts
+const path = "/path/to/file.txt";
+await Bun.write(path, "Lorem ipsum");
+```
+
+---
+
+The `BunFile` class extends `Blob`, so you can pass a `BunFile` directly into `Bun.write()` as well.
+
+```ts
+const path = "./out.txt";
+const data = Bun.file("./in.txt");
+
+// write the contents of ./in.txt to ./out.txt
+await Bun.write(path, data);
+```
+
+---
+
+See [Docs > API > File I/O](https://bun.sh/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

package/docs/guides/write-file/cat.md

@@ -0,0 +1,17 @@
+---
+name: Write a file to stdout
+---
+
+Bun exposes `stdout` as a `BunFile` with the `Bun.stdout` property. This can be used as a destination for [`Bun.write()`](https://bun.sh/docs/api/file-io#writing-files-bun-write).
+
+This code writes a file to `stdout` similar to the `cat` command in Unix.
+
+```ts#cat.ts
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
+await Bun.write(Bun.stdout, file);
+```
+
+---
+
+See [Docs > API > File I/O](https://bun.sh/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

package/docs/guides/write-file/file-cp.md

@@ -0,0 +1,16 @@
+---
+name: Copy a file to another location
+---
+
+This code snippet copies a file to another location on disk.
+
+It uses the fast [`Bun.write()`](https://bun.sh/docs/api/file-io#writing-files-bun-write) API to efficiently write data to disk. The first argument is a _destination_, like an absolute path or `BunFile` instance. The second argument is the _data_ to write.
+
+```ts
+const file = Bun.file("/path/to/original.txt");
+await Bun.write("/path/to/copy.txt", file);
+```
+
+---
+
+See [Docs > API > File I/O](https://bun.sh/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.