initial commit

Author: xpl

.eslintrc

@@ -0,0 +1,6 @@
+{
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "script"
+  }
+}

.gitignore

@@ -0,0 +1,37 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Vitaly Gordon (https://github.com/xpl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,78 @@
+# get-source
+
+Platform-agnostic source code inspection, with sourcemaps support.
+
+```bash
+npm install get-source
+```
+
+## Features
+
+- [x] Allows to read source code files in Node and browsers
+- [x] Full sourcemap support (path resolving, external/embedded linking and long chains)
+- [x] **Synchronous** API — which is good when you implement a debugging tool (e.g. logging)
+- [x] Built-in cache
+
+## What for
+
+- [x] Call stacks enhanced with source code information (see [StackTracey](https://github.com/xpl/stacktracey) library)
+- [x] Advanced logging / assertion printing
+
+## Usage
+
+```javascript
+getSource = require ('get-source')
+```
+
+Will read `./scripts/index.min.js` synchronously (either via XHR, or by filesystem API, depending on the environment):
+
+```javascript
+file = getSource ('./scripts/index.min.js')
+```
+
+Result will contain following fields:
+
+```javascript
+file.path  // normalized file path
+file.text  // text contents
+file.lines // array of lines
+```
+
+And following methods:
+
+```javascript
+file.resolve ({ line: 1, column: 8 }) // indexes here start from 1 (by widely accepted convention). Zero indexes are invalid.
+```
+
+It will look through the sourcemap chain, returning following:
+
+```
+{
+   line:       <original line number>,
+   column:     <original column number>,
+   sourceFile: <original source file object>
+   sourceLine: <original source line text, trimmed>
+}
+```
+
+In that returned object, `sourceFile` is the same kind of object that `getSource` returns. So you can access its `text`, `lines` and `path` fields to obtain the full information. And the `sourceLine` is returned just for the convenience, as a shortcut.
+
+## Error handling
+
+In case of a nonexistent file:
+
+```
+nonsense = getSource ('/some/nonexistent/file')
+
+nonsense.text  // should be '' (so it's safe to access without checking)
+nonsense.error // should be Error object, representing an actual error thrown during reading/parsing
+```
+
+Calling `resolve` on an erroneous file:
+
+```
+resolved = nonsense.resolve ({ line: 5, column: 0 })
+
+resolved.error      // should be Error object, representing an actual error thrown during reading/parsing
+resolved.sourceLine // empty string (so it's safe to access without checking)
+```

get-source.js

@@ -0,0 +1,107 @@
+"use strict";
+
+/*  ------------------------------------------------------------------------ */
+
+const O                 = Object,
+      isBrowser         = (typeof window !== 'undefined') && (window.window === window) && window.navigator,
+      SourceMapConsumer = require ('source-map').SourceMapConsumer,
+      path              = require ('./impl/path'),
+      memoize           = require ('lodash.memoize'),
+      lastOf            = x => x[x.length - 1]
+
+/*  ------------------------------------------------------------------------ */
+
+const newSourceFileMemoized = memoize (file => new SourceFile (file))
+
+const getSource = module.exports = file => newSourceFileMemoized (path.normalize (file))
+
+/*  ------------------------------------------------------------------------ */
+
+class SourceMap {
+
+    constructor (originalFilePath, sourceMapPath) {
+
+        this.file      = getSource (path.relativeToFile (originalFilePath, sourceMapPath))
+        this.parsed    = (this.file.text && SourceMapConsumer (JSON.parse (this.file.text))) || null
+        this.sourceFor = memoize (this.sourceFor.bind (this))
+    }
+
+    sourceFor (file) {
+        const content = this.parsed.sourceContentFor (file, true /* return null on missing */)
+        const fullPath = path.relativeToFile (this.file.path, file)
+        return content ? new SourceFile (fullPath, content) : getSource (fullPath)
+    }
+
+    resolve (loc) {
+
+        const originalLoc = this.parsed.originalPositionFor (loc)
+        
+        return this.sourceFor (originalLoc.source)
+                   .resolve (O.assign ({}, loc, {
+                        line: originalLoc.line,
+                        column: originalLoc.column,
+                        name: originalLoc.name }))
+    }
+}
+
+/*  ------------------------------------------------------------------------ */
+
+class SourceFile {
+
+    constructor (path, text /* optional */) {
+
+        this.path = path
+
+        if (text) {
+            this.text = text }
+
+        else {
+            try {
+                if (isBrowser) {
+
+                    let xhr = new XMLHttpRequest ()
+
+                        xhr.open ('GET', path, false /* SYNCHRONOUS XHR FTW :) */)
+                        xhr.send (null)
+
+                    this.text = xhr.responseText }
+
+                else {
+                    this.text = require ('fs').readFileSync (path, { encoding: 'utf8' }) } }
+
+            catch (e) {
+                this.error = e
+                this.text = '' } }
+    }
+
+    get lines () {
+        return (this.lines_ = this.lines_ || this.text.split ('\n'))
+    }
+
+    get sourceMap () {
+
+        try {
+            if (this.sourceMap_ === undefined) {
+                let url = this.text.match (/\# sourceMappingURL=(.+\.map)/)
+                if (url = (url && url[1])) {
+                    this.sourceMap_ = new SourceMap (this.path, url) } } }
+
+        catch (e) {
+            this.sourceMapError = e
+            this.sourceMap_ = null }
+
+        return this.sourceMap_
+    }
+
+    resolve (loc /* { line, column } */) /* → { line, column, sourceFile, sourceLine } */ {
+
+        return this.sourceMap ? this.sourceMap.resolve (loc) : O.assign ({}, loc, {
+
+            sourceFile:  this,
+            sourceLine: (this.lines[loc.line - 1] || ''),
+            error:       this.error
+        })
+    }
+}
+
+/*  ------------------------------------------------------------------------ */

impl/path.js

@@ -0,0 +1,35 @@
+"use strict";
+
+/*  ------------------------------------------------------------------------ */
+
+const path = module.exports = {
+
+    concat: (a, b) => {
+
+                const a_endsWithSlash = (a[a.length - 1] === '/'),
+                	  b_startsWithSlash = (b[0] === '/')
+
+                return a + ((a_endsWithSlash || b_startsWithSlash) ? '' : '/') +
+                           ((a_endsWithSlash && b_startsWithSlash) ? b.substring (1) : b) },
+
+	normalize: path => {
+
+		let output = [],
+		    skip = 0
+
+		path.split ('/').reverse ().filter (x => x !== '.').forEach (x => {
+
+			     if (x === '..') { skip++ }
+			else if (skip === 0) { output.push (x) }
+			else                 { skip-- }
+		})
+
+		return output.reverse ().join ('/')
+	},
+
+	relativeToFile: (a, b) => {
+	    return path.normalize (path.concat (a.split ('/').slice (0, -1).join ('/'), b))
+	}
+}
+
+/*  ------------------------------------------------------------------------ */

package.json

@@ -0,0 +1,33 @@
+{
+  "name": "get-source",
+  "version": "1.0.0",
+  "description": "Platform-agnostic source code inspection, with sourcemaps support",
+  "main": "get-source",
+  "scripts": {
+    "test": "./node_modules/.bin/mocha --reporter spec --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xpl/get-source.git"
+  },
+  "keywords": [
+    "sources",
+    "sourcemap",
+    "read source",
+    "cached sources"
+  ],
+  "author": "Vitaly Gordon <rocket.mind@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/xpl/get-source/issues"
+  },
+  "homepage": "https://github.com/xpl/get-source",
+  "devDependencies": {
+    "chai": "^3.5.0",
+    "mocha": "^2.4.5"
+  },
+  "dependencies": {
+    "lodash.memoize": "^4.1.2",
+    "source-map": "^0.5.6"
+  }
+}