ESTrace

Trace functions in Node.js EcmaScript Modules. For CommonJS use njsTrace.

Install

npm i estrace

Run

Loaders used to get things done, run with --loader flag:

NODE_OPTIONS="'--loader estrace --no-warnings'" node lint.js

Perf

When you want to see report of the most hot function calls count use:

NODE_OPTIONS="'--loader estrace/perf --no-warnings'" node example/perf.js

Example

Let's suppose you want to trace lint.js:

const checkFile = (a) => a;
lint();

function lint(runners) {
    const files = getFiles(runners);
    const checkedFiles = checkFiles(files);
    
    return checkedFiles;
}

function getFiles(runners) {
    const files = [];
    
    for (const run of runners) {
        files.push(...run());
    }
    
    return files;
}

function lintFiles(files) {
    const linted = [];
    
    for (const file of files) {
        linted.push(checkFile(file));
    }
    
    return linted;
}

You will see something like this

coderaiser@cloudcmd:~/estrace$ node --loader estrace example/lint.js
..💣 lint([]) 16.05mb file:///Users/coderaiser/estrace/example/lint.js:5
....💣 getFiles([]) 16.05mb file:///Users/coderaiser/estrace/example/lint.js:12
....💥 getFiles 16.06mb file:///Users/coderaiser/estrace/example/lint.js:12
....💣 lintFiles([]) 16.06mb file:///Users/coderaiser/estrace/example/lint.js:22
....💥 lintFiles 16.06mb file:///Users/coderaiser/estrace/example/lint.js:22
..💥 lint 16.06mb file:///Users/coderaiser/estrace/example/lint.js:5

How ESTrace works?

Let's suppost you have a function: const fn = (a) => a. EStrace will replace it with:

const fn = (a) => {
    try {
        var __estrace_context = __estrace.enter('<anonymous:2>', 'file://hello.js:2', arguments);
        return a;
    } finally {
        __estrace.exit('<anonymous:2>', 'file://hello.js:2', __estrace_context);
    }
};

And you cat get more information about the way your code works.

Ignore function

When you need to ignore a function, just add __estrace.ignore() before function:

export /* __estrace.ignore() */
function enter() {}

And ESTrace won't touch it.

Using as plugin

First of all ESTrace is plugin for 🐊Putout and it can be used independely:

import putout from 'putout';
import {estracePlugin} from 'estrace/plugin';

const source = `
    const fn = (a) => a;
`;

const {code} = putout(source, {
    plugins: [estracePlugin],
});

console.log(code);

Passing file url

If you need to pass url, you can with help of rules :

const {code} = putout(source, {
    rules: {
        'estrace/trace': ['on', {
            url: 'file://hello.js',
        }],
    },
    plugins: [estracePlugin],
});

Exclude functions

When you need to exclude some kinds of functions, you can use universal cross-plugin way:

const {code} = putout(source, {
    rules: {
        'estrace/trace': ['on', {
            url: 'file://hello.js',
            exclude: [
                'ArrowFunctionExpression',
            ],
        }],
    },
    plugins: [estracePlugin],
});

Overriding plugin name

If for some reason you need to override the name of a plugin, you can use default import and name it in a way you like.

import putout from 'putout';
import funnyTracer from 'estrace/plugin';

const source = `
    const fn = (a) => a;
`;

const {code} = putout(source, {
    rules: {
        'funnyTracer/trace': ['on', {
            url: 'file://hello.js',
        }],
    },
    plugins: [
        ['funnyTracer', funnyTracer],
    ],
});

console.log(code);

Supported function types:

— FunctionDeclaration (named):

function hello() {
    return 'world';
}

— FunctionExpression (anonymous):

hello(function(word) {
    return `hello ${word}`;
});

— ArrowFunctionExpression (arrow):

hello((word) => {
    return `hello ${word}`;
});

— ClassMethod (method):

class Hello {
    hello(word) {
        return `hello ${word}`;
    }
}

License

MIT