Add files (#3826)

9 files changed, 216 insertions, 0 deletions

diff --git a/docs/guides/write-file/basic.md b/docs/guides/write-file/basic.md
new file mode 100644
index 000000000..66f180a40
--- /dev/null
+++ b/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()`](/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](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/blob.md b/docs/guides/write-file/blob.md
new file mode 100644
index 000000000..a923190bf
--- /dev/null
+++ b/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()`](/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](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/cat.md b/docs/guides/write-file/cat.md
new file mode 100644
index 000000000..a9f9a0ba6
--- /dev/null
+++ b/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()`](/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](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/file-cp.md b/docs/guides/write-file/file-cp.md
new file mode 100644
index 000000000..b8910e269
--- /dev/null
+++ b/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()`](/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](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/filesink.md b/docs/guides/write-file/filesink.md
new file mode 100644
index 000000000..10ea792ee
--- /dev/null
+++ b/docs/guides/write-file/filesink.md
@@ -0,0 +1,52 @@
+---
+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](/docs/api/file-io#incremental-writing-with-filesink).
diff --git a/docs/guides/write-file/index.json b/docs/guides/write-file/index.json
new file mode 100644
index 000000000..dea48e215
--- /dev/null
+++ b/docs/guides/write-file/index.json
@@ -0,0 +1,4 @@
+{
+  "name": "Writing files",
+  "description": "A collection of guides for writing files with Bun"
+}
diff --git a/docs/guides/write-file/response.md b/docs/guides/write-file/response.md
new file mode 100644
index 000000000..fb2bd79eb
--- /dev/null
+++ b/docs/guides/write-file/response.md
@@ -0,0 +1,17 @@
+---
+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()`](/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.sh");
+const path = "./file.txt";
+await Bun.write(path, result);
+```
+
+---
+
+See [Docs > API > File I/O](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/stdout.md b/docs/guides/write-file/stdout.md
new file mode 100644
index 000000000..00fa11a60
--- /dev/null
+++ b/docs/guides/write-file/stdout.md
@@ -0,0 +1,21 @@
+---
+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()`](/docs/api/file-io#writing-files-bun-write).
+
+```ts
+await Bun.write(Bun.stdout, "Lorem ipsum");
+```
+
+---
+
+See [Docs > API > File I/O](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/write-file/stream.md b/docs/guides/write-file/stream.md
new file mode 100644
index 000000000..efb7efd8a
--- /dev/null
+++ b/docs/guides/write-file/stream.md
@@ -0,0 +1,17 @@
+---
+name: Write a ReadableStream to a file
+---
+
+To write a `ReadableStream` to disk, first create a `Response` instance from the stream. This `Response` can then be written to disk using [`Bun.write()`](/docs/api/file-io#writing-files-bun-write).
+
+```ts
+const stream: ReadableStream = ...;
+const path = "./file.txt";
+const response = new Response(stream);
+
+await Bun.write(path, response);
+```
+
+---
+
+See [Docs > API > File I/O](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.