Add files (#3826)

10 files changed, 259 insertions, 0 deletions

diff --git a/docs/guides/read-file/arraybuffer.md b/docs/guides/read-file/arraybuffer.md
new file mode 100644
index 000000000..149b08d8e
--- /dev/null
+++ b/docs/guides/read-file/arraybuffer.md
@@ -0,0 +1,28 @@
+---
+name: Read a file to an ArrayBuffer
+---
+
+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
+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 `Uint8Array`.
+
+```ts
+const buffer = await file.arrayBuffer();
+const bytes = new Uint8Array(buffer);
+
+bytes[0];
+bytes.length;
+```
+
+---
+
+Refer to the [Typed arrays](/docs/api/binary-data#typedarray) docs for more information on working with typed arrays in Bun.
diff --git a/docs/guides/read-file/buffer.md b/docs/guides/read-file/buffer.md
new file mode 100644
index 000000000..d27fa1489
--- /dev/null
+++ b/docs/guides/read-file/buffer.md
@@ -0,0 +1,19 @@
+---
+name: Read a file to a Buffer
+---
+
+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
+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](/docs/api/binary-data#buffer) for more information on working with `Buffer` and other binary data formats in Bun.
diff --git a/docs/guides/read-file/exists.md b/docs/guides/read-file/exists.md
new file mode 100644
index 000000000..fd6cbbf9a
--- /dev/null
+++ b/docs/guides/read-file/exists.md
@@ -0,0 +1,16 @@
+---
+name: Check if a file exists
+---
+
+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
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+file.exists(); // boolean;
+```
+
+---
+
+Refer to [API > File I/O](/docs/api/file-io) for more information on working with `BunFile`.
diff --git a/docs/guides/read-file/index.json b/docs/guides/read-file/index.json
new file mode 100644
index 000000000..321fd96e2
--- /dev/null
+++ b/docs/guides/read-file/index.json
@@ -0,0 +1,4 @@
+{
+  "name": "Reading files",
+  "description": "A collection of guides for reading files with Bun"
+}
diff --git a/docs/guides/read-file/json.md b/docs/guides/read-file/json.md
new file mode 100644
index 000000000..3b7488472
--- /dev/null
+++ b/docs/guides/read-file/json.md
@@ -0,0 +1,34 @@
+---
+name: Read a JSON file
+---
+
+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.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const contents = await file.json();
+// { name: "my-package" }
+```
+
+---
+
+The MIME type of the `BunFile` will be set accordingly.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+file.type; // => "application/json;charset=utf-8";
+```
+
+---
+
+If the path to the `.json` file is static, it can be directly imported as a module.
+
+```ts
+import pkg from "./package.json";
+
+pkg.name; // => "my-package"
+```
diff --git a/docs/guides/read-file/mime.md b/docs/guides/read-file/mime.md
new file mode 100644
index 000000000..44a8e6860
--- /dev/null
+++ b/docs/guides/read-file/mime.md
@@ -0,0 +1,20 @@
+---
+name: Get the MIME type of a file
+---
+
+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](/docs/api/file-io) for more information on working with `BunFile`.
diff --git a/docs/guides/read-file/stream.md b/docs/guides/read-file/stream.md
new file mode 100644
index 000000000..6b88c3672
--- /dev/null
+++ b/docs/guides/read-file/stream.md
@@ -0,0 +1,26 @@
+---
+name: Read a file as a ReadableStream
+---
+
+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 = await file.stream();
+```
+
+---
+
+The chunks of the stream can be consumed with `for await`.
+
+```ts
+for await (const chunk of stream.values()) {
+  chunk; // => Uint8Array
+}
+```
+
+---
+
+Refer to the [Streams](/docs/api/streams) documentation for more information on working with streams in Bun.
diff --git a/docs/guides/read-file/string.md b/docs/guides/read-file/string.md
new file mode 100644
index 000000000..08cdfd952
--- /dev/null
+++ b/docs/guides/read-file/string.md
@@ -0,0 +1,22 @@
+---
+name: Read a file as a string
+---
+
+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);
+```
diff --git a/docs/guides/read-file/uint8array.md b/docs/guides/read-file/uint8array.md
new file mode 100644
index 000000000..1afcaa797
--- /dev/null
+++ b/docs/guides/read-file/uint8array.md
@@ -0,0 +1,22 @@
+---
+name: Read a file to a Uint8Array
+---
+
+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` as an `ArrayBuffer` with `.arrayBuffer()`, then pass it into the `Uint8Array` constructor.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const arrBuffer = await file.arrayBuffer();
+const byteArray = new Uint8Array(arrBuffer);
+
+byteArray[0]; // first byteArray
+byteArray.length; // length of byteArray
+```
+
+---
+
+Refer to [API > Binary data > Typed arrays](/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.
diff --git a/docs/guides/read-file/watch.md b/docs/guides/read-file/watch.md
new file mode 100644
index 000000000..0c38a0ece
--- /dev/null
+++ b/docs/guides/read-file/watch.md
@@ -0,0 +1,68 @@
+---
+name: Watch a directory for changes
+---
+
+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](/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.