unknown

The unknown type is a type-safe top type in TypeScript’s type system. It represents a value that can be of any type, but unlike the any type, it enforces strict compiler checks by prohibiting arbitrary operations, property access, or method calls until the value’s specific type is resolved.

Assignability

Because unknown is a top type, all other types are assignable to it.

let value: unknown;

value = 42;           // Valid
value = "string";     // Valid
value = false;        // Valid
value = { a: 1 };     // Valid
value = null;         // Valid
value = undefined;    // Valid

Conversely, unknown is strictly constrained in outbound assignability. A variable of type unknown can only be assigned to variables of type unknown or any.

let unknownValue: unknown = "data";

let val1: any = unknownValue;      // Valid
let val2: unknown = unknownValue;  // Valid

// let val3: string = unknownValue; // Error: Type 'unknown' is not assignable to type 'string'
// let val4: object = unknownValue; // Error: Type 'unknown' is not assignable to type 'object'

Operational Constraints

The TypeScript compiler treats unknown as a completely opaque value. You cannot perform operations on it, access its properties, or invoke it as a function or constructor.

let target: unknown = { execute: () => console.log("running") };

// target.execute(); // Error: Object is of type 'unknown'
// target();         // Error: Object is of type 'unknown'
// new target();     // Error: Object is of type 'unknown'

Type Resolution

To interact with an unknown value, you must resolve its type using either control flow analysis (type narrowing) or type assertions.

1. Type Narrowing Using type guards (typeof, instanceof, or custom type guard functions) allows the compiler to narrow the unknown type to a more specific type within a conditional block.

let data: unknown = "TypeScript";

if (typeof data === "string") {
    // Within this block, 'data' is narrowed to 'string'
    console.log(data.toUpperCase()); 
}

2. Type Assertions If the type is known to the developer but not the compiler, a type assertion can be used to override the unknown constraint.

let data: unknown = "TypeScript";

// Asserting that 'data' is a string
let length: number = (data as string).length; 

Union and Intersection Mechanics

When combined with other types in unions and intersections, unknown follows specific algebraic rules:

Union Types A union of unknown and any other type (except any) evaluates to unknown. It absorbs other types because unknown already encompasses all possible values.

type T1 = unknown | string;  // Resolves to unknown
type T2 = unknown | number;  // Resolves to unknown
type T3 = unknown | any;     // Resolves to any

Intersection Types An intersection of unknown and any other type evaluates to the other type. Since unknown places no structural constraints on a type, intersecting with it does not alter the intersected type.

type T4 = unknown & string;  // Resolves to string
type T5 = unknown & number;  // Resolves to number

Master TypeScript with Deep Grasping Methodology!

Learn More