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

Shared utilities and types for loglayer packages.

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?: LogLevel;
    /**
     * 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;
}

/**
 * Input for the `onBeforeDataOut` plugin lifecycle method.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html#onbeforedataout | Creating Plugins}
 */
interface PluginBeforeDataOutParams {
    /**
     * Log level of the data
     */
    logLevel: LogLevelType;
    /**
     * The object containing metadata / context / error data. This
     * is `undefined` if there is no object with data.
     */
    data?: Record<string, any>;
}
/**
 * Input for the `shouldSendToLogger` plugin lifecycle method.
 * @see {@link https://loglayer.dev/plugins/creating-plugins.html#shouldsendtologger | Creating Plugins}
 */
interface PluginShouldSendToLoggerParams {
    /**
     * 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 object containing metadata / context / error data. This
     * is `undefined` if there is no object with data.
     */
    data?: Record<string, any>;
}
/**
 * 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[];
}
/**
 * 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 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): Record<string, any> | 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: Record<string, any>, loglayer: ILogLayer) => Record<string, any> | 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: Record<string, any>, loglayer: ILogLayer) => Record<string, any> | null | undefined;
}

/**
 * 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;
    /**
     * The child logger instance
     */
    childLogger: ILogLayer;
    /**
     * The parent logger's context manager
     */
    parentContextManager: IContextManager;
    /**
     * The child logger's context manager
     */
    childContextManager: IContextManager;
}
/**
 * Interface for implementing a context manager instance.
 * @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?: Record<string, any>): void;
    /**
     * Appends context data to the existing context data.
     */
    appendContext(context: Record<string, any>): void;
    /**
     * Returns the context data to be included with every log entry.
     */
    getContext(): Record<string, any>;
    /**
     * Returns true if context data is present.
     */
    hasContextData(): boolean;
    /**
     * 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;
}
/**
 * Input to the LogLayer transport shipToLogger() method.
 * @see {@link https://loglayer.dev/transports/creating-transports.html | Creating Transports Docs}
 */
interface LogLayerTransportParams {
    /**
     * 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[];
    /**
     * Object data such as metadata, context, and / or error data
     */
    data?: Record<string, any>;
    /**
     * If true, the data object is included in the message parameters
     */
    hasData?: boolean;
}
/**
 * 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.
 * @see {@link https://loglayer.dev | LogLayer Documentation}
 */
interface ILogBuilder {
    /**
     * Sends a log message to the logging library under an info log level.
     */
    info(...messages: MessageDataType[]): void;
    /**
     * Sends a log message to the logging library under the warn log level
     */
    warn(...messages: MessageDataType[]): void;
    /**
     * Sends a log message to the logging library under the error log level
     */
    error(...messages: MessageDataType[]): void;
    /**
     * Sends a log message to the logging library under the debug log level
     */
    debug(...messages: MessageDataType[]): void;
    /**
     * Sends a log message to the logging library under the trace log level
     */
    trace(...messages: MessageDataType[]): void;
    /**
     * Sends a log message to the logging library under the fatal log level
     */
    fatal(...messages: MessageDataType[]): void;
    /**
     * Specifies metadata to include with the log message
     *
     * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
     */
    withMetadata(metadata?: Record<string, any>): ILogBuilder;
    /**
     * 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;
    /**
     * 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;
    /**
     * 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;
}
/**
 * Interface for implementing a LogLayer logger instance.
 * @see {@link https://loglayer.dev | LogLayer Documentation}
 */
interface ILogLayer extends ILogBuilder {
    /**
     * 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): ILogLayer;
    /**
     * 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?: Record<string, any>): ILogLayer;
    /**
     * Clears the context data.
     *
     * @see {@link https://loglayer.dev/logging-api/context.html | Context Docs}
     */
    clearContext(): void;
    /**
     * Specifies metadata to include with the log message
     *
     * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
     */
    withMetadata(metadata?: Record<string, any>): ILogBuilder;
    /**
     * 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;
    /**
     * 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
     *
     * @see {@link https://loglayer.dev/logging-api/metadata.html | Metadata Docs}
     */
    metadataOnly(metadata?: Record<string, any>, logLevel?: LogLevelType): void;
    /**
     * Returns the context used
     *
     * @see {@link https://loglayer.dev/logging-api/context.html | Context Docs}
     */
    getContext(): Record<string, any>;
    /**
     * 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(): ILogLayer;
    /**
     * Disables inclusion of context data in the print
     *
     * @see {@link https://loglayer.dev/logging-api/context.html#managing-context | Managing Context Docs}
     */
    muteContext(): ILogLayer;
    /**
     * Enables inclusion of context data in the print
     *
     * @see {@link https://loglayer.dev/logging-api/context.html#managing-context | Managing Context Docs}
     */
    unMuteContext(): ILogLayer;
    /**
     * 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(): ILogLayer;
    /**
     * 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(): ILogLayer;
    /**
     * 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): ILogLayer;
    /**
     * 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): ILogLayer;
    /**
     * 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): ILogLayer;
    /**
     * 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(): ILogLayer;
    /**
     * 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(): ILogLayer;
    /**
     * 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.
     * When used with child loggers, it only affects the current logger instance
     * and does not modify the parent's transports.
     *
     * @see {@link https://loglayer.dev/logging-api/transport-management.html | Transport Management Docs}
     */
    withFreshTransports(transports: LogLayerTransport | Array<LogLayerTransport>): ILogLayer;
    /**
     * 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>): ILogLayer;
    /**
     * Sets the context manager to use for managing context data.
     */
    withContextManager(manager: IContextManager): ILogLayer;
    /**
     * Gets the context manager used by the logger.
     */
    getContextManager<M extends IContextManager = IContextManager>(): M;
}

export { type ErrorOnlyOpts, type IContextManager, type ILogBuilder, type ILogLayer, type LogLayerPlugin, type LogLayerPluginParams, type LogLayerTransport, type LogLayerTransportParams, LogLevel, LogLevelPriority, LogLevelPriorityToNames, type LogLevelType, type MessageDataType, type OnChildLoggerCreatedParams, type PluginBeforeDataOutParams, type PluginBeforeMessageOutParams, type PluginShouldSendToLoggerParams };