open-draft / logger

Environment-agnostic, ESM-friendly logger for simple needs.

Logger

Environment-agnostic, ESM-friendly logger for simple needs.

Why does this exist?

I've been using debug for quite some time but wanted to migrate my projects to better ESM support. Alas, debug doesn't ship as ESM so I went and wrote this little logger just for my needs. You will likely see it printing useful data in Mock Service Worker and beyond.

Installation

npm install @open-draft/logger

Usage

This package has the same API for both browser and Node.js and can run in those environments out of the box.

// app.js
import { Logger } from '@open-draft/logger'

const logger = new Logger('parser')

logger.info('starting parsing...')
logger.warning('found legacy document format')
logger.success('parsed 120 documents!')

Logging is disabled by default. To enable logging, provide the DEBUG environment variable:

DEBUG=1 node ./app.js

You can also use true instead of 1. You can also use a specific logger's name to enable logger filtering.

API

• Class: Logger
  • new Logger(name)
  • logger.debug(message, ...positionals)
  • logger.info(message, ...positionals)
  • logger.success(message, ...positionals)
  • logger.warning(message, ...positionals)
  • logger.error(message, ...positionals)
  • logger.extend(name)
  • logger.only(callback)

new Logger(name)

• name string the name of the logger.

Creates a new instance of the logger. Each message printed by the logger will be prefixed with the given name. You can have multiple loggers with different names for different areas of your system.

const logger = new Logger('parser')

You can nest loggers via logger.extend().

logger.debug(message, ...positionals)

• message string
• positionals unknown[]

Prints a debug message.

logger.debug('no duplicates found, skipping...')

12:34:56:789 [parser] no duplicates found, skipping...

logger.info(message, ...positionals)

• message string
• positionals unknown[]

Prints an info message.

logger.info('new parse request')

12:34:56:789 [parser] new parse request

logger.success(message, ...positionals)

• message string
• positionals unknown[]

Prints a success message.

logger.success('prased 123 documents!')

12:34:56:789 ✔ [parser] prased 123 documents!

logger.warning(message, ...positionals)

• message string
• positionals unknown[]

Prints a warning. In Node.js, prints it to process.stderr.

logger.warning('found legacy document format')

12:34:56:789 ⚠ [parser] found legacy document format

logger.error(message, ...positionals)

• message string
• positionals unknown[]

Prints an error. In Node.js, prints it to process.stderr.

logger.error('failed to parse document')

12:34:56:789 ✖ [parser] failed to parse document

logger.extend(prefix)

• prefix string Additional prefix to append to the logger's name.

Creates a new logger out of the current one.

const logger = new Logger('parser')

function parseRequest(request) {
  const requestLogger = logger.extend(`${request.method} ${request.url}`)
  requestLogger.info('start parsing...')
}

12:34:56:789 [parser] [GET https://example.com] start parsing...

logger.only(callback)

Executes a given callback only when the logging is activated. Useful for computing additional information for logs.

logger.only(() => {
  const documentSize = getSizeBytes(document)
  logger.debug(`document size: ${documentSize}`)
})

You can nest logger.* methods in the callback to logger.only().

Log levels

You can specify the log levels to print using the LOG_LEVEL environment variable.

There are the following log levels:

• debug
• info
• success
• warning
• error

Providing no log level will print all the messages.

Here's an example of how to print only warnings:

// app.js
import { Logger } from '@open-draft/logger'

const logger = new Logger('parser')

logger.info('some info')
logger.warning('some warning')
logger.error('some error')

LOG_LEVEL=warning node ./app.js

12:34:56:789 ⚠ [parser] some warning

Logger filtering

You can only print a specific logger by providing its name as the DEBUG environment variable.

// app.js
import { Logger } from '@open-draft/logger'

const appLogger = new Logger('app')
const parserLogger = new Logger('parser')

appLogger.info('starting app...')
parserLogger.info('creating a new parser...')

DEBUG=app node ./app.js

12:34:56:789 [app] starting app...