:knot: log

Log messages in the terminal and browser

Contents

• What is this?
• Why this package?
• Install
• Use
• API
  • logger
  • createLogger
  • logLevels
  • Reporter
  • BaseReporter
  • FancyReporter
• Types
  • Logger
  • Create
  • InputLogObject
  • Inspect
  • InspectOptions
  • LogFormatOptions
  • LogFunction
  • LogFunctions
  • LogLevel
  • LogLevelMap
  • LogLevelOption
  • LogLevelType
  • LogObject
  • LogType
  • LogTypeFunctions
  • LogTypeMap
  • LoggerOptions
  • ReportersOption
  • WithDefaults
  • WithTag
  • Write
  • WriteStream
• Contribute

What is this?

This is a small, but useful, library for logging messages in the terminal and browser consoles.

Colorful messages can be logged in the terminal and browser consoles that support ANSI colors.

Why this package?

:ok_hand: Easy to use
:electric_plug: Pluggable reporters
:computer: Consistent terminal experience
:bookmark: Tag support
:globe_with_meridians: Browser support

Install

This package is ESM only.

In Node.js with yarn:

yarn add @flex-development/log

In Deno with esm.sh:

import { createLogger } from 'https://esm.sh/@flex-development/log'

In browsers with esm.sh:

<script type="module">
  import { logger } from 'https://esm.sh/@flex-development/log'
</script>

With bun:

bun add @flex-development/log

Use

import { logger } from '@flex-development/log'

logger.info('Using @flex-development/log 5.0.0')
logger.start('Building project...')
logger.warn('A new version of @flex-development/log is available: 5.0.1')
logger.success('Project built!')
logger.fail(new Error('This is an example error. Everything is fine!'))

Will display in the terminal:

API

This package exports the following identifiers:

• logger
• createLogger
• logLevels
• Reporter
• BaseReporter
• FancyReporter

The default export is logger.

logger

(Logger) The default, pre-configured logger. Logs are written using the FancyReporter.

createLogger([options])

Create a new logger.

Parameters

• options (LogLevelOption | LoggerOptions, optional) — Log level or configuration options

Returns

(Logger) Logger object

logLevels

(Readonly<Record<LogType, LogLevel>>) Map where each key is a log type and each value is a log level.

Reporter

Log reporter (abstract class).

Properties

• logger (Logger) — the logger this reporter writes to

Methods

init(logger)

Initialize the reporter.

Parameters

• logger (Logger) — the logger this reporter writes to

Returns

(this) this reporter

abstract report(info)

Define how a log message is processed and displayed by this reporter.

Parameters

• info (LogObject) — the log information to process

Returns

(undefined | void) Nothing.

BaseReporter

Log reporter with basic utilities (abstract class).

Extends

• Reporter

FancyReporter

Fancy log reporter (class).

Extends

• BaseReporter

Types

This package is fully typed with TypeScript.

Logger

Logger API (TypeScript interface).

Extends

• LogFunctions

Properties

• browser (boolean, readonly) — whether the logger is operating in a browser environment
• get color(): boolean — whether color logs are enabled
• set color(color: boolean | null | undefined) — enable or disable color log. color will be disabled if not supported
  • color (boolean | null | undefined) — color logs enabled?
• get colors(): Colors — get a colorizer based on the current color configuration
• create (Create) — create a new logger, inheriting options from the current instance, with possible overrides
• defaults (InputLogObject) — properties to apply to all logs, regardless of log type or level
• eol (string) — the character, or characters, used to signify the end of a line
• format (LogFormatOptions) — formatting options
• get level(): LogLevel — get the current log level
• set level(level: LogLevelOption | null | undefined) — set the maximum log level to output
  • level (LogLevelOption | null | undefined) — maximum log level (inclusive)
• levels (Readonly<LogLevelMap>, readonly) — log level map
• reporters (Set<Reporter>, readonly) — list of reporter instances used to handle and output log messages
• stderr (WriteStream) — the writeable stream for standard error output
• stdout (WriteStream) — the writeable stream for standard output
• types (Record<LogType, InputLogObject>) — record, where each key is a LogType and each value is an InputLogObject defining the configuration for the log type
• unicode (boolean) — whether unicode is supported
• withDefaults (WithDefaults) — create a new logger with the specified default log object properties
• withTag (WithTag) — create a new logger with the specified tag. the tag will be included in any logs sent from the new logger

Create

Create a new logger, inheriting options from the current instance, with possible overrides (TypeScript interface).

Plain objects (i.e. options.format, options.types) are merged recursively.

Parameters

• options (LoggerOptions, optional) — overrides for the new logger

Returns

(Logger) The new logger.

InputLogObject

Input log data object (TypeScript interface).

Properties

• additional? (string | string[], optional) — an additional line, or list of lines, to be logged with the message
• args? (unknown[], optional) — format arguments
• color? (Color, optional) — color associated with the log
• date? (Date, optional) — timestamp
• format? (LogFormatOptions, optional) — format options
• icon? (string, optional) — icon to display
• level? (LogLevelOption, optional) — log level
• message? (unknown, optional) — log message; inserted into args as the first format argument if defined
• stack? (string, optional) — stack trace
• tag? (string, optional) — a string to categorize or identify the log
• type? (LogType, optional) — log type

