README.md

Caterpillar

Caterpillar is the ultimate logging system for Deno, Node.js, and Web Browsers. Log levels are implemented to the RFC standard. Log entries can be filtered and piped to various streams, including coloured output to the terminal, the browser's console, and debug files. You can even write your own transforms.

Usage

Complete API Documentation.

Examples

• Deno Example
• Node.js Example
• Web Browser Example
• Writing a Custom Transform

Overview

The RFC Log Levels are provided by the rfc-log-levels package which follows RFC 3164 - The BSD Syslog Protocol.

Log Entries that are within the lineLevel range, will have their line information fetched using the get-current-line package.

The Logger is what you write your log messages to, which you then pipe to destinations and transforms.

The Filter transport is used to filter out log levels that we do not want to pass onto the next destination.

The Human transport is used to convert the Log Entries into a human readable and colourful output.

The Browser transport is used to send the human output, including colours, to the Web Browser console.

The Transform is used to write your own transforms, and is what all the others are based from.

Node.js Guide

To get started for Node.js, setup a new Node.js project for this guide and install Caterpillar.

mkdir caterpillar-guide
cd caterpillar-guide
npm init
npm install --save caterpillar
touch index.js

Then edit our index.js file with the following, that will output all the log messages in JSON format to stdout, and can be run via node index.js:

const { Logger } = require('caterpillar')
const logger = new Logger()

logger.pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

Outputting in JSON format is not a nice experience, instead we can do better by using the Human transport such that it is human readable.

const { Logger, Human } = require('caterpillar')
const logger = new Logger()

logger.pipe(new Human()).pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

However, perhaps we want to still store the JSON format for querying later. We can pipe the human format to stdout as before, but we can pipe the raw output to a debug file.

const { Logger, Human } = require('caterpillar')
const logger = new Logger()

const { createWriteStream } = require('fs')
logger.pipe(createWriteStream('./debug.log'))

logger.pipe(new Human()).pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

Now let's stay for some reason, we want to capitalise all the log messages that are warning levels and higher, we can do this by making our own transport by extending the Transform.

const { Logger, Transform, Human } = require('caterpillar')
const logger = new Logger()

const { createWriteStream } = require('fs')
logger.pipe(createWriteStream('./debug.log'))

class Uppercase extends Transform {
    format(entry) {
        if (entry.levelNumber <= 4) {
            entry.args.forEach(function (value, index) {
                if (typeof value === 'string') {
                    entry.args[index] = value.toUpperCase()
                }
            })
        }
        return entry
    }
}

logger.pipe(new Uppercase()).pipe(new Human()).pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

Futhermore, the user probably doesn't need to see debug messages, even though they are useful for debugging. We can filter out the debug messages for the user, but maintain them for the debug.log file by applying the Filter transport to the pipe that goes to stdout.

const { Logger, Transform, Filter, Human } = require('caterpillar')
const logger = new Logger()

const { createWriteStream } = require('fs')
logger.pipe(createWriteStream('./debug.log'))

class Uppercase extends Transform {
    format(entry) {
        if (entry.levelNumber <= 4) {
            entry.args.forEach(function (value, index) {
                if (typeof value === 'string') {
                    entry.args[index] = value.toUpperCase()
                }
            })
        }
        return entry
    }
}

logger
    .pipe(new Filter({ filterLevel: 5 }))
    .pipe(new Uppercase())
    .pipe(new Human())
    .pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

As fetching line information is computationally expensive process, for large applications for performance we probably only want to fetch the line information for messages that we actually show to the user. As such, we should make the filterLevel and the lineLevel the same.

const { Logger, Transform, Filter, Human } = require('caterpillar')
const level = 5
const logger = new Logger({ lineLevel: level })

const { createWriteStream } = require('fs')
logger.pipe(createWriteStream('./debug.log'))

class Uppercase extends Transform {
    format(entry) {
        if (entry.levelNumber <= 4) {
            entry.args.forEach(function (value, index) {
                if (typeof value === 'string') {
                    entry.args[index] = value.toUpperCase()
                }
            })
        }
        return entry
    }
}

logger
    .pipe(new Filter({ filterLevel: 5 }))
    .pipe(new Uppercase())
    .pipe(new Human())
    .pipe(process.stdout)

