🔧

node_modules/magic-string/README.md

@@ -13,7 +13,7 @@
        alt="license">
 </a>
 
-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 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).
+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).
 
 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.
 
@@ -43,10 +43,10 @@ import fs from 'fs'
 
 const s = new MagicString('problems = 99');
 
-s.overwrite(0, 8, 'answer');
+s.update(0, 8, 'answer');
 s.toString(); // 'answer = 99'
 
-s.overwrite(11, 13, '42'); // character indices always refer to the original string
+s.update(11, 13, '42'); // character indices always refer to the original string
 s.toString(); // 'answer = 42'
 
 s.prepend('var ').append(';'); // most methods are chainable
@@ -66,10 +66,11 @@ You can pass an options argument:
 
 ```js
 const s = new MagicString(someCode, {
-  // both these options will be used if you later
-  // call `bundle.addSource( s )` - see below
+  // these options will be used if you later call `bundle.addSource( s )` - see below
   filename: 'foo.js',
-  indentExclusionRanges: [/*...*/]
+  indentExclusionRanges: [/*...*/],
+  // market source as ignore in DevTools, see below #Bundling
+  ignoreList: false
 });
 ```
 
@@ -106,7 +107,7 @@ Generates a [version 3 sourcemap](https://docs.google.com/document/d/1U1RGAehQwR
 * `file` - the filename where you plan to write the sourcemap
 * `source` - the filename of the file containing the original source
 * `includeContent` - whether to include the original content in the map's `sourcesContent` array
-* `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.
+* `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. You can also set `"boundary"` to generate a semi-hi-res mappings segmented per word boundary instead of per character, suitable for string semantics that are separated by words. If sourcemap locations have been specified with `s.addSourcemapLocation()`, they will be used here.
 
 The returned sourcemap has two (non-enumerable) methods attached for convenience:
 
@@ -117,6 +118,10 @@ The returned sourcemap has two (non-enumerable) methods attached for convenience
 code += '\n//# sourceMappingURL=' + map.toUrl();
 ```
 
+### s.hasChanged()
+
+Indicates if the string has been changed.
+
 ### s.indent( prefix[, options] )
 
 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`.
@@ -131,6 +136,10 @@ The `options` argument can have an `exclude` property, which is an array of `[st
 
 **DEPRECATED** since 0.17 – use `s.prependRight(...)` instead
 
+### s.isEmpty()
+
+Returns true if the resulting source is empty (disregarding white space).
+
 ### s.locate( index )
 
 **DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
@@ -139,16 +148,18 @@ The `options` argument can have an `exclude` property, which is an array of `[st
 
 **DEPRECATED** since 0.10 – see [#30](https://github.com/Rich-Harris/magic-string/pull/30)
 
-### s.move( start, end, newIndex )
+### s.move( start, end, index )
 
 Moves the characters from `start` and `end` to `index`. Returns `this`.
 
 ### s.overwrite( start, end, content[, options] )
 
-Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply. Returns `this`.
+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`.
 
 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.
 
+It may be preferred to use `s.update(...)` instead if you wish to avoid overwriting the appended/prepended content.
+
 ### s.prepend( content )
 
 Prepends the string with the specified content. Returns `this`.
@@ -161,6 +172,29 @@ Same as `s.appendLeft(...)`, except that the inserted content will go *before* a
 
 Same as `s.appendRight(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
 
+### s.replace( regexpOrString, substitution )
+
+String replacement with RegExp or string. When using a RegExp, replacer function is also supported. Returns `this`.
+
+```ts
+import MagicString from 'magic-string'
+
+const s = new MagicString(source)
+
+s.replace('foo', 'bar')
+s.replace(/foo/g, 'bar')
+s.replace(/(\w)(\d+)/g, (_, $1, $2) => $1.toUpperCase() + $2)
+```
+
+The differences from [`String.replace`]((https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)):
+- It will always match against the **original string**
+- It mutates the magic string state (use `.clone()` to be immutable)
+
+### s.replaceAll( regexpOrString, substitution )
+
+Same as `s.replace`, but replace all matched strings instead of just one.
+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).
+
 ### s.remove( start, end )
 
 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`.
@@ -193,9 +227,13 @@ Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the e
 
 Removes empty lines from the start and end. Returns `this`.
 
-### s.isEmpty()
+### s.update( start, end, content[, options] )
 
-Returns true if the resulting source is empty (disregarding white space).
+Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply. Returns `this`.
+
+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.
+
+`s.update(start, end, content)` is equivalent to `s.overwrite(start, end, content, { contentOnly: true })`.
 
 ## Bundling
 
@@ -214,6 +252,15 @@ bundle.addSource({
   content: new MagicString('console.log( answer )')
 });
 
+// Sources can be marked as ignore-listed, which provides a hint to debuggers
+// to not step into this code and also don't show the source files depending
+// on user preferences.
+bundle.addSource({
+  filename: 'some-3rdparty-library.js',
+  content: new MagicString('function myLib(){}'),
+  ignoreList: false // <--
+})
+
 // Advanced: a source can include an `indentExclusionRanges` property
 // alongside `filename` and `content`. This will be passed to `s.indent()`
 // - see documentation above