Skip to content

Loosen lib types for string methods that internally call %Symbol.*% methods - #64442

Open
graphemecluster (graphemecluster) wants to merge 1 commit into
microsoft:mainfrom
graphemecluster:string-api-using-symbol-methods
Open

graphemecluster (graphemecluster) wants to merge 1 commit into
microsoft:mainfrom
graphemecluster:string-api-using-symbol-methods

Conversation

@graphemecluster

@graphemecluster graphemecluster (graphemecluster) commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

This is intended as a more general fix to #54387.
Out of String.{replace,match}{,All}, .search and .split, modify or add signatures involving custom objects implementing well-known symbol methods, the parameter and return types of which are now preserved (yes, per the spec they just directly call the raw value and return the raw result. There is no type coercion involved, so I think it is acceptable to define them like this).
The addition of replaceAll and matchAll signatures ensures their definitions are parallel to their equivalent without All.
The wordings of the documentation are adjusted accordingly.

Fixes #54387
Fixes #61448

For historical reference, most of this PR was extracted from #60249 (generic RegExp is excluded of course).

Copilot AI balanced review requested due to automatic review settings September 25, 2026 00:01
@typescript-automation typescript-automation Bot added the For Milestone Bug PRs that fix a bug with a specific milestone label Sep 25, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The new replacement signatures introduce implicit-any regressions and the custom-symbol inference behavior lacks focused tests.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: None

What changed in this PR

This PR broadens String well-known-symbol method typings to preserve custom argument and return types.

Changes:

  • Adds generic custom-symbol overloads for matching, replacing, searching, and splitting.
  • Expands matchAll/replaceAll inputs and revises documentation.
  • Updates affected compiler and call-hierarchy baselines.
File Description
tsc/​testdata/​baselines/​reference/​fourslash/​callHierarchy/​callHierarchyInPropDeclarationOfExportedDefaultClass1.callHierarchy.txt Updates shifted library spans.
tsc/​testdata/​baselines/​reference/​fourslash/​callHierarchy/​callHierarchyIncomingCallsObjectLiteralMethodInStringLiteralComputedProperty.callHierarchy.txt Updates split hierarchy output.
tsc/​testdata/​baselines/​reference/​fourslash/​callHierarchy/​callHierarchyIncomingCallsObjectLiteralMethodInIdentifierComputedProperty.callHierarchy.txt Updates split hierarchy output.
tsc/​testdata/​baselines/​reference/​fourslash/​callHierarchy/​callHierarchyIncomingCallsObjectLiteralMethodInExpressionComputedProperty.callHierarchy.txt Updates split hierarchy output.
tsc/​testdata/​baselines/​reference/​fourslash/​callHierarchy/​callHierarchyIncomingCallsNoCrashArrayPush.callHierarchy.txt Updates shifted library spans.
tsc/​testdata/​baselines/​reference/​conformance/​useRegexpGroups.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​conformance/​parserRealSource11.types Records revised replace and split types.
tsc/​testdata/​baselines/​reference/​conformance/​parserRealSource11.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​conformance/​parserharness.types Records consolidated replace signature.
tsc/​testdata/​baselines/​reference/​conformance/​parserharness.symbols Updates replace symbols.
tsc/​testdata/​baselines/​reference/​conformance/​parserArgumentList1.types Records lost callback contextual types.
tsc/​testdata/​baselines/​reference/​conformance/​parserArgumentList1.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​conformance/​parserArgumentList1.errors.txt Adds callback implicit-any diagnostics.
tsc/​testdata/​baselines/​reference/​conformance/​parser630933.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​stringMatchAll.types Records expanded matchAll signatures.
tsc/​testdata/​baselines/​reference/​compiler/​stringMatchAll.symbols Records added matchAll declaration.
tsc/​testdata/​baselines/​reference/​compiler/​regExpWithSlashInCharClass.types Records revised replace types.
tsc/​testdata/​baselines/​reference/​compiler/​regExpWithSlashInCharClass.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​compiler/​regexMatchAll.types Updates parameter naming.
tsc/​testdata/​baselines/​reference/​compiler/​regexMatchAll-esnext.types Updates parameter naming.
tsc/​testdata/​baselines/​reference/​compiler/​overloadResolutionOverNonCTLambdas.types Records revised replace overloads.
tsc/​testdata/​baselines/​reference/​compiler/​overloadResolutionOverNonCTLambdas.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​compiler/​noImplicitAnyInContextuallyTypesFunctionParamter.types Records revised replace overloads.
tsc/​testdata/​baselines/​reference/​compiler/​noImplicitAnyInContextuallyTypesFunctionParamter.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​compiler/​narrowingWithNonNullExpression.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​initializedDestructuringAssignmentTypes.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​flatArrayNoExcessiveStackDepth.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​firstMatchRegExpMatchArray.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​extendGlobalThis.types Records generic split overload.
tsc/​testdata/​baselines/​reference/​compiler/​doYouNeedToChangeYourTargetLibraryES2016Plus.types Records generic match overload.
tsc/​testdata/​baselines/​reference/​compiler/​controlFlowPropertyDeclarations.types Records revised replace types.
tsc/​testdata/​baselines/​reference/​compiler/​controlFlowPropertyDeclarations.symbols Updates replace declarations.
tsc/​testdata/​baselines/​reference/​compiler/​bestChoiceType.types Records generic match overload.
tsc/​internal/​bundled/​libs/​lib.es5.d.ts Revises core string signatures and docs.
tsc/​internal/​bundled/​libs/​lib.es2021.string.d.ts Expands replaceAll overloads.
tsc/​internal/​bundled/​libs/​lib.es2020.symbol.wellknown.d.ts Revises RegExp.matchAll documentation.
tsc/​internal/​bundled/​libs/​lib.es2020.string.d.ts Expands String.matchAll.
tsc/​internal/​bundled/​libs/​lib.es2015.symbol.wellknown.d.ts Generalizes well-known-symbol dispatch.

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

