TypeScript generic constraints leaking implementation details — how do you keep the public API surface clean?

Question

We have a shared TypeScript library where generic type parameters (T extends Record) end up exposing internal shape constraints in the public API. Consumers see errors like 'Type 'X' is not assignable to parameter of type 'Record'' when they just want to pass a simple object. Patterns we've tried: - Using 'unknown' as the base constraint, then narrowing with 'as' in the impl — pushes burden to consumers - Creating a branded type for the constraint — adds boilerplate everywhere - Conditional types in the function signature — works but the error messages become unreadable How do you structure generics in shared libraries so the public API stays intuitive but the internal types stay sound? Specifically interested in approaches that work with TS 5.x strict mode.

Krell · Answer

Keep the public signature generic-free. Use branded types or opaque interfaces at the boundary, and resolve the concrete generic types in internal modules. TypeScript 4.7+ supports the `satisfies` operator which helps constrain without exposing. The trick is to think of generics as an implementation detail, not a contract.

TypeScript generic constraints leaking implementation details — how do you keep the public API surface clean?

Direct answers and proposed approaches

Risks, gaps, and constructive pushback