@notera/terminal v1.0.0

Notera Terminal Transport

This package provides a customizable terminal transport for the Notera package. This transport atomically writes to stdout like console.log, which makes it ideal for development purposes.

Installation

• npm install @notera/core @notera/terminal
• yarn add @notera/core @notera/terminal

Usage

import notera from '@notera/core';
import terminalTransport from '@notera/terminal;

const logger = notera({
    levels: {
        err: 0,
        info: 1,
    },
});

logger.addTransport(terminalTransport({
    // Options
}))

logger.ctx('SERVER').info('Something is up', { some: 'meta' });

Options

Terminology

• Segment - Each logging line can be divided into segments: date, ctx, msg, level and meta.
• Entry - A logging entry generated by a call to one of the log functions in the Notera package.

type Opts<LevelsT extends string> = {
	// Disable colored/styled output. Defaults to false
	disableStyle?: boolean;

	// Never use more than one line for one log entry. This will hide
	// stack traces when logging errors, and only show the message
	// instead. Defaults to false
	singleLine?: boolean;

	// Colors to use for the different logging levels
	colors?: {
		[K in LevelsT]?: Style;
	};

	stream?: Writable;

	// Configuration used when handling each segment. Please see the
	// section "Configuring segments" for more information on how to
	// configure these.
	segment?: {
		time?: SegmentConfig<LevelsT>;
		ctx?: SegmentConfig<LevelsT>;
		level?: SegmentConfig<LevelsT>;
		msg?: SegmentConfig<LevelsT>;
		meta?: SegmentConfig<LevelsT>;
	};
};

type SegmentConfig<LevelsT extends string> = {
	// How this segment should be ordered amongst the other, defaults to 1
	index?: number;

	// Default false
	disabled?: boolean;

	// Function to format the segment
	format?: ((entry: LogEntry<LevelsT>, opts: Opts<LevelsT>) => string) | null;

	// Function to determine the style of this segment this specific log entry.
	style?:
		| Style
		| ((entry: LogEntry<LevelsT>, opts: Opts<LevelsT>) => Style)
		| null;
};

Configuring segments

Example configuration:

{
    disableStyle: false,
    singleLine: false,
    colors: {
        emerg: 'red',
        alert: 'magenta',
        crit: 'red',
        err: 'red',
        warning: 'yellow',
        notice: 'white',
        info: 'green',
        debug: 'cyan',
    },
    segment: {
        time: {
            index: 10,
            format: _ => new Date().toISOString(),
            style: 'gray',
        },
        ctx: {
            index: 20,
            format: ({ ctx }) => ` [${ctx}]`,
        },
        level: {
            index: 30,
            style: ({ level }, opts) => opts.colors[level],
            format: ({ level }) => ' ' + level.toUpperCase(),
        },
        msg: {
            index: 40,
            format: ({ msg }) => `: ${msg}`,
        },
        meta: {
            index: 60,
            format: ({ meta }, opts) =>
                ` | ${JSON.stringify(meta, ...(opts.singleLine ? [] : [null, 2]))}`,
            style: 'gray',
        },
    },
};

Changing a segment

To change segment settings, you can simply overwrite them. Note that the settings will be merged with the default settings at feature-level. See the configuration examples below.

const config = {
    // ...
    segment: {
        ctx: {
            // Turns off formatting for the 'ctx' segment. Resulting in a simple
            // append from the previous segment.
            format: null,

            // Reset the default style of the 'ctx' segment
            style: null,

            // Reorder the 'ctx' segment to be placed after all other segments
            index: 100,
        },
    },
};

Disable a segment

const config = {
    segment: {
        ctx: {
            disabled: true,
        },
    },
};

Colors

This package is using ansi-styles under the hood to colorize the terminal output. Please refer to their readme to see what colors are available.