Logion

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.