microsoft · graphemecluster (graphemecluster) · Sep 24, 2026 · Daniel Rosenwasser (DanielRosenwasser) · Sep 25, 2026
diff --git a/tsc/internal/bundled/libs/lib.es2015.symbol.wellknown.d.ts b/tsc/internal/bundled/libs/lib.es2015.symbol.wellknown.d.ts
@@ -180,48 +180,37 @@ interface PromiseConstructor {
 
 interface RegExp {
     /**
-     * Matches a string with this regular expression, and returns an array containing the results of
-     * that search.
+     * Matches a string with this regular expression.
      * @param string A string to search within.
+     * @returns An array containing the matches, or `null` if no matches are present.
      */
     [Symbol.match](string: string): RegExpMatchArray | null;
 
     /**
-     * Replaces text in a string, using this regular expression.
-     * @param string A String object or string literal whose contents matching against
-     *               this regular expression will be replaced
-     * @param replaceValue A String object or string literal containing the text to replace for every
-     *                     successful match of this regular expression.
-     */
-    [Symbol.replace](string: string, replaceValue: string): string;
-
-    /**
-     * Replaces text in a string, using this regular expression.
-     * @param string A String object or string literal whose contents matching against
-     *               this regular expression will be replaced
-     * @param replacer A function that returns the replacement text.
+     * Replaces one or more occurrences of substrings that match this regular expression.
+     * All matches are replaced if the `g` (global) flag is set
+     * (or only those matches at the beginning, if the `y` (sticky) flag is also present).
+     * Otherwise, only the first match is replaced.
+     * @param string A string to search within.
+     * @param replaceValue The replacement text, or a callback function that returns the replacement text.
      */
-    [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string;
+    [Symbol.replace](string: string, replaceValue: string | ((substring: string, ...args: any[]) => string)): string;
 
     /**
-     * Finds the position beginning first substring match in a regular expression search
-     * using this regular expression.
-     *
-     * @param string The string to search within.
+     * Returns the index of the first occurrence that matches this regular expression, or `-1` if no matches are present.
+     * @param string A string to search within.
      */
     [Symbol.search](string: string): number;
 
     /**
-     * Returns an array of substrings that were delimited by strings in the original input that
-     * match against this regular expression.
+     * Returns an array of substrings that were delimited by separators that match this regular expression.
      *
      * If the regular expression contains capturing parentheses, then each time this
      * regular expression matches, the results (including any undefined results) of the
      * capturing parentheses are spliced.
      *
-     * @param string string value to split
-     * @param limit if not undefined, the output array is truncated so that it contains no more
-     * than 'limit' elements.
+     * @param string The string value to be split.
+     * @param limit If specified, the output array is truncated so that it contains no more than `limit` elements.
      */
     [Symbol.split](string: string, limit?: number): string[];
 }
@@ -232,38 +221,34 @@ interface RegExpConstructor {
 
 interface String {
     /**
-     * Matches a string or an object that supports being matched against, and returns an array
-     * containing the results of that search, or null if no matches are found.
+     * Passes the string to the `[Symbol.match]` method on {@linkcode matcher}.
+     * This method is expected to implement its own matching algorithm.
      * @param matcher An object that supports being matched against.
      */
-    match(matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null;
+    match<This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R;
 
     /**
-     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.
+     * Passes the string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
+     * This method is expected to implement its own replacement algorithm.
      * @param searchValue An object that supports searching for and replacing matches within a string.
-     * @param replaceValue The replacement text.
-     */
-    replace(searchValue: { [Symbol.replace](string: string, replaceValue: string): string; }, replaceValue: string): string;
-
-    /**
-     * Replaces text in a string, using an object that supports replacement within a string.
-     * @param searchValue A object can search for and replace matches within a string.
-     * @param replacer A function that returns the replacement text.
+     * @param replaceValue A value to be passed into {@linkcode searchValue}.
      */
-    replace(searchValue: { [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string; }, replacer: (substring: string, ...args: any[]) => string): string;
+    replace<This, T, R>(this: This, searchValue: { [Symbol.replace](string: This, replaceValue: T): R; }, replaceValue: T): R;
 
     /**
-     * Finds the first substring match in a regular expression search.
-     * @param searcher An object which supports searching within a string.
+     * Passes the string to the `[Symbol.search]` method on {@linkcode searcher}.
+     * This method is expected to implement its own searching algorithm.
+     * @param searcher An object that supports searching within a string.
      */
-    search(searcher: { [Symbol.search](string: string): number; }): number;
+    search<This, R>(this: This, searcher: { [Symbol.search](string: This): R; }): R;
 
     /**
-     * Split a string into substrings using the specified separator and return them as an array.
-     * @param splitter An object that can split a string.
-     * @param limit A value used to limit the number of elements returned in the array.
+     * Passes the string and {@linkcode limit} to the `[Symbol.split]` method on {@linkcode splitter}.
+     * This method is expected to implement its own splitting algorithm.
+     * @param splitter An object that supports splitting a string.
+     * @param limit A value to be passed into {@linkcode splitter}.
      */
-    split(splitter: { [Symbol.split](string: string, limit?: number): string[]; }, limit?: number): string[];
+    split<This, T, R>(this: This, splitter: { [Symbol.split](string: This, limit?: T): R; }, limit?: T): R;
 }
 
 interface ArrayBuffer {

diff --git a/tsc/internal/bundled/libs/lib.es2020.string.d.ts b/tsc/internal/bundled/libs/lib.es2020.string.d.ts
@@ -20,11 +20,20 @@ and limitations under the License.
 
 interface String {
     /**
-     * Matches a string with a regular expression, and returns an iterable of matches
-     * containing the results of that search.
-     * @param regexp A regular expression
+     * Matches a string with a regular expression.
+     * @param regexp The regular expression for searching. If the provided value is not a RegExp,
+     * it is implicitly converted to a RegExp with the global (`g`) flag set by `new RegExp(regexp, "g")`.
+     * @returns An iterator of regular expression matches.
+     * @throws A {@linkcode TypeError} if the global (`g`) flag is not set on the RegExp.
      */
-    matchAll(regexp: RegExp): RegExpStringIterator<RegExpExecArray>;
+    matchAll(regexp: RegExp | string): RegExpStringIterator<RegExpExecArray>;
+
+    /**
+     * Passes the string to the `[Symbol.matchAll]` method on {@linkcode matcher}.
+     * This method is expected to implement its own matching algorithm.
+     * @param matcher An object that supports being matched against.
+     */
+    matchAll<This, R>(this: This, matcher: { [Symbol.matchAll](string: This): R; }): R;
 
     /** Converts all alphabetic characters to lowercase, taking into account the host environment's current locale. */
     toLocaleLowerCase(locales?: Intl.LocalesArgument): string;

diff --git a/tsc/internal/bundled/libs/lib.es2020.symbol.wellknown.d.ts b/tsc/internal/bundled/libs/lib.es2020.symbol.wellknown.d.ts
@@ -31,9 +31,10 @@ interface RegExpStringIterator<T> extends IteratorObject<T, BuiltinIteratorRetur
 
 interface RegExp {
     /**
-     * Matches a string with this regular expression, and returns an iterable of matches
-     * containing the results of that search.
+     * Matches a string with this regular expression.
      * @param string A string to search within.
+     * @returns An iterator of regular expression matches.
+     * @throws A {@linkcode TypeError} if the global (`g`) flag is not set on the RegExp.
      */
-    [Symbol.matchAll](str: string): RegExpStringIterator<RegExpExecArray>;
+    [Symbol.matchAll](string: string): RegExpStringIterator<RegExpExecArray>;
 }
diff --git a/tsc/internal/bundled/libs/lib.es2021.string.d.ts b/tsc/internal/bundled/libs/lib.es2021.string.d.ts
@@ -16,16 +16,19 @@ and limitations under the License.
 
 interface String {
     /**
-     * Replace all instances of a substring in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
-     * @param replaceValue A string containing the text to replace for every successful match of searchValue in this string.
+     * Replaces all instances of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, a `TypeError` is thrown if the `g` (global) flag is not set
+     * (only matches at the beginning are replaced if the `y` (sticky) flag is also present).
+     * @param searchValue A string or regular expression to search for.
+     * @param replaceValue The replacement text, or a callback function that returns the replacement text.
      */
-    replaceAll(searchValue: string | RegExp, replaceValue: string): string;
+    replaceAll(searchValue: string | RegExp, replaceValue: string | ((substring: string, ...args: any[]) => string)): string;
 
     /**
-     * Replace all instances of a substring in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
-     * @param replacer A function that returns the replacement text.
+     * Passes the string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}.
+     * This method is expected to implement its own replacement algorithm.
+     * @param searchValue An object that supports searching for and replacing matches within a string.
+     * @param replaceValue A value to be passed into {@linkcode searchValue}.
      */
-    replaceAll(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string;
+    replaceAll<This, T, R>(this: This, searchValue: { [Symbol.replace](string: This, replaceValue: T): R; }, replaceValue: T): R;
 }
diff --git a/tsc/internal/bundled/libs/lib.es5.d.ts b/tsc/internal/bundled/libs/lib.es5.d.ts
@@ -448,28 +448,27 @@ interface String {
     localeCompare(that: string): number;
 
     /**
-     * Matches a string with a regular expression, and returns an array containing the results of that search.
-     * @param regexp A variable name or string literal containing the regular expression pattern and flags.
+     * Matches the string with a regular expression.
+     * @param regexp The regular expression for searching. If the provided value is not a RegExp,
+     * it is implicitly converted to a RegExp without flags by `new RegExp(regexp)`.
+     * @returns An array containing the matches, or `null` if no matches are present.
      */
     match(regexp: string | RegExp): RegExpMatchArray | null;
 
     /**
-     * Replaces text in a string, using a regular expression or search string.
+     * Replaces one or more occurrences of substrings that match a search string or a regular expression.
+     * When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` (global) flag is set
+     * (or only those matches at the beginning, if the `y` (sticky) flag is also present).
+     * Otherwise, only the first match of {@linkcode searchValue} is replaced.
      * @param searchValue A string or regular expression to search for.
-     * @param replaceValue A string containing the text to replace. When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` flag is set (or only those matches at the beginning, if the `y` flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.
+     * @param replaceValue The replacement text, or a callback function that returns the replacement text.
      */
-    replace(searchValue: string | RegExp, replaceValue: string): string;
+    replace(searchValue: string | RegExp, replaceValue: string | ((substring: string, ...args: any[]) => string)): string;
 
     /**
-     * Replaces text in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
-     * @param replacer A function that returns the replacement text.
-     */
-    replace(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string;
-
-    /**
-     * Finds the first substring match in a regular expression search.
-     * @param regexp The regular expression pattern and applicable flags.
+     * Returns the index of the first occurrence that matches a regular expression, or `-1` if no matches are present.
+     * @param regexp The regular expression for searching. If the provided value is not a RegExp,
+     * it is implicitly converted to a RegExp without flags by `new RegExp(regexp)`.
      */
     search(regexp: string | RegExp): number;
 
@@ -482,9 +481,15 @@ interface String {
     slice(start?: number, end?: number): string;
 
     /**
-     * Split a string into substrings using the specified separator and return them as an array.
-     * @param separator A string that identifies character or characters to use in separating the string. If omitted, a single-element array containing the entire string is returned.
-     * @param limit A value used to limit the number of elements returned in the array.
+     * Returns an array of substrings that were delimited by separators in the string.
+     * @param separator A string or a regular expression that identifies characters to use in separating the string.
+     * If omitted, a single-element array containing the entire string is returned.
+     *
+     * If the regular expression contains capturing parentheses, then each time this
+     * regular expression matches, the results (including any undefined results) of the
+     * capturing parentheses are spliced into the output array.
+     *
+     * @param limit If specified, the output array is truncated so that it contains no more than `limit` elements.
      */
     split(separator: string | RegExp, limit?: number): string[];
 

diff --git a/tsc/testdata/baselines/reference/compiler/bestChoiceType.types b/tsc/testdata/baselines/reference/compiler/bestChoiceType.types
@@ -9,9 +9,9 @@
 >(''.match(/ /) || []) : RegExpMatchArray | []
 >''.match(/ /) || [] : RegExpMatchArray | []
 >''.match(/ /) : RegExpMatchArray | null
->''.match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>''.match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >'' : ""
->match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >/ / : RegExp
 >[] : []
 >map : (<U>(callbackfn: (value: string, index: number, array: string[]) => U, thisArg?: any) => U[]) | (<U>(callbackfn: (value: never, index: number, array: never[]) => U, thisArg?: any) => U[])
@@ -30,9 +30,9 @@ function f1() {
     let x = ''.match(/ /);
 >x : RegExpMatchArray | null
 >''.match(/ /) : RegExpMatchArray | null
->''.match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>''.match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >'' : ""
->match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >/ / : RegExp
 
     let y = x || [];
@@ -61,9 +61,9 @@ function f2() {
     let x = ''.match(/ /);
 >x : RegExpMatchArray | null
 >''.match(/ /) : RegExpMatchArray | null
->''.match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>''.match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >'' : ""
->match : { (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }
+>match : { (regexp: string | RegExp): RegExpMatchArray | null; <This, R>(this: This, matcher: { [Symbol.match](string: This): R; }): R; }
 >/ / : RegExp
 
     let y = x ? x : [];

diff --git a/tsc/testdata/baselines/reference/compiler/controlFlowPropertyDeclarations.symbols b/tsc/testdata/baselines/reference/compiler/controlFlowPropertyDeclarations.symbols
@@ -222,15 +222,15 @@ export class HTMLtoJSX {
       // wrapping newlines and sequences of two or more spaces in variables.
       text = text
 >text : Symbol(text, Decl(controlFlowPropertyDeclarations.ts, 113, 7))
->text        .replace(/\r/g, '')        .replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
->text        .replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
+>text        .replace(/\r/g, '')        .replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
+>text        .replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
 >text : Symbol(text, Decl(controlFlowPropertyDeclarations.ts, 113, 7))
 
         .replace(/\r/g, '')
->replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
+>replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
 
         .replace(/( {2,}|\n|\t|\{|\})/g, function(whitespace) {
->replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
+>replace : Symbol(String.replace, Decl(lib.es5.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --))
 >whitespace : Symbol(whitespace, Decl(controlFlowPropertyDeclarations.ts, 121, 50))
 
           return '{' + JSON.stringify(whitespace) + '}';