* @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;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a while back we decided not to thread through this parameters in methods with callbacks because of perf costs. Maybe it matters less now.

@DanielRosenwasser

Copy link
Copy Markdown
Member

TypeScript Bot (@typescript-bot) test it

@typescript-automation

typescript-automation Bot commented Sep 25, 2026 •

Copy link
Copy Markdown

Starting jobs; this comment will be updated as builds start and complete.

Command Status Results
test top400 ✅ Started 👀 Results
user test this ✅ Started 👀 Results
run dt ✅ Started ✅ Results
perf test this faster ✅ Started 👀 Results

@typescript-automation

Copy link
Copy Markdown

Daniel Rosenwasser (@DanielRosenwasser)
The results of the perf run you requested are in!

Here they are:

tsc

Comparison Report - baseline..pr
Metric baseline pr Delta Best Worst p-value
Compiler-Unions - native
Errors 41 41 ~ ~ ~ p=1.000 n=12
Symbols 115,480 115,514 +34 (+ 0.03%) ~ ~ p=0.000 n=12
Types 96,949 96,980 +31 (+ 0.03%) ~ ~ p=0.000 n=12
Memory Used 148,741k (± 0.47%) 147,962k (± 0.28%) ~ 146,946k 148,998k p=0.089 n=12
Memory Allocs 2,271,678 (± 0.00%) 2,272,571 (± 0.00%) +893 (+ 0.04%) 2,272,224 2,272,778 p=0.000 n=12
Config Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Parse Time 0.040s (± 4.38%) 0.041s (± 4.12%) ~ 0.037s 0.046s p=0.280 n=12
Bind Time 0.012s (± 9.31%) 0.014s (±13.69%) ~ 0.010s 0.019s p=0.171 n=12
Check Time 0.503s (± 1.01%) 0.500s (± 0.68%) ~ 0.494s 0.511s p=0.296 n=12
Emit Time 0.266s (± 2.09%) 0.272s (± 2.05%) ~ 0.258s 0.287s p=0.164 n=12
Total Time 0.827s (± 0.94%) 0.833s (± 0.82%) ~ 0.814s 0.853s p=0.103 n=12
angular-1 - native
Errors 3 3 ~ ~ ~ p=1.000 n=12
Symbols 847,544 (± 0.04%) 854,952 (± 0.08%) +7,408 (+ 0.87%) 852,987 856,891 p=0.000 n=12
Types 250,004 (± 0.00%) 253,414 (± 0.00%) +3,410 (+ 1.36%) 253,411 253,423 p=0.000 n=12
Memory Used 793,465k (± 0.04%) 797,504k (± 0.07%) +4,039k (+ 0.51%) 796,004k 799,636k p=0.000 n=12
Memory Allocs 12,959,106 (± 0.04%) 12,992,478 (± 0.05%) +33,372 (+ 0.26%) 12,984,788 13,015,318 p=0.000 n=12
Config Time 0.016s 0.016s ~ ~ ~ p=1.000 n=12
Parse Time 0.271s (± 3.41%) 0.267s (± 2.73%) ~ 0.251s 0.287s p=0.560 n=12
Bind Time 0.068s (±18.70%) 0.069s (±15.23%) ~ 0.057s 0.102s p=0.655 n=12
Check Time 0s 0s ~ ~ ~ p=1.000 n=12
Emit Time 1.627s (± 1.52%) 1.633s (± 1.60%) ~ 1.593s 1.694s p=0.944 n=12
Total Time 1.999s (± 1.66%) 2.005s (± 1.80%) ~ 1.950s 2.094s p=0.943 n=12
mui-docs - native
Errors 11,402 (± 0.04%) 11,404 (± 0.03%) ~ 11,391 11,408 p=0.343 n=12
Symbols 4,402,219 5,009,326 🔻+607,107 (+13.79%) ~ ~ p=0.000 n=12
Types 1,489,173 1,706,097 🔻+216,924 (+14.57%) ~ ~ p=0.000 n=12
Memory Used 4,787,797k (± 0.04%) 5,675,094k (± 0.03%) 🔻+887,296k (+18.53%) 5,671,089k 5,679,377k p=0.000 n=12
Memory Allocs 42,335,079 (± 0.05%) 52,264,445 (± 0.03%) 🔻+9,929,366 (+23.45%) 52,214,890 52,307,849 p=0.000 n=12
Config Time 0.016s (± 2.12%) 0.015s (± 2.02%) ~ 0.015s 0.016s p=0.680 n=12
Parse Time 0.568s (± 1.86%) 0.561s (± 1.95%) ~ 0.528s 0.585s p=0.297 n=12
Bind Time 0.002s 0.002s ~ ~ ~ p=1.000 n=12
Check Time 15.333s (± 0.31%) 15.870s (± 0.35%) +0.537s (+ 3.50%) 15.760s 16.025s p=0.000 n=12
Emit Time 0.463s (± 5.52%) 0.483s (±10.71%) ~ 0.427s 0.645s p=0.503 n=12
Total Time 17.138s (± 0.38%) 17.692s (± 0.33%) +0.554s (+ 3.23%) 17.548s 17.843s p=0.000 n=12
strada-build-src - native
Errors 0 0 ~ ~ ~ p=1.000 n=12
Symbols 1,394,252 1,395,757 +1,505 (+ 0.11%) ~ ~ p=0.000 n=12
Types 443,566 445,041 +1,475 (+ 0.33%) ~ ~ p=0.000 n=12
Memory Used 1,666,636k (± 0.71%) 1,655,219k (± 0.20%) ~ 1,646,169k 1,664,109k p=0.319 n=12
Memory Allocs 83,644,902 (± 0.04%) 83,464,463 (± 0.02%) -180,439 (- 0.22%) 83,425,020 83,504,430 p=0.000 n=12
Config Time 0.004s (±12.82%) 0.004s (±13.87%) ~ 0.003s 0.006s p=0.721 n=12
Parse Time 0.271s (± 2.72%) 0.270s (± 1.92%) ~ 0.260s 0.287s p=0.989 n=12
Bind Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Check Time 1.839s (± 0.72%) 1.789s (± 0.61%) -0.050s (- 2.72%) 1.767s 1.812s p=0.000 n=12
Emit Time 0.284s (± 4.24%) 0.291s (± 3.05%) ~ 0.268s 0.312s p=0.442 n=12
Total Time 21.167s (± 0.91%) 21.021s (± 0.56%) ~ 20.695s 21.245s p=0.319 n=12
strada-compiler - native
Errors 0 0 ~ ~ ~ p=1.000 n=12
Symbols 337,531 338,081 +550 (+ 0.16%) ~ ~ p=0.000 n=12
Types 198,885 198,716 -169 (- 0.08%) ~ ~ p=0.000 n=12
Memory Used 319,603k (± 0.03%) 319,074k (± 0.02%) -529k (- 0.17%) 318,899k 319,240k p=0.000 n=12
Memory Allocs 4,672,840 (± 0.01%) 4,664,718 (± 0.01%) -8,123 (- 0.17%) 4,663,306 4,666,471 p=0.000 n=12
Config Time 0.001s 0.001s ~ ~ ~ p=1.000 n=12
Parse Time 0.113s (± 3.76%) 0.112s (± 4.53%) ~ 0.103s 0.128s p=0.579 n=12
Bind Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Check Time 1.074s (± 0.50%) 1.072s (± 0.48%) ~ 1.062s 1.087s p=0.451 n=12
Emit Time 0.137s (±10.27%) 0.123s (±13.28%) ~ 0.095s 0.159s p=0.173 n=12
Total Time 1.375s (± 0.77%) 1.361s (± 1.44%) ~ 1.312s 1.423s p=0.103 n=12
ts-pre-modules - native
Errors 87 87 ~ ~ ~ p=1.000 n=12
Symbols 305,179 304,022 -1,157 (- 0.38%) ~ ~ p=0.000 n=12
Types 181,926 181,214 -712 (- 0.39%) ~ ~ p=0.000 n=12
Memory Used 277,127k (± 0.02%) 276,021k (± 0.07%) -1,106k (- 0.40%) 275,051k 276,268k p=0.000 n=12
Memory Allocs 1,641,995 (± 0.01%) 1,679,101 (± 0.01%) +37,106 (+ 2.26%) 1,678,331 1,679,693 p=0.000 n=12
Config Time 0.001s (±65.70%) 0.000s (±113.79%) ~ 0.000s 0.001s p=0.400 n=12
Parse Time 0.099s (± 3.73%) 0.099s (± 4.27%) ~ 0.088s 0.109s p=0.898 n=12
Bind Time 0.038s (±10.80%) 0.040s (±11.11%) ~ 0.029s 0.050s p=0.485 n=12
Check Time 0.838s (± 0.34%) 0.854s (± 1.76%) +0.015s (+ 1.83%) 0.834s 0.925s p=0.006 n=12
Emit Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Total Time 0.988s (± 0.63%) 1.006s (± 1.45%) +0.018s (+ 1.78%) 0.986s 1.075s p=0.007 n=12
vscode - native
Errors 371 371 ~ ~ ~ p=1.000 n=12
Symbols 9,677,458 9,677,948 +490 (+ 0.01%) ~ ~ p=0.000 n=12
Types 3,258,672 3,258,976 +304 (+ 0.01%) ~ ~ p=0.000 n=12
Memory Used 6,376,637k (± 0.02%) 6,378,036k (± 0.01%) +1,399k (+ 0.02%) 6,376,507k 6,379,501k p=0.010 n=12
Memory Allocs 48,938,156 (± 0.01%) 48,992,269 (± 0.01%) +54,113 (+ 0.11%) 48,985,955 49,011,135 p=0.000 n=12
Config Time 0.066s (± 0.55%) 0.066s (± 0.41%) ~ 0.065s 0.067s p=0.496 n=12
Parse Time 1.805s (± 2.41%) 1.767s (± 3.67%) ~ 1.652s 1.945s p=0.213 n=12
Bind Time 0.471s (±12.02%) 0.600s (±19.42%) ~ 0.400s 0.849s p=0.086 n=12
Check Time 12.874s (± 1.27%) 12.743s (± 1.38%) ~ 12.492s 13.105s p=0.192 n=12
Emit Time 4.463s (±12.60%) 4.782s (±10.91%) ~ 3.660s 5.558s p=0.590 n=12
Total Time 19.793s (± 2.21%) 20.071s (± 2.03%) ~ 19.162s 20.688s p=0.219 n=12
webpack - native
Errors 848 850 +2 (+ 0.24%) ~ ~ p=0.000 n=12
Symbols 1,358,721 1,438,463 🔻+79,742 (+ 5.87%) ~ ~ p=0.000 n=12
Types 597,693 613,701 +16,008 (+ 2.68%) ~ ~ p=0.000 n=12
Memory Used 954,323k (± 0.02%) 990,022k (± 0.01%) +35,699k (+ 3.74%) 989,709k 990,429k p=0.000 n=12
Memory Allocs 6,224,215 (± 0.02%) 6,346,064 (± 0.02%) +121,849 (+ 1.96%) 6,344,351 6,349,653 p=0.000 n=12
Config Time 0.009s 0.009s ~ ~ ~ p=1.000 n=12
Parse Time 0.264s (± 3.13%) 0.261s (± 1.78%) ~ 0.248s 0.274s p=0.339 n=12
Bind Time 0.065s (±18.85%) 0.067s (±16.49%) ~ 0.053s 0.100s p=0.405 n=12
Check Time 2.230s (± 0.86%) 1.943s (± 0.44%) 🟩-0.287s (-12.87%) 1.923s 1.965s p=0.000 n=12
Emit Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Total Time 2.602s (± 0.51%) 2.317s (± 0.28%) 🟩-0.285s (-10.97%) 2.301s 2.337s p=0.000 n=12
xstate-main - native
Errors 0 0 ~ ~ ~ p=1.000 n=12
Symbols 1,045,695 1,033,895 -11,800 (- 1.13%) ~ ~ p=0.000 n=12
Types 383,049 378,220 -4,829 (- 1.26%) ~ ~ p=0.000 n=12
Memory Used 611,284k (± 0.02%) 608,468k (± 0.02%) -2,816k (- 0.46%) 608,183k 608,673k p=0.000 n=12
Memory Allocs 4,830,656 (± 0.04%) 4,793,506 (± 0.04%) -37,150 (- 0.77%) 4,790,784 4,802,515 p=0.000 n=12
Config Time 0.003s (±12.54%) 0.003s 🔻+0.000s (+16.13%) ~ ~ p=0.037 n=12
Parse Time 0.148s (± 3.98%) 0.152s (± 3.53%) ~ 0.138s 0.163s p=0.354 n=12
Bind Time 0.046s (±16.30%) 0.043s (±17.12%) ~ 0.034s 0.068s p=0.721 n=12
Check Time 1.204s (± 0.70%) 1.146s (± 1.34%) 🟩-0.058s (- 4.81%) 1.104s 1.200s p=0.000 n=12
Emit Time 0.000s 0.000s ~ ~ ~ p=1.000 n=12
Total Time 1.412s (± 0.89%) 1.353s (± 1.11%) 🟩-0.059s (- 4.15%) 1.312s 1.397s p=0.000 n=12
System info unknown
Hosts
  • native
