Logion

Logion allows you to output beautiful logs to a console (TTY) - from different parts of the program - use separators, indents, spinners and style your text.

Install

Install via yarn add logion | npm install logion.

Usage

Create instance:

import Logion from 'logion';

const logger = new Logion(opts);

Logion comes with an easy to use composable API that supports chaining:

logger
  .text('Hello World!')
  .newline(2)
  .text('Good job', 'success')
  .separate()
  .line('One liner')
  .spinner('oh', 'Beatifull spinner');

API

logion

• logion
  • module.exports ⏏
    • static
      • .Logion
        • new exports.Logion(options)
        • .width ⇒ number
        • .height ⇒ number
        • .disabled ⇒ boolean
        • .paused ⇒ boolean
        • .styleNames ⇒ object
        • .newline([num], [force], [identifier]) ⇒ Instance
        • .indent([num], [identifier]) ⇒ Instance
        • .separate([color], [char], [identifier]) ⇒ Instance
        • .text([string], styles, [identifier]) ⇒ Instance
        • .style(string, styles, [identifier]) ⇒ string
        • .styleReset(string) ⇒ string
        • .line([string], [styles], [indt]) ⇒ Instance
        • .clear() ⇒ Instance
        • .spinner(identifier, [text], [config]) ⇒ Instance
        • .spinnerDone(identifier, [config]) ⇒ Instance
        • .spinnerDoneAll([config]) ⇒ Instance
        • .beep() ⇒ Instance
        • .waitInteraction([text], [config]) ⇒ Promise.<Instance>
        • .log(string, [identifier]) ⇒ Instance
        • .removeLog(identifier) ⇒ Instance
        • .enable() ⇒ Instance
        • .disable() ⇒ Instance
        • .resume() ⇒ Instance
        • .pause() ⇒ Instance
    • inner
      • ~Instance : object
      • ~styleName : "success" | "error" | "info" | "bold" | "underline" | "italic" | "strikethrough"
      • ~color : "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright"
      • ~spinnerFormatDone ⇒ string

module.exports ⏏

Class representing a logger.

Kind: Exported member

module.exports.Logion

Class representing a logger.

Kind: static class of module.exports

• .Logion
  • new exports.Logion(options)
  • .width ⇒ number
  • .height ⇒ number
  • .disabled ⇒ boolean
  • .paused ⇒ boolean
  • .styleNames ⇒ object
  • .newline([num], [force], [identifier]) ⇒ Instance
  • .indent([num], [identifier]) ⇒ Instance
  • .separate([color], [char], [identifier]) ⇒ Instance
  • .text([string], styles, [identifier]) ⇒ Instance
  • .style(string, styles, [identifier]) ⇒ string
  • .styleReset(string) ⇒ string
  • .line([string], [styles], [indt]) ⇒ Instance
  • .clear() ⇒ Instance
  • .spinner(identifier, [text], [config]) ⇒ Instance
  • .spinnerDone(identifier, [config]) ⇒ Instance
  • .spinnerDoneAll([config]) ⇒ Instance
  • .beep() ⇒ Instance
  • .waitInteraction([text], [config]) ⇒ Promise.<Instance>
  • .log(string, [identifier]) ⇒ Instance
  • .removeLog(identifier) ⇒ Instance
  • .enable() ⇒ Instance
  • .disable() ⇒ Instance
  • .resume() ⇒ Instance
  • .pause() ⇒ Instance

new exports.Logion(options)

Create a logger.

Returns: Instance - a logger instance.

