@loglayer/mixin-datadog-http-metrics 1.0.0 → 2.1.0

package/dist/index.d.cts

@@ -1,6 +1,67 @@
 import metrics, { BufferedMetricsLogger as BufferedMetricsLogger$1, BufferedMetricsLoggerOptions, BufferedMetricsLoggerOptions as BufferedMetricsLoggerOptions$1 } from "datadog-metrics";
 
 //#region ../../core/shared/dist/index.d.ts
+//#region src/lazy.d.ts
+/**
+ * Symbol used to identify lazy values in context and metadata.
+ * Can be used to check if a value is a lazy wrapper: `LAZY_SYMBOL in value`.
+ *
+ * @see {@link https://loglayer.dev/logging-api/lazy-evaluation | Lazy Evaluation Docs}
+ */
+declare const LAZY_SYMBOL: unique symbol;
+/**
+ * String constant used as a replacement value when a lazy callback fails during evaluation.
+ * Exported so users can programmatically detect lazy evaluation failures in their log output.
+ *
+ * @see {@link https://loglayer.dev/logging-api/lazy-evaluation#error-handling | Lazy Evaluation Error Handling Docs}
+ */
+/**
+ * Represents a lazy value that defers evaluation until log time.
+ *
+ * Created by the {@link lazy} function.
+ *
+ * When the type parameter `T` is a `Promise`, log methods that receive this
+ * lazy value in metadata will return `Promise<void>` instead of `void`.
+ *
+ * @see {@link https://loglayer.dev/logging-api/lazy-evaluation | Lazy Evaluation Docs}
+ */
+interface LazyLogValue<T = any> {
+  [LAZY_SYMBOL]: () => T;
+}
+/**
+ * Wraps a callback function to defer its evaluation until log time.
+ *
+ * The callback will only be invoked if the log level is enabled,
+ * avoiding unnecessary computation for disabled log levels.
+ *
+ * Can be used in both `withContext()` and `withMetadata()` at the root level.
+ *
+ * When the callback returns a `Promise` (i.e., is an async function), the
+ * log method will return `Promise<void>` so TypeScript can track that the
+ * operation is asynchronous.
+ *
+ * Adapted from [LogTape's lazy evaluation](https://logtape.org/manual/lazy).
+ *
+ * @example
+ * ```typescript
+ * import { LogLayer, lazy } from "loglayer";
+ *
+ * const log = new LogLayer({ ... });
+ *
+ * // Dynamic context - evaluated on each log call
+ * log.withContext({
+ *   memoryUsage: lazy(() => process.memoryUsage().heapUsed),
+ * });
+ *
+ * // Dynamic metadata - evaluated only if debug is enabled
+ * log.withMetadata({
+ *   data: lazy(() => JSON.stringify(largeObject)),
+ * }).debug("Processing complete");
+ * ```
+ *
+ * @see {@link https://loglayer.dev/logging-api/lazy-evaluation | Lazy Evaluation Docs}
+ */
+//#endregion
 //#region src/common.types.d.ts
 declare enum LogLevel {
   info = "info",
@@ -26,7 +87,7 @@ interface ErrorOnlyOpts {
   /**
    * Sets the log level of the error
    */
-  logLevel?: LogLevel;
+  logLevel?: LogLevelType;
   /**
    * If `true`, copies the `error.message` if available to the transport library's
    * message property.
@@ -50,6 +111,49 @@ interface LogLayerMetadata extends Record<string, any> {}
  * Used internally by LogLayer when assembling the final data object (metadata / context / error) sent to transports.
  */
 interface LogLayerData extends Record<string, any> {}
+/**
+ * Type-level helper that checks whether a metadata/context record type
+ * contains any {@link LazyLogValue} whose callback returns a `Promise`.
+ *
+ * Evaluates to `true` if any property is `LazyLogValue<Promise<any>>`,
+ * `false` otherwise. Returns `false` for `undefined` or `null` inputs.
+ *
+ * @see {@link https://loglayer.dev/logging-api/lazy-evaluation | Lazy Evaluation Docs}
+ */
+type ContainsAsyncLazy<M> = M extends undefined | null ? false : true extends { [K in keyof M]: M[K] extends LazyLogValue<infer T> ? (T extends Promise<any> ? true : false) : false }[keyof M] ? true : false;
+/**
+ * Helper type that resolves the return type of log methods based on whether
+ * async lazy values are present.
+ *
+ * - `true` → `Promise<void>` (async lazy values detected)
+ * - `false` → `void` (no async lazy values)
+ * - `boolean` → `void | Promise<void>` (indeterminate, used by implementation classes)
+ */
+type LogReturnType<IsAsync extends boolean> = IsAsync extends true ? Promise<void> : IsAsync extends false ? void : void | Promise<void>;
+/**
+ * Configuration for a single log group.
+ * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+ */
+interface LogGroupConfig {
+  /**
+   * Array of transport IDs that this group routes to.
+   */
+  transports: string[];
+  /**
+   * Minimum log level for this group. Logs below this level are dropped
+   * for this group's transports. Default is "trace" (all levels pass).
+   */
+  level?: LogLevelType;
+  /**
+   * Whether this group is enabled. Default is true.
+   */
+  enabled?: boolean;
+}
+/**
+ * Map of group names to their configurations.
+ * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+ */
+type LogGroupsConfig = Record<string, LogGroupConfig>;
 interface LogLayerCommonDataParams {
   /**
    * Combined object data containing the metadata, context, and / or error data in a
@@ -70,6 +174,37 @@ interface LogLayerCommonDataParams {
   context?: LogLayerContext;
 } //#endregion
 //#region src/plugin.types.d.ts
+/**
+ * Schema information for navigating the assembled log data.
+ *
+ * Contains the resolved field names used when assembling the log data,
+ * so plugins can navigate Data precisely (e.g., find the error map at
+ * errorFieldName).
+ *
+ * @note Only `errorFieldName` is guaranteed to be present. `contextFieldName`
+ * and `metadataFieldName` are `undefined` when their respective data is merged
+ * at the root level of the data object (i.e., when `contextFieldName` or
+ * `metadataFieldName` is not configured in LogLayer).
+ *
+ * @see {@link https://loglayer.dev/plugins/creating-plugins.html | Creating Plugins}
+ */
+interface LogLayerPluginSchema {
+  /**
+   * The key under which persistent context data is nested in data.
+   * `undefined` when context is merged at root level.
+   */
+  contextFieldName?: string;
+  /**
+   * The key under which per-call metadata is nested in data.
+   * `undefined` when metadata is merged at root level.
+   */
+  metadataFieldName?: string;
+  /**
+   * The key under which the serialized error is stored in data.
+   * Always populated; defaults to "err".
+   */
+  errorFieldName: string;
+}
 /**
  * Input for the `onBeforeDataOut` plugin lifecycle method.
  * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforedataout | Creating Plugins}
@@ -79,6 +214,21 @@ interface PluginBeforeDataOutParams extends LogLayerCommonDataParams {
    * Log level of the data
    */
   logLevel: LogLevelType;
+  /**
+   * The group names this log entry belongs to, if any.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: string[];
+  /**
+   * Schema information for navigating the assembled data.
+   */
+  schema?: LogLayerPluginSchema;
+  /**
+   * The prefix attached via withPrefix() on the emitting logger (or set
+   * via config.prefix). Empty when no prefix was set.
+   */
+  prefix?: string;
 }
 /**
  * Input for the `transformLogLevel` plugin lifecycle method.
@@ -93,6 +243,21 @@ interface PluginTransformLogLevelParams extends LogLayerCommonDataParams {
    * Message data that is copied from the original.
    */
   messages: any[];
+  /**
+   * The group names this log entry belongs to, if any.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: string[];
+  /**
+   * Schema information for navigating the assembled data.
+   */
+  schema?: LogLayerPluginSchema;
+  /**
+   * The prefix attached via withPrefix() on the emitting logger (or set
+   * via config.prefix). Empty when no prefix was set.
+   */
+  prefix?: string;
 }
 /**
  * Input for the `shouldSendToLogger` plugin lifecycle method.
@@ -111,6 +276,21 @@ interface PluginShouldSendToLoggerParams extends LogLayerCommonDataParams {
    * Log level of the message
    */
   logLevel: LogLevelType;
+  /**
+   * The group names this log entry belongs to, if any.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: string[];
+  /**
+   * Schema information for navigating the assembled data.
+   */
+  schema?: LogLayerPluginSchema;
+  /**
+   * The prefix attached via withPrefix() on the emitting logger (or set
+   * via config.prefix). Empty when no prefix was set.
+   */
+  prefix?: string;
 }
 /**
  * Input for the `onBeforeMessageOut` plugin lifecycle method.
@@ -125,6 +305,21 @@ interface PluginBeforeMessageOutParams {
    * Message data that is copied from the original.
    */
   messages: any[];
