Back in Designing a Typed API Client, routes with no input forced callers to write call('GET /me', {}). The fix needs a type that makes a decision: “if this route’s input has no required fields, make the argument optional; otherwise, require it”. Mapped types loop. Conditional types decide.
type IsArray<T> = T extends readonly unknown[] ? true : false;\n\ntype A = IsArray<string[]>; // true\ntype B = IsArray<Order>; // falseT extends U ? X : Y reads like a ternary: if T is assignable to U, the result is X, otherwise Y. The extends here is the same assignability check as everywhere else in TypeScript, “is T a subset of U?”. When T is a generic parameter that is not known yet, TypeScript defers the conditional and keeps it as is until a concrete type arrives.
Here is the API client fix. {} extends Input is true exactly when every property of Input is optional (an empty object would satisfy it):
type CallArgs<R extends keyof Routes> = {} extends Routes[R]['input']\n ? [input?: Routes[R]['input']]\n : [input: Routes[R]['input']];\n\ndeclare function call<R extends keyof Routes>(route: R, ...args: CallArgs<R>): Promise<Routes[R]['output']>;\n\ncall('GET /me'); // ok: input is {}\ncall('GET /orders'); // ok: every filter is optional\ncall('GET /orders/:id'); // Error: Expected 2 arguments, but got 1.\ncall('GET /orders/:id', { id: 1 }); // okThe conditional produces a tuple type, and the rest parameter ...args spreads it into the parameter list. Labeled tuple elements (input?:) keep the parameter name in tooltips. Not one call site changed.
Conditional types have one behaviour that surprises everyone. When the checked type is a naked type parameter and you pass it a union, the conditional runs once per member and the results are joined:
\ntype ToArray<T> = T extends unknown ? T[] : never;\n\ntype X = ToArray<string | number>; // string[] | number[], not (string | number)[]This is called distribution, and it is the engine behind several utility types. Here are Exclude and Extract, exactly as the lib defines them:
type MyExclude<T, U> = T extends U ? never : T;\ntype MyExtract<T, U> = T extends U ? T : never;\n\ntype Active = MyExclude<OrderStatus, 'cancelled' | 'returned'>; // 'processing' | 'shipped' | 'delivered'\ntype Shipped = MyExtract<Order, { status: 'shipped' }>; // the ShippedOrder variantEach member goes through the conditional on its own. Members mapped to never vanish, because never is the empty union. MyExtract<Order, { status: 'shipped' }> is the cleanest way to name one variant of a discriminated union.
To turn distribution off, wrap both sides in a one-element tuple. [T] is not a naked type parameter, so the union is checked as a whole:
type ToArrayWhole<T> = [T] extends [unknown] ? T[] : never;\ntype Y = ToArrayWhole<string | number>; // (string | number)[]Inside the extends clause, infer X declares a type variable that captures whatever sits in that position, if the pattern matches. This is essentially how the lib defines ReturnType (the lib version also constrains F to a function type and falls back to any):
type MyReturnType<F> = F extends (...args: any[]) => infer R ? R : never;\n\ntype Loaded = MyReturnType<typeof loadOrder>; // Promise<Order>The same trick pulls types out of anything with structure:
\ntype ElementOf<T> = T extends readonly (infer E)[] ? E : never;\ntype UnwrapPromise<T> = T extends Promise<infer V> ? V : T;\ntype FirstArg<F> = F extends (first: infer A, ...rest: any[]) => any ? A : never;infer can also carry a constraint, as in infer S extends string, which only matches when the captured type is a string and gives you S already narrowed. You will need that in the next lesson, when you capture pieces of string literal types.
Combine a mapped type, a conditional and an indexed access, and you can select keys by what their values are:
\ntype KeysOfType<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];\n\ntype Line = { sku: string; quantity: number; unitPriceCents: number };\ntype NumericField = KeysOfType<Line, number>; // 'quantity' | 'unitPriceCents'The mapped type turns each property into its own key name or never, and [keyof T] collects the values into a union, where the nevers disappear. It reads backwards the first time; write it once, name it well, and reuse it. A sort function typed sortBy(lines, key: KeysOfType<Line, number>) now refuses to sort by sku.
It is tempting to give a function a conditional return type, such as function format<T extends number | number[]>(x: T): T extends number ? string : string[]. Callers get precise types, but the implementation does not: inside the function, T is still unknown, the conditional stays deferred, and TypeScript cannot check that return x.toFixed(2) matches it. You end up writing as any or as T extends number ? string : string[] on every return, which means the most delicate code in the function is the code nobody checks.
That is why the previous section preferred overloads or separate functions for this job. Conditional types shine in derived types (CallArgs, Extract, KeysOfType) where nothing has to be implemented against them, and they are weakest as the declared return type of hand-written logic.
In the exercise you will re-implement Exclude, Extract and ReturnType and use them on Cartwheel’s order types. The next lesson applies conditionals and infer to strings.
T extends U ? X : Y picks X when T is assignable to U and Y otherwise; with a generic T, the choice waits until T is known.","A conditional on a naked type parameter distributes over unions, running once per member and joining the results.","Wrap both sides in brackets, [T] extends [U], to test the union as a whole instead of distributing.","infer declares a type variable inside the extends clause and captures whatever matches it, which is how ReturnType and Awaited work.","Mapping each key to itself or never and then indexing with [keyof T] filters keys by the type of their value."],"further":[{"title":"Conditional Types","url":"https://www.typescriptlang.org/docs/handbook/2/conditional-types.html"},{"title":"Utility Types (Exclude, Extract, ReturnType)","url":"https://www.typescriptlang.org/docs/handbook/utility-types.html"}],"quiz":[{"q":"type ToArray<T> = T extends unknown ? T[] : never. What is ToArray<string | number>?
(string | number)[]","why":"That is the non-distributive result, which you get with [T] extends [unknown]."},{"text":"never","why":"Both members extend unknown, so neither takes the never branch."},{"text":"unknown[]","why":"The true branch uses T, which is each member in turn, not the constraint unknown."},{"text":"string[] | number[]","why":"Correct. T is a naked type parameter, so the conditional runs once for string and once for number, and the results are joined."}],"answer":3},{"q":"Which type gives you the shipped variant of the Order union?
Extract<Order, { status: 'shipped' }>","why":"Correct. Extract keeps the union members assignable to { status: 'shipped' }, which is exactly the shipped variant."},{"text":"Exclude<Order, { status: 'shipped' }>","why":"Exclude does the opposite: it removes the shipped variant and keeps the rest."},{"text":"Order['shipped']","why":"Indexed access looks up a property named shipped, which Order does not have."},{"text":"Order extends { status: 'shipped' } ? Order : never","why":"Order is a concrete type here, not a type parameter, so nothing distributes. The whole union is not assignable to the shipped shape, so you get never."}],"answer":0},{"q":"What is R?
type MyReturnType<F> = F extends (...args: any[]) => infer R ? R : never;\ntype R = MyReturnType<(id: number) => Promise<Order>>;Order","why":"infer R captures the return type as written. Unwrapping the promise needs a second step, such as Awaited."},{"text":"Promise<Order>","why":"Correct. The function type matches the pattern, and R captures its return type exactly."},{"text":"never","why":"You get never only when F is not a function type. Here it matches."}],"answer":1},{"q":"type IsString<T> = T extends string ? true : false. What is IsString<never>?
true, because never is assignable to everything","why":"That is true for a non-distributive check like [never] extends [string]. A distributive conditional never gets that far."},{"text":"false, because never is not a string","why":"The conditional is not evaluated at all; there are no union members to run it on."},{"text":"never, because distributing over an empty union produces an empty union","why":"Correct. never is the empty union, so a distributive conditional maps zero members and returns never."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order =\n | { id: number; status: 'processing' }\n | { id: number; status: 'shipped'; trackingNumber: string }\n | { id: number; status: 'delivered'; trackingNumber: string; deliveredAt: string }\n | { id: number; status: 'cancelled'; cancelReason: string }\n | { id: number; status: 'returned'; trackingNumber: string; deliveredAt: string; refundCents: number };\ntype Line = { sku: string; quantity: number; unitPriceCents: number; giftWrapped: boolean };\ndeclare function loadOrder(id: number): PromiseImplement these with conditional types (do not use the built-in Exclude, Extract, ReturnType or Awaited):
MyExclude<T, U>: the members of T not assignable to U.MyExtract<T, U>: the members of T assignable to U.MyReturnType<F>: the return type of a function type.UnwrapPromise<T>: the value inside a Promise, or T itself if it is not a promise.OrderWithStatus<S>: the Order variant(s) whose status is S.KeysOfType<T, V>: the keys of T whose values are assignable to V.MyExclude and MyExtract are one-line distributive conditionals: one returns never in the true branch, the other in the false branch.","Use infer to capture a part of a type: F extends (...args: any[]) => infer R ? R : never.","OrderWithStatus is MyExtract<Order, { status: S }>. For KeysOfType, map each key to itself or never, then index the result with [keyof T]."],"explanation":"MyExclude and MyExtract rely on distribution: T is a naked type parameter, so each union member is tested separately and the never results vanish. The same distribution makes OrderWithStatus<'delivered' | 'returned'> give both variants, which is why ['deliveredAt'] works on it. infer captures the return type and the promise’s value. KeysOfType builds an object whose values are key names or never, then reads all of its values at once with [keyof T].