[isolatedDeclarations] An option like disableSourceOfProjectReferenceRedirect, but configurable on the referenced project's end

🔍 Search Terms

isolated declarations disableSourceOfProjectReferenceRedirect editor vscode tsserver

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

disableSourceOfProjectReferenceRedirect is an option that improves performance by making it so that files can be typechecked using source files in referenced projects for type information rather than declaration files. I'm interested in a new option which enables this behavior only for projects that have isolated declarations enabled.

cc @sheetalkamat @andrewbranch - I'd be interested in working on this if this seems valuable.

📃 Motivating Example

With isolated declarations, it's now feasible to run a watcher in the background which can emit declarations quickly in response to changes. For projects with isolated declarations enabled, their dependent projects might be able to achieve a similar level of responsiveness by just reading from declaration files rather than from source files if there is a watcher emitting changes running in the background.

In a composite project where all sub-projects have isolatedDeclarations enabled, it would suffice to just enable disableSourceOfProjectReferenceRedirect for all projects, run watchers for each project, and reap all the benefits, but that might be suboptimal if there's a mix of projects with and without isolatedDeclarations enabled. This state can arise from there being a transition period as projects are being migrated.

A hybrid approach that might have the best of both worlds would be to enable the behavior of disableSourceOfProjectReferenceRedirect but only for the referenced projects that don't have isolated declarations enabled. To me, this would be more natural to specify on the referenced project, where it is effectively saying, "don't use my source files for typechecking, buddy", rather than on the dependent project. Regardless, I'll try to enumerate some concrete options:

Option A: New option on referenced project
disallowRedirectingToSources (default: false) - Prevent projects that reference this project from using the sources of this project for typechecking, via TSServer, in the editor. Can be used orthogonally with isolatedDeclarations but if it somehow eases implementation, could be restricted to usable only when isolatedDeclarations is enabled.

Option B: New value for existing disableSourceOfProjectReferenceRedirect option on dependent project
disableSourceOfProjectReferenceRedirect: "nonIsolatedDeclarations"

Option C: New option on dependent project
I don't feel like thinking of a name for this flag since I don't think it's a good idea anyway and it's annoying for end-users to have to consider how this flag interacts with others like disableSourceOfProjectReferenceRedirect.

💻 Use Cases

Better editing experience for large composite projects with a mix of isolated declarations usage.

Start with tsserver's handling of project references and the existing disableSourceOfProjectReferenceRedirect option, then compare the proposed referenced-project and dependent-project approaches. Done means selecting and implementing a coherent configuration behavior for mixed isolatedDeclarations projects, with coverage for the stated editor responsiveness use case.