In TypeScript, when should a shared type be declared explicitly and enforced onto the implementation, rather than derived from it with `ReturnType<typeof ...>`?

## Two directions of authority Every shared type in a codebase has an implicit direction. Either the implementation defines the type — you derive with `ReturnType<typeof fn>` or `Awaited<...>` and consumers follow — or the type defines the implementation, which is annotated or `satisfies`-checked against it. Both are defensible. Choosing per-boundary rather than picking one style for the whole repo is the judgment being tested. ## What derivation buys The win is real and it is why the idiom spread. There is no duplicate to keep in step, refactors propagate for free, and a whole category of drift bug — the interface that quietly stopped matching the object literal — cannot occur. For a store's state, the reducers *are* the definition; writing a parallel `RootState` interface by hand is pure liability: ```ts type RootState = ReturnType<typeof store.getState>; type AppDispatch = typeof store.dispatch; ``` ## What derivation costs **Contract changes stop being visible.** If `getUser` gains a field, every derived consumer silently accepts the new shape. That is convenient inside a module and dangerous across a package boundary, where the shape is a promise you made to someone else. A declared type turns the same edit into one error at the function — the place a reviewer can actually judge it. **Error messages get worse.** A named `interface User` appears in diagnostics as `User`. A derived alias resolves to its structure, so a mismatch prints a wall of properties. On a deep chain — `Awaited<ReturnType<typeof handler>>["data"][number]` — the reader can no longer tell what was supposed to be true. **Inference leaks internals.** Whatever the implementation happens to return becomes the contract, including fields that were incidental, and including types imported from private modules. A declared type is a deliberate projection; a derived one exports whatever fell out. **Emitted declarations depend on inference.** When a package ships `.d.ts` files, derived public types make the emitted output a function of how much the compiler could infer. Explicit annotations at exported boundaries keep that output stable and cheap to produce. ## The middle position The choice is not binary, and the strongest answer says so. You can keep the type authoritative *and* keep the implementation honest: ```ts export interface User { id: string; name: string; } // The type is the contract; the function is checked against it. export async function fetchUser(id: string): Promise<User> { const raw = await getRow(id); return { id: raw.id, name: raw.name }; } ``` An explicit return annotation costs one line and moves every failure to the definition. For object constants, `satisfies` does the same job while preserving the narrower inferred type for local use. Either way the contract is written down and the implementation must live up to it — the opposite of derivation, achieved without duplicating a shape by hand. ## A workable policy - **Derive down.** Inside a module or feature slice, where implementation and consumers ship together and no one outside can observe the shape, derive freely: store state, thunk results, factory outputs, private fetchers. - **Declare across.** At any boundary someone else depends on — a published package's exports, an API response, a persisted record, a contract between teams — declare the type and enforce it with an annotation or `satisfies`. - **Never derive from something you do not control.** `ReturnType<typeof someLibraryFn>` couples you to a shape the library never promised, and it can change in a patch release without notice. - **Cap the depth.** A chain of three or more utilities over a `typeof` query is usually a sign that a named type should have existed two steps ago. Name the intermediate. ## The cost that is *not* real Worth saying explicitly, because candidates reach for it: neither approach costs anything at runtime. Types are erased, and a derived type does not call, inspect, or retain the function it was derived from. The entire tradeoff is about change management, diagnostics, build-time behaviour and human readability — never about performance of the shipped program.