@optique/logtape 0.8.0-dev.1

package/dist/index.cjs

@@ -0,0 +1,570 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
+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 __optique_core_constructs = __toESM(require("@optique/core/constructs"));
+
+//#region src/loglevel.ts
+/**
+* All valid log levels in order from lowest to highest severity.
+*/
+const LOG_LEVELS = [
+	"trace",
+	"debug",
+	"info",
+	"warning",
+	"error",
+	"fatal"
+];
+/**
+* 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
+*/
+function logLevel(options = {}) {
+	return (0, __optique_core_valueparser.choice)(LOG_LEVELS, {
+		metavar: options.metavar ?? "LEVEL",
+		caseInsensitive: true,
+		errors: options.errors?.invalidLevel != null ? { invalidChoice: typeof options.errors.invalidLevel === "function" ? (input, _choices) => options.errors.invalidLevel(input) : options.errors.invalidLevel } : void 0
+	});
+}
+
+//#endregion
+//#region src/verbosity.ts
+/**
+* Mapping from verbosity count (offset from base) to log level.
+* Index 0 is base, 1 is base+1 flag, 2 is base+2 flags, etc.
+*/
+const VERBOSITY_LEVELS = [
+	"fatal",
+	"error",
+	"warning",
+	"info",
+	"debug",
+	"trace"
+];
+/**
+* Index of "warning" in VERBOSITY_LEVELS (the default base level).
+*/
+const WARNING_INDEX = 2;
+/**
+* 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
+*/
+function verbosity(options = {}) {
+	const short = options.short ?? "-v";
+	const long = options.long ?? "--verbose";
+	const baseLevel = options.baseLevel ?? "warning";
+	const baseIndex = VERBOSITY_LEVELS.indexOf(baseLevel);
+	const effectiveBaseIndex = baseIndex >= 0 ? baseIndex : WARNING_INDEX;
+	const flagParser = (0, __optique_core_primitives.flag)(short, long, { description: options.description });
+	const multipleFlags = (0, __optique_core_modifiers.multiple)(flagParser);
+	return (0, __optique_core_modifiers.map)(multipleFlags, (flags) => {
+		const count = flags.length;
+		const targetIndex = Math.min(effectiveBaseIndex + count, VERBOSITY_LEVELS.length - 1);
+		return VERBOSITY_LEVELS[targetIndex];
+	});
+}
+
+//#endregion
+//#region src/debug.ts
+/**
+* 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
+*/
+function debug(options = {}) {
+	const short = options.short ?? "-d";
+	const long = options.long ?? "--debug";
+	const debugLevel = options.debugLevel ?? "debug";
+	const normalLevel = options.normalLevel ?? "info";
+	const flagParser = (0, __optique_core_primitives.flag)(short, long, { description: options.description });
+	return (0, __optique_core_modifiers.map)((0, __optique_core_modifiers.optional)(flagParser), (value) => {
+		return value === true ? debugLevel : normalLevel;
+	});
+}
+
+//#endregion
+//#region src/output.ts
+/**
+* Creates a value parser for log output destinations.
+*
+* This parser accepts either `-` for console output or a file path for file
+* output. The `-` value follows the common CLI convention for representing
+* standard output/error.
+*
+* @param options Configuration options for the parser.
+* @returns A {@link ValueParser} that produces a {@link LogOutput}.
+*/
+function logOutputValueParser(options = {}) {
+	return {
+		metavar: options.metavar ?? "FILE",
+		parse(input) {
+			if (input === "-") return {
+				success: true,
+				value: { type: "console" }
+			};
+			if (input.trim() === "") return {
+				success: false,
+				error: options.errors?.emptyPath ? typeof options.errors.emptyPath === "function" ? options.errors.emptyPath(input) : options.errors.emptyPath : __optique_core_message.message`Log output path cannot be empty.`
+			};
+			return {
+				success: true,
+				value: {
+					type: "file",
+					path: input
+				}
+			};
+		},
+		format(value) {
+			return value.type === "console" ? "-" : value.path;
+		},
+		*suggest(prefix) {
+			if ("-".startsWith(prefix)) yield {
+				kind: "literal",
+				text: "-"
+			};
+			yield {
+				kind: "file",
+				type: "file",
+				pattern: prefix
+			};
+		}
+	};
+}
+/**
+* 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
+*/
+function logOutput(options = {}) {
+	const long = options.long ?? "--log-output";
+	const valueParser = logOutputValueParser(options);
+	if (options.short) {
+		const short = options.short;
+		return (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(short, long, valueParser, { description: options.description }));
+	}
+	return (0, __optique_core_modifiers.optional)((0, __optique_core_primitives.option)(long, valueParser, { description: options.description }));
+}
+/**
+* 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
+*/
+function createConsoleSink(options = {}) {
+	const defaultStream = options.stream ?? "stderr";
+	const streamResolver = options.streamResolver;
+	return (record) => {
+		const stream = streamResolver ? streamResolver(record.level) : defaultStream;
+		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 timestamp = record.timestamp ? new Date(record.timestamp).toISOString() : (/* @__PURE__ */ new Date()).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);
+	};
+}
+/**
+* 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
+*/
+async function createSink(output, consoleSinkOptions = {}) {
+	if (output.type === "console") return createConsoleSink(consoleSinkOptions);
+	try {
+		const { getFileSink } = await import("@logtape/file");
+		return getFileSink(output.path);
+	} catch (e) {
+		throw new Error(`File sink requires @logtape/file package. Install it with:
+  npm install @logtape/file
+  # or
+  deno add jsr:@logtape/file
+
+Original error: ${e}`);
+	}
+}
+
+//#endregion
+//#region src/preset.ts
+/**
+* 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
+*/
+function loggingOptions(config) {
+	const groupLabel = config.groupLabel ?? "Logging options";
+	const outputEnabled = config.output?.enabled !== false;
+	const outputLong = config.output?.long ?? "--log-output";
+	let levelParser;
+	switch (config.level) {
+		case "option": {
+			const long = config.long ?? "--log-level";
+			const short = config.short ?? "-l";
+			const defaultLevel = config.default ?? "info";
+			levelParser = (0, __optique_core_modifiers.withDefault)((0, __optique_core_primitives.option)(short, long, logLevel()), defaultLevel);
+			break;
+		}
+		case "verbosity": {
+			const verbosityOptions = {
+				short: config.short,
+				long: config.long,
+				baseLevel: config.baseLevel
+			};
+			levelParser = verbosity(verbosityOptions);
+			break;
+		}
+		case "debug": {
+			const debugOptions = {
+				short: config.short,
+				long: config.long,
+				debugLevel: config.debugLevel,
+				normalLevel: config.normalLevel
+			};
+			levelParser = debug(debugOptions);
+			break;
+		}
+	}
+	const defaultOutput = { type: "console" };
+	const outputParser = (0, __optique_core_modifiers.withDefault)(logOutput({ long: outputLong }), defaultOutput);
+	if (!outputEnabled) {
+		const constantOutputParser = {
+			$valueType: [],
+			$stateType: [],
+			priority: 0,
+			usage: [],
+			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 innerParser = (0, __optique_core_constructs.object)({
+		logLevel: levelParser,
+		logOutput: outputParser
+	});
+	return (0, __optique_core_constructs.group)(groupLabel, innerParser);
+}
+/**
+* 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
+*/
+async function createLoggingConfig(options, consoleSinkOptions = {}, additionalConfig = {}) {
+	const sink = await createSink(options.logOutput, consoleSinkOptions);
+	return {
+		sinks: {
+			default: sink,
+			...additionalConfig.sinks
+		},
+		loggers: [{
+			category: [],
+			lowestLevel: options.logLevel,
+			sinks: ["default"]
+		}, ...additionalConfig.loggers ?? []],
+		filters: additionalConfig.filters,
+		reset: additionalConfig.reset
+	};
+}
+
+//#endregion
+exports.LOG_LEVELS = LOG_LEVELS;
+exports.createConsoleSink = createConsoleSink;
+exports.createLoggingConfig = createLoggingConfig;
+exports.createSink = createSink;
+exports.debug = debug;
+exports.logLevel = logLevel;
+exports.logOutput = logOutput;
+exports.loggingOptions = loggingOptions;
+exports.verbosity = verbosity;