colinhacks/typejest

🦆
typejest

Delightful type assertions with a Jest-like API

Types need tests, too! If you're application code involves generics, type inference, or conditional types, you should write tests to make sure everything is working as expected! typejest provides a Jest-like API for making assertions about types.

Installation

bun add -d typejest
npm add -D typejest
yarn add -D typejest
pnpm add -D typejest

Usage

First, import the texpect function from typejest.

import {texpect} from 'typejest';

Start by specifying an input type.

// you can pass in a value
texpect('tuna'); // TExpect<string>

// or pass in a type directly
texpect<string>(); // TExpect<string>

Note: texpect is analogous to expect in Jest.

The returned TExpect object has methods that can be used to make assertions about the type. For instance, to assert that the input exactly matches a certain type:

import {texpect} from 'typejest';

texpect('tuna').is<string>(); // assert value is of type
texpect<string>().is<string>(); // assert two types are equal

If an assertion is not true, typejest will throw an error.

API

To assert that the input exactly matches a certain type:

texpect('tuna').is<string>();
texpect<string>().is<string>();

To assert that the input extends a certain type:

const value = 'asdf';

texpect(value).extends<string | number>(); // true
texpect<string>().extends<string | number>(); // true

To assert that the input matches certain common types, convenience methods are provided:

texpect('asdf').string();
texpect(123).number();
texpect(true).boolean();
texpect(false).boolean();
texpect(Symbol()).symbol();
texpect(BigInt(123)).bigint();
texpect({}).object();
texpect(() => {}).function();
texpect<any[]>().array();
texpect(null).null();
texpect(undefined).undefined();
texpect<never>().never();
texpect<unknown>().unknown();
texpect<void>().void();

Object types

The following helpers are available for object types. These helpers transform the input type and return a new TExpect instance. They do not make any assertions about the type.

type Dog = {name: string; age?: number};

texpect<Dog>().partial; // TExpect<Partial<Dog>>
texpect<Dog>().required; // TExpect<Required<Dog>>
texpect<Dog>().keyof; // TExpect<keyof Dog>

texpect<Dog>().pick<'name'>; // TExpect<Pick<Dog, "name">>
texpect<Dog>().pick('name'); // TExpect<Pick<Dog, "name">>

texpect<Dog>().omit<'name'>; // TExpect<Omit<Dog, "name">>
texpect<Dog>().omit('name'); // TExpect<Omit<Dog, "name">>

These helpers can be used in conjunction with the assertion methods:

texpect<Dog>.keyof.is<"name" | "age">();
texpect<Dog>.pick("name").is<{ name: string }>();
texpect<Dog>.partial.is<{ name?: string; age?: number; }>();

Tuple types

The following assertion methods are available for tuple types:

const value = ['string', 234] as const;

texpect<typeof value>().first<'string'>();
texpect<typeof value>().last<234>();

Object types

The following assertion methods are available for function types:

function length(arg: string) {
  return arg.length;
}

texpect<typeof length>().returns<number>();
texpect<typeof length>().accepts<[string]>();

Development

Made by @colinhacks. MIT licensed. Contributions welcome!