Nasty Popsicle Machine

    traceback
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/traceback package

    0.3.1 • Public • Published

    Traceback: easy access to the call stack, for Node.js

    Writing a Node app? Need to know the function backtrace? Don't want to compile C++ code? Use Traceback.

    Traceback provides a normal JavaScript array of the execution stack frames. You can see function names, line numbers, and other useful stuff.

    Traceback is available from NPM.

    $ npm install traceback
    

    Example

    example.js

    var traceback = require('../traceback');
     
    function start() { first() }
    function first() { second() }
    var second = function() { last() }
     
    function last() {
      var stack = traceback();
      console.log('I am ' + stack[0].name + ' from file ' + stack[0].file)
     
      for(var i = 1; i <= 3; i++)
        console.log('  ' + i + ' above me: ' + stack[i].name + ' at line ' + stack[i].line);
    }
     
    start();

    Output:

    I am last from file example.js
      1 above me: second at line 5
      2 above me: first at line 4
      3 above me: start at line 3
    

    Usage

    Simply calling traceback() gives you the stack, with the current function in position 0.

    Stack frame objects have normal V8 CallSite objects as prototypes. All those methods will work. You can also call traceback.raw() to get the exact stack made by V8.

    But traceback()'s stack frame objects have convenient attribute names:

    • name | The function name
    • path | The absolute path of the file defining the function
    • file | The basename of the path file ("example.js")
    • line | The line number in the file
    • col | The column number in the file
    • pos | The byte position in the file
    • fun | The function itself
    • method | If this function was called as a method, the name it is stored as
    • this | The object bound to the label this in the function
    • type | The type of this; the name of the constructor function (Object, ReadStream, etc.)
    • origin | The CallSite that ran eval(), if this frame is an eval
    • is_top | Boolean indicating whether the function was called with a global this
    • is_eval | Boolean indicating whether the function comes from an eval() call
    • is_native | Boolean indicating whether the function is native
    • is_ctor | Boolean indicating whether this is a constructor (new) call

    They also work correctly in JSON.stringify().

    Tests

    Tests use node-tap. Clone this Git repository, run npm install and then run the tests through npm:

    $ npm test
    
    > traceback@0.3.1 test /Users/jhs/src/traceback
    > tap test/
    
    ok test/api.js ...................................... 326/326
    ok test/fail.js ....................................... 36/36
    ok test/format.js ....................................... 7/7
    ok test/readme.js ....................................... 2/2
    total ............................................... 371/371
    
    ok
    

    License

    Apache 2.0

    Install

    npm i traceback

    DownloadsWeekly Downloads

    267

    Version

    0.3.1

    License

    none

    Last publish

    Collaborators

    • jhs