{"id":12174,"library":"ts-expect","title":"TS Expect: TypeScript Compile-Time Type Assertions","description":"ts-expect provides a set of lightweight utilities designed for compile-time TypeScript type assertions. Its primary function, `expectType`, takes a value and a generic type, leveraging the TypeScript compiler to ensure the value is assignable to the generic type without performing any runtime checks. The current stable version is v1.3.0, with releases typically adding new utility functions or refining existing type definitions. Key differentiators include its minimalistic approach, relying solely on TypeScript's type system for validation, making it an excellent tool for testing type definitions within a project's codebase. It avoids the overhead of more complex type-checking frameworks like `dtslint` by focusing on direct, in-code type assertions, making it ideal for maintaining type correctness during refactoring or when developing complex generics.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"git://github.com/TypeStrong/ts-expect","tags":["javascript","typescript","type-check","assert","expect","type","check","types","typings"],"install":[{"cmd":"npm install ts-expect","lang":"bash","label":"npm"},{"cmd":"yarn add ts-expect","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-expect","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used in TypeScript files for compile-time type assertions. The CJS require pattern is incorrect for its primary usage context.","wrong":"const { expectType } = require('ts-expect');","symbol":"expectType","correct":"import { expectType } from 'ts-expect';"},{"note":"A utility type used for stricter type equality checks. Cannot be 'required' as it's a type-level construct.","wrong":"const { TypeEqual } = require('ts-expect');","symbol":"TypeEqual","correct":"import { TypeEqual } from 'ts-expect';"},{"note":"Introduced in v1.3.0 for exhaustive type checks within control flow, returning `never` at runtime and ensuring compile-time exhaustiveness.","wrong":"const { expectNever } = require('ts-expect');","symbol":"expectNever","correct":"import { expectNever } from 'ts-expect';"}],"quickstart":{"code":"import { expectType, TypeEqual, expectNever } from \"ts-expect\";\n\n// --- Basic expectType assertions ---\n// These checks are performed at compile-time by TypeScript.\nexpectType<string>(\"hello world\");\nexpectType<number>(42);\n\n// The following line would cause a compile-time error:\n// expectType<boolean>(\"true\"); // Type 'string' is not assignable to type 'boolean'.\n\n// --- Using TypeEqual for stricter type comparisons ---\n// TypeEqual is a utility type to ensure two types are exactly the same.\ninterface User {\n  id: string;\n  name: string;\n}\n\ntype AdminUser = { id: string; name: string; roles: string[] };\n\n// Expects that User and AdminUser are NOT equal, so asserting 'false' should pass.\nexpectType<TypeEqual<User, AdminUser>>(false);\n\n// The following would cause a compile-time error if types were not equal:\n// expectType<TypeEqual<User, { id: string; name: string }>>(false); // Type 'false' is not assignable to type 'true'.\n\n// --- Exhaustive checks with expectNever ---\n// expectNever is useful for ensuring all cases in a discriminated union or switch statement are handled.\ntype TrafficLight = \"red\" | \"yellow\" | \"blue\"; // Typo: 'blue' should likely be 'green'\n\nfunction getAction(light: TrafficLight): string {\n  switch (light) {\n    case \"red\":\n      return \"Stop\";\n    case \"yellow\":\n      return \"Prepare to stop\";\n    // If 'green' was intended and 'blue' added, this 'default' will catch unhandled types.\n    default:\n      // This line will trigger a TypeScript error if 'light' is not assignable to 'never'.\n      // It helps catch unhandled cases in unions at compile time.\n      return expectNever(light); // Expects 'light' to be 'never' here.\n  }\n}\n\ngetAction(\"red\");\ngetAction(\"yellow\");\n// The 'blue' case will cause a compile-time error due to expectNever if it's not handled.\n// This demonstrates a powerful pattern for ensuring type safety in complex logic.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to assert a value with a type that is not assignable to the generic type provided to `expectType`.","error":"Argument of type '\"some string\"' is not assignable to parameter of type 'number'."},{"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.","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.","error":"Type 'false' is not assignable to type 'true'."},{"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.","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.","error":"Function lacks ending return statement and return type does not include 'undefined'."}],"ecosystem":"npm"}