Param	Type	Default	Description
options	object		Options object.
[options.streamIn]	object	process.stdin	Input stream (for scrolling and shortcuts).
[options.streamOut]	object	process.stdout	Output stream.
[options.disabled]	boolean	auto	Is logger disabled (no logging). By default, disabled if not ran in TTY.
[options.paused]	boolean	false	Is logger paused (not outputting to console and not listening for key presses, but still collecting logs).
[options.renderInterval]	number	80	Render interval in ms to update spinners.
[options.spinnerColor]	color	white	Spinner char color.
[options.spinnerIndent]	number	0	Spinner indent length in text chars.
[options.spinnerFrames]	Array.<string>	["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]	Spinner frames characters.
[options.spinnerDoneChar]	string	"✱"	Char to replace spinner after it is done (when calling spinnerDone).
[options.spinnerDoneAllChar]	string	"✸"	Char to replace active spinners after they are done (when calling spinnerDoneAll).
[options.spinnerFormatDone]	function	(str) => str	Call this function to format the spinner text after it is done, see spinnerFormatDone.

logion.width ⇒ number

Width of a console.

Kind: instance property of Logion
Returns: number - width in chars.
Read only: true

logion.height ⇒ number

Height of a console.

Kind: instance property of Logion
Returns: number - height in chars.
Read only: true

logion.disabled ⇒ boolean

Returns true if a logger is disabled.

Kind: instance property of Logion
Returns: boolean - is disabled.
Read only: true

logion.paused ⇒ boolean

Returns true if a logger is paused.

Kind: instance property of Logion
Returns: boolean - is paused.
Read only: true

logion.styleNames ⇒ object

Shortening style names enum. See Available style names

Kind: instance property of Logion
Returns: object - style names enum.
Read only: true

logion.newline([num], [force], [identifier]) ⇒ Instance

Output a newline(s). Accommodates if line breaks have been used before.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[num]	number	1	Number of new lines to output.
[force]	boolean	false	Do not accommodate for previous lines.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.indent([num], [identifier]) ⇒ Instance

Output spaces. Can be used in the middle of a line.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[num]	number	2	Number of spaces to output.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.separate([color], [char], [identifier]) ⇒ Instance

Output a separator on a new line. It fills all the available width.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[color]	color	grey	A separator character's color.
[char]	string	"-"	Character that make up the separator.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.text([string], styles, [identifier]) ⇒ Instance

Output a text with stlies applied. Does not add a new line.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[string]	string	"$space"	Text to output.
styles	object | styleName		Style object or styleName string.
[styles.color]	color		Text color (uses Chalk module color).
[styles.bgColor]	color		Background color (uses Chalk color).
[styles.bold]	boolean	false	Output as bold.
[styles.underline]	boolean	false	Output as underlined.
[styles.italic]	boolean	false	Output as italic.
[styles.strikethrough]	boolean	false	Output as strike-through.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.style(string, styles, [identifier]) ⇒ string

Style a text string. Shortening names could be one of: "success", "error", "info", "bold", "underline", "italic", "strikethrough".

Kind: instance method of Logion
Returns: string - a styled string (with escape codes).

Param	Type	Default	Description
string	string		Text to style.
styles	object | styleName		Style object or styleName string.
[styles.color]	color		Text color (uses Chalk module color).
[styles.bgColor]	color		Background color (uses Chalk color).
[styles.bold]	boolean	false	Output as bold.
[styles.underline]	boolean	false	Output as underlined.
[styles.italic]	boolean	false	Output as italic.
[styles.strikethrough]	boolean	false	Output as strike-through.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.styleReset(string) ⇒ string

Reset all styles for a string.

Kind: instance method of Logion
Returns: string - an unstyled string.

Param	Type	Description
string	string	String with styled text.

logion.line([string], [styles], [indt]) ⇒ Instance

Output a line of a text with an indent.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[string]	string	"$space"	Your text.
[styles]	object | string		Style object or shortening name (as string), same as style.
[styles.color]	color		Text color (uses Chalk module color).
[styles.bgColor]	color		Background color (uses Chalk color).
[styles.bold]	boolean	false	Output as bold.
[styles.underline]	boolean	false	Output as underlined.
[styles.italic]	boolean	false	Output as italic.
[styles.strikethrough]	boolean	false	Output as strike-through.
[indt]	number	0	Line indentation, a number of spaces to output before the text.

logion.clear() ⇒ Instance

Clear all the output.

Kind: instance method of Logion
Returns: Instance - a logger instance.

logion.spinner(identifier, [text], [config]) ⇒ Instance

Create a spinner on a new line. You can mark a spinner as done using its identifier with spinnerDone.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
identifier	string		Identifier for this spinner (required, should be unique).
[text]	string		Text to output after this spinner (on the same line).
[config]	object		An object for configuring this spinner.
[config.color]	color	white	Spinner char color (uses Chalk module color).
[config.indent]	number	0	Amount of spaces to output before this spinner.

logion.spinnerDone(identifier, [config]) ⇒ Instance

Mark the spinner as done. If text is not provided, uses spinnerFormatDone to format the original text.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
identifier	string		Identifier for the spinner (previously used to create the spinner in spinner).
[config]	object		An object for configuring this spinner.
[config.text]	string		A new text for this spinner (if empty, leaves the original text).
[config.color]	color		A new spinner char color (if empty, uses the original color).
[config.char]	string	"✱"	A character which replaces the spinner.

logion.spinnerDoneAll([config]) ⇒ Instance

Mark all spinners that are not already done as done. Uses spinnerFormatDone to format the original text.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
[config]	object		An object for configuring this spinner.
[config.color]	color		A new spinner char color (if empty, uses the original color).
[config.char]	string	"✸"	A character which replaces the spinner.

logion.beep() ⇒ Instance

Make a beep sound. May not be played in some consoles.

Kind: instance method of Logion
Returns: Instance - a logger instance.

logion.waitInteraction([text], [config]) ⇒ Promise.<Instance>

Output a special spinner and waits for a user interaction. Removes the spinner after interaction and resolves a Promise.

Kind: instance method of Logion
Returns: Promise.<Instance> - a promise which resolves after user interaction (resolver returns a logger instance).

Param	Type	Default	Description
[text]	string	"Press any key to continue"	Text for the spinner
[config]	object		An object for configuring the spinner, see spinner.

logion.log(string, [identifier]) ⇒ Instance

Log a row string. Other methods use this under the hood.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Default	Description
string	string		String to output.
[identifier]	string	"$random"	Identifier for this log message (should be unique).

logion.removeLog(identifier) ⇒ Instance

Remove a log message with the corresponding identifier.

Kind: instance method of Logion
Returns: Instance - a logger instance.

Param	Type	Description
identifier	string	Identifier for the log message (used to create it in other methods).

logion.enable() ⇒ Instance

Enable a logger.

Kind: instance method of Logion
Returns: Instance - a logger instance.

logion.disable() ⇒ Instance

Disable a logger. When disabled, it removes all listeners, resets screen buffer, and clears all logs.

Kind: instance method of Logion
Returns: Instance - a logger instance.

logion.resume() ⇒ Instance

Update the console with the last messages, resume spinners and listen for user interactions. Use this after pause.

Kind: instance method of Logion
Returns: Instance - a logger instance.

logion.pause() ⇒ Instance

Pause all logging, remove all listeners. Use this to temporary output something outside a logger instance, or to release a process from events listening (by logion).

Kind: instance method of Logion
Returns: Instance - a logger instance.

module.exports~Instance : object

A logger instance.

Kind: inner typedef of module.exports

module.exports~styleName : "success" | "error" | "info" | "bold" | "underline" | "italic" | "strikethrough"

Available style names.

Kind: inner typedef of module.exports

module.exports~color : "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright"

Supported color names.

Kind: inner typedef of module.exports

module.exports~spinnerFormatDone ⇒ string

Format the spinner text when it is marked as done.

Kind: inner typedef of module.exports
Returns: string - a formated spinner text.

Type	Description
string	Current spinner text.

TODO

• Add more tests.
• Add a help message for scrolling and document it.
• Add more text style (colors) variants.
• Fix flickering and rerender screen only if needed.