+  /**
+   * The group names this log entry belongs to, if any.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: string[];
+  /**
+   * Schema information for navigating the assembled data.
+   */
+  schema?: LogLayerPluginSchema;
+  /**
+   * The prefix attached via withPrefix() on the emitting logger (or set
+   * via config.prefix). Empty when no prefix was set.
+   */
+  prefix?: string;
 }
 /**
  * Parameters for creating a LogLayer plugin.
@@ -430,6 +625,21 @@ interface LogLayerTransportParams extends LogLayerCommonDataParams {
    * If true, the data object is included in the message parameters
    */
   hasData?: boolean;
+  /**
+   * The group names this log entry belongs to, if any.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: string[];
+  /**
+   * Schema information for navigating the assembled data.
+   */
+  schema?: LogLayerPluginSchema;
+  /**
+   * The prefix attached via withPrefix() on the emitting logger (or set
+   * via config.prefix). Empty when no prefix was set.
+   */
+  prefix?: string;
 }
 /**
  * Interface for implementing a LogLayer transport instance.
@@ -461,57 +671,112 @@ interface LogLayerTransport<LogLibrary = any> {
 }
 /**
  * Interface for implementing a LogLayer builder instance.
+ *
+ * @typeParam This - The concrete builder type for polymorphic chaining.
+ * @typeParam IsAsync - Whether the builder contains async lazy metadata.
+ *   When `true`, log methods return `Promise<void>`. When `false`, they return `void`.
+ *   When `boolean` (indeterminate), they return `void | Promise<void>`.
+ *
  * @see {@link https://loglayer.dev | LogLayer Documentation}
  */
