1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# 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 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: <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:
```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
```
|
