callsite-record

Create fancy log entries for errors and function call sites.

For Error:

1'use strict';
2
3const createCallsiteRecord = require('callsite-record');
4
5function myFunc() {
6    throw new Error('Yo!');
7}
8
9try {
10    myFunc();
11}
12catch(err) {
13    console.log(createCallsiteRecord({ forError: err }).renderSync());
14}
15

⬇

For function call up in the stack:

1'use strict';
2
3const createCallsiteRecord = require('callsite-record');
4
5function func2 () {
6    (function func1 () {
7        console.log(createCallsiteRecord({ byFunctionName: 'func2' }).renderSync());
8    })();
9}
10
11func2();

⬇

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( { forError, isCallsiteFrame, processFrameFn }) → 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:

1const createCallsiteRecord = require('callsite-record');
2
3try {
4    throw new Error("We're doomed");
5}
6catch(err) {
7    const record = createCallsiteRecord({ forError: err });
8}

createCallsiteRecord({ byFunctionName, typeName, processFrameFn }) → CallsiteRecord

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

Example:

1const createCallsiteRecord = require('callsite-record');
2
3(function func1() {
4    (function func2() {
5        (function func3() {
6            const record = createCallsiteRecord({ byFunctionName: 'func2' });
7        })();
8    })();
9})();

You can specify processFrameFn function, which will process every frame in callstack. It's usefull when you need to enable frame processing like source-maps-support.

Example:

1const createCallsiteRecord = require('callsite-record');
2const wrapCallSite         = require('source-map-support').wrapCallSite;
3
4try {
5    throw new Error("We're doomed");
6}
7catch(err) {
8    const record = createCallsiteRecord({ forError: err, processFrameFn: wrapCallSite });
9}
10
11(function func1() {
12    (function func2() {
13        (function func3() {
14            const record = createCallsiteRecord({ byFunctionName: 'func2', processFrameFn: wrapCallSite });
15        })();
16    })();
17})();

CallsiteRecord

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

Renders call site record to the string.

Example:

1record.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:

1console.log(record.renderSync({ frameSize: 0 }));
2// > 12 |    func1();
3// ...
4
5console.log(record.renderSync({ frameSize: 1 }));
6//   11 |(function func2() {
7// > 12 |    func1();
8//   13 |})();
9// ...

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:

1const sep = require('path').sep;
2
3// Remove node core lib calls from the stack trace
4record.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:

1const defaultRenderer = require('callsite-record').renderers.default;
2
3record.renderSync({ renderer: defaultRenderer });

renderers.noColor

Same as default renderer but without colors.

Usage:

1const noColorRenderer = require('callsite-record').renderers.noColor;
2
3record.renderSync({ renderer: noColorRenderer });

renderers.html

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

Usage:

1const htmlRenderer = require('callsite-record').renderers.html;
2
3record.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 (ifaaan@gmail.com)