ECMAScript Proposal- `String.prototype.replaceAll`

The normal string method .replace() only lets you replace one occurrence if you search for string (and not a regular expression with the flag /g ). The proposal “ String.prototype.replaceAll ” (by Mathias Bynens) fixes that.

.replace() : the status quo  

Let’s look at three options for replacing that we currently have.

First, we can search for a string and replace the first occurrence:

> 'Cyan + magenta + yellow + black'.replace('+', 'and')
'Cyan and magenta + yellow + black'

Second, we can search for a regular expression with the flag /g and replace all occurrences:

> 'Cyan + magenta + yellow + black'.replace(/\+/g, 'and')
'Cyan and magenta and yellow and black'

Third, we can convert a string into a regular expression with flag /g and replace all occurrences:

function escapeForRegExp(str) {
  return str.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&'); // (A)
}
const regExp = new RegExp(escapeForRegExp('+'), 'g');
assert.equal(
  'Cyan + magenta + yellow + black'.replace(regExp, 'and'),
  'Cyan and magenta and yellow and black'
);

“JavaScript for impatient programmers” has a few more details on escapeForRegExp() .

.replaceAll() : replacing strings multiple times  

The proposed string method .replaceAll() provides one service that .replace() can’t: Searching for a string and replacing all occurrences:

> 'Cyan + magenta + yellow + black'.replaceAll('+', 'and')
'Cyan and magenta and yellow and black'

.replaceAll() throws an exception if we use a regular expression that does not have the flag /g . The assumption is that we made a mistake and should switch to .replace() if we really only want to replace the first occurrence. The following code demonstrates that:

assert.throws(
  () => 'abcdef'.replaceAll(/abc/, 'x'),
  TypeError
);

Other than that, .replaceAll() works like .replace() . This table summarizes the differences between .replace() and .replaceAll() :

Search for String RegExp RegExp with /g .replace First occurrence First All .replaceAll All occurrences TypeError All