@logtape/adaptor-winston 1.0.0-dev.257

package/dist/mod.d.cts

@@ -0,0 +1,300 @@
+import { LogLevel, Sink } from "@logtape/logtape";
+import { LeveledLogMethod } from "winston";
+
+//#region mod.d.ts
+
+/**
+ * Logger interface for Winston-compatible loggers.
+ * @since 1.0.0
+ */
+interface Logger {
+  error: LeveledLogMethod;
+  warn: LeveledLogMethod;
+  info: LeveledLogMethod;
+  http: LeveledLogMethod;
+  verbose: LeveledLogMethod;
+  debug: LeveledLogMethod;
+  silly: LeveledLogMethod;
+}
+/**
+ * Configuration options for the winston sink.
+ *
+ * @example Basic usage with default options
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger);
+ * ```
+ *
+ * @example Custom level mapping
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   levelsMap: {
+ *     "trace": "debug",
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "error"
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom category formatting
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   category: {
+ *     separator: ".",
+ *     position: "start",
+ *     decorator: "[]"
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface WinstonSinkOptions {
+  /**
+   * Mapping between LogTape log levels and winston log levels.
+   *
+   * By default, LogTape levels are mapped as follows:
+   *
+   * - `trace` → `silly`
+   * - `debug` → `debug`
+   * - `info` → `info`
+   * - `warning` → `warn`
+   * - `error` → `error`
+   * - `fatal` → `error`
+   */
+  readonly levelsMap?: Readonly<Record<LogLevel, keyof Logger>>;
+  /**
+   * Configuration for how LogTape categories are handled in winston logs.
+   *
+   * - `false` or `undefined`: Categories are not included in the log message
+   * - `true`: Categories are included with default formatting (":" decorator at start)
+   * - `CategoryOptions`: Custom category formatting configuration
+   *
+   * @default undefined
+   */
+  readonly category?: boolean | CategoryOptions;
+  /**
+   * Custom formatter for interpolated values in log messages.
+   *
+   * This function is used to convert values that are interpolated into
+   * log messages (e.g., the `name` in
+   * `logger.info("Hello, {name}!", { name: "world" })`).
+   *
+   * @param value The value to format
+   * @returns A string representation of the value
+   * @default `inspect` (from `node:util` module)
+   */
+  readonly valueFormatter?: (value: unknown) => string;
+}
+/**
+ * Configuration options for formatting LogTape categories in winston log messages.
+ *
+ * Categories in LogTape represent a hierarchical namespace for loggers
+ * (e.g., ["myapp", "database", "connection"]). This interface controls
+ * how these categories are formatted when included in winston log messages.
+ *
+ * @example Default formatting
+ * ```typescript
+ * // With category ["myapp", "db"] and default options:
+ * // Output: "myapp·db: User logged in"
+ * const options: CategoryOptions = {};
+ * ```
+ *
+ * @example Custom separator and decorator
+ * ```typescript
+ * // With category ["myapp", "db"] and custom options:
+ * // Output: "[myapp.db] User logged in"
+ * const options: CategoryOptions = {
+ *   separator: ".",
+ *   decorator: "[]"
+ * };
+ * ```
+ *
+ * @example Category at end
+ * ```typescript
+ * // With category ["myapp", "db"] and position at end:
+ * // Output: "User logged in: myapp·db"
+ * const options: CategoryOptions = {
+ *   position: "end"
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface CategoryOptions {
+  /**
+   * The separator used to join category parts when multiple categories exist.
+   * @default "·"
+   */
+  readonly separator?: string;
+  /**
+   * Where to position the category in the log message.
+   * - `"start"`: Category appears at the beginning of the message
+   * - `"end"`: Category appears at the end of the message
+   * @default "start"
+   */
+  readonly position?: "start" | "end";
+  /**
+   * The decorator used to format the category in the log message.
+   * - `"[]"`: [category] format
+   * - `"()"`: (category) format
+   * - `"<>"`: <category> format
+   * - `"{}"`: {category} format
+   * - `":"`: category: format
+   * - `"-"`: category - format
+   * - `"|"`: category | format
+   * - `"/"`: category / format
+   * - `""`: category format (no decoration)
+   * @default ":"
+   */
+  readonly decorator?: "[]" | "()" | "<>" | "{}" | ":" | "-" | "|" | "/" | "";
+}
+/**
+ * Creates a LogTape sink that forwards log records to a winston logger.
+ *
+ * This function creates a sink function that can be used with LogTape's
+ * configuration system. The sink will format LogTape log records and
+ * forward them to the provided winston logger instance.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import winston from "winston";
+ * import { configure } from "@logtape/logtape";
+ * import { getWinstonSink } from "@logtape/adaptor-winston";
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: "info",
+ *   format: winston.format.combine(
+ *     winston.format.timestamp(),
+ *     winston.format.json()
+ *   ),
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * await configure({
+ *   sinks: {
+ *     winston: getWinstonSink(winstonLogger)
+ *   },
+ *   loggers: [
+ *     { category: ["myapp"], sinks: ["winston"] }
+ *   ]
+ * });
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   category: {
+ *     separator: ".",
+ *     position: "start",
+ *     decorator: "[]"
+ *   },
+ *   levelsMap: {
+ *     "trace": "debug",  // Map trace to debug instead of silly
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "error"
+ *   }
+ * });
+ * ```
+ *
+ * @param logger The winston logger instance to forward logs to. Must implement
+ *               the Logger interface with error, warn, info, http, verbose,
+ *               debug, and silly methods.
+ * @param options Configuration options for the sink behavior.
+ * @returns A sink function that can be used with LogTape's configure() function.
+ * @since 1.0.0
+ */
+declare function getWinstonSink(logger: Logger, options?: WinstonSinkOptions): Sink;
+/**
+ * Automatically configures LogTape to route all logs to a winston logger.
+ *
+ * This is a convenience function that automatically sets up LogTape to forward
+ * all log records to a winston logger instance. By default, it uses winston's
+ * default logger, but you can provide a custom logger as the first parameter.
+ *
+ * @param logger The winston logger instance to use.
+ * @param options Configuration options for the winston sink behavior.
+ *
+ * @example Basic auto-configuration with default logger
+ * ```typescript
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * // Automatically route all LogTape logs to winston's default logger
+ * install();
+ *
+ * // Now any LogTape-enabled library will log through winston
+ * import { getLogger } from "@logtape/logtape";
+ * const logger = getLogger("my-app");
+ * logger.info("This will be logged through winston");
+ * ```
+ *
+ * @example Auto-configuration with custom winston logger
+ * ```typescript
+ * import winston from "winston";
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * const customLogger = winston.createLogger({
+ *   level: "info",
+ *   format: winston.format.combine(
+ *     winston.format.timestamp(),
+ *     winston.format.json()
+ *   ),
+ *   transports: [
+ *     new winston.transports.Console(),
+ *     new winston.transports.File({ filename: "app.log" })
+ *   ]
+ * });
+ *
+ * // Install with custom logger
+ * install(customLogger);
+ * ```
+ *
+ * @example Auto-configuration with custom options
+ * ```typescript
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * install(undefined, {
+ *   category: {
+ *     position: "start",
+ *     decorator: "[]",
+ *     separator: "."
+ *   },
+ *   levelsMap: {
+ *     "trace": "debug"  // Map LogTape trace to winston debug
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom logger with custom options
+ * ```typescript
+ * import winston from "winston";
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * const customLogger = winston.createLogger({
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * install(customLogger, {
+ *   category: { position: "start", decorator: "[]" }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function install(logger: Logger, options?: WinstonSinkOptions): void;
+/**
+ * Configures LogTape to route all logs to winston's default logger.
+ *
+ * @param options Optional configuration for the winston sink behavior.
+ * @since 1.0.0
+ */
+declare function install(options?: WinstonSinkOptions): void;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { CategoryOptions, Logger, WinstonSinkOptions, getWinstonSink, install };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../mod.ts"],"sourcesContent":[],"mappings":";;;;;AAoaA;;;;UAvXiB,MAAA;SACR;QACD;QACA;QACA;WACG;SACF;SACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAsCQ,kBAAA;;;;;;;;;;;;;uBAaM,SAAS,OAAO,gBAAgB;;;;;;;;;;gCAWvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAmDf,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkGD,cAAA,SACN,kBACC,qBACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ia,OAAA,SACN,kBACE;;;;;;;iBASI,OAAA,WACJ"}

