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

package/docs/guides/process/ipc.mdx

@@ -0,0 +1,69 @@
+---
+title: Spawn a child process and communicate using IPC
+sidebarTitle: Spawn a child process and communicate using IPC
+mode: center
+---
+
+Use [`Bun.spawn()`](https://bun.com/docs/api/spawn) to spawn a child process. When spawning a second `bun` process, you can open a direct inter-process communication (IPC) channel between the two processes.
+
+<Note>
+  This API is only compatible with other `bun` processes. Use `process.execPath` to get a path to the currently running
+  `bun` executable.
+</Note>
+
+```ts parent.ts icon="/icons/typescript.svg"
+const child = Bun.spawn(["bun", "child.ts"], {
+  ipc(message) {
+    /**
+     * The message received from the sub process
+     **/
+  },
+});
+```
+
+---
+
+The parent process can send messages to the subprocess using the `.send()` method on the returned `Subprocess` instance. A reference to the sending subprocess is also available as the second argument in the `ipc` handler.
+
+```ts parent.ts icon="/icons/typescript.svg"
+const childProc = Bun.spawn(["bun", "child.ts"], {
+  ipc(message, childProc) {
+    /**
+     * The message received from the sub process
+     **/
+    childProc.send("Respond to child");
+  },
+});
+
+childProc.send("I am your father"); // The parent can send messages to the child as well
+```
+
+---
+
+Meanwhile the child process can send messages to its parent using with `process.send()` and receive messages with `process.on("message")`. This is the same API used for `child_process.fork()` in Node.js.
+
+```ts child.ts icon="/icons/typescript.svg"
+process.send("Hello from child as string");
+process.send({ message: "Hello from child as object" });
+
+process.on("message", message => {
+  // print message from parent
+  console.log(message);
+});
+```
+
+---
+
+All messages are serialized using the JSC `serialize` API, which allows for the same set of [transferrable types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) supported by `postMessage` and `structuredClone`, including strings, typed arrays, streams, and objects.
+
+```ts child.ts icon="/icons/typescript.svg"
+// send a string
+process.send("Hello from child as string");
+
+// send an object
+process.send({ message: "Hello from child as object" });
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.com/docs/api/spawn) for complete documentation.

package/docs/guides/process/nanoseconds.mdx

@@ -0,0 +1,15 @@
+---
+title: Get the process uptime in nanoseconds
+sidebarTitle: Process uptime
+mode: center
+---
+
+Use `Bun.nanoseconds()` to get the total number of nanoseconds the `bun` process has been alive.
+
+```ts
+Bun.nanoseconds();
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/process/os-signals.mdx

@@ -0,0 +1,41 @@
+---
+title: Listen to OS signals
+sidebarTitle: OS signals
+mode: center
+---
+
+Bun supports the Node.js `process` global, including the `process.on()` method for listening to OS signals.
+
+```ts
+process.on("SIGINT", () => {
+  console.log("Received SIGINT");
+});
+```
+
+---
+
+If you don't know which signal to listen for, you listen to the umbrella `"exit"` event.
+
+```ts
+process.on("exit", code => {
+  console.log(`Process exited with code ${code}`);
+});
+```
+
+---
+
+If you don't know which signal to listen for, you listen to the [`"beforeExit"`](https://nodejs.org/api/process.html#event-beforeexit) and [`"exit"`](https://nodejs.org/api/process.html#event-exit) events.
+
+```ts
+process.on("beforeExit", code => {
+  console.log(`Event loop is empty!`);
+});
+
+process.on("exit", code => {
+  console.log(`Process is exiting with code ${code}`);
+});
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/process/spawn-stderr.mdx

@@ -0,0 +1,34 @@
+---
+title: Read stderr from a child process
+sidebarTitle: Read stderr
+mode: center
+---
+
+When using [`Bun.spawn()`](https://bun.com/docs/api/spawn), the child process inherits the `stderr` of the spawning process. If instead you'd prefer to read and handle `stderr`, set the `stderr` option to `"pipe"`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stderr: "pipe",
+});
+
+proc.stderr; // => ReadableStream
+```
+
+---
+
+To read `stderr` until the child process exits, use .text()
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stderr: "pipe",
+});
+
+const errors: string = await proc.stderr.text();
+if (errors) {
+  // handle errors
+}
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.com/docs/api/spawn) for complete documentation.

package/docs/guides/process/spawn-stdout.mdx

