get-source

get-source

Fetch source-mapped sources. Peek by file, line, column. Node & browsers. Sync & async.

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 — good for CLI tools (e.g. logging). Works in browsers!
• Asynchronous API — good for everything web!
• Built-in cache

What for

• Call stacks enhanced with source code information (see the StackTracey library)
• Advanced logging / assertion printing
• Error displaying components for front-end web development

Usage (Synchronous)

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.

Usage (Asynchronous)

Pretty much the same as synchronous, except it's getSource.async. It returns awaitable promises:

file     = await getSource.async ('./scripts/index.min.js')
location = await file.resolve ({ line: 1, column: 8 })

Error handling

In synchronous mode, it never throws (due to backward compatibility reasons with existing code):

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

In asychronous mode, it throws an error:

try { 
   file     = await getSource.async ('/some/file')
   location = await file.resolve ({ line: 5, column: 0 })
} catch (e) {
   ...
}

Resetting Cache

E.g. when you need to force-reload files:

getSource.resetCache ()        // sync cache
getSource.async.resetCache ()  // async cache

Also, viewing cached files:

getSource.getCache ()        // sync cache
getSource.async.getCache ()  // async cache