Typescript The Unknown And Never Types Complete Guide

Type unknown

The unknown type is a safe alternative to any. It represents any value but requires you to perform some type checks before using it. This makes your code more robust and less error-prone.

Example 1: Basic Usage

Let's start with a simple example where we declare a variable of type unknown and try to work with it:

let userInput: unknown;

userInput = 'Hello World';
userInput = 42;
userInput = true;
userInput = { key: 'value' };

In this example, userInput can hold any type of value because it's declared as unknown. But if you try to use the variable directly, TypeScript will throw an error unless you narrow down the type.

Error Example

// Error: Cannot assign type 'unknown' to type 'string'
let message: string = userInput;

To fix this, you need to check the type of userInput:

Example 2: Type Guard

We can use a type guard to ensure that userInput is a string before assigning it to message:

if (typeof userInput === 'string') {
  let message: string = userInput; // Now TypeScript knows userInput is a string
  console.log(message);
} else {
  console.error('userInput is not a string');
}

Here’s what happens:

• TypeScript narrows down the type of userInput inside the if block using the typeof operator.
• Since typeof userInput returns 'string', TypeScript treats userInput as a string within that block.
• You can now safely assign userInput to a string variable or call string-specific methods.

Example 3: Unknown vs. Any

To illustrate the difference between unknown and any, compare the following two examples:

Using any

let userInputAny: any;
userInputAny = 'Hello';

// No errors because TypeScript has no way to know userInputAny's type
console.log(userInputAny.toUpperCase()); 

Using unknown

let userInputUnknown: unknown;
userInputUnknown = 'Hello';

// Error: Property 'toUpperCase' does not exist on type 'unknown'.
console.log(userInputUnknown.toUpperCase());

if (typeof userInputUnknown === 'string') {
  // Inside this block, userInputUnknown is treated as a string
  console.log(userInputUnknown.toUpperCase());
} else {
  console.error('userInputUnknown is not a string');
}

As you can see, unknown forces you to add type checks before performing operations, while any allows you to skip these checks at the cost of type safety.

Type never

The never type represents values which are never supposed to occur. You typically use this type when a function will never return normally or when a variable will never be assigned a value.

Example 1: Functions That Never Return

A common use case for never is functions that always throw an error or contain an infinite loop:

function throwError(errMsg: string): never {
  throw new Error(errMsg);
}

function infiniteLoop(): never {
  while (true) {
    // do something
  }
}

In both cases, TypeScript knows these functions will never return a value, hence their return type is never.

Example 2: Type Checking

You might use never in type guard scenarios where you have exhausted all possible cases:

type Animal = 'dog' | 'cat' | 'bird';

function getAnimalDescription(animal: Animal): string {
  switch (animal) {
    case 'dog':
      return 'A dog is a loyal companion.';
    case 'cat':
      return 'Cats are independent and often mysterious.';
    case 'bird':
      return 'Birds can fly and sing.';
    
    default:
      // TypeScript will infer this line to be type 'never' 
      // because you should have covered all possible Animal types.
      const invalidAnimal: never = animal;
      throw new Error(`Unknown animal type: ${invalidAnimal}`);
  }
}

const descriptionDog = getAnimalDescription('dog'); // Valid
const descriptionCat = getAnimalDescription('cat'); // Valid
const descriptionBird = getAnimalDescription('bird'); // Valid

// Error: Argument of type 'fish' is not assignable to parameter of type 'Animal'.
const descriptionFish = getAnimalDescription('fish'); // Invalid

In this scenario:

• The function getAnimalDescription takes an argument of type Animal, which is a union of literal types 'dog', 'cat', and 'bird'.
• If you try to pass a value that is not part of the Animal union, TypeScript will throw an error.
• The default case includes a never type guard that ensures you've exhaustively handled all possible values for Animal.

Exhaustive Type Checking

If you don't include the never type guard:

function getAnimalDescription(animal: Animal): string {
  switch (animal) {
    case 'dog':
      return 'A dog is a loyal companion.';
    case 'cat':
      return 'Cats are independent and often mysterious.';
    // Missing case for 'bird'
    default:
      // Error: Type 'Bird' is not assignable to type 'never'.
      let invalidAnimal: never = animal; 
      throw new Error(`Unknown animal type: ${animal}`);
  }
}

This code will produce an error because the switch statement doesn’t cover all possible Animal values (bird is missing).

By adding the never type guard in the default case, TypeScript ensures that all possible values are handled:

switch (animal) {
  case 'dog':
    return 'A dog is a loyal companion.';
  case 'cat':
    return 'Cats are independent and often mysterious.';
  case 'bird':
    return 'Birds can fly and sing.';
  default:
    let invalidAnimal: never = animal; // Ensures all cases are handled
    throw new Error(`Unknown animal type: ${invalidAnimal}`);
}

With this guard, if you ever expand the Animal type (e.g., add a new fish literal), TypeScript will remind you to handle the new case in the switch statement.

Example 3: Impossible State

Sometimes, a variable should never reach a certain state. For example:

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${value}`);
}

function describeShape(shape: 'circle' | 'square'): string {
  switch (shape) {
    case 'circle':
      return 'A circle is round.';
    case 'square':
      return 'A square has four equal sides.';
    default:
      // TypeScript will infer the 'default' case to be unreachable,
      // thus, assigning the type 'never' to it.
      return assertNever(shape);
  }
}

In this scenario:

• The describeShape function takes a shape argument that can only be 'circle' or 'square'.
• If the function reaches the default case, it's an indication of an unexpected state—this should never happen.
• The assertNever function is designed to throw an error, but it also has a return type of never to indicate that it will never actually finish executing.

Summary

• Unknown: A type representing any value, but requires type checks before working with the value. Helps prevent type-related errors that any would allow.
• Never: A type for values that never occur, such as functions that never return or variables that should be impossible to reach.