@loglayer/shared/dist/index.d.ts

Shared utilities and types for loglayer packages.

//#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}
 */
declare const LAZY_EVAL_ERROR = "[LazyEvalError]";
/**
 * Describes a single lazy evaluation failure.
 * @internal
 */
interface LazyEvalFailure {
  key: string;
  error: unknown;
}
/**
 * Result of resolving lazy values, including any errors that occurred.
 * @internal
 */
interface ResolveLazyResult<T> {
  resolved: T;
  errors: LazyEvalFailure[] | null;
}
/**
 * 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}
 */
declare function lazy<T>(fn: () => T): LazyLogValue<T>;
/**
 * Checks if a value is a lazy value created by {@link lazy}.
 * @internal
 */
declare function isLazy(value: unknown): value is LazyLogValue;
/**
 * Counts the number of lazy values in a record.
 * @internal
 */
declare function countLazyValues(obj: Record<string, any>): number;
/**
 * Resolves any lazy values in a record at the root level.
 * Returns the original object if no lazy values are found (optimization).
 * If a lazy callback throws, the value is replaced with LAZY_EVAL_ERROR
 * and the error is collected in the result.
 * @internal
 */
declare function resolveLazyValues<T extends Record<string, any>>(obj: T): ResolveLazyResult<T>;
/**
 * Checks if any values in a record are Promises.
 * @internal
 */
declare function hasPromiseValues(obj: Record<string, any>): boolean;
/**
 * Replaces any Promise values in a record with LAZY_EVAL_ERROR.
 * Used to strip async lazy values from context where only sync lazy is supported.
 * Returns the keys that were replaced.
 * @internal
 */
declare function replacePromiseValues<T extends Record<string, any>>(obj: T): {
  resolved: T;
  asyncKeys: string[] | null;
};
/**
 * Resolves any Promise values in a record using Promise.allSettled.
 * If a Promise rejects, the value is replaced with LAZY_EVAL_ERROR
 * and the error is collected in the result.
 * @internal
 */
declare function resolvePromiseValues<T extends Record<string, any>>(obj: T): Promise<ResolveLazyResult<T>>;
//#endregion
//#region src/common.types.d.ts
declare enum LogLevel {
  info = "info",
  warn = "warn",
  error = "error",
  debug = "debug",
  trace = "trace",
  fatal = "fatal"
}
/**
 * Combination of the LogLevel enum and its string representations.
 */
type LogLevelType = LogLevel | `${LogLevel}`;
/**
 * Mapping of log levels to their numeric values.
 */
declare const LogLevelPriority: Record<LogLevel, number>;
/**
 * Mapping of numeric values to their log level names.
 */
declare const LogLevelPriorityToNames: {
  10: LogLevel;
  20: LogLevel;
  30: LogLevel;
  40: LogLevel;
  50: LogLevel;
  60: LogLevel;
};
type MessageDataType = string | number | boolean | null | undefined;
/**
 * Options for the `errorOnly` method.
 * @see {@link https://loglayer.dev/logging-api/error-handling.html#error-only-logging | Error Only Logging Doc}
 */
interface ErrorOnlyOpts {
  /**
   * Sets the log level of the error
   */
  logLevel?: LogLevelType;
  /**
   * If `true`, copies the `error.message` if available to the transport library's
   * message property.
   *
   * If the config option `error.copyMsgOnOnlyError` is enabled, this property
   * can be set to `true` to disable the behavior for this specific log entry.
   */
  copyMsg?: boolean;
}
/**
 * Defines the structure for context data that persists across multiple log entries
 * within the same context scope. This is set using log.withContext().
 */
interface LogLayerContext extends Record<string, any> {}
/**
 * Defines the structure for metadata that can be attached to individual log entries.
 * This is set using log.withMetadata() or log.metadataOnly().
 */
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
   * structured format configured by the user.
   */
  data?: LogLayerData;
  /**
   * Individual metadata object passed to the log message method.
   */
  metadata?: LogLayerMetadata;
  /**
   * Error passed to the log message method.
   */
  error?: any;
  /**
   * Context data that is included with each log entry.
   */
  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}
 */
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.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html#transformloglevel | Creating Plugins}
 */
