Allow circular references of project references

Search Terms

circular reference project references graph

Suggestion

Currently, project reference graphs are required to be acyclical because

• Project references imply a .d.ts file is loaded, and .d.ts files can't exist before the build occurs
• Only acyclic graphs can be topologically sorted

Both of these problems are solvable without too much work.

With the work done in #32028, we can effectively toggle the redirecting behavior, fixing the first issue. This would be done during the initial build phase only when an upstream project dependency isn't built yet.

The other problem is that project build order might not be predictable if we arbitrarily pick some starting point in the unsortable graph. This is fixable if we force solution authors to indicate which edges in the graph should be treated as ignored for the purposes of the topological sort:

    "references": [
        { "path": "../a" },
        { "path": "../b", "circular": true },
                          ^^^^^^^^^^^^^^^^
        { "path": "../c" }
    ],

The benefits of this are:

• In case of suboptimal .d.ts generation or memory pressure, developers can control where the "weak" link occurs in the build process
• The build ordering is fully deterministic regardless of starting point
• Graphs can't become "accidentally" circular - this is a clear opt-in

Use Cases

npm and other package managers do allow circularities in dependency graphs, so this is apparently a thing.
We've also gotten feedback from some industry partners that they want to move to project references, but their dependency graph is circular in a way that would require a lot of work to "fix".

Examples

Given the graph:

A -> B -> C -(circular)-> A

The build order is deterministically C, B, A. During C's compilation, source file redirects from C to A are not active.

Checklist

My suggestion meets these guidelines:

• 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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Inizia leggendo l’implementazione della build di project-reference e dell’ordinamento del grafo, insieme al lavoro descritto in #32028. Traccia il modo in cui le project references implicano reindirizzamenti dei file di dichiarazione e come l’ordine di build viene ordinato topologicamente. Il lavoro è completo quando i riferimenti circolari sono contrassegnati esplicitamente, l’ordine è deterministico e le build iniziali gestiscono i reindirizzamenti disabilitati descritti nell’esempio.