Nutritious Pumpkin Meal

    logger-neue
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.1 • Public • Published

    logger-neue · Version License Travis CI TypeScript

    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 pathlogger-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

    Install

    npm i logger-neue

    DownloadsWeekly Downloads

    1

    Version

    3.1.1

    License

    MIT

    Unpacked Size

    62.2 kB

    Total Files

    25

    Last publish

    Collaborators

    • citycide
    • haltcase