@paulshryock/logger/dist/index.d.ts

PSR-3-compliant logger for Node.js.

import { CommandLine } from '@paulshryock/abstractions';

/**
 * String or object implementing toString().
 *
 * @since unreleased
 */
export interface Stringable {
	/**
	 * Returns a string representing the object.
	 *
	 * @return {string}
	 *
	 * @link   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
	 *
	 * @since  unreleased
	 */
	toString(): string;
}
/**
 * Logging context for logged messages.
 *
 * @since unreleased
 */
export interface LogContext extends Record<string, Stringable> {
	exception?: Error;
}
/**
 * Describes log levels.
 */
export declare enum LogLevel {
	EMERGENCY = "emergency",
	ALERT = "alert",
	CRITICAL = "critical",
	ERROR = "error",
	WARNING = "warning",
	NOTICE = "notice",
	INFO = "info",
	DEBUG = "debug"
}
/**
 * Describes a logger instance.
 *
 * The message MUST be a string or object implementing toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context object can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Error instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 *
 * @since unreleased
 */
export interface Logger {
	/**
	 * System is unusable.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	emergency(message: Stringable, context: LogContext): void;
	/**
	 * Action must be taken immediately.
	 *
	 * Example: Entire website down, database unavailable, etc. This should
	 * trigger the SMS alerts and wake you up.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	alert(message: Stringable, context: LogContext): void;
	/**
	 * Critical conditions.
	 *
	 * Example: Application component unavailable, unexpected exception.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	critical(message: Stringable, context: LogContext): void;
	/**
	 * Runtime errors that do not require immediate action but should typically
	 * be logged and monitored.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	error(message: Stringable, context: LogContext): void;
	/**
	 * Exceptional occurrences that are not errors.
	 *
	 * Example: Use of deprecated APIs, poor use of an API, undesirable things
	 * that are not necessarily wrong.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	warning(message: Stringable, context: LogContext): void;
	/**
	 * Normal but significant events.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	notice(message: Stringable, context: LogContext): void;
	/**
	 * Interesting events.
	 *
	 * Example: User logs in, SQL logs.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	info(message: Stringable, context: LogContext): void;
	/**
	 * Detailed debug information.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	debug(message: Stringable, context: LogContext): void;
	/**
	 * Logs with an arbitrary level.
	 *
	 * @param  {LogLevel}   level   Logging level.
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 * @throws {TypeError}
	 *
	 * @since  unreleased
	 */
	log(level: LogLevel, message: Stringable, context: LogContext): void;
}
/**
 * Describes a logger-aware instance.
 *
 * @since unreleased
 */
export interface LoggerAware {
	/**
	 * Sets a logger instance on the object.
	 *
	 * @param  {Logger} logger The logger to give this object.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	setLogger(logger: Logger): void;
}
/**
 * Describes a null logger instance.
 *
 * The message MUST be a string or object implementing toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context object can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Error instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 *
 * @since unreleased
 */
export declare abstract class NullLogger implements Logger {
	/**
	 * System is unusable.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	emergency(message: Stringable, context?: LogContext): void;
	/**
	 * Action must be taken immediately.
	 *
	 * Example: Entire website down, database unavailable, etc. This should
	 * trigger the SMS alerts and wake you up.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	alert(message: Stringable, context?: LogContext): void;
	/**
	 * Critical conditions.
	 *
	 * Example: Application component unavailable, unexpected exception.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	critical(message: Stringable, context?: LogContext): void;
	/**
	 * Runtime errors that do not require immediate action but should typically
	 * be logged and monitored.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	error(message: Stringable, context?: LogContext): void;
	/**
	 * Exceptional occurrences that are not errors.
	 *
	 * Example: Use of deprecated APIs, poor use of an API, undesirable things
	 * that are not necessarily wrong.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	warning(message: Stringable, context?: LogContext): void;
	/**
	 * Normal but significant events.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	notice(message: Stringable, context?: LogContext): void;
	/**
	 * Interesting events.
	 *
	 * Example: User logs in, SQL logs.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	info(message: Stringable, context?: LogContext): void;
	/**
	 * Detailed debug information.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 *
	 * @since  unreleased
	 */
	debug(message: Stringable, context?: LogContext): void;
	/**
	 * Logs with an arbitrary level.
	 *
	 * @param  {LogLevel}   level   Logging level.
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 * @throws {TypeError}
	 *
	 * @since  unreleased
	 */
	abstract log(level: LogLevel, message: Stringable, context: LogContext): void;
	/**
	 * Interpolates some logging context into a log message.
	 *
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {string}             Interpolated message.
	 *
	 * @since  unreleased
	 */
	protected interpolate(message: Stringable, context: LogContext): string;
}
/**
 * Describes a command line logger instance.
 *
 * The message MUST be a string or object implementing toString().
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 *
 * The context object can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Error instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 *
 * @since unreleased
 */
export declare class CommandLineLogger extends NullLogger implements Logger {
	#private;
	/**
	 * Constructs a command line logger.
	 *
	 * @param {CommandLine} commandLine Command line abstraction.
	 *
	 * @since unreleased
	 */
	constructor(commandLine?: CommandLine);
	/**
	 * Logs with an arbitrary level.
	 *
	 * @param  {LogLevel}   level   Logging level.
	 * @param  {Stringable} message Message to log.
	 * @param  {LogContext} context Logging context for the logged message.
	 * @return {void}
	 * @throws {TypeError}
	 *
	 * @since  unreleased
	 */
	log(level: LogLevel, message: Stringable, context?: LogContext): void;
}

export {};