@optique/run 1.0.12-dev.2690 → 1.0.12-dev.2694

package/dist/run.d.cts

@@ -33,6 +33,9 @@ interface RunOptions {
    * 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;
@@ -45,12 +48,27 @@ interface RunOptions {
    * 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;
@@ -295,6 +313,24 @@ 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.
@@ -378,6 +414,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.
@@ -406,6 +444,8 @@ 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.

package/dist/run.d.ts

@@ -33,6 +33,9 @@ interface RunOptions {
    * 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;
@@ -45,12 +48,27 @@ interface RunOptions {
    * 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;
@@ -295,6 +313,24 @@ 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.
@@ -378,6 +414,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.
@@ -406,6 +444,8 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.0.12-dev.2690",
+  "version": "1.0.12-dev.2694",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.12-dev.2690+8d8637e0"
+    "@optique/core": "1.0.12-dev.2694+de298ac0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",