@rcompat/io 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) Terrablue <terrablue@proton.me> and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# @rcompat/io
+
+Standard input/output utilities for JavaScript runtimes.
+
+## What is @rcompat/io?
+
+A cross-runtime module providing access to standard streams (stdin, stdout,
+stderr) and process utilities like executing commands, spawning processes,
+and reading user input. Works consistently across Node, Deno, and Bun.
+
+## Installation
+
+```bash
+npm install @rcompat/io
+```
+
+```bash
+pnpm add @rcompat/io
+```
+
+```bash
+yarn add @rcompat/io
+```
+
+```bash
+bun add @rcompat/io
+```
+
+## Usage
+
+### Standard streams
+
+```js
+import io from "@rcompat/io";
+
+// write to stdout (no newline)
+io.stdout.write("Hello, ");
+io.stdout.write("World!\n");
+
+// write to stderr
+io.stderr.write("Error: something went wrong\n");
+```
+
+### Check if running in a terminal
+
+```js
+import io from "@rcompat/io";
+
+if (io.isatty()) {
+  // interactive terminal - show colors, prompts, etc.
+  console.log("\x1b[32mGreen text!\x1b[0m");
+} else {
+  // piped or redirected - plain output
+  console.log("Plain text");
+}
+```
+
+### Run a command
+
+```js
+import io from "@rcompat/io";
+
+// get command output as string
+const output = await io.run("echo hello");
+console.log(output); // "hello\n"
+
+// with options
+const files = await io.run("ls -la", { cwd: "/tmp" });
+```
+
+### Spawn a process
+
+```js
+import io from "@rcompat/io";
+
+const { stdin, stdout, stderr } = io.spawn("cat", { cwd: "." });
+
+// write to process stdin (Web WritableStream)
+const writer = stdin.getWriter();
+await writer.write(new TextEncoder().encode("Hello from stdin!"));
+await writer.close();
+
+// read from process stdout (Web ReadableStream)
+const reader = stdout.getReader();
+const { value } = await reader.read();
+console.log(new TextDecoder().decode(value)); // "Hello from stdin!"
+```
+
+### Find an executable
+
+```js
+import io from "@rcompat/io";
+
+const node = await io.which("node");
+console.log(node); // "/usr/local/bin/node"
+
+const bun = await io.which("bun");
+console.log(bun); // "/home/user/.bun/bin/bun"
+```
+
+## API Reference
+
+### `stdin`
+
+```ts
+import io from "@rcompat/io";
+io.stdin;
+```
+
+The standard input stream. A `ReadStream` for reading user input.
+
+### `stdout`
+
+```ts
+import io from "@rcompat/io";
+
+io.stdout.write(data: string | Uint8Array): boolean;
+```
+
+The standard output stream. Use `write()` to output without a newline.
+
+### `stderr`
+
+```ts
+import io from "@rcompat/io";
+
+io.stderr.write(data: string | Uint8Array): boolean;
+```
+
+The standard error stream. Use for error messages and diagnostics.
+
+### `isatty`
+
+```ts
+import io from "@rcompat/io";
+
+io.isatty(): boolean;
+```
+
+Returns `true` if stdout is connected to a terminal (TTY).
+
+### `run`
+
+```ts
+import io from "@rcompat/io";
+
+io.run(command: string, options?: ExecOptions): Promise<string>;
+```
+
+Runs a shell command and returns its stdout as a string. Rejects on error.
+
+| Parameter | Type          | Description                |
+| --------- | ------------- | -------------------------- |
+| `command` | `string`      | Shell command to execute   |
+| `options` | `ExecOptions` | Optional execution options |
+
+Options include `cwd`, `env`, `timeout`, `maxBuffer`, etc.
+
+### `spawn`
+
+```ts
+import io from "@rcompat/io";
+
+io.spawn(command: string, options: SpawnOptions): {
+  stdin: WritableStream<Uint8Array>;
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+};
+```
+
+Spawns a process and returns Web Streams for I/O.
+
+| Parameter | Type           | Description               |
+| --------- | -------------- | ------------------------- |
+| `command` | `string`       | Command to spawn          |
+| `options` | `SpawnOptions` | Spawn options (e.g., cwd) |
+
+### `which`
+
+```ts
+import io from "@rcompat/io";
+
+io.which(command: string): Promise<string>;
+```
+
+Finds the full path to an executable. Cross-platform (uses `which` on Unix,
+`where` on Windows).
+
+## Examples
+
+### Run a command and process output
+
+```js
+import io from "@rcompat/io";
+
+async function getBranch() {
+  try {
+    const branch = await io.run("git branch --show-current");
+    return branch.trim();
+  } catch {
+    return null;
+  }
+}
+
+const branch = await getBranch();
+console.log(`Current branch: ${branch ?? "not a git repo"}`);
+```
+
+### Stream processing with spawn
+
+```js
+import io from "@rcompat/io";
+
+const { stdout } = io.spawn("ping -c 3 localhost", { cwd: "." });
+
+const reader = stdout.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  process.stdout.write(decoder.decode(value));
+}
+```
+
+### Check for required tools
+
+```js
+import io from "@rcompat/io";
+
+async function checkDependencies(tools) {
+  const missing = [];
+
+  for (const tool of tools) {
+    try {
+      await io.which(tool);
+    } catch {
+      missing.push(tool);
+    }
+  }
+
+  return missing;
+}
+
+const missing = await checkDependencies(["git", "node", "docker"]);
+
+if (missing.length > 0) {
+  console.error(`Missing tools: ${missing.join(", ")}`);
+  process.exit(1);
+}
+```
+
+### Conditional formatting
+
+```js
+import io from "@rcompat/io";
+
+function log(message, color = 32) {
+  if (io.isatty()) {
+    io.stdout.write(`\x1b[${color}m${message}\x1b[0m\n`);
+  } else {
+    io.stdout.write(`${message}\n`);
+  }
+}
+
+log("Success!", 32); // green in terminal, plain when piped
+log("Warning!", 33); // yellow in terminal
+log("Error!", 31); // red in terminal
+```
+
+## Cross-Runtime Compatibility
+
+| Runtime | Supported |
+| ------- | --------- |
+| Node.js | ✓         |
+| Deno    | ✓         |
+| Bun     | ✓         |
+
+No configuration required — just import and use.
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) in the repository root.

package/lib/private/async/context.d.ts

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export default AsyncLocalStorage;
+//# sourceMappingURL=context.d.ts.map

package/lib/private/async/context.js

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export default AsyncLocalStorage;
+//# sourceMappingURL=context.js.map

package/lib/private/async.d.ts

@@ -0,0 +1,6 @@
+declare namespace _default {
+    export { context };
+}
+export default _default;
+import context from "#async/context";
+//# sourceMappingURL=async.d.ts.map

package/lib/private/async.js

@@ -0,0 +1,5 @@
+import context from "#async/context";
+export default {
+    context,
+};
+//# sourceMappingURL=async.js.map

package/lib/private/index.d.ts

@@ -0,0 +1,24 @@
+declare const _default: {
+    async: {
+        context: typeof import("node:async_hooks").AsyncLocalStorage;
+    };
+    isatty: () => boolean;
+    run: (command: string, options?: import("node:child_process").ExecOptions) => Promise<string>;
+    spawn: (command: string, options: import("node:child_process").SpawnOptions) => {
+        stderr: import("node:stream/web").ReadableStream<any>;
+        stdin: import("node:stream/web").WritableStream<any>;
+        stdout: import("node:stream/web").ReadableStream<any>;
+    };
+    stderr: NodeJS.WriteStream & {
+        fd: 2;
+    };
+    stdin: NodeJS.ReadStream & {
+        fd: 0;
+    };
+    stdout: NodeJS.WriteStream & {
+        fd: 1;
+    };
+    which: (command: string) => Promise<string>;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/lib/private/index.js

@@ -0,0 +1,19 @@
+import async from "#async";
+import isatty from "#isatty";
+import run from "#run";
+import spawn from "#spawn";
+import stderr from "#std/err";
+import stdin from "#std/in";
+import stdout from "#std/out";
+import which from "#which";
+export default {
+    async,
+    isatty,
+    run,
+    spawn,
+    stderr,
+    stdin,
+    stdout,
+    which,
+};
+//# sourceMappingURL=index.js.map

package/lib/private/isatty.d.ts

@@ -0,0 +1,3 @@
+declare const _default: () => boolean;
+export default _default;
+//# sourceMappingURL=isatty.d.ts.map

package/lib/private/isatty.js

@@ -0,0 +1,2 @@
+export default () => Boolean(process.stdout.isTTY);
+//# sourceMappingURL=isatty.js.map

package/lib/private/run.d.ts

@@ -0,0 +1,4 @@
+import { type ExecOptions } from "node:child_process";
+declare const _default: (command: string, options?: ExecOptions) => Promise<string>;
+export default _default;
+//# sourceMappingURL=run.d.ts.map

package/lib/private/run.js

@@ -0,0 +1,5 @@
+import { exec } from "node:child_process";
+export default (command, options) => new Promise((resolve, reject) => {
+    exec(command, options ?? {}, (error, stdout, stderr) => error === null ? resolve(stdout) : reject(stderr));
+});
+//# sourceMappingURL=run.js.map

package/lib/private/spawn.d.ts

@@ -0,0 +1,8 @@
+import { type SpawnOptions } from "node:child_process";
+declare const _default: (command: string, options: SpawnOptions) => {
+    stderr: import("node:stream/web").ReadableStream<any>;
+    stdin: import("node:stream/web").WritableStream<any>;
+    stdout: import("node:stream/web").ReadableStream<any>;
+};
+export default _default;
+//# sourceMappingURL=spawn.d.ts.map

package/lib/private/spawn.js

@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+export default (command, options) => {
+    const { stderr, stdin, stdout } = spawn(command, {
+        ...options,
+        shell: true,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    return {
+        stderr: Readable.toWeb(stderr),
+        stdin: Writable.toWeb(stdin),
+        stdout: Readable.toWeb(stdout),
+    };
+};
+//# sourceMappingURL=spawn.js.map

package/lib/private/std/err.d.ts

@@ -0,0 +1,2 @@
+export { stderr as default } from "node:process";
+//# sourceMappingURL=err.d.ts.map

package/lib/private/std/err.js

@@ -0,0 +1,2 @@
+export { stderr as default } from "node:process";
+//# sourceMappingURL=err.js.map

package/lib/private/std/in.d.ts

@@ -0,0 +1,2 @@
+export { stdin as default } from "node:process";
+//# sourceMappingURL=in.d.ts.map

package/lib/private/std/in.js

@@ -0,0 +1,2 @@
+export { stdin as default } from "node:process";
+//# sourceMappingURL=in.js.map

package/lib/private/std/out.d.ts

@@ -0,0 +1,2 @@
+export { stdout as default } from "node:process";
+//# sourceMappingURL=out.d.ts.map

package/lib/private/std/out.js

@@ -0,0 +1,2 @@
+export { stdout as default } from "node:process";
+//# sourceMappingURL=out.js.map

package/lib/private/which.d.ts

@@ -0,0 +1,3 @@
+declare const _default: (command: string) => Promise<string>;
+export default _default;
+//# sourceMappingURL=which.d.ts.map

package/lib/private/which.js

@@ -0,0 +1,6 @@
+import run from "#run";
+const is_win = process.platform === "win32";
+const which = is_win ? "where" : "which";
+const qualify = (path) => is_win ? `"${path}"` : path;
+export default async (command) => qualify(await run(`${which} ${command}`, {})).replaceAll("\n", "");
+//# sourceMappingURL=which.js.map

package/lib/public/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "#index";
+//# sourceMappingURL=index.d.ts.map

package/lib/public/index.js

@@ -0,0 +1,2 @@
+export { default } from "#index";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rcompat/io",
+  "version": "0.1.0",
+  "description": "Standard library input/output",
+  "bugs": "https://github.com/rcompat/rcompat/issues",
+  "license": "MIT",
+  "files": [
+    "/lib/**/*.js",
+    "/lib/**/*.d.ts",
+    "!/**/*.spec.*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rcompat/rcompat",
+    "directory": "packages/io"
+  },
+  "type": "module",
+  "imports": {
+    "#*": {
+      "apekit": "./src/private/*.ts",
+      "default": "./lib/private/*.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "apekit": "./src/public/index.ts",
+      "default": "./lib/public/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "test": "npm run build && npx proby",
+    "clean": "rm -rf ./lib"
+  }
+}