AK-21/Graphite-Industrial-Intelligence

1# Source Map Support2[![Build Status](https://travis-ci.org/evanw/node-source-map-support.svg?branch=master)](https://travis-ci.org/evanw/node-source-map-support)3 4This module provides source map support for stack traces in node via the [V8 stack trace API](https://github.com/v8/v8/wiki/Stack-Trace-API). It uses the [source-map](https://github.com/mozilla/source-map) module to replace the paths and line numbers of source-mapped files with their original paths and line numbers. The output mimics node's stack trace format with the goal of making every compile-to-JS language more of a first-class citizen. Source maps are completely general (not specific to any one language) so you can use source maps with multiple compile-to-JS languages in the same node process.5 6## Installation and Usage7 8#### Node support9 10```11$ npm install source-map-support12```13 14Source maps can be generated using libraries such as [source-map-index-generator](https://github.com/twolfson/source-map-index-generator). Once you have a valid source map, place a source mapping comment somewhere in the file (usually done automatically or with an option by your transpiler):15 16```17//# sourceMappingURL=path/to/source.map18```19 20If multiple sourceMappingURL comments exist in one file, the last sourceMappingURL comment will be21respected (e.g. if a file mentions the comment in code, or went through multiple transpilers).22The path should either be absolute or relative to the compiled file.23 24From here you have two options.25 26##### CLI Usage27 28```bash29node -r source-map-support/register compiled.js30```31 32##### Programmatic Usage33 34Put the following line at the top of the compiled file.35 36```js37require('source-map-support').install();38```39 40It is also possible to install the source map support directly by41requiring the `register` module which can be handy with ES6:42 43```js44import 'source-map-support/register'45 46// Instead of:47import sourceMapSupport from 'source-map-support'48sourceMapSupport.install()49```50Note: if you're using babel-register, it includes source-map-support already.51 52It is also very useful with Mocha:53 54```55$ mocha --require source-map-support/register tests/56```57 58#### Browser support59 60This library also works in Chrome. While the DevTools console already supports source maps, the V8 engine doesn't and `Error.prototype.stack` will be incorrect without this library. Everything will just work if you deploy your source files using [browserify](http://browserify.org/). Just make sure to pass the `--debug` flag to the browserify command so your source maps are included in the bundled code.61 62This library also works if you use another build process or just include the source files directly. In this case, include the file `browser-source-map-support.js` in your page and call `sourceMapSupport.install()`. It contains the whole library already bundled for the browser using browserify.63 64```html65<script src="browser-source-map-support.js"></script>66<script>sourceMapSupport.install();</script>67```68 69This library also works if you use AMD (Asynchronous Module Definition), which is used in tools like [RequireJS](http://requirejs.org/). Just list `browser-source-map-support` as a dependency:70 71```html72<script>73  define(['browser-source-map-support'], function(sourceMapSupport) {74    sourceMapSupport.install();75  });76</script>77```78 79## Options80 81This module installs two things: a change to the `stack` property on `Error` objects and a handler for uncaught exceptions that mimics node's default exception handler (the handler can be seen in the demos below). You may want to disable the handler if you have your own uncaught exception handler. This can be done by passing an argument to the installer:82 83```js84require('source-map-support').install({85  handleUncaughtExceptions: false86});87```88 89This module loads source maps from the filesystem by default. You can provide alternate loading behavior through a callback as shown below. For example, [Meteor](https://github.com/meteor) keeps all source maps cached in memory to avoid disk access.90 91```js92require('source-map-support').install({93  retrieveSourceMap: function(source) {94    if (source === 'compiled.js') {95      return {96        url: 'original.js',97        map: fs.readFileSync('compiled.js.map', 'utf8')98      };99    }100    return null;101  }102});103```104 105The module will by default assume a browser environment if XMLHttpRequest and window are defined. If either of these do not exist it will instead assume a node environment.106In some rare cases, e.g. when running a browser emulation and where both variables are also set, you can explictly specify the environment to be either 'browser' or 'node'.107 108```js109require('source-map-support').install({110  environment: 'node'111});112```113 114To support files with inline source maps, the `hookRequire` options can be specified, which will monitor all source files for inline source maps.115 116 117```js118require('source-map-support').install({119  hookRequire: true120});121```122 123This monkey patches the `require` module loading chain, so is not enabled by default and is not recommended for any sort of production usage.124 125## Demos126 127#### Basic Demo128 129original.js:130 131```js132throw new Error('test'); // This is the original code133```134 135compiled.js:136 137```js138require('source-map-support').install();139 140throw new Error('test'); // This is the compiled code141// The next line defines the sourceMapping.142//# sourceMappingURL=compiled.js.map143```144 145compiled.js.map:146 147```json148{149  "version": 3,150  "file": "compiled.js",151  "sources": ["original.js"],152  "names": [],153  "mappings": ";;AAAA,MAAM,IAAI"154}155```156 157Run compiled.js using node (notice how the stack trace uses original.js instead of compiled.js):158 159```160$ node compiled.js161 162original.js:1163throw new Error('test'); // This is the original code164      ^165Error: test166    at Object.<anonymous> (original.js:1:7)167    at Module._compile (module.js:456:26)168    at Object.Module._extensions..js (module.js:474:10)169    at Module.load (module.js:356:32)170    at Function.Module._load (module.js:312:12)171    at Function.Module.runMain (module.js:497:10)172    at startup (node.js:119:16)173    at node.js:901:3174```175 176#### TypeScript Demo177 178demo.ts:179 180```typescript181declare function require(name: string);182require('source-map-support').install();183class Foo {184  constructor() { this.bar(); }185  bar() { throw new Error('this is a demo'); }186}187new Foo();188```189 190Compile and run the file using the TypeScript compiler from the terminal:191 192```193$ npm install source-map-support typescript194$ node_modules/typescript/bin/tsc -sourcemap demo.ts195$ node demo.js196 197demo.ts:5198  bar() { throw new Error('this is a demo'); }199                ^200Error: this is a demo201    at Foo.bar (demo.ts:5:17)202    at new Foo (demo.ts:4:24)203    at Object.<anonymous> (demo.ts:7:1)204    at Module._compile (module.js:456:26)205    at Object.Module._extensions..js (module.js:474:10)206    at Module.load (module.js:356:32)207    at Function.Module._load (module.js:312:12)208    at Function.Module.runMain (module.js:497:10)209    at startup (node.js:119:16)210    at node.js:901:3211```212 213There is also the option to use `-r source-map-support/register` with typescript, without the need add the `require('source-map-support').install()` in the code base:214 215```216$ npm install source-map-support typescript217$ node_modules/typescript/bin/tsc  -sourcemap demo.ts218$ node -r source-map-support/register demo.js219 220demo.ts:5221  bar() { throw new Error('this is a demo'); }222                ^223Error: this is a demo224    at Foo.bar (demo.ts:5:17)225    at new Foo (demo.ts:4:24)226    at Object.<anonymous> (demo.ts:7:1)227    at Module._compile (module.js:456:26)228    at Object.Module._extensions..js (module.js:474:10)229    at Module.load (module.js:356:32)230    at Function.Module._load (module.js:312:12)231    at Function.Module.runMain (module.js:497:10)232    at startup (node.js:119:16)233    at node.js:901:3234```235 236#### CoffeeScript Demo237 238demo.coffee:239 240```coffee241require('source-map-support').install()242foo = ->243  bar = -> throw new Error 'this is a demo'244  bar()245foo()246```247 248Compile and run the file using the CoffeeScript compiler from the terminal:249 250```sh251$ npm install source-map-support coffeescript252$ node_modules/.bin/coffee --map --compile demo.coffee253$ node demo.js254 255demo.coffee:3256  bar = -> throw new Error 'this is a demo'257                     ^258Error: this is a demo259    at bar (demo.coffee:3:22)260    at foo (demo.coffee:4:3)261    at Object.<anonymous> (demo.coffee:5:1)262    at Object.<anonymous> (demo.coffee:1:1)263    at Module._compile (module.js:456:26)264    at Object.Module._extensions..js (module.js:474:10)265    at Module.load (module.js:356:32)266    at Function.Module._load (module.js:312:12)267    at Function.Module.runMain (module.js:497:10)268    at startup (node.js:119:16)269```270 271## Tests272 273This repo contains both automated tests for node and manual tests for the browser. The automated tests can be run using mocha (type `mocha` in the root directory). To run the manual tests:274 275* Build the tests using `build.js`276* Launch the HTTP server (`npm run serve-tests`) and visit277  * http://127.0.0.1:1336/amd-test278  * http://127.0.0.1:1336/browser-test279  * http://127.0.0.1:1336/browserify-test - **Currently not working** due to a bug with browserify (see [pull request #66](https://github.com/evanw/node-source-map-support/pull/66) for details).280* For `header-test`, run `server.js` inside that directory and visit http://127.0.0.1:1337/281 282## License283 284This code is available under the [MIT license](http://opensource.org/licenses/MIT).285