Reference for stage 3 regex-escaping (#36928)

* Reference for stage 3 regex-escaping

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

* Apply suggestions from code review

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

Co-authored-by: Kevin Gibbons <bakkot@gmail.com>

* Update index.md

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

* Fix wording

* Update files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Update files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

Co-authored-by: Kevin Gibbons <bakkot@gmail.com>

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Kevin Gibbons <bakkot@gmail.com>

files/en-us/web/javascript/guide/regular_expressions/index.md

@@ -157,18 +157,7 @@ For instance, to match the string "C:\\" where "C" can be any letter, you'd use
 If using the `RegExp` constructor with a string literal, remember that the backslash is an escape in string literals, so to use it in the regular expression, you need to escape it at the string literal level.
 `/a\*b/` and `new RegExp("a\\*b")` create the same expression, which searches for "a" followed by a literal "\*" followed by "b".
 
-If escape strings are not already part of your pattern you can add them using {{jsxref("String.prototype.replace()")}}:
-
-```js
-function escapeRegExp(string) {
-  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
-}
-```
-
-The "g" after the regular expression is an option or flag that performs a global search, looking in the whole string and returning all matches.
-It is explained in detail below in [Advanced Searching With Flags](#advanced_searching_with_flags).
-
-_Why isn't this built into JavaScript?_ There is a [proposal](https://github.com/tc39/proposal-regex-escaping) to add such a function to RegExp.
+The {{jsxref("RegExp.escape()")}} function returns a new string where all special characters in regex syntax are escaped. This allows you to do `new RegExp(RegExp.escape("a*b"))` to create a regular expression that matches only the string `"a*b"`.
 
 ### Using parentheses
 

files/en-us/web/javascript/reference/global_objects/regexp/escape/index.md

@@ -0,0 +1,108 @@
+---
+title: RegExp.escape()
+slug: Web/JavaScript/Reference/Global_Objects/RegExp/escape
+page-type: javascript-static-method
+browser-compat: javascript.builtins.RegExp.escape
+---
+
+{{JSRef}}
+
+The **`RegExp.escape()`** static method [escapes](/en-US/docs/Web/JavaScript/Reference/Regular_expressions#escape_sequences) any potential regex syntax characters in a string, and returns a new string that can be safely used as a [literal](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Literal_character) pattern for the {{jsxref("RegExp/RegExp", "RegExp()")}} constructor.
+
+When dynamically creating a {{jsxref("RegExp")}} with user-provided content, consider using this function to sanitize the input (unless the input is actually intended to contain regex syntax). In addition, don't try to re-implement its functionality by, for example, using {{jsxref("String.prototype.replaceAll()")}} to insert a `\` before all syntax characters. `RegExp.escape()` is designed to use escape sequences that work in many more edge cases/contexts than hand-crafted code is likely to achieve.
+
+## Syntax
+
+```js-nolint
+RegExp.escape(string)
+```
+
+### Parameters
+
+- `string`
+  - : The string to escape.
+
+### Return value
+
+A new string that can be safely used as a literal pattern for the {{jsxref("RegExp/RegExp", "RegExp()")}} constructor. Namely, the following things in the input string are replaced:
+
+- The first character of the string, if it's either a decimal digit (0–9) or ASCII letter (a–z, A–Z), is escaped using the `\x` [character escape](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape) syntax. For example, `RegExp.escape("foo")` returns `"\\x66oo"` (here and after, the two backslashes in a string literal denote a single backslash character). This step ensures that if this escaped string is embedded into a bigger pattern where it's immediately preceded by `\1`, `\x0`, `\u000`, etc., the leading character doesn't get interpreted as part of the escape sequence.
+- Regex [syntax characters](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Literal_character#description), including `^`, `$`, `\`, `.`, `*`, `+`, `?`, `(`, `)`, `[`, `]`, `{`, `}`, and `|`, as well as the `/` delimiter, are escaped by inserting a `\` character before them. For example, `RegExp.escape("foo.bar")` returns `"\\x66oo\\.bar"`, and `RegExp.escape("(foo)")` returns `"\\(foo\\)"`.
+- Other punctuators, including `,`, `-`, `=`, `<`, `>`, `#`, `&`, `!`, `%`, `:`, `;`, `@`, `~`, `'`, `` ` ``, and `"`, are escaped using the `\x` syntax. For example, `RegExp.escape("foo-bar")` returns `"\\x66oo\\x2dbar"`. These characters cannot be escaped by prefixing with `\` because, for example, `/foo\-bar/u` is a syntax error.
+- The characters with their own [character escape](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape) sequences: `\f` (U+000C FORM FEED), `\n` (U+000A LINE FEED), `\r` (U+000D CARRIAGE RETURN), `\t` (U+0009 CHARACTER TABULATION), and `\v` (U+000B LINE TABULATION), are replaced with their escape sequences. For example, `RegExp.escape("foo\nbar")` returns `"\\x66oo\\nbar"`.
+- The space character is escaped as `"\\x20"`.
+- Other non-ASCII [line break and white space characters](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#white_space) are replaced with one or two `\uXXXX` escape sequences representing their UTF-16 code units. For example, `RegExp.escape("foo\u2028bar")` returns `"\\x66oo\\u2028bar"`.
+- [Lone surrogates](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#utf-16_characters_unicode_code_points_and_grapheme_clusters) are replaced with their `\uXXXX` escape sequences. For example, `RegExp.escape("foo\uD800bar")` returns `"\\x66oo\\ud800bar"`.
+
+### Exceptions
+
+- {{jsxref("TypeError")}}
+  - : Thrown if `string` is not a string.
+
+## Examples
+
+### Using RegExp.escape()
+
+The following examples demonstrate various inputs and outputs for the `RegExp.escape()` method.
+
+```js
+RegExp.escape("Buy it. use it. break it. fix it.");
+// "\\x42uy\\x20it\\.\\x20use\\x20it\\.\\x20break\\x20it\\.\\x20fix\\x20it\\."
+RegExp.escape("foo.bar"); // "\\x66oo\\.bar"
+RegExp.escape("foo-bar"); // "\\x66oo\\x2dbar"
+RegExp.escape("foo\nbar"); // "\\x66oo\\nbar"
+RegExp.escape("foo\uD800bar"); // "\\x66oo\\ud800bar"
+RegExp.escape("foo\u2028bar"); // "\\x66oo\\u2028bar"
+```
+
+### Using RegExp.escape() with the RegExp constructor
+
+The primary use case of `RegExp.escape()` is when you want to embed a string into a bigger regex pattern, and you want to ensure that the string is treated as a literal pattern, not as a regex syntax. Consider the following naïve example that replaces URLs:
+
+```js
+function removeDomain(text, domain) {
+  return text.replace(new RegExp(`https?://${domain}(?=/)`, "g"), "");
+}
+
+const input =
+  "Consider using [RegExp.escape()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape) to escape special characters in a string.";
+const domain = "developer.mozilla.org";
+console.log(removeDomain(input, domain));
+// Consider using [RegExp.escape()](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape) to escape special characters in a string.
+```
+
+Inserting the `domain` above results in the regular expression literal `https?://developer.mozilla.org(?=/)`, where the "." character is a regex [wildcard](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Wildcard) character. This means the string will match the string with any character in place of the ".", such as `developer-mozilla-org`. Therefore, it would incorrectly also change the following text:
+
+```js
+const input =
+  "This is not an MDN link: https://developer-mozilla.org/, be careful!";
+const domain = "developer.mozilla.org";
+console.log(removeDomain(input, domain));
+// This is not an MDN link: /, be careful!
+```
+
+To fix this, we can use `RegExp.escape()` to ensure that any user input is treated as a literal pattern:
+
+```js
+function removeDomain(text, domain) {
+  return text.replace(
+    new RegExp(`https?://${RegExp.escape(domain)}(?=/)`, "g"),
+    "",
+  );
+}
+```
+
+Now this function will do exactly what we intend to, and will not transform `developer-mozilla.org` URLs.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Polyfill of `RegExp.escape` in `core-js`](https://github.com/zloirock/core-js#regexp-escaping)
+- {{jsxref("RegExp")}}

files/en-us/web/javascript/reference/global_objects/regexp/index.md

@@ -115,6 +115,11 @@ Note that several of the `RegExp` properties have both long and short (Perl-like
 - [`RegExp[Symbol.species]`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.species)
   - : The constructor function that is used to create derived objects.
 
+## Static methods
+
+- {{jsxref("RegExp.escape()")}}
+  - : [Escapes](/en-US/docs/Web/JavaScript/Reference/Regular_expressions#escape_sequences) any potential regex syntax characters in a string, and returns a new string that can be safely used as a [literal](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Literal_character) pattern for the {{jsxref("RegExp/RegExp", "RegExp()")}} constructor.
+
 ## Instance properties
 
 These properties are defined on `RegExp.prototype` and shared by all `RegExp` instances.

files/en-us/web/javascript/reference/global_objects/string/replaceall/index.md

@@ -41,7 +41,7 @@ A new string, with all matches of a pattern replaced by a replacement.
 
 This method does not mutate the string value it's called on. It returns a new string.
 
-Unlike [`replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), this method would replace all occurrences of a string, not just the first one. This is especially useful if the string is not statically known, as calling the [`RegExp()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) constructor without escaping special characters may unintentionally change its semantics.
+Unlike [`replace()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), this method replaces all occurrences of a string, not just the first one. While it is also possible to use `replace()` with a global regex dynamically constructed with [`RegExp()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp) to replace all instances of a string, this can have unintended consequences if the string contains special characters that have meaning in regular expressions (which might happen if the replacement string comes from user input). While you can mitigate this case using {{jsxref("RegExp.escape()")}} to make the regular expression string into a literal pattern, it is better to just use `replaceAll()` and pass the string without converting it to a regex.
 
 ```js
 function unsafeRedactName(text, name) {

files/en-us/web/javascript/reference/regular_expressions/index.md

@@ -147,7 +147,7 @@ _Escape sequences_ in regexes refer to any kind of syntax formed by `\` followed
 [VCC]: /en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_class#v-mode_character_class
 [WBA]: /en-US/docs/Web/JavaScript/Reference/Regular_expressions/Word_boundary_assertion
 
-`\` followed by any other digit character becomes a [legacy octal escape sequence](/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features#escape_sequences), which is forbidden in [Unicode-aware mode](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode#unicode-aware_mode).
+`\` followed by `0` and another digit becomes a [legacy octal escape sequence](/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features#escape_sequences), which is forbidden in [Unicode-aware mode](/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/unicode#unicode-aware_mode). `\` followed by any other digit sequence becomes a [backreference](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Backreference).
 
 In addition, `\` can be followed by some non-letter-or-digit characters, in which case the escape sequence is always a [character escape](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape) representing the escaped character itself: