[alpha_squared]

Until it's the root cause of code not working as expected, by another developer far removed from initial implementation. Non-obvious code is harder to maintain. Code is written for people, not machines; that means the harder it is for people to maintain, the less useful it actually is.

[jorisd]

Valid point. On the other hand, these kinds of advanced types can prevent lots of bugs and maintenance work, and may therefore be worth the day of debugging when it breaks after two or three years of usage.

I've used types like this in a pretty advanced TypeScript UI project consuming lots of services to enforce compile time errors. We were using generated TS clients for all of the APIs we consumed, and the compiler would automatically throw readable errors wherever we were missing form fields or types became incompatible. I committed the advanced type once, documented its usage, and I don't think anyone has had to deal with it since, whilst the types have steadily prevented errors.

And even then: it's just type definitions. If it really becomes a maintenance burden or someone has no clue what it does, you can simply replace the type with "any" or something similar and all of your problems are gone and typescript won't complain anymore (at the expense of less type error checking).

EDIT: improved wording

[dllthomas]

Complicated types (like any complicated code) need their own tests demonstrating that they do what the author thinks (and fails to think about, as it's changed).