@@ -0,0 +1,28 @@
+---
+title: Read stdout from a child process
+sidebarTitle: Read stdout
+mode: center
+---
+
+When using [`Bun.spawn()`](https://bun.com/docs/api/spawn), the `stdout` of the child process can be consumed as a `ReadableStream` via `proc.stdout`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+const output = await proc.stdout.text();
+output; // => "hello"
+```
+
+---
+
+To instead pipe the `stdout` of the child process to `stdout` of the parent process, set "inherit".
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stdout: "inherit",
+});
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.com/docs/api/spawn) for complete documentation.

package/docs/guides/process/spawn.mdx

@@ -0,0 +1,43 @@
+---
+title: Spawn a child process
+sidebarTitle: Spawn child process
+mode: center
+---
+
+Use [`Bun.spawn()`](https://bun.com/docs/api/spawn) to spawn a child process.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+// await completion
+await proc.exited;
+```
+
+---
+
+The second argument accepts a configuration object.
+
+```ts
+const proc = Bun.spawn(["echo", "Hello, world!"], {
+  cwd: "/tmp",
+  env: { FOO: "bar" },
+  onExit(proc, exitCode, signalCode, error) {
+    // exit handler
+  },
+});
+```
+
+---
+
+By default, the `stdout` of the child process can be consumed as a `ReadableStream` using `proc.stdout`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+const output = await proc.stdout.text();
+output; // => "hello\n"
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.com/docs/api/spawn) for complete documentation.

package/docs/guides/process/stdin.mdx