Scenarios
  • Compiler-Unions - native
  • angular-1 - native
  • mui-docs - native
  • strada-build-src - native
  • strada-compiler - native
  • ts-pre-modules - native
  • vscode - native
  • webpack - native
  • xstate-main - native
Benchmark Name Iterations
Current pr 12
Baseline baseline 12

Developer Information:

Download Benchmarks

@typescript-automation

Copy link
Copy Markdown

Daniel Rosenwasser (@DanielRosenwasser) Here are the results of running the user tests with tsc comparing main and refs/pull/64442/merge:

There were infrastructure failures potentially unrelated to your change:

  • 1 instance of "Git clone failed"
  • 1 instance of "Package install failed"

Otherwise...

Something interesting changed - please have a look.

Details

puppeteer

test/tsconfig.json

webpack

tsconfig.json

tsconfig.types.json

tsconfig.types.test.json

@typescript-automation

Copy link
Copy Markdown

Daniel Rosenwasser (@DanielRosenwasser) Here are the results of running the top 400 repos with tsc comparing main and refs/pull/64442/merge:

Something interesting changed - please have a look.

Details

diegosouzapw/OmniRoute

4 of 10 projects failed to build with the old tsc and were ignored

open-sse/tsconfig.json

neoclide/coc.nvim

tsconfig.json

tsconfig.test.json

SBoudrias/Inquirer.js

tsconfig.json

packages/inquirer/tsconfig.json

stablyai/orca

14 of 23 projects failed to build with the old tsc and were ignored

config/tsconfig.cli.json

config/tsconfig.tc.cli.json

config/tsconfig.tc.web.json

@typescript-automation

Copy link
Copy Markdown

Hey Daniel Rosenwasser (@DanielRosenwasser), the results of running the DT tests are ready.

Everything looks the same!

You can check the log here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

For Milestone Bug PRs that fix a bug with a specific milestone

Projects

Status: Not started

Development

Successfully merging this pull request may close these issues.

Add types for String.{matchAll,replaceAll} with a well known symbol Notes about String.replace

4 participants