@vercube/logger 1.2.1 → 1.3.0

package/dist/Otlp.d.mts

@@ -0,0 +1,2 @@
+export * from "evlog/otlp";
+export * from "evlog/pipeline";

package/dist/Otlp.mjs

@@ -0,0 +1,3 @@
+export * from "evlog/otlp";
+export * from "evlog/pipeline";
+export {};

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { DrainContext, DrainFn, EnvironmentContext, ErrorOptions, EvlogError, Log, LogLevel, LogLevel as LogLevel$1, LoggerConfig, LoggerConfig as LoggerConfig$1, RedactConfig, RequestLogger, RequestLoggerOptions, SamplingConfig, WideEvent, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, initLogger, log, parseError } from "evlog";
+import { DrainContext, DrainFn, EnrichContext, EnvironmentContext, ErrorOptions, EvlogError, EvlogPlugin, EvlogPlugin as EvlogPlugin$1, Log, LogLevel, LogLevel as LogLevel$1, LoggerConfig, LoggerConfig as LoggerConfig$1, RedactConfig, RequestLogger, RequestLoggerOptions, SamplingConfig, WideEvent, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, definePlugin, drainPlugin, enricherPlugin, initLogger, log, parseError } from "evlog";
 //#region src/Types/LoggerTypes.d.ts
 /**
  * Types for the evlog-backed Vercube logger.
  *
  * @see https://evlog.dev
  */
