logita v0.0.2

logita

🚧 Work in progress (pre-release) 🚧

Simplistic logging for node.js with extensive TypeScript support.

npm i logita

Why?

There are several logging libraries, but none of them seem to suite these needs:

• Logging should always be simple. Just log a your messages with given severity level.
• Logs should always be easily tracked. When debugging, it is important to be able to see where the message gets logged, without having to pass extra parameters.
• Configuration should always be simple. Nothing frustrates more than trying to find out the perfect configuration for your own needs, when all you want is just pretty logging to console. Too often you need to implement an unnecessarily complicated wrapper to achieve this.

Features

• Customizable logging levels
• Extensive TypeScript support
• Can be used as easily and as flexibly as console.log or console.error
• Display file path with line & column numbers (where the log function was called from)
• Quickly navigate to log location on editors like VS Code
• Track chains of requests or other asynchronous functions easily with log spans

Getting started

1. To use default logging settings, just import log.
2. To create logging object with custom settings, call createLoggers. Export the created logging object for your project needs.
3. Start logging!

Simplest example

// /app/src/some-file.ts
import { log } from "logita";

log.debug("Wow, this is cool!");

Example with some settings overridden

// /app/src/log.ts
import { createLoggers } from "logita";

export default createLoggers({
  showFile: false,
  // Use Moment.js format to format the timestamp!
  timestamp: "DD.MM.YYYY HH:mm:ss"
});

// /app/src/another-file.ts
import log from "./log";

log.debug("Wow, this is cool!");

Example with custom logging levels

import { createLoggers } from "logita";
// Use chalk to define log level colors!
import chalk from "chalk";

export default createLoggers({
  levels: {
    important: {
      priority: 0,
      color: chalk.bgRed.white,
      text: "UH-OH"
    },
    notSoImportant: {
      priority: 1,
      color: chalk.yellow,
      text: "meh"
    },
    silly: {
      priority: 2,
      color: chalk.green
    }
  },
  showFile: true,
  timestamp: "YYYY-MM-DD HH:mm:ss"
});

// /app/src/another-file.ts
import log from "./log";

log.important("Alarm!");
log.notSoImportant("Hello world");
log.silly("How do you do");

Log spans

Need to track times on chains of requests or other asynchronous functions? Because of the repetitive nature of such logging, logita provides log spans. Just create a log span with a default logging level and a name between the parentheses:

import { log } from "logita";

const span = log.span.debug("My span");

After this you can log the span with splitTime, success and fail logging functions:

const span = log.span.debug("My span");
try {
  await doSomething();
  span.splitTime();
  await doSomethingElse();
  span.splitTime();
  await doSomethingFinal();
  span.success();
} catch (error) {
  span.fail();
}

You can also give a message for the functions to be more verbose:

const span = log.span.debug("My span");
try {
  await doSomething();
  span.splitTime("First request done");
  await doSomethingElse();
  span.splitTime("Second request done");
  await doSomethingFinal();
  span.success("Finally finished");
} catch (error) {
  span.fail("Something went wrong");
}

Note: Only use messages of type string, because span logs should not log actual data. For that, please use the normal logging functions.

To take things even further, you can also log each message with a different level from the default one:

const span = log.span.debug("My span");
try {
  await doSomething();
  span.info.splitTime("First request done");
  await doSomethingElse();
  span.verbose.splitTime("Second request done");
  await doSomethingFinal();
  span.info.success("Finally finished");
} catch (error) {
  span.fatal.fail("Something went wrong");
}

API

createLoggers(config)

Returns an object containing a simple logging function for each given logging level.

• config.levels (optional)
  • Default levels:
    • fatal (0)
    • error (1)
    • warning (2)
    • info (3)
    • verbose (4)
    • debug (5)
  • config.levelslevel.priority (required)
    • Number
    • Defines the priority for logging level: the lower, more important the level is
  • config.levelslevel.text (optional)
    • String
    • Log level text, shown in the prefix of the log message
    • Default: log level key in upper case
  • config.levelslevel.color (optional)
    • Log level text color as a Chalk function
    • Default: chalk.bgBlack.bold.white
  • config.levelslevel.stderr (optional)
    • Boolean
    • Should the log be directed to stderr instead of stdout?
    • Default: false
• config.span (optional)
  • Log span specific settings
  • config.span.showSplitDifference (optional)
    • Boolean
    • Show the split difference since the previous time?
    • Default: true
• config.minLevel (optional)
  • String (key of some log level)
  • Minimum log level that should be logged
  • Default: tries to find it from process.env.MIN_LOG_LEVEL, but if none is found, everything gets logged
• config.timestamp (optional)
  • Boolean or string
  • If false, timestamp is not shown
  • If true, timestamp is shown with Date.prototype.toUTCString
  • If string, timestamp is formatted with it using Moment.js
  • Default: true, i.e. show timestamp with Date.prototype.toUTCString
• config.showFile (optional)
  • Boolean
  • Should the file path be shown in the log message prefix?
  • Default: true
• config.stdout (optional)
  • Function for logging stdout output
  • Default: console.log
• config.stderr (optional)
  • Function for logging stderr output
  • Default: console.error

Default config:

{
  {
    levels: {
      fatal: {
        priority: 0,
        color: chalk.bgRedBright.white,
        stderr: true
      },
      error: {
        priority: 1,
        color: chalk.bgBlack.red,
        stderr: true
      },
      warning: {
        priority: 2,
        color: chalk.bgBlack.yellow
      },
      info: {
        priority: 3,
        color: chalk.bgBlack.blue
      },
      verbose: {
        priority: 4,
        color: chalk.bgBlack.green
      },
      debug: {
        priority: 5,
        color: chalk.inverse.bgWhite.gray
      }
    }
  },
  span: {
    showSplitDifference: true
  }
  showFile: true,
  timestamp: true,
  minLevel: process.env.LOG_MIN_LEVEL || undefined,
  stdout: console.log,
  stderr: console.error
}

Example log messages with default config: