@optique/run 0.3.0-dev.45 → 0.3.0-dev.47

package/dist/index.cjs

@@ -1,5 +1,9 @@
 const require_run = require('./run.cjs');
 const require_valueparser = require('./valueparser.cjs');
+const require_print = require('./print.cjs');
 
+exports.createPrinter = require_print.createPrinter;
 exports.path = require_valueparser.path;
+exports.print = require_print.print;
+exports.printError = require_print.printError;
 exports.run = require_run.run;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
 import { RunOptions, run } from "./run.cjs";
 import { PathOptions, path } from "./valueparser.cjs";
-export { PathOptions, RunOptions, path, run };
+import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.cjs";
+export { PathOptions, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 import { RunOptions, run } from "./run.js";
 import { PathOptions, path } from "./valueparser.js";
-export { PathOptions, RunOptions, path, run };
+import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.js";
+export { PathOptions, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { run } from "./run.js";
 import { path } from "./valueparser.js";
+import { createPrinter, print, printError } from "./print.js";
 
-export { path, run };
+export { createPrinter, path, print, printError, run };

package/dist/print.cjs

@@ -0,0 +1,101 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
+
+//#region src/print.ts
+/**
+* Prints a formatted message to stdout with automatic terminal detection.
+*
+* This function automatically detects terminal capabilities (colors, width)
+* and formats the message accordingly. It's ideal for general application
+* output that should be visible to users.
+*
+* @param message The structured message to print.
+* @param options Optional formatting options to override defaults.
+*
+* @example
+* ```typescript
+* import { print } from "@optique/run";
+* import { message, optionName } from "@optique/core/message";
+*
+* const configFile = "config.json";
+* const port = 3000;
+*
+* print(message`Configuration loaded from ${configFile}`);
+* print(message`Using ${optionName("--port")} ${port}`);
+* ```
+*
+* @since 0.3.0
+*/
+function print(message, options = {}) {
+	const printer = createPrinter({
+		stream: options.stream ?? "stdout",
+		colors: options.colors,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth
+	});
+	printer(message);
+}
+function printError(message, options = {}) {
+	const stream = options.stream ?? "stderr";
+	const output = node_process.default[stream];
+	const quotes = options.quotes ?? !output.isTTY;
+	const printer = createPrinter({
+		stream,
+		colors: options.colors,
+		quotes,
+		maxWidth: options.maxWidth
+	});
+	const errorMessage = [{
+		type: "text",
+		text: "Error: "
+	}, ...message];
+	printer(errorMessage);
+	if (options.exitCode != null) node_process.default.exit(options.exitCode);
+}
+/**
+* Creates a custom printer function with predefined formatting options.
+*
+* This is useful when you need consistent formatting across multiple print
+* operations or when you want to override the automatic terminal detection.
+*
+* @param options Formatting options for the printer.
+* @returns A printer function that can be called with messages.
+*
+* @example
+* ```typescript
+* import { createPrinter } from "@optique/run";
+* import { message, metavar } from "@optique/core/message";
+*
+* // Create a printer with forced colors and no quotes
+* const printer = createPrinter({
+*   colors: true,
+*   quotes: false,
+*   stream: "stdout",
+* });
+*
+* printer(message`Starting server on ${metavar("PORT")}...`);
+* printer(message`Ready to accept connections`);
+* ```
+*
+* @since 0.3.0
+*/
+function createPrinter(options = {}) {
+	const stream = options.stream ?? "stdout";
+	const output = node_process.default[stream];
+	const formatOptions = {
+		colors: options.colors ?? output.isTTY,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth ?? output.columns
+	};
+	return (message) => {
+		const formatted = (0, __optique_core_message.formatMessage)(message, formatOptions);
+		if (stream === "stderr") console.error(formatted);
+		else console.log(formatted);
+	};
+}
+
+//#endregion
+exports.createPrinter = createPrinter;
+exports.print = print;
+exports.printError = printError;

package/dist/print.d.cts

@@ -0,0 +1,133 @@
+import { Message, MessageFormatOptions } from "@optique/core/message";
+
+//#region src/print.d.ts
+
+/**
+ * Options for the {@link print} function.
+ * @since 0.3.0
+ */
+interface PrintOptions extends MessageFormatOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stdout"`
+   */
+  readonly stream?: "stdout" | "stderr";
+}
+/**
+ * Options for the {@link printError} function.
+ * @since 0.3.0
+ */
+interface PrintErrorOptions extends PrintOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stderr"`
+   */
+  readonly stream?: "stdout" | "stderr";
+  /**
+   * Exit code to use when exiting the process.
+   * If specified, the process will exit with this code after printing the error.
+   */
+  readonly exitCode?: number;
+}
+/**
+ * Options for creating a custom printer.
+ * @since 0.3.0
+ */
+interface PrinterOptions extends MessageFormatOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stdout"`
+   */
+  readonly stream?: "stdout" | "stderr";
+}
+/**
+ * A printer function that outputs formatted messages.
+ * @param message The structured message to print.
+ * @since 0.3.0
+ */
+type Printer = (message: Message) => void;
+/**
+ * Prints a formatted message to stdout with automatic terminal detection.
+ *
+ * This function automatically detects terminal capabilities (colors, width)
+ * and formats the message accordingly. It's ideal for general application
+ * output that should be visible to users.
+ *
+ * @param message The structured message to print.
+ * @param options Optional formatting options to override defaults.
+ *
+ * @example
+ * ```typescript
+ * import { print } from "@optique/run";
+ * import { message, optionName } from "@optique/core/message";
+ *
+ * const configFile = "config.json";
+ * const port = 3000;
+ *
+ * print(message`Configuration loaded from ${configFile}`);
+ * print(message`Using ${optionName("--port")} ${port}`);
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function print(message: Message, options?: PrintOptions): void;
+/**
+ * Prints a formatted error message to stderr with automatic terminal detection.
+ *
+ * This function automatically detects terminal capabilities and formats error
+ * messages with an "Error: " prefix. Optionally exits the process with a
+ * specified exit code.
+ *
+ * @param message The structured error message to print.
+ * @param options Optional formatting options and exit code.
+ *
+ * @example
+ * ```typescript
+ * import { printError } from "@optique/run";
+ * import { message, optionName } from "@optique/core/message";
+ *
+ * const filename = "missing.txt";
+ *
+ * // Print error and continue
+ * printError(message`File ${filename} not found`);
+ *
+ * // Print error and exit with code 2
+ * printError(message`Invalid ${optionName("--config")} value`, { exitCode: 2 });
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function printError(message: Message, options: PrintErrorOptions & {
+  exitCode: number;
+}): never;
+declare function printError(message: Message, options?: PrintErrorOptions): void;
+/**
+ * Creates a custom printer function with predefined formatting options.
+ *
+ * This is useful when you need consistent formatting across multiple print
+ * operations or when you want to override the automatic terminal detection.
+ *
+ * @param options Formatting options for the printer.
+ * @returns A printer function that can be called with messages.
+ *
+ * @example
+ * ```typescript
+ * import { createPrinter } from "@optique/run";
+ * import { message, metavar } from "@optique/core/message";
+ *
+ * // Create a printer with forced colors and no quotes
+ * const printer = createPrinter({
+ *   colors: true,
+ *   quotes: false,
+ *   stream: "stdout",
+ * });
+ *
+ * printer(message`Starting server on ${metavar("PORT")}...`);
+ * printer(message`Ready to accept connections`);
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function createPrinter(options?: PrinterOptions): Printer;
+//#endregion
+export { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError };

package/dist/print.d.ts

@@ -0,0 +1,133 @@
+import { Message, MessageFormatOptions } from "@optique/core/message";
+
+//#region src/print.d.ts
+
+/**
+ * Options for the {@link print} function.
+ * @since 0.3.0
+ */
+interface PrintOptions extends MessageFormatOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stdout"`
+   */
+  readonly stream?: "stdout" | "stderr";
+}
+/**
+ * Options for the {@link printError} function.
+ * @since 0.3.0
+ */
+interface PrintErrorOptions extends PrintOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stderr"`
+   */
+  readonly stream?: "stdout" | "stderr";
+  /**
+   * Exit code to use when exiting the process.
+   * If specified, the process will exit with this code after printing the error.
+   */
+  readonly exitCode?: number;
+}
+/**
+ * Options for creating a custom printer.
+ * @since 0.3.0
+ */
+interface PrinterOptions extends MessageFormatOptions {
+  /**
+   * The output stream to write to.
+   * @default `"stdout"`
+   */
+  readonly stream?: "stdout" | "stderr";
+}
+/**
+ * A printer function that outputs formatted messages.
+ * @param message The structured message to print.
+ * @since 0.3.0
+ */
+type Printer = (message: Message) => void;
+/**
+ * Prints a formatted message to stdout with automatic terminal detection.
+ *
+ * This function automatically detects terminal capabilities (colors, width)
+ * and formats the message accordingly. It's ideal for general application
+ * output that should be visible to users.
+ *
+ * @param message The structured message to print.
+ * @param options Optional formatting options to override defaults.
+ *
+ * @example
+ * ```typescript
+ * import { print } from "@optique/run";
+ * import { message, optionName } from "@optique/core/message";
+ *
+ * const configFile = "config.json";
+ * const port = 3000;
+ *
+ * print(message`Configuration loaded from ${configFile}`);
+ * print(message`Using ${optionName("--port")} ${port}`);
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function print(message: Message, options?: PrintOptions): void;
+/**
+ * Prints a formatted error message to stderr with automatic terminal detection.
+ *
+ * This function automatically detects terminal capabilities and formats error
+ * messages with an "Error: " prefix. Optionally exits the process with a
+ * specified exit code.
+ *
+ * @param message The structured error message to print.
+ * @param options Optional formatting options and exit code.
+ *
+ * @example
+ * ```typescript
+ * import { printError } from "@optique/run";
+ * import { message, optionName } from "@optique/core/message";
+ *
+ * const filename = "missing.txt";
+ *
+ * // Print error and continue
+ * printError(message`File ${filename} not found`);
+ *
+ * // Print error and exit with code 2
+ * printError(message`Invalid ${optionName("--config")} value`, { exitCode: 2 });
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function printError(message: Message, options: PrintErrorOptions & {
+  exitCode: number;
+}): never;
+declare function printError(message: Message, options?: PrintErrorOptions): void;
+/**
+ * Creates a custom printer function with predefined formatting options.
+ *
+ * This is useful when you need consistent formatting across multiple print
+ * operations or when you want to override the automatic terminal detection.
+ *
+ * @param options Formatting options for the printer.
+ * @returns A printer function that can be called with messages.
+ *
+ * @example
+ * ```typescript
+ * import { createPrinter } from "@optique/run";
+ * import { message, metavar } from "@optique/core/message";
+ *
+ * // Create a printer with forced colors and no quotes
+ * const printer = createPrinter({
+ *   colors: true,
+ *   quotes: false,
+ *   stream: "stdout",
+ * });
+ *
+ * printer(message`Starting server on ${metavar("PORT")}...`);
+ * printer(message`Ready to accept connections`);
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function createPrinter(options?: PrinterOptions): Printer;
+//#endregion
+export { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError };

package/dist/print.js

@@ -0,0 +1,98 @@
+import process from "node:process";
+import { formatMessage } from "@optique/core/message";
+
+//#region src/print.ts
+/**
+* Prints a formatted message to stdout with automatic terminal detection.
+*
+* This function automatically detects terminal capabilities (colors, width)
+* and formats the message accordingly. It's ideal for general application
+* output that should be visible to users.
+*
+* @param message The structured message to print.
+* @param options Optional formatting options to override defaults.
+*
+* @example
+* ```typescript
+* import { print } from "@optique/run";
+* import { message, optionName } from "@optique/core/message";
+*
+* const configFile = "config.json";
+* const port = 3000;
+*
+* print(message`Configuration loaded from ${configFile}`);
+* print(message`Using ${optionName("--port")} ${port}`);
+* ```
+*
+* @since 0.3.0
+*/
+function print(message$1, options = {}) {
+	const printer = createPrinter({
+		stream: options.stream ?? "stdout",
+		colors: options.colors,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth
+	});
+	printer(message$1);
+}
+function printError(message$1, options = {}) {
+	const stream = options.stream ?? "stderr";
+	const output = process[stream];
+	const quotes = options.quotes ?? !output.isTTY;
+	const printer = createPrinter({
+		stream,
+		colors: options.colors,
+		quotes,
+		maxWidth: options.maxWidth
+	});
+	const errorMessage = [{
+		type: "text",
+		text: "Error: "
+	}, ...message$1];
+	printer(errorMessage);
+	if (options.exitCode != null) process.exit(options.exitCode);
+}
+/**
+* Creates a custom printer function with predefined formatting options.
+*
+* This is useful when you need consistent formatting across multiple print
+* operations or when you want to override the automatic terminal detection.
+*
+* @param options Formatting options for the printer.
+* @returns A printer function that can be called with messages.
+*
+* @example
+* ```typescript
+* import { createPrinter } from "@optique/run";
+* import { message, metavar } from "@optique/core/message";
+*
+* // Create a printer with forced colors and no quotes
+* const printer = createPrinter({
+*   colors: true,
+*   quotes: false,
+*   stream: "stdout",
+* });
+*
+* printer(message`Starting server on ${metavar("PORT")}...`);
+* printer(message`Ready to accept connections`);
+* ```
+*
+* @since 0.3.0
+*/
+function createPrinter(options = {}) {
+	const stream = options.stream ?? "stdout";
+	const output = process[stream];
+	const formatOptions = {
+		colors: options.colors ?? output.isTTY,
+		quotes: options.quotes,
+		maxWidth: options.maxWidth ?? output.columns
+	};
+	return (message$1) => {
+		const formatted = formatMessage(message$1, formatOptions);
+		if (stream === "stderr") console.error(formatted);
+		else console.log(formatted);
+	};
+}
+
+//#endregion
+export { createPrinter, print, printError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.3.0-dev.45+6e2fc7f2",
+  "version": "0.3.0-dev.47+8e847e26",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",