ts-expect
v1.3.0
Published
Checks TypeScript types match expected values
Downloads
533,966
Maintainers
Readme
TS Expect
Checks values in TypeScript match expectations.
Installation
npm install ts-expect --save
Usage
TS Expect exports a function, named expectType
, that does nothing at all. Instead, it depends on the TypeScript compiler and a generic to test the type of a "value" passed to expectType
is assignable to its generic in the type system.
import { expectType } from "ts-expect";
expectType<string>("test");
expectType<number>(123);
expectType<number>("test"); // Compiler error!
How does this work?
TypeScript generics allow you to pass any value that implements the generic type. In this case, we're defining the generic explicitly as we pass the value so any value that isn't implementing our type is rejected by the TypeScript compiler. It's really that simple! The technical implementation is just <T>(value: T) => void
.
TypeScript has a "top type" named unknown
and a "bottom type" named never
. Using the top type to check assignability would mean every value is accepted, and the bottom type would mean nothing is accepted (except never
itself). As a result, you probably wouldn't want to use unknown
because everything would pass that check.
A quick note on any
: it's an "off switch" for TypeScript. It acts as a magical every type, both a top and a bottom type. This means it's assignable to everything and passing an any
value to expectType
will always pass the check.
Testing definitions
Use with built-in or custom TypeScript utility types to implement a simple testing framework for your type definitions. If it compiles, it's valid!
import { expectType, TypeEqual } from "ts-expect";
import { add } from "./adder";
expectType<number>(add(1, 2));
expectType<TypeEqual<boolean, ReturnType<typeof add>>>(true);
expectType<TypeEqual<[number, number], Parameters<typeof add>>>(true);
Exhaustive checks
Use with TypeScript's type narrowing to test that value
is what you expect. If you expand SupportedValue
with other values in the future, it'll fail an expectType<never>
or expectNever
check because you haven't used all the possible values.
import { expectNever } from "ts-expect";
type SupportedValue = "a" | "b";
function doSomething(value: SupportedValue) {
switch (value) {
case "a":
return true;
case "b":
return true;
default:
return expectNever(value);
}
}
Tip: Use expectNever(value)
when you need to return never
(i.e. throw an error if the code runs), use expectType<never>(value)
when you want to do tests in your code and expect the actual expression to be executed (i.e. do type checks but ignore the runtime).
Exported Types
TS Expect comes with some utility types built-in to make testing easier. File an issue if you think something is missing!
TypeEqual<Target, Value>
Checks that Value
is equal to the same type as Target
. This is a stricter check that avoids issues with testing sub-types. If you want to verify that an object is identical shape, not just "implements" Target
, this is the type you need.
TypeOf<Target, Value>
Checks that Value
is assignable to Target
. This is effectively the same as expectType<Type>(value)
, except it's implemented in the type system directly so you can use it to test types instead of values by checking the result is true
or false
.
Prior Works
Some great prior works have been mentioned after publishing this package:
dtslint
does type checks via comment directives and inspired this approach of using the compilertsd-check
is a CLI that runs the TypeScript type checker over assertionstype-plus
comes with various type and runtime TypeScript assertionsstatic-type-assert
exposes a similar API surface with some type assertion functions
License
MIT