stack-tracer
Global access to all CallSite/Stack Trace Properties and more
Install
npm install stack-tracer
or
npm install -g stack-tracer
Then import the module into your program:
var trace = ;
Background
A Stack is a list of all active functions within the program in the order they were invoked
Every time a function is invoked, a corresponding CallSite Object is created and added to the Stack
- This CallSite Object contains information regarding the location and context of the invocation
Whenever a function returns, the CallSite corresponding to the invocation is removed from the Stack Trace
This module uses a common method of capturing the raw Stack Trace (an Array of CallSite Objects)
It then creates a Tracer Object containing information about a specific CallSite
Read more about the V8 Stack Trace/CallSite API here
Usage
A Tracer Object can be created multiple ways:
- Explicitly by invoking the module export
- Implicitly by invoking one of the global properties the module creates
- From an Error
Explicit
A Tracer Object can be created by invoking the exported function:
trace( [index] )
index
- The index of the CallSite that the Tracer Object should be based on- An empty input or input of
0
will correspond to the immediate (this) invocation
- An empty input or input of
It contains the following properties:
callSite
- The corresponding CallSite Object
stack
- The raw Stack Trace starting from the corresponding CallSite object
trace
- This Tracer Object (self-referencing)
fileName
- The name of the file where the invocation is defined
isNative
- Does the invocation occur within Native V8 code?
line
- The line number of the invocation within the file
column
- The column number of the invocation within the file
var trace = ; var myTracer = ; //or trace(0);//myTracer.line = 3//myTracer.column = 16 { return ;} myTracer = ;//myTracer.line = 8//myTracer.column = 10
this
- The
this
value in the context of the invocation
typeName
- The type of
this
as a String
var trace = ; var myTracer = ;//myTracer.this = this//myTracer.typeName = 'Object' var myContext = ;{ return ;} myTracer = getTracer;//myTracer.this = myContext//myTracer.typeName = 'Array'
function
- The function where the invocation occurred
functionName
- The name of the function as a String
var trace = ; var myTracer = ;//myTracer.function = <<this entire script>>//myTracer.functionName = null { return ;} myTracer = ;//myTracer.function = getTracer//myTracer.functionName = 'getTracer'
methodName
- The name of the property within
this
which maps to the function where the invocation occurred
var trace = ; var myTracer = ;//myTracer.methodName = null var myObj = { return ; } myTracer = myObj;//myTracer.this = myObj//myTracer.function = myObj.get//myTracer.functionName = 'myObj.get'//myTracer.methodName = 'get' //Function can be named:myObj = { return ; } myTracer = myObj;//myTracer.functionName = 'getTracer'
isTopLevel
- Is
this
theglobal
object?
var trace = ; var myTracer = ;//myTracer.isToplevel = true { return ;} myTracer = ;//myTracer.isToplevel = true myTracer = getTracer;//myTracer.isToplevel = false
isEval
- Does the invocation occur within an eval statement?
evalOrigin
- String representing the CallSite of the
eval
function where the invocation was defined
var trace = ; var myTracer = ;//myTracer.isEval = true { return ;} myTracer = ;//myTracer.isEval = true ;myTracer = ;//myTracer.isEval = true
isConstructor
- Does the invocation occur with a function invoked as a constructor?
var trace = ; var myTracer = ;//myTracer.isConstructor = false { return ;} myTracer = ;//myTracer.isConstructor = false myTracer = ;//myTracer.isConstructor = true
caller
- The Tracer corresponding to the CallSite one level above this CallSite in the Stack Trace
- i.e. the function that called this function
- Will be null if no caller exists
var trace = ; var myTracer = ;//myTracer.function = <<this entire script>>//myTracer.functionName = null { return caller; //or trace(1)} myTracer = ;//myTracer.function = <<this entire script>>//myTracer.functionName = null
callee
- The Tracer corresponding to the CallSite one level below this CallSite in the Stack Trace
- i.e. the function that this function called
- Will be null if no callee exists
var trace = ; var myTracer = ;//myTracer.callee = null { return caller;} myTracer = ;//myTracer.callee.function = getTracer//myTracer.callee.functionName = 'getTracer'
Implicit
The module also adds a number of global properties which implicitly create a Tracer object at that location and return the corresponding property
It is the equivalent of invoking trace().<property>
The properties are all of the above properties, prefixed with '__':
__callSite
- A CallSite Object for this invocation
__stack
- A raw Stack Trace Array starting from the corresponding CallSite object
__trace
- A Tracer Object for this invocation
__caller
- The Tracer corresponding to the CallSite one level above this CallSite in the Stack Trace
- i.e. the function that called this function
- Will be null if no caller exists
__callee
- The Tracer corresponding to the CallSite one level below this CallSite in the Stack Trace
- i.e. the function that this function called
- Will be null if no callee exists
__fileName
- The name of the file where the invocation is defined
__line
- The line number of the invocation within the file
__column
- The column number of the invocation within the file
__this
- The
this
value in the context of the invocation
__typeName
- The type of
this
as a String
__function
- The function where the invocation occurred
__functionName
- The name of the function as a String
__methodName
- The name of the property within
this
which maps to the function where the invocation occurred
__evalOrigin
- String representing the CallSite of the
eval
function where the invocation was defined
__isToplevel
- Is
this
theglobal
object?
__isEval
- Does the invocation occur within an eval statement?
__isNative
- Does the invocation occur within Native V8 code?
__isConstructor
- Does the invocation occur with a function invoked as a constructor?
var trace = ; __line //3, same as trace().line__column //1, same as trace().column { if __isConstructor return __caller //same as trace().caller or trace(1) else return __trace //same as trace().trace or trace()} var myTracer = ;//myTracer.line = 8//myTracer.column = 15 myTracer = ;//myTracer.line = 15//myTracer.column = 11
From an Error
Every Error has a __stack property which contains the raw Stack Trace Array.
Note - The Error.stack
property must be requested in order to invoke the creation of the __stack property
A Tracer Object can then be created from an Error by invoking the following:
trace.from( error )
error
- The Error Object that the Tracer Object should be based on
var trace = ; var err = ;//error.__stack = undefined errstack; //invoke the creation of the stack trace array//err.__stack = <<Array of CallSites>> var myTracer = trace;//myTracer.line = 3//myTracer.column = 11