1 | # magic-string
|
2 |
|
3 | <a href="https://travis-ci.org/Rich-Harris/magic-string">
|
4 | <img src="http://img.shields.io/travis/Rich-Harris/magic-string.svg"
|
5 | alt="build status">
|
6 | </a>
|
7 | <a href="https://npmjs.org/package/magic-string">
|
8 | <img src="https://img.shields.io/npm/v/magic-string.svg"
|
9 | alt="npm version">
|
10 | </a>
|
11 | <a href="https://github.com/Rich-Harris/magic-string/blob/master/LICENSE.md">
|
12 | <img src="https://img.shields.io/npm/l/magic-string.svg"
|
13 | alt="license">
|
14 | </a>
|
15 |
|
16 | Suppose you have some source code. You want to make some light modifications to it - replacing a few characters here and there, wrapping it with a header and footer, etc - and ideally you'd like to generate a [source map](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/) at the end of it. You've thought about using something like [recast](https://github.com/benjamn/recast) (which allows you to generate an AST from some JavaScript, manipulate it, and reprint it with a sourcemap without losing your comments and formatting), but it seems like overkill for your needs (or maybe the source code isn't JavaScript).
|
17 |
|
18 | Your requirements are, frankly, rather niche. But they're requirements that I also have, and for which I made magic-string. It's a small, fast utility for manipulating strings and generating sourcemaps.
|
19 |
|
20 | ## Installation
|
21 |
|
22 | magic-string works in both node.js and browser environments. For node, install with npm:
|
23 |
|
24 | ```bash
|
25 | npm i magic-string
|
26 | ```
|
27 |
|
28 | To use in browser, grab the [magic-string.umd.js](https://unpkg.com/magic-string/dist/magic-string.umd.js) file and add it to your page:
|
29 |
|
30 | ```html
|
31 | <script src='magic-string.umd.js'></script>
|
32 | ```
|
33 |
|
34 | (It also works with various module systems, if you prefer that sort of thing - it has a dependency on [vlq](https://github.com/Rich-Harris/vlq).)
|
35 |
|
36 | ## Usage
|
37 |
|
38 | These examples assume you're in node.js, or something similar:
|
39 |
|
40 | ```js
|
41 | import MagicString from 'magic-string';
|
42 | import fs from 'fs'
|
43 |
|
44 | const s = new MagicString('problems = 99');
|
45 |
|
46 | s.update(0, 8, 'answer');
|
47 | s.toString(); // 'answer = 99'
|
48 |
|
49 | s.update(11, 13, '42'); // character indices always refer to the original string
|
50 | s.toString(); // 'answer = 42'
|
51 |
|
52 | s.prepend('var ').append(';'); // most methods are chainable
|
53 | s.toString(); // 'var answer = 42;'
|
54 |
|
55 | const map = s.generateMap({
|
56 | source: 'source.js',
|
57 | file: 'converted.js.map',
|
58 | includeContent: true
|
59 | }); // generates a v3 sourcemap
|
60 |
|
61 | fs.writeFileSync('converted.js', s.toString());
|
62 | fs.writeFileSync('converted.js.map', map.toString());
|
63 | ```
|
64 |
|
65 | You can pass an options argument:
|
66 |
|
67 | ```js
|
68 | const s = new MagicString(someCode, {
|
69 | // both these options will be used if you later
|
70 | // call `bundle.addSource( s )` - see below
|
71 | filename: 'foo.js',
|
72 | indentExclusionRanges: [/*...*/]
|
73 | });
|
74 | ```
|
75 |
|
76 | ## Methods
|
77 |
|
78 | ### s.addSourcemapLocation( index )
|
79 |
|
80 | Adds the specified character index (with respect to the original string) to sourcemap mappings, if `hires` is `false` (see below).
|
81 |
|
82 | ### s.append( content )
|
83 |
|
84 | Appends the specified content to the end of the string. Returns `this`.
|
85 |
|
86 | ### s.appendLeft( index, content )
|
87 |
|
88 | Appends the specified `content` at the `index` in the original string. If a range *ending* with `index` is subsequently moved, the insert will be moved with it. Returns `this`. See also `s.prependLeft(...)`.
|
89 |
|
90 | ### s.appendRight( index, content )
|
91 |
|
92 | Appends the specified `content` at the `index` in the original string. If a range *starting* with `index` is subsequently moved, the insert will be moved with it. Returns `this`. See also `s.prependRight(...)`.
|
93 |
|
94 | ### s.clone()
|
95 |
|
96 | Does what you'd expect.
|
97 |
|
98 | ### s.generateDecodedMap( options )
|
99 |
|
100 | Generates a sourcemap object with raw mappings in array form, rather than encoded as a string. See `generateMap` documentation below for options details. Useful if you need to manipulate the sourcemap further, but most of the time you will use `generateMap` instead.
|
101 |
|
102 | ### s.generateMap( options )
|
103 |
|
104 | Generates a [version 3 sourcemap](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit). All options are, well, optional:
|
105 |
|
106 | * `file` - the filename where you plan to write the sourcemap
|
107 | * `source` - the filename of the file containing the original source
|
108 | * `includeContent` - whether to include the original content in the map's `sourcesContent` array
|
109 | * `hires` - whether the mapping should be high-resolution. Hi-res mappings map every single character, meaning (for example) your devtools will always be able to pinpoint the exact location of function calls and so on. With lo-res mappings, devtools may only be able to identify the correct line - but they're quicker to generate and less bulky. If sourcemap locations have been specified with `s.addSourceMapLocation()`, they will be used here.
|
110 |
|
111 | The returned sourcemap has two (non-enumerable) methods attached for convenience:
|
112 |
|
113 | * `toString` - returns the equivalent of `JSON.stringify(map)`
|
114 | * `toUrl` - returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
|
115 |
|
116 | ```js
|
117 | code += '\n//# sourceMappingURL=' + map.toUrl();
|
118 | ```
|
119 |
|
120 | ### s.hasChanged()
|
121 |
|
122 | Indicates if the string has been changed.
|
123 |
|
124 | ### s.indent( prefix[, options] )
|
125 |
|
126 | Prefixes each line of the string with `prefix`. If `prefix` is not supplied, the indentation will be guessed from the original content, falling back to a single tab character. Returns `this`.
|
127 |
|
128 | The `options` argument can have an `exclude` property, which is an array of `[start, end]` character ranges. These ranges will be excluded from the indentation - useful for (e.g.) multiline strings.
|
129 |
|
130 | ### s.insertLeft( index, content )
|
131 |
|
132 | **DEPRECATED** since 0.17 – use `s.appendLeft(...)` instead
|
133 |
|
134 | ### s.insertRight( index, content )
|
135 |
|
136 | **DEPRECATED** since 0.17 – use `s.prependRight(...)` instead
|
137 |
|
138 | ### s.isEmpty()
|
139 |
|
140 | Returns true if the resulting source is empty (disregarding white space).
|
141 |
|
142 | ### s.locate( index )
|
143 |
|
144 | **DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
|
145 |
|
146 | ### s.locateOrigin( index )
|
147 |
|
148 | **DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
|
149 |
|
150 | ### s.move( start, end, newIndex )
|
151 |
|
152 | Moves the characters from `start` and `end` to `index`. Returns `this`.
|
153 |
|
154 | ### s.overwrite( start, end, content[, options] )
|
155 |
|
156 | Replaces the characters from `start` to `end` with `content`, along with the appended/prepended content in that range. The same restrictions as `s.remove()` apply. Returns `this`.
|
157 |
|
158 | The fourth argument is optional. It can have a `storeName` property — if `true`, the original name will be stored for later inclusion in a sourcemap's `names` array — and a `contentOnly` property which determines whether only the content is overwritten, or anything that was appended/prepended to the range as well.
|
159 |
|
160 | It may be preferred to use `s.update(...)` instead if you wish to avoid overwriting the appended/prepended content.
|
161 |
|
162 | ### s.prepend( content )
|
163 |
|
164 | Prepends the string with the specified content. Returns `this`.
|
165 |
|
166 | ### s.prependLeft ( index, content )
|
167 |
|
168 | Same as `s.appendLeft(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
|
169 |
|
170 | ### s.prependRight ( index, content )
|
171 |
|
172 | Same as `s.appendRight(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
|
173 |
|
174 | ### s.replace( regexpOrString, substitution )
|
175 |
|
176 | String replacement with RegExp or string. When using a RegExp, replacer function is also supported. Returns `this`.
|
177 |
|
178 | ```ts
|
179 | import MagicString from 'magic-string'
|
180 |
|
181 | const s = new MagicString(source)
|
182 |
|
183 | s.replace('foo', 'bar')
|
184 | s.replace(/foo/g, 'bar')
|
185 | s.replace(/(\w)(\d+)/g, (_, $1, $2) => $1.toUpperCase() + $2)
|
186 | ```
|
187 |
|
188 | The differences from [`String.replace`]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)):
|
189 | - It will always match against the **original string**
|
190 | - It mutates the magic string state (use `.clone()` to be immutable)
|
191 |
|
192 | ### s.replaceAll( regexpOrString, substitution )
|
193 |
|
194 | Same as `s.replace`, but replace all matched strings instead of just one.
|
195 | If `substitution` is a regex, then it must have the global (`g`) flag set, or a `TypeError` is thrown. Matches the behavior of the bultin [`String.property.replaceAll`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll).
|
196 |
|
197 | ### s.remove( start, end )
|
198 |
|
199 | Removes the characters from `start` to `end` (of the original string, **not** the generated string). Removing the same content twice, or making removals that partially overlap, will cause an error. Returns `this`.
|
200 |
|
201 | ### s.slice( start, end )
|
202 |
|
203 | Returns the content of the generated string that corresponds to the slice between `start` and `end` of the original string. Throws error if the indices are for characters that were already removed.
|
204 |
|
205 | ### s.snip( start, end )
|
206 |
|
207 | Returns a clone of `s`, with all content before the `start` and `end` characters of the original string removed.
|
208 |
|
209 | ### s.toString()
|
210 |
|
211 | Returns the generated string.
|
212 |
|
213 | ### s.trim([ charType ])
|
214 |
|
215 | Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start and end. Returns `this`.
|
216 |
|
217 | ### s.trimStart([ charType ])
|
218 |
|
219 | Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start. Returns `this`.
|
220 |
|
221 | ### s.trimEnd([ charType ])
|
222 |
|
223 | Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the end. Returns `this`.
|
224 |
|
225 | ### s.trimLines()
|
226 |
|
227 | Removes empty lines from the start and end. Returns `this`.
|
228 |
|
229 | ### s.update( start, end, content[, options] )
|
230 |
|
231 | Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply. Returns `this`.
|
232 |
|
233 | The fourth argument is optional. It can have a `storeName` property — if `true`, the original name will be stored for later inclusion in a sourcemap's `names` array — and an `overwrite` property which defaults to `false` and determines whether anything that was appended/prepended to the range will be overwritten along with the original content.
|
234 |
|
235 | `s.update(start, end, content)` is equivalent to `s.overwrite(start, end, content, { contentOnly: true })`.
|
236 |
|
237 | ## Bundling
|
238 |
|
239 | To concatenate several sources, use `MagicString.Bundle`:
|
240 |
|
241 | ```js
|
242 | const bundle = new MagicString.Bundle();
|
243 |
|
244 | bundle.addSource({
|
245 | filename: 'foo.js',
|
246 | content: new MagicString('var answer = 42;')
|
247 | });
|
248 |
|
249 | bundle.addSource({
|
250 | filename: 'bar.js',
|
251 | content: new MagicString('console.log( answer )')
|
252 | });
|
253 |
|
254 | // Advanced: a source can include an `indentExclusionRanges` property
|
255 | // alongside `filename` and `content`. This will be passed to `s.indent()`
|
256 | // - see documentation above
|
257 |
|
258 | bundle.indent() // optionally, pass an indent string, otherwise it will be guessed
|
259 | .prepend('(function () {\n')
|
260 | .append('}());');
|
261 |
|
262 | bundle.toString();
|
263 | // (function () {
|
264 | // var answer = 42;
|
265 | // console.log( answer );
|
266 | // }());
|
267 |
|
268 | // options are as per `s.generateMap()` above
|
269 | const map = bundle.generateMap({
|
270 | file: 'bundle.js',
|
271 | includeContent: true,
|
272 | hires: true
|
273 | });
|
274 | ```
|
275 |
|
276 | As an alternative syntax, if you a) don't have `filename` or `indentExclusionRanges` options, or b) passed those in when you used `new MagicString(...)`, you can simply pass the `MagicString` instance itself:
|
277 |
|
278 | ```js
|
279 | const bundle = new MagicString.Bundle();
|
280 | const source = new MagicString(someCode, {
|
281 | filename: 'foo.js'
|
282 | });
|
283 |
|
284 | bundle.addSource(source);
|
285 | ```
|
286 |
|
287 | ## License
|
288 |
|
289 | MIT
|