Inspect

Use util.inspect on value and print its string representation (TypeScript type).

Parameters

• value (unknown) — the thing to inspect
• options (InspectOptions, optional) — inspection options

Returns

(undefined) Nothing.

InspectOptions

Options for inspecting a value (TypeScript interface).

Extends

• Omit<util.InspectOptions, 'colors'>

Properties

• colors (boolean, optional) — whether to use color

LogFormatOptions

Log formatting options (TypeScript interface).

Extends

• InspectOptions

Properties

• badge? (boolean, optional) — whether to display the log type as a badge
• columns? (number, optional) — the maximum number of columns to output
• date? (boolean, optional) — whether to include timestamp information in log messages
• icon? (boolean, optional) — whether to display the icon associated with the log

LogFunction

Send a message to all reporter instances (TypeScript interface).

Overloads

• (message: InputLogObject | string, ...args: unknown[]) => undefined | void
• (message: unknown, ...args: unknown[]) => undefined | void

Parameters

• message (InputLogObject | unknown) — the message to write
• ...args (unknown[], optional) — message arguments

Returns

(undefined | void) Nothing.

LogFunctions

Log formatting options (TypeScript interface).

Extends

• LogTypeFunctions

Properties

• inspect (Inspect) — use util.inspect on a value and print its string representation

LogLevel

Union of log levels (TypeScript type).

To register custom log levels, augment LogLevelMap. They will be added to the union automatically.

type LogLevel = LogLevelMap[keyof LogLevelMap]

LogLevelMap

Registry of log levels (TypeScript interface).

interface LogLevelMap {/* see code */}

When developing extensions that use additional levels, augment LogLevelMap to register custom log levels:

declare module '@flex-development/log' {
  interface LogLevelMap {
    box: 3
  }
}

LogLevelOption

Union of log level options (TypeScript type).

type LogLevelOption = LogLevel | LogLevelType

LogLevelType

Union of log level types (TypeScript type).

To register custom log level types, augment LogLevelMap. They will be added to the union automatically.

type LogLevelType = Extract<keyof LogLevelMap, string>

LogObject

Log data object (TypeScript interface).

Extends

• InputLogObject

Properties

• additional? (string[], optional) — additional lines to be logged with the message
• args (unknown[]) — format arguments
• date (Date) — timestamp
• level (LogLevel) — log level
• message? (null | undefined, optional) — log message
• type (LogType) — log type

LogType

Union of log types (TypeScript type).

To register custom log types, augment LogTypeMap. They will be added to the union automatically.

type LogType = LogTypeMap[keyof LogTypeMap]

LogTypeFunctions

Dictionary of log type functions (TypeScript type).

To register custom log type functions, augment LogTypeMap. They will be added to the union automatically.

type LogTypeFunctions = { [T in LogType]: LogFunction }

LogTypeMap

Registry of log types (TypeScript interface).

interface LogTypeMap {/* see code */}

When developing extensions that use additional types, augment LogTypeMap to register custom log types:

declare module '@flex-development/log' {
  interface LogTypeMap {
    box: 'box'
  }
}

LoggerOptions

Logger configuration options (TypeScript interface).

Properties

• defaults? (InputLogObject, optional) — properties to apply to all logs, regardless of log type or level. defaults can be overridden per log type using types
• eol? (string, optional) — the character, or characters, used to signify the end of a line
• color? (Color) — color associated with the log
• format? (LogFormatOptions, optional) — formatting options
• level? (LogLevelOption, optional) — the maximum log level to output
• reporters? (ReportersOption, optional) — reporter instances used to handle and output log messages
• stderr? (WriteStream, optional) — the writeable stream for standard error output
• stdout? (WriteStream, optional) — the writeable stream for standard output
• types? (Partial<Record<LogType, InputLogObject>>, optional) — record, where each key is a LogType and each value is an InputLogObject defining the configuration for the log type

ReportersOption

Union of values used to configure reporters (TypeScript type).

type ReportersOption =
  | Reporter
  | Set<Reporter | false | null | undefined>
  | readonly (Reporter | false | null | undefined)[]

Write

Write data to the stream (TypeScript type).

Parameters

• buffer (string) — the data to write

Returns

(boolean | undefined | void) true if all data was flushed successfully, false if all or part of the data was queued in user memory, or nothing.

WithDefaults

Create a new logger with the specified default log object properties (TypeScript interface).

Parameters

• defaults (InputLogObject, optional) — default properties to apply to any log reported from the new logger

Returns

(Logger) The new logger.

WithTag

Create a new logger with the specified tag (TypeScript interface).

Parameters

• tag (string) — the tag to include in each log reported from the new logger
• separator (string, optional) — the string to used separate tags
  • default: ':'

Returns

(Logger) The new logger.

WriteStream

Write stream API (TypeScript interface).

Properties

• columns? (number, optional) — number of columns the tty currently has
• write (Write) — write data to the stream

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.