@optique/logtape 0.8.0-dev.1

package/dist/index.d.ts

@@ -0,0 +1,615 @@
+import { ValueParser } from "@optique/core/valueparser";
+import { Message } from "@optique/core/message";
+import { Config, LogLevel, LogLevel as LogLevel$1, LogRecord, Sink, Sink as Sink$1 } from "@logtape/logtape";
+import { Parser } from "@optique/core/parser";
+
+//#region src/loglevel.d.ts
+/**
+ * All valid log levels in order from lowest to highest severity.
+ */
+declare const LOG_LEVELS: readonly LogLevel$1[];
+/**
+ * Options for creating a log level value parser.
+ * @since 0.8.0
+ */
+interface LogLevelOptions {
+  /**
+   * The metavariable name for this parser. This is used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"LEVEL"`
+   */
+  readonly metavar?: string;
+  /**
+   * Custom error messages for log level parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid log level.
+     * Can be a static message or a function that receives the input string.
+     */
+    invalidLevel?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} for LogTape log levels.
+ *
+ * This parser validates that the input is one of the valid LogTape severity
+ * levels: `"trace"`, `"debug"`, `"info"`, `"warning"`, `"error"`, or `"fatal"`.
+ * The parsing is case-insensitive.
+ *
+ * @param options Configuration options for the log level parser.
+ * @returns A {@link ValueParser} that converts string input to {@link LogLevel}.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { logLevel } from "@optique/logtape";
+ * import { option, withDefault } from "@optique/core";
+ *
+ * const parser = object({
+ *   level: withDefault(
+ *     option("--log-level", "-l", logLevel()),
+ *     "info"
+ *   ),
+ * });
+ * ```
+ *
+ * @example Custom metavar
+ * ```typescript
+ * import { logLevel } from "@optique/logtape";
+ *
+ * const parser = logLevel({ metavar: "LOG_LEVEL" });
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function logLevel(options?: LogLevelOptions): ValueParser<LogLevel$1>;
+//#endregion
+//#region src/verbosity.d.ts
+/**
+ * Options for creating a verbosity parser.
+ * @since 0.8.0
+ */
+interface VerbosityOptions {
+  /**
+   * Short option name for the verbosity flag.
+   * @default `"-v"`
+   */
+  readonly short?: string;
+  /**
+   * Long option name for the verbosity flag.
+   * @default `"--verbose"`
+   */
+  readonly long?: string;
+  /**
+   * The base log level when no verbosity flags are provided.
+   * @default `"warning"`
+   */
+  readonly baseLevel?: LogLevel$1;
+  /**
+   * Description to show in help text.
+   */
+  readonly description?: Message;
+}
+/**
+ * Creates a parser for verbosity flags (`-v`, `-vv`, `-vvv`, etc.).
+ *
+ * This parser accumulates `-v` flags to determine the log level.
+ * Each additional `-v` flag increases the verbosity (decreases the log level
+ * severity).
+ *
+ * Default level mapping with `baseLevel: "warning"`:
+ * - No flags: `"warning"`
+ * - `-v`: `"info"`
+ * - `-vv`: `"debug"`
+ * - `-vvv` or more: `"trace"`
+ *
+ * @param options Configuration options for the verbosity parser.
+ * @returns A {@link Parser} that produces a {@link LogLevel}.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { verbosity } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   logLevel: verbosity(),
+ * });
+ *
+ * // No flags -> "warning"
+ * // -v -> "info"
+ * // -vv -> "debug"
+ * // -vvv -> "trace"
+ * ```
+ *
+ * @example Custom base level
+ * ```typescript
+ * import { verbosity } from "@optique/logtape";
+ *
+ * const parser = verbosity({ baseLevel: "error" });
+ * // No flags -> "error"
+ * // -v -> "warning"
+ * // -vv -> "info"
+ * // -vvv -> "debug"
+ * // -vvvv -> "trace"
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function verbosity(options?: VerbosityOptions): Parser<LogLevel$1, unknown>;
+//#endregion
+//#region src/debug.d.ts
+/**
+ * Options for creating a debug flag parser.
+ * @since 0.8.0
+ */
+interface DebugOptions {
+  /**
+   * Short option name for the debug flag.
+   * @default `"-d"`
+   */
+  readonly short?: string;
+  /**
+   * Long option name for the debug flag.
+   * @default `"--debug"`
+   */
+  readonly long?: string;
+  /**
+   * The log level to use when the debug flag is present.
+   * @default `"debug"`
+   */
+  readonly debugLevel?: LogLevel$1;
+  /**
+   * The log level to use when the debug flag is not present.
+   * @default `"info"`
+   */
+  readonly normalLevel?: LogLevel$1;
+  /**
+   * Description to show in help text.
+   */
+  readonly description?: Message;
+}
+/**
+ * Creates a parser for a debug flag (`-d`, `--debug`).
+ *
+ * This parser provides a simple boolean toggle for enabling debug-level
+ * logging. When the flag is present, it returns the debug level; otherwise,
+ * it returns the normal level.
+ *
+ * @param options Configuration options for the debug flag parser.
+ * @returns A {@link Parser} that produces a {@link LogLevel}.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { debug } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   logLevel: debug(),
+ * });
+ *
+ * // No flag -> "info"
+ * // --debug or -d -> "debug"
+ * ```
+ *
+ * @example Custom levels
+ * ```typescript
+ * import { debug } from "@optique/logtape";
+ *
+ * const parser = debug({
+ *   debugLevel: "trace",
+ *   normalLevel: "warning",
+ * });
+ * // No flag -> "warning"
+ * // --debug -> "trace"
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function debug(options?: DebugOptions): Parser<LogLevel$1, unknown>;
+//#endregion
+//#region src/output.d.ts
+/**
+ * Represents a log output destination.
+ *
+ * This is a discriminated union type that represents either console output
+ * or file output.
+ * @since 0.8.0
+ */
+type LogOutput = {
+  readonly type: "console";
+} | {
+  readonly type: "file";
+  readonly path: string;
+};
+/**
+ * Options for configuring console sink creation.
+ * @since 0.8.0
+ */
+interface ConsoleSinkOptions {
+  /**
+   * The stream to write to. Either `"stdout"` or `"stderr"`.
+   * @default `"stderr"`
+   */
+  readonly stream?: "stdout" | "stderr";
+  /**
+   * A function that determines which stream to use based on the log level.
+   * If provided, this takes precedence over the `stream` option.
+   *
+   * @example
+   * ```typescript
+   * // Write warnings and above to stderr, info and below to stdout
+   * streamResolver: (level) =>
+   *   level === "warning" || level === "error" || level === "fatal"
+   *     ? "stderr"
+   *     : "stdout"
+   * ```
+   */
+  readonly streamResolver?: (level: LogLevel$1) => "stdout" | "stderr";
+}
+/**
+ * Options for creating a log output parser.
+ * @since 0.8.0
+ */
+interface LogOutputOptions {
+  /**
+   * Long option name for the log output option.
+   * @default `"--log-output"`
+   */
+  readonly long?: string;
+  /**
+   * Short option name for the log output option.
+   */
+  readonly short?: string;
+  /**
+   * The metavariable name shown in help text.
+   * @default `"FILE"`
+   */
+  readonly metavar?: string;
+  /**
+   * Description to show in help text.
+   */
+  readonly description?: Message;
+  /**
+   * Custom error messages.
+   */
+  readonly errors?: {
+    /**
+     * Error message when the output path is empty.
+     */
+    emptyPath?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a parser for log output destination (`--log-output`).
+ *
+ * This parser accepts either `-` for console output (following CLI convention)
+ * or a file path for file output.
+ *
+ * @param options Configuration options for the log output parser.
+ * @returns A {@link Parser} that produces a {@link LogOutput} or `undefined`.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { logOutput } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   output: logOutput(),
+ * });
+ *
+ * // --log-output=- -> console output
+ * // --log-output=/var/log/app.log -> file output
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function logOutput(options?: LogOutputOptions): Parser<LogOutput | undefined, unknown>;
+/**
+ * Creates a console sink with configurable stream selection.
+ *
+ * This function creates a LogTape sink that writes to the console. The target
+ * stream (stdout or stderr) can be configured statically or dynamically per
+ * log record.
+ *
+ * @param options Configuration options for the console sink.
+ * @returns A {@link Sink} function.
+ *
+ * @example Static stream selection
+ * ```typescript
+ * import { createConsoleSink } from "@optique/logtape";
+ *
+ * const sink = createConsoleSink({ stream: "stderr" });
+ * ```
+ *
+ * @example Dynamic stream selection based on level
+ * ```typescript
+ * import { createConsoleSink } from "@optique/logtape";
+ *
+ * const sink = createConsoleSink({
+ *   streamResolver: (level) =>
+ *     level === "error" || level === "fatal" ? "stderr" : "stdout"
+ * });
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function createConsoleSink(options?: ConsoleSinkOptions): Sink$1;
+/**
+ * Creates a sink from a {@link LogOutput} destination.
+ *
+ * For console output, this creates a console sink. For file output, this
+ * dynamically imports `@logtape/file` and creates a file sink.
+ *
+ * @param output The log output destination.
+ * @param consoleSinkOptions Options for console sink (only used when output is console).
+ * @returns A promise that resolves to a {@link Sink}.
+ * @throws {Error} If file output is requested but `@logtape/file` is not installed.
+ *
+ * @example Console output
+ * ```typescript
+ * import { createSink } from "@optique/logtape";
+ *
+ * const sink = await createSink({ type: "console" }, { stream: "stderr" });
+ * ```
+ *
+ * @example File output
+ * ```typescript
+ * import { createSink } from "@optique/logtape";
+ *
+ * const sink = await createSink({ type: "file", path: "/var/log/app.log" });
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function createSink(output: LogOutput, consoleSinkOptions?: ConsoleSinkOptions): Promise<Sink$1>;
+//#endregion
+//#region src/preset.d.ts
+/**
+ * Result type for the logging options parser.
+ * @since 0.8.0
+ */
+interface LoggingOptionsResult {
+  /**
+   * The configured log level.
+   */
+  readonly logLevel: LogLevel$1;
+  /**
+   * The configured log output destination.
+   */
+  readonly logOutput: LogOutput;
+}
+/**
+ * Configuration for log output option in presets.
+ * @since 0.8.0
+ */
+interface LogOutputConfig {
+  /**
+   * Whether to enable the log output option.
+   * @default `true`
+   */
+  readonly enabled?: boolean;
+  /**
+   * Long option name for the log output option.
+   * @default `"--log-output"`
+   */
+  readonly long?: string;
+}
+/**
+ * Configuration for logging options preset using `--log-level` option.
+ * @since 0.8.0
+ */
+interface LoggingOptionsWithLevel {
+  /**
+   * Use explicit log level option.
+   */
+  readonly level: "option";
+  /**
+   * Long option name for the log level option.
+   * @default `"--log-level"`
+   */
+  readonly long?: string;
+  /**
+   * Short option name for the log level option.
+   * @default `"-l"`
+   */
+  readonly short?: string;
+  /**
+   * Default log level when not specified.
+   * @default `"info"`
+   */
+  readonly default?: LogLevel$1;
+  /**
+   * Configuration for log output option.
+   */
+  readonly output?: LogOutputConfig;
+  /**
+   * Label for the option group in help text.
+   * @default `"Logging options"`
+   */
+  readonly groupLabel?: string;
+}
+/**
+ * Configuration for logging options preset using `-v`/`-vv`/`-vvv` flags.
+ * @since 0.8.0
+ */
+interface LoggingOptionsWithVerbosity {
+  /**
+   * Use verbosity flags.
+   */
+  readonly level: "verbosity";
+  /**
+   * Short option name for the verbosity flag.
+   * @default `"-v"`
+   */
+  readonly short?: string;
+  /**
+   * Long option name for the verbosity flag.
+   * @default `"--verbose"`
+   */
+  readonly long?: string;
+  /**
+   * Base log level when no verbosity flags are provided.
+   * @default `"warning"`
+   */
+  readonly baseLevel?: LogLevel$1;
+  /**
+   * Configuration for log output option.
+   */
+  readonly output?: LogOutputConfig;
+  /**
+   * Label for the option group in help text.
+   * @default `"Logging options"`
+   */
+  readonly groupLabel?: string;
+}
+/**
+ * Configuration for logging options preset using `--debug` flag.
+ * @since 0.8.0
+ */
+interface LoggingOptionsWithDebug {
+  /**
+   * Use debug flag.
+   */
+  readonly level: "debug";
+  /**
+   * Long option name for the debug flag.
+   * @default `"--debug"`
+   */
+  readonly long?: string;
+  /**
+   * Short option name for the debug flag.
+   * @default `"-d"`
+   */
+  readonly short?: string;
+  /**
+   * Log level when debug flag is present.
+   * @default `"debug"`
+   */
+  readonly debugLevel?: LogLevel$1;
+  /**
+   * Log level when debug flag is not present.
+   * @default `"info"`
+   */
+  readonly normalLevel?: LogLevel$1;
+  /**
+   * Configuration for log output option.
+   */
+  readonly output?: LogOutputConfig;
+  /**
+   * Label for the option group in help text.
+   * @default `"Logging options"`
+   */
+  readonly groupLabel?: string;
+}
+/**
+ * Configuration for logging options preset.
+ *
+ * This is a discriminated union type that determines how log level is
+ * configured. Only one method can be used at a time:
+ *
+ * - `level: "option"`: Use `--log-level=LEVEL` option
+ * - `level: "verbosity"`: Use `-v`/`-vv`/`-vvv` flags
+ * - `level: "debug"`: Use `--debug` flag
+ *
+ * @since 0.8.0
+ */
+type LoggingOptionsConfig = LoggingOptionsWithLevel | LoggingOptionsWithVerbosity | LoggingOptionsWithDebug;
+/**
+ * Creates a logging options parser preset.
+ *
+ * This function creates a parser that combines log level and log output
+ * options into a single group. The log level can be configured using one of
+ * three methods (mutually exclusive):
+ *
+ * - `"option"`: Explicit `--log-level=LEVEL` option
+ * - `"verbosity"`: `-v`/`-vv`/`-vvv` flags for increasing verbosity
+ * - `"debug"`: Simple `--debug` flag toggle
+ *
+ * @param config Configuration for the logging options.
+ * @returns A {@link Parser} that produces a {@link LoggingOptionsResult}.
+ *
+ * @example Using log level option
+ * ```typescript
+ * import { loggingOptions } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   logging: loggingOptions({ level: "option" }),
+ * });
+ * // --log-level=debug --log-output=/var/log/app.log
+ * ```
+ *
+ * @example Using verbosity flags
+ * ```typescript
+ * import { loggingOptions } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   logging: loggingOptions({ level: "verbosity" }),
+ * });
+ * // -vv --log-output=-
+ * ```
+ *
+ * @example Using debug flag
+ * ```typescript
+ * import { loggingOptions } from "@optique/logtape";
+ * import { object } from "@optique/core/constructs";
+ *
+ * const parser = object({
+ *   logging: loggingOptions({ level: "debug" }),
+ * });
+ * // --debug
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function loggingOptions(config: LoggingOptionsConfig): Parser<LoggingOptionsResult, unknown>;
+/**
+ * Creates a LogTape configuration from parsed logging options.
+ *
+ * This helper function converts the result of {@link loggingOptions} parser
+ * into a configuration object that can be passed to LogTape's `configure()`
+ * function.
+ *
+ * @param options The parsed logging options.
+ * @param consoleSinkOptions Options for console sink (only used when output is console).
+ * @param additionalConfig Additional LogTape configuration to merge.
+ * @returns A promise that resolves to a LogTape {@link Config}.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { loggingOptions, createLoggingConfig } from "@optique/logtape";
+ * import { configure } from "@logtape/logtape";
+ * import { object, parse } from "@optique/core";
+ *
+ * const parser = object({
+ *   logging: loggingOptions({ level: "option" }),
+ * });
+ *
+ * const result = parse(parser, ["--log-level=debug"]);
+ * if (result.success) {
+ *   const config = await createLoggingConfig(result.value.logging);
+ *   await configure(config);
+ * }
+ * ```
+ *
+ * @example With additional configuration
+ * ```typescript
+ * import { loggingOptions, createLoggingConfig } from "@optique/logtape";
+ * import { configure } from "@logtape/logtape";
+ *
+ * const config = await createLoggingConfig(result.value.logging, {
+ *   stream: "stderr",
+ * }, {
+ *   loggers: [
+ *     { category: ["my-app", "database"], lowestLevel: "debug", sinks: ["default"] },
+ *   ],
+ * });
+ * await configure(config);
+ * ```
+ *
+ * @since 0.8.0
+ */
+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 };