@optique/run 1.3.1 → 1.3.3

package/dist/output.cjs

@@ -0,0 +1,127 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+
+//#region src/output.ts
+let sleepCell;
+function sleepSync(ms) {
+	sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+function getErrorCode(error) {
+	return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
+}
+/**
+* Writes all of the given bytes to a file descriptor synchronously.
+*
+* Partial writes resume from the next unwritten byte.  When the descriptor
+* is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+* briefly and retries, blocking the current thread until the reader catches
+* up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+* (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+* silently.
+*
+* @param fd The file descriptor to write to.
+* @param bytes The bytes to write.
+* @param deps Dependencies to use instead of the defaults, for testing.
+* @throws {Error} If writing fails for any other reason, or if a write makes
+*         no progress.
+* @internal
+*/
+function writeAllSync(fd, bytes, deps = {}) {
+	const writeSync = deps.writeSync ?? node_fs.writeSync;
+	const sleep = deps.sleep ?? sleepSync;
+	let offset = 0;
+	while (offset < bytes.length) {
+		let written;
+		try {
+			written = writeSync(fd, bytes, offset, bytes.length - offset);
+		} catch (error) {
+			const code = getErrorCode(error);
+			if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+				sleep(1);
+				continue;
+			}
+			if (code === "EINTR") continue;
+			if (code === "EPIPE" || code === "ECONNRESET") return;
+			throw error;
+		}
+		if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
+		offset += written;
+	}
+}
+/**
+* Reads the encoding a writable stream applies to strings, which
+* `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+* the stream's internal state, so this returns `undefined` when that is not
+* available.
+*
+* @param stream The stream to inspect.
+* @returns The default encoding, or `undefined` if it cannot be read.
+* @internal
+*/
+function getDefaultEncoding(stream) {
+	if (!("_writableState" in stream)) return void 0;
+	const state = stream._writableState;
+	return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
+}
+function isUtf8Encoding(encoding) {
+	return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
+}
+/**
+* Decides whether output for the given stream should bypass the stream and
+* be written directly to its file descriptor.
+*
+* TTYs keep going through the stream, since terminal writes are synchronous
+* on POSIX and Windows consoles need the stream's own handling.  Windows is
+* excluded altogether.  Streams without a file descriptor, such as
+* `process.stdout` in a Node.js worker thread, also keep going through the
+* stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+* Deno is excluded as well: its streams do not lose queued output on exit,
+* and its `fs.writeSync()` can write part of the buffer to a non-blocking
+* pipe and then throw `EAGAIN` without reporting how much it wrote, which
+* would make retrying duplicate output.  Finally, streams whose default
+* encoding is not UTF-8 keep going through the stream, since direct writes
+* always encode the text as UTF-8.
+*
+* @param stream The stream to inspect.
+* @param platform The value of `process.platform`.
+* @param deno Whether the current runtime is Deno.
+* @returns `true` if output should be written directly to `stream.fd`.
+* @internal
+*/
+function shouldWriteDirectly(stream, platform, deno) {
+	const fd = stream.fd;
+	return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
+}
+const encoder = new TextEncoder();
+/**
+* Writes text to standard output or standard error such that, when the
+* stream is a pipe or a file, the text has been completely handed to the
+* operating system by the time this returns (unless the reader closed the
+* pipe).  Otherwise, it falls back to the stream's `write()` method.
+*
+* Note that output queued in the stream by earlier `write()` calls is not
+* flushed, and that text written directly can overtake it.
+*
+* @param streamName The stream to write to.
+* @param text The text to write.
+* @throws {Error} If writing to the file descriptor fails.
+* @internal
+*/
+function writeOutput(streamName, text) {
+	const stream = node_process.default[streamName];
+	const streamLike = {
+		isTTY: stream.isTTY,
+		fd: stream.fd,
+		defaultEncoding: getDefaultEncoding(stream)
+	};
+	if (shouldWriteDirectly(streamLike, node_process.default.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
+	else stream.write(text);
+}
+
+//#endregion
+exports.getDefaultEncoding = getDefaultEncoding;
+exports.shouldWriteDirectly = shouldWriteDirectly;
+exports.writeAllSync = writeAllSync;
+exports.writeOutput = writeOutput;

package/dist/output.d.cts

@@ -0,0 +1,98 @@
+//#region src/output.d.ts
+/**
+ * Dependencies of {@link writeAllSync}, injectable for testing.
+ * @internal
+ */
+interface WriteAllSyncDeps {
+  /**
+   * Writes bytes to a file descriptor and returns how many bytes were
+   * written.
+   * @default `writeSync()` from `node:fs`
+   */
+  readonly writeSync?: (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+  /**
+   * Blocks the current thread for the given number of milliseconds.
+   * @default A sleep based on `Atomics.wait()`
+   */
+  readonly sleep?: (ms: number) => void;
+}
+/**
+ * Writes all of the given bytes to a file descriptor synchronously.
+ *
+ * Partial writes resume from the next unwritten byte.  When the descriptor
+ * is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+ * briefly and retries, blocking the current thread until the reader catches
+ * up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+ * (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+ * silently.
+ *
+ * @param fd The file descriptor to write to.
+ * @param bytes The bytes to write.
+ * @param deps Dependencies to use instead of the defaults, for testing.
+ * @throws {Error} If writing fails for any other reason, or if a write makes
+ *         no progress.
+ * @internal
+ */
+declare function writeAllSync(fd: number, bytes: Uint8Array, deps?: WriteAllSyncDeps): void;
+/**
+ * The subset of a writable stdio stream that {@link shouldWriteDirectly}
+ * inspects.
+ * @internal
+ */
+interface StdioStreamLike {
+  readonly isTTY?: boolean;
+  readonly fd?: unknown;
+  /** The encoding the stream applies to strings, if known. */
+  readonly defaultEncoding?: unknown;
+}
+/**
+ * Reads the encoding a writable stream applies to strings, which
+ * `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+ * the stream's internal state, so this returns `undefined` when that is not
+ * available.
+ *
+ * @param stream The stream to inspect.
+ * @returns The default encoding, or `undefined` if it cannot be read.
+ * @internal
+ */
+declare function getDefaultEncoding(stream: object): unknown;
+/**
+ * Decides whether output for the given stream should bypass the stream and
+ * be written directly to its file descriptor.
+ *
+ * TTYs keep going through the stream, since terminal writes are synchronous
+ * on POSIX and Windows consoles need the stream's own handling.  Windows is
+ * excluded altogether.  Streams without a file descriptor, such as
+ * `process.stdout` in a Node.js worker thread, also keep going through the
+ * stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+ * Deno is excluded as well: its streams do not lose queued output on exit,
+ * and its `fs.writeSync()` can write part of the buffer to a non-blocking
+ * pipe and then throw `EAGAIN` without reporting how much it wrote, which
+ * would make retrying duplicate output.  Finally, streams whose default
+ * encoding is not UTF-8 keep going through the stream, since direct writes
+ * always encode the text as UTF-8.
+ *
+ * @param stream The stream to inspect.
+ * @param platform The value of `process.platform`.
+ * @param deno Whether the current runtime is Deno.
+ * @returns `true` if output should be written directly to `stream.fd`.
+ * @internal
+ */
+declare function shouldWriteDirectly(stream: StdioStreamLike, platform: string, deno: boolean): boolean;
+/**
+ * Writes text to standard output or standard error such that, when the
+ * stream is a pipe or a file, the text has been completely handed to the
+ * operating system by the time this returns (unless the reader closed the
+ * pipe).  Otherwise, it falls back to the stream's `write()` method.
+ *
+ * Note that output queued in the stream by earlier `write()` calls is not
+ * flushed, and that text written directly can overtake it.
+ *
+ * @param streamName The stream to write to.
+ * @param text The text to write.
+ * @throws {Error} If writing to the file descriptor fails.
+ * @internal
+ */
+declare function writeOutput(streamName: "stdout" | "stderr", text: string): void;
+//#endregion
+export { StdioStreamLike, WriteAllSyncDeps, getDefaultEncoding, shouldWriteDirectly, writeAllSync, writeOutput };

package/dist/output.d.ts

@@ -0,0 +1,98 @@
+//#region src/output.d.ts
+/**
+ * Dependencies of {@link writeAllSync}, injectable for testing.
+ * @internal
+ */
+interface WriteAllSyncDeps {
+  /**
+   * Writes bytes to a file descriptor and returns how many bytes were
+   * written.
+   * @default `writeSync()` from `node:fs`
+   */
+  readonly writeSync?: (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+  /**
+   * Blocks the current thread for the given number of milliseconds.
+   * @default A sleep based on `Atomics.wait()`
+   */
+  readonly sleep?: (ms: number) => void;
+}
+/**
+ * Writes all of the given bytes to a file descriptor synchronously.
+ *
+ * Partial writes resume from the next unwritten byte.  When the descriptor
+ * is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+ * briefly and retries, blocking the current thread until the reader catches
+ * up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+ * (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+ * silently.
+ *
+ * @param fd The file descriptor to write to.
+ * @param bytes The bytes to write.
+ * @param deps Dependencies to use instead of the defaults, for testing.
+ * @throws {Error} If writing fails for any other reason, or if a write makes
+ *         no progress.
+ * @internal
+ */
+declare function writeAllSync(fd: number, bytes: Uint8Array, deps?: WriteAllSyncDeps): void;
+/**
+ * The subset of a writable stdio stream that {@link shouldWriteDirectly}
+ * inspects.
+ * @internal
+ */
+interface StdioStreamLike {
+  readonly isTTY?: boolean;
+  readonly fd?: unknown;
+  /** The encoding the stream applies to strings, if known. */
+  readonly defaultEncoding?: unknown;
+}
+/**
+ * Reads the encoding a writable stream applies to strings, which
+ * `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+ * the stream's internal state, so this returns `undefined` when that is not
+ * available.
+ *
+ * @param stream The stream to inspect.
+ * @returns The default encoding, or `undefined` if it cannot be read.
+ * @internal
+ */
+declare function getDefaultEncoding(stream: object): unknown;
+/**
+ * Decides whether output for the given stream should bypass the stream and
+ * be written directly to its file descriptor.
+ *
+ * TTYs keep going through the stream, since terminal writes are synchronous
+ * on POSIX and Windows consoles need the stream's own handling.  Windows is
+ * excluded altogether.  Streams without a file descriptor, such as
+ * `process.stdout` in a Node.js worker thread, also keep going through the
+ * stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+ * Deno is excluded as well: its streams do not lose queued output on exit,
+ * and its `fs.writeSync()` can write part of the buffer to a non-blocking
+ * pipe and then throw `EAGAIN` without reporting how much it wrote, which
+ * would make retrying duplicate output.  Finally, streams whose default
+ * encoding is not UTF-8 keep going through the stream, since direct writes
+ * always encode the text as UTF-8.
+ *
+ * @param stream The stream to inspect.
+ * @param platform The value of `process.platform`.
+ * @param deno Whether the current runtime is Deno.
+ * @returns `true` if output should be written directly to `stream.fd`.
+ * @internal
+ */
+declare function shouldWriteDirectly(stream: StdioStreamLike, platform: string, deno: boolean): boolean;
+/**
+ * Writes text to standard output or standard error such that, when the
+ * stream is a pipe or a file, the text has been completely handed to the
+ * operating system by the time this returns (unless the reader closed the
+ * pipe).  Otherwise, it falls back to the stream's `write()` method.
+ *
+ * Note that output queued in the stream by earlier `write()` calls is not
+ * flushed, and that text written directly can overtake it.
+ *
+ * @param streamName The stream to write to.
+ * @param text The text to write.
+ * @throws {Error} If writing to the file descriptor fails.
+ * @internal
+ */
+declare function writeOutput(streamName: "stdout" | "stderr", text: string): void;
+//#endregion
+export { StdioStreamLike, WriteAllSyncDeps, getDefaultEncoding, shouldWriteDirectly, writeAllSync, writeOutput };

package/dist/output.js

@@ -0,0 +1,123 @@
+import { writeSync } from "node:fs";
+import process from "node:process";
+
+//#region src/output.ts
+let sleepCell;
+function sleepSync(ms) {
+	sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+function getErrorCode(error) {
+	return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
+}
+/**
+* Writes all of the given bytes to a file descriptor synchronously.
+*
+* Partial writes resume from the next unwritten byte.  When the descriptor
+* is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+* briefly and retries, blocking the current thread until the reader catches
+* up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+* (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+* silently.
+*
+* @param fd The file descriptor to write to.
+* @param bytes The bytes to write.
+* @param deps Dependencies to use instead of the defaults, for testing.
+* @throws {Error} If writing fails for any other reason, or if a write makes
+*         no progress.
+* @internal
+*/
+function writeAllSync(fd, bytes, deps = {}) {
+	const writeSync$1 = deps.writeSync ?? writeSync;
+	const sleep = deps.sleep ?? sleepSync;
+	let offset = 0;
+	while (offset < bytes.length) {
+		let written;
+		try {
+			written = writeSync$1(fd, bytes, offset, bytes.length - offset);
+		} catch (error) {
+			const code = getErrorCode(error);
+			if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+				sleep(1);
+				continue;
+			}
+			if (code === "EINTR") continue;
+			if (code === "EPIPE" || code === "ECONNRESET") return;
+			throw error;
+		}
+		if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
+		offset += written;
+	}
+}
+/**
+* Reads the encoding a writable stream applies to strings, which
+* `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+* the stream's internal state, so this returns `undefined` when that is not
+* available.
+*
+* @param stream The stream to inspect.
+* @returns The default encoding, or `undefined` if it cannot be read.
+* @internal
+*/
+function getDefaultEncoding(stream) {
+	if (!("_writableState" in stream)) return void 0;
+	const state = stream._writableState;
+	return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
+}
+function isUtf8Encoding(encoding) {
+	return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
+}
+/**
+* Decides whether output for the given stream should bypass the stream and
+* be written directly to its file descriptor.
+*
+* TTYs keep going through the stream, since terminal writes are synchronous
+* on POSIX and Windows consoles need the stream's own handling.  Windows is
+* excluded altogether.  Streams without a file descriptor, such as
+* `process.stdout` in a Node.js worker thread, also keep going through the
+* stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+* Deno is excluded as well: its streams do not lose queued output on exit,
+* and its `fs.writeSync()` can write part of the buffer to a non-blocking
+* pipe and then throw `EAGAIN` without reporting how much it wrote, which
+* would make retrying duplicate output.  Finally, streams whose default
+* encoding is not UTF-8 keep going through the stream, since direct writes
+* always encode the text as UTF-8.
+*
+* @param stream The stream to inspect.
+* @param platform The value of `process.platform`.
+* @param deno Whether the current runtime is Deno.
+* @returns `true` if output should be written directly to `stream.fd`.
+* @internal
+*/
+function shouldWriteDirectly(stream, platform, deno) {
+	const fd = stream.fd;
+	return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
+}
+const encoder = new TextEncoder();
+/**
+* Writes text to standard output or standard error such that, when the
+* stream is a pipe or a file, the text has been completely handed to the
+* operating system by the time this returns (unless the reader closed the
+* pipe).  Otherwise, it falls back to the stream's `write()` method.
+*
+* Note that output queued in the stream by earlier `write()` calls is not
+* flushed, and that text written directly can overtake it.
+*
+* @param streamName The stream to write to.
+* @param text The text to write.
+* @throws {Error} If writing to the file descriptor fails.
+* @internal
+*/
+function writeOutput(streamName, text) {
+	const stream = process[streamName];
+	const streamLike = {
+		isTTY: stream.isTTY,
+		fd: stream.fd,
+		defaultEncoding: getDefaultEncoding(stream)
+	};
+	if (shouldWriteDirectly(streamLike, process.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
+	else stream.write(text);
+}
+
+//#endregion
+export { getDefaultEncoding, shouldWriteDirectly, writeAllSync, writeOutput };

package/dist/print.cjs

@@ -1,4 +1,5 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_output = require('./output.cjs');
 const __optique_core_internal_terminal = require_rolldown_runtime.__toESM(require("@optique/core/internal/terminal"));
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
 
@@ -50,8 +51,12 @@ function printError(message, options = {}) {
 		quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	});
-	output.write(formatted + "\n");
-	if (options.exitCode != null) node_process.default.exit(options.exitCode);
+	const text = formatted + "\n";
+	if (options.exitCode == null) output.write(text);
+	else {
+		require_output.writeOutput(stream, text);
+		node_process.default.exit(options.exitCode);
+	}
 }
 /**
 * Creates a custom printer function with predefined formatting options.
@@ -84,7 +89,17 @@ function printError(message, options = {}) {
 */
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
-	const output = node_process.default[stream];
+	const format = createFormatter(options);
+	return (message) => {
+		node_process.default[stream].write(format(message) + "\n");
+	};
+}
+/**
+* Creates a function that formats messages for the given stream, resolving
+* terminal-dependent defaults once, at creation time.
+*/
+function createFormatter(options) {
+	const output = node_process.default[options.stream ?? "stdout"];
 	const formatMessage = (0, __optique_core_internal_terminal.resolveMessageFormatter)(options);
 	const formatOptions = {
 		initialWidth: options.initialWidth,
@@ -92,11 +107,7 @@ function createPrinter(options = {}) {
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
-	return (message) => {
-		const formatted = formatMessage(message, formatOptions);
-		if (stream === "stderr") node_process.default.stderr.write(formatted + "\n");
-		else node_process.default.stdout.write(formatted + "\n");
-	};
+	return (message) => formatMessage(message, formatOptions);
 }
 
 //#endregion

package/dist/print.d.cts

@@ -31,6 +31,12 @@ interface PrintErrorOptions extends PrintOptions {
   /**
    * Exit code to use when exiting the process.
    * If specified, the process will exit with this code after printing the error.
+   *
+   * When the output stream is a pipe or a file on POSIX systems under Node.js
+   * or Bun, the error message is written directly to its file descriptor, and
+   * the process exits only after the whole message has been written, even if
+   * the reader is slow.  Output that earlier calls queued in the stream is not
+   * flushed.
    */
   readonly exitCode?: number;
 }
@@ -95,6 +101,9 @@ declare function print(message: Message, options?: PrintOptions): void;
  * @param options Optional formatting options and exit code.
  * @throws {TypeError} If initialWidth is not a finite integer.
  * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+ * @throws {Error} If `exitCode` is specified and writing the message directly
+ *         to the output stream's file descriptor fails for a reason other
+ *         than the reader having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript

package/dist/print.d.ts

@@ -31,6 +31,12 @@ interface PrintErrorOptions extends PrintOptions {
   /**
    * Exit code to use when exiting the process.
    * If specified, the process will exit with this code after printing the error.
+   *
+   * When the output stream is a pipe or a file on POSIX systems under Node.js
+   * or Bun, the error message is written directly to its file descriptor, and
+   * the process exits only after the whole message has been written, even if
+   * the reader is slow.  Output that earlier calls queued in the stream is not
+   * flushed.
    */
   readonly exitCode?: number;
 }
@@ -95,6 +101,9 @@ declare function print(message: Message, options?: PrintOptions): void;
  * @param options Optional formatting options and exit code.
  * @throws {TypeError} If initialWidth is not a finite integer.
  * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
+ * @throws {Error} If `exitCode` is specified and writing the message directly
+ *         to the output stream's file descriptor fails for a reason other
+ *         than the reader having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript

package/dist/print.js

@@ -1,3 +1,4 @@
+import { writeOutput } from "./output.js";
 import { renderErrorMessage, resolveMessageFormatter } from "@optique/core/internal/terminal";
 import process from "node:process";
 
@@ -49,8 +50,12 @@ function printError(message, options = {}) {
 		quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	});
-	output.write(formatted + "\n");
-	if (options.exitCode != null) process.exit(options.exitCode);
+	const text = formatted + "\n";
+	if (options.exitCode == null) output.write(text);
+	else {
+		writeOutput(stream, text);
+		process.exit(options.exitCode);
+	}
 }
 /**
 * Creates a custom printer function with predefined formatting options.
@@ -83,7 +88,17 @@ function printError(message, options = {}) {
 */
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
-	const output = process[stream];
+	const format = createFormatter(options);
+	return (message) => {
+		process[stream].write(format(message) + "\n");
+	};
+}
+/**
+* Creates a function that formats messages for the given stream, resolving
+* terminal-dependent defaults once, at creation time.
+*/
+function createFormatter(options) {
+	const output = process[options.stream ?? "stdout"];
 	const formatMessage = resolveMessageFormatter(options);
 	const formatOptions = {
 		initialWidth: options.initialWidth,
@@ -91,11 +106,7 @@ function createPrinter(options = {}) {
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
-	return (message) => {
-		const formatted = formatMessage(message, formatOptions);
-		if (stream === "stderr") process.stderr.write(formatted + "\n");
-		else process.stdout.write(formatted + "\n");
-	};
+	return (message) => formatMessage(message, formatOptions);
 }
 
 //#endregion

package/dist/run.cjs

@@ -1,9 +1,10 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_output = require('./output.cjs');
 const require_terminal = require('./terminal.cjs');
 const __optique_core_internal_terminal = require_rolldown_runtime.__toESM(require("@optique/core/internal/terminal"));
 const __optique_core_facade = require_rolldown_runtime.__toESM(require("@optique/core/facade"));
-const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 
 //#region src/run.ts
 function getProgramHelpMetadata(metadata) {
@@ -68,10 +69,10 @@ function buildCoreOptions(options, programMetadata) {
 	const programName = options.programName ?? node_path.default.basename(node_process.default.argv[1] ?? "cli");
 	const args = options.args ?? node_process.default.argv.slice(2);
 	const stdout = options.stdout ?? ((line) => {
-		node_process.default.stdout.write(`${line}\n`);
+		require_output.writeOutput("stdout", `${line}\n`);
 	});
 	const stderr = options.stderr ?? ((line) => {
-		node_process.default.stderr.write(`${line}\n`);
+		require_output.writeOutput("stderr", `${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => node_process.default.exit(exitCode));
 	const colors = options.colors ?? require_terminal.detectColorSupport(node_process.default.stdout, require_terminal.readEnvironmentVariable);

package/dist/run.d.cts

@@ -34,6 +34,14 @@ interface RunOptions {
    * Function used to output help and usage messages.  Assumes it prints the
    * ending newline.
    *
+   * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.log()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stdout` with a trailing newline
    */
   readonly stdout?: (text: string) => void;
@@ -41,12 +49,32 @@ interface RunOptions {
    * Function used to output error messages.  Assumes it prints the ending
    * newline.
    *
+   * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.error()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stderr` with a trailing newline
    */
   readonly stderr?: (text: string) => void;
   /**
    * Function used to exit the process on help/version display or parse error.
    *
+   * This hook is synchronous and runs immediately after an output handler
+   * returns.  With the default `process.exit()` handler, custom `stdout` and
+   * `stderr` handlers must finish writing synchronously before returning.
+   * The default exit handler also does not wait for writes queued by
+   * application code.
+   *
+   * To wait for asynchronous writes, record their completion promises and
+   * throw an exception carrying the exit code from `onExit`.  Catch that
+   * exception outside the runner, await the recorded promises, then call
+   * `process.exit()` with that code.
+   * An arbitrary delay does not guarantee that output has been flushed.
+   *
    * @default `process.exit`
    */
   readonly onExit?: (exitCode: number) => never;
@@ -343,6 +371,25 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * - Exit the process with appropriate codes on help or error
  * - Format output according to terminal capabilities
  *
+ * On affected Bun versions, importing `@optique/run` can cause large
+ * application `console.log()` output to be silently truncated when piped,
+ * even after successful parsing and natural process exit.  This is
+ * [Bun issue #36419](https://github.com/oven-sh/bun/issues/36419), reported
+ * on macOS arm64 with Bun 1.3.14 and 1.4.2.  Use `process.stdout.write()`
+ * instead of `console.log()` for application data, and `process.stderr.write()`
+ * instead of `console.error()` for diagnostics.  Both console methods can lose
+ * large piped output.  Let the process exit naturally.  If explicit termination
+ * is necessary, wait for the completion callbacks of all pending stdout/stderr
+ * writes before calling `process.exit()`; a delay is not a flush guarantee.
+ * Waiting after `console.log()` or `console.error()` cannot recover dropped
+ * bytes.
+ *
+ * Setting `colors` and `maxWidth` explicitly does not avoid this Bun bug:
+ * importing `node:process`, which this module does, was enough to trigger it
+ * in Bun 1.3.14.  The upstream fix was merged in
+ * [Bun PR #43868](https://github.com/oven-sh/bun/pull/43868); check whether
+ * your Bun release includes it.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
@@ -351,6 +398,9 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * color, even when colors are disabled.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript
@@ -425,6 +475,8 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * Use this when you know your parser is sync-only to get direct return values
  * without Promise wrappers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The sync parser type being executed.
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
@@ -433,6 +485,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -452,12 +507,17 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * Promise. Use this when working with parsers that may contain async
  * value parsers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns A Promise of the parsed result if successful.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {

package/dist/run.d.ts

@@ -34,6 +34,14 @@ interface RunOptions {
    * Function used to output help and usage messages.  Assumes it prints the
    * ending newline.
    *
+   * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.log()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stdout` with a trailing newline
    */
   readonly stdout?: (text: string) => void;
@@ -41,12 +49,32 @@ interface RunOptions {
    * Function used to output error messages.  Assumes it prints the ending
    * newline.
    *
+   * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.error()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stderr` with a trailing newline
    */
   readonly stderr?: (text: string) => void;
   /**
    * Function used to exit the process on help/version display or parse error.
    *
+   * This hook is synchronous and runs immediately after an output handler
+   * returns.  With the default `process.exit()` handler, custom `stdout` and
+   * `stderr` handlers must finish writing synchronously before returning.
+   * The default exit handler also does not wait for writes queued by
+   * application code.
+   *
+   * To wait for asynchronous writes, record their completion promises and
+   * throw an exception carrying the exit code from `onExit`.  Catch that
+   * exception outside the runner, await the recorded promises, then call
+   * `process.exit()` with that code.
+   * An arbitrary delay does not guarantee that output has been flushed.
+   *
    * @default `process.exit`
    */
   readonly onExit?: (exitCode: number) => never;
@@ -343,6 +371,25 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * - Exit the process with appropriate codes on help or error
  * - Format output according to terminal capabilities
  *
+ * On affected Bun versions, importing `@optique/run` can cause large
+ * application `console.log()` output to be silently truncated when piped,
+ * even after successful parsing and natural process exit.  This is
+ * [Bun issue #36419](https://github.com/oven-sh/bun/issues/36419), reported
+ * on macOS arm64 with Bun 1.3.14 and 1.4.2.  Use `process.stdout.write()`
+ * instead of `console.log()` for application data, and `process.stderr.write()`
+ * instead of `console.error()` for diagnostics.  Both console methods can lose
+ * large piped output.  Let the process exit naturally.  If explicit termination
+ * is necessary, wait for the completion callbacks of all pending stdout/stderr
+ * writes before calling `process.exit()`; a delay is not a flush guarantee.
+ * Waiting after `console.log()` or `console.error()` cannot recover dropped
+ * bytes.
+ *
+ * Setting `colors` and `maxWidth` explicitly does not avoid this Bun bug:
+ * importing `node:process`, which this module does, was enough to trigger it
+ * in Bun 1.3.14.  The upstream fix was merged in
+ * [Bun PR #43868](https://github.com/oven-sh/bun/pull/43868); check whether
+ * your Bun release includes it.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
@@ -351,6 +398,9 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * color, even when colors are disabled.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript
@@ -425,6 +475,8 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * Use this when you know your parser is sync-only to get direct return values
  * without Promise wrappers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The sync parser type being executed.
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
@@ -433,6 +485,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -452,12 +507,17 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * Promise. Use this when working with parsers that may contain async
  * value parsers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
  * @returns A Promise of the parsed result if successful.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {

package/dist/run.js

@@ -1,8 +1,9 @@
+import { writeOutput } from "./output.js";
 import { detectColorSupport, detectTerminalWidth, readEnvironmentVariable } from "./terminal.js";
 import { withAutomaticWidth } from "@optique/core/internal/terminal";
 import { runParser, runWith, runWithSync } from "@optique/core/facade";
-import path from "node:path";
 import process from "node:process";
+import path from "node:path";
 
 //#region src/run.ts
 function getProgramHelpMetadata(metadata) {
@@ -67,10 +68,10 @@ function buildCoreOptions(options, programMetadata) {
 	const programName = options.programName ?? path.basename(process.argv[1] ?? "cli");
 	const args = options.args ?? process.argv.slice(2);
 	const stdout = options.stdout ?? ((line) => {
-		process.stdout.write(`${line}\n`);
+		writeOutput("stdout", `${line}\n`);
 	});
 	const stderr = options.stderr ?? ((line) => {
-		process.stderr.write(`${line}\n`);
+		writeOutput("stderr", `${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => process.exit(exitCode));
 	const colors = options.colors ?? detectColorSupport(process.stdout, readEnvironmentVariable);

package/dist/valueparser.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
 const __optique_core_nonempty = require_rolldown_runtime.__toESM(require("@optique/core/nonempty"));
-const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 
 //#region src/valueparser.ts
 /**

package/dist/valueparser.js

@@ -1,7 +1,7 @@
+import { existsSync, statSync } from "node:fs";
 import { basename, dirname, extname } from "node:path";
 import { message, text } from "@optique/core/message";
 import { ensureNonEmptyString } from "@optique/core/nonempty";
-import { existsSync, statSync } from "node:fs";
 
 //#region src/valueparser.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -76,11 +76,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.3.1"
+    "@optique/core": "1.3.3"
   },
   "devDependencies": {
-    "@optique/config": "1.3.1",
-    "@optique/env": "1.3.1",
+    "@optique/config": "1.3.3",
+    "@optique/env": "1.3.3",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",