Reference · library-grade patterns

Reading library-grade types — a decoder

Five real-world shapes you'll meet in @types/…. For each: what to look for, and how to read it without drowning. Find the inferred input; treat the rest as defaults.

1 · Nested library generics (useQuery)

Find the one parameter inferred from your call; the rest default off it. Trace that parameter to its one meaningful use, not every layer.

declare function useQuery<
  TQueryFnData = unknown,   // ← inferred from queryFn's return type
  TError = DefaultError,
  TData = TQueryFnData,       // ← defaults off TQueryFnData
  TQueryKey extends QueryKey = QueryKey
>(options: UndefinedInitialDataOptions<...>): UseQueryResult<TData, TError>;

// the field that PRODUCES the inference, deep in the layers:
type QueryFunction<T> = (ctx: ...) => T | Promise<T>;  // T = return type

Layers (QueryOptions → … → UndefinedInitialDataOptions) just forward the same params and add fields. TData ≠ TQueryFnData only when you pass select.

2 · Builder / phantom accumulation

A method returning Class<TOld & New> instead of plain this is accumulating. Read the return type; the body is just return this.

class TypeSafeStringMap<TMap extends Record<string,string> = {}> {
  get(key: keyof TMap): string { ... }       // only keys set so far
  set<K extends string>(key: K, value: string)
    : TypeSafeStringMap<TMap & Record<K, string>> { return this; }
}
// new TypeSafeStringMap().set("a","1").set("b","2")
//   → TMap = { a: string } & { b: string }; get("c") errors

Phantom = compile-time only. TMap never appears in emitted JS.

3 · Branded / nominal types

Base type & an object with a never-assigned marker (__brand, a unique symbol) = a brand. It fakes nominal typing in a structural system.

type UserId = string & { readonly __brand: 'UserId' };
function toUserId(s: string): UserId { /* validate */ return s as UserId; }

const raw: string = "x";
getUser(raw);            // ❌ missing __brand → not a UserId
getUser(toUserId(raw));  // ✅ minted through the one sanctioned cast

The brand is a promise the value passed toUserId, not a runtime check.

4 · The React type cheat

type	read as	width
ReactNode	anything renderable	widest — strings, arrays, null, elements
ReactElement	one element object	narrow — a single element
JSX.Element	ReactElement, loose generics	narrow — what JSX evaluates to

children → ReactNode (wide slot). Component return type → ReactElement / JSX.Element (narrow). Grab props without an export:

type Props = ComponentProps<typeof ComponentA>;  // typeof = value type → extract props

5 · Zustand generic form

fn<T>()(arg) = curry to fix T first, then infer from arg. Needed when T is invariant (in both input and output positions) so single-call inference yields unknown.

const useStore = create<BearState>()((set) => ({  // () pins T; then creator is checked
  bears: 0,
  increase: (by) => set((s) => ({ bears: s.bears + by })),
}));
// StateCreator<T> = (set, get) => T  — with T fixed, set/get/return all resolve

The one decoder for all five

World? type vs value (Module 0).
Inputs? which type parameters, inferred from where (Module 2).
Operators? extends ? :, infer, mapped, template-literal, intersection (Module 3).
Output? read it off. Library types just nest these.