Generic API Patterns & Pitfalls

## What the caller is really doing A generic function is checked by *inference*: the compiler looks at the arguments, matches them against the parameter types, and solves for each type parameter. In `fetchJson<T>(url: string): Promise<T>` the only parameter is a `string`, which mentions T nowhere. There is no inference site, so the type parameter has no relationship to anything in the call. Writing `fetchJson<User>('/api/me')` does not *check* that the result is a `User`; it *declares* it. The compiler has nothing to compare that claim against, so it accepts it. The honest desugaring of the pattern is: ```ts // what the signature promises const u: User = await fetchJson<User>("/api/me"); // what it actually does const u = (await someRawJson("/api/me")) as User; ``` Both are assertions. The difference is optics: `as User` reads as a claim a reviewer will challenge, while `fetchJson<User>(...)` reads as "typed API client" and sails through. ## Why the checker cannot object Types are erased. There is no `T` at runtime, so `fetchJson` cannot inspect the parsed value even if it wanted to; the body ends at `JSON.parse`, which is declared in the standard library as returning `any`. Everything downstream is the compiler taking the caller at their word. This is one of TypeScript's deliberate unsoundness escape hatches — the type system models data it never sees, and at an I/O boundary the data is genuinely unknown until something checks it. The consequences are the ones you should be able to name in an interview: - A renamed or removed field on the server produces **no** compile error anywhere; you find out when a property is `undefined` three layers away. - Optional versus required is not enforced: declaring `name: string` when the API sometimes omits it means the compiler will refuse to let you handle the `undefined` case, because as far as it knows there isn't one. - Refactors are validated against the lie, not the data, so the type system's main benefit at that boundary is gone precisely where you most wanted it. ## What T infers when you omit the type argument If a caller writes `await fetchJson('/api/me')` with no explicit type argument, T is an unconstrained type parameter with no inference candidates, and TypeScript resolves it to `unknown`. That is a small mercy: the un-annotated call is the *safe* one, because `unknown` forces narrowing before use. It also tells you what the signature should have said in the first place. ## Making the type parameter real The rule from this topic — a type parameter must appear at least twice — points straight at the fix: give T a second appearance in a position derived from code that runs. ```ts declare function readJson(url: string): Promise<unknown>; async function getJson<T>(url: string, parse: (raw: unknown) => T): Promise<T> { return parse(await readJson(url)); } ``` Now T is *inferred* from the `parse` argument rather than asserted by the caller. If `parse` is a hand-written type predicate or a schema library's parser, the returned type and the runtime check come from the same source, so they cannot drift apart independently. A schema library gives you the same shape: the schema is the value, the static type is derived from it, and the parse call is the only place a type claim is made. The minimal alternative, when you do not want to force validation into the helper, is: ```ts declare function fetchJson(url: string): Promise<unknown>; ``` Callers must then narrow — with a type predicate, an assertion function, or a parser — before touching a property. The unsafe call sites do not disappear, but they become visible: each one now needs a deliberate step you can review. ## When the pattern is defensible It is not always wrong. A generated client where the type argument is filled in by codegen from an OpenAPI or GraphQL schema has an external guarantee that hand-written annotations lack — the type and the server contract come from one source, and drift is caught by regenerating. Likewise an internal wrapper is fine if validation demonstrably happens elsewhere on every path. The failure mode is the *hand-written* type argument, chosen by whoever wrote the call site, checked by nobody. ## Reviewing for it The scan is quick: find every exported function whose type parameter appears only in the return type. Common offenders beyond HTTP clients are database query helpers (`query<Row>(sql)`), cache and key-value reads (`get<T>(key)`), configuration lookups, message-queue payload readers, and anything wrapping `JSON.parse`. In each case ask what evidence the function has for the type it is returning. If the answer is "whatever the caller typed", the signature should say `unknown` and let the caller do the narrowing where it can be seen.