@@ -0,0 +1,62 @@
+---
+title: Read from stdin
+sidebarTitle: Read from stdin
+mode: center
+---
+
+For CLI tools, it's often useful to read from `stdin`. In Bun, the `console` object is an `AsyncIterable` that yields lines from `stdin`.
+
+```ts index.ts icon="/icons/typescript.svg"
+const prompt = "Type something: ";
+process.stdout.write(prompt);
+for await (const line of console) {
+  console.log(`You typed: ${line}`);
+  process.stdout.write(prompt);
+}
+```
+
+---
+
+Running this file results in a never-ending interactive prompt that echoes whatever the user types.
+
+```sh terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+Type something: hello
+You typed: hello
+Type something: hello again
+You typed: hello again
+```
+
+---
+
+Bun also exposes stdin as a `BunFile` via `Bun.stdin`. This is useful for incrementally reading large inputs that are piped into the `bun` process.
+
+There is no guarantee that the chunks will be split line-by-line.
+
+```ts stdin.ts icon="/icons/typescript.svg"
+for await (const chunk of Bun.stdin.stream()) {
+  // chunk is Uint8Array
+  // this converts it to text (assumes ASCII encoding)
+  const chunkText = Buffer.from(chunk).toString();
+  console.log(`Chunk: ${chunkText}`);
+}
+```
+
+---
+
+This will print the input that is piped into the `bun` process.
+
+```sh terminal icon="terminal"
+echo "hello" | bun run stdin.ts
+```
+
+```txt
+Chunk: hello
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/read-file/arraybuffer.mdx

@@ -0,0 +1,30 @@
+---
+title: Read a file to an ArrayBuffer
+sidebarTitle: Read to ArrayBuffer
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.arrayBuffer()` to read the file as an `ArrayBuffer`.
+
+```ts index.ts icon="/icons/typescript.svg"
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const buffer = await file.arrayBuffer();
+```
+
+---
+
+The binary content in the `ArrayBuffer` can then be read as a typed array, such as `Int8Array`. For `Uint8Array`, use [`.bytes()`](./uint8array).
+
+```ts index.ts icon="/icons/typescript.svg"
+const buffer = await file.arrayBuffer();
+const bytes = new Int8Array(buffer);
+
+bytes[0];
+bytes.length;
+```
+
+---
+
+Refer to the [Typed arrays](https://bun.com/docs/api/binary-data#typedarray) docs for more information on working with typed arrays in Bun.

package/docs/guides/read-file/buffer.mdx

@@ -0,0 +1,21 @@
+---
+title: Read a file to a Buffer
+sidebarTitle: Read to Buffer
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats.
+
+To read the file into a `Buffer` instance, first use `.arrayBuffer()` to consume the file as an `ArrayBuffer`, then use `Buffer.from()` to create a `Buffer` from the `ArrayBuffer`.
+
+```ts index.ts icon="/icons/typescript.svg"
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const arrbuf = await file.arrayBuffer();
+const buffer = Buffer.from(arrbuf);
+```
+
+---
+
+Refer to [Binary data > Buffer](https://bun.com/docs/api/binary-data#buffer) for more information on working with `Buffer` and other binary data formats in Bun.

package/docs/guides/read-file/exists.mdx

@@ -0,0 +1,18 @@
+---
+title: Check if a file exists
+sidebarTitle: Check file exists
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. Use the `.exists()` method to check if a file exists at the given path.
+
+```ts index.ts icon="/icons/typescript.svg"
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+await file.exists(); // boolean;
+```
+
+---
+
+Refer to [API > File I/O](https://bun.com/docs/api/file-io) for more information on working with `BunFile`.

package/docs/guides/read-file/json.mdx

@@ -0,0 +1,19 @@
+---
+title: Read a JSON file
+sidebarTitle: Read JSON file
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.json()` to read and parse the contents of a `.json` file as a plain object.
+
+The MIME type of the `BunFile` will be set accordingly.
+
+```ts index.ts icon="/icons/typescript.svg"
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const contents = await file.json();
+// { name: "my-package" }
+
+file.type; // => "application/json;charset=utf-8";
+```

package/docs/guides/read-file/mime.mdx

@@ -0,0 +1,22 @@
+---
+title: Get the MIME type of a file
+sidebarTitle: Get MIME type
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob`, so use the `.type` property to read the MIME type.
+
+```ts
+const file = Bun.file("./package.json");
+file.type; // application/json
+
+const file = Bun.file("./index.html");
+file.type; // text/html
+
+const file = Bun.file("./image.png");
+file.type; // image/png
+```
+
+---
+
+Refer to [API > File I/O](https://bun.com/docs/api/file-io) for more information on working with `BunFile`.

package/docs/guides/read-file/stream.mdx

@@ -0,0 +1,28 @@
+---
+title: Read a file as a ReadableStream
+sidebarTitle: Read as stream
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.stream()` to consume the file incrementally as a `ReadableStream`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const stream = file.stream();
+```
+
+---
+
+The chunks of the stream can be consumed as an [async iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) using `for await`.
+
+```ts
+for await (const chunk of stream) {
+  chunk; // => Uint8Array
+}
+```
+
+---
+
+Refer to the [Streams](https://bun.com/docs/api/streams) documentation for more information on working with streams in Bun.

package/docs/guides/read-file/string.mdx

@@ -0,0 +1,24 @@
+---
+title: Read a file as a string
+sidebarTitle: Read as string
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.text()` to read the contents as a string.
+
+```ts
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
+
+const text = await file.text();
+// string
+```
+
+---
+
+Any relative paths will be resolved relative to the project root (the nearest directory containing a `package.json` file).
+
+```ts
+const path = "./file.txt";
+const file = Bun.file(path);
+```

package/docs/guides/read-file/uint8array.mdx

@@ -0,0 +1,23 @@
+---
+title: Read a file to a Uint8Array
+sidebarTitle: Read to Uint8Array
+mode: center
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats.
+
+To read the file into a `Uint8Array` instance, retrieve the contents of the `BunFile` with `.bytes()`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const byteArray = await file.bytes();
+
+byteArray[0]; // first byteArray
+byteArray.length; // length of byteArray
+```
+
+---
+
+Refer to [API > Binary data > Typed arrays](https://bun.com/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.

package/docs/guides/read-file/watch.mdx

@@ -0,0 +1,66 @@
+---
+title: Watch a directory for changes
+sidebarTitle: Watch directory
+mode: center
+---
+
+Bun implements the `node:fs` module, including the `fs.watch` function for listening for file system changes.
+
+This code block listens for changes to files in the current directory. By default this operation is _shallow_, meaning that changes to files in subdirectories will not be detected.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+```
+
+---
+
+To listen to changes in subdirectories, pass the `recursive: true` option to `fs.watch`.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, { recursive: true }, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+```
+
+---
+
+Using the `node:fs/promises` module, you can listen for changes using `for await...of` instead of a callback.
+
+```ts
+import { watch } from "fs/promises";
+
+const watcher = watch(import.meta.dir);
+for await (const event of watcher) {
+  console.log(`Detected ${event.eventType} in ${event.filename}`);
+}
+```
+
+---
+
+To stop listening for changes, call `watcher.close()`. It's common to do this when the process receives a `SIGINT` signal, such as when the user presses Ctrl-C.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+
+process.on("SIGINT", () => {
+  // close watcher when Ctrl-C is pressed
+  console.log("Closing watcher...");
+  watcher.close();
+
+  process.exit(0);
+});
+```
+
+---
+
+Refer to [API > Binary data > Typed arrays](https://bun.com/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.