@epdoc/console-logger

console-logger

A simple, customizable console logger for Node.js with terminal color support and method chaining.

Features

• Multiple log levels (trace, debug, verbose, info, warn, error)
• Customizable output formatting, including colors and styles
• Chainable API - log.h1('header').info('plain text')
• Can include elapsed time in log messages - log.elapsed().info('Finished')
• Mock mode for testing - log.mock.enable = true; log.info('test');

Installation

npm install @epdoc/console-logger

Usage

import { Logger } from '@epdoc/console-logger';

// Declare one global logger instance and import it wherever you need to log
const log:LoggerInstance = new Logger({enableStyles:true});

log.info('Hello, world!');

Type Safety for Dynamic Methods

When creating a logger instance, we recommend using:

const log: LoggerInstance = new Logger();

instead of:

const log = new Logger();

The LoggerInstance type includes all the dynamically added style methods (like h1, h2, text, etc.) that are not part of the original Logger class definition. These methods are added at runtime, but TypeScript needs to know about them at compile time.

By using LoggerInstance, you get full type safety and autocompletion for all logger methods, including the dynamically added ones. This approach combines the flexibility of runtime method creation with the benefits of static typing.

Runtime loading of methods also allows for custom styles to be added, which is demonstrated in the Custom Styles section below.

Changing Log Level

The default log level is LogLevel.info. You can change the log level in the constructor or at any time using the setLevel method.

log.setLevel(LogLevel.debug);
log.debug('Now this debug message will be shown');

Using Prefixes

You can enable level and time prefixes when initializing the logger:

const log:LoggerInstance = new Logger({ levelPrefix: true, timePrefix: 'local' });
log.info('Hello'); // Outputs: "14:30:45 [INFO] Hello"

The timePrefix can be one of the following values:

• 'local' - local time
• 'utc' - UTC time
• 'elapsed' - elapsed time since application start
• false - no time prefix

Chaining Methods

A line of output can be built up using method chaining, and is only output when one of the methods trace, debug, verbose, info or output are called.

log.text('User:').value('John Doe').info('logged in');

Using Elapsed Time Suffic

The elapsed time since application start, and the time since the last call to elapsed() can be appended to the output.

log.h1('Starting operation').info();
// ... some code ...
log.tab().text('Operation completed').elapsed().info();

Using Indentation

log.indent().info('This is indented by the default 2 spaces');
log.tab().text('This is also indented by 2 spaces').info();
log.indent('>>').info('This is indented by ">> "');
log.indent(4).info('This is indented by 4 spaces');
log.tab(2).text('This is also indented by 4 spaces').info();
log.tab(2).info('This is also indented by 4 spaces');
log.info('This is not indented');

Using Headers

log.h1('Big Header').info('This is a big header');
log.h2('Smaller Header').info('This is a smaller header');

Lines for Testing or just because

If you want to collect lines for testing or just because, you can use the setKeepLines method or initialize the logger with keepLines: true.

log.setKeepLines(true);
log.info('Test message');
log.info('Test message 2');
console.log(log.lines); // ['Test message', 'Test message 2']

Custom Styles

You can provide your own custom styles when initializing the logger. Here's how:

• Define your custom styles:

import { StyleDef, Color } from 'your-logger-package';
const customStyles: Record<string, StyleDef> = {
success: { fg: Color.green },
warning: { fg: Color.yellow },
critical: { fg: Color.red, bg: Color.white },
// Add more custom styles as needed
};

• Pass the custom styles when creating a new logger instance:

const log:LoggerInstance = new Logger({
level: LogLevel.info,
styles: customStyles
});

• Use your custom styles in your logs:

log.success('Operation completed successfully');
log.warning('Proceed with caution');
log.critical('System failure detected');

API Reference

Logger Class

• constructor({level: LogLevel = LogLevel.info, keepLines: boolean = false, timePrefix: 'local' | 'utc' | 'elapsed' | false = 'local', levelPrefix: boolean = false})
• setLevel(level: LogLevel | string): this
• getLevel(): LogLevel
• isEnabledFor(level: LogLevel): boolean
• setStyle(style: Style): this
• getStyle(): Style
• setLevelPrefix(val: boolean): this
• setTimePrefix(val: TimePrefix): this
• setElapsed(val: Elapsed): this
• setKeepLines(val: boolean): this
• elapsed(): this
• clearLines(): this
• clearLine(): this

Methods for Pre-formatted Text, using declared styles

• text(...args: any[]): this
• data(arg: any): this
• h1(...args: any[]): this
• h2(...args: any[]): this
• h3(...args: any[]): this
• label(...args: any[]): this
• action(...args: any[]): this
• value(...args: any[]): this
• path(...args: any[]): this
• critical(...args: any[]): this
• fatal(...args: any[]): this

Support methods for Pre-formatted Text, regardless of styles

• data(arg: any): this
• stylize(style: StyleName | StyleDef, ...args: any[]): this
• tab(val: Integer = 2): this
• indent(n: Integer = 2): this

Methods for Output

• trace(...args: any[]): this
• debug(...args: any[]): this
• verbose(...args: any[]): this
• info(...args: any[]): this
• warn(...args: any[]): this
• error(...args: any[]): this
• output(...args: any[]): this

LogLevel Enum

• trace = 1
• debug = 3
• verbose = 5
• info = 7
• warn = 8
• error = 9

License

This project is licensed under the MIT License.