tracekit.javascript.txt

                                  ┏━━━━━━━━━━━━━━┓
                                  ┃   TRACEKIT   ┃
                                  ┗━━━━━━━━━━━━━━┛

ALTERNATIVES (PARSING) ==>        #See stacktrace.js

ALTERNATIVES (GENERATION) ==>     #  - tracekit (prefered if focus on old browsers)
                                  #     - good support for old browsers
                                  #  - stacktrace.js (prefered if Node/browser)
                                  #     - support for old IE
                                  #  - njstrace:
                                  #     - also add passed arguments and execution time
                                  #     - do it by monkey-patching require()
                                  #     - not well maintained

ALTERNATIVES (CONTEXT) ==>        #See better-stack-traces

VERSION ==>                       #0.4.7
                                  #Browser-only (focus on old browsers support)

                                  ┌────────────────┐
                                  │   GENERATION   │
                                  └────────────────┘

TRACEKIT.computeStackTrace        #CS

CS.ofCaller([NUM])                #Same as CS(new Error, NUM + 1)
CS(ERROR[, NUM])->STACK_OBJ       #Retrieves ERROR's STACK_OBJ, cross-browsers
                                  #Tries to:
                                  #  - 'stacktrace': parse ERROR.stacktrace (Opera 10/11)
                                  #  - 'stack': parse ERROR.stack
                                  #  - 'multiline': parse ERROR.message (Opera <9)
                                  #  - 'callers': use arguments.caller (old Safari/IE)
                                  #NUM is max depth when using 'callers' mode.
CS.computeStackTraceFromStackProp
 (ERROR)->'STACK'                 #Like CS() but only for 'stack' mode

STACK_OBJ.name                    #ERROR 'NAME'
STACK_OBJ.message                 #ERROR 'MESSAGE'
STACK_OBJ.stack                   #SCALL_ARR or (if 'failed') undefined
STACK_OBJ.mode                    #How stack was retrieved: 'stacktrace|stack|multiline|callers' or 'failed'

SCALL.url                         #'URI'
SCALL.func                        #'FUNC_NAME'
                                  #If absent, tries to guess it by using REGEXps at line NUM in file URI
                                  #Underlying function is CS.guessFunctionName('URI', NUM)->'FUNC|?'
SCALL.args                        #'VAR'_ARR
SCALL.line|column                 #NUM

CS.getSource('URI')->STR_ARR      #Perform HTTP request, then split on newlines
                                  #Used by CS.guessFunctionName() and CS.gatherContext()
                                  #Not performed if TRACEKIT.remoteFetching false (def: true)

                                  ┌─────────────┐
                                  │   CONTEXT   │
                                  └─────────────┘

SCALL.context                     #STR_ARR
                                  #Line of source code and surrounding lines
                                  #Underlying function is CS.guessContext('URI', LINE_NUM)->STR_ARR
                                  #Uses TRACEKIT.linesOfContext NUM2 (def: 11, i.e. 5 before|after)

                                  ┌────────────────────────┐
                                  │   EXCEPTION HANDLING   │
                                  └────────────────────────┘

TRACEKIT.subscribe                #Call FUNC on either:
 (FUNC(STACK_OBJ, BOOL, ERROR))   #  - TRACEKIT.report(ERROR)
                                  #     - BOOL false
                                  #     - wait for STACK_OBJ to be built (is async if CS.getSource() in process)
                                  #     - only use last ERROR if TRACEKIT.report() called several times in a row
                                  #  - WINDOW.onerror|onunhandledrection
                                  #     - BOOL true
                                  #     - handles old browsers
                                  #     - disabled by TRACEKIT.collectWindowErrors false (def: true)
TRACEKIT.unsubscribe(FUNC)        #
TRACEKIT.wrap(FUNC)->FUNC         #Add error handler that fires TRACEKIT.report() then rethrows
TRACEKIT.
 extendToAsynchronousCallbacks()  #Monkey patch setTimeout|setInterval(FUNC) so they call TRACEKIT.wrap(FUNC)