The circularity hydra

and how to defeat it

Valeriy Kuzmin co-authored by Tamas Hegedus

Moonfare, Berlin, 2022

The problem

// ClassA.ts
import { B } from "./ClassB";

export class A extends B {
}

export const UsefulStuff = "Useful";


// ClassB.ts
import { UsefulStuff } from './ClassA';

console.log(UsefulStuff);

export class B {

}

Modules?

ReferenceError: Cannot access 'UsefulStuff' before initialization

The cause

In order to prevent an infinite loop, an unfinished copy of the a.js exports object is returned to the b.js module. b.js then finishes loading, and its exports object is provided to the a.js module.

https://nodejs.org/api/modules.html#cycles

Why bother?

Circular dependencies in JS projects are endemic
They create unpredictable, cross-domain errors at runtime
They make code tightly coupled
Amount of circular dependencies is a good indicator of code quality

At moonfare

Cycle around src/common/entity/users/Investor.ts

     src/common/entity/users/Investor.ts
 new src/common/services/QuestionnaireService/SuitabilityStatuses.ts
     src/common/services/QuestionnaireService/QuestionnaireServiceInterface.ts
     src/common/entity/users/Investor.ts

Some recipes

1. Fully nominal dependency

// ClassA.ts
import { B } from "./ClassB";

export class A extends B {
}

export const UsefulStuff = "Useful";


// ClassB.ts
import { UsefulStuff } from './ClassA';

console.log(UsefulStuff);

export class B {

}

Demo: example-1

1. Solution - lift

Just lift the common dependency out

Always apply when you can, it's the easiest way out
Leads to better SRP and less coupling automatically
Automatable: in WebStorm press 'Move members' (typically F6)

How

Pros & Cons

2. Coupled implementation dependency

Demo: example-2

2. Solution - full decouple

Split the coupled implementation into 2

Sometimes it's hard and requires test coverage
May seem unnatural
Same pros as 'fully nominal lift'

Pros & Cons

2. Solution - apply service locator

Extract the interface
Depend on inteface + get the impl via locator
In locator, init normally

Doesn't really fix the circularity, hides the problem
Service locator ideally shouldn't be used
May be a lot of trouble for tests
Easiest to achieve, prepares code for DI due to interface-splitting

Pros & Cons

2. Solution - use event calling

Refactor the call into an event publishing
Bind the dependency in an event handler on some top level, like with locator

Not always applicable if you need a result or to wait for completion
Again, only hides the problem
Hard to refactor & bad for readability
But still leads to less coupling

Pros & Cons

3. God class (e.g. 'router' switch)

Demo: example-3-4

3. God class (e.g. 'router' switch)

Demo: example-3-4

Note: it's a subproblem of 2, and sometimes not a root cause

3. Solution: apply events or even commands

Explicit routing is an improper implementation of events, do it right!

Pros:

Same as event calling

Cons:

Same as event calling
May need to use commands (harder to write) since here waiting for result may be necessary

4. Bad barrel file

// f/a.ts
export const a = "a";
// f/b.ts
export const b = "b";
// f/index.ts
import {a} from "./a";
import {b} from "./b";
export {a, b};

// or
export * from "./a";
export * from "./b";

“… Because the problem with object-oriented languages is they’ve got all this implicit environment that they carry around with them. You wanted a banana but what you got was a gorilla holding the banana and the entire jungle. “ — Joe Armstrong, creator of Erlang progamming language

A fitting quote

Why people use barrels?

Fake export control
Mental grouping when too lazy to make a folder
Desire to not write Button/Button.tsx

Why barrels are bad?

Aggravating pattern for circularity, almost guarantees you cycles
Extra effort that duplicates a directory for little win
Plain doesn't work as export control without a linter
Without proper setup, horrible for treeshaking and bundle/docker image size
Requires EXTRA linting to make right

Solution: Instead of barrels, use...

WS: auto-imports out of the box
VSCode: add .jsconfig file
VIM: https://github.com/Quramy/tsuquyomi

Come on, it's 2022, and you're not writing in a notepad

Solution: Instead of barrels, use auto-imports

Pros:

You write code faster
No useless code leading only to problems

Cons:

Used without understanding, they will give you even more cycles

5. ORM entity dependency

'True' cycles
A bit controversial

Demo: example-5

5. Solution - cut the link in one direction

Choose which is the 'main' out of 2 models
In the 'subordinate' model, replace the TS type binding with string name binding
Specify 'unknown' instead of actual type if necessary

May be inconvenient to use
Requires unique model names
But completely eliminates the bad joins possibility
Nicely fits into DDD
Less coupling as usual

Pros & Cons

5. Alternative solution - allow for models only

Configure depcruiser with tsPreCompilationDeps=false for models folder
Force-ignore cycles produced by models, if they only contain model files

More complicated linting config
May not be foolproof against cycles
Does not protect again bad joins
But, easier to use code and only needs to be configured once

Pros & Cons

6. Hacky workarounds - delayed require

import x from "bad";

x.doStuff();

// convert into

setTimeout(() => {
  const x = require("bad");
  x.doStuff();
}, 0)

7. Hacky workarounds - type ignore

tsPreCompileDeps = false | "specify"

7. Hacky workarounds - type ignore

Demo: example-7

The end!

Questions?