caterpillar

caterpillar

Version 8.2.0
Published 9 months ago
238 kB
4 dependencies
Artistic-2.0 license

Install

npm i caterpillar

yarn add caterpillar

pnpm add caterpillar

Overview

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

Classes

class Browser

class Browser extends Transform {}

Convert human readable Caterpillar entries into browser compatible entries.

Example 1

import { Logger, Human, Browser } from 'caterpillar'
const logger = new Logger()
logger.pipe(new Human()).pipe(new Browser())
logger.log('info', 'some', {data: 'oh yeah'}, 42)

constructor

constructor(opts?: BrowserOptions);

Create our instance and apply our configuraiton options.

property color

color: boolean;

Whether or not we should use color.

property output

output: boolean;

Whether or not we should write to the browser console.

property styles

styles: Styles;

The objects that tell our browser transform how to convert terminal colours into console colours.

method format

format: (message: string) => string[];

Convert a human readable Caterpillar entry into a format that browser consoles can understand. And if the write config property is true (it is by default), write the result to the browser console.

class Filter

class Filter extends Transform {}

Caterpillar Filter Transform. Filters the log entries, keeping only those equal to or below the specified filterLevel.

Example 1

import { Logger, Filter } from 'caterpillar'
const logger = new Logger()
const filter = new Filter({ filterLevel: 6 })
logger.pipe(filter).pipe(process.stdout)
logger.log('info', 'this will be outputted')
logger.log('debug', 'this will be ignored')
filter.filterLevel = 5
logger.log('info', 'now even this will be ignored')
logger.log('note', 'but not this')

constructor

constructor(opts?: FilterOptions);

Create our instance and apply our configuraiton options.

property filterLevel

filterLevel: number;

Only display entries that have a log level below or equal to this number. Defaults to 6, which by default is the info log level.

method format

format: (entry: LogEntry) => LogEntry | null;

Retain only log entries that are equal to or less than the specified filter level.

class Human

class Human extends Transform {}

Convert Logger entries into human readable format. Transform

Example 1

import { Logger, Human } from 'caterpillar'
const logger = new Logger()
const human = new Human()
logger.pipe(human).pipe(process.stdout)
logger.log('info', 'some', {data: 'oh yeah'}, 42)

constructor

constructor(opts?: HumanOptions);

Create our instance and apply our configuration options.

property color

color: boolean;

Whether or not to use colors?

property colors

colors: LevelsToColorsMap;

Mapping of which log level numbers correspond to which colours

method format

format: (entry: LogEntry) => string;

Convert a logger entry into a human readable format

method formatArguments

formatArguments: (args: any[]) => string;

Convert logger entry arguments into a human readable string

method formatDate

formatDate: (datetime: Date | number | string) => string;

Convert a datetime into a human readable format

method getColor

getColor: (levelNumber: number) => ansi.ANSIApplier | false;

Get the color for the log level

method padLeft

padLeft: (padding: string, size: number, content: string | number) => string;

Pad the left of some content if need be with the specified padding to make the content reach a certain size

class Logger

class Logger extends Transform {}

Logger. This is what we write to.

Example 1

Creation

// Via class
import { Logger } from 'caterpillar'
const logger = new Logger()

constructor

constructor(opts?: LoggerOptions);

Create our instance and apply our configuraiton options.

property defaultLevelInfo

defaultLevelInfo: LevelInfo;

The log level information to use when the log level was unable to be determined. Defaults to the info log level.

property levels

levels: LevelsMap;

The mapping of log level names to log level numbers. Defaults to the RFC Log Level configuration.

property lineLevel

lineLevel: number;

Only fetch line information for entries that have a log level equal to, or below this number. You should only specify this if you need it, as fFetching line information for thousands of log entries, which is typical in large applications, will slow your application down dramatically. If not specified, defaults to -Infinity which effect is to ignore gathering line information for all log levels.

property lineOffset

lineOffset: Offset;

The configuration to use for the line offset. This defaults to any file path that includes logger, and any method that includes the word log.

method debug

debug: (...args: any) => void;

Alias for log which prefixes the debug log level

method error

error: (...args: any) => void;

Alias for log which prefixes the error log level

method format

format: (args: any) => LogEntry;

Takes an arguments array and tranforms it into a log entry.

method getLogLevel

getLogLevel: (value: number | string) => LevelInfo | null;

Alias for getLogLevel using the configured logger levels as reference.

method info

info: (...args: any) => void;

Alias for log which prefixes the info log level

method log

log: (...args: any) => void;

Log the arguments into the logger stream as formatted data with debugging information. Such that our transformers can deal with it intelligently.

Example 1

Inputs

logger.log('note', 'this is working swell')

logger.log('this', 'worked', 'swell')

Example 2

Results

{
	"args": ["this is working swell"],
	"date": "2013-04-25T10:18:25.722Z",
	"levelNumber": 5,
	"levelName": "notice",
	"line": "59",
	"method": "Object.<anonymous>",
	"file": "/Users/balupton/some-project/calling-file.js"
}

