-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathstacktrace.js.javascript.txt
172 lines (144 loc) · 10.5 KB
/
stacktrace.js.javascript.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
┏━━━━━━━━━━━━━━━━━━━┓
┃ STACKTRACE.JS ┃
┗━━━━━━━━━━━━━━━━━━━┛
ALTERNATIVES (PARSING) ==> #(preferred if not Node.js only)
# - stacktrace.js (prefered)
# - Node/browser (agnostic format)
# - tracekit (prefered if need old browser support and Browser-only)
# - browser-only (agnostic format)
# - focus on old browsers support
# - exception handling helpers
# - can show lines of context
#(preferred if Node.js only)
# - callsites (prefered if need minimalistic for current location):
# - Node/Chrome (V8 CALL_ARR)
# - very thin wrapper around Error.prepareStackTrace()
# - error-callsites (prefered if need minimalistic for any error):
# - Node/Chrome (V8 CALL_ARR)
# - very thin wrapper around Error.prepareStackTrace()
# - stackman (prefered if need normalized stack traces):
# - Node/Chrome (V8 CALL_ARR)
# - source map support
# - normalize CALL_ARR
# - can show lines of context
# - node-stack-trace (prefered if need easy way to parse stringified stack)
# - Node/Chrome (V8 CALL_ARR)
# - can parse stringified stack
# - not well maintained
# - stack-utils (prefered if need accurate way to parse stringified stack or need to control stack trace limit)
# - Node/Chrome (V8 CALL_ARR)
# - can parse stringified stack
# - not well maintained
# - stack-chain
# - Node/Chrome (V8 CALL_ARR)
# - good support for filtering|mapping CALLs
# - stackback:
# - Node/Chrome (V8 CALL_ARR)
# - thin wrapper around Error.prepareStackTrace()
# - not maintained
ALTERNATIVES (GENERATION) ==> #See tracekit
ALTERNATIVES (SOURCE MAP) ==> #See node-source-map-support
VERSION ==> #2.0.1
GOAL ==> # - parse ERROR.stack into OBJ_ARR (Node/browser)
# - source map support for stack traces (browser only)
# - retrieve stack trace in old IE lacking ERROR.stack (browser only)
┌──────────┐
│ CORE │
└──────────┘
get([OPTS])->PROMISE_FRAME_ARR #Retrieve current stack as FRAME_ARR
#Automatically translate locations using source maps (see below)
#Calls either:
# - if current browser supports ERROR.stack: fromError(new Error, OPTS)
# - otherwise: generateArtificially(OPTS)
getSync([OPTS])->FRAME_ARR #Same but sync and does not call STACKTRACE-GPS() (i.e. no source maps handling)
fromError(ERROR[, OPTS]) #Same as:
->PROMISE_FRAME_ARR # - ERROR-STACK-PARSER.parse() (see below)
# - new STACKTRACE-GPS(OPTS) + GPS.pinpoint() on each FRAME
generateArtificially([OPTS])
->PROMISE_FRAME_ARR #Same as STACK-GENERATOR.backtrace() (see below)
OPTS.filter #Apply FRAME_ARR.filter(FUNC) for any of the above functions
#Def: removes function of stacktrace.js library itself
instrument(FUNC, FUNC2(FRAME_ARR),#Calls FUNC2(FRAME_ARR) (or FUNC3 is problem):
FUNC3(ERROR)[, THIS])->FUNC # - each time FUNC(...) is called (using get())
# - each time FUNC(...) throws an ERROR (using fromError(ERROR)) (except on old browsers)
deinstrument(FUNC)->FUNC #Removes
report(FRAME_ARR, 'URI'[, STR] #Sends an HTTP request (using XMLHttpRequest, i.e. only in browsers) to URI
[, XHR_OPTS]) #with JSON payload { stack: FRAME_ARR, message STR }.
#Can set XHR_OPTS.headers OBJ
┌───────────┐
│ FRAME │
└───────────┘
STACKFRAME ==> #Version 1.3.4
#Abstraction of a stack trace single line.
new StackFrame([OPTS]) #By default its members have no logic except toString(), i.e. what's documented here
#is only the intended meaning for calling code.
#OPTS:
# - source STR: original stack stack single line
# - fileName 'URI|PATH'
# - functionName 'FUNC' (def during toString(): '<anonymous>')
# - args 'VAR'_ARR: function parameters
# - lineNumber NUM
# - columnNumber NUM
# - isConstructor BOOL: called with new
# - isEval BOOL: called with eval() (or equivalent)
# - evalOrigin FRAME2: if eval(), parent FRAME
# - isNative BOOL: C/C++ bindings
# - isTopLevel BOOL
FRAME.get*()->VAL #Getter for each OPT
FRAME.set*(VAL) #Setter for each OPT
FRAME.toString()->STR #Returns 'FUNCTION_NAME(ARG,...)[@FILENAME][:LINE][:COLUMN]'
StackFrame.fromString(STR)->FRAME #
┌────────────┐
│ PARSER │
└────────────┘
ERROR-STACK-PARSER ==> #3.0.0
#Parses ERROR.stack to FRAME_ARR
parse(ERROR)->FRAME_ARR #Gets FRAME_ARR from ERROR.stack
#FRAME has (each optional): source, fileName, functionName, args, lineNumber, columnNumber
#Automatically detect whether on IE, Chrome, Firefox, Safari, Opera or Node
┌───────────────┐
│ GENERATOR │
└───────────────┘
STACK-GENERATOR ==> #Version 2.0.10
#Retrieve current stack trace.
#Does not work well with strict mode, i.e. only meant as a fallback of ERROR-STACK-PARSER for
#old IE that lacks ERROR.stack
backtrace([OPTS])->FRAME_ARR #Get current stack trace as FRAME_ARR (with functionName and args)
#Use arguments.callee then iterate over arguments.caller:
# - i.e. first parent function in 'strict mode' will stop iteration
#OPTS:
# - maxStackSize NUM (def: 10)
┌─────────────────┐
│ SOURCE MAPS │
└─────────────────┘
STACKTRACE-GPS ==> #3.1.2
#Source map support in stack traces
#Browser only
new STACKTRACE-GPS([OPTS]) #
FRAME.fileName|functionName|
args|lineNumber|columnNumber #Are the only members kept in the methods below
GPS.pinpoint(FRAME)
->PROMISE_FRAME #Same as getMappedLocation() + findFunctionName()
GPS.getMappedLocation(FRAME) #Modifies FRAME.fileName|functionName|lineNumber|columnNumber from compiled to source file's position.
->PROMISE_FRAME #Do it by:
# - fetching FRAME.fileName
# - retrieving source map sourceMappingURL (must exist)
# - fetching source map (if normal URI) or decode it (if data URI)
# - parsing it with mozilla source-map's CONSUMER.originalPositionFor() (see its doc)
GPS.findFunctionName(FRAME) #Modifies FRAME.functionName using source map's information
->PROMISE_FRAME #Do it by:
# - fetching FRAME.fileName
# - guess in which function a specific FRAME is by applying REGEXPs on source code
OPTS.sourceMapConsumerCache #OBJ (def: {}):
#Customize cache for source map parsing
OPTS.sourceCache #OBJ (def: {}):
#Customize cache for HTTP requests
OPTS.offline #BOOL (def: false):
#Forces using sourceCache instead of making HTTP requests
#I.e. OPTS.sourceCache must be already filled
OPTS.ajax #FUNC('URI')->PROMISE_STR:
#Customize HTTP request
#Def: use XMLHttpRequest (i.e. does not work in Node)
OPTS.atob #FUNC('BASE64')->STR:
#Customize base64 decoding
#Def: use window.atob() (i.e. does not work in Node)