@optique/run 1.0.11 → 1.0.12-dev.2690

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,124 @@
1
+ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
3
+ const node_process = require_rolldown_runtime.__toESM(require("node:process"));
4
+
5
+ //#region src/output.ts
6
+ let sleepCell;
7
+ function sleepSync(ms) {
8
+ sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
9
+ Atomics.wait(sleepCell, 0, 0, ms);
10
+ }
11
+ function getErrorCode(error) {
12
+ return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
13
+ }
14
+ /**
15
+ * Writes all of the given bytes to a file descriptor synchronously.
16
+ *
17
+ * Partial writes resume from the next unwritten byte. When the descriptor
18
+ * is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
19
+ * briefly and retries, blocking the current thread until the reader catches
20
+ * up. When the reader has closed the pipe (`EPIPE`) or reset the socket
21
+ * (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
22
+ * silently.
23
+ *
24
+ * @param fd The file descriptor to write to.
25
+ * @param bytes The bytes to write.
26
+ * @param deps Dependencies to use instead of the defaults, for testing.
27
+ * @throws {Error} If writing fails for any other reason, or if a write makes
28
+ * no progress.
29
+ * @internal
30
+ */
31
+ function writeAllSync(fd, bytes, deps = {}) {
32
+ const writeSync = deps.writeSync ?? node_fs.writeSync;
33
+ const sleep = deps.sleep ?? sleepSync;
34
+ let offset = 0;
35
+ while (offset < bytes.length) {
36
+ let written;
37
+ try {
38
+ written = writeSync(fd, bytes, offset, bytes.length - offset);
39
+ } catch (error) {
40
+ const code = getErrorCode(error);
41
+ if (code === "EAGAIN" || code === "EWOULDBLOCK") {
42
+ sleep(1);
43
+ continue;
44
+ }
45
+ if (code === "EINTR") continue;
46
+ if (code === "EPIPE" || code === "ECONNRESET") return;
47
+ throw error;
48
+ }
49
+ if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
50
+ offset += written;
51
+ }
52
+ }
53
+ /**
54
+ * Reads the encoding a writable stream applies to strings, which
55
+ * `setDefaultEncoding()` changes. Node.js and Bun expose it only through
56
+ * the stream's internal state, so this returns `undefined` when that is not
57
+ * available.
58
+ *
59
+ * @param stream The stream to inspect.
60
+ * @returns The default encoding, or `undefined` if it cannot be read.
61
+ * @internal
62
+ */
63
+ function getDefaultEncoding(stream) {
64
+ if (!("_writableState" in stream)) return void 0;
65
+ const state = stream._writableState;
66
+ return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
67
+ }
68
+ function isUtf8Encoding(encoding) {
69
+ return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
70
+ }
71
+ /**
72
+ * Decides whether output for the given stream should bypass the stream and
73
+ * be written directly to its file descriptor.
74
+ *
75
+ * TTYs keep going through the stream, since terminal writes are synchronous
76
+ * on POSIX and Windows consoles need the stream's own handling. Windows is
77
+ * excluded altogether. Streams without a file descriptor, such as
78
+ * `process.stdout` in a Node.js worker thread, also keep going through the
79
+ * stream, since writing to fd 1 or 2 would bypass the worker's redirection.
80
+ * Deno is excluded as well: its streams do not lose queued output on exit,
81
+ * and its `fs.writeSync()` can write part of the buffer to a non-blocking
82
+ * pipe and then throw `EAGAIN` without reporting how much it wrote, which
83
+ * would make retrying duplicate output. Finally, streams whose default
84
+ * encoding is not UTF-8 keep going through the stream, since direct writes
85
+ * always encode the text as UTF-8.
86
+ *
87
+ * @param stream The stream to inspect.
88
+ * @param platform The value of `process.platform`.
89
+ * @param deno Whether the current runtime is Deno.
90
+ * @returns `true` if output should be written directly to `stream.fd`.
91
+ * @internal
92
+ */
93
+ function shouldWriteDirectly(stream, platform, deno) {
94
+ const fd = stream.fd;
95
+ return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
96
+ }
97
+ const encoder = new TextEncoder();
98
+ /**
99
+ * Writes text to standard output or standard error such that, when the
100
+ * stream is a pipe or a file, the text has been completely handed to the
101
+ * operating system by the time this returns (unless the reader closed the
102
+ * pipe). Otherwise, it falls back to the stream's `write()` method.
103
+ *
104
+ * Note that output queued in the stream by earlier `write()` calls is not
105
+ * flushed, and that text written directly can overtake it.
106
+ *
107
+ * @param streamName The stream to write to.
108
+ * @param text The text to write.
109
+ * @throws {Error} If writing to the file descriptor fails.
110
+ * @internal
111
+ */
112
+ function writeOutput(streamName, text) {
113
+ const stream = node_process.default[streamName];
114
+ const streamLike = {
115
+ isTTY: stream.isTTY,
116
+ fd: stream.fd,
117
+ defaultEncoding: getDefaultEncoding(stream)
118
+ };
119
+ if (shouldWriteDirectly(streamLike, node_process.default.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
120
+ else stream.write(text);
121
+ }
122
+
123
+ //#endregion
124
+ exports.writeOutput = writeOutput;
package/dist/output.js ADDED
@@ -0,0 +1,123 @@
1
+ import { writeSync } from "node:fs";
2
+ import process from "node:process";
3
+
4
+ //#region src/output.ts
5
+ let sleepCell;
6
+ function sleepSync(ms) {
7
+ sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
8
+ Atomics.wait(sleepCell, 0, 0, ms);
9
+ }
10
+ function getErrorCode(error) {
11
+ return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
12
+ }
13
+ /**
14
+ * Writes all of the given bytes to a file descriptor synchronously.
15
+ *
16
+ * Partial writes resume from the next unwritten byte. When the descriptor
17
+ * is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
18
+ * briefly and retries, blocking the current thread until the reader catches
19
+ * up. When the reader has closed the pipe (`EPIPE`) or reset the socket
20
+ * (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
21
+ * silently.
22
+ *
23
+ * @param fd The file descriptor to write to.
24
+ * @param bytes The bytes to write.
25
+ * @param deps Dependencies to use instead of the defaults, for testing.
26
+ * @throws {Error} If writing fails for any other reason, or if a write makes
27
+ * no progress.
28
+ * @internal
29
+ */
30
+ function writeAllSync(fd, bytes, deps = {}) {
31
+ const writeSync$1 = deps.writeSync ?? writeSync;
32
+ const sleep = deps.sleep ?? sleepSync;
33
+ let offset = 0;
34
+ while (offset < bytes.length) {
35
+ let written;
36
+ try {
37
+ written = writeSync$1(fd, bytes, offset, bytes.length - offset);
38
+ } catch (error) {
39
+ const code = getErrorCode(error);
40
+ if (code === "EAGAIN" || code === "EWOULDBLOCK") {
41
+ sleep(1);
42
+ continue;
43
+ }
44
+ if (code === "EINTR") continue;
45
+ if (code === "EPIPE" || code === "ECONNRESET") return;
46
+ throw error;
47
+ }
48
+ if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
49
+ offset += written;
50
+ }
51
+ }
52
+ /**
53
+ * Reads the encoding a writable stream applies to strings, which
54
+ * `setDefaultEncoding()` changes. Node.js and Bun expose it only through
55
+ * the stream's internal state, so this returns `undefined` when that is not
56
+ * available.
57
+ *
58
+ * @param stream The stream to inspect.
59
+ * @returns The default encoding, or `undefined` if it cannot be read.
60
+ * @internal
61
+ */
62
+ function getDefaultEncoding(stream) {
63
+ if (!("_writableState" in stream)) return void 0;
64
+ const state = stream._writableState;
65
+ return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
66
+ }
67
+ function isUtf8Encoding(encoding) {
68
+ return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
69
+ }
70
+ /**
71
+ * Decides whether output for the given stream should bypass the stream and
72
+ * be written directly to its file descriptor.
73
+ *
74
+ * TTYs keep going through the stream, since terminal writes are synchronous
75
+ * on POSIX and Windows consoles need the stream's own handling. Windows is
76
+ * excluded altogether. Streams without a file descriptor, such as
77
+ * `process.stdout` in a Node.js worker thread, also keep going through the
78
+ * stream, since writing to fd 1 or 2 would bypass the worker's redirection.
79
+ * Deno is excluded as well: its streams do not lose queued output on exit,
80
+ * and its `fs.writeSync()` can write part of the buffer to a non-blocking
81
+ * pipe and then throw `EAGAIN` without reporting how much it wrote, which
82
+ * would make retrying duplicate output. Finally, streams whose default
83
+ * encoding is not UTF-8 keep going through the stream, since direct writes
84
+ * always encode the text as UTF-8.
85
+ *
86
+ * @param stream The stream to inspect.
87
+ * @param platform The value of `process.platform`.
88
+ * @param deno Whether the current runtime is Deno.
89
+ * @returns `true` if output should be written directly to `stream.fd`.
90
+ * @internal
91
+ */
92
+ function shouldWriteDirectly(stream, platform, deno) {
93
+ const fd = stream.fd;
94
+ return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
95
+ }
96
+ const encoder = new TextEncoder();
97
+ /**
98
+ * Writes text to standard output or standard error such that, when the
99
+ * stream is a pipe or a file, the text has been completely handed to the
100
+ * operating system by the time this returns (unless the reader closed the
101
+ * pipe). Otherwise, it falls back to the stream's `write()` method.
102
+ *
103
+ * Note that output queued in the stream by earlier `write()` calls is not
104
+ * flushed, and that text written directly can overtake it.
105
+ *
106
+ * @param streamName The stream to write to.
107
+ * @param text The text to write.
108
+ * @throws {Error} If writing to the file descriptor fails.
109
+ * @internal
110
+ */
111
+ function writeOutput(streamName, text) {
112
+ const stream = process[streamName];
113
+ const streamLike = {
114
+ isTTY: stream.isTTY,
115
+ fd: stream.fd,
116
+ defaultEncoding: getDefaultEncoding(stream)
117
+ };
118
+ if (shouldWriteDirectly(streamLike, process.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
119
+ else stream.write(text);
120
+ }
121
+
122
+ //#endregion
123
+ export { writeOutput };
package/dist/print.cjs CHANGED
@@ -1,4 +1,5 @@
1
1
  const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ const require_output = require('./output.cjs');
2
3
  const node_process = require_rolldown_runtime.__toESM(require("node:process"));
3
4
  const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
4
5
 
@@ -40,7 +41,7 @@ function printError(message, options = {}) {
40
41
  const stream = options.stream ?? "stderr";
41
42
  const output = node_process.default[stream];
42
43
  const quotes = options.quotes ?? !output.isTTY;
43
- const printer = createPrinter({
44
+ const format = createFormatter({
44
45
  stream,
45
46
  colors: options.colors,
46
47
  quotes,
@@ -50,8 +51,12 @@ function printError(message, options = {}) {
50
51
  type: "text",
51
52
  text: "Error: "
52
53
  }, ...message];
53
- printer(errorMessage);
54
- if (options.exitCode != null) node_process.default.exit(options.exitCode);
54
+ const text = format(errorMessage) + "\n";
55
+ if (options.exitCode == null) output.write(text);
56
+ else {
57
+ require_output.writeOutput(stream, text);
58
+ node_process.default.exit(options.exitCode);
59
+ }
55
60
  }
56
61
  /**
57
62
  * Creates a custom printer function with predefined formatting options.
@@ -82,17 +87,23 @@ function printError(message, options = {}) {
82
87
  */
83
88
  function createPrinter(options = {}) {
84
89
  const stream = options.stream ?? "stdout";
85
- const output = node_process.default[stream];
90
+ const format = createFormatter(options);
91
+ return (message) => {
92
+ node_process.default[stream].write(format(message) + "\n");
93
+ };
94
+ }
95
+ /**
96
+ * Creates a function that formats messages for the given stream, resolving
97
+ * terminal-dependent defaults once, at creation time.
98
+ */
99
+ function createFormatter(options) {
100
+ const output = node_process.default[options.stream ?? "stdout"];
86
101
  const formatOptions = {
87
102
  colors: options.colors ?? output.isTTY,
88
103
  quotes: options.quotes,
89
104
  maxWidth: options.maxWidth ?? output.columns
90
105
  };
91
- return (message) => {
92
- const formatted = (0, __optique_core_message.formatMessage)(message, formatOptions);
93
- if (stream === "stderr") node_process.default.stderr.write(formatted + "\n");
94
- else node_process.default.stdout.write(formatted + "\n");
95
- };
106
+ return (message) => (0, __optique_core_message.formatMessage)(message, formatOptions);
96
107
  }
97
108
 
98
109
  //#endregion
package/dist/print.d.cts CHANGED
@@ -26,6 +26,12 @@ interface PrintErrorOptions extends PrintOptions {
26
26
  /**
27
27
  * Exit code to use when exiting the process.
28
28
  * If specified, the process will exit with this code after printing the error.
29
+ *
30
+ * When the output stream is a pipe or a file on POSIX systems under Node.js
31
+ * or Bun, the error message is written directly to its file descriptor, and
32
+ * the process exits only after the whole message has been written, even if
33
+ * the reader is slow. Output that earlier calls queued in the stream is not
34
+ * flushed.
29
35
  */
30
36
  readonly exitCode?: number;
31
37
  }
@@ -80,6 +86,9 @@ declare function print(message: Message, options?: PrintOptions): void;
80
86
  *
81
87
  * @param message The structured error message to print.
82
88
  * @param options Optional formatting options and exit code.
89
+ * @throws {Error} If `exitCode` is specified and writing the message directly
90
+ * to the output stream's file descriptor fails for a reason other
91
+ * than the reader having gone away (for example, `ENOSPC`).
83
92
  *
84
93
  * @example
85
94
  * ```typescript
package/dist/print.d.ts CHANGED
@@ -26,6 +26,12 @@ interface PrintErrorOptions extends PrintOptions {
26
26
  /**
27
27
  * Exit code to use when exiting the process.
28
28
  * If specified, the process will exit with this code after printing the error.
29
+ *
30
+ * When the output stream is a pipe or a file on POSIX systems under Node.js
31
+ * or Bun, the error message is written directly to its file descriptor, and
32
+ * the process exits only after the whole message has been written, even if
33
+ * the reader is slow. Output that earlier calls queued in the stream is not
34
+ * flushed.
29
35
  */
30
36
  readonly exitCode?: number;
31
37
  }
@@ -80,6 +86,9 @@ declare function print(message: Message, options?: PrintOptions): void;
80
86
  *
81
87
  * @param message The structured error message to print.
82
88
  * @param options Optional formatting options and exit code.
89
+ * @throws {Error} If `exitCode` is specified and writing the message directly
90
+ * to the output stream's file descriptor fails for a reason other
91
+ * than the reader having gone away (for example, `ENOSPC`).
83
92
  *
84
93
  * @example
85
94
  * ```typescript
package/dist/print.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { writeOutput } from "./output.js";
1
2
  import process from "node:process";
2
3
  import { formatMessage } from "@optique/core/message";
3
4
 
@@ -39,7 +40,7 @@ function printError(message$1, options = {}) {
39
40
  const stream = options.stream ?? "stderr";
40
41
  const output = process[stream];
41
42
  const quotes = options.quotes ?? !output.isTTY;
42
- const printer = createPrinter({
43
+ const format = createFormatter({
43
44
  stream,
44
45
  colors: options.colors,
45
46
  quotes,
@@ -49,8 +50,12 @@ function printError(message$1, options = {}) {
49
50
  type: "text",
50
51
  text: "Error: "
51
52
  }, ...message$1];
52
- printer(errorMessage);
53
- if (options.exitCode != null) process.exit(options.exitCode);
53
+ const text$1 = format(errorMessage) + "\n";
54
+ if (options.exitCode == null) output.write(text$1);
55
+ else {
56
+ writeOutput(stream, text$1);
57
+ process.exit(options.exitCode);
58
+ }
54
59
  }
55
60
  /**
56
61
  * Creates a custom printer function with predefined formatting options.
@@ -81,17 +86,23 @@ function printError(message$1, options = {}) {
81
86
  */
82
87
  function createPrinter(options = {}) {
83
88
  const stream = options.stream ?? "stdout";
84
- const output = process[stream];
89
+ const format = createFormatter(options);
90
+ return (message$1) => {
91
+ process[stream].write(format(message$1) + "\n");
92
+ };
93
+ }
94
+ /**
95
+ * Creates a function that formats messages for the given stream, resolving
96
+ * terminal-dependent defaults once, at creation time.
97
+ */
98
+ function createFormatter(options) {
99
+ const output = process[options.stream ?? "stdout"];
85
100
  const formatOptions = {
86
101
  colors: options.colors ?? output.isTTY,
87
102
  quotes: options.quotes,
88
103
  maxWidth: options.maxWidth ?? output.columns
89
104
  };
90
- return (message$1) => {
91
- const formatted = formatMessage(message$1, formatOptions);
92
- if (stream === "stderr") process.stderr.write(formatted + "\n");
93
- else process.stdout.write(formatted + "\n");
94
- };
105
+ return (message$1) => formatMessage(message$1, formatOptions);
95
106
  }
96
107
 
97
108
  //#endregion
package/dist/run.cjs CHANGED
@@ -1,7 +1,8 @@
1
1
  const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ const require_output = require('./output.cjs');
2
3
  const __optique_core_facade = require_rolldown_runtime.__toESM(require("@optique/core/facade"));
3
- const node_path = require_rolldown_runtime.__toESM(require("node:path"));
4
4
  const node_process = require_rolldown_runtime.__toESM(require("node:process"));
5
+ const node_path = require_rolldown_runtime.__toESM(require("node:path"));
5
6
 
6
7
  //#region src/run.ts
7
8
  function getProgramHelpMetadata(metadata) {
@@ -66,10 +67,10 @@ function buildCoreOptions(options, programMetadata) {
66
67
  const programName = options.programName ?? node_path.default.basename(node_process.default.argv[1] ?? "cli");
67
68
  const args = options.args ?? node_process.default.argv.slice(2);
68
69
  const stdout = options.stdout ?? ((line) => {
69
- node_process.default.stdout.write(`${line}\n`);
70
+ require_output.writeOutput("stdout", `${line}\n`);
70
71
  });
71
72
  const stderr = options.stderr ?? ((line) => {
72
- node_process.default.stderr.write(`${line}\n`);
73
+ require_output.writeOutput("stderr", `${line}\n`);
73
74
  });
74
75
  const onExit = options.onExit ?? ((exitCode) => node_process.default.exit(exitCode));
75
76
  const colors = options.colors ?? node_process.default.stdout.isTTY;
package/dist/run.d.cts CHANGED
@@ -28,6 +28,11 @@ interface RunOptions {
28
28
  * Function used to output help and usage messages. Assumes it prints the
29
29
  * ending newline.
30
30
  *
31
+ * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
32
+ * Bun, the default writes directly to its file descriptor and returns only
33
+ * after the whole text has been written, even if the reader is slow, so that
34
+ * exiting the process right afterward does not truncate the output.
35
+ *
31
36
  * @default Writes to `process.stdout` with a trailing newline
32
37
  */
33
38
  readonly stdout?: (text: string) => void;
@@ -35,6 +40,11 @@ interface RunOptions {
35
40
  * Function used to output error messages. Assumes it prints the ending
36
41
  * newline.
37
42
  *
43
+ * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
44
+ * Bun, the default writes directly to its file descriptor and returns only
45
+ * after the whole text has been written, even if the reader is slow, so that
46
+ * exiting the process right afterward does not truncate the output.
47
+ *
38
48
  * @default Writes to `process.stderr` with a trailing newline
39
49
  */
40
50
  readonly stderr?: (text: string) => void;
@@ -291,6 +301,9 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
291
301
  * See {@link RunOptions} for available settings.
292
302
  * @returns The parsed result if successful. On help display or parse errors,
293
303
  * the function will call `process.exit()` and not return.
304
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
305
+ * to the stream's file descriptor for a reason other than the reader
306
+ * having gone away (for example, `ENOSPC`).
294
307
  *
295
308
  * @example
296
309
  * ```typescript
@@ -371,6 +384,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
371
384
  * @returns The parsed result if successful.
372
385
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
373
386
  * is passed at runtime. Use {@link run} or {@link runAsync} instead.
387
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
388
+ * to the stream's file descriptor for a reason other than the reader
389
+ * having gone away (for example, `ENOSPC`).
374
390
  * @since 0.9.0
375
391
  */
376
392
  declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -394,6 +410,9 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
394
410
  * @param parser The command-line parser to execute.
395
411
  * @param options Configuration options for customizing behavior.
396
412
  * @returns A Promise of the parsed result if successful.
413
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
414
+ * to the stream's file descriptor for a reason other than the reader
415
+ * having gone away (for example, `ENOSPC`).
397
416
  * @since 0.9.0
398
417
  */
399
418
  declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
package/dist/run.d.ts CHANGED
@@ -28,6 +28,11 @@ interface RunOptions {
28
28
  * Function used to output help and usage messages. Assumes it prints the
29
29
  * ending newline.
30
30
  *
31
+ * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
32
+ * Bun, the default writes directly to its file descriptor and returns only
33
+ * after the whole text has been written, even if the reader is slow, so that
34
+ * exiting the process right afterward does not truncate the output.
35
+ *
31
36
  * @default Writes to `process.stdout` with a trailing newline
32
37
  */
33
38
  readonly stdout?: (text: string) => void;
@@ -35,6 +40,11 @@ interface RunOptions {
35
40
  * Function used to output error messages. Assumes it prints the ending
36
41
  * newline.
37
42
  *
43
+ * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
44
+ * Bun, the default writes directly to its file descriptor and returns only
45
+ * after the whole text has been written, even if the reader is slow, so that
46
+ * exiting the process right afterward does not truncate the output.
47
+ *
38
48
  * @default Writes to `process.stderr` with a trailing newline
39
49
  */
40
50
  readonly stderr?: (text: string) => void;
@@ -291,6 +301,9 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
291
301
  * See {@link RunOptions} for available settings.
292
302
  * @returns The parsed result if successful. On help display or parse errors,
293
303
  * the function will call `process.exit()` and not return.
304
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
305
+ * to the stream's file descriptor for a reason other than the reader
306
+ * having gone away (for example, `ENOSPC`).
294
307
  *
295
308
  * @example
296
309
  * ```typescript
@@ -371,6 +384,9 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
371
384
  * @returns The parsed result if successful.
372
385
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
373
386
  * is passed at runtime. Use {@link run} or {@link runAsync} instead.
387
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
388
+ * to the stream's file descriptor for a reason other than the reader
389
+ * having gone away (for example, `ENOSPC`).
374
390
  * @since 0.9.0
375
391
  */
376
392
  declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -394,6 +410,9 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
394
410
  * @param parser The command-line parser to execute.
395
411
  * @param options Configuration options for customizing behavior.
396
412
  * @returns A Promise of the parsed result if successful.
413
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
414
+ * to the stream's file descriptor for a reason other than the reader
415
+ * having gone away (for example, `ENOSPC`).
397
416
  * @since 0.9.0
398
417
  */
399
418
  declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
package/dist/run.js CHANGED
@@ -1,6 +1,7 @@
1
+ import { writeOutput } from "./output.js";
1
2
  import { runParser, runWith, runWithSync } from "@optique/core/facade";
2
- import path from "node:path";
3
3
  import process from "node:process";
4
+ import path from "node:path";
4
5
 
5
6
  //#region src/run.ts
6
7
  function getProgramHelpMetadata(metadata) {
@@ -65,10 +66,10 @@ function buildCoreOptions(options, programMetadata) {
65
66
  const programName = options.programName ?? path.basename(process.argv[1] ?? "cli");
66
67
  const args = options.args ?? process.argv.slice(2);
67
68
  const stdout = options.stdout ?? ((line) => {
68
- process.stdout.write(`${line}\n`);
69
+ writeOutput("stdout", `${line}\n`);
69
70
  });
70
71
  const stderr = options.stderr ?? ((line) => {
71
- process.stderr.write(`${line}\n`);
72
+ writeOutput("stderr", `${line}\n`);
72
73
  });
73
74
  const onExit = options.onExit ?? ((exitCode) => process.exit(exitCode));
74
75
  const colors = options.colors ?? process.stdout.isTTY;
@@ -1,8 +1,8 @@
1
1
  const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
2
3
  const node_path = require_rolldown_runtime.__toESM(require("node:path"));
3
4
  const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
4
5
  const __optique_core_nonempty = require_rolldown_runtime.__toESM(require("@optique/core/nonempty"));
5
- const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
6
6
 
7
7
  //#region src/valueparser.ts
8
8
  /**
@@ -1,7 +1,7 @@
1
+ import { existsSync, statSync } from "node:fs";
1
2
  import { basename, dirname, extname } from "node:path";
2
3
  import { message, text } from "@optique/core/message";
3
4
  import { ensureNonEmptyString } from "@optique/core/nonempty";
4
- import { existsSync, statSync } from "node:fs";
5
5
 
6
6
  //#region src/valueparser.ts
7
7
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/run",
3
- "version": "1.0.11",
3
+ "version": "1.0.12-dev.2690",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",
@@ -70,7 +70,7 @@
70
70
  },
71
71
  "sideEffects": false,
72
72
  "dependencies": {
73
- "@optique/core": "1.0.11"
73
+ "@optique/core": "1.0.12-dev.2690+8d8637e0"
74
74
  },
75
75
  "devDependencies": {
76
76
  "@types/node": "^20.19.9",