@optique/logtape 0.8.0-dev.1

package/dist/index.js

@@ -0,0 +1,539 @@
+import { choice } from "@optique/core/valueparser";
+import { flag, option } from "@optique/core/primitives";
+import { map, multiple, optional, withDefault } from "@optique/core/modifiers";
+import { message } from "@optique/core/message";
+import { group, object } from "@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 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 = flag(short, long, { description: options.description });
+	const multipleFlags = multiple(flagParser);
+	return 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 = flag(short, long, { description: options.description });
+	return map(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 : 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 optional(option(short, long, valueParser, { description: options.description }));
+	}
+	return optional(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 = withDefault(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 = 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 group(groupLabel, object({
+			logLevel: levelParser,
+			logOutput: constantOutputParser
+		}));
+	}
+	const innerParser = object({
+		logLevel: levelParser,
+		logOutput: outputParser
+	});
+	return 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
+export { LOG_LEVELS, createConsoleSink, createLoggingConfig, createSink, debug, logLevel, logOutput, loggingOptions, verbosity };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@optique/logtape",
+  "version": "0.8.0-dev.1",
+  "description": "LogTape logging integration for Optique CLI parser",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "logging",
+    "logtape"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/logtape/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@logtape/logtape": "^1.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@logtape/file": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@optique/core": ""
+  },
+  "devDependencies": {
+    "@logtape/logtape": "^1.2.2",
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}