# The Cycle Problem

This document describes a situation with Angular applications that contain indirect cycles, which currently affect the output of the compiler and can cause issues with downstream builds.

There is no currently agreed upon solution to this problem.

## Indirect cycles via templates

Cycles are permitted in the ES module ecosystem, and occur when through a series of imports, a TS file ends up importing itself. Ordinarily this is detectable by looking at the imports of a program as a directed graph:

digraph cycle {
  "a.ts"->"b.ts"
  "b.ts"->"c.ts"
  "c.ts"->"a.ts"
}

In Angular Ivy, cycles can be introduced _indirectly_, without being present in the initial import graph. This is because the use of a component, directive, or pipe in the template of another will result in the _generation_ of an import at compile time, even if that import was not initially present.

Consider the following example:

//foo.ts
import {Unrelated} from './bar';

@Component({
  selector: 'foo-cmp',
  template: '...',
})
export class FooCmp {}

// bar.ts
@Component({
  selector: 'bar-cmp',
  template: '<foo-cmp></foo-cmp>',
})
export class BarCmp {}

export class Unrelated {...}

Initially, this program has an import graph which looks like:

digraph imports {
  "foo.ts"->"bar.ts"
}

However, there is an implicit edge from `bar.ts` back to `foo.ts` due to the use of `<foo-cmp>` in `BarCmp`'s template. This edge exists because Ivy dictates that because of the template reference, `BarCmp` have an `ɵcmp.directiveDefs` that contains `FooCmp.ɵcmp`. To construct this field, the Ivy compiler introduces an import of `FooCmp` into `bar.ts`, making the real import graph after compilation:

digraph imports {
  "foo.ts"->"bar.ts"
  edge [style=dashed]
  "bar.ts"->"foo.ts"
}

This would create an import cycle where it was not obvious to the user before that there was one.

### google3

Cycles like this are completely forbidden in google3, where the Closure Compiler enforces the acyclic nature of the import graph.

### External tooling

External tooling, including the ES module standards, TypeScript, Webpack, Uglify, Rollup, etc. all accept code with import cycles.

### View Engine's immunity

Angular's View Engine runtime and compiler did not suffer from this problem, for a simple reason: View Engine generates components as separate NgFactory files instead of inline into user code. This kept the user's imports separate from the ones that Angular needed to add. The import graph after compilation for View Engine looked like:

digraph ve_imports {
  "foo.ts"->"bar.ts"
  edge [style=dashed]
  "foo.ngfactory.ts"->"foo.ts"
  "bar.ngfactory.ts"->"bar.ts"
  "bar.ngfactory.ts"->"foo.ts"
}

Again, dashed lines represent the imports added by the VE compiler. There are no cycles in this graph.

## Mitigation

It was decided to implement a mitigation for this problem, for two reasons:

1. It would be impossible to land Ivy in g3 without either a mitigation or a major effort to refactor g3 apps, as many have such implicit cycles.

2. Even with external tooling which is accepting of cycles, the order of evaluation might result in previously working Angular apps breaking.

### Cycle detection

The Angular Ivy compiler (ngtsc) performs cycle detection when compiling components. It builds a graph of imports present in the user program and knows when the addition of an import for `directiveDefs` would result in the creation of a cycle.

A limitation of the current cycle detector is that it does not distinguish between imports of values (which cause runtime cycles) and imports of types (which are eventually elided by TypeScript and have no runtime impact). Thus, cycle detection occasionally produces false positives. The TypeScript feature for `import type` might offer some relief from this.

Another downside of the current cycle detector is its cost: it's one of the more expensive parts of compilation currently.

### Remote scoping

If adding the imports for a component would otherwise create a cycle, the compiler instead populates `directiveDefs` via a strategy known as "remote scoping".

`directiveDefs` within the actual component file is left empty. Instead, a side-effectful call is inserted into the file which contains the `NgModule` that declared the component. This looks like:

// module.ts

import {FooCmp} from './foo';
import {BarCmp} from './bar';

@NgModule({
  declarations: [FooCmp, BarCmp],
})
export class FooBarModule {}
ng.setComponentScope(BarCmp, [FooCmp, BarCmp]);

When this file is evaluated, `setComponentScope` will patch `BarCmp.ɵcmp.directiveDefs` and add the listed components. This strategy works because:

* The module file is guaranteed to already import all components it declares, so no new imports are necessary and thus no cycles created.
* The module file is guaranteed to be executed, because Angular DI guarantees that an instance of each `NgModule` present in the application will be created via DI.

This strategy was developed during the initial implementation of the Ivy compiler: [design doc](https://docs.google.com/document/d/1ip64jXBGc7SIadZ-xGtL99O5l3jPZTERGJ-rx6SMHvA/edit#heading=h.5npn8u2fnag2).

## Limitations

Although this solution works, it has some significant drawbacks.

### Tree-shaking

Side-effectful code defeats tree-shaking entirely. Thus in g3, code which should be removed by the optimizer is retained if it is referenced by one of these components that is remotely scoped in this way, or by a component _referenced_ in the template of a remotely scoped component.

This is made worse by the fact that the compiler currently emits the full module scope for remotely scoped components, including references to directives/pipes which are not actually used in its template. This was originally due to the compiler's architecture (at the time the scoping decision was made, the list of used directives/pipes was not available), and could be fixed today with some effort.

### `sideEffects: false`

After the implementation of this mitigation, as Ivy tree-shaking was studied and improved the impact of side-effectful code became more apparent. It was decided that Angular libraries would be assumed to be side-effect free, and published on NPM with `sideEffects: false` in their `package.json` files. This informs Webpack and any downstream optimizers that they're free to assume top-level function calls have no side effects, and can potentially be removed.

This causes Angular libraries which use the cycle mitigation to break when depended on by CLI apps, unless they explicitly specify `sideEffects: true`.

One workaround would be to move the mitigation code from being a top-level function call to a static property on the `NgModule` class:

class FooBarModule {
  static _ = (function() {
    ng.setComponentScope(BarCmp, [FooCmp, BarCmp]);
  })();
}

This would allow the side effects to at least survive optimization.

#### Side-effect free applications

The Angular tooling team intends to enable the `sideEffects: false` behavior for application builds in the near future. This would break the mitigation for cyclic references to components unless it is adjusted in some way.
> [name=Alan Agius] this is targeted for v10 (opt-in)

## Potential future directions

It is clear that the status quo is not ideal long-term. Some open questions are:

* should Angular permit cycles to be emitted in JS?
* if so, how should they be handled in g3 where such cycles are forbidden by tooling?
* should we have a flag to allow cycles, or make them errors?
* if so, how should we evaluate/manage the risk of breaking applications due to order-of-evaluation?
* if not, do we continue to use the existing mitigation? modify it in some way? replace it with a different one?