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.

Beginne damit, die Implementierung für den project-reference-Build und die Graph-Sortierung sowie die in #32028 beschriebene Arbeit zu lesen. Verfolge, wie project references Weiterleitungen von Deklarationsdateien implizieren und wie die Build-Reihenfolge topologisch sortiert wird. Als erledigt gilt die Aufgabe, wenn zirkuläre Referenzen explizit markiert sind, die Reihenfolge deterministisch ist und initiale Builds die im Beispiel beschriebenen deaktivierten Weiterleitungen behandeln.