@optique/logtape 1.2.0-dev.2322 → 1.2.0-dev.2329

package/README.md

@@ -70,6 +70,42 @@ Features:
     `"fatal"`
  -  Provides suggestions for shell completion
 
+### `textFormatter()`
+
+A value parser for LogTape text formatters. Parses `"jsonl"`, `"logfmt"`,
+`"color"`, and `"plain"` into LogTape formatter functions.
+
+~~~~ typescript
+import { textFormatter } from "@optique/logtape";
+import { object, option, parse } from "@optique/core";
+
+const parser = object({
+  formatter: option("--log-format", textFormatter()),
+});
+
+const result = parse(parser, ["--log-format=logfmt"]);
+// result.value.formatter is LogTape's logfmtFormatter
+~~~~
+
+Formats:
+
+`"jsonl"`
+:   [JSON Lines][LogTape JSON Lines formatter] output
+
+`"logfmt"`
+:   [logfmt][LogTape logfmt formatter] key-value output
+
+`"color"`
+:   [ANSI-colored][LogTape ANSI color formatter] console output
+
+`"plain"`
+:   [LogTape's default text][LogTape default text formatter] output
+
+[LogTape JSON Lines formatter]: https://logtape.org/manual/formatters#json-lines-formatter
+[LogTape logfmt formatter]: https://logtape.org/manual/formatters#logfmt-formatter
+[LogTape ANSI color formatter]: https://logtape.org/manual/formatters#ansi-color-formatter
+[LogTape default text formatter]: https://logtape.org/manual/formatters#default-text-formatter
+
 ### `verbosity()`
 
 A parser for accumulating `-v` flags to determine log level.
@@ -152,6 +188,37 @@ const result2 = parse(parser, ["--log-output=/var/log/app.log"]);
 const sink = await createSink(result1.value.output);
 ~~~~
 
+Use `formatter` to add a text formatter option and wire it through the
+resulting `LogOutput`:
+
+~~~~ typescript
+import { logOutput } from "@optique/logtape";
+import { object, parse } from "@optique/core";
+
+const parser = object({
+  output: logOutput({ formatter: "--log-format" }),
+});
+
+const result = parse(parser, ["--log-format=logfmt"]);
+// result.value.output is a console LogOutput with logfmtFormatter
+~~~~
+
+You can also pass a fixed LogTape text formatter. In that case no additional
+command-line option is added:
+
+~~~~ typescript
+import { logfmtFormatter } from "@logtape/logtape";
+import { logOutput } from "@optique/logtape";
+import { object, parse } from "@optique/core";
+
+const parser = object({
+  output: logOutput({ formatter: logfmtFormatter }),
+});
+
+const result = parse(parser, ["--log-output=/var/log/app.log"]);
+// result.value.output is a file LogOutput with logfmtFormatter
+~~~~
+
 ### `loggingOptions()`
 
 A preset that combines log level and log output options into a single group.
@@ -206,9 +273,21 @@ Common options:
 
  -  `output.enabled`: Whether to enable log output option (default: `true`)
  -  `output.long`: Long option name for output (default: `"--log-output"`)
+ -  `formatter`: Text formatter or long option name for output format
  -  `groupLabel`: Label for option group in help text (default:
     `"Logging options"`)
 
+Set `formatter` at the top level when using the preset:
+
+~~~~ typescript
+const parser = object({
+  logging: loggingOptions({
+    level: "option",
+    formatter: "--log-format",
+  }),
+});
+~~~~
+
 ### `createLoggingConfig()`
 
 Converts parsed logging options into a LogTape configuration object.
@@ -240,6 +319,7 @@ if (result.success) {
 Creates a console sink with configurable stream selection.
 
 ~~~~ typescript
+import { logfmtFormatter } from "@logtape/logtape";
 import { createConsoleSink } from "@optique/logtape";
 
 // Write to stderr (default)
@@ -253,6 +333,20 @@ const sink3 = createConsoleSink({
   streamResolver: (level) =>
     level === "error" || level === "fatal" ? "stderr" : "stdout",
 });
+
+// Structured logfmt output
+const sink4 = createConsoleSink({
+  formatter: logfmtFormatter,
+});
+
+// Custom console formatting with multiple console arguments
+const sink5 = createConsoleSink({
+  formatter: (record) => [
+    "%s %o",
+    record.level.toUpperCase(),
+    record.properties,
+  ],
+});
 ~~~~
 
 ### `createSink()`
@@ -260,13 +354,21 @@ const sink3 = createConsoleSink({
 Creates a LogTape sink from a `LogOutput` value.
 
 ~~~~ typescript
+import { logfmtFormatter } from "@logtape/logtape";
 import { createSink, type LogOutput } from "@optique/logtape";
 
-// Console sink
-const consoleSink = await createSink({ type: "console" });
+// Console sink with a formatter selected by logOutput()
+const consoleSink = await createSink({
+  type: "console",
+  formatter: logfmtFormatter,
+});
 
 // File sink (requires @logtape/file package)
-const fileSink = await createSink({ type: "file", path: "/var/log/app.log" });
+const fileSink = await createSink({
+  type: "file",
+  path: "/var/log/app.log",
+  formatter: logfmtFormatter,
+});
 ~~~~
 
 > [!NOTE]

package/dist/index.cjs

@@ -22,12 +22,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
+const __logtape_logtape = __toESM(require("@logtape/logtape"));
 const __optique_core_primitives = __toESM(require("@optique/core/primitives"));
 const __optique_core_modifiers = __toESM(require("@optique/core/modifiers"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
 const node_path = __toESM(require("node:path"));
-const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
 const __optique_core_constructs = __toESM(require("@optique/core/constructs"));
+const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
 
 //#region src/loglevel.ts
 /**
@@ -92,6 +93,38 @@ function logLevel(options = {}) {
 	});
 }
 
+//#endregion
+//#region src/textformatter.ts
+const textFormatters = {
+	jsonl: __logtape_logtape.jsonLinesFormatter,
+	logfmt: __logtape_logtape.logfmtFormatter,
+	color: __logtape_logtape.ansiColorFormatter,
+	plain: __logtape_logtape.defaultTextFormatter
+};
+/**
+* Creates a {@link ValueParser} for LogTape text formatters.
+*
+* This parser accepts `"jsonl"`, `"logfmt"`, `"color"`, and `"plain"` and
+* maps them to LogTape's `jsonLinesFormatter`, `logfmtFormatter`,
+* `ansiColorFormatter`, and `defaultTextFormatter` respectively.
+*
+* @returns A {@link ValueParser} that converts formatter names to
+*   LogTape text formatter functions.
+*
+* @example
+* ```typescript
+* import { option } from "@optique/core";
+* import { textFormatter } from "@optique/logtape";
+*
+* const parser = option("--log-format", textFormatter());
+* ```
+*
+* @since 1.2.0
+*/
+function textFormatter() {
+	return (0, __optique_core_valueparser.biject)(textFormatters);
+}
+
 //#endregion
 //#region src/verbosity.ts
 /**
@@ -306,9 +339,41 @@ function logOutput(options = {}) {
 	const description = options.description ?? __optique_core_message.message`Log output destination. Use ${"-"} for console.`;
 	if (options.short) {
 		const short = options.short;
-		return (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(short, long, valueParser, { description }));
+		const outputParser$1 = (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(short, long, valueParser, { description }));
+		return withFormatter(outputParser$1, options.formatter);
 	}
-	return (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(long, valueParser, { description }));
+	const outputParser = (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(long, valueParser, { description }));
+	return withFormatter(outputParser, options.formatter);
+}
+function withFormatter(outputParser, formatter) {
+	if (formatter == null) return outputParser;
+	if (typeof formatter !== "string") return outputParser.map((output) => output == null ? void 0 : {
+		...output,
+		formatter
+	});
+	const formatterParser = createTextFormatterOption(formatter);
+	return (0, __optique_core_constructs.object)({
+		output: outputParser,
+		formatter: formatterParser
+	}).map(({ output, formatter: formatter$1 }) => {
+		if (formatter$1 == null) return output;
+		return {
+			...output ?? { type: "console" },
+			formatter: formatter$1
+		};
+	});
+}
+/**
+* Creates an optional parser for a text formatter option.
+*
+* @param long The long option name for selecting the formatter.
+* @returns A parser that produces the selected {@link TextFormatter}, or
+*   `undefined` when the option is not present.
+* @throws {TypeError} If `long` is not a valid option name.
+* @since 1.2.0
+*/
+function createTextFormatterOption(long) {
+	return (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(long, textFormatter(), { description: __optique_core_message.message`Log output format.` }));
 }
 /**
 * Creates a console sink with configurable stream selection.
@@ -346,6 +411,7 @@ function logOutput(options = {}) {
 function createConsoleSink(options = {}) {
 	const streamResolver = options.streamResolver;
 	const defaultStream = options.stream ?? "stderr";
+	const formatter = options.formatter ?? defaultConsoleFormatter;
 	const invalidStreamError = (value) => {
 		let repr;
 		if (typeof value === "string") repr = JSON.stringify(value);
@@ -361,22 +427,30 @@ function createConsoleSink(options = {}) {
 	return (record) => {
 		const stream = streamResolver ? streamResolver(record.level) : defaultStream;
 		if (stream !== "stdout" && stream !== "stderr") throw invalidStreamError(stream);
-		const messageParts = [];
-		for (let i = 0; i < record.message.length; i++) {
-			const part = record.message[i];
-			if (typeof part === "string") messageParts.push(part);
-			else messageParts.push(String(part));
-		}
-		const formattedMessage = messageParts.join("");
-		const ts = record.timestamp;
-		const timestamp = new Date(ts != null && !Number.isNaN(ts) ? ts : Date.now()).toISOString();
-		const category = record.category.join(".");
-		const level = record.level.toUpperCase().padEnd(7);
-		const line = `${timestamp} [${level}] ${category}: ${formattedMessage}`;
-		if (stream === "stderr") console.error(line);
-		else console.log(line);
+		const args = toConsoleArgs(formatter(record));
+		if (stream === "stderr") console.error(...args);
+		else console.log(...args);
 	};
 }
+function toConsoleArgs(value) {
+	if (typeof value === "string") return [value.replace(/\r?\n$/, "")];
+	if (Array.isArray(value)) return value;
+	return value == null ? [] : [value];
+}
+function defaultConsoleFormatter(record) {
+	const messageParts = [];
+	for (let i = 0; i < record.message.length; i++) {
+		const part = record.message[i];
+		if (typeof part === "string") messageParts.push(part);
+		else messageParts.push(String(part));
+	}
+	const formattedMessage = messageParts.join("");
+	const ts = record.timestamp;
+	const timestamp = new Date(ts != null && !Number.isNaN(ts) ? ts : Date.now()).toISOString();
+	const category = record.category.join(".");
+	const level = record.level.toUpperCase().padEnd(7);
+	return `${timestamp} [${level}] ${category}: ${formattedMessage}`;
+}
 /**
 * Creates a sink from a {@link LogOutput} destination.
 *
@@ -409,7 +483,10 @@ function createConsoleSink(options = {}) {
 * @since 0.8.0
 */
 async function createSink(output, consoleSinkOptions = {}) {
-	if (output.type === "console") return createConsoleSink(consoleSinkOptions);
+	if (output.type === "console") return createConsoleSink({
+		...consoleSinkOptions,
+		formatter: consoleSinkOptions.formatter ?? output.formatter
+	});
 	let getFileSink;
 	try {
 		({getFileSink} = await import("@logtape/file"));
@@ -421,7 +498,7 @@ async function createSink(output, consoleSinkOptions = {}) {
 
 Original error: ${e}`);
 	}
-	return getFileSink(output.path);
+	return getFileSink(output.path, output.formatter == null ? void 0 : { formatter: output.formatter });
 }
 
 //#endregion
@@ -482,6 +559,7 @@ function loggingOptions(config) {
 	const groupLabel = config.groupLabel ?? "Logging options";
 	const outputEnabled = config.output?.enabled !== false;
 	const outputLong = config.output?.long ?? "--log-output";
+	const outputFormatter = config.formatter;
 	let levelParser;
 	switch (config.level) {
 		case "option": {
@@ -513,35 +591,40 @@ function loggingOptions(config) {
 		}
 		default: throw new TypeError(`Unsupported level configuration: ${String(config.level)}.  Expected "option", "verbosity", or "debug".`);
 	}
-	const defaultOutput = { type: "console" };
-	const outputParser = (0, __optique_core_modifiers.withDefault)(logOutput({ long: outputLong }), defaultOutput);
-	if (!outputEnabled) {
-		const constantOutputParser = {
-			mode: "sync",
-			$valueType: [],
-			$stateType: [],
-			priority: 0,
-			usage: [],
-			leadingNames: /* @__PURE__ */ new Set(),
-			acceptingAnyToken: false,
-			initialState: void 0,
-			parse: (context) => ({
-				success: true,
-				next: context,
-				consumed: []
-			}),
-			complete: () => ({
-				success: true,
-				value: defaultOutput
-			}),
-			*suggest() {},
-			getDocFragments: () => ({ fragments: [] })
-		};
-		return (0, __optique_core_constructs.group)(groupLabel, (0, __optique_core_constructs.object)({
-			logLevel: levelParser,
-			logOutput: constantOutputParser
-		}));
-	}
+	const defaultOutput = typeof outputFormatter === "function" ? {
+		type: "console",
+		formatter: outputFormatter
+	} : { type: "console" };
+	let outputParser;
+	if (outputEnabled) outputParser = (0, __optique_core_modifiers.withDefault)(logOutput({
+		long: outputLong,
+		formatter: outputFormatter
+	}), defaultOutput);
+	else if (typeof outputFormatter === "string") outputParser = createTextFormatterOption(outputFormatter).map((formatter) => formatter == null ? defaultOutput : {
+		type: "console",
+		formatter
+	});
+	else outputParser = {
+		mode: "sync",
+		$valueType: [],
+		$stateType: [],
+		priority: 0,
+		usage: [],
+		leadingNames: /* @__PURE__ */ new Set(),
+		acceptingAnyToken: false,
+		initialState: void 0,
+		parse: (context) => ({
+			success: true,
+			next: context,
+			consumed: []
+		}),
+		complete: () => ({
+			success: true,
+			value: defaultOutput
+		}),
+		*suggest() {},
+		getDocFragments: () => ({ fragments: [] })
+	};
 	const innerParser = (0, __optique_core_constructs.object)({
 		logLevel: levelParser,
 		logOutput: outputParser
@@ -620,4 +703,5 @@ exports.debug = debug;
 exports.logLevel = logLevel;
 exports.logOutput = logOutput;
 exports.loggingOptions = loggingOptions;
+exports.textFormatter = textFormatter;
 exports.verbosity = verbosity;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Config, LogLevel, LogLevel as LogLevel$1, LogRecord, Sink, Sink as Sink$1 } from "@logtape/logtape";
+import { Config, ConsoleFormatter, LogLevel, LogLevel as LogLevel$1, LogRecord, Sink, Sink as Sink$1, TextFormatter } from "@logtape/logtape";
 import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
 import { Message } from "@optique/core/message";
 import { FluentParser } from "@optique/core/fluent";
@@ -73,6 +73,34 @@ interface LogLevelOptions {
  */
 declare function logLevel(options?: LogLevelOptions): ValueParser<"sync", LogLevel$1>;
 //#endregion
+//#region src/textformatter.d.ts
+/**
+ * The names accepted by {@link textFormatter}.
+ * @since 1.2.0
+ */
+type TextFormatterName = "jsonl" | "logfmt" | "color" | "plain";
+/**
+ * Creates a {@link ValueParser} for LogTape text formatters.
+ *
+ * This parser accepts `"jsonl"`, `"logfmt"`, `"color"`, and `"plain"` and
+ * maps them to LogTape's `jsonLinesFormatter`, `logfmtFormatter`,
+ * `ansiColorFormatter`, and `defaultTextFormatter` respectively.
+ *
+ * @returns A {@link ValueParser} that converts formatter names to
+ *   LogTape text formatter functions.
+ *
+ * @example
+ * ```typescript
+ * import { option } from "@optique/core";
+ * import { textFormatter } from "@optique/logtape";
+ *
+ * const parser = option("--log-format", textFormatter());
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare function textFormatter(): ValueParser<"sync", TextFormatter>;
+//#endregion
 //#region src/verbosity.d.ts
 /**
  * Options for creating a verbosity parser.
@@ -229,9 +257,11 @@ declare function debug(options?: DebugOptions): FluentParser<"sync", LogLevel$1,
  */
 type LogOutput = {
   readonly type: "console";
+  readonly formatter?: TextFormatter;
 } | {
   readonly type: "file";
   readonly path: string;
+  readonly formatter?: TextFormatter;
 };
 /**
  * Options for configuring console sink creation.
@@ -258,6 +288,16 @@ interface ConsoleSinkOptions {
    * ```
    */
   readonly streamResolver?: (level: LogLevel$1) => "stdout" | "stderr";
+  /**
+   * A formatter for converting log records to console output.
+   * Text formatters return one string argument, while console formatters
+   * return the full argument list passed to the selected console method.
+   *
+   * If omitted, records are formatted as
+   * `ISO_TIMESTAMP [LEVEL] category: message`.
+   * @since 1.2.0
+   */
+  readonly formatter?: TextFormatter | ConsoleFormatter;
 }
 /**
  * Options for creating a log output parser.
@@ -282,6 +322,26 @@ interface LogOutputOptions {
    * Description to show in help text.
    */
   readonly description?: Message;
+  /**
+   * Text formatter to apply to the selected log output, or a long option name
+   * for selecting the text formatter from the command line.
+   *
+   * When a string is specified, this adds an option that accepts `"jsonl"`,
+   * `"logfmt"`, `"color"`, and `"plain"` and stores the selected formatter in
+   * the resulting {@link LogOutput}. If the formatter option is specified
+   * without a log output option, the output defaults to console.
+   *
+   * When a formatter function is specified, it is applied to the resulting
+   * {@link LogOutput} only when the log output option itself is present.
+   *
+   * @example
+   * ```typescript
+   * logOutput({ formatter: "--log-format" })
+   * ```
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Custom error messages.
    */
@@ -318,6 +378,16 @@ interface LogOutputOptions {
  * @since 0.8.0
  */
 declare function logOutput(options?: LogOutputOptions): FluentParser<"sync", LogOutput | undefined, unknown>;
+/**
+ * Creates an optional parser for a text formatter option.
+ *
+ * @param long The long option name for selecting the formatter.
+ * @returns A parser that produces the selected {@link TextFormatter}, or
+ *   `undefined` when the option is not present.
+ * @throws {TypeError} If `long` is not a valid option name.
+ * @since 1.2.0
+ */
+
 /**
  * Creates a console sink with configurable stream selection.
  *
@@ -444,6 +514,13 @@ interface LoggingOptionsWithLevel {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -478,6 +555,13 @@ interface LoggingOptionsWithVerbosity {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -517,6 +601,13 @@ interface LoggingOptionsWithDebug {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -637,4 +728,4 @@ declare function loggingOptions(config: LoggingOptionsConfig): FluentParser<"syn
  */
 declare function createLoggingConfig(options: LoggingOptionsResult, consoleSinkOptions?: ConsoleSinkOptions, additionalConfig?: Partial<Config<string, string>>): Promise<Config<string, string>>;
 //#endregion
-export { type ConsoleSinkOptions, type DebugOptions, LOG_LEVELS, type LogLevel, type LogLevelOptions, type LogOutput, type LogOutputConfig, type LogOutputOptions, type LogRecord, type LoggingOptionsConfig, type LoggingOptionsResult, type LoggingOptionsWithDebug, type LoggingOptionsWithLevel, type LoggingOptionsWithVerbosity, type Sink, type VerbosityOptions, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, verbosity };
+export { type ConsoleSinkOptions, type DebugOptions, LOG_LEVELS, type LogLevel, type LogLevelOptions, type LogOutput, type LogOutputConfig, type LogOutputOptions, type LogRecord, type LoggingOptionsConfig, type LoggingOptionsResult, type LoggingOptionsWithDebug, type LoggingOptionsWithLevel, type LoggingOptionsWithVerbosity, type Sink, type TextFormatterName, type VerbosityOptions, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, textFormatter, verbosity };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
+import { Config, ConsoleFormatter, LogLevel, LogLevel as LogLevel$1, LogRecord, Sink, Sink as Sink$1, TextFormatter } from "@logtape/logtape";
 import { Message } from "@optique/core/message";
-import { Config, LogLevel, LogLevel as LogLevel$1, LogRecord, Sink, Sink as Sink$1 } from "@logtape/logtape";
 import { FluentParser } from "@optique/core/fluent";
 
 //#region src/loglevel.d.ts
@@ -73,6 +73,34 @@ interface LogLevelOptions {
  */
 declare function logLevel(options?: LogLevelOptions): ValueParser<"sync", LogLevel$1>;
 //#endregion
+//#region src/textformatter.d.ts
+/**
+ * The names accepted by {@link textFormatter}.
+ * @since 1.2.0
+ */
+type TextFormatterName = "jsonl" | "logfmt" | "color" | "plain";
+/**
+ * Creates a {@link ValueParser} for LogTape text formatters.
+ *
+ * This parser accepts `"jsonl"`, `"logfmt"`, `"color"`, and `"plain"` and
+ * maps them to LogTape's `jsonLinesFormatter`, `logfmtFormatter`,
+ * `ansiColorFormatter`, and `defaultTextFormatter` respectively.
+ *
+ * @returns A {@link ValueParser} that converts formatter names to
+ *   LogTape text formatter functions.
+ *
+ * @example
+ * ```typescript
+ * import { option } from "@optique/core";
+ * import { textFormatter } from "@optique/logtape";
+ *
+ * const parser = option("--log-format", textFormatter());
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare function textFormatter(): ValueParser<"sync", TextFormatter>;
+//#endregion
 //#region src/verbosity.d.ts
 /**
  * Options for creating a verbosity parser.
@@ -229,9 +257,11 @@ declare function debug(options?: DebugOptions): FluentParser<"sync", LogLevel$1,
  */
 type LogOutput = {
   readonly type: "console";
+  readonly formatter?: TextFormatter;
 } | {
   readonly type: "file";
   readonly path: string;
+  readonly formatter?: TextFormatter;
 };
 /**
  * Options for configuring console sink creation.
@@ -258,6 +288,16 @@ interface ConsoleSinkOptions {
    * ```
    */
   readonly streamResolver?: (level: LogLevel$1) => "stdout" | "stderr";
+  /**
+   * A formatter for converting log records to console output.
+   * Text formatters return one string argument, while console formatters
+   * return the full argument list passed to the selected console method.
+   *
+   * If omitted, records are formatted as
+   * `ISO_TIMESTAMP [LEVEL] category: message`.
+   * @since 1.2.0
+   */
+  readonly formatter?: TextFormatter | ConsoleFormatter;
 }
 /**
  * Options for creating a log output parser.
@@ -282,6 +322,26 @@ interface LogOutputOptions {
    * Description to show in help text.
    */
   readonly description?: Message;
+  /**
+   * Text formatter to apply to the selected log output, or a long option name
+   * for selecting the text formatter from the command line.
+   *
+   * When a string is specified, this adds an option that accepts `"jsonl"`,
+   * `"logfmt"`, `"color"`, and `"plain"` and stores the selected formatter in
+   * the resulting {@link LogOutput}. If the formatter option is specified
+   * without a log output option, the output defaults to console.
+   *
+   * When a formatter function is specified, it is applied to the resulting
+   * {@link LogOutput} only when the log output option itself is present.
+   *
+   * @example
+   * ```typescript
+   * logOutput({ formatter: "--log-format" })
+   * ```
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Custom error messages.
    */
@@ -318,6 +378,16 @@ interface LogOutputOptions {
  * @since 0.8.0
  */
 declare function logOutput(options?: LogOutputOptions): FluentParser<"sync", LogOutput | undefined, unknown>;
+/**
+ * Creates an optional parser for a text formatter option.
+ *
+ * @param long The long option name for selecting the formatter.
+ * @returns A parser that produces the selected {@link TextFormatter}, or
+ *   `undefined` when the option is not present.
+ * @throws {TypeError} If `long` is not a valid option name.
+ * @since 1.2.0
+ */
+
 /**
  * Creates a console sink with configurable stream selection.
  *
@@ -444,6 +514,13 @@ interface LoggingOptionsWithLevel {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -478,6 +555,13 @@ interface LoggingOptionsWithVerbosity {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -517,6 +601,13 @@ interface LoggingOptionsWithDebug {
    * Configuration for log output option.
    */
   readonly output?: LogOutputConfig;
+  /**
+   * Text formatter to apply to the generated sink, or a long option name for
+   * selecting the text formatter from the command line.
+   *
+   * @since 1.2.0
+   */
+  readonly formatter?: string | TextFormatter;
   /**
    * Label for the option group in help text.
    * @default `"Logging options"`
@@ -637,4 +728,4 @@ declare function loggingOptions(config: LoggingOptionsConfig): FluentParser<"syn
  */
 declare function createLoggingConfig(options: LoggingOptionsResult, consoleSinkOptions?: ConsoleSinkOptions, additionalConfig?: Partial<Config<string, string>>): Promise<Config<string, string>>;
 //#endregion
-export { type ConsoleSinkOptions, type DebugOptions, LOG_LEVELS, type LogLevel, type LogLevelOptions, type LogOutput, type LogOutputConfig, type LogOutputOptions, type LogRecord, type LoggingOptionsConfig, type LoggingOptionsResult, type LoggingOptionsWithDebug, type LoggingOptionsWithLevel, type LoggingOptionsWithVerbosity, type Sink, type VerbosityOptions, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, verbosity };
+export { type ConsoleSinkOptions, type DebugOptions, LOG_LEVELS, type LogLevel, type LogLevelOptions, type LogOutput, type LogOutputConfig, type LogOutputOptions, type LogRecord, type LoggingOptionsConfig, type LoggingOptionsResult, type LoggingOptionsWithDebug, type LoggingOptionsWithLevel, type LoggingOptionsWithVerbosity, type Sink, type TextFormatterName, type VerbosityOptions, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, textFormatter, verbosity };

package/dist/index.js

@@ -1,10 +1,11 @@
-import { choice } from "@optique/core/valueparser";
+import { biject, choice } from "@optique/core/valueparser";
+import { ansiColorFormatter, defaultTextFormatter, jsonLinesFormatter, logfmtFormatter } from "@logtape/logtape";
 import { flag, option } from "@optique/core/primitives";
 import { map, multiple, optional, withDefault } from "@optique/core/modifiers";
 import { message } from "@optique/core/message";
 import { basename } from "node:path";
-import { ensureNonEmptyString } from "@optique/core/nonempty";
 import { group, object } from "@optique/core/constructs";
+import { ensureNonEmptyString } from "@optique/core/nonempty";
 
 //#region src/loglevel.ts
 /**
@@ -69,6 +70,38 @@ function logLevel(options = {}) {
 	});
 }
 
+//#endregion
+//#region src/textformatter.ts
+const textFormatters = {
+	jsonl: jsonLinesFormatter,
+	logfmt: logfmtFormatter,
+	color: ansiColorFormatter,
+	plain: defaultTextFormatter
+};
+/**
+* Creates a {@link ValueParser} for LogTape text formatters.
+*
+* This parser accepts `"jsonl"`, `"logfmt"`, `"color"`, and `"plain"` and
+* maps them to LogTape's `jsonLinesFormatter`, `logfmtFormatter`,
+* `ansiColorFormatter`, and `defaultTextFormatter` respectively.
+*
+* @returns A {@link ValueParser} that converts formatter names to
+*   LogTape text formatter functions.
+*
+* @example
+* ```typescript
+* import { option } from "@optique/core";
+* import { textFormatter } from "@optique/logtape";
+*
+* const parser = option("--log-format", textFormatter());
+* ```
+*
+* @since 1.2.0
+*/
+function textFormatter() {
+	return biject(textFormatters);
+}
+
 //#endregion
 //#region src/verbosity.ts
 /**
@@ -283,9 +316,41 @@ function logOutput(options = {}) {
 	const description = options.description ?? message`Log output destination. Use ${"-"} for console.`;
 	if (options.short) {
 		const short = options.short;
-		return optional(option(short, long, valueParser, { description }));
+		const outputParser$1 = optional(option(short, long, valueParser, { description }));
+		return withFormatter(outputParser$1, options.formatter);
 	}
-	return optional(option(long, valueParser, { description }));
+	const outputParser = optional(option(long, valueParser, { description }));
+	return withFormatter(outputParser, options.formatter);
+}
+function withFormatter(outputParser, formatter) {
+	if (formatter == null) return outputParser;
+	if (typeof formatter !== "string") return outputParser.map((output) => output == null ? void 0 : {
+		...output,
+		formatter
+	});
+	const formatterParser = createTextFormatterOption(formatter);
+	return object({
+		output: outputParser,
+		formatter: formatterParser
+	}).map(({ output, formatter: formatter$1 }) => {
+		if (formatter$1 == null) return output;
+		return {
+			...output ?? { type: "console" },
+			formatter: formatter$1
+		};
+	});
+}
+/**
+* Creates an optional parser for a text formatter option.
+*
+* @param long The long option name for selecting the formatter.
+* @returns A parser that produces the selected {@link TextFormatter}, or
+*   `undefined` when the option is not present.
+* @throws {TypeError} If `long` is not a valid option name.
+* @since 1.2.0
+*/
+function createTextFormatterOption(long) {
+	return optional(option(long, textFormatter(), { description: message`Log output format.` }));
 }
 /**
 * Creates a console sink with configurable stream selection.
@@ -323,6 +388,7 @@ function logOutput(options = {}) {
 function createConsoleSink(options = {}) {
 	const streamResolver = options.streamResolver;
 	const defaultStream = options.stream ?? "stderr";
+	const formatter = options.formatter ?? defaultConsoleFormatter;
 	const invalidStreamError = (value) => {
 		let repr;
 		if (typeof value === "string") repr = JSON.stringify(value);
@@ -338,22 +404,30 @@ function createConsoleSink(options = {}) {
 	return (record) => {
 		const stream = streamResolver ? streamResolver(record.level) : defaultStream;
 		if (stream !== "stdout" && stream !== "stderr") throw invalidStreamError(stream);
-		const messageParts = [];
-		for (let i = 0; i < record.message.length; i++) {
-			const part = record.message[i];
-			if (typeof part === "string") messageParts.push(part);
-			else messageParts.push(String(part));
-		}
-		const formattedMessage = messageParts.join("");
-		const ts = record.timestamp;
-		const timestamp = new Date(ts != null && !Number.isNaN(ts) ? ts : Date.now()).toISOString();
-		const category = record.category.join(".");
-		const level = record.level.toUpperCase().padEnd(7);
-		const line = `${timestamp} [${level}] ${category}: ${formattedMessage}`;
-		if (stream === "stderr") console.error(line);
-		else console.log(line);
+		const args = toConsoleArgs(formatter(record));
+		if (stream === "stderr") console.error(...args);
+		else console.log(...args);
 	};
 }
+function toConsoleArgs(value) {
+	if (typeof value === "string") return [value.replace(/\r?\n$/, "")];
+	if (Array.isArray(value)) return value;
+	return value == null ? [] : [value];
+}
+function defaultConsoleFormatter(record) {
+	const messageParts = [];
+	for (let i = 0; i < record.message.length; i++) {
+		const part = record.message[i];
+		if (typeof part === "string") messageParts.push(part);
+		else messageParts.push(String(part));
+	}
+	const formattedMessage = messageParts.join("");
+	const ts = record.timestamp;
+	const timestamp = new Date(ts != null && !Number.isNaN(ts) ? ts : Date.now()).toISOString();
+	const category = record.category.join(".");
+	const level = record.level.toUpperCase().padEnd(7);
+	return `${timestamp} [${level}] ${category}: ${formattedMessage}`;
+}
 /**
 * Creates a sink from a {@link LogOutput} destination.
 *
@@ -386,7 +460,10 @@ function createConsoleSink(options = {}) {
 * @since 0.8.0
 */
 async function createSink(output, consoleSinkOptions = {}) {
-	if (output.type === "console") return createConsoleSink(consoleSinkOptions);
+	if (output.type === "console") return createConsoleSink({
+		...consoleSinkOptions,
+		formatter: consoleSinkOptions.formatter ?? output.formatter
+	});
 	let getFileSink;
 	try {
 		({getFileSink} = await import("@logtape/file"));
@@ -398,7 +475,7 @@ async function createSink(output, consoleSinkOptions = {}) {
 
 Original error: ${e}`);
 	}
-	return getFileSink(output.path);
+	return getFileSink(output.path, output.formatter == null ? void 0 : { formatter: output.formatter });
 }
 
 //#endregion
@@ -459,6 +536,7 @@ function loggingOptions(config) {
 	const groupLabel = config.groupLabel ?? "Logging options";
 	const outputEnabled = config.output?.enabled !== false;
 	const outputLong = config.output?.long ?? "--log-output";
+	const outputFormatter = config.formatter;
 	let levelParser;
 	switch (config.level) {
 		case "option": {
@@ -490,35 +568,40 @@ function loggingOptions(config) {
 		}
 		default: throw new TypeError(`Unsupported level configuration: ${String(config.level)}.  Expected "option", "verbosity", or "debug".`);
 	}
-	const defaultOutput = { type: "console" };
-	const outputParser = withDefault(logOutput({ long: outputLong }), defaultOutput);
-	if (!outputEnabled) {
-		const constantOutputParser = {
-			mode: "sync",
-			$valueType: [],
-			$stateType: [],
-			priority: 0,
-			usage: [],
-			leadingNames: /* @__PURE__ */ new Set(),
-			acceptingAnyToken: false,
-			initialState: void 0,
-			parse: (context) => ({
-				success: true,
-				next: context,
-				consumed: []
-			}),
-			complete: () => ({
-				success: true,
-				value: defaultOutput
-			}),
-			*suggest() {},
-			getDocFragments: () => ({ fragments: [] })
-		};
-		return group(groupLabel, object({
-			logLevel: levelParser,
-			logOutput: constantOutputParser
-		}));
-	}
+	const defaultOutput = typeof outputFormatter === "function" ? {
+		type: "console",
+		formatter: outputFormatter
+	} : { type: "console" };
+	let outputParser;
+	if (outputEnabled) outputParser = withDefault(logOutput({
+		long: outputLong,
+		formatter: outputFormatter
+	}), defaultOutput);
+	else if (typeof outputFormatter === "string") outputParser = createTextFormatterOption(outputFormatter).map((formatter) => formatter == null ? defaultOutput : {
+		type: "console",
+		formatter
+	});
+	else outputParser = {
+		mode: "sync",
+		$valueType: [],
+		$stateType: [],
+		priority: 0,
+		usage: [],
+		leadingNames: /* @__PURE__ */ new Set(),
+		acceptingAnyToken: false,
+		initialState: void 0,
+		parse: (context) => ({
+			success: true,
+			next: context,
+			consumed: []
+		}),
+		complete: () => ({
+			success: true,
+			value: defaultOutput
+		}),
+		*suggest() {},
+		getDocFragments: () => ({ fragments: [] })
+	};
 	const innerParser = object({
 		logLevel: levelParser,
 		logOutput: outputParser
@@ -589,4 +672,4 @@ async function createLoggingConfig(options, consoleSinkOptions = {}, additionalC
 }
 
 //#endregion
-export { LOG_LEVELS, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, verbosity };
+export { LOG_LEVELS, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, textFormatter, verbosity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/logtape",
-  "version": "1.2.0-dev.2322",
+  "version": "1.2.0-dev.2329",
   "description": "LogTape logging integration for Optique CLI parser",
   "keywords": [
     "CLI",
@@ -60,8 +60,8 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@logtape/file": "^2.0.4",
-    "@logtape/logtape": "^2.0.4"
+    "@logtape/file": "^2.2.2",
+    "@logtape/logtape": "^2.2.2"
   },
   "peerDependenciesMeta": {
     "@logtape/file": {
@@ -69,11 +69,11 @@
     }
   },
   "dependencies": {
-    "@optique/core": "1.2.0-dev.2322+fa56f91e"
+    "@optique/core": "1.2.0-dev.2329+7836254a"
   },
   "devDependencies": {
-    "@logtape/file": "^2.0.4",
-    "@logtape/logtape": "^2.0.4",
+    "@logtape/file": "^2.2.2",
+    "@logtape/logtape": "^2.2.2",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3"