interface PluginTransformLogLevelParams extends LogLayerCommonDataParams {
  /**
   * Log level of the data
   */
  logLevel: LogLevelType;
  /**
   * 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.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html#shouldsendtologger | Creating Plugins}
 */
interface PluginShouldSendToLoggerParams extends LogLayerCommonDataParams {
  /**
   * Unique identifier for the transport. Can be used to not send to a specific transport.
   */
  transportId?: string;
  /**
   * Message data that is copied from the original.
   */
  messages: any[];
  /**
   * 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.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforemessageout | Creating Plugins}
 */
interface PluginBeforeMessageOutParams {
  /**
   * Log level of the message
   */
  logLevel: LogLevelType;
  /**
   * 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.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html | Creating Plugins}
 */
interface LogLayerPluginParams {
  /**
   * Unique identifier for the plugin. Used for selectively disabling / enabling
   * and removing the plugin. If not defined, a randomly generated ID will be used.
   */
  id?: string;
  /**
   * If true, the plugin will skip execution
   */
  disabled?: boolean;
}
/**
 * Interface for implementing a LogLayer plugin.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html | Creating Plugins}
 */
interface LogLayerPlugin extends LogLayerPluginParams {
  /**
   * Called after `onBeforeDataOut` and `onBeforeMessageOut` but before `shouldSendToLogger` to transform the log level.
   * This allows you to change the log level based on the processed log data, metadata, context, error, or messages.
   *
   * - The shape of `data` varies depending on your `fieldName` configuration
   * for metadata / context / error. The metadata / context / error data is a *shallow* clone.
   * - If data was not found for assembly, `undefined` is used as the `data` input.
   * - The `data` parameter will contain any modifications made by `onBeforeDataOut` plugins.
   * - The `messages` parameter will contain any modifications made by `onBeforeMessageOut` plugins.
   * - If multiple plugins define `transformLogLevel`, the last one that returns a valid log level wins.
   *
   * @returns [LogLevelType] The log level to use for the log. Returning null, undefined, or false
   * will use the log level originally specified.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#transformloglevel | Creating Plugins}
   */
  transformLogLevel?(params: PluginTransformLogLevelParams, loglayer: ILogLayer): LogLevelType | null | undefined | false;
  /**
   * Called after the assembly of the data object that contains
   * the metadata / context / error data before being sent to the destination logging
   * library.
   *
   * - The shape of `data` varies depending on your `fieldName` configuration
   * for metadata / context / error. The metadata / context / error data is a *shallow* clone.
   * - If data was not found for assembly, `undefined` is used as the `data` input.
   * - You can also create your own object and return it to be sent to the logging library.
   *
   * @returns [Object] The object to be sent to the destination logging
   * library or null / undefined to not pass an object through.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforedataout | Creating Plugins}
   */
  onBeforeDataOut?(params: PluginBeforeDataOutParams, loglayer: ILogLayer): LogLayerData | null | undefined;
  /**
   * Called after `onBeforeDataOut` and before `shouldSendToLogger`.
   * This allows you to modify the message data before it is sent to the destination logging library.
   *
   * @returns [Array] The message data to be sent to the destination logging library.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforemessageout | Creating Plugins}
   */
  onBeforeMessageOut?(params: PluginBeforeMessageOutParams, loglayer: ILogLayer): any[];
  /**
   * Called before the data is sent to the transport. Return false to omit sending
   * to the transport. Useful for isolating specific log messages for debugging /
   * troubleshooting.
   *
   * If there are multiple plugins with shouldSendToLogger defined, the
   * first plugin to return false will stop the data from being sent to the
   * transport.
   *
   * @returns boolean If true, sends data to the transport, if false does not.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#shouldsendtologger | Creating Plugins}
   */
  shouldSendToLogger?(params: PluginShouldSendToLoggerParams, loglayer: ILogLayer): boolean;
  /**
   * Called when withMetadata() or metadataOnly() is called. This allows you to modify the metadata before it is sent to the destination logging library.
   *
   * The metadata is a *shallow* clone of the metadata input.
   *
   * If null is returned, then no metadata will be sent to the destination logging library.
   *
   * In multiple plugins, the modified metadata will be passed through each plugin in the order they are added.
   *
   * @returns [Object] The metadata object to be sent to the destination logging library.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onmetadatacalled | Creating Plugins}
   */
  onMetadataCalled?: (metadata: LogLayerMetadata, loglayer: ILogLayer) => LogLayerMetadata | null | undefined;
  /**
   * Called when withContext() is called. This allows you to modify the context before it is used.
   *
   * The context is a *shallow* clone of the context input.
   *
   * If null is returned, then no context will be used.
   *
   * In multiple plugins, the modified context will be passed through each plugin in the order they are added.
   *
   * @returns [Object] The context object to be used.
   *
   * @see {@link https://loglayer.dev/plugins/creating-plugins.html#oncontextcalled | Creating Plugins}
   */
  onContextCalled?: (context: LogLayerContext, loglayer: ILogLayer) => LogLayerContext | null | undefined;
}
//#endregion
//#region src/loglayer.types.d.ts
/**
 * Interface for raw log entries that allows complete control over all aspects of a log entry.
 *
 * @see {@link https://loglayer.dev/logging-api/basic-logging.html#raw-logging | Raw Logging Documentation}
 */
interface RawLogEntry {
  /**
   * Context data to include with the log entry.
   *
   * - When provided, this context data will be used instead of the context manager.
   * - If not provided, the context manager data will be used instead
   * - An empty object will result in no context data being used at all
   */
  context?: LogLayerContext;
  /**
   * Metadata to include with the log entry.
   */
  metadata?: LogLayerMetadata;
  /**
   * Data to spread directly at the root level of the log entry.
   *
   * Unlike `metadata`, this bypasses `metadataFieldName` / `contextFieldName`
   * nesting and is always flattened at the root of the emitted log object.
   *
   * Note: Unlike `metadata`, `rootData` does not support lazy evaluation.
   */
  rootData?: LogLayerMetadata;
  /**
   * Error object to include with the log entry.
   */
  error?: any;
  /**
   * The log level for this entry.
   */
  logLevel: LogLevelType;
  /**
   * Array of message parameters to log.
   *
   * These are the actual log messages and can include strings, numbers,
   * booleans, null, or undefined values. The first string message will
   * have any configured prefix applied to it.
   */
  messages?: MessageDataType[];
}
/**
 * Context Manager callback function for when a child logger is created.
 * @see {@link https://loglayer.dev/context-managers/creating-context-managers.html | Creating Context Managers Docs}
 */
interface OnChildLoggerCreatedParams {
  /**
   * The parent logger instance
   */
  parentLogger: ILogLayer<any>;
  /**
   * The child logger instance
   */
  childLogger: ILogLayer<any>;
  /**
   * The parent logger's context manager
   */
  parentContextManager: IContextManager;
  /**
   * The child logger's context manager
   */
  childContextManager: IContextManager;
}
/**
 * Interface for implementing a context manager instance.
 *
 * If your context manager needs to clean up resources (like file handles, memory, or external connections),
 * you can optionally implement the {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management | Disposable} interface.
 * LogLayer will automatically call the dispose method when the context manager is replaced using `withContextManager()`.
 *
 * @see {@link https://loglayer.dev/context-managers/creating-context-managers.html | Creating Context Managers Docs}
 */
interface IContextManager {
  /**
   * Sets the context data to be included with every log entry. Set to `undefined` to clear the context data.
   */
  setContext(context?: LogLayerContext): void;
  /**
   * Appends context data to the existing context data.
   */
  appendContext(context: Partial<LogLayerContext>): void;
  /**
   * Returns the context data to be included with every log entry.
   */
  getContext(): LogLayerContext;
  /**
   * Returns true if context data is present.
   */
  hasContextData(): boolean;
  /**
   * Clears the context data. If keys are provided, only those keys will be removed.
   * If no keys are provided, all context data will be cleared.
   */
  clearContext(keys?: string | string[]): void;
  /**
   * Called when a child logger is created. Use to manipulate context data between parent and child.
   */
  onChildLoggerCreated(params: OnChildLoggerCreatedParams): void;
  /**
   * Creates a new instance of the context manager with the same context data.
   */
  clone(): IContextManager;
}
/**
 * Log Level Manager callback function for when a child logger is created.
 */
interface OnChildLogLevelManagerCreatedParams {
  /**
   * The parent logger instance
   */
  parentLogger: ILogLayer<any>;
  /**
   * The child logger instance
   */
  childLogger: ILogLayer<any>;
  /**
   * The parent logger's log level manager
   */
  parentLogLevelManager: ILogLevelManager;
  /**
   * The child logger's log level manager
   */
  childLogLevelManager: ILogLevelManager;
}
/**
 * Interface for implementing a log level manager instance.
 *
 * Log level managers are responsible for managing log level settings across logger instances.
 * They control how log levels are inherited and propagated between parent and child loggers.
 *
 * If your log level manager needs to clean up resources (like parent-child references, memory, or external connections),
 * you can optionally implement the {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management | Disposable} interface.
 * LogLayer will automatically call the dispose method when the log level manager is replaced using `withLogLevelManager()`.
 *
 * @see {@link https://loglayer.dev/log-level-managers/creating-log-level-managers.html | Creating Log Level Managers Docs}
 */
interface ILogLevelManager {
  /**
   * Sets the minimum log level to be used by the logger. Only messages with
   * this level or higher severity will be logged.
   *
   * **When triggered:** Called when `logger.setLevel()` is invoked on a LogLayer instance.
   */
  setLevel(logLevel: LogLevelType): void;
  /**
   * Enables a specific log level.
   *
   * **When triggered:** Called when `logger.enableIndividualLevel()` is invoked on a LogLayer instance.
   */
  enableIndividualLevel(logLevel: LogLevelType): void;
  /**
   * Disables a specific log level.
   *
   * **When triggered:** Called when `logger.disableIndividualLevel()` is invoked on a LogLayer instance.
   */
  disableIndividualLevel(logLevel: LogLevelType): void;
  /**
   * Checks if a specific log level is enabled.
   *
   * **When triggered:** Called before every log method execution (e.g., `info()`, `warn()`, `error()`, `debug()`, `trace()`, `fatal()`, `raw()`, `metadataOnly()`, `errorOnly()`) to determine if the log should be processed. Also called when `logger.isLevelEnabled()` is invoked directly.
   */
  isLevelEnabled(logLevel: LogLevelType): boolean;
  /**
   * Enable sending logs to the logging library.
   *
   * **When triggered:** Called when `logger.enableLogging()` is invoked on a LogLayer instance.
   */
  enableLogging(): void;
  /**
   * All logging inputs are dropped and stops sending logs to the logging library.
   *
   * **When triggered:** Called when `logger.disableLogging()` is invoked on a LogLayer instance, or when a LogLayer instance is created with `enabled: false` in the configuration.
   */
  disableLogging(): void;
  /**
   * Called when a child logger is created. Use to manipulate log level settings between parent and child.
   *
   * **When triggered:** Called automatically when `logger.child()` is invoked, after the child logger is created and the parent's log level manager has been cloned. This allows the manager to establish relationships between parent and child loggers.
   */
  onChildLoggerCreated(params: OnChildLogLevelManagerCreatedParams): void;
  /**
   * Creates a new instance of the log level manager with the same log level settings.
   *
   * **When triggered:** Called automatically when `logger.child()` is invoked to create a new log level manager instance for the child logger. The cloned instance should have the same initial log level state as the parent, but can be modified independently (unless the manager implements shared state behavior).
   */
  clone(): ILogLevelManager;
}
/**
 * Input to the LogLayer transport shipToLogger() method.
 * @see {@link https://loglayer.dev/transports/creating-transports.html | Creating Transports Docs}
 */
interface LogLayerTransportParams extends LogLayerCommonDataParams {
  /**
   * The log level of the message
   */
  logLevel: LogLevelType;
  /**
   * The parameters that were passed to the log message method (eg: info / warn / debug / error)
   */
  messages: any[];
  /**
   * 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.
 * @see {@link https://loglayer.dev/transports/creating-transports.html | Creating Transports Docs}
 */
interface LogLayerTransport<LogLibrary = any> {
  /**
   * A user-defined identifier for the transport
   **/
  id?: string;
  /**
   * If false, the transport will not send logs to the logger.
   * Default is true.
   */
  enabled?: boolean;
  /**
   * Sends the log data to the logger for transport
   */
  shipToLogger(params: LogLayerTransportParams): any[];
  /**
   * Internal use only. Do not implement.
   * @param params
   */
  _sendToLogger(params: LogLayerTransportParams): void;
  /**
   * Returns the logger instance attached to the transport
   */
  getLoggerInstance(): LogLibrary;
}
/**
 * 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, 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  info(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  warn(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  error(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  debug(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  trace(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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(strings: TemplateStringsArray, ...values: any[]): LogReturnType<IsAsync>;
  fatal(...messages: MessageDataType[]): LogReturnType<IsAsync>;
  /**
   * 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<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): 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(): 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(): ILogBuilder<This, IsAsync>;
}
/**
 * Interface for implementing a LogLayer logger instance.
 * @see {@link https://loglayer.dev | LogLayer Documentation}
 */
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.
   *
   * 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.
   *
   * 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.
   *
   * 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.
   *
   * 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.
   *
   * 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.
   * 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<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, false>;
  /**
   * 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;
  /**
   * 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;
  /**
   * Calls child() and sets the prefix to be included with every log message.
   *
   * @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.
   *
   * Passing in an empty value / object will *not* clear the context.
   *
   * To clear the context, use {@link clearContext}.
   *
   * @see {@link https://loglayer.dev/logging-api/context.html | Context Docs}
   */
  withContext(context?: LogLayerContext): This;
  /**
   * Clears the context data. If keys are provided, only those keys will be removed.
   * If no keys are provided, all context data will be cleared.
   *
   * @see {@link https://loglayer.dev/logging-api/context.html | Context Docs}
   */
  clearContext(keys?: string | string[]): This;
  /**
   * Logs only the error object without a log message
   *
   * @see {@link https://loglayer.dev/logging-api/error-handling.html | Error Handling Docs}
   */
  errorOnly(error: any, opts?: ErrorOnlyOpts): void;
  /**
   * 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<M extends LogLayerMetadata>(metadata?: M, logLevel?: LogLevelType): LogReturnType<ContainsAsyncLazy<NonNullable<M>>>;
  /**
   * 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(options?: {
    raw?: boolean;
  }): LogLayerContext;
  /**
   * Creates a new instance of LogLayer but with the initialization
   * configuration and context data copied over.
   *
   * The copied context data is a *shallow copy*.
   *
   * @see {@link https://loglayer.dev/logging-api/child-loggers.html | Child Logging Docs}
   */
  child(): This;
  /**
   * Disables inclusion of context data in the print
   *
   * @see {@link https://loglayer.dev/logging-api/context.html#managing-context | Managing Context Docs}
   */
  muteContext(): This;
  /**
   * Enables inclusion of context data in the print
   *
   * @see {@link https://loglayer.dev/logging-api/context.html#managing-context | Managing Context Docs}
   */
  unMuteContext(): This;
  /**
   * Disables inclusion of metadata data in the print
   *
   * @see {@link https://loglayer.dev/logging-api/metadata.html#controlling-metadata-output | Controlling Metadata Output Docs}
   */
  muteMetadata(): This;
  /**
   * Enables inclusion of metadata data in the print
   *
   * @see {@link https://loglayer.dev/logging-api/metadata.html#controlling-metadata-output | Controlling Metadata Output Docs}
   */
  unMuteMetadata(): This;
  /**
   * Enables a specific log level
   *
   * @see {@link https://loglayer.dev/logging-api/basic-logging.html#enabling-disabling-logging | Enabling/Disabling Logging Docs}
   */
  enableIndividualLevel(logLevel: LogLevelType): This;
  /**
   * Disables a specific log level
   *
   * @see {@link https://loglayer.dev/logging-api/basic-logging.html#enabling-disabling-logging | Enabling/Disabling Logging Docs}
   */
  disableIndividualLevel(logLevel: LogLevelType): This;
  /**
   * Sets the minimum log level to be used by the logger. Only messages with
   * this level or higher severity will be logged.
   *
   * For example, if you setLevel(LogLevel.warn), this will:
   * Enable:
   * - warn
   * - error
   * - fatal
   * Disable:
   * - info
   * - debug
   * - trace
   *
   * @see {@link https://loglayer.dev/logging-api/basic-logging.html#enabling-disabling-logging | Enabling/Disabling Logging Docs}
   */
  setLevel(logLevel: LogLevelType): This;
  /**
   * Checks if a specific log level is enabled
   *
   * @see {@link https://loglayer.dev/logging-api/basic-logging.html#checking-if-a-log-level-is-enabled | Checking if a Log Level is Enabled Docs}
   */
  isLevelEnabled(logLevel: LogLevelType): boolean;
  /**
   * 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;
  /**
   * 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;
  /**
   * Returns a logger instance for a specific transport
   *
   * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
   */
  getLoggerInstance<Library>(id: string): Library | undefined;
  /**
   * Replaces all existing transports with new ones while preserving other logger configuration.
   *
   * Transport changes only affect the current logger instance. Child loggers
   * created before the change will retain their original transports, and
   * parent loggers are not affected when a child modifies its transports.
   *
   * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
   */
  withFreshTransports(transports: LogLayerTransport | Array<LogLayerTransport>): This;
  /**
   * Adds one or more transports to the existing transports.
   * If a transport with the same ID already exists, it will be replaced.
   *
   * Transport changes only affect the current logger instance. Child loggers
   * created before the change will retain their original transports, and
   * parent loggers are not affected when a child modifies its transports.
   *
   * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
   */
  addTransport(transports: LogLayerTransport | Array<LogLayerTransport>): This;
  /**
   * Removes a transport by its ID.
   *
   * Transport changes only affect the current logger instance. Child loggers
   * created before the change will retain their original transports, and
   * parent loggers are not affected when a child modifies its transports.
   *
   * @returns true if the transport was found and removed, false otherwise.
   *
   * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
   */
  removeTransport(id: string): boolean;
  /**
   * Replaces all existing plugins with new ones.
   *
   * When used with child loggers, it only affects the current logger instance
   * and does not modify the parent's plugins.
   *
   * @see {@link https://loglayer.dev/plugins/ | Plugins Docs}
   */
  withFreshPlugins(plugins: Array<LogLayerPlugin>): This;
  /**
   * Sets the context manager to use for managing context data.
   */
  withContextManager(manager: IContextManager): This;
  /**
   * Gets the context manager used by the logger.
   */
  getContextManager<M extends IContextManager = IContextManager>(): M;
  /**
   * Sets the log level manager to use for managing log levels.
   */
  withLogLevelManager(manager: ILogLevelManager): This;
  /**
   * Gets the log level manager used by the logger.
   */
  getLogLevelManager<M extends ILogLevelManager = ILogLevelManager>(): M;
  /**
   * Returns the configuration object used to initialize the logger.
   */
  getConfig(): {
    prefix?: string;
    enabled?: boolean;
    consoleDebug?: boolean;
    transport: LogLayerTransport | Array<LogLayerTransport>;
    plugins?: Array<LogLayerPlugin>;
    errorSerializer?: (err: any) => Record<string, any> | string;
    errorFieldName?: string;
    copyMsgOnOnlyError?: boolean;
    errorFieldInMetadata?: boolean;
    contextFieldName?: string;
    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.
   *
   * This method allows you to bypass the normal LogLayer API and directly specify
   * all aspects of a log entry including log level, messages, metadata, and error.
   * It's useful for scenarios where you need to log structured data that doesn't
   * fit the standard LogLayer patterns, or when integrating with external logging
   * 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<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.
 */
declare function resolveMessages(args: any[]): MessageDataType[];
//#endregion
export { ContainsAsyncLazy, ErrorOnlyOpts, IContextManager, ILogBuilder, ILogLayer, ILogLevelManager, LAZY_EVAL_ERROR, LAZY_SYMBOL, LazyEvalFailure, LazyLogValue, LogGroupConfig, LogGroupsConfig, LogLayerCommonDataParams, LogLayerContext, LogLayerData, LogLayerMetadata, LogLayerPlugin, LogLayerPluginParams, LogLayerPluginSchema, LogLayerTransport, LogLayerTransportParams, LogLevel, LogLevelPriority, LogLevelPriorityToNames, LogLevelType, LogReturnType, MessageDataType, OnChildLogLevelManagerCreatedParams, OnChildLoggerCreatedParams, PluginBeforeDataOutParams, PluginBeforeMessageOutParams, PluginShouldSendToLoggerParams, PluginTransformLogLevelParams, RawLogEntry, ResolveLazyResult, TaggedTemplateArgs, TaggedTemplateOrMessageArgs, countLazyValues, hasPromiseValues, isLazy, lazy, replacePromiseValues, resolveLazyValues, resolveMessages, resolvePromiseValues };