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.

[dqsully]

@AlexLeung I’m not sure if this helps, but my team has been using pnpm workspaces to have our monorepo projects symlinked as node_module dependencies. I don’t know if this keeps any of the benefits of TypeScript project references, but it allows us to keep our code separated into distinct modules. The TypeScript compiler works great with this project structure, and the TypeScript Language Server for VSCode works too, although it can be a little slow at times in our project. I’m not sure if it doesn’t understand our symlinked structure and sometimes loads the same file multiple times, or if our project is just huge and abusive of TypeScript’s powers… Overall it works great for us though, and we’ve got 30+ modules

[JanKaczmarkiewicz]

I am trying to adopt strict mode in one package in monorepo. Packages have multiple circular dependencies, so right now project reference is not an option. It would be helpful to have the possibility to gradually migrate some of the packages to eg. strict mode without moving a lot of code between packages. I think many monorepo based projects can have similar problems and benefit from this proposal.