UNPKG

7.42 kBMarkdownView Raw
1# convert-source-map [![Build Status][ci-image]][ci-url]
2
3Converts a source-map from/to different formats and allows adding/changing properties.
4
5```js
6var convert = require('convert-source-map');
7
8var json = convert
9 .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
10 .toJSON();
11
12var modified = convert
13 .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
14 .setProperty('sources', [ 'SRC/FOO.JS' ])
15 .toJSON();
16
17console.log(json);
18console.log(modified);
19```
20
21```json
22{"version":3,"file":"build/foo.min.js","sources":["src/foo.js"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
23{"version":3,"file":"build/foo.min.js","sources":["SRC/FOO.JS"],"names":[],"mappings":"AAAA","sourceRoot":"/"}
24```
25
26## Upgrading
27
28Prior to v2.0.0, the `fromMapFileComment` and `fromMapFileSource` functions took a String directory path and used that to resolve & read the source map file from the filesystem. However, this made the library limited to nodejs environments and broke on sources with querystrings.
29
30In v2.0.0, you now need to pass a function that does the file reading. It will receive the source filename as a String that you can resolve to a filesystem path, URL, or anything else.
31
32If you are using `convert-source-map` in nodejs and want the previous behavior, you'll use a function like such:
33
34```diff
35+ var fs = require('fs'); // Import the fs module to read a file
36+ var path = require('path'); // Import the path module to resolve a path against your directory
37- var conv = convert.fromMapFileSource(css, '../my-dir');
38+ var conv = convert.fromMapFileSource(css, function (filename) {
39+ return fs.readFileSync(path.resolve('../my-dir', filename), 'utf-8');
40+ });
41```
42
43## API
44
45### fromObject(obj)
46
47Returns source map converter from given object.
48
49### fromJSON(json)
50
51Returns source map converter from given json string.
52
53### fromURI(uri)
54
55Returns source map converter from given uri encoded json string.
56
57### fromBase64(base64)
58
59Returns source map converter from given base64 encoded json string.
60
61### fromComment(comment)
62
63Returns source map converter from given base64 or uri encoded json string prefixed with `//# sourceMappingURL=...`.
64
65### fromMapFileComment(comment, readMap)
66
67Returns source map converter from given `filename` by parsing `//# sourceMappingURL=filename`.
68
69`readMap` must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a `Promise` containing a String or Buffer of the source map (if read asynchronously).
70
71If `readMap` doesn't return a `Promise`, `fromMapFileComment` will return a source map converter synchronously.
72
73If `readMap` returns a `Promise`, `fromMapFileComment` will also return `Promise`. The `Promise` will be either resolved with the source map converter or rejected with an error.
74
75#### Examples
76
77**Synchronous read in Node.js:**
78
79```js
80var convert = require('convert-source-map');
81var fs = require('fs');
82
83function readMap(filename) {
84 return fs.readFileSync(filename, 'utf8');
85}
86
87var json = convert
88 .fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
89 .toJSON();
90console.log(json);
91```
92
93
94**Asynchronous read in Node.js:**
95
96```js
97var convert = require('convert-source-map');
98var { promises: fs } = require('fs'); // Notice the `promises` import
99
100function readMap(filename) {
101 return fs.readFile(filename, 'utf8');
102}
103
104var converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
105var json = converter.toJSON();
106console.log(json);
107```
108
109**Asynchronous read in the browser:**
110
111```js
112var convert = require('convert-source-map');
113
114async function readMap(url) {
115 const res = await fetch(url);
116 return res.text();
117}
118
119const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
120var json = converter.toJSON();
121console.log(json);
122```
123
124### fromSource(source)
125
126Finds last sourcemap comment in file and returns source map converter or returns `null` if no source map comment was found.
127
128### fromMapFileSource(source, readMap)
129
130Finds last sourcemap comment in file and returns source map converter or returns `null` if no source map comment was found.
131
132`readMap` must be a function which receives the source map filename and returns either a String or Buffer of the source map (if read synchronously), or a `Promise` containing a String or Buffer of the source map (if read asynchronously).
133
134If `readMap` doesn't return a `Promise`, `fromMapFileSource` will return a source map converter synchronously.
135
136If `readMap` returns a `Promise`, `fromMapFileSource` will also return `Promise`. The `Promise` will be either resolved with the source map converter or rejected with an error.
137
138### toObject()
139
140Returns a copy of the underlying source map.
141
142### toJSON([space])
143
144Converts source map to json string. If `space` is given (optional), this will be passed to
145[JSON.stringify](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify) when the
146JSON string is generated.
147
148### toURI()
149
150Converts source map to uri encoded json string.
151
152### toBase64()
153
154Converts source map to base64 encoded json string.
155
156### toComment([options])
157
158Converts source map to an inline comment that can be appended to the source-file.
159
160By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would
161normally see in a JS source file.
162
163When `options.encoding == 'uri'`, the data will be uri encoded, otherwise they will be base64 encoded.
164
165When `options.multiline == true`, the comment is formatted like: `/*# sourceMappingURL=... */`, which you would find in a CSS source file.
166
167### addProperty(key, value)
168
169Adds given property to the source map. Throws an error if property already exists.
170
171### setProperty(key, value)
172
173Sets given property to the source map. If property doesn't exist it is added, otherwise its value is updated.
174
175### getProperty(key)
176
177Gets given property of the source map.
178
179### removeComments(src)
180
181Returns `src` with all source map comments removed
182
183### removeMapFileComments(src)
184
185Returns `src` with all source map comments pointing to map files removed.
186
187### commentRegex
188
189Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments.
190
191Breaks down a source map comment into groups: Groups: 1: media type, 2: MIME type, 3: charset, 4: encoding, 5: data.
192
193### mapFileCommentRegex
194
195Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments pointing to map files.
196
197### generateMapFileComment(file, [options])
198
199Returns a comment that links to an external source map via `file`.
200
201By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would normally see in a JS source file.
202
203When `options.multiline == true`, the comment is formatted like: `/*# sourceMappingURL=... */`, which you would find in a CSS source file.
204
205[ci-url]: https://github.com/thlorenz/convert-source-map/actions?query=workflow:ci
206[ci-image]: https://img.shields.io/github/workflow/status/thlorenz/convert-source-map/CI?style=flat-square