@logtape/adaptor-log4js 2.0.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024–2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+<!-- deno-fmt-ignore-file -->
+
+@logtape/adaptor-log4js
+=======================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+*@logtape/adaptor-log4js* is a [LogTape] adapter that forwards log records to
+[log4js] loggers, enabling seamless integration between LogTape-enabled
+libraries and applications using log4js for logging infrastructure.
+
+[JSR badge]: https://jsr.io/badges/@logtape/adaptor-log4js
+[JSR]: https://jsr.io/@logtape/adaptor-log4js
+[npm badge]: https://img.shields.io/npm/v/@logtape/adaptor-log4js?logo=npm
+[npm]: https://www.npmjs.com/package/@logtape/adaptor-log4js
+[LogTape]: https://logtape.org/
+[log4js]: https://log4js-node.github.io/log4js-node/
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@logtape/adaptor-log4js  # for Deno
+npm  add     @logtape/adaptor-log4js  # for npm
+pnpm add     @logtape/adaptor-log4js  # for pnpm
+yarn add     @logtape/adaptor-log4js  # for Yarn
+bun  add     @logtape/adaptor-log4js  # for Bun
+~~~~
+
+
+Usage
+-----
+
+### Quick setup
+
+The simplest way to integrate LogTape with log4js is using the auto-installer:
+
+~~~~ typescript
+import log4js from "log4js";
+
+// Configure log4js first
+log4js.configure({
+  appenders: { out: { type: "stdout" } },
+  categories: { default: { appenders: ["out"], level: "info" } }
+});
+
+// Simply import to automatically set up the adapter
+import "@logtape/adaptor-log4js/install";
+
+// Now all LogTape logs will be routed to log4js
+import { getLogger } from "@logtape/logtape";
+const logger = getLogger("my-app");
+logger.info("This will be logged through log4js");
+~~~~
+
+### Using the `install()` function
+
+For more control, use the `install()` function:
+
+~~~~ typescript
+import log4js from "log4js";
+import { install } from "@logtape/adaptor-log4js";
+
+log4js.configure({
+  appenders: { out: { type: "stdout" } },
+  categories: { default: { appenders: ["out"], level: "info" } }
+});
+
+// With default options (category-based loggers)
+install(log4js);
+
+// Or with a custom logger
+const customLogger = log4js.getLogger("myapp");
+install(log4js, customLogger);
+
+// Or with custom options
+install(log4js, undefined, {
+  categoryMapper: (cat) => cat.join("::"),
+  contextStrategy: "args"
+});
+~~~~
+
+### Manual configuration
+
+For full control over the log4js integration, configure LogTape manually:
+
+~~~~ typescript
+import { configure } from "@logtape/logtape";
+import { getLog4jsSink } from "@logtape/adaptor-log4js";
+import log4js from "log4js";
+
+log4js.configure({
+  appenders: { out: { type: "stdout" } },
+  categories: { default: { appenders: ["out"], level: "info" } }
+});
+
+await configure({
+  sinks: {
+    log4js: getLog4jsSink(log4js, undefined, {
+      categoryMapper: (cat) => cat.join("."),
+      contextStrategy: "mdc",
+      contextPreservation: "preserve"
+    })
+  },
+  loggers: [
+    { category: "my-library", sinks: ["log4js"] }
+  ]
+});
+~~~~
+
+
+Category mapping
+----------------
+
+By default, LogTape categories are mapped to log4js categories using dot
+notation. For example, LogTape category `["app", "database", "query"]` becomes
+log4js category `"app.database.query"`.
+
+You can customize this behavior using the `categoryMapper` option:
+
+~~~~ typescript
+import { getLog4jsSink } from "@logtape/adaptor-log4js";
+
+// Use :: as separator
+const sink = getLog4jsSink(log4js, undefined, {
+  categoryMapper: (cat) => cat.join("::")
+});
+
+// Custom logic
+const sink2 = getLog4jsSink(log4js, undefined, {
+  categoryMapper: (cat) => {
+    if (cat.length === 0) return "default";
+    return cat.slice(0, 2).join("."); // Only use first two parts
+  }
+});
+~~~~
+
+
+Context handling
+----------------
+
+The adapter supports two strategies for handling LogTape properties.
+The type system ensures that `contextPreservation` can only be used with
+the MDC strategy:
+
+### MDC (Mapped Diagnostic Context) strategy (default)
+
+Uses log4js's built-in context feature to add LogTape properties:
+
+~~~~ typescript
+const sink = getLog4jsSink(log4js, undefined, {
+  contextStrategy: "mdc"
+});
+~~~~
+
+When using MDC strategy, you can control how existing context is handled:
+
+~~~~ typescript
+// Preserve existing context (default)
+// LogTape properties are added during logging, then removed
+const sink1 = getLog4jsSink(log4js, undefined, {
+  contextStrategy: "mdc",
+  contextPreservation: "preserve"
+});
+
+// Merge with existing context
+// LogTape properties are added and left in context
+const sink2 = getLog4jsSink(log4js, undefined, {
+  contextStrategy: "mdc",
+  contextPreservation: "merge"
+});
+
+// Replace existing context
+// Existing context is cleared before adding LogTape properties
+const sink3 = getLog4jsSink(log4js, undefined, {
+  contextStrategy: "mdc",
+  contextPreservation: "replace"
+});
+~~~~
+
+### Args strategy
+
+Passes LogTape properties as additional arguments to log methods.
+Note that `contextPreservation` is not available with this strategy:
+
+~~~~ typescript
+const sink = getLog4jsSink(log4js, undefined, {
+  contextStrategy: "args"
+  // contextPreservation is not allowed here - TypeScript will error
+});
+~~~~
+
+
+Docs
+----
+
+See the [API reference] on JSR for further details.
+
+[API reference]: https://jsr.io/@logtape/adaptor-log4js/doc

