caterpillar

  • Version 6.8.0
  • Published
  • 133 kB
  • 3 dependencies
  • MIT 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

Index

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: any;
  • The log level information to use when the log level was unable to be determined. Defaults to the info log level.

property levels

levels: any;
  • 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: any;
  • 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) => any;
  • 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;

    property output

    output?: boolean;

    property styles

    styles?: Styles;

    interface FilterOptions

    interface FilterOptions {}
    • Configuration options for the Caterpillar Filter Transform

    property filterLevel

    filterLevel?: number;

    interface HumanOptions

    interface HumanOptions {}
    • Configuration options for the Caterpillar Human Transform

    property color

    color?: boolean;

    property colors

    colors?: LevelsToColorsMap;

    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;

    property levels

    levels?: LevelsMap;

    property lineLevel

    lineLevel?: number;

    property lineOffset

    lineOffset?: Offset;

    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 (3)

            Dev Dependencies (17)

            Peer Dependencies (0)

            No peer dependencies.

            Badge

            To add a badge like this onejsDocs.io badgeto 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>