1 | # convert-source-map [![Build Status][ci-image]][ci-url]
|
2 |
|
3 | Converts a source-map from/to different formats and allows adding/changing properties.
|
4 |
|
5 | ```js
|
6 | var convert = require('convert-source-map');
|
7 |
|
8 | var json = convert
|
9 | .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
|
10 | .toJSON();
|
11 |
|
12 | var modified = convert
|
13 | .fromComment('//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbGQvZm9vLm1pbi5qcyIsInNvdXJjZXMiOlsic3JjL2Zvby5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSIsInNvdXJjZVJvb3QiOiIvIn0=')
|
14 | .setProperty('sources', [ 'SRC/FOO.JS' ])
|
15 | .toJSON();
|
16 |
|
17 | console.log(json);
|
18 | console.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 |
|
28 | Prior 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 |
|
30 | In 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 |
|
32 | If 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 |
|
47 | Returns source map converter from given object.
|
48 |
|
49 | ### fromJSON(json)
|
50 |
|
51 | Returns source map converter from given json string.
|
52 |
|
53 | ### fromURI(uri)
|
54 |
|
55 | Returns source map converter from given uri encoded json string.
|
56 |
|
57 | ### fromBase64(base64)
|
58 |
|
59 | Returns source map converter from given base64 encoded json string.
|
60 |
|
61 | ### fromComment(comment)
|
62 |
|
63 | Returns source map converter from given base64 or uri encoded json string prefixed with `//# sourceMappingURL=...`.
|
64 |
|
65 | ### fromMapFileComment(comment, readMap)
|
66 |
|
67 | Returns 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 |
|
71 | If `readMap` doesn't return a `Promise`, `fromMapFileComment` will return a source map converter synchronously.
|
72 |
|
73 | If `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
|
80 | var convert = require('convert-source-map');
|
81 | var fs = require('fs');
|
82 |
|
83 | function readMap(filename) {
|
84 | return fs.readFileSync(filename, 'utf8');
|
85 | }
|
86 |
|
87 | var json = convert
|
88 | .fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
|
89 | .toJSON();
|
90 | console.log(json);
|
91 | ```
|
92 |
|
93 |
|
94 | **Asynchronous read in Node.js:**
|
95 |
|
96 | ```js
|
97 | var convert = require('convert-source-map');
|
98 | var { promises: fs } = require('fs'); // Notice the `promises` import
|
99 |
|
100 | function readMap(filename) {
|
101 | return fs.readFile(filename, 'utf8');
|
102 | }
|
103 |
|
104 | var converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
|
105 | var json = converter.toJSON();
|
106 | console.log(json);
|
107 | ```
|
108 |
|
109 | **Asynchronous read in the browser:**
|
110 |
|
111 | ```js
|
112 | var convert = require('convert-source-map');
|
113 |
|
114 | async function readMap(url) {
|
115 | const res = await fetch(url);
|
116 | return res.text();
|
117 | }
|
118 |
|
119 | const converter = await convert.fromMapFileComment('//# sourceMappingURL=map-file-comment.css.map', readMap)
|
120 | var json = converter.toJSON();
|
121 | console.log(json);
|
122 | ```
|
123 |
|
124 | ### fromSource(source)
|
125 |
|
126 | Finds 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 |
|
130 | Finds 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 |
|
134 | If `readMap` doesn't return a `Promise`, `fromMapFileSource` will return a source map converter synchronously.
|
135 |
|
136 | If `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 |
|
140 | Returns a copy of the underlying source map.
|
141 |
|
142 | ### toJSON([space])
|
143 |
|
144 | Converts 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
|
146 | JSON string is generated.
|
147 |
|
148 | ### toURI()
|
149 |
|
150 | Converts source map to uri encoded json string.
|
151 |
|
152 | ### toBase64()
|
153 |
|
154 | Converts source map to base64 encoded json string.
|
155 |
|
156 | ### toComment([options])
|
157 |
|
158 | Converts source map to an inline comment that can be appended to the source-file.
|
159 |
|
160 | By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would
|
161 | normally see in a JS source file.
|
162 |
|
163 | When `options.encoding == 'uri'`, the data will be uri encoded, otherwise they will be base64 encoded.
|
164 |
|
165 | When `options.multiline == true`, the comment is formatted like: `/*# sourceMappingURL=... */`, which you would find in a CSS source file.
|
166 |
|
167 | ### addProperty(key, value)
|
168 |
|
169 | Adds given property to the source map. Throws an error if property already exists.
|
170 |
|
171 | ### setProperty(key, value)
|
172 |
|
173 | Sets given property to the source map. If property doesn't exist it is added, otherwise its value is updated.
|
174 |
|
175 | ### getProperty(key)
|
176 |
|
177 | Gets given property of the source map.
|
178 |
|
179 | ### removeComments(src)
|
180 |
|
181 | Returns `src` with all source map comments removed
|
182 |
|
183 | ### removeMapFileComments(src)
|
184 |
|
185 | Returns `src` with all source map comments pointing to map files removed.
|
186 |
|
187 | ### commentRegex
|
188 |
|
189 | Provides __a fresh__ RegExp each time it is accessed. Can be used to find source map comments.
|
190 |
|
191 | Breaks down a source map comment into groups: Groups: 1: media type, 2: MIME type, 3: charset, 4: encoding, 5: data.
|
192 |
|
193 | ### mapFileCommentRegex
|
194 |
|
195 | Provides __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 |
|
199 | Returns a comment that links to an external source map via `file`.
|
200 |
|
201 | By default, the comment is formatted like: `//# sourceMappingURL=...`, which you would normally see in a JS source file.
|
202 |
|
203 | When `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
|