package/dist/install.cjs

@@ -0,0 +1,7 @@
+const require_src = require('./src-tAG616xa.cjs');
+const log4js = require_src.__toESM(require("log4js"));
+
+//#region src/install.ts
+require_src.install(log4js.default);
+
+//#endregion

package/dist/install.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/install.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/install.js

@@ -0,0 +1,7 @@
+import { install } from "./src-Cb2nEPMQ.js";
+import log4js from "log4js";
+
+//#region src/install.ts
+install(log4js);
+
+//#endregion

package/dist/mod.cjs

@@ -0,0 +1,4 @@
+const require_src = require('./src-tAG616xa.cjs');
+
+exports.getLog4jsSink = require_src.getLog4jsSink;
+exports.install = require_src.install;

package/dist/mod.d.cts

@@ -0,0 +1,325 @@
+import { LogLevel, Sink } from "@logtape/logtape";
+import log4js from "log4js";
+
+//#region src/mod.d.ts
+
+/**
+ * Logger interface for log4js-compatible loggers.
+ * @since 2.0.0
+ */
+interface Logger {
+  trace: LogMethod;
+  debug: LogMethod;
+  info: LogMethod;
+  warn: LogMethod;
+  error: LogMethod;
+  fatal: LogMethod;
+  addContext: (key: string, value: unknown) => void;
+  removeContext: (key: string) => void;
+  clearContext: () => void;
+}
+/**
+ * Log method signature for log4js.
+ * @since 2.0.0
+ */
+interface LogMethod {
+  (message: string, ...args: unknown[]): void;
+}
+/**
+ * log4js log level type.
+ * @since 2.0.0
+ */
+type Log4jsLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/**
+ * Strategy for handling LogTape properties in log4js.
+ * @since 2.0.0
+ */
+type ContextStrategy = "mdc" | "args";
+/**
+ * Strategy for handling existing log4js context.
+ * @since 2.0.0
+ */
+type ContextPreservation = "preserve" | "merge" | "replace";
+/**
+ * Base configuration options shared by all context strategies.
+ * @since 2.0.0
+ */
+interface Log4jsSinkOptionsBase {
+  /**
+   * Mapping between LogTape log levels and log4js log levels.
+   *
+   * By default, LogTape levels are mapped as follows:
+   *
+   * - `trace` → `trace`
+   * - `debug` → `debug`
+   * - `info` → `info`
+   * - `warning` → `warn`
+   * - `error` → `error`
+   * - `fatal` → `fatal`
+   */
+  readonly levelsMap?: Readonly<Record<LogLevel, Log4jsLevel>>;
+  /**
+   * Custom mapper function to convert LogTape categories to log4js category strings.
+   *
+   * By default, LogTape categories are joined with dots (e.g., `["app", "db"]` becomes `"app.db"`).
+   *
+   * @param category The LogTape category array
+   * @returns The log4js category string
+   * @default (category) => category.join(".")
+   *
+   * @example
+   * ```typescript
+   * // Use :: as separator
+   * categoryMapper: (cat) => cat.join("::")
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Custom logic for category mapping
+   * categoryMapper: (cat) => {
+   *   if (cat.length === 0) return "default";
+   *   return cat.join(".");
+   * }
+   * ```
+   */
+  readonly categoryMapper?: (category: readonly string[]) => string;
+  /**
+   * 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 log4js sink with MDC (Mapped Diagnostic Context) strategy.
+ * @since 2.0.0
+ */
+interface Log4jsSinkOptionsMdc extends Log4jsSinkOptionsBase {
+  /**
+   * Strategy for handling LogTape properties.
+   *
+   * Use `"mdc"` to leverage log4js's built-in MDC (Mapped Diagnostic Context) feature.
+   *
+   * @default "mdc"
+   */
+  readonly contextStrategy?: "mdc";
+  /**
+   * Strategy for handling existing log4js context when using MDC strategy.
+   *
+   * - `"preserve"` (default): Preserve existing context by saving and restoring it
+   * - `"merge"`: Merge LogTape properties with existing context (existing values take precedence)
+   * - `"replace"`: Replace existing context with LogTape properties
+   *
+   * @default "preserve"
+   *
+   * @example
+   * ```typescript
+   * // Preserve existing context (default)
+   * const sink = getLog4jsSink(undefined, undefined, {
+   *   contextStrategy: "mdc",
+   *   contextPreservation: "preserve"
+   * });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Merge with existing context
+   * const sink = getLog4jsSink(undefined, undefined, {
+   *   contextStrategy: "mdc",
+   *   contextPreservation: "merge"
+   * });
+   * ```
+   */
+  readonly contextPreservation?: ContextPreservation;
+}
+/**
+ * Configuration options for log4js sink with args strategy.
+ * @since 2.0.0
+ */
+interface Log4jsSinkOptionsArgs extends Log4jsSinkOptionsBase {
+  /**
+   * Strategy for handling LogTape properties.
+   *
+   * Use `"args"` to pass properties as additional arguments to log methods.
+   */
+  readonly contextStrategy: "args";
+}
+/**
+ * Configuration options for the log4js sink.
+ *
+ * This is a discriminated union type based on the `contextStrategy` option.
+ * When `contextStrategy` is `"mdc"` (or omitted), the `contextPreservation` option
+ * is available. When `contextStrategy` is `"args"`, the `contextPreservation` option
+ * is not allowed.
+ *
+ * @example Basic usage with default options (MDC strategy)
+ * ```typescript
+ * const sink = getLog4jsSink();
+ * ```
+ *
+ * @example Custom level mapping
+ * ```typescript
+ * const sink = getLog4jsSink(undefined, undefined, {
+ *   levelsMap: {
+ *     "trace": "debug",
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "fatal"
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom category mapping
+ * ```typescript
+ * const sink = getLog4jsSink(undefined, undefined, {
+ *   categoryMapper: (category) => category.join("::")
+ * });
+ * ```
+ *
+ * @example Using MDC strategy with preserve (default)
+ * ```typescript
+ * const sink = getLog4jsSink(undefined, undefined, {
+ *   contextStrategy: "mdc",
+ *   contextPreservation: "preserve"
+ * });
+ * ```
+ *
+ * @example Using args strategy
+ * ```typescript
+ * const sink = getLog4jsSink(undefined, undefined, {
+ *   contextStrategy: "args"
+ *   // contextPreservation is not allowed here
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+type Log4jsSinkOptions = Log4jsSinkOptionsMdc | Log4jsSinkOptionsArgs;
+/**
+ * Creates a LogTape sink that forwards log records to a log4js 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 log4js logger instance or create one
+ * based on the LogTape category.
+ *
+ * @example Basic usage with default log4js logger
+ * ```typescript
+ * import log4js from "log4js";
+ * import { configure } from "@logtape/logtape";
+ * import { getLog4jsSink } from "@logtape/adaptor-log4js";
+ *
+ * log4js.configure({
+ *   appenders: { out: { type: "stdout" } },
+ *   categories: { default: { appenders: ["out"], level: "info" } }
+ * });
+ *
+ * await configure({
+ *   sinks: {
+ *     log4js: getLog4jsSink()
+ *   },
+ *   loggers: [
+ *     { category: ["myapp"], sinks: ["log4js"] }
+ *   ]
+ * });
+ * ```
+ *
+ * @example With custom log4js logger
+ * ```typescript
+ * import log4js from "log4js";
+ * import { getLog4jsSink } from "@logtape/adaptor-log4js";
+ *
+ * const logger = log4js.getLogger("custom");
+ * const sink = getLog4jsSink(logger);
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * const sink = getLog4jsSink(undefined, {
+ *   categoryMapper: (cat) => cat.join("::"),
+ *   contextStrategy: "args",
+ *   levelsMap: {
+ *     "trace": "debug",
+ *     "debug": "debug",
+ *     "info": "info",
+ *     "warning": "warn",
+ *     "error": "error",
+ *     "fatal": "fatal"
+ *   }
+ * });
+ * ```
+ *
+ * @param log4jsModule The log4js module instance. If not provided, log4js will be imported dynamically.
+ * @param logger The log4js logger instance to forward logs to. If not provided,
+ *               a logger will be created for each LogTape category using log4js.getLogger().
+ * @param options Configuration options for the sink behavior.
+ * @returns A sink function that can be used with LogTape's configure() function.
+ * @since 2.0.0
+ */
+declare function getLog4jsSink(log4jsModule?: typeof log4js, logger?: Logger, options?: Log4jsSinkOptions): Sink;
+/**
+ * Automatically configures LogTape to route all logs to log4js.
+ *
+ * This is a convenience function that automatically sets up LogTape to forward
+ * all log records to log4js. By default, it creates loggers based on LogTape
+ * categories using log4js.getLogger(), but you can provide a custom logger
+ * as the second parameter.
+ *
+ * @param log4jsModule The log4js module instance. If not provided, log4js will be imported dynamically.
+ * @param logger Optional log4js logger instance to use for all logs.
+ * @param options Configuration options for the log4js sink behavior.
+ *
+ * @example Basic auto-configuration
+ * ```typescript
+ * import log4js from "log4js";
+ * import { install } from "@logtape/adaptor-log4js";
+ *
+ * log4js.configure({
+ *   appenders: { out: { type: "stdout" } },
+ *   categories: { default: { appenders: ["out"], level: "info" } }
+ * });
+ *
+ * // Automatically route all LogTape logs to log4js
+ * install(log4js);
+ *
+ * // Now any LogTape-enabled library will log through log4js
+ * import { getLogger } from "@logtape/logtape";
+ * const logger = getLogger("my-app");
+ * logger.info("This will be logged through log4js");
+ * ```
+ *
+ * @example Auto-configuration with custom logger
+ * ```typescript
+ * import log4js from "log4js";
+ * import { install } from "@logtape/adaptor-log4js";
+ *
+ * const customLogger = log4js.getLogger("myapp");
+ *
+ * // Install with custom logger
+ * install(log4js, customLogger);
+ * ```
+ *
+ * @example Auto-configuration with custom options
+ * ```typescript
+ * import log4js from "log4js";
+ * import { install } from "@logtape/adaptor-log4js";
+ *
+ * install(log4js, undefined, {
+ *   categoryMapper: (cat) => cat.join("::"),
+ *   contextStrategy: "args"
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+declare function install(log4jsModule: typeof log4js, logger?: Logger, options?: Log4jsSinkOptions): void;
+//#endregion
+export { ContextPreservation, ContextStrategy, Log4jsLevel, Log4jsSinkOptions, Log4jsSinkOptionsArgs, Log4jsSinkOptionsBase, Log4jsSinkOptionsMdc, LogMethod, Logger, getLog4jsSink, install };