In a TypeScript codebase you can either derive your internal types from external payload types with key-remapping mapped types, or declare them by hand. How do you decide, and what does the derived approach cost a team?

## What derivation actually promises Writing `type Domain = { [K in keyof Wire as Names[K]]: Wire[K] }` makes a claim with real force: this type is not an independent design, it is a *function* of `Wire`. Recompute the input and the output changes. That is enormously valuable where the two shapes are genuinely required to agree, because it converts an entire class of silent drift into a compile error. Hand-written twins do the opposite: they agree on the day they are written and diverge quietly forever after. So the first question is never "is this clever" but "is this shape genuinely a function of that one, permanently?" If yes, derive. If the answer is "today it happens to match", declare it by hand and let a mapper's signature check the correspondence. ## The costs, in the order a team feels them **Names that do not exist in the source.** This is the largest and most underrated. If `userId` is produced by an `as` clause, then searching the repository for `userId` finds usages but not the declaration, and an IDE rename cannot rewrite what was never written. New engineers grep, find nothing, and conclude the field is untyped. On a codebase with a handful of derived aliases this is a shrug; across a whole domain layer it is a permanent tax on navigation. **Error messages inherit the formula.** A mismatch is reported against the computed type, and the further the derivation chain goes — remap, then filter, then intersect — the further the message drifts from anything a reader typed. The team's ability to self-serve on type errors degrades roughly with the depth of the chain. **Coupling of the field *set*, not just the names.** A homomorphic derivation takes everything. When the upstream team adds three fields for their own reasons, your internal type grows three fields you never reviewed. That is fine for a DTO whose whole job is to mirror the wire, and corrosive for a domain model, which should represent your business, not their schema version. **Direction matters.** Deriving the wire type *from* your domain model is worse than the reverse: it asserts control over an interface you do not own, and the compiler will cheerfully agree with you right up until the API changes. Derive downstream, never upstream. ## Where declaration wins Hand-declared types are searchable, hoverable, documentable with real doc comments per field, and reviewable in a diff. They are also the only honest way to express a model that is *supposed* to differ from the payload: fields you deliberately drop, names chosen for your domain rather than theirs, invariants encoded as narrower types than the wire admits. If a reviewer would want to discuss the addition of a field, that field should be typed by hand, because derivation removes the review. ## The arrangement I would defend Three layers, each with the right technique. The **wire type** is declared explicitly and matched to the API contract, ideally generated from the provider's schema if one exists. The **boundary shape** may be derived — filtered, remapped, narrowed — because its whole purpose is to be a function of the wire. The **domain model** is hand-declared. A mapper function sits between the last two with both types in its signature; that signature is what makes drift a build failure without welding the model to the payload. You get the error-on-change property that made derivation attractive, and you keep the model reviewable. ## How to keep derived types tolerable If derivation is right for a case, contain it. Keep the remapping in one small module rather than inline at usage sites. Give the intermediate results named aliases so hovers and error messages have something readable to print. Keep the chain shallow — each additional transformation multiplies the distance between the message and the source. And write a couple of type-level assertions that pin the expected result, so a reader can see the resolved shape spelled out somewhere in the repository even though the compiler computed it. ## The signal to watch for The honest test is a maintenance one: when the upstream shape changes, do you *want* your type to change automatically? For a translation layer, yes — that is the entire point. For the vocabulary your product is written in, no; you want a person to decide. Answer that question first and the derived-versus-declared choice stops being a matter of taste.