TypeScript never Type Guide

The never type represents values that never occur. Here's how to use it effectively.

Understanding never#

// never is the bottom type
// No value can be assigned to never
let x: never;

// x = 1;         // Error
// x = 'string';  // Error
// x = null;      // Error
// x = undefined; // Error

// never is a subtype of all types
const n: never = undefined as never;
const str: string = n;    // OK - never assignable to anything
const num: number = n;    // OK
const bool: boolean = n;  // OK

// But nothing is assignable to never (except never)
// const n2: never = 'hello'; // Error

Functions That Never Return#

// Function that throws
function throwError(message: string): never {
  throw new Error(message);
}

// Function with infinite loop
function infiniteLoop(): never {
  while (true) {
    // Never exits
  }
}

// Comparison with void
function logMessage(msg: string): void {
  console.log(msg);
  // Returns undefined implicitly
}

function fail(msg: string): never {
  throw new Error(msg);
  // Never returns anything
}

// Usage in call chains
function processData(data: unknown): string {
  if (typeof data !== 'string') {
    throwError('Expected string'); // never type - code below unreachable
  }
  return data.toUpperCase(); // TypeScript knows data is string
}

Exhaustive Checking#

// Ensure all cases handled
type Shape = 'circle' | 'square' | 'triangle';

function getArea(shape: Shape): number {
  switch (shape) {
    case 'circle':
      return Math.PI * 10 ** 2;
    case 'square':
      return 10 * 10;
    case 'triangle':
      return (10 * 10) / 2;
    default:
      // If all cases handled, shape is never
      const _exhaustive: never = shape;
      return _exhaustive;
  }
}

// Add new shape - TypeScript catches missing case
type ShapeV2 = 'circle' | 'square' | 'triangle' | 'rectangle';

function getAreaV2(shape: ShapeV2): number {
  switch (shape) {
    case 'circle':
      return Math.PI * 10 ** 2;
    case 'square':
      return 10 * 10;
    case 'triangle':
      return (10 * 10) / 2;
    // Missing 'rectangle' case!
    default:
      const _exhaustive: never = shape;
      // Error: Type 'string' is not assignable to type 'never'
      return _exhaustive;
  }
}

// Helper function
function assertNever(value: never, message?: string): never {
  throw new Error(message || `Unexpected value: ${value}`);
}

function getAreaWithHelper(shape: Shape): number {
  switch (shape) {
    case 'circle':
      return Math.PI * 10 ** 2;
    case 'square':
      return 10 * 10;
    case 'triangle':
      return (10 * 10) / 2;
    default:
      return assertNever(shape, `Unknown shape: ${shape}`);
  }
}

Type Narrowing#

// never appears after exhaustive narrowing
function process(value: string | number) {
  if (typeof value === 'string') {
    console.log(value.toUpperCase());
  } else if (typeof value === 'number') {
    console.log(value.toFixed(2));
  } else {
    // value is never here - all cases handled
    const _check: never = value;
  }
}

// With discriminated unions
type Result =
  | { type: 'success'; data: string }
  | { type: 'error'; error: Error };

function handleResult(result: Result) {
  switch (result.type) {
    case 'success':
      console.log(result.data);
      break;
    case 'error':
      console.error(result.error);
      break;
    default:
      const _exhaustive: never = result;
  }
}

Conditional Types#

// never in conditional types
type NonNullable<T> = T extends null | undefined ? never : T;

type A = NonNullable<string | null>;    // string
type B = NonNullable<undefined | number>; // number
type C = NonNullable<null>;              // never

// Filter from union
type Filter<T, U> = T extends U ? never : T;

type Numbers = Filter<string | number | boolean, string>;
// number | boolean

// Exclude (built-in)
type Exclude<T, U> = T extends U ? never : T;

type WithoutString = Exclude<string | number | boolean, string>;
// number | boolean

// Extract (built-in)
type Extract<T, U> = T extends U ? T : never;

type OnlyStrings = Extract<string | number | boolean, string>;
// string

// never in unions disappears
type Union = string | never | number;
// string | number

Impossible States#

// Represent impossible combinations
type LoadingState = {
  status: 'loading';
  data?: never;  // Can't have data while loading
  error?: never; // Can't have error while loading
};

type SuccessState = {
  status: 'success';
  data: string;
  error?: never; // Can't have error on success
};

type ErrorState = {
  status: 'error';
  data?: never;  // Can't have data on error
  error: Error;
};

type State = LoadingState | SuccessState | ErrorState;

// TypeScript enforces valid states
const loading: State = { status: 'loading' }; // OK
const success: State = { status: 'success', data: 'Hello' }; // OK
const error: State = { status: 'error', error: new Error() }; // OK

// Invalid states caught at compile time
// const invalid: State = {
//   status: 'success',
//   data: 'Hello',
//   error: new Error() // Error: Type 'Error' is not assignable to type 'undefined'
// };

Function Overloads#

// never helps with overload resolution
function processValue(value: string): string;
function processValue(value: number): number;
function processValue(value: string | number): string | number {
  if (typeof value === 'string') {
    return value.toUpperCase();
  }
  return value * 2;
}

// Without proper overloads, return would include never
type Result = ReturnType<typeof processValue>;
// string | number (never filtered out)

Generic Constraints#

// Use never for impossible generics
type Keys<T> = T extends object ? keyof T : never;

type StringKeys = Keys<{ a: 1; b: 2 }>; // 'a' | 'b'
type NoKeys = Keys<string>;              // never

// Require at least one property
type RequireAtLeastOne<T> = {
  [K in keyof T]: Pick<T, K>;
}[keyof T];

// If no properties, becomes never
type Empty = RequireAtLeastOne<{}>; // never

// Mutual exclusion
type Without<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;

type User = {
  id: number;
  name: string;
  email: string;
};

type UserWithoutId = Without<User, 'id'>;
// { name: string; email: string; }

Error Handling Patterns#

// Type-safe error handling
type Success<T> = { success: true; value: T };
type Failure<E> = { success: false; error: E };
type Result<T, E = Error> = Success<T> | Failure<E>;

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return { success: false, error: 'Division by zero' };
  }
  return { success: true, value: a / b };
}

function handleResult<T, E>(
  result: Result<T, E>,
  onSuccess: (value: T) => void,
  onFailure: (error: E) => void
): void {
  if (result.success) {
    onSuccess(result.value);
  } else {
    onFailure(result.error);
  }
}

// Never-returning error handler
function panic(error: string): never {
  console.error(error);
  process.exit(1);
}

function unwrap<T>(result: Result<T>): T {
  if (result.success) {
    return result.value;
  }
  return panic(`Unwrap failed: ${result.error}`);
}

Best Practices#

Use never For:
✓ Exhaustive switch checks
✓ Functions that throw/loop forever
✓ Filtering union types
✓ Representing impossible states

Exhaustive Checking:
✓ Add default case with never
✓ Create assertNever helper
✓ Catch missing cases at compile time
✓ Use discriminated unions

Type Design:
✓ Use never for impossible properties
✓ Filter with conditional types
✓ Validate completeness
✓ Document never in APIs

Avoid:
✗ Assigning to never intentionally
✗ Ignoring never in results
✗ Over-complicating with never
✗ Forgetting exhaustive checks

The never type represents impossibility in TypeScript's type system. Use it for exhaustive checks, functions that don't return, conditional type filtering, and representing impossible states. It's essential for type-safe switch statements and catching missing cases at compile time.