@likec4/log 1.49.0 → 1.50.0

package/dist/index.d.mts

@@ -2,28 +2,61 @@ import * as _logtape_logtape0 from "@logtape/logtape";
 import { AnsiColorFormatterOptions, Config, ConsoleFormatter, ConsoleSinkOptions, Filter, LogLevel, LogRecord, LogRecord as LogRecord$1, Logger, Sink, Sink as Sink$1, TextFormatter, TextFormatter as TextFormatter$1, TextFormatterOptions, withFilter } from "@logtape/logtape";
 
 //#region src/formatters.d.ts
+/**
+ * Extract a single Error from a log record (from properties or rawMessage).
+ * @param record - Log record that may contain error in properties or rawMessage
+ * @returns Merged/wrapped Error or null if none found
+ */
 declare function errorFromLogRecord(record: LogRecord$1): Error | null;
+/**
+ * Formatter that outputs only the log message (no timestamp/level/category).
+ * @returns TextFormatter that returns just the message string
+ */
 declare function getMessageOnlyFormatter(): TextFormatter$1;
+/**
+ * Build a text formatter with optional custom format; appends error from record.
+ * @param options - Optional format and logtape options
+ * @returns TextFormatter
+ */
 declare function getTextFormatter(options?: TextFormatterOptions): TextFormatter$1;
+/**
+ * Build an ANSI-colored text formatter (level/category colors); appends error in red.
+ * @param options - Optional format and logtape ANSI options
+ * @returns TextFormatter with ANSI colors
+ */
 declare function getAnsiColorFormatter(options?: AnsiColorFormatterOptions): TextFormatter$1;
 /**
  * The formatter returns an array where:
  * - First element is the formatted message string
  * - Second element is the record properties object
+ * @param options - Optional messageFormatter (TextFormatter)
+ * @returns ConsoleFormatter for console.log/error
  */
 declare function getConsoleFormatter(options?: {
   messageFormatter?: TextFormatter$1;
 }): ConsoleFormatter;
 //#endregion
 //#region src/sink.d.ts
+/**
+ * Create a sink that writes formatted log records to stdout (default formatter).
+ * @param options - Optional console sink options (e.g. custom formatter)
+ * @returns Sink that writes to stdout
+ */
 declare function getConsoleSink(options?: ConsoleSinkOptions): Sink$1;
 /**
  * Creates a console sink that writes to stderr.
  * (MCP protocol requires stderr to be used for logging)
+ * @param options - Optional console sink options (e.g. custom formatter)
+ * @returns Sink that writes to stderr
  */
 declare function getConsoleStderrSink(options?: ConsoleSinkOptions): Sink$1;
 //#endregion
 //#region src/utils.d.ts
+/**
+ * Serialize unknown to a string (Error → message + stack; else safe-stringify).
+ * @param error - Caught value (Error, string, or arbitrary object)
+ * @returns Human-readable string for logging
+ */
 declare function loggable(error: unknown): string;
 type NormalizeError<ErrorArg> = ErrorArg extends Error ? ErrorArg : Error;
 /**
@@ -70,6 +103,10 @@ declare const logger: _logtape_logtape0.Logger;
  * @returns The child logger.
  */
 declare function createLogger(subcategory: string | readonly [string] | readonly [string, ...string[]]): _logtape_logtape0.Logger;
+/**
+ * Configure the global logger: sinks, loggers, and lowest level per category.
+ * @param config - Optional partial config (sinks, loggers). Merged with defaults.
+ */
 declare function configureLogger<TSinkId extends string, TFilterId extends string>(config?: Partial<Config<TSinkId, TFilterId>>): void;
 //#endregion
 export { type Filter, type LogLevel, type LogRecord, type Logger, type Sink, type TextFormatter, configureLogger, logger as consola, logger, logger as rootLogger, createLogger, errorFromLogRecord, getAnsiColorFormatter, getConsoleFormatter, getConsoleSink, getConsoleStderrSink, getMessageOnlyFormatter, getTextFormatter, loggable, withFilter, wrapError };

package/dist/index.mjs

@@ -1,16 +1,34 @@
 import { n as wrapErrorMessage, t as mergeErrorCause } from "./_chunks/libs/merge-error-cause.mjs";
+import "./_chunks/libs/is-error-instance.mjs";
+import "./_chunks/libs/is-plain-obj.mjs";
 import { t as safeStringify } from "./_chunks/libs/safe-stringify.mjs";
 import { configureSync, getAnsiColorFormatter as getAnsiColorFormatter$1, getConsoleSink as getConsoleSink$1, getLogger, getTextFormatter as getTextFormatter$1, withFilter } from "@logtape/logtape";
