Skip to content

Commit 17cc2e9

Browse files
oliversalzburgoliversalzburg
committed
Preparing for 1.0
1 parent cf6c1e3 commit 17cc2e9

File tree

4 files changed

+174
-67
lines changed

4 files changed

+174
-67
lines changed

‎MIGRATION_GUIDE.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Migrating from v0.x to v1.x
2+
3+
In version 1.x, We've switched from a *synchronous* API to an *asynchronous* one using [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
4+
because synchronous ajax calls are [deprecated](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests#Synchronous_request)
5+
and frowned upon due to performance implications.
6+
7+
> **HEADS UP:** StackTrace.JS does *NOT* provide a Promises polyfill by default, but we do distribute a [version with polyfills](https://raw.githubusercontent.com/stacktracejs/stacktrace.js/master/dist/stacktrace-with-polyfills.min.js)!
8+
> Check [the Promises page on caniuse.com](http://caniuse.com/#feat=promises) to determine if you need one.
9+
10+
All methods now return [stackframe](https://github.com/stacktracejs/stackframe)s.
11+
This Object representation is modeled closely after StackFrame representations in Gecko and V8.
12+
All you have to do to get stacktrace.js v0.x behavior is call `.toString()` on a stackframe.
13+
14+
### Use Case: Give me a trace from wherever I am right now
15+
16+
v0.x:
17+
```js
18+
printStackTrace();
19+
=> Array[String]
20+
```
21+
22+
v1.x:
23+
```js
24+
StackTrace.get().then(callback).catch(errback);
25+
=> Promise(Array[StackFrame], Error)
26+
```
27+
28+
`StackTrace.get()` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
29+
30+
### Use Case: Parse this error
31+
32+
33+
v0.x:
34+
```js
35+
var error = new Error('Boom');
36+
printStackTrace({e: error});
37+
=> Array[String]
38+
```
39+
40+
v1.x:
41+
```js
42+
var error = new Error('Boom');
43+
StackTrace.fromError(error).then(callback).catch(errback);
44+
=> Promise(Array[StackFrame], Error)
45+
```
46+
47+
If this is all you need, you don't even need the full stacktrace.js library! Just use [error-stack-parser](https://github.com/stacktracejs/error-stack-parser)!
48+
```js
49+
ErrorStackParser.parse(new Error('boom'));
50+
```
51+
52+
### Use Case: Give me a trace anytime this function is called
53+
54+
Instrumenting now takes `Function` references instead of `String`s.
55+
56+
v0.x:
57+
```js
58+
function interestingFn() {...};
59+
60+
var p = new printStackTrace.implementation();
61+
p.instrumentFunction(this, 'interestingFn', logStackTrace);
62+
=> Function (instrumented)
63+
64+
p.deinstrumentFunction(this, 'interestingFn');
65+
=> Function (original)
66+
```
67+
68+
v1.x:
69+
```js
70+
function interestingFn() {...};
71+
72+
StackTrace.instrument(interestingFn, callback, errback);
73+
=> Function (instrumented)
74+
75+
StackTrace.deinstrument(interestingFn);
76+
=> Function (original)
77+
```

‎README.md‎

Lines changed: 72 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
stacktrace.js
2-
===============
3-
[![Build Status](https://travis-ci.org/stacktracejs/stacktrace.js.svg?branch=master)](https://travis-ci.org/stacktracejs/stacktrace.js) [![Coverage Status](https://img.shields.io/coveralls/stacktracejs/stacktrace.js.svg)](https://coveralls.io/r/stacktracejs/stacktrace.js?branch=master) [![Code Climate](https://codeclimate.com/github/stacktracejs/stacktrace.js/badges/gpa.svg)](https://codeclimate.com/github/stacktracejs/stacktrace.js)
1+
# stacktrace.js
2+
## Framework-agnostic, micro-library for getting stack traces in all web browsers
3+
<p class="shields">[![Build Status](https://travis-ci.org/stacktracejs/stacktrace.js.svg?branch=master)](https://travis-ci.org/stacktracejs/stacktrace.js) [![Coverage Status](https://img.shields.io/coveralls/stacktracejs/stacktrace.js.svg)](https://coveralls.io/r/stacktracejs/stacktrace.js?branch=master) [![Code Climate](https://codeclimate.com/github/stacktracejs/stacktrace.js/badges/gpa.svg)](https://codeclimate.com/github/stacktracejs/stacktrace.js)</p>
44

5-
A JavaScript tool that allows you to debug your JavaScript by giving you a [stack trace](http://en.wikipedia.org/wiki/Stack_trace) of function calls leading to an error (or any condition you specify).
5+
Debug and profile your JavaScript with a [stack trace](http://en.wikipedia.org/wiki/Stack_trace) of function calls leading to an error (or any condition you specify).
66

7-
The promises referenced below are [ES6-Promises](https://github.com/jakearchibald/es6-promise).
7+
stacktrace.js uses browsers' `Error.stack` mechanism to generate stack traces, parses them, enhances them with
8+
[source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) and uses
9+
[Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
10+
to return an Array of [StackFrames](https://github.com/stacktracejs/stackframe).
11+
12+
#### Upgrading? Check the [0.x -> 1.x Migration Guide](http://www.stacktracejs.com/docs/v0-migration-guide)
813

914
## Usage
15+
#### Get a stack trace from current location
1016
```js
1117
var callback = function(stackframes) {
1218
var stringifiedStack = stackframes.map(function(sf) {
@@ -17,19 +23,39 @@ var callback = function(stackframes) {
1723

1824
var errback = function(err) { console.log(err.message); };
1925

20-
StackTrace.get().then(callback, errback)
21-
=> Promise(Array[StackFrame](https://github.com/stacktracejs/stackframe), Error)
26+
StackTrace.get().then(callback).catch(errback)
27+
=> Promise(Array[StackFrame], Error)
2228
=> callback([StackFrame('func1', [], 'file.js', 203, 9), StackFrame('func2', [], 'http://localhost:3000/file.min.js', 1, 3284)])
29+
```
30+
31+
#### window.onerror integration
32+
Automatically handle errors
33+
```js
34+
window.onerror = function(msg, file, line, col, error) {
35+
// callback is called with an Array[StackFrame]
36+
StackTrace.fromError(error).then(callback).catch(errback);
37+
};
38+
```
2339

24-
// Somewhere else...
40+
#### Get stack trace from an Error
41+
```js
2542
var error = new Error('BOOM!');
2643

27-
StackTrace.fromError(error).then(callback, errback)
28-
=> Promise(Array[StackFrame](https://github.com/stacktracejs/stackframe), Error)
44+
StackTrace.fromError(error).then(callback).catch(errback)
45+
=> Promise(Array[StackFrame], Error)
46+
```
2947

30-
StackTrace.generateArtificially().then(callback, errback)
31-
=> Promise(Array[StackFrame](https://github.com/stacktracejs/stackframe), Error)
48+
#### Generate a stacktrace from walking arguments.callee
49+
This might capture arguments information, but isn't supported in ES5 strict-mode
50+
```js
51+
StackTrace.generateArtificially().then(callback).catch(errback)
52+
=> Promise(Array[StackFrame], Error)
53+
```
3254

55+
#### Trace every time a given function is invoked
56+
```js
57+
// callback is called with an Array[StackFrame] every time
58+
// the wrapped interestingFn is called
3359
StackTrace.instrument(interestingFn, callback, errback)
3460
=> Instrumented Function
3561

@@ -41,43 +67,50 @@ StackTrace.deinstrument(interestingFn)
4167
```
4268
npm install stacktrace-js
4369
bower install stacktrace-js
44-
https://rawgithub.com/stacktracejs/stacktrace.js/master/dist/stacktrace.min.js
70+
https://cdnjs.cloudflare.com/ajax/libs/stacktrace.js/1.0.0/stacktrace.min.js
4571
```
4672

47-
### stacktrace.js is available on cdnjs.com
48-
https://cdnjs.com/libraries/stacktrace.js
49-
50-
`//cdnjs.cloudflare.com/ajax/libs/stacktrace.js/0.6.4/stacktrace.min.js`
51-
5273
## API
5374

54-
#### `StackTrace.get(/*optional*/ options)` => Promise(Array[StackFrame])
75+
#### `StackTrace.get(/*optional*/ options)` => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)(Array[[StackFrame](https://github.com/stacktracejs/stackframe)])
5576
Generate a backtrace from invocation point, then parse and enhance it.
56-
options: Object
57-
* **sourceCache: Object (String URL => String Source)** - Pre-populate source cache to avoid network requests
58-
* **offline: Boolean (default: false)** - Set to `true` to prevent all network requests
77+
78+
**(Optional) options: Object**
79+
* *filter: Function([StackFrame](https://github.com/stacktracejs/stackframe) => Boolean)* - Only include stack entries matching for which `filter` returns `true`
80+
* *sourceCache: Object (String URL => String Source)* - Pre-populate source cache to avoid network requests
81+
* *offline: Boolean (default: false)* - Set to `true` to prevent all network requests
5982

60-
#### `StackTrace.fromError(error, /*optional*/ options)` => Promise(Array[StackFrame])
83+
#### `StackTrace.fromError(error, /*optional*/ options)` => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)(Array[[StackFrame](https://github.com/stacktracejs/stackframe)])
6184
Given an Error object, use [error-stack-parser](https://github.com/stacktracejs/error-stack-parser)
62-
to parse it and enhance location information with [stacktrace-gps](https://github.com/stacktracejs/stacktrace-gps).
63-
* **sourceCache: Object (String URL => String Source)** - Pre-populate source cache to avoid network requests
64-
* **offline: Boolean (default: false)** - Set to `true` to prevent all network requests
85+
to parse it and enhance location information with [stacktrace-gps](https://github.com/stacktracejs/stacktrace-gps).
86+
87+
**error: Error**
88+
89+
**(Optional) options: Object**
90+
* *filter: Function([StackFrame](https://github.com/stacktracejs/stackframe) => Boolean)* - Only include stack entries matching for which `filter` returns `true`
91+
* *sourceCache: Object (String URL => String Source)* - Pre-populate source cache to avoid network requests
92+
* *offline: Boolean (default: false)* - Set to `true` to prevent all network requests
6593

66-
#### `StackTrace.generateArtificially(/*optional*/ options)` => Promise(Array[StackFrame])
94+
#### `StackTrace.generateArtificially(/*optional*/ options)` => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)(Array[[StackFrame](https://github.com/stacktracejs/stackframe)])
6795
Use [stack-generator](https://github.com/stacktracejs/stack-generator) to generate a backtrace by walking the `arguments.callee.caller` chain.
68-
* **sourceCache: Object (String URL => String Source)** - Pre-populate source cache to avoid network requests
69-
* **offline: Boolean (default: false)** - Set to `true` to prevent all network requests
96+
97+
**(Optional) options: Object**
98+
* *filter: Function([StackFrame](https://github.com/stacktracejs/stackframe) => Boolean)* - Only include stack entries matching for which `filter` returns `true`
99+
* *sourceCache: Object (String URL => String Source)* - Pre-populate source cache to avoid network requests
100+
* *offline: Boolean (default: false)* - Set to `true` to prevent all network requests
70101

71102
#### `StackTrace.instrument(fn, callback, /*optional*/ errback)` => Boolean
72103
Call callback with a _stack trace_ anytime `fn` is called. Returns `true` if given Function is successfully instrumented
73-
* **fn** - Function to wrap, call callback on invocation and call-through
74-
* **callback** - Function to call with stack trace (generated by `StackTrace.get()`) when fn is called
75-
* **errback** - (Optional) Function to call with Error object if there was a problem getting a stack trace.
104+
105+
* **fn: Function** - to wrap, call callback on invocation and call-through
106+
* **callback: Function** - to call with stack trace (generated by `StackTrace.get()`) when fn is called
107+
* **(Optional) errback: Function** - to call with Error object if there was a problem getting a stack trace.
76108
Fails silently (though `fn` is still called) if a stack trace couldn't be generated.
77109

78110
#### `StackTrace.deinstrument(fn)` => Boolean
79-
Remove StackTrace instrumentation on `fn`. Returns `true` if deinstrumentation succeeds.
80-
* **fn** - Previously wrapped Function
111+
Remove StackTrace instrumentation on `fn`. Returns `true` if de-instrumentation succeeds.
112+
113+
* **fn: Function** - Previously wrapped Function
81114

82115
## Browser Support
83116
* Chrome 1+
@@ -88,21 +121,19 @@ Remove StackTrace instrumentation on `fn`. Returns `true` if deinstrumentation s
88121
* iOS 7+
89122
* Android 4.0+
90123

91-
_NOTE: You won't get the benefit of [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/)
92-
in IE9- or other very old browsers._
124+
> **HEADS UP**: You won't get the benefit of [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/)
125+
in IE9- or other very old browsers.
93126

94127
## Using node.js/io.js only?
95-
I recommend the [stack-trace node package](https://www.npmjs.com/package/stack-trace).
128+
I recommend the [stack-trace node package](https://www.npmjs.com/package/stack-trace) specifically built for node.
96129
It has a very similar API and also supports source maps.
97130

98131
## Contributing
99-
Want to be listed as a *Contributor*? Start with the [Contributing Guide](CONTRIBUTING.md)!
132+
Want to be listed as a *Contributor*? Start with the [Contributing Guide](https://github.com/stacktracejs/stacktrace.js/blob/master/CONTRIBUTING.md)!
100133

101134
This project is made possible due to the efforts of these fine people:
102135

103136
* [Eric Wendelin](http://www.eriwen.com)
104137
* [Victor Homyakov](https://github.com/victor-homyakov)
138+
* [Oliver Salzburg](https://github.com/oliversalzburg)
105139
* [Many others](https://github.com/stacktracejs/stacktrace.js/graphs/contributors)
106-
107-
## License
108-
This project is licensed to the [Public Domain](http://unlicense.org)

‎karma.conf.ci.js‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,12 @@ module.exports = function (config) {
6262
platform: 'Windows 8.1',
6363
version: '11'
6464
},
65-
//slIE10: {
66-
// base: 'SauceLabs',
67-
// browserName: 'internet explorer',
68-
// platform: 'Windows 8',
69-
// version: '10'
70-
//}
65+
slIE10: {
66+
base: 'SauceLabs',
67+
browserName: 'internet explorer',
68+
platform: 'Windows 8',
69+
version: '10'
70+
}
7171
//slIE9: {
7272
// base: 'SauceLabs',
7373
// browserName: 'internet explorer',
@@ -79,13 +79,13 @@ module.exports = function (config) {
7979
// browserName: 'internet explorer',
8080
// platform: 'Windows XP',
8181
// version: '8'
82-
//},
83-
slIE7: {
84-
base: 'SauceLabs',
85-
browserName: 'internet explorer',
86-
platform: 'Windows XP',
87-
version: '7'
88-
}
82+
//}
83+
//slIE7: {
84+
// base: 'SauceLabs',
85+
// browserName: 'internet explorer',
86+
// platform: 'Windows XP',
87+
// version: '7'
88+
//}
8989
//slIE6: {
9090
// base: 'SauceLabs',
9191
// browserName: 'internet explorer',
@@ -98,8 +98,8 @@ module.exports = function (config) {
9898
basePath: '',
9999
frameworks: ['jasmine', 'sinon'],
100100
files: [
101-
'polyfills.js',
102101
'node_modules/es6-promise/dist/es6-promise.js',
102+
'polyfills.js',
103103
'node_modules/stacktrace-gps/dist/stacktrace-gps.min.js',
104104
'node_modules/error-stack-parser/dist/error-stack-parser.js',
105105
'node_modules/stack-generator/dist/stack-generator.js',

‎package.json‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
"dependencies": {
2424
"error-stack-parser": "~1.2",
2525
"stack-generator": "~1",
26-
"stacktrace-gps": "~2.1"
26+
"stacktrace-gps": "~2"
2727
},
2828
"devDependencies": {
2929
"colors": "^1.1.2",
@@ -37,19 +37,18 @@
3737
"gulp-uglify": "^1.2.0",
3838
"jasmine-node": "~1.14",
3939
"jasmine-sinon": "^0.4.0",
40-
"karma": "~0.12",
41-
"karma-chrome-launcher": "^0.1.5",
42-
"karma-coverage": "^0.2.6",
43-
"karma-firefox-launcher": "^0.1.3",
44-
"karma-ie-launcher": "^0.1.5",
40+
"karma": "^0.13.9",
41+
"karma-chrome-launcher": "^0.2.0",
42+
"karma-coverage": "^0.5.0",
43+
"karma-firefox-launcher": "^0.1.6",
44+
"karma-ie-launcher": "^0.2.0",
4545
"karma-jasmine": "^0.1.5",
46-
"karma-opera-launcher": "^0.1.0",
47-
"karma-phantomjs2-launcher": "^0.3.1",
46+
"karma-opera-launcher": "^0.3.0",
47+
"karma-phantomjs2-launcher": "^0.3.2",
4848
"karma-safari-launcher": "^0.1.1",
49-
"karma-sauce-launcher": "^0.2.10",
50-
"karma-sinon": "^1.0.3",
51-
"run-sequence": "^1.1.2",
52-
"sinon": "^1.2.22"
49+
"karma-sauce-launcher": "^0.2.14",
50+
"karma-sinon": "^1.0.4",
51+
"run-sequence": "^1.1.2"
5352
},
5453
"bugs": {
5554
"url": "https://github.com/stacktracejs/stacktrace.js/issues"

0 commit comments

Comments
 (0)