@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"
}
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: LogLevel;
    /**
     * 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: LogLevel;
    /**
     * 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: LogLevel;
    /**
     * 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: LogLevel;
    /**
     * 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?: LogLevel): 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;
    /**
     * 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, type MessageDataType, type OnChildLoggerCreatedParams, type PluginBeforeDataOutParams, type PluginBeforeMessageOutParams, type PluginShouldSendToLoggerParams };