logger-neue

v3.1.1

Published

2 years ago

Doing for Node logging what Neue did for Helvetica.

Downloads

0High
0Medium
0Low

citycide

haltcase

logging node logger console colors chalk formatted typescript

logger-neue ·

logger-neue is an attempt to refine the concept of logging in Node. It aims to be easier to configure than similar projects like winston for simple features like custom log levels and file output.

It also has basic support for Node-ish environments like Electron's renderer, where it will write to the developer tools console.

Since v2, logger-neue is written in strict TypeScript and includes type definitions. :tada:

installation · usage · api · defaults · templates · events · contributing · license

installation

install

Using Yarn:

yarn add logger-neue

Or using npm:

npm install logger-neue

import

In TypeScript / ES2015+:

import loggerNeue from "logger-neue"

In ES5 / commonjs:

const loggerNeue = require("logger-neue").default

usage

While logger-neue is highly configurable, minimum configuration for a prettier alternative to the standard console.log is as simple as:

const log = loggerNeue()

Or even prettier, with full color:

const log = loggerNeue({
  console: { fullColor: true }
})

Below is an example of a more thorough configuration. Note that there's no need to pass a write stream for the file or deal with a complicated transports configuration. You just have to define options.file and provide a path — logger-neue does the rest.

import loggerNeue from "logger-neue"

import { dirname } from "path"

const log = loggerNeue({
  file: {
    // if relative, resolved using `process.cwd()`
    path: "./test.log",
    // to specify the base directory, also pass the `dir` property
    dir: dirname(import.meta.url),
    // level defaults to "error"
    level: "error"
  },
  console: {
    // pass either a string or number
    // resolved against the log level map below
    level: process.env.NODE_ENV === "development" ? "trace" : "error",
    // if set to true, uses the `colors` option of `util.inspect`
    // for all logged arguments, regardless of type
    fullColor: true
  },
  levels: {
    // the level map to be used for both file & console
    // this example uses array syntax
    error:  [0, ["red", "bold", "underline"]],
    // array[0] = the log level
    // array[1] = an array ( or single string ) of colorette modifiers
    warn:   [1, "yellow"],
    info:   [2, "magenta"],
    debug:  [3, "cyan"],
    // undefined or invalid `style` defaults to "white"
    trace:  [4],
    absurd: [5, "gray"],

    // levels can also be defined with object syntax:
    ridiculous: {
      level: 6,
      style: ["blue", "bgYellow", "underline", "italic"]
    }
  }
})

api

loggerNeue (`constructor`)

loggerNeue(options)

There are actually two ways to create a new instance — you can use the default export (which is a function) or the named export LoggerNeue. This means the following are (roughly) equivalent:

import loggerNeue, { LoggerNeue } from "logger-neue"
const logger1 = new LoggerNeue()
const logger2 = loggerNeue()

The difference is that LoggerNeue is the raw class, and the default export is a wrapper function that provides helpful type information based on your provided level definitions.

optional {object} options:

| property | type | default | description | | --------- | :--------: | :---------: | --------------------------------- | | file | object or false | false | Configuration for file output. | | console | object | see below | Configuration for console output. |

options.file:

| property | type | default | description | | ---------- | :-------------: | :-------------: | ----------------------------------- | | dir | string | process.cwd() | Base directory with which to resolve path. | | level | string or number | 0 or error | Number or name of the output level. | | path | string | - | Path to the log file, resolved with dir if relative. | | template | string | see here | strat compatible template with which to format the output. See templates for more. |

options.console:

| property | type | default | description | | ----------- | :-------------: | :-------------: | ----------------------------------- | | fullColor | boolean | false | Whether to apply color to all types of values. | | level | string or number | 2 or info | Number or name of the output level. | | template | string | see here | strat compatible template with which to format the output. See templates for more. |

options.levels:

If provided as an object, it should have these properties:

| property | type | default | description | | ---------- | :--------: | :---------: | --------------------------------- | | level | number | 0 | Determines when this log method fires. | | style | string or string[] | - | colorette styles for terminal output, either a single string or array of styles. | | isError | boolean | false | If true, target stderr instead of stdout. |

If provided as an array, it should take the form of [level, style, isError]

addLevel

addLevel(name, properties)

{string} name
{Object} properties:

If provided as an object, it should have these properties:

If provided as an array, it should take the form of [level, style, isError]

log

log(level, ...args)

Alternative method of calling a log level. The following are equivalent:

log.error("fail")
log("error", "fail")

// can also call by level number
log(0, "fail")

{string|number} level: name or number of the log level to trigger
{...any} args: arguments passed to the log level function

getLevelByNumber

getLevelByNumber(number)

{number} number: number to search levels for

{string}: name of the associated level

getNumberOfLevel

getNumberOfLevel(name)

