assertNever function

Marks a code path as unreachable: in the default of a switch over a union, TypeScript fails when a member is not handled, and an unexpected value throws at run time.

import { assertNever } from 'utils';

Signature

export function assertNever(value: never, message = 'Unexpected value'): never

Parameters

Name	Description
value	The value narrowed to never.
message	The message of the error. Defaults to 'Unexpected value'.

Errors

• Throws Error: Always.

Example

switch (mode) {
  case 'day': return light;
  case 'night': return dark;
  default: return assertNever(mode);
}

Tests

Line coverage: 100 %.

• ✅ throws with a custom message
• ✅ throws "Unexpected value" for a null or undefined message

Source

src/guard/assert-never.ts (on GitHub)

Source code

/**
 * Marks a code path as unreachable: in the `default` of a `switch` over a union, TypeScript fails when a
 * member is not handled, and an unexpected value throws at run time.
 *
 * @param value - The value narrowed to `never`.
 * @param message - The message of the error. Defaults to `'Unexpected value'`.
 * @throws {Error} Always.
 * @example
 * switch (mode) {
 *   case 'day': return light;
 *   case 'night': return dark;
 *   default: return assertNever(mode);
 * }
 */
export function assertNever(value: never, message = 'Unexpected value'): never {
  throw new Error(message);
}

Test file

import { assertNever } from './assert-never';

describe(assertNever, () => {
  it('throws with a custom message', () => {
    expect(() => assertNever('oops' as never, 'Unknown mode')).toThrow('Unknown mode');
  });

  it('throws "Unexpected value" for a null or undefined message', () => {
    expect(() => assertNever(1 as never)).toThrow('Unexpected value');
  });
});

Keywords: assert, never, guards, function