logger.log('warn', 'this is a warning, which is level', 4)
logger.warn('this is a warning, which is level', 4)
logger.log('debug', 'this is a debug message, which is level', 7)
logger.warn('this is a debug message, which is level', 7)

Finally, if we are using Caterpillar in web browser environments, instead of Node.js, instead of doing:

const { Logger, Transform, Filter, Human } = require('caterpillar')
// ...
logger.pipe(new Human()).pipe(process.stdout)
// ...

We would pipe to the Browser transform instead of to stdout.

const { Logger, Transform, Filter, Human, Browser } = require('caterpillar')
// ...
logger.pipe(new Human()).pipe(new Browser())
// ...

With this, you now have enough information to leverage the cross-platform power of Caterpillar for most purposes, and the power to write your own custom transforms which can be published as their own packages and shared.

Install

npm

• Install: npm install --save caterpillar
• Import: import * as pkg from ('caterpillar')
• Require: const pkg = require('caterpillar')

Deno

import * as pkg from 'https://unpkg.com/caterpillar@^8.2.0/edition-deno/index.ts'

Skypack

<script type="module">
    import * as pkg from '//cdn.skypack.dev/caterpillar@^8.2.0'
</script>

unpkg

<script type="module">
    import * as pkg from '//unpkg.com/caterpillar@^8.2.0'
</script>

jspm

<script type="module">
    import * as pkg from '//dev.jspm.io/[email protected]'
</script>

Editions

This package is published with the following editions:

• caterpillar aliases caterpillar/index.cjs which uses the Editions Autoloader to automatically select the correct edition for the consumer's environment
• caterpillar/source/index.ts is TypeScript source code with Import for modules
• caterpillar/edition-browsers/index.js is TypeScript compiled against ES2022 for web browsers with Import for modules
• caterpillar/edition-es2022/index.js is TypeScript compiled against ES2022 for Node.js 14 || 16 || 18 || 20 || 21 with Require for modules
• caterpillar/edition-es2017/index.js is TypeScript compiled against ES2017 for Node.js 8 || 10 || 12 || 14 || 16 || 18 || 20 || 21 with Require for modules
• caterpillar/edition-es2015/index.js is TypeScript compiled against ES2015 for Node.js 6 || 8 || 10 || 12 || 14 || 16 || 18 || 20 || 21 with Require for modules
• caterpillar/edition-es5/index.js is TypeScript compiled against ES5 for Node.js 4 || 6 || 8 || 10 || 12 || 14 || 16 with Require for modules
• caterpillar/edition-es2017-esm/index.js is TypeScript compiled against ES2017 for Node.js 12 || 14 || 16 || 18 || 20 || 21 with Import for modules
• caterpillar/edition-types/index.d.ts is TypeScript compiled Types with Import for modules
• caterpillar/edition-deno/index.ts is TypeScript source code made to be compatible with Deno

History

Discover the release history by heading on over to the HISTORY.md file.

Backers

Code

Discover how to contribute via the CONTRIBUTING.md file.

Authors

• Benjamin Lupton — Accelerating collaborative wisdom.

Maintainers

• Benjamin Lupton — Accelerating collaborative wisdom.

Contributors

• Benjamin Lupton — view contributions
• t-visualappeal — view contributions
• Tim Helfensdörfer — view contributions

Finances

Sponsors

• Andrew Nesbitt — Software engineer and researcher
• Balsa — We're Balsa, and we're building tools for builders.
• Codecov — Empower developers with tools to improve code quality and testing.
• Poonacha Medappa
• Rob Morris
• Sentry — Real-time crash reporting for your web apps, mobile apps, and games.
• Syntax — Syntax Podcast

Donors

• Andrew Nesbitt
• Armen Mkrtchian
• Balsa
• Chad
• Codecov
• dr.dimitru
• Elliott Ditman
• entroniq
• GitHub
• Hunter Beast
• Jean-Luc Geering
• Michael Duane Mooring
• Michael Harry Scepaniak
• Mohammed Shah
• Mr. Henry
• Nermal
• Pleo
• Poonacha Medappa
• Rob Morris
• Robert de Forest
• Sentry
• ServieJS
• Skunk Team
• Syntax
• WriterJohnBuck

License

Unless stated otherwise all works are:

• Copyright © Benjamin Lupton

and licensed under:

• Artistic License 2.0