@toreda/log/dist/log.d.ts

Lightweight TypeScript logger with flexible custom transports.

import { LogOptionsGlobal } from './log/options/global';
import { LogOptionsGroup } from './log/options/group';
import { Expand } from '@toreda/types';
import { LogStateGlobal } from './log/state/global';
import { LogStateGroup } from './log/state/group';
import { Transport } from './transport';
/**
 * Main log class holding attached transports and internal state
 * data, and logging configuration.
 */
export declare class Log {
    /** Serializable shared state data */
    readonly globalState: LogStateGlobal;
    /** Serializable internal state data */
    readonly groupState: LogStateGroup;
    constructor(options?: LogOptionsGroup | LogOptionsGlobal);
    /**
     * Enable global console logging for development and debugging.
     */
    activateDefaultConsole(level?: number): void;
    deactivateDefaultConsole(): void;
    /**
     * Sets the level of the default console to the level
     * of the log.
     */
    resetLevelDefaultConsole(): void;
    setLevelDefaultConsole(level: number): void;
    enableLevelDefaultConsole(level: number): void;
    disableLevelDefaultConsole(level: number): void;
    /**
     * Attempt to make new log group with target id. Does not
     * overwrite existing groups.
     * @param id	 		id of new log.
     * @returns 			The new log if successful or null if it fails.
     */
    makeLog(id: '', options?: MakeLogOptions): null;
    makeLog(id: string, options?: MakeLogOptions): Log;
    /**
     * Add transport to log.
     * @param transportData		Transport to add to log.
     */
    addTransport(transportData: Transport | TransportArgs): boolean;
    getTransport(transportId: string): Transport | null;
    /**
     * Remove transport from target group, or from the 'all' group if
     * id is null.
     * @param transport
     */
    removeTransport(transport: Transport | null): boolean;
    /**
     * Remove transport matching target id from target group if
     * both the group exists and the transport is in the group.
     * @param transportId
     */
    removeTransportById(transportId: string): boolean;
    /**
     * Remove multiple transports in one call by providing an array
     * of log transports to remove from this group.
     * @param transports
     */
    removeTransports(transports: Transport[]): boolean;
    /**
     * Remove matching transports from all groups. Expensive call not suitable to
     * use generally, but available for specific cases where transports must be removed
     * and may exist in multiple unknown groups. Prefer to use use `removeTransport` or
     * `removeGroupTransport` when possible.
     * @param transport
     */
    removeTransportEverywhere(transport: Transport): boolean;
    /**
     * All Logs become disabled without changing
     * the state of each log individually.
     */
    enforceGlobalDisable(): void;
    /**
     * All Logs become enabled without changing the
     * state of each log individually.
     */
    enforceGlobalEnable(): void;
    /**
     * Both global enable and disable are turned
     * off. Logs rely on their own setting.
     */
    useGroupEnable(): void;
    /**
     * Enable log.
     */
    enable(): void;
    /**
     * Disable log.
     */
    disable(): void;
    /**
     * Change global log level. Individual group levels
     * are used instead of global level when they are set.
     * @param level
     */
    setGlobalLevel(level: number): void;
    /**
     * Add a level flag to the global log level without
     * affecting other global level flags. Has no effect
     * if target level flag is already enabled.
     * @param level
     */
    enableGlobalLevel(level: number): void;
    /**
     * Add multiple flags to global log level. Performs
     * sanity checks on each provided level and discards
     * invalid values.
     * @param levels
     */
    enableGlobalLevels(levels: number[]): void;
    disableGlobalLevel(level: number): void;
    disableGlobalLevels(levels: number[]): void;
    /**
     * Set log level for target group.
     * @param level
     * @param id
     */
    setGroupLevel(level: number): void;
    enableGroupLevel(level: number): void;
    enableGroupLevels(levels: number[]): void;
    disableGroupLevel(level: number): void;
    disableGroupLevels(levels: number[]): void;
    /**
     * Create structured log message. Provided as a call argument
     * during transport execution.
     * @param ts			UTC timestamp when msg was created.
     * @param level			Level bitmask msg was logged with.
     * @param msg			Msg that was logged.
     */
    private createMessage;
    private stringifyMessage;
    /**
     * Determine whether group transport can execute target log
     * message. Checks msg log level against global log level,
     * group log level, and transport log level.
     * @param transport
     * @param globalLevel
     * @param msgLevel
     */
    private canExecute;
    /**
     * Log message to default group.
     * @param msgLevel
     * @param msg
     */
    log(msgLevel: number, ...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Trigger an error-level log message for no specific group (global).
     * @param msg
     */
    error(...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Trigger a warn-level log message for no specific group (global).
     * @param msg
     */
    warn(...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Trigger an info-level log message for no specific group (global).
     * @param args
     */
    info(...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Trigger a -level log message for no specific group (global).
     * @param msg
     */
    debug(...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Trigger a trace-level log message for no specific group (global).
     * @param args
     */
    trace(...msg: unknown[]): Promise<boolean | LogResult>;
    /**
     * Clear all transports from this group.
     */
    clear(): void;
    /**
     * Clear all transports from all groups.
     */
    clearAll(): void;
    /**
     * Remove all groups except the initial group.
     * Clear all transport from the initial group.
     */
    reset(): Log;
}
declare type LogResult = Record<string, boolean | Error>;
declare type MakeLogOptions = Expand<Omit<LogOptionsGroup, 'state' | 'id' | 'parent' | 'path'>>;
declare type TransportArgs = ConstructorParameters<typeof Transport>[0];
export {};