kroitor / get-source

Platform-agnostic source code inspection, with sourcemaps support

get-source

Platform-agnostic source code inspection, with sourcemaps support.

npm install get-source

Features

• Allows to read source code files in Node and browsers
• Full sourcemap support (path resolving, external/embedded/inline linking, and long chains)
• Synchronous API — which is good when you implement a debugging tool (e.g. logging)
• Built-in cache

What for

• Call stacks enhanced with source code information (see the StackTracey library)
• Advanced logging / assertion printing

Usage

getSource = require ('get-source')

file = getSource ('./scripts/index.min.js')

Will read the file synchronously (either via XHR or by filesystem API, depending on the environment) and return it's cached representation. Result will contain the following fields:

file.path  // normalized file path
file.text  // text contents
file.lines // array of lines

And the resolve method:

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>
}

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

nonsense = getSource ('/some/nonexistent/file')

nonsense.text  // should be '' (so it's safe to access without checking)
nonsense.error // should be an Error object, representing an actual error thrown during reading/parsing

resolved = nonsense.resolve ({ line: 5, column: 0 })

resolved.sourceLine // empty string (so it's safe to access without checking)
resolved.error      // should be an Error object, representing an actual error thrown during reading/parsing