+/**
+* Split stack string into lines and normalize (e.g. strip file://).
+* @param stack - Error stack string
+* @returns Array of normalized lines
+*/
 const parseStack = (stack) => {
 	return stack.split("\n").map((l) => {
 		return l.trim().replace("file://", "");
 	});
 };
+/**
+* Indent each line of value by the given number of spaces.
+* @param value - String or array of lines to indent
+* @param indentation - Number of spaces (default 2)
+* @returns Indented string
+*/
 function indent(value, indentation = 2) {
 	value = Array.isArray(value) ? value : value.split("\n");
 	const prefix = " ".repeat(indentation);
 	return value.map((l) => `${prefix}${l}`).join("\n");
 }
+/**
+* Serialize unknown to a string (Error → message + stack; else safe-stringify).
+* @param error - Caught value (Error, string, or arbitrary object)
+* @returns Human-readable string for logging
+*/
 function loggable(error) {
 	if (typeof error === "string") return error;
 	if (error instanceof Error) {
@@ -23,36 +41,80 @@ function loggable(error) {
 	}
 	return safeStringify(error, { indentation: "	" });
 }
+/**
+* Appends `message` to `error.message`. If `message` ends with `:` or `:\n`,
+* prepends it instead.
+*
+* Returns `error`. If `error` is not an `Error` instance, it is converted to
+* one.
+*
+* @example
+* ```js
+* wrapErrorMessage(new Error('Message.'), 'Additional message.')
+* // Error: Message.
+* // Additional message.
+*
+* wrapErrorMessage(new Error('Message.'), 'Additional message:')
+* // Error: Additional message: Message.
+*
+* wrapErrorMessage(new Error('Message.'), 'Additional message:\n')
+* // Error: Additional message:
+* // Message.
+*
+* wrapErrorMessage(new Error('Message.'), '')
+* // Error: Message.
+*
+* const invalidError = 'Message.'
+* wrapErrorMessage(invalidError, 'Additional message.')
+* // Error: Message.
+* // Additional message.
+*
+* wrapErrorMessage(new Error('  Message with spaces  '), '  Additional message  ')
+* // Error: Message with spaces
+* // Additional message
+* ```
+*/
 function wrapError(error, newMessage) {
 	return wrapErrorMessage(error, newMessage);
 }
-function gerErrorFromLogRecord(record) {
+function getErrorFromLogRecord(record) {
 	const errors = Object.entries(record.properties).flatMap(([k, err]) => {
 		if (err instanceof Error) {
 			const mergedErr = mergeErrorCause(err);
 			if (mergedErr.stack) mergedErr.stack = parseStack(mergedErr.stack).join("\n");
 			return [mergedErr];
 		}
-		if (k === "error" || k === "err") return [/* @__PURE__ */ new Error(`${err}`)];
+		if (k === "error" || k === "err") return [new Error(loggable(err))];
 		return [];
 	});
 	if (errors.length === 0) return null;
 	return errors.length === 1 ? errors[0] : new AggregateError(errors);
 }
+/**
+* Extract a single Error from a log record (from properties or rawMessage).
+* @param record - Log record that may contain error in properties or rawMessage
+* @returns Merged/wrapped Error or null if none found
+*/
 function errorFromLogRecord(record) {
-	const error = gerErrorFromLogRecord(record);
+	const error = getErrorFromLogRecord(record);
 	if (error && typeof record.rawMessage === "string") return wrapErrorMessage(error, record.rawMessage + "\n");
 	return error;
 }
+/**
+* Append error from record properties to the formatted message (optionally colored).
+* @param values - Formatted values (record + message)
+* @param color - When true, wrap error text in ANSI red
+* @returns Updated FormattedValues with error appended to message
+*/
 function appendErrorToMessage(values, color = false) {
-	const error = gerErrorFromLogRecord(values.record);
+	const error = getErrorFromLogRecord(values.record);
 	if (error) {
-		let errorMessge = error.message;
-		if (error.stack) errorMessge = errorMessge + "\n" + indent(error.stack.split("\n").slice(1));
-		if (color) errorMessge = `${ansiColors.red}${errorMessge}${RESET}`;
+		let errorMessage = error.message;
+		if (error.stack) errorMessage = errorMessage + "\n" + indent(error.stack.split("\n").slice(1));
+		if (color) errorMessage = `${ansiColors.red}${errorMessage}${RESET}`;
 		return {
 			...values,
-			message: values.message + "\n" + indent(errorMessge)
+			message: values.message + "\n" + indent(errorMessage)
 		};
 	}
 	return values;
@@ -65,12 +127,21 @@ const levelAbbreviations = {
 	"error": "ERROR",
 	"fatal": "FATAL"
 };
+/**
+* Formatter that outputs only the log message (no timestamp/level/category).
+* @returns TextFormatter that returns just the message string
+*/
 function getMessageOnlyFormatter() {
 	return getTextFormatter({ format: ({ message }) => {
 		return message;
 	} });
 }
 const level = (l) => levelAbbreviations[l];
+/**
+* Build a text formatter with optional custom format; appends error from record.
+* @param options - Optional format and logtape options
+* @returns TextFormatter
+*/
 function getTextFormatter(options) {
 	const _format = options?.format ?? (({ timestamp, level, category, message }) => {
 		return `${timestamp} ${level} ${category} ${message}`;
@@ -87,6 +158,11 @@ function getTextFormatter(options) {
 }
 const RESET = "\x1B[0m";
 const ansiColors = { red: "\x1B[31m" };
+/**
+* Build an ANSI-colored text formatter (level/category colors); appends error in red.
+* @param options - Optional format and logtape ANSI options
+* @returns TextFormatter with ANSI colors
+*/
 function getAnsiColorFormatter(options) {
 	const _format = options?.format ?? (({ timestamp, level, category, message }) => {
 		return `${timestamp} ${level} ${category} ${message}`;
@@ -103,6 +179,13 @@ function getAnsiColorFormatter(options) {
 		}
 	});
 }
+/**
+* The formatter returns an array where:
+* - First element is the formatted message string
+* - Second element is the record properties object
+* @param options - Optional messageFormatter (TextFormatter)
+* @returns ConsoleFormatter for console.log/error
+*/
 function getConsoleFormatter(options) {
 	const formatter = options?.messageFormatter;
 	if (formatter) return (record) => {
@@ -116,12 +199,23 @@ function getConsoleFormatter(options) {
 		return message;
 	};
 }
+/**
+* Create a sink that writes formatted log records to stdout (default formatter).
+* @param options - Optional console sink options (e.g. custom formatter)
+* @returns Sink that writes to stdout
+*/
 function getConsoleSink(options) {
 	return getConsoleSink$1({
 		formatter: getConsoleFormatter(),
 		...options
 	});
 }
+/**
+* Creates a console sink that writes to stderr.
+* (MCP protocol requires stderr to be used for logging)
+* @param options - Optional console sink options (e.g. custom formatter)
+* @returns Sink that writes to stderr
+*/
 function getConsoleStderrSink(options) {
 	const formatter = options?.formatter ?? getConsoleFormatter();
 	return (record) => {
@@ -133,19 +227,30 @@ function getConsoleStderrSink(options) {
 	};
 }
 const logger = getLogger("likec4");
+/**
+* Get a child logger with the given subcategory.
+*
+* @param subcategory The subcategory.
+* @returns The child logger.
+*/
 function createLogger(subcategory) {
 	return logger.getChild(subcategory);
 }
+/**
+* Configure the global logger: sinks, loggers, and lowest level per category.
+* @param config - Optional partial config (sinks, loggers). Merged with defaults.
+*/
 function configureLogger(config) {
 	try {
-		const sinks = config?.sinks ?? {};
+		const { sinks = {}, loggers: _loggers, ...restConfig } = config ?? {};
+		const sinksWithConsole = {
+			console: getConsoleSink(),
+			...sinks
+		};
 		configureSync({
 			reset: true,
-			...config,
-			sinks: {
-				console: getConsoleSink(),
-				...sinks
-			},
+			...restConfig,
+			sinks: sinksWithConsole,
 			loggers: [{
 				category: ["logtape", "meta"],
 				sinks: ["console"],

package/package.json

@@ -2,7 +2,7 @@
   "name": "@likec4/log",
   "description": "Shared interface for logging",
   "license": "MIT",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "bugs": "https://github.com/likec4/likec4/issues",
   "homepage": "https://likec4.dev",
   "author": "Denis Davydkov <denis@davydkov.com>",
@@ -35,13 +35,13 @@
     "@logtape/logtape": "^1.3.7"
   },
   "devDependencies": {
-    "@types/node": "~22.19.10",
+    "@types/node": "~22.19.11",
     "merge-error-cause": "^5.0.2",
     "safe-stringify": "^1.3.0",
     "typescript": "5.9.3",
-    "obuild": "^0.4.27",
+    "obuild": "^0.4.31",
     "wrap-error-message": "^3.0.1",
-    "@likec4/tsconfig": "1.49.0",
+    "@likec4/tsconfig": "1.50.0",
     "@likec4/devops": "1.42.0"
   },
   "scripts": {

package/src/formatters.ts

@@ -11,9 +11,9 @@ import {
 } from '@logtape/logtape'
 import mergeErrorCause from 'merge-error-cause'
 import wrapErrorMessage from 'wrap-error-message'
-import { indent, parseStack } from './utils'
+import { indent, loggable, parseStack } from './utils'
 
-function gerErrorFromLogRecord(record: LogRecord): Error | null {
+function getErrorFromLogRecord(record: LogRecord): Error | null {
   const errors = Object
     .entries(record.properties)
     .flatMap(([k, err]) => {
@@ -25,7 +25,7 @@ function gerErrorFromLogRecord(record: LogRecord): Error | null {
         return [mergedErr]
       }
       if (k === 'error' || k === 'err') {
-        return [new Error(`${err}`)]
+        return [new Error(loggable(err))]
       }
       return []
     })
@@ -35,27 +35,38 @@ function gerErrorFromLogRecord(record: LogRecord): Error | null {
   return errors.length === 1 ? errors[0]! : new AggregateError(errors)
 }
 
+/**
+ * Extract a single Error from a log record (from properties or rawMessage).
+ * @param record - Log record that may contain error in properties or rawMessage
+ * @returns Merged/wrapped Error or null if none found
+ */
 export function errorFromLogRecord(record: LogRecord): Error | null {
-  const error = gerErrorFromLogRecord(record)
+  const error = getErrorFromLogRecord(record)
   if (error && typeof record.rawMessage === 'string') {
     return wrapErrorMessage(error, record.rawMessage + '\n')
   }
   return error
 }
 
+/**
+ * Append error from record properties to the formatted message (optionally colored).
+ * @param values - Formatted values (record + message)
+ * @param color - When true, wrap error text in ANSI red
+ * @returns Updated FormattedValues with error appended to message
+ */
 export function appendErrorToMessage(values: FormattedValues, color = false): FormattedValues {
-  const error = gerErrorFromLogRecord(values.record)
+  const error = getErrorFromLogRecord(values.record)
   if (error) {
-    let errorMessge = error.message
+    let errorMessage = error.message
     if (error.stack) {
-      errorMessge = errorMessge + '\n' + indent(error.stack.split('\n').slice(1))
+      errorMessage = errorMessage + '\n' + indent(error.stack.split('\n').slice(1))
     }
     if (color) {
-      errorMessge = `${ansiColors.red}${errorMessge}${RESET}`
+      errorMessage = `${ansiColors.red}${errorMessage}${RESET}`
     }
     return {
       ...values,
-      message: values.message + '\n' + indent(errorMessge),
+      message: values.message + '\n' + indent(errorMessage),
     }
   }
   return values
@@ -70,6 +81,10 @@ const levelAbbreviations: Record<LogLevel, string> = {
   'fatal': 'FATAL',
 }
 
+/**
+ * Formatter that outputs only the log message (no timestamp/level/category).
+ * @returns TextFormatter that returns just the message string
+ */
 export function getMessageOnlyFormatter(): TextFormatter {
   return getTextFormatter({
     format: ({ message }): string => {
@@ -80,11 +95,15 @@ export function getMessageOnlyFormatter(): TextFormatter {
 
 const level = (l: LogLevel): string => levelAbbreviations[l]
 
+/**
+ * Build a text formatter with optional custom format; appends error from record.
+ * @param options - Optional format and logtape options
+ * @returns TextFormatter
+ */
 export function getTextFormatter(options?: TextFormatterOptions): TextFormatter {
   const _format = options?.format ?? (({ timestamp, level, category, message }: FormattedValues): string => {
     return `${timestamp} ${level} ${category} ${message}`
   })
-  // const format = options?.format
   return getLogtapeTextFormatter({
     timestamp: 'time',
     level,
@@ -109,6 +128,11 @@ const ansiColors = {
   // white: "\x1b[37m",
 } as const
 
+/**
+ * Build an ANSI-colored text formatter (level/category colors); appends error in red.
+ * @param options - Optional format and logtape ANSI options
+ * @returns TextFormatter with ANSI colors
+ */
 export function getAnsiColorFormatter(options?: AnsiColorFormatterOptions): TextFormatter {
   const _format = options?.format ?? (({ timestamp, level, category, message }: FormattedValues): string => {
     return `${timestamp} ${level} ${category} ${message}`
@@ -130,6 +154,8 @@ export function getAnsiColorFormatter(options?: AnsiColorFormatterOptions): Text
  * The formatter returns an array where:
  * - First element is the formatted message string
  * - Second element is the record properties object
+ * @param options - Optional messageFormatter (TextFormatter)
+ * @returns ConsoleFormatter for console.log/error
  */
 export function getConsoleFormatter(options?: {
   messageFormatter?: TextFormatter

package/src/index.ts

@@ -1,5 +1,6 @@
 import {
   type Config,
+  type Sink,
   configureSync as configureLogtape,
   getLogger,
 } from '@logtape/logtape'
@@ -53,18 +54,23 @@ export function createLogger(subcategory: string | readonly [string] | readonly
   return logger.getChild(subcategory)
 }
 
+/**
+ * Configure the global logger: sinks, loggers, and lowest level per category.
+ * @param config - Optional partial config (sinks, loggers). Merged with defaults.
+ */
 export function configureLogger<TSinkId extends string, TFilterId extends string>(
   config?: Partial<Config<TSinkId, TFilterId>>,
 ) {
   try {
-    const sinks = config?.sinks ?? {}
-    configureLogtape<any, any>({
+    const { sinks = {}, loggers: _loggers, ...restConfig } = config ?? {}
+    const sinksWithConsole: Record<TSinkId | 'console', Sink> = {
+      console: getConsoleSink(),
+      ...sinks,
+    } as Record<TSinkId | 'console', Sink>
+    configureLogtape<TSinkId | 'console', TFilterId>({
       reset: true,
-      ...config,
-      sinks: {
-        console: getConsoleSink(),
-        ...sinks,
-      },
+      ...restConfig,
+      sinks: sinksWithConsole,
       loggers: [
         { category: ['logtape', 'meta'], sinks: ['console'], lowestLevel: 'warning' },
         ...(config?.loggers ?? [

package/src/sink.ts

@@ -6,6 +6,11 @@ import {
 } from '@logtape/logtape'
 import { getConsoleFormatter } from './formatters'
 
+/**
+ * Create a sink that writes formatted log records to stdout (default formatter).
+ * @param options - Optional console sink options (e.g. custom formatter)
+ * @returns Sink that writes to stdout
+ */
 export function getConsoleSink(options?: ConsoleSinkOptions): Sink {
   return getLogtapeConsoleSink({
     formatter: getConsoleFormatter(),
@@ -16,6 +21,8 @@ export function getConsoleSink(options?: ConsoleSinkOptions): Sink {
 /**
  * Creates a console sink that writes to stderr.
  * (MCP protocol requires stderr to be used for logging)
+ * @param options - Optional console sink options (e.g. custom formatter)
+ * @returns Sink that writes to stderr
  */
 export function getConsoleStderrSink(options?: ConsoleSinkOptions): Sink {
   const formatter = options?.formatter ?? getConsoleFormatter()

package/src/utils.ts

@@ -2,6 +2,11 @@ import mergeErrorCause from 'merge-error-cause'
 import safeStringify from 'safe-stringify'
 import wrapErrorMessage from 'wrap-error-message'
 
+/**
+ * Split stack string into lines and normalize (e.g. strip file://).
+ * @param stack - Error stack string
+ * @returns Array of normalized lines
+ */
 export const parseStack = (stack: string): string[] => {
   const lines = stack
     .split('\n')
@@ -17,12 +22,23 @@ export const parseStack = (stack: string): string[] => {
   return lines
 }
 
+/**
+ * Indent each line of value by the given number of spaces.
+ * @param value - String or array of lines to indent
+ * @param indentation - Number of spaces (default 2)
+ * @returns Indented string
+ */
 export function indent(value: string | string[], indentation = 2): string {
   value = Array.isArray(value) ? value : value.split('\n')
   const prefix = ' '.repeat(indentation)
   return value.map((l) => `${prefix}${l}`).join('\n')
 }
 
+/**
+ * Serialize unknown to a string (Error → message + stack; else safe-stringify).
+ * @param error - Caught value (Error, string, or arbitrary object)
+ * @returns Human-readable string for logging
+ */
 export function loggable(error: unknown): string {
   if (typeof error === 'string') {
     return error