You are designing a public TypeScript type whose declaration is shaped like `Query<TData, TError, TKey>`. How do you decide the order of the type parameters and which of them get defaults, and what does that decision commit you to later?

## Why order is a hard commitment Type-argument lists are positional and admit no placeholder. There is no way to write "use the default for the first, but let me set the third" — a caller who needs the last parameter must write out everything before it. That single fact makes parameter order a real part of your public contract, not a cosmetic choice. The practical rule is to sort by *probability of being specified*, descending. The parameter almost every caller supplies goes first. The parameter a tenth of callers touch goes next. The one that exists for two power users goes last. Any other ordering taxes the common case: users end up writing out types they did not care about just to reach the one they did, and those spelled-out types then become an accidental part of their code that must be maintained. ## The defaults rule pushes in the same direction A type parameter with a default is optional, and optional parameters must be trailing — once you default one, everything after it must be defaulted too. So the parameters you intend to be omitted are forced to the tail regardless. Happily this agrees with the ordering rule: rarely specified means defaulted means last. When the two rules seem to conflict — a frequently specified parameter that also wants a default — the frequency argument wins, and you give the earlier parameter a default as well so the shape stays legal. ## Choosing each default The default type is the contract for every caller who says nothing, which in practice is most of them. - `unknown` is the conservative choice. Callers who omit the argument still have to narrow before using the value, so an omission produces friction rather than silence. Good for data whose shape genuinely varies. - A concrete type — `Error` for a failure channel, `string` for an identifier — reads well and makes the short form pleasant. It is a claim about the real world, so make it when the claim is nearly always true, and accept that a caller with a different type must now supply the argument. - `any` is the choice to argue against. It makes the short form compile everywhere and turns off checking for the values flowing through that position, with no diagnostic and no obvious symptom. Most "TypeScript didn't catch it" stories in a generic-heavy codebase start with a defaulted `any`. - Repeating the constraint as the default — the `<T extends X = X>` shape — is the honest neutral option when the parameter exists so that callers can narrow. It says: supply something more specific if you have it, otherwise you get the widest thing allowed. ```ts interface Query<TData, TError = Error> { data: TData; error: TError | null; } type UserQuery = Query<{ id: string }>; // TError = Error type StrictQuery = Query<{ id: string }, string>; // both supplied ``` ## What the decision commits you to Evolution is where these choices are paid for. - **Appending a new parameter with a default is source-compatible.** Every existing reference that supplied fewer arguments keeps compiling, and the new parameter is opt-in. This is the one safe move, and it is the reason to leave room at the tail. - **Appending without a default breaks everything.** All existing references become arity errors at once. - **Inserting in the middle is worse than breaking — it can silently change meaning.** A reference that used to bind its argument to the first parameter now binds it to the newcomer, and if the types happen to be compatible nothing complains. - **Removing a default is breaking**; adding one to an existing parameter is not, since it only widens what is accepted. - **Reordering is breaking for every call site simultaneously**, with the same silent-rebinding hazard as insertion. So the order you ship is close to permanent, while the tail is your only growth area. ## Naming, because the call site is positional Single letters are fine at one or two parameters. Beyond that the reader of a reference sees only positions and has to count, so descriptive names with a `T` prefix — `TData`, `TError`, `TKey` — pay for themselves in the declaration and in hover tooltips. This is convention rather than a compiler rule, but it is close to universal in libraries with wide generic surfaces. ## The best answer is usually fewer parameters A three-parameter generic is a smell worth interrogating before you ship it. Ask which parameters could be inferred from an argument the caller already passes, which could be derived from another parameter and defaulted to that derivation, and which exist only because one caller once wanted them. Every parameter you remove removes an ordering decision you would otherwise be stuck with, and inference costs the caller nothing at the point of use. And none of it exists at runtime: the whole list is erased at compile time, so this is purely an ergonomics-and-evolution decision about the source people write.