From 4c89c60867591b50e0b31bf5009fd5ad6a3cebe1 Mon Sep 17 00:00:00 2001
From: Colin McDonnell <colinmcd94@gmail.com>
Date: Wed, 26 Jul 2023 14:59:39 -0700
Subject: Add files (#3826)

---
 docs/guides/process/stdin.md | 54 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/guides/process/stdin.md

(limited to 'docs/guides/process/stdin.md')

diff --git a/docs/guides/process/stdin.md b/docs/guides/process/stdin.md
new file mode 100644
index 000000000..c19c9e106
--- /dev/null
+++ b/docs/guides/process/stdin.md
@@ -0,0 +1,54 @@
+---
+name: Read from stdin
+---
+
+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
+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
+$ bun run index.tsx
+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
+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
+$ echo "hello" | bun run stdin.ts
+Chunk: hello
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
-- 
cgit v1.2.3