callsite-record

What is callsite-record?

The callsite-record npm package is used to capture and format call site information in Node.js. It is particularly useful for debugging and logging purposes, as it allows developers to obtain detailed information about the call stack, including file names, line numbers, and function names.

What are callsite-record's main functionalities?

Capture Call Site Information

This feature allows you to capture call site information by creating a new Error object and passing it to callsite-record. The renderSync method is then used to format and display the call site information.

const callsiteRecord = require('callsite-record');

function getCallSite() {
  const record = callsiteRecord({ forError: new Error() });
  console.log(record.renderSync());
}

getCallSite();

Asynchronous Call Site Information

This feature allows you to capture call site information asynchronously. The render method returns a promise that resolves to the formatted call site information.

const callsiteRecord = require('callsite-record');

async function getAsyncCallSite() {
  const record = await callsiteRecord({ forError: new Error() }).render();
  console.log(record);
}

getAsyncCallSite();

Custom Error Handling

This feature demonstrates how to use callsite-record for custom error handling. When an error is caught, the customErrorHandler function captures and logs the call site information.

const callsiteRecord = require('callsite-record');

function customErrorHandler(err) {
  const record = callsiteRecord({ forError: err });
  console.log(record.renderSync());
}

try {
  throw new Error('Something went wrong');
} catch (err) {
  customErrorHandler(err);
}

Other packages similar to callsite-record

stack-trace

The stack-trace package provides a similar functionality by capturing and parsing stack traces in Node.js. It allows you to get detailed information about the call stack, including file names, line numbers, and function names. Compared to callsite-record, stack-trace offers more flexibility in terms of parsing and manipulating stack traces.

error-stack-parser

The error-stack-parser package is used to parse error stack traces into a more readable format. It is particularly useful for front-end applications where you need to display error information to users. While callsite-record focuses on capturing call site information, error-stack-parser is more about formatting and presenting error stack traces.

traceback

The traceback package provides utilities for capturing and formatting stack traces in Node.js. It offers similar functionalities to callsite-record, such as capturing call site information and formatting stack traces. However, traceback is more focused on providing a simple API for capturing and formatting stack traces without additional features like asynchronous support.

README

callsite-record

Create fancy log entries for errors and function call sites.

For Error:

'use strict';

const createCallsiteRecord = require('callsite-record');

function myFunc() {
    throw new Error('Yo!');
}

try {
    myFunc();
}
catch(err) {
    console.log(createCallsiteRecord(err).renderSync());
}

⬇

For function call up in the stack:

'use strict';

const createCallsiteRecord = require('callsite-record');

function func2 () {
    (function func1 () {
        console.log(createCallsiteRecord('func2').renderSync());
    })();
}

func2();

⬇

Additional goodies:

• Use renderers for different output formats, e.g. to produce output in HTML.
• Use stack filter to produce clean and beautiful stacks, e.g. removing Node lib internal calls.

Install

npm install callsite-record

API

createCallsiteRecord(error, [isCallsiteFrame]) → CallsiteRecord

You can generate a callsite for any stack frame, not only the topmost one. Use the isCallsiteFrame function to select a frame. This function is called for each frame starting from the top. Return true for the desired frame to generate the callsite.

Example:

const createCallsiteRecord = require('callsite-record');

try {
    throw new Error("We're doomed");
}
catch(err) {
    const record = createCallsiteRecord(err);
}

createCallsiteRecord(functionName, [typeName]) → CallsiteRecord

Creates CallsiteRecord for the function up in the call stack specified by functionName. You can optionally specify a typeName if the function is a method. If the function is a constructor set functionName to constructor.

Example:

const createCallsiteRecord = require('callsite-record');

(function func1() {
    (function func2() {
        (function func3() {
            const record = createCallsiteRecord('func2');
        })();
    })();
})();

CallsiteRecord

CallsiteRecord.render([renderOptions]) → Promise<String>

Renders call site record to the string.

Example:

record.render().then(str => console.log(str));

CallsiteRecord.renderSync([renderOptions]) → String

Sync version of the CallsiteRecord.render.

renderOptions.frameSize

Specifies the number of lines rendered above and below the call site in the code frame. Default: 5.

Example:

console.log(record.renderSync({ frameSize: 0 }));
// > 12 |    func1();
// ...

console.log(record.renderSync({ frameSize: 1 }));
//   11 |(function func2() {
// > 12 |    func1();
//   13 |})();
// ...

renderOptions.codeFrame

Specifies if code frame should be rendered. If disabled only stack will be rendered. Default: true.

renderOptions.stack

Specifies if stack trace should be rendered in addition to the code frame. Default: true.

renderOptions.stackFilter

Function that will be used to filter stack frames. Function accepts 2 arguments:

• stackFrame - stack entry.
• idx - index of the frame.
• isV8StackFrame - if true then stackFrame is a V8 CallSite object. Otherwise it's a StackFrame object.

Default: null.

Example:

const sep = require('path').sep;

// Remove node core lib calls from the stack trace
record.renderSync({ stackFilter: frame => frame.getFileName().indexOf(sep) > -1 });

renderOptions.renderer

Specifies the output format of the rendering. Default: renderers.default. You can pass your own renderer object (example implementations) or use one of the built-in renderers:

renderers.default

Provides ANSI-colored output as shown above.

Usage:

const defaultRenderer = require('callsite-record').renderers.default;

record.renderSync({ renderer: defaultRenderer });

renderers.noColor

Same as default renderer but without colors.

Usage:

const noColorRenderer = require('callsite-record').renderers.noColor;

record.renderSync({ renderer: noColorRenderer });

renderers.html

Outputs HTML that can be later decorated with the CSS and embeded into the web page. Example output.

Usage:

const htmlRenderer = require('callsite-record').renderers.html;

record.renderSync({ renderer: html });

Related

• is-es2016-keyword - Determine if string is an ES2016 keyword.
• highlight-es - Highlight ECMAScript syntax for the console or any other medium.

Author

Ivan Nikulin ([e-mail])