In TypeScript, `declare function box<T>(x: T): { value: T }` called as `box("red")` produces `{ value: string }` rather than `{ value: "red" }`. Why does the literal widen, and how would you change the signature to keep it?

## Two kinds of literal type When you write the expression `"red"`, TypeScript does not immediately give it the type `string`. It gives it the literal type `"red"`, but marks that type as **fresh** — the compiler internally calls it a *widening literal type*. Freshness records the fact "this literal came straight out of an expression, and nobody has yet said it must stay narrow". A fresh literal collapses to its base primitive (`"red"` to `string`, `1` to `number`, `true` to `boolean`) as soon as it flows into a position that has no reason to keep it precise: ```ts let a = "red"; // string — a mutable binding has no reason to stay narrow const b = "red"; // "red" — kept, but still a *widening* literal type const c: "red" = "red"; // "red" — the annotation makes it non-fresh ``` This is not a special generics rule; generics simply inherit it. ## What happens during a generic call Checking a generic call has two phases. First the compiler collects **inference candidates** for each type parameter by matching argument types against parameter types. Then it picks a type argument from the candidates. A candidate that came from a fresh literal is widened at that second step unless something in the signature says otherwise. With a bare `<T>`, nothing does: ```ts declare function box<T>(x: T): { value: T }; const r = box("red"); // { value: string } ``` A detail that surprises people: declaring the argument with `const` first does not help. ```ts const color = "red"; // type "red", but a widening literal type const r2 = box(color); // still { value: string } ``` The variable's own type is still the *widening* literal type, so it widens on the way into `T` exactly as the inline literal did. Only a non-fresh literal type — one produced by an annotation, a const assertion, or a constrained inference — survives. ## Fix one: constrain the type parameter If the type parameter is constrained to a primitive type, TypeScript keeps the literal candidate instead of widening it. This is the cheapest and most portable fix, and it works on any modern compiler: ```ts declare function box<T extends string>(x: T): { value: T }; const r3 = box("red"); // { value: "red" } declare function pick<T extends string>(x: T[]): T; const p = pick(["a", "b"]); // "a" | "b" ``` Note *where* the constraint goes. Constraining the parameter to an array type instead of constraining the element type puts you right back where you started, because the inferred `T` is now an array type built from already-widened elements: ```ts declare function pickWrong<T extends string[]>(x: T): T[number]; const q = pickWrong(["a", "b"]); // string ``` The rule of thumb: the type parameter that must stay literal is the one that has to be constrained to the *primitive*. ## Fix two: a const type parameter Since TypeScript 5.0 you can write `<const T>`, which infers the argument as if the caller had written a const assertion. It handles cases the constraint trick cannot — nested object and array structure — and it also adds `readonly`: ```ts declare function conf<const T>(o: T): T; const c = conf({ mode: "dark", n: 1 }); // { readonly mode: "dark"; readonly n: 1 } ``` It carries the same call-site limitation as above: if the caller passes a variable rather than an inline expression, the modifier changes nothing. ## Fix three: push the burden to the caller The caller can always annotate the parameter type or apply a const assertion at the call site. That keeps the signature simple, but every call site has to remember, and forgetting produces no error — just a silently useless type. For a library API that is usually the wrong trade: the signature is written once, the call sites are written thousands of times. ## Why anyone cares This is what separates an API whose literals round-trip from one whose types are noise. Event emitters, route tables, form-field maps, state-machine definitions and `keyof`-driven helpers all depend on the caller's literal surviving inference: if `on("click", h)` infers `string`, the handler parameter cannot be looked up and autocomplete offers nothing. Finally, remember what layer this lives on. Widening, constraints and const type parameters exist only during checking. The emitted JavaScript is identical either way — no literal type is present at runtime, and nothing is frozen or validated.