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

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

@@ -1,54 +0,0 @@
----
-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.com/docs/api/hashing#bun-password) for complete documentation.

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

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

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

@@ -1,13 +0,0 @@
----
-name: Get the file name of the current file
----
-
-Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/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.com/docs/api/import-meta) for complete documentation.

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

@@ -1,13 +0,0 @@
----
-name: Get the absolute path of the current file
----
-
-Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/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.com/docs/api/import-meta) for complete documentation.

package/docs/guides/util/javascript-uuid.md

@@ -1,23 +0,0 @@
----
-name: Generate a UUID
----
-
-Use `crypto.randomUUID()` to generate a UUID v4. This API works in Bun, Node.js, and browsers. It requires no dependencies.
-
-```ts
-crypto.randomUUID();
-// => "123e4567-e89b-12d3-a456-426614174000"
-```
-
----
-
-In Bun, you can also use `Bun.randomUUIDv7()` to generate a [UUID v7](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html).
-
-```ts
-Bun.randomUUIDv7();
-// => "0196a000-bb12-7000-905e-8039f5d5b206"
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/main.md

@@ -1,32 +0,0 @@
----
-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.com/docs/api/utils) for more useful utilities.

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

@@ -1,14 +0,0 @@
----
-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.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/sleep.md

@@ -1,22 +0,0 @@
----
-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.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/version.md

@@ -1,21 +0,0 @@
----
-name: Get the current Bun version
----
-
-Get the current version of Bun in a semver format.
-
-```ts#index.ts
-Bun.version; // => "1.3.2-canary.20251104T140728"
-```
-
----
-
-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.com/docs/api/utils) for more useful utilities.

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

@@ -1,15 +0,0 @@
----
-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.com/docs/api/utils#bun-which) for complete documentation.

package/docs/guides/websocket/compression.md

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

@@ -1,77 +0,0 @@
----
-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.com/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({
-  fetch(req, server) {
-    const success = server.upgrade(req, {
-      data: {
-        socketId: Math.random(),
-      },
-    });
-    if (success) return undefined;
-
-    // handle HTTP request normally
-    // ...
-  },
-  websocket: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as { socketId: number },
-
-    // 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;
-};
-
-Bun.serve({
-  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: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as WebSocketData,
-
-    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

@@ -1,41 +0,0 @@
----
-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({
-  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: {
-    // TypeScript: specify the type of ws.data like this
-    data: {} as { username: string },
-
-    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

@@ -1,33 +0,0 @@
----
-name: Build a simple WebSocket server
----
-
-Start a simple WebSocket server using [`Bun.serve`](https://bun.com/docs/api/http).
-
-Inside `fetch`, we attempt to upgrade incoming `ws:` or `wss:` requests to WebSocket connections.
-
-```ts
-const server = Bun.serve({
-  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

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

@@ -1,44 +0,0 @@
----
-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.com/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.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

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

@@ -1,28 +0,0 @@
----
-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.com/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.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

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

@@ -1,17 +0,0 @@
----
-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.com/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.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

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

@@ -1,16 +0,0 @@
----
-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.com/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.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.

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

@@ -1,52 +0,0 @@
----
-name: Write a file incrementally
----
-
-Bun provides an API for incrementally writing to a file. This is useful for writing large files, or for writing to a file over a long period of time.
-
-Call `.writer()` on a `BunFile` to retrieve a `FileSink` instance. This instance can be used to efficiently buffer data and periodically "flush" it to disk. You can write & flush many times.
-
-```ts
-const file = Bun.file("/path/to/file.txt");
-const writer = file.writer();
-
-writer.write("lorem");
-writer.write("ipsum");
-writer.write("dolor");
-
-writer.flush();
-
-// continue writing & flushing
-```
-
----
-
-The `.write()` method can accept strings or binary data.
-
-```ts
-w.write("hello");
-w.write(Buffer.from("there"));
-w.write(new Uint8Array([0, 255, 128]));
-writer.flush();
-```
-
----
-
-The `FileSink` will also auto-flush when its internal buffer is full. You can configure the buffer size with the `highWaterMark` option.
-
-```ts
-const file = Bun.file("/path/to/file.txt");
-const writer = file.writer({ highWaterMark: 1024 * 1024 }); // 1MB
-```
-
----
-
-When you're done writing to the file, call `.end()` to auto-flush the buffer and close the file.
-
-```ts
-writer.end();
-```
-
----
-
-Full documentation: [FileSink](https://bun.com/docs/api/file-io#incremental-writing-with-filesink).

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

@@ -1,17 +0,0 @@
----
-name: Write a Response to a file
----
-
-This code snippet writes a `Response` to disk at a particular path. Bun will consume the `Response` body according to its `Content-Type` header.
-
-It uses the fast [`Bun.write()`](https://bun.com/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 result = await fetch("https://bun.com");
-const path = "./file.txt";
-await Bun.write(path, result);
-```
-
----
-
-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/write-file/stdout.md

@@ -1,21 +0,0 @@
----
-name: Write to stdout
----
-
-The `console.log` function writes to `stdout`. It will automatically append a line break at the end of the printed data.
-
-```ts
-console.log("Lorem ipsum");
-```
-
----
-
-For more advanced use cases, Bun exposes `stdout` as a `BunFile` via the `Bun.stdout` property. This can be used as a destination for [`Bun.write()`](https://bun.com/docs/api/file-io#writing-files-bun-write).
-
-```ts
-await Bun.write(Bun.stdout, "Lorem ipsum");
-```
-
----
-
-See [Docs > API > File I/O](https://bun.com/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.