{string} name: name of the level to search for

{number}: logging level of name

getLevelNames

getLevelNames()

{string[]}: array of all log level names

getConsoleLevel

getConsoleLevel()

{number}: the current logging level for console output

setConsoleLevel

setConsoleLevel(level)

Set the logging level for console output. Any levels below this are not output.

{string|number}: either the name of the level or its logging level number

getFileLevel

getFileLevel()

{number}: the current logging level for file output

setFileLevel

setFileLevel(level)

Set the logging level for file output. Any levels below this are not output.

{string|number}: either the name of the level or its logging level number

defaults

logger-neue attempts to make setup as painless as possible, which means it uses sane defaults to allow for minimal or zero configuration.

Without providing a config object, logger-neue uses the following defaults:

options = {
  // no file output
  file: false,
  console: {
    // will output "info", "warn", and "error"
    level: "info",
    // does not apply color to primitives
    fullColor: false,
    template: "{level}{padding}  {input}"
  },
  levels: {
    //       [level, style, isError]
    error:   [0, ["red", "bgBlack"], true],
    warn:    [1, ["black", "bgYellow"], false],
    info:    [2, ["green"], false],
    verbose: [3, ["blue", "bgBlack"], false],
    debug:   [4, ["cyan"], false],
    silly:   [5, ["inverse"], false]
  }
}

If options.file.path is provided, these defaults are used for the rest of the properties in options.file:

options.file = {
  // used as base directory if `path` is relative
  dir: process.cwd(),
  // only outputs "error"
  level: 0,
  template:
    `{{"level":{level!json},` +
    `"input":{args!json},` +
    `"timestamp":{timestamp!json}}}`
}

This means a console-only config can be as simple as:

const logger = loggerNeue()

... and adding additional output to a file can be as simple as:

const logger = loggerNeue({
  file: { path: "./log.txt" }
})

templates

The strat module is used to format all output strings. The templates are customizable by passing them to the console or file options objects at construction time.

You can also use the format() method of any log level to pass a template to be interpolated.

variables

The variables replaced from a template are:

| name | description | | ------- | ----------- | | args | Array of the raw arguments passed to the log function. | | padding | String of spaces for use in aligning log levels of varying lengths. | | input | Array of the arguments after they've been processed & stylized. | | level | Name of the log level, stylized by default with colorette for terminals. | | timestamp | Defaults to an ISO string timestamp of log time. |

presets

Several template presets are exported for your usage:

import loggerNeue, { templatePresets } from "logger-neue"

const log = loggerNeue({
  console: {
    fullColor: true,
    template: templatePresets.bracketedLevel
  }
})

log.info("hello there!")
// -> [info]        hello there!

log.ridiculous("hello again!")
// -> [ridiculous]  hello again!

| name | template | | ---------------- | ----------------------------------------- | | alignLeft¹ | {level}{padding} {input} | | alignRight | {padding}{level} {input} | | separatedColon | {level}: {input} | | bracketedLevel | [{level}]{padding} {input} | | jsonTimestamp² | {{"level":{level!json},"input":{args!json},"timestamp":{timestamp!json}}} |

¹ default console template ² default file template

transformers

Templates also support transformers — functions that modify the above variables just by appending them to the variable name after a !, like this substring taken from the default file template:

"{level!json}"

The json transformer stringifies its argument, level in this case.

All the transformers available are:

| name | description | | ------- | ----------------------------------------- | | upper | Upper cases the argument | | lower | Lower cases the argument | | paren | Wraps the argument in parentheses | | brace | Wraps the argument in braces ([]) | | curly | Wraps the argument in curly braces ({}) | | json | JSON stringifies the argument |

See the strat documentation for more details about how these transformers work.

events

Each instance of logger-neue is also an event emitter, so you can use all methods of Node's EventEmitter on it:

const log = loggerNeue()
log.on("log", event => {
  const { name, level, args } = event
})

log.on("log:info", event => {
  // only `log.info()` will trigger this
  const { name, level, args } = event
})

log.once(/* ... */)
log.removeAllListeners()
// etc

There are also events emitted prior to the log being output — just prepend pre: to the events in the above example. These events provide the same fields but with the addition of a prevent() function. Calling this function prevents the log from being output.

log.on("pre:log", event => {
  const { name, level, args, prevent } = event
})

log.on("pre:log:trace", event => {
  // prevent all output when `log.trace()` is called
  event.prevent()
})

contributing

This project is open to contributions of all kinds! Please check and search the issues if you encounter a problem before opening a new one. Pull requests for improvements are also welcome.

Fork the project, and preferably create a branch named something like feat-make-better
Modify the source files in the src directory as needed
Run npm test to make sure all tests continue to pass, and it never hurts to have more tests
Commit, push, and open a pull request.