Narrow Unions and Nullable Values

A union lists permitted alternatives for one value. The value can be one alternative at a time; it does not need to be every listed type simultaneously.

In a product search, an identifier might come from a numeric database key or a text-based catalog key. ProductId communicates both permitted forms. A literal union is narrower: ViewMode permits only the exact strings listed.

These aliases reject values outside their contracts, such as true for ProductId or "table" for ViewMode.

These aliases describe the permitted values for the product-search interface.

TypeScript must protect every remaining possibility in a union. That means an operation is allowed only when it works for all alternatives currently permitted.

For example, toUpperCase() is a string operation. It cannot be called directly on a ProductId, because a ProductId might currently be a number. Conversely, number-specific arithmetic cannot assume the identifier is numeric.

A preceding check will later let TypeScript narrow the possibilities. For now, the key rule is: do not use an operation that only one union member supports while the other member is still possible.

This function has a type error because the parameter may be a number.

Complete the two aliases so the shown assignments are accepted by TypeScript.

A runtime check also gives TypeScript information. Before a guard, ProductId can be either string or number, so an operation must work for both. Inside a branch guarded by typeof id === "string", only the string alternative remains reachable. The other branch contains the number alternative.

This refinement of a union is called narrowing. TypeScript follows the control flow of your conditions rather than changing the value itself.

Equality can narrow a union of literal values in the same way. When mode is checked against one permitted literal, that branch has exactly that literal. Once the grid branch returns, the final return can only be reached when the remaining literal is present.

A strict equality check selects one literal alternative.

An early return makes the remaining type especially clear. If the string path returns immediately, execution can continue only when id is a number. The final line can therefore call a number-specific method safely.

This is control-flow analysis: TypeScript tracks which alternatives are still reachable at each point in the function.

The first return removes the string alternative from the code below it.

A value can be missing in two different ways under strict null checking:

• null is an explicit value. In this product search, it means there is deliberately no selected product.
• undefined occurs when an optional property was omitted.

Both are nullish values: specifically, null or undefined. Before using a value that might be nullish, narrow away its missing alternatives.

The optional-property marker affects the type you get when you read the property. It does not mean that every product object contains that property.

Use the existing product contracts and fixtures below. Hover a variable in your editor to inspect its inferred union type.

TypeScript infers a union for each optional-property read.

Guard each missing alternative explicitly. After a branch returns, control flow knows that alternative cannot reach the code below it.

Do not use typeof subtitle === "object" to establish that a subtitle is available: typeof null is also "object", and undefined is a separate possibility. Once explicit null and undefined guards have returned, the remaining type is string.

Each early return removes one missing alternative from the remaining path.

selectedProduct may be a Product or null. Optional chaining, written as ?., checks its receiver before continuing a property access.

• If selectedProduct is null or undefined, the access stops and produces undefined.
• If it is a product, TypeScript reads subtitle normally. That property can still be a string, null, or undefined.

Optional chaining handles an absent receiver; it does not make fields from a different object type available.

The result can still contain the property’s own missing alternatives.

An optional-chain result may need a fallback. Use nullish coalescing, ??, when the fallback should apply only to null or undefined.

This is different from logical OR, ||. OR treats every falsy value as a reason to use the fallback, including values that may be intentional in a product interface.

Here, the main fixture keeps its intentional empty subtitle, zero stock, and false featured value. A fallback is used only when the selection or property is nullish.

SearchTarget can describe one of two object shapes:

• a text search with a required query property
• a product lookup with a required productId property

Before a check, TypeScript cannot assume that either property exists. The in operator checks whether an object has a property key. When you check "query" in target, TypeScript narrows the matching branch to the text-search shape.

This is a property-presence check, not a truthiness check. An empty string is still a present query property.

For a focused local check, temporarily use this complete example in src/main.ts. Run npx tsc --noEmit, then run npm run dev and inspect the browser console.

A required query key makes the first branch safe: it can read target.query.length. The other branch is narrowed to the shape that has productId.

document.querySelector("#product-query") can either find an element or find nothing, so TypeScript gives its result the type Element | null. The selector ID identifies what you looked for; it does not prove which HTML element was found.

A null guard proves that a selection exists. A second guard, instanceof HTMLInputElement, proves that the existing element is specifically an input. Only then is the input-only value property safe to read.

Replace the relevant part of your existing index.html with this small search interface. Keep the status element in every test variation.

The guards are deliberately separate. If the search input is absent, the code can show one message. If an element exists at that ID but is not an input, it can show a different message.

Select both references first. Guard statusElement before assigning its textContent; it does not need an input subtype check. Then guard queryElement for absence and subtype before reading its value.

Enter your completed code in src/main.ts, then run npx tsc --noEmit and npm run dev.

Test three versions of index.html while keeping #search-status:

1. Leave the provided input in place.
2. Remove the element with id="product-query".
3. Replace that input with <div id="product-query"></div>.

For each version, inspect the status region in the browser. The second and third cases should be distinguishable rather than treated as the same failure.

A discriminated union is an object union in which every variant shares a discriminant property with a distinct literal value. Here, status identifies the current search outcome.

Each object represents one coherent state. A loading or empty search has no payload; a successful search owns products; a failed search owns message. This is safer than one broad object with several optional payload properties, where contradictory combinations could be possible.

Add this type alongside the existing Product type in src/main.ts.

A Product[] may contain zero items, even in the success variant. Choose the explicit empty outcome after checking products.length.

When status is checked, TypeScript narrows the whole state object in that branch. Therefore, products is available only in the success branch and message only in the error branch.

Use the state creator and message function in src/main.ts.

This final demo combines the checks you have already practiced. Each specialized operation follows a guard that answers one precise uncertainty:

• typeof selects the current primitive alternative.
• === null handles an absent selection or DOM lookup.
• "query" in target selects an object shape by a required key.
• instanceof HTMLInputElement establishes an input subtype.
• state.status === ... selects one interface outcome.
• ?? supplies a default only when a value is nullish.

The goal is not new syntax. It is to connect each uncertainty to the guard that makes the next operation safe.

In your existing local Vite project, replace index.html with this small interface. It supplies the search input and the status region used by the TypeScript demo.

index.html

Replace src/main.ts with this first section. chooseSelectedProduct has an explicit Product | null return type, so changing its argument later keeps both alternatives available to TypeScript.

src/main.ts — part 1

Append this directly after part 1.

Append this final section in src/main.ts. It checks the status element, distinguishes a missing query selection from a wrong element subtype, and preserves the fixture's intentional 0, false, and empty string with ??.

src/main.ts — part 3

From the project folder, run the type check and then start the local preview. Open the local address printed by Vite.

Run these commands from the project folder.

Use your local copy for these controlled variations. After each source edit, run npx tsc --noEmit, refresh the browser, observe the result, and restore the initial code before the next variation.

1. Keep the initial success state to confirm both identifier formats and the preserved 0, false, and empty subtitle.
2. Replace the state value one at a time with { status: "loading" }, { status: "empty" }, and { status: "error", message: "Network unavailable" }.
3. Change chooseSelectedProduct(true) to chooseSelectedProduct(false). Its declared return type remains Product | null, so this variation must still type-check.
4. Change the query selector to "#missing-query", then to "#search-status". Finally change the status selector to "#missing-status". The final case has no status region to update, but it should return safely without an exception.