https://github.com/xpl/get-source
Fetch source-mapped sources. Peek by file, line, column. Node & browsers. Sync & async.
https://github.com/xpl/get-source
javascript read-source-code reflection source source-code source-code-analysis sourcecode sourcemap sourcemap-support sourcemaps typescript
Last synced: 3 months ago
JSON representation
Fetch source-mapped sources. Peek by file, line, column. Node & browsers. Sync & async.
- Host: GitHub
- URL: https://github.com/xpl/get-source
- Owner: xpl
- License: mit
- Created: 2016-08-23T16:25:42.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-14T11:57:15.000Z (about 4 years ago)
- Last Synced: 2025-01-26T02:12:52.716Z (3 months ago)
- Topics: javascript, read-source-code, reflection, source, source-code, source-code-analysis, sourcecode, sourcemap, sourcemap-support, sourcemaps, typescript
- Language: JavaScript
- Homepage: http://npmjs.com/package/get-source
- Size: 722 KB
- Stars: 28
- Watchers: 5
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# get-source
[](https://travis-ci.org/xpl/get-source) [](https://coveralls.io/github/xpl/get-source) [](https://npmjs.com/package/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](https://github.com/xpl/ololog)). 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](https://github.com/xpl/stacktracey) library)
- [x] [Advanced logging](https://github.com/xpl/ololog) / assertion printing
- [x] [Error displaying components](https://github.com/xpl/panic-overlay) for the 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
```