ES2021: 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 Peter Marshall, Jakob Gruber, 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'
);

“Exploring JavaScript” 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():

Implementations  #

• Polyfills:
  • string.prototype.replaceall
  • core-js
• Support in JavaScript engines: Keep an eye on the proposal for updates.

Further reading  #

• Section “Flag /g and its pitfalls” in “Exploring JavaScript”