-declare namespace LoggerTypes {
+export declare namespace LoggerTypes {
   /**
    * Supported severity levels, aligned with evlog.
    * Order: debug < info < warn < error.
@@ -19,6 +19,15 @@ declare namespace LoggerTypes {
    * Structured context merged into emitted (wide) events.
    */
   type Context = Record<string, unknown>;
+  /**
+   * Supplies context computed at emit time.
+   *
+   * Unlike {@link Logger.set}, which stores a fixed object, a provider is
+   * called for every event. That is what lets ambient state - the active trace
+   * and span, for instance - reach log lines without every call site passing it
+   * along. Returning `undefined` contributes nothing.
+   */
+  type ContextProvider = () => Context | undefined;
   /**
    * Logger configuration.
    *
@@ -42,7 +51,7 @@ declare namespace LoggerTypes {
  * default implementation ({@link BaseLogger}) is backed by evlog
  * (https://evlog.dev) and forwards calls to evlog's logging API.
  */
-declare abstract class Logger {
+export declare abstract class Logger {
   /**
    * Configures the underlying logger.
    * Maps to evlog's `initLogger` under the hood.
@@ -50,6 +59,43 @@ declare abstract class Logger {
    * @param options - Configuration options for the logger
    */
   abstract configure(options: LoggerTypes.Options): void;
+  /**
+   * Registers an evlog plugin without discarding the current configuration.
+   *
+   * evlog only accepts plugins through `initLogger`, and calling that a second
+   * time would replace whatever the application configured for itself. This
+   * re-applies the stored configuration with the plugin appended, so framework
+   * packages - telemetry, devtools - can attach themselves to the log pipeline
+   * instead of wrapping the logger instance.
+   *
+   * @param plugin - The evlog plugin to register
+   */
+  abstract addPlugin(plugin: EvlogPlugin$1): void;
+  /**
+   * Registers a drain: a callback receiving every emitted event.
+   *
+   * @param name - Stable plugin name, used for de-duplication
+   * @param drain - The drain callback
+   */
+  abstract addDrain(name: string, drain: NonNullable<EvlogPlugin$1['drain']>): void;
+  /**
+   * Registers an enricher: a callback that may mutate an event before it drains.
+   *
+   * @param name - Stable plugin name, used for de-duplication
+   * @param enrich - The enricher callback
+   */
+  abstract addEnricher(name: string, enrich: NonNullable<EvlogPlugin$1['enrich']>): void;
+  /**
+   * Registers a provider consulted for every event this logger emits.
+   *
+   * evlog's `enrich` hook only runs for request wide events, so it cannot
+   * decorate a plain `logger.info()`. A context provider covers that path.
+   *
+   * @param provider - Called per event; its fields are merged in first, so
+   *   anything the call site passes wins
+   * @returns A function that unregisters the provider
+   */
+  abstract addContextProvider(provider: LoggerTypes.ContextProvider): () => void;
   /**
    * Logs a debug message.
    * @param args - Values to log (strings, objects, errors)
@@ -108,16 +154,74 @@ declare abstract class Logger {
  * lifecycle. For request-scoped wide events use the evlog toolkit
  * (`@vercube/logger/toolkit`) together with the framework's request middleware.
  */
-declare class BaseLogger extends Logger {
+export declare class BaseLogger extends Logger {
   /**
    * Accumulated structured context merged into every emitted event.
    */
   private fContext;
+  /**
+   * The last configuration applied, replayed whenever a plugin is added.
+   */
+  private fOptions;
+  /**
+   * Plugins registered through {@link BaseLogger.addPlugin}, kept apart from
+   * the ones the application passed to {@link BaseLogger.configure} so that
+   * reconfiguring never drops them.
+   */
+  private readonly fPlugins;
+  /**
+   * Providers consulted for every emitted event. Shared by reference with
+   * child loggers, so registering one after `child()` still reaches them.
+   */
+  private fContextProviders;
   /**
    * Configures the underlying evlog logger.
    * @param options - Configuration options
    */
   configure(options: LoggerTypes.Options): void;
+  /**
+   * Registers an evlog plugin, keeping the current configuration intact.
+   *
+   * Registering the same name twice replaces the previous registration, which
+   * makes attaching a plugin idempotent across hot reloads.
+   *
+   * @param plugin - The evlog plugin to register
+   */
+  addPlugin(plugin: EvlogPlugin$1): void;
+  /**
+   * Registers a drain: a callback receiving every emitted event.
+   *
+   * @param name - Stable plugin name
+   * @param drain - The drain callback
+   */
+  addDrain(name: string, drain: NonNullable<EvlogPlugin$1['drain']>): void;
+  /**
+   * Registers an enricher: a callback that may mutate an event before it drains.
+   *
+   * @param name - Stable plugin name
+   * @param enrich - The enricher callback
+   */
+  addEnricher(name: string, enrich: NonNullable<EvlogPlugin$1['enrich']>): void;
+  /**
+   * Registers a provider consulted for every event this logger emits.
+   *
+   * @param provider - Called per event
+   * @returns A function that unregisters the provider
+   */
+  addContextProvider(provider: LoggerTypes.ContextProvider): () => void;
+  /**
+   * Collects the fields every registered provider contributes.
+   *
+   * @returns The merged provided context, or null when nothing was contributed
+   * @private
+   */
+  private providedContext;
+  /**
+   * Pushes the stored configuration and every registered plugin into evlog.
+   *
+   * @private
+   */
+  private apply;
   /**
    * Logs a debug message.
    * @param args - Values to log
@@ -173,4 +277,4 @@ declare class BaseLogger extends Logger {
   private dispatch;
 }
 //#endregion
-export { BaseLogger, type DrainContext, type DrainFn, type EnvironmentContext, type ErrorOptions, EvlogError, type Log, type LogLevel, Logger, type LoggerConfig, LoggerTypes, type RedactConfig, type RequestLogger, type RequestLoggerOptions, type SamplingConfig, type WideEvent, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, initLogger, log, parseError };
+export { type DrainContext, type DrainFn, type EnrichContext, type EnvironmentContext, type ErrorOptions, EvlogError, type EvlogPlugin, type Log, type LogLevel, type LoggerConfig, type RedactConfig, type RequestLogger, type RequestLoggerOptions, type SamplingConfig, type WideEvent, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, definePlugin, drainPlugin, enricherPlugin, initLogger, log, parseError };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { EvlogError, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, initLogger, initLogger as initLogger$1, log, log as log$1, parseError } from "evlog";
+import { EvlogError, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, definePlugin, drainPlugin, drainPlugin as drainPlugin$1, enricherPlugin, enricherPlugin as enricherPlugin$1, initLogger, initLogger as initLogger$1, log, log as log$1, parseError } from "evlog";
 //#region src/Common/Logger.ts
 /**
 * Abstract base class for the Vercube logger.
@@ -26,14 +26,99 @@ var BaseLogger = class BaseLogger extends Logger {
 	*/
 	fContext = {};
 	/**
+	* The last configuration applied, replayed whenever a plugin is added.
+	*/
+	fOptions = {};
+	/**
+	* Plugins registered through {@link BaseLogger.addPlugin}, kept apart from
+	* the ones the application passed to {@link BaseLogger.configure} so that
+	* reconfiguring never drops them.
+	*/
+	fPlugins = [];
+	/**
+	* Providers consulted for every emitted event. Shared by reference with
+	* child loggers, so registering one after `child()` still reaches them.
+	*/
+	fContextProviders = [];
+	/**
 	* Configures the underlying evlog logger.
 	* @param options - Configuration options
 	*/
 	configure(options) {
-		const { logLevel, ...config } = options ?? {};
+		this.fOptions = options ?? {};
+		this.apply();
+	}
+	/**
+	* Registers an evlog plugin, keeping the current configuration intact.
+	*
+	* Registering the same name twice replaces the previous registration, which
+	* makes attaching a plugin idempotent across hot reloads.
+	*
+	* @param plugin - The evlog plugin to register
+	*/
+	addPlugin(plugin) {
+		const existing = this.fPlugins.findIndex((registered) => registered.name === plugin.name);
+		if (existing === -1) this.fPlugins.push(plugin);
+		else this.fPlugins[existing] = plugin;
+		this.apply();
+	}
+	/**
+	* Registers a drain: a callback receiving every emitted event.
+	*
+	* @param name - Stable plugin name
+	* @param drain - The drain callback
+	*/
+	addDrain(name, drain) {
+		this.addPlugin(drainPlugin$1(name, drain));
+	}
+	/**
+	* Registers an enricher: a callback that may mutate an event before it drains.
+	*
+	* @param name - Stable plugin name
+	* @param enrich - The enricher callback
+	*/
+	addEnricher(name, enrich) {
+		this.addPlugin(enricherPlugin$1(name, enrich));
+	}
+	/**
+	* Registers a provider consulted for every event this logger emits.
+	*
+	* @param provider - Called per event
+	* @returns A function that unregisters the provider
+	*/
+	addContextProvider(provider) {
+		this.fContextProviders.push(provider);
+		return () => {
+			const index = this.fContextProviders.indexOf(provider);
+			if (index !== -1) this.fContextProviders.splice(index, 1);
+		};
+	}
+	/**
+	* Collects the fields every registered provider contributes.
+	*
+	* @returns The merged provided context, or null when nothing was contributed
+	* @private
+	*/
+	providedContext() {
+		if (this.fContextProviders.length === 0) return null;
+		let merged = null;
+		for (const provider of this.fContextProviders) {
+			const context = provider();
+			if (context) merged = merged === null ? { ...context } : Object.assign(merged, context);
+		}
+		return merged;
+	}
+	/**
+	* Pushes the stored configuration and every registered plugin into evlog.
+	*
+	* @private
+	*/
+	apply() {
+		const { logLevel, plugins, ...config } = this.fOptions;
 		initLogger$1({
 			...config,
-			minLevel: logLevel ?? config.minLevel
+			minLevel: logLevel ?? config.minLevel,
+			plugins: plugins ? [...plugins, ...this.fPlugins] : this.fPlugins
 		});
 	}
 	/**
@@ -87,6 +172,7 @@ var BaseLogger = class BaseLogger extends Logger {
 			...this.fContext,
 			...context
 		};
+		child.fContextProviders = this.fContextProviders;
 		return child;
 	}
 	/**
@@ -95,6 +181,7 @@ var BaseLogger = class BaseLogger extends Logger {
 	*/
 	emit(overrides = {}) {
 		const event = {
+			...this.providedContext(),
 			...this.fContext,
 			...overrides
 		};
@@ -116,11 +203,15 @@ var BaseLogger = class BaseLogger extends Logger {
 	* @param args - The raw arguments passed to the log method
 	*/
 	dispatch(level, args) {
-		if (!(Object.keys(this.fContext).length > 0) && args.length === 2 && typeof args[0] === "string" && typeof args[1] === "string") {
+		const provided = this.providedContext();
+		if (!(provided !== null || Object.keys(this.fContext).length > 0) && args.length === 2 && typeof args[0] === "string" && typeof args[1] === "string") {
 			log$1[level](args[0], args[1]);
 			return;
 		}
-		const event = { ...this.fContext };
+		const event = {
+			...provided,
+			...this.fContext
+		};
 		const messageParts = [];
 		let tag;
 		for (const arg of args) if (arg instanceof Error) event.error = {
@@ -140,4 +231,4 @@ var BaseLogger = class BaseLogger extends Logger {
 	}
 };
 //#endregion
-export { BaseLogger, EvlogError, Logger, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, initLogger, log, parseError };
+export { BaseLogger, EvlogError, Logger, createError, createLogger, createRequestLogger, defineError, defineErrorCatalog, definePlugin, drainPlugin, enricherPlugin, initLogger, log, parseError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/logger",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Logger module for Vercube framework",
   "repository": {
     "type": "git",
@@ -23,6 +23,11 @@
       "import": "./dist/Toolkit.mjs",
       "default": "./dist/Toolkit.mjs"
     },
+    "./otlp": {
+      "types": "./dist/Otlp.d.mts",
+      "import": "./dist/Otlp.mjs",
+      "default": "./dist/Otlp.mjs"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.mts",
@@ -31,8 +36,8 @@
     "README.md"
   ],
   "dependencies": {
-    "evlog": "^2.26.0",
-    "@vercube/di": "1.2.1"
+    "@vercube/di": "1.3.0",
+    "evlog": "^2.28.1"
   },
   "publishConfig": {
     "access": "public"