TS Expect: TypeScript Compile-Time Type Assertions

Common errors

• Argument of type '"some string"' is not assignable to parameter of type 'number'.

  cause Attempting to assert a value with a type that is not assignable to the generic type provided to `expectType`.
  fix Ensure the type of the value passed to `expectType` is assignable to the generic type. For example, `expectType<string>("hello")` or `expectType<number>(123)`.

• Type 'false' is not assignable to type 'true'.

  cause This error occurs when using `expectType<TypeEqual<Target, Value>>(true)` and `Target` is not strictly equal to `Value`. The `TypeEqual` utility resolves to `false`, causing the assertion against `true` to fail.
  fix Verify that `Target` and `Value` are indeed strictly equal in the TypeScript type system. If they are intentionally different, assert `expectType<TypeEqual<Target, Value>>(false)` instead.

• Function lacks ending return statement and return type does not include 'undefined'.

  cause When using `expectNever(value)` in a function with an explicit return type, this error can appear if not all code paths explicitly return a value of the declared type. This often happens if `expectNever`'s branch is expected to be unreachable but the compiler still needs a return.
  fix Ensure that `expectNever` is used in contexts where its return value (`never`) aligns with the function's return type (e.g., by throwing an error or in a `void` function). Alternatively, make sure all other branches explicitly return a value matching the function's return type.

Warnings

• gotcha `ts-expect` provides purely compile-time checks and performs no runtime validation. Developers expecting runtime assertions will find that `expectType` and `expectNever` do nothing at all when JavaScript code executes.
  Fix: For runtime validation, use a dedicated runtime validation library (e.g., Zod, Yup) or implement explicit runtime checks alongside `ts-expect` for compile-time safety.
• gotcha The `any` type in TypeScript acts as an 'off switch' for type checking. Passing a value typed as `any` to `expectType` will always pass, effectively bypassing the type check.
  Fix: Avoid using `any` when type safety is critical. Prefer `unknown` when you need a top type and explicitly narrow its type before assertion, or use more specific types.
• gotcha There's a subtle but important distinction between `expectType<never>(value)` and `expectNever(value)`. `expectType<never>(value)` is solely a compile-time assertion, whereas `expectNever(value)` also returns `never`, making it suitable for exhaustive checks in runtime code paths (like default cases in `switch` statements) where you want to ensure unreachable code remains unreachable.
  Fix: Use `expectNever(value)` when you need to return `never` (e.g., throwing an error in an unhandled case), and `expectType<never>(value)` for purely testing that a type resolves to `never` without affecting runtime flow.

Install

• npm install ts-expect npm
• yarn add ts-expect yarn
• pnpm add ts-expect pnpm

Imports

• expectType
  wrong:

  const { expectType } = require('ts-expect');

  correct:

  import { expectType } from 'ts-expect';

  Primarily used in TypeScript files for compile-time type assertions. The CJS require pattern is incorrect for its primary usage context.
• TypeEqual
  wrong:

  const { TypeEqual } = require('ts-expect');

  correct:

  import { TypeEqual } from 'ts-expect';

  A utility type used for stricter type equality checks. Cannot be 'required' as it's a type-level construct.
• expectNever
  wrong:

  const { expectNever } = require('ts-expect');

  correct:

  import { expectNever } from 'ts-expect';

  Introduced in v1.3.0 for exhaustive type checks within control flow, returning `never` at runtime and ensuring compile-time exhaustiveness.

Quickstart

This quickstart demonstrates basic compile-time type assertions with `expectType`, strict type comparisons using `TypeEqual`, and ensuring exhaustive handling of union types with `expectNever`, all without runtime execution.

import { expectType, TypeEqual, expectNever } from "ts-expect";

// --- Basic expectType assertions ---
// These checks are performed at compile-time by TypeScript.
expectType<string>("hello world");
expectType<number>(42);

// The following line would cause a compile-time error:
// expectType<boolean>("true"); // Type 'string' is not assignable to type 'boolean'.

// --- Using TypeEqual for stricter type comparisons ---
// TypeEqual is a utility type to ensure two types are exactly the same.
interface User {
  id: string;
  name: string;
}

type AdminUser = { id: string; name: string; roles: string[] };

// Expects that User and AdminUser are NOT equal, so asserting 'false' should pass.
expectType<TypeEqual<User, AdminUser>>(false);

// The following would cause a compile-time error if types were not equal:
// expectType<TypeEqual<User, { id: string; name: string }>>(false); // Type 'false' is not assignable to type 'true'.

// --- Exhaustive checks with expectNever ---
// expectNever is useful for ensuring all cases in a discriminated union or switch statement are handled.
type TrafficLight = "red" | "yellow" | "blue"; // Typo: 'blue' should likely be 'green'

function getAction(light: TrafficLight): string {
  switch (light) {
    case "red":
      return "Stop";
    case "yellow":
      return "Prepare to stop";
    // If 'green' was intended and 'blue' added, this 'default' will catch unhandled types.
    default:
      // This line will trigger a TypeScript error if 'light' is not assignable to 'never'.
      // It helps catch unhandled cases in unions at compile time.
      return expectNever(light); // Expects 'light' to be 'never' here.
  }
}

getAction("red");
getAction("yellow");
// The 'blue' case will cause a compile-time error due to expectNever if it's not handled.
// This demonstrates a powerful pattern for ensuring type safety in complex logic.