{
		"args": ["this", "worked", "well"],
		"date": "2013-04-25T10:18:26.539Z",
		"levelNumber": 6,
		"levelName": "info",
		"line": "60",
		"method": "Object.<anonymous>",
		"file": "/Users/balupton/some-project/calling-file.js"
}

method warn

warn: (...args: any) => void;

Alias for log which prefixes the warn log level

class Transform

class Transform implements Pipeable {}

Caterpillar Transform Class. Provides the methods needed to provide a pipable Caterpillar Transform. Such that all you need to do is write your Transform.format method. It can pipe to anything that provides a Pipeable.write method.
Example 1
[Writing a Custom Transform](https://repl.it/@balupton/caterpillar-custom-transform)

method close

close: () => Promise<void>;

Close the child pipes.

method end

end: (cb?: () => void) => void;

method format

format: (message: any) => any;

Format the received log entry representation. Your transformer should extend this.

method pipe

pipe: <T extends Pipeable>(to: T) => T;

Pipe future log entries into a caterpillar transform or a stream.

method write

write: (chunk: any) => Promise<void>;

Write to the child pipes.

Interfaces

interface BrowserOptions

interface BrowserOptions {}

Configuration optons for the Caterpillar Browser Transform

property color

color?: boolean;

Use to override the default value of Filter.color

property output

output?: boolean;

Use to override the default value of Filter.console

property styles

styles?: Styles;

Use to override the default value of Filter.styles

interface FilterOptions {}

Configuration options for the Caterpillar Filter Transform

filterLevel?: number;

Use to override the default value of Filter.filterLevel

interface HumanOptions

interface HumanOptions {}

Configuration options for the Caterpillar Human Transform

property color

color?: boolean;

Use to override the default value of Human.color

property colors

colors?: LevelsToColorsMap;

Use to override the default value of Human.colors

interface LogEntry

interface LogEntry extends LevelInfo, Location {}

The log entry that Caterpillar creates and forwards to its transforms

property args

args: any[];

all the arguments that were after the log level

property date

date: string;

the iso string of when the log occured

interface LoggerOptions

interface LoggerOptions {}

Configuration for the Caterpillar Logger

property defaultLevel

defaultLevel?: number | string;

Use to override the default value of Logger.defaultLevelInfo

property levels

levels?: LevelsMap;

Use to override the default value of Logger.levels

property lineLevel

lineLevel?: number;

Use to override the default value of Logger.lineLevel

property lineOffset

lineOffset?: Offset;

Use to override the default value of Logger.lineOffset

interface Pipeable

interface Pipeable {}

Caterpillar supports piping to anything that supports this interface. Which includes: - - [Deno Writer Streams](https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.Writer), e.g. - [Deno.stdout](https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.stdout) - [Node.js Writable Streams](https://nodejs.org/dist/latest-v14.x/docs/api/stream.html#stream_writable_streams), e.g. - [process.stdout](https://nodejs.org/dist/latest-v14.x/docs/api/process.html#process_process_stdout) - [fs.createWriteStream](https://nodejs.org/dist/latest-v14.x/docs/api/fs.html#fs_fs_createwritestream_path_options) - [WhatWG Writable Streams](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)

method close

close: () => Promise<void> | void;

method end

end: (cb?: () => void) => void;

method write

write: (chunk: any) => any;

interface Styles

interface Styles {}

Mapping of ANSI color codes into a CSS style

index signature

[key: string]: {
    /** The ANSI color code used to start the style */
    start: string;
    /** The ANSI color code used to end the style */
    end: string;
    /** The CSS style value */
    value: string;
};

Package Files (6)

Dependencies (4)

Dev Dependencies (16)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/caterpillar.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/caterpillar)

HTML

<a href="https://www.jsdocs.io/package/caterpillar"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 9 months ago.
Package analyzed in 4325 ms.
Missing or incorrect documentation? Open an issue for this package.

caterpillar

Install

Overview

Index

Classes

Interfaces

Classes

class Browser

Example 1

constructor

property color

property output

property styles

method format

class Filter

Example 1

constructor

property filterLevel

method format

class Human

Example 1

constructor

property color

property colors

method format

method formatArguments

method formatDate

method getColor

method padLeft

class Logger

Example 1

constructor

property defaultLevelInfo

property levels

property lineLevel

property lineOffset

method debug

method error

method format

method getLogLevel

method info

method log

Example 1

Example 2

method warn

class Transform

Example 1

method close

method end

method format

method pipe

method write

Interfaces

interface BrowserOptions

property color

property output

property styles

interface FilterOptions

property filterLevel

interface HumanOptions

property color

property colors

interface LogEntry

property args

property date

interface LoggerOptions

property defaultLevel

property levels

property lineLevel

property lineOffset

interface Pipeable

method close

method end

method write

interface Styles

index signature

Package Files (6)

Dependencies (4)

Dev Dependencies (16)

Peer Dependencies (0)