Add files (#3826)

9 files changed, 246 insertions, 0 deletions

diff --git a/docs/guides/process/argv.md b/docs/guides/process/argv.md
new file mode 100644
index 000000000..f9f3c77e4
--- /dev/null
+++ b/docs/guides/process/argv.md
@@ -0,0 +1,22 @@
+---
+name: Parse command-line arguments
+---
+
+The _argument vector_ is the list of arguments passed to the program when it is run. It is available as `Bun.argv`.
+
+```ts#cli.ts
+console.log(Bun.argv);
+```
+
+---
+
+Running this file with arguments results in the following:
+
+```sh
+$ bun run cli.tsx --flag1 --flag2 value
+[ '/path/to/bun', '/path/to/cli.ts', '--flag1', '--flag2', 'value' ]
+```
+
+---
+
+To parse `argv` into a more useful format, consider using [minimist](https://github.com/minimistjs/minimist) or [commander](https://github.com/tj/commander.js).
diff --git a/docs/guides/process/ctrl-c.md b/docs/guides/process/ctrl-c.md
new file mode 100644
index 000000000..b880cf62c
--- /dev/null
+++ b/docs/guides/process/ctrl-c.md
@@ -0,0 +1,16 @@
+---
+name: Listen for CTRL+C
+---
+
+The `ctrl+c` shortcut sends an _interrupt signal_ to the running process. This signal can be intercepted by listening for the `SIGINT` event. If you want to close the process, you must explicitly call `process.exit()`.
+
+```ts
+process.on("SIGINT", () => {
+  console.log("Ctrl-C was pressed");
+  process.exit();
+});
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/process/index.json b/docs/guides/process/index.json
new file mode 100644
index 000000000..df0384544
--- /dev/null
+++ b/docs/guides/process/index.json
@@ -0,0 +1,4 @@
+{
+  "name": "Processes",
+  "description": "A collection of guides for inspecting the current process and creating child processes with Bun"
+}
diff --git a/docs/guides/process/nanoseconds.md b/docs/guides/process/nanoseconds.md
new file mode 100644
index 000000000..b8aee8123
--- /dev/null
+++ b/docs/guides/process/nanoseconds.md
@@ -0,0 +1,13 @@
+---
+name: Get the process uptime in nanoseconds
+---
+
+Use `Bun.nanoseconds()` to get the total number of nanoseconds the `bun` process has been alive.
+
+```ts
+Bun.nanoseconds();
+```
+
+---
+
+See [Docs > API > Utils](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/process/os-signals.md b/docs/guides/process/os-signals.md
new file mode 100644
index 000000000..ae7b9896f
--- /dev/null
+++ b/docs/guides/process/os-signals.md
@@ -0,0 +1,39 @@
+---
+name: Listen to OS signals
+---
+
+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](/docs/api/utils) for more useful utilities.
diff --git a/docs/guides/process/spawn-stderr.md b/docs/guides/process/spawn-stderr.md
new file mode 100644
index 000000000..3ea56b24e
--- /dev/null
+++ b/docs/guides/process/spawn-stderr.md
@@ -0,0 +1,31 @@
+---
+name: Read stderr from a child process
+---
+
+When using [`Bun.spawn()`](/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 the [`Bun.readableStreamToText()`](/docs/api/utils#bun-readablestreamto) convenience function.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stderr: "pipe",
+});
+
+const errors: string = await Bun.readableStreamToText(proc.stderr);
+if (errors) {
+  // handle errors
+}
+```
+
+---
+
+See [Docs > API > Child processes](/docs/api/spawn) for complete documentation..
diff --git a/docs/guides/process/spawn-stdout.md b/docs/guides/process/spawn-stdout.md
new file mode 100644
index 000000000..490e8b143
--- /dev/null
+++ b/docs/guides/process/spawn-stdout.md
@@ -0,0 +1,26 @@
+---
+name: Read stdout from a child process
+---
+
+When using [`Bun.spawn()`](/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 new Response(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](/docs/api/spawn) for complete documentation..
diff --git a/docs/guides/process/spawn.md b/docs/guides/process/spawn.md
new file mode 100644
index 000000000..2a6589458
--- /dev/null
+++ b/docs/guides/process/spawn.md
@@ -0,0 +1,41 @@
+---
+name: Spawn a child process
+---
+
+Use [`Bun.spawn()`](/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 new Response(proc.stdout).text();
+output; // => "hello"
+```
+
+---
+
+See [Docs > API > Child processes](/docs/api/spawn) for complete documentation..
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.