initial commit

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. `BunFile` extends `Blob`, so you can read the file lazily 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();
+```
+
+---
+
+Read the binary content of the `ArrayBuffer` with a typed array, such as `Int8Array`. For `Uint8Array`, use [`.bytes()`](/guides/read-file/uint8array).
+
+```ts index.ts icon="/icons/typescript.svg"
+const buffer = await file.arrayBuffer();
+const bytes = new Int8Array(buffer);
+
+bytes[0];
+bytes.length;
+```
+
+---
+
+See [Typed arrays](/runtime/binary-data#typedarray) for more on working with typed arrays in Bun.

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. `BunFile` extends `Blob`, so you can read the file lazily in a variety of formats.
+
+To read the file into a `Buffer`, read it as an `ArrayBuffer` with `.arrayBuffer()`, then pass the result to `Buffer.from()`.
+
+```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);
+```
+
+---
+
+See [Buffer](/runtime/binary-data#buffer) for more on working with `Buffer` and other binary data formats in Bun.

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;
+```
+
+---
+
+See [File I/O](/runtime/file-io) for more on working with `BunFile`.

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. `BunFile` extends `Blob`, so you can read the file lazily in a variety of formats. Use `.json()` to read and parse the contents of a `.json` file as a plain object.
+
+Bun sets the MIME type of the `BunFile` 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";
+```

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;charset=utf-8
+
+const html = Bun.file("./index.html");
+html.type; // text/html;charset=utf-8
+
+const image = Bun.file("./image.png");
+image.type; // image/png
+```
+
+---
+
+See [File I/O](/runtime/file-io) for more on working with `BunFile`.

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. `BunFile` extends `Blob`, so you can read the file lazily 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 stream is an [async iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols), so you can read its chunks with `for await`.
+
+```ts
+for await (const chunk of stream) {
+  chunk; // => Uint8Array
+}
+```
+
+---
+
+See [Streams](/runtime/streams) for more on working with streams in Bun.

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. `BunFile` extends `Blob`, so you can read the file lazily 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
+```
+
+---
+
+Bun resolves relative paths from the current working directory.
+
+```ts
+const path = "./file.txt";
+const file = Bun.file(path);
+```

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. `BunFile` extends `Blob`, so you can read the file lazily in a variety of formats.
+
+To read the file into a `Uint8Array`, use `.bytes()`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const byteArray = await file.bytes();
+
+byteArray[0]; // first byte
+byteArray.length; // length of byteArray
+```
+
+---
+
+See [Typed arrays](/runtime/binary-data#typedarray) for more on working with `Uint8Array` and other binary data formats in Bun.

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.
+
+The following code listens for changes to files in the current directory. By default the watch is _shallow_: it does not detect changes to files in subdirectories.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+```
+
+---
+
+To listen for 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, relativePath) => {
+  console.log(`Detected ${event} in ${relativePath}`);
+});
+```
+
+---
+
+With the `node:fs/promises` module, you can listen for changes with `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);
+});
+```
+
+---
+
+See the [Node.js documentation](https://nodejs.org/api/fs.html#fswatchfilename-options-listener) for `fs.watch`.