-interface ILogBuilder<This = ILogBuilder<any>> {
+interface ILogBuilder<This = ILogBuilder<any, any>, IsAsync extends boolean = false> {
   /**
    * Sends a log message to the logging library under an info log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ userId }).info`User ${userId} logged in`;
+   * ```
    */
-  info(...messages: MessageDataType[]): void;
+  info(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  info(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Sends a log message to the logging library under the warn log level
+   * Sends a log message to the logging library under the warn log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ requestId }).warn`Request ${requestId} timed out`;
+   * ```
    */
-  warn(...messages: MessageDataType[]): void;
+  warn(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  warn(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Sends a log message to the logging library under the error log level
+   * Sends a log message to the logging library under the error log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withError(err).error`Failed to process ${taskId}`;
+   * ```
    */
-  error(...messages: MessageDataType[]): void;
+  error(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  error(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Sends a log message to the logging library under the debug log level
+   * Sends a log message to the logging library under the debug log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ cacheKey }).debug`Cache hit for ${cacheKey}`;
+   * ```
    */
-  debug(...messages: MessageDataType[]): void;
+  debug(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  debug(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Sends a log message to the logging library under the trace log level
+   * Sends a log message to the logging library under the trace log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ functionName }).trace`Entering ${functionName}`;
+   * ```
    */
-  trace(...messages: MessageDataType[]): void;
+  trace(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  trace(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Sends a log message to the logging library under the fatal log level
+   * Sends a log message to the logging library under the fatal log level.
+   * Returns a Promise when async lazy values are present in metadata.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withError(err).fatal`System crash: ${reason}`;
+   * ```
    */
-  fatal(...messages: MessageDataType[]): void;
+  fatal(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
+  fatal(...messages: MessageDataType[]): LogReturnType<IsAsync>;
   /**
-   * Specifies metadata to include with the log message
+   * Specifies metadata to include with the log message.
+   * If the metadata contains async lazy values, subsequent log methods will return `Promise<void>`.
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  withMetadata(metadata?: LogLayerMetadata): This;
+  withMetadata<M extends LogLayerMetadata>(metadata?: M): ILogBuilder<This, ContainsAsyncLazy<NonNullable<M>> extends true ? true : IsAsync>;
   /**
    * Specifies an Error to include with the log message
    *
    * @see {@link https://loglayer.dev/logging-api/error-handling.html | Error Handling Docs}
    */
-  withError(error: any): This;
+  withError(error: any): ILogBuilder<This, IsAsync>;
+  /**
+   * Tags this log entry with one or more groups for routing.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  withGroup(group: string | string[]): ILogBuilder<This, IsAsync>;
   /**
    * Enable sending logs to the logging library.
    *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html#enabling-disabling-logging | Enabling/Disabling Logging Docs}
    */
-  enableLogging(): This;
+  enableLogging(): ILogBuilder<This, IsAsync>;
   /**
    * All logging inputs are dropped and stops sending logs to the logging library.
    *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html#enabling-disabling-logging | Enabling/Disabling Logging Docs}
    */
-  disableLogging(): This;
+  disableLogging(): ILogBuilder<This, IsAsync>;
 }
 /**
  * Interface for implementing a LogLayer logger instance.
@@ -520,40 +785,77 @@ interface ILogBuilder<This = ILogBuilder<any>> {
 interface ILogLayer<This = ILogLayer<any>> {
   /**
    * Sends a log message to the logging library under an info log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.info`User ${userId} logged in`;
+   * ```
    */
+  info(strings: TemplateStringsArray, ...values: any[]): void;
   info(...messages: MessageDataType[]): void;
   /**
-   * Sends a log message to the logging library under the warn log level
+   * Sends a log message to the logging library under the warn log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.warn`Request ${requestId} timed out`;
+   * ```
    */
+  warn(strings: TemplateStringsArray, ...values: any[]): void;
   warn(...messages: MessageDataType[]): void;
   /**
-   * Sends a log message to the logging library under the error log level
+   * Sends a log message to the logging library under the error log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.error`Failed to process ${taskId}`;
+   * ```
    */
+  error(strings: TemplateStringsArray, ...values: any[]): void;
   error(...messages: MessageDataType[]): void;
   /**
-   * Sends a log message to the logging library under the debug log level
+   * Sends a log message to the logging library under the debug log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.debug`Cache hit for ${cacheKey}`;
+   * ```
    */
+  debug(strings: TemplateStringsArray, ...values: any[]): void;
   debug(...messages: MessageDataType[]): void;
   /**
-   * Sends a log message to the logging library under the trace log level
+   * Sends a log message to the logging library under the trace log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.trace`Entering ${functionName}`;
+   * ```
    */
+  trace(strings: TemplateStringsArray, ...values: any[]): void;
   trace(...messages: MessageDataType[]): void;
   /**
-   * Sends a log message to the logging library under the fatal log level
+   * Sends a log message to the logging library under the fatal log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.fatal`System crash: ${reason}`;
+   * ```
    */
+  fatal(strings: TemplateStringsArray, ...values: any[]): void;
   fatal(...messages: MessageDataType[]): void;
   /**
-   * Specifies metadata to include with the log message
+   * Specifies metadata to include with the log message.
+   * If the metadata contains async lazy values, the builder's log methods will return `Promise<void>`.
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  withMetadata(metadata?: LogLayerMetadata): ILogBuilder<any>;
+  withMetadata<M extends LogLayerMetadata>(metadata?: M): ILogBuilder<any, ContainsAsyncLazy<NonNullable<M>>>;
   /**
    * Specifies an Error to include with the log message
    *
    * @see {@link https://loglayer.dev/logging-api/error-handling.html | Error Handling Docs}
    */
-  withError(error: any): ILogBuilder<any>;
+  withError(error: any): ILogBuilder<any, false>;
   /**
    * Enable sending logs to the logging library.
    *
@@ -572,6 +874,57 @@ interface ILogLayer<This = ILogLayer<any>> {
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html#message-prefixing | Message Prefixing Docs}
    */
   withPrefix(string: string): This;
+  /**
+   * Creates a child logger with the specified group(s) persistently assigned.
+   * All logs from the child will be tagged with these groups.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  withGroup(group: string | string[]): This;
+  /**
+   * Adds a new group definition at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  addGroup(name: string, config: LogGroupConfig): This;
+  /**
+   * Removes a group definition at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  removeGroup(name: string): This;
+  /**
+   * Enables a group by name (sets enabled: true).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  enableGroup(name: string): This;
+  /**
+   * Disables a group by name (sets enabled: false). Logs tagged with a disabled
+   * group will not be routed through that group.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  disableGroup(name: string): This;
+  /**
+   * Sets the minimum log level for a group at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  setGroupLevel(name: string, level: LogLevelType): This;
+  /**
+   * Sets which groups are active. Only active groups will route logs.
+   * Pass null to clear the filter (all groups active).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  setActiveGroups(groups: string[] | null): This;
+  /**
+   * Returns a snapshot of all group configurations.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  getGroups(): LogGroupsConfig;
   /**
    * Appends context data which will be included with
    * every log entry.
@@ -597,17 +950,23 @@ interface ILogLayer<This = ILogLayer<any>> {
    */
   errorOnly(error: any, opts?: ErrorOnlyOpts): void;
   /**
-   * Logs only metadata without a log message
+   * Logs only metadata without a log message.
+   * Returns a Promise when async lazy values are present in metadata.
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  metadataOnly(metadata?: LogLayerMetadata, logLevel?: LogLevelType): void;
+  metadataOnly<M extends LogLayerMetadata>(metadata?: M, logLevel?: LogLevelType): LogReturnType<ContainsAsyncLazy<NonNullable<M>>>;
   /**
-   * Returns the context used
+   * Returns the context used.
+   * By default, lazy values are resolved before returning.
+   * Pass `{ raw: true }` to return the raw lazy wrappers without resolving them.
+   * Async lazy values in context are not supported and will be replaced with `"[LazyEvalError]"`.
    *
    * @see {@link https://loglayer.dev/logging-api/context.html | Context Docs}
    */
-  getContext(): LogLayerContext;
+  getContext(options?: {
+    raw?: boolean;
+  }): LogLayerContext;
   /**
    * Creates a new instance of LogLayer but with the initialization
    * configuration and context data copied over.
@@ -769,6 +1128,9 @@ interface ILogLayer<This = ILogLayer<any>> {
     metadataFieldName?: string;
     muteContext?: boolean;
     muteMetadata?: boolean;
+    groups?: LogGroupsConfig;
+    activeGroups?: string[] | null;
+    ungroupedBehavior?: "all" | "none" | string[];
   };
   /**
    * Logs a raw log entry with complete control over all log parameters.
@@ -780,11 +1142,28 @@ interface ILogLayer<This = ILogLayer<any>> {
    * systems that provide pre-formatted log entries.
    *
    * The raw entry will still go through all LogLayer processing.
+   * Returns a Promise when async lazy values are present in the entry's metadata.
    *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  raw(rawEntry: RawLogEntry): void;
+  raw<R extends RawLogEntry>(rawEntry: R): LogReturnType<ContainsAsyncLazy<NonNullable<R["metadata"]>>>;
 } //#endregion
+//#region src/template-utils.d.ts
+/**
+ * Arguments from a tagged template literal call: [TemplateStringsArray, ...values]
+ */
+type TaggedTemplateArgs = [TemplateStringsArray, ...any[]];
+/**
+ * Union of tagged template args and regular message args.
+ * Used by log methods that accept both syntaxes:
+ * - log.info\`Message ${value}\`
+ * - log.info("Message", value)
+ */
+type TaggedTemplateOrMessageArgs = TaggedTemplateArgs | MessageDataType[];
+/**
+ * Converts tagged template arguments to a message array.
+ * Detects tagged templates by checking for the `raw` property on TemplateStringsArray.
+ */
 //#endregion
 //#region ../../core/plugin/dist/index.d.ts
 /**
@@ -857,17 +1236,18 @@ declare class PluginManager {
  * A mock implementation of the ILogBuilder interface that does nothing.
  * Useful for writing unit tests.
  */
-declare class MockLogBuilder implements ILogBuilder<MockLogBuilder> {
-  debug(..._messages: MessageDataType[]): void;
-  error(..._messages: MessageDataType[]): void;
-  info(..._messages: MessageDataType[]): void;
-  trace(..._messages: MessageDataType[]): void;
-  warn(..._messages: MessageDataType[]): void;
-  fatal(..._messages: MessageDataType[]): void;
+declare class MockLogBuilder implements ILogBuilder<MockLogBuilder, false> {
+  debug(..._args: TaggedTemplateOrMessageArgs): void;
+  error(..._args: TaggedTemplateOrMessageArgs): void;
+  info(..._args: TaggedTemplateOrMessageArgs): void;
+  trace(..._args: TaggedTemplateOrMessageArgs): void;
+  warn(..._args: TaggedTemplateOrMessageArgs): void;
+  fatal(..._args: TaggedTemplateOrMessageArgs): void;
   enableLogging(): this;
   disableLogging(): this;
-  withMetadata(_metadata?: Record<string, any>): this;
-  withError(_error: any): this;
+  withMetadata(_metadata?: Record<string, any>): any;
+  withError(_error: any): any;
+  withGroup(_group: string | string[]): any;
 } //#endregion
 //#region src/MockLogLayer.d.ts
 /**
@@ -875,29 +1255,39 @@ declare class MockLogBuilder implements ILogBuilder<MockLogBuilder> {
  * Useful for writing unit tests.
  * MockLogLayer implements both ILogLayer and ILogBuilder for simplicity in testing.
  */
-declare class MockLogLayer$1 implements ILogLayer<MockLogLayer$1>, ILogBuilder<MockLogLayer$1> {
+declare class MockLogLayer$1 implements ILogLayer<MockLogLayer$1> {
   private mockLogBuilder;
   private mockContextManager;
   private mockLogLevelManager;
-  info(..._messages: MessageDataType[]): void;
-  warn(..._messages: MessageDataType[]): void;
-  error(..._messages: MessageDataType[]): void;
-  debug(..._messages: MessageDataType[]): void;
-  trace(..._messages: MessageDataType[]): void;
-  fatal(..._messages: MessageDataType[]): void;
-  raw(_rawEntry: RawLogEntry): void;
+  info(..._args: TaggedTemplateOrMessageArgs): void;
+  warn(..._args: TaggedTemplateOrMessageArgs): void;
+  error(..._args: TaggedTemplateOrMessageArgs): void;
+  debug(..._args: TaggedTemplateOrMessageArgs): void;
+  trace(..._args: TaggedTemplateOrMessageArgs): void;
+  fatal(..._args: TaggedTemplateOrMessageArgs): void;
+  raw(_rawEntry: RawLogEntry): any;
   getLoggerInstance<_T extends LogLayerTransport>(_id: string): any;
   errorOnly(_error: any, _opts?: ErrorOnlyOpts): void;
-  metadataOnly(_metadata?: Record<string, any>, _logLevel?: LogLevel): void;
+  metadataOnly(_metadata?: Record<string, any>, _logLevel?: LogLevel): any;
   addPlugins(_plugins: Array<LogLayerPlugin>): void;
   removePlugin(_id: string): void;
   enablePlugin(_id: string): void;
   disablePlugin(_id: string): void;
   withPrefix(_prefix: string): this;
+  withGroup(_group: string | string[]): this;
+  addGroup(_name: string, _config: LogGroupConfig): this;
+  removeGroup(_name: string): this;
+  enableGroup(_name: string): this;
+  disableGroup(_name: string): this;
+  setGroupLevel(_name: string, _level: LogLevelType): this;
+  setActiveGroups(_groups: string[] | null): this;
+  getGroups(): LogGroupsConfig;
   withContext(_context?: Record<string, any>): this;
-  withError(_error: any): any;
-  withMetadata(_metadata?: Record<string, any>): any;
-  getContext(): Record<string, any>;
+  withError(_error: any): ILogBuilder<any, false>;
+  withMetadata<M extends LogLayerMetadata>(_metadata?: M): ILogBuilder<any, ContainsAsyncLazy<NonNullable<M>>>;
+  getContext(_options?: {
+    raw?: boolean;
+  }): Record<string, any>;
   clearContext(_keys?: string | string[]): this;
   enableLogging(): this;
   disableLogging(): this;
@@ -926,7 +1316,7 @@ declare class MockLogLayer$1 implements ILogLayer<MockLogLayer$1>, ILogBuilder<M
   /**
    * Returns the mock log builder used for testing.
    */
-  getMockLogBuilder(): ILogBuilder<ILogBuilder<any>>;
+  getMockLogBuilder(): ILogBuilder<ILogBuilder<any, any>, false>;
   /**
    * Resets the mock log builder to a new instance of MockLogBuilder.
    */
@@ -1107,6 +1497,32 @@ interface LogLayerConfig {
    * If set to true, will not include metadata data in the log message.
    */
   muteMetadata?: boolean;
+  /**
+   * Named routing groups. Each group defines which transports it routes to
+   * and an optional minimum log level.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  groups?: LogGroupsConfig;
+  /**
+   * When set, only these group names are active. Logs tagged with inactive
+   * groups are dropped. The `LOGLAYER_GROUPS` env variable overrides this
+   * at construction time.
+   *
+   * Set to `null` to clear the filter (all defined groups are active).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  activeGroups?: string[] | null;
+  /**
+   * Controls what happens to logs that have NO group tags.
+   * - `'all'` (default): ungrouped logs go to ALL transports (backward compatible).
+   * - `'none'`: ungrouped logs are dropped entirely.
+   * - `string[]`: ungrouped logs go only to the listed transport IDs.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  ungroupedBehavior?: "all" | "none" | string[];
 } //#endregion
 //#region src/LogLayer.d.ts
 interface FormatLogParams {
@@ -1115,6 +1531,7 @@ interface FormatLogParams {
   metadata?: LogLayerMetadata | null;
   err?: any;
   context?: LogLayerContext | null;
+  groups?: string[] | null;
 }
 /**
  * Wraps around a logging framework to provide convenience methods that allow
@@ -1128,6 +1545,12 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
   private singleTransport;
   private contextManager;
   private logLevelManager;
+  private _isLoggingLazyError;
+  private _lazyContextCount;
+  private _assignedGroups;
+  private _groupsConfig;
+  private _activeGroups;
+  private _ungroupedBehavior;
   /**
    * The configuration object used to initialize the logger.
    * This is for internal use only and should not be modified directly.
@@ -1161,6 +1584,56 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html#message-prefixing | Message Prefixing Docs}
    */
   withPrefix(prefix: string): LogLayer$1;
+  /**
+   * Creates a child logger with the specified group(s) persistently assigned.
+   * All logs from the child will be tagged with these groups.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  withGroup(group: string | string[]): LogLayer$1;
+  /**
+   * Adds a new group definition at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  addGroup(name: string, config: LogGroupConfig): LogLayer$1;
+  /**
+   * Removes a group definition at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  removeGroup(name: string): LogLayer$1;
+  /**
+   * Enables a group by name (sets enabled: true).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  enableGroup(name: string): LogLayer$1;
+  /**
+   * Disables a group by name (sets enabled: false).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  disableGroup(name: string): LogLayer$1;
+  /**
+   * Sets the minimum log level for a group at runtime.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  setGroupLevel(name: string, level: LogLevelType): LogLayer$1;
+  /**
+   * Sets which groups are active. Only active groups will route logs.
+   * Pass null to clear the filter (all groups active).
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  setActiveGroups(groups: string[] | null): LogLayer$1;
+  /**
+   * Returns a snapshot of all group configurations.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  getGroups(): LogGroupsConfig;
   /**
    * Appends context data which will be included with
    * every log entry.
@@ -1177,7 +1650,9 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    * If no keys are provided, all context data will be cleared.
    */
   clearContext(keys?: string | string[]): this;
-  getContext(): LogLayerContext;
+  getContext(options?: {
+    raw?: boolean;
+  }): LogLayerContext;
   /**
    * Add additional plugins.
    *
@@ -1207,13 +1682,13 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  withMetadata(metadata?: LogLayerMetadata): LogBuilder;
+  withMetadata<M extends LogLayerMetadata>(metadata?: M): ILogBuilder<any, ContainsAsyncLazy<NonNullable<M>>>;
   /**
    * Specifies an Error to include with the log message
    *
    * @see {@link https://loglayer.dev/logging-api/error-handling.html | Error Handling Docs}
    */
-  withError(error: any): LogBuilder;
+  withError(error: any): ILogBuilder<any, false>;
   /**
    * Creates a new instance of LogLayer but with the initialization
    * configuration and context copied over.
@@ -1275,46 +1750,73 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  metadataOnly(metadata?: LogLayerMetadata, logLevel?: LogLevelType): void;
+  metadataOnly<M extends LogLayerMetadata>(metadata?: M, logLevel?: LogLevelType): LogReturnType<ContainsAsyncLazy<NonNullable<M>>>;
   /**
    * Sends a log message to the logging library under an info log level.
    *
-   * The logging library may or may not support multiple message parameters and only
-   * the first parameter would be used.
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.info`User ${userId} logged in`;
+   * ```
    *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  info(...messages: MessageDataType[]): void;
+  info(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Sends a log message to the logging library under the warn log level
    *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.warn`Request ${requestId} timed out`;
+   * ```
+   *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  warn(...messages: MessageDataType[]): void;
+  warn(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Sends a log message to the logging library under the error log level
    *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.error`Failed to process ${taskId}`;
+   * ```
+   *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  error(...messages: MessageDataType[]): void;
+  error(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Sends a log message to the logging library under the debug log level
    *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.debug`Cache hit for ${cacheKey}`;
+   * ```
+   *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  debug(...messages: MessageDataType[]): void;
+  debug(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Sends a log message to the logging library under the trace log level
    *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.trace`Entering ${functionName}`;
+   * ```
+   *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  trace(...messages: MessageDataType[]): void;
+  trace(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Sends a log message to the logging library under the fatal log level
    *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.fatal`System crash: ${reason}`;
+   * ```
+   *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  fatal(...messages: MessageDataType[]): void;
+  fatal(...args: TaggedTemplateOrMessageArgs): void;
   /**
    * Logs a raw log entry with complete control over all log parameters.
    *
@@ -1328,7 +1830,7 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    *
    * @see {@link https://loglayer.dev/logging-api/basic-logging.html | Basic Logging Docs}
    */
-  raw(logEntry: RawLogEntry): void;
+  raw<R extends RawLogEntry>(logEntry: R): LogReturnType<ContainsAsyncLazy<NonNullable<R["metadata"]>>>;
   /**
    * All logging inputs are dropped and stops sending logs to the logging library.
    *
@@ -1408,80 +1910,147 @@ declare class LogLayer$1 implements ILogLayer<LogLayer$1> {
    * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
    */
   getLoggerInstance<Logger>(id: string): Logger | undefined;
+  /**
+   * Parses the LOGLAYER_GROUPS environment variable and overrides
+   * _activeGroups and group levels accordingly.
+   * Format: "name,name" or "name:level,name:level"
+   */
+  private _parseEnvGroups;
+  /**
+   * Merges per-log groups (from LogBuilder) with logger-level assigned groups.
+   */
+  private _mergeGroups;
+  /**
+   * Applies ungrouped routing rules for a transport.
+   */
+  private _applyUngroupedRules;
+  /**
+   * Determines whether a transport should receive a log entry based on group routing rules.
+   */
+  private _shouldTransportReceiveLog;
   _formatMessage(messages?: MessageDataType[]): void;
   _formatLog({
     logLevel,
     params,
     metadata,
     err,
-    context
-  }: FormatLogParams): void;
+    context,
+    groups
+  }: FormatLogParams): void | Promise<void>;
+  /**
+   * Resolves any Promise values in metadata (from async lazy callbacks)
+   * and then processes the log entry. Context is already fully resolved.
+   */
+  private _resolveAsyncAndProcess;
+  /**
+   * Logs error entries for lazy evaluation failures.
+   * Calls _processLog directly to bypass lazy evaluation and prevent recursion.
+   */
+  private _logLazyEvalErrors;
+  /**
+   * Logs error entries for async lazy values found in context.
+   * Async lazy values are only supported in metadata, not context.
+   */
+  private _logAsyncLazyContextErrors;
+  /**
+   * Processes a log entry after lazy values have been fully resolved.
+   * Handles data assembly, plugins, and transport dispatch.
+   */
+  private _processLog;
 } //#endregion
 //#region src/LogBuilder.d.ts
 /**
  * A class that contains methods to specify log metadata and an error and assembles
  * it to form a data object that can be passed into the transport.
  */
-declare class LogBuilder implements ILogBuilder<LogBuilder> {
+declare class LogBuilder implements ILogBuilder<LogBuilder, boolean> {
   private err;
   private metadata;
   private structuredLogger;
   private hasMetadata;
   private pluginManager;
+  private _groups;
   constructor(structuredLogger: LogLayer$1);
   /**
    * Specifies metadata to include with the log message
    *
    * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
    */
-  withMetadata(metadata?: LogLayerMetadata): this;
+  withMetadata(metadata?: LogLayerMetadata): any;
   /**
    * Specifies an Error to include with the log message
    *
    * @see {@link https://loglayer.dev/logging-api/error-handling.html | Error Handling Docs}
    */
-  withError(error: any): this;
+  withError(error: any): any;
+  /**
+   * Tags this log entry with one or more groups for routing.
+   *
+   * @see {@link https://loglayer.dev/logging-api/groups.html | Groups Docs}
+   */
+  withGroup(group: string | string[]): any;
   /**
    * Sends a log message to the logging library under an info log level.
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ userId }).info`User ${userId} logged in`;
+   * ```
    */
-  info(...messages: MessageDataType[]): void;
+  info(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * Sends a log message to the logging library under the warn log level
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ requestId }).warn`Request ${requestId} timed out`;
+   * ```
    */
-  warn(...messages: MessageDataType[]): void;
+  warn(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * Sends a log message to the logging library under the error log level
+   *
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withError(err).error`Failed to process ${taskId}`;
+   * ```
    */
-  error(...messages: MessageDataType[]): void;
+  error(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * Sends a log message to the logging library under the debug log level
    *
-   * The logging library may or may not support multiple message parameters and only
-   * the first parameter would be used.
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ cacheKey }).debug`Cache hit for ${cacheKey}`;
+   * ```
    */
-  debug(...messages: MessageDataType[]): void;
+  debug(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * Sends a log message to the logging library under the trace log level
    *
-   * The logging library may or may not support multiple message parameters and only
-   * the first parameter would be used.
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withMetadata({ functionName }).trace`Entering ${functionName}`;
+   * ```
    */
-  trace(...messages: MessageDataType[]): void;
+  trace(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * Sends a log message to the logging library under the fatal log level
    *
-   * The logging library may or may not support multiple message parameters and only
-   * the first parameter would be used.
+   * Supports tagged template syntax:
+   * ```typescript
+   * log.withError(err).fatal`System crash: ${reason}`;
+   * ```
    */
-  fatal(...messages: MessageDataType[]): void;
+  fatal(...args: TaggedTemplateOrMessageArgs): void | Promise<void>;
   /**
    * All logging inputs are dropped and stops sending logs to the logging library.
    */
-  disableLogging(): this;
+  disableLogging(): any;
   /**
    * Enable sending logs to the logging library.
    */
-  enableLogging(): this;
+  enableLogging(): any;
   private formatLog;
 } //#endregion
 //#region src/mixins.d.ts