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. 🎉

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

installation

1. install

   Using Yarn:

   yarn add logger-neue

   Or using npm:

   npm install logger-neue

2. 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.

Arguments

• 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)

Arguments

• {string} name
• {Object} properties:

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]

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")

Arguments

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

getLevelByNumber

getLevelByNumber(number)

Arguments

• {number} number: number to search levels for

Returns

{string}: name of the associated level

getNumberOfLevel

getNumberOfLevel(name)

Arguments

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

Returns

{number}: logging level of name

getLevelNames

getLevelNames()

Returns

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

getConsoleLevel

getConsoleLevel()

Returns

{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.

Arguments

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

getFileLevel

getFileLevel()

Returns

{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.

Arguments

{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.

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

see also

• strat – string formatting library at home in ES2015+ JavaScript
• colorette – terminal string styling done right

license

MIT © Bo Lingen / citycide