feat: add update method as safer alternative to overwrite

README.md

@@ -135,6 +135,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)
@@ -149,6 +153,8 @@ Moves the characters from `start` and `end` to `index`. Returns `this`.
 
 ### s.overwrite( start, end, content[, options] )
 
+__Note:__ It may be preferred to use `s.update(...)` instead
+
 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 a `contentOnly` property which determines whether only the content is overwritten, or anything that was appended/prepended to the range as well.
@@ -215,9 +221,11 @@ 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.
 
 ## Bundling
 

index.d.ts

@@ -98,6 +98,11 @@ export interface OverwriteOptions {
   contentOnly?: boolean;
 }
 
+export interface UpdateOptions {
+  storeName?: boolean;
+  overwrite?: boolean;
+}
+
 export default class MagicString {
   constructor(str: string, options?: MagicStringOptions);
   /**
@@ -155,13 +160,23 @@ export default class MagicString {
    */
   move(start: number, end: number, index: number): MagicString;
   /**
+   * __Note:__ It may be preferred to use `s.update(...)` instead
+   * 
    * Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply.
    *
    * 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.
    */
   overwrite(start: number, end: number, content: string, options?: boolean | OverwriteOptions): MagicString;
+  /**
+   * Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply.
+   *
+   * 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 determines whether only
+   * the content is overwritten, or anything that was appended/prepended to the range as well.
+   */
+  update(start: number, end: number, content: string, options?: boolean | UpdateOptions): MagicString;
   /**
    * Prepends the string with the specified content. 
    */

src/MagicString.js

@@ -334,6 +334,12 @@ export default class MagicString {
 	}
 
 	overwrite(start, end, content, options) {
+		options = options || {};
+		options.overwrite = !options.contentOnly;
+		return this.update(start, end, content, options);
+	}
+
+	update(start, end, content, options) {
 		if (typeof content !== 'string') throw new TypeError('replacement content must be a string');
 
 		while (start < 0) start += this.original.length;
@@ -361,7 +367,7 @@ export default class MagicString {
 			options = { storeName: true };
 		}
 		const storeName = options !== undefined ? options.storeName : false;
-		const contentOnly = options !== undefined ? options.contentOnly : false;
+		const overwrite = options !== undefined ? options.overwrite : false;
 
 		if (storeName) {
 			const original = this.original.slice(start, end);
@@ -385,7 +391,7 @@ export default class MagicString {
 				chunk.edit('', false);
 			}
 
-			first.edit(content, storeName, contentOnly);
+			first.edit(content, storeName, !overwrite);
 		} else {
 			// must be inserting at the end
 			const newChunk = new Chunk(start, end, '').edit(content, storeName);