get-source

  

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

``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/inline linking, and long chains)
- [x] Synchronous API — good for CLI tools (e.g. logging). Works in browsers!
- [x] Asynchronous API — good for everything web!
- [x] Built-in cache

What for

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

Usage (Synchronous)

`javascript
import getSource from 'get-source'
`
`javascript
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:

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

And the resolve method:

`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:

`javascript
{
line: ,
column: ,
sourceFile: ,
sourceLine:
}
`

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:

`javascript
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):

`javascript
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
`
`javascript
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:

`javascript
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:

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

Also, viewing cached files:

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