The unknown Type

unknown represents a value whose actual type has not been established. Unlike any, it requires a check before unsafe operations.

In this lesson, you will study the rule, run a complete TypeScript example, explain its output, and test a small change.

Use unknown for values from untrusted or broadly typed sources. You can assign concrete values to an unknown variable, but you cannot call string-only methods without narrowing. typeof, equality checks and user-defined guards help establish what operations are safe.

Use the diagram to locate the checks, values or branches involved in the example.

Save this code as main.ts or paste it into the TypeScript Playground. The example uses fixed values so it runs without prompting for input.

TypeScript code

const received: unknown = "typescript";
 if (typeof received === "string") {
   console.log(received.toUpperCase());
 } else {
   console.log("Not text");
 }

Verified output

TYPESCRIPT

How to run locally: npx tsc --strict --target es2022 --module commonjs main.ts, then node main.js. When using a project configuration, run the matching project build instead.

The runtime typeof test confirms the string branch. Inside that block TypeScript narrows unknown to string, so toUpperCase is permitted.

Predict the output before you run the sample. Compare each line with the source expression that produced it, and distinguish the type checker’s work from what happens in JavaScript at runtime.

An as string assertion does not validate received. If the input can come from outside your program, prefer a runtime check.

Debugging habit: when a change is rejected, read the exact compiler diagnostic and inspect the operand types. When it compiles but behaves unexpectedly, follow the values through the JavaScript expressions.

Change received to 123, then add a number branch that prints received * 2.

Challenge: write down your prediction first, run the changed source, and explain any difference. Return to the verified version before continuing.

The unknown Type: Use unknown for values from untrusted or broadly typed sources.

Narrowing is based on a real runtime check that TypeScript understands.

Before continuing, be able to explain what is checked before execution and what actually changes at runtime in the example above.