package/dist/mod.d.ts

@@ -0,0 +1,300 @@
+import { LogLevel, Sink } from "@logtape/logtape";
+import { LeveledLogMethod } from "winston";
+
+//#region mod.d.ts
+
+/**
+ * Logger interface for Winston-compatible loggers.
+ * @since 1.0.0
+ */
+interface Logger {
+  error: LeveledLogMethod;
+  warn: LeveledLogMethod;
+  info: LeveledLogMethod;
+  http: LeveledLogMethod;
+  verbose: LeveledLogMethod;
+  debug: LeveledLogMethod;
+  silly: LeveledLogMethod;
+}
+/**
+ * Configuration options for the winston sink.
+ *
+ * @example Basic usage with default options
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger);
+ * ```
+ *
+ * @example Custom level mapping
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   levelsMap: {
+ *     "trace": "debug",
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "error"
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom category formatting
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   category: {
+ *     separator: ".",
+ *     position: "start",
+ *     decorator: "[]"
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface WinstonSinkOptions {
+  /**
+   * Mapping between LogTape log levels and winston log levels.
+   *
+   * By default, LogTape levels are mapped as follows:
+   *
+   * - `trace` → `silly`
+   * - `debug` → `debug`
+   * - `info` → `info`
+   * - `warning` → `warn`
+   * - `error` → `error`
+   * - `fatal` → `error`
+   */
+  readonly levelsMap?: Readonly<Record<LogLevel, keyof Logger>>;
+  /**
+   * Configuration for how LogTape categories are handled in winston logs.
+   *
+   * - `false` or `undefined`: Categories are not included in the log message
+   * - `true`: Categories are included with default formatting (":" decorator at start)
+   * - `CategoryOptions`: Custom category formatting configuration
+   *
+   * @default undefined
+   */
+  readonly category?: boolean | CategoryOptions;
+  /**
+   * Custom formatter for interpolated values in log messages.
+   *
+   * This function is used to convert values that are interpolated into
+   * log messages (e.g., the `name` in
+   * `logger.info("Hello, {name}!", { name: "world" })`).
+   *
+   * @param value The value to format
+   * @returns A string representation of the value
+   * @default `inspect` (from `node:util` module)
+   */
+  readonly valueFormatter?: (value: unknown) => string;
+}
+/**
+ * Configuration options for formatting LogTape categories in winston log messages.
+ *
+ * Categories in LogTape represent a hierarchical namespace for loggers
+ * (e.g., ["myapp", "database", "connection"]). This interface controls
+ * how these categories are formatted when included in winston log messages.
+ *
+ * @example Default formatting
+ * ```typescript
+ * // With category ["myapp", "db"] and default options:
+ * // Output: "myapp·db: User logged in"
+ * const options: CategoryOptions = {};
+ * ```
+ *
+ * @example Custom separator and decorator
+ * ```typescript
+ * // With category ["myapp", "db"] and custom options:
+ * // Output: "[myapp.db] User logged in"
+ * const options: CategoryOptions = {
+ *   separator: ".",
+ *   decorator: "[]"
+ * };
+ * ```
+ *
+ * @example Category at end
+ * ```typescript
+ * // With category ["myapp", "db"] and position at end:
+ * // Output: "User logged in: myapp·db"
+ * const options: CategoryOptions = {
+ *   position: "end"
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface CategoryOptions {
+  /**
+   * The separator used to join category parts when multiple categories exist.
+   * @default "·"
+   */
+  readonly separator?: string;
+  /**
+   * Where to position the category in the log message.
+   * - `"start"`: Category appears at the beginning of the message
+   * - `"end"`: Category appears at the end of the message
+   * @default "start"
+   */
+  readonly position?: "start" | "end";
+  /**
+   * The decorator used to format the category in the log message.
+   * - `"[]"`: [category] format
+   * - `"()"`: (category) format
+   * - `"<>"`: <category> format
+   * - `"{}"`: {category} format
+   * - `":"`: category: format
+   * - `"-"`: category - format
+   * - `"|"`: category | format
+   * - `"/"`: category / format
+   * - `""`: category format (no decoration)
+   * @default ":"
+   */
+  readonly decorator?: "[]" | "()" | "<>" | "{}" | ":" | "-" | "|" | "/" | "";
+}
+/**
+ * Creates a LogTape sink that forwards log records to a winston logger.
+ *
+ * This function creates a sink function that can be used with LogTape's
+ * configuration system. The sink will format LogTape log records and
+ * forward them to the provided winston logger instance.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import winston from "winston";
+ * import { configure } from "@logtape/logtape";
+ * import { getWinstonSink } from "@logtape/adaptor-winston";
+ *
+ * const winstonLogger = winston.createLogger({
+ *   level: "info",
+ *   format: winston.format.combine(
+ *     winston.format.timestamp(),
+ *     winston.format.json()
+ *   ),
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * await configure({
+ *   sinks: {
+ *     winston: getWinstonSink(winstonLogger)
+ *   },
+ *   loggers: [
+ *     { category: ["myapp"], sinks: ["winston"] }
+ *   ]
+ * });
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * const sink = getWinstonSink(winstonLogger, {
+ *   category: {
+ *     separator: ".",
+ *     position: "start",
+ *     decorator: "[]"
+ *   },
+ *   levelsMap: {
+ *     "trace": "debug",  // Map trace to debug instead of silly
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "error"
+ *   }
+ * });
+ * ```
+ *
+ * @param logger The winston logger instance to forward logs to. Must implement
+ *               the Logger interface with error, warn, info, http, verbose,
+ *               debug, and silly methods.
+ * @param options Configuration options for the sink behavior.
+ * @returns A sink function that can be used with LogTape's configure() function.
+ * @since 1.0.0
+ */
+declare function getWinstonSink(logger: Logger, options?: WinstonSinkOptions): Sink;
+/**
+ * Automatically configures LogTape to route all logs to a winston logger.
+ *
+ * This is a convenience function that automatically sets up LogTape to forward
+ * all log records to a winston logger instance. By default, it uses winston's
+ * default logger, but you can provide a custom logger as the first parameter.
+ *
+ * @param logger The winston logger instance to use.
+ * @param options Configuration options for the winston sink behavior.
+ *
+ * @example Basic auto-configuration with default logger
+ * ```typescript
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * // Automatically route all LogTape logs to winston's default logger
+ * install();
+ *
+ * // Now any LogTape-enabled library will log through winston
+ * import { getLogger } from "@logtape/logtape";
+ * const logger = getLogger("my-app");
+ * logger.info("This will be logged through winston");
+ * ```
+ *
+ * @example Auto-configuration with custom winston logger
+ * ```typescript
+ * import winston from "winston";
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * const customLogger = winston.createLogger({
+ *   level: "info",
+ *   format: winston.format.combine(
+ *     winston.format.timestamp(),
+ *     winston.format.json()
+ *   ),
+ *   transports: [
+ *     new winston.transports.Console(),
+ *     new winston.transports.File({ filename: "app.log" })
+ *   ]
+ * });
+ *
+ * // Install with custom logger
+ * install(customLogger);
+ * ```
+ *
+ * @example Auto-configuration with custom options
+ * ```typescript
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * install(undefined, {
+ *   category: {
+ *     position: "start",
+ *     decorator: "[]",
+ *     separator: "."
+ *   },
+ *   levelsMap: {
+ *     "trace": "debug"  // Map LogTape trace to winston debug
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom logger with custom options
+ * ```typescript
+ * import winston from "winston";
+ * import { install } from "@logtape/adaptor-winston";
+ *
+ * const customLogger = winston.createLogger({
+ *   transports: [new winston.transports.Console()]
+ * });
+ *
+ * install(customLogger, {
+ *   category: { position: "start", decorator: "[]" }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function install(logger: Logger, options?: WinstonSinkOptions): void;
+/**
+ * Configures LogTape to route all logs to winston's default logger.
+ *
+ * @param options Optional configuration for the winston sink behavior.
+ * @since 1.0.0
+ */
+declare function install(options?: WinstonSinkOptions): void;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { CategoryOptions, Logger, WinstonSinkOptions, getWinstonSink, install };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../mod.ts"],"sourcesContent":[],"mappings":";;;;;AAoaA;;;;UAvXiB,MAAA;SACR;QACD;QACA;QACA;WACG;SACF;SACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAsCQ,kBAAA;;;;;;;;;;;;;uBAaM,SAAS,OAAO,gBAAgB;;;;;;;;;;gCAWvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAmDf,eAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkGD,cAAA,SACN,kBACC,qBACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+Ia,OAAA,SACN,kBACE;;;;;;;iBASI,OAAA,WACJ"}