🦆

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 declare function from typejest.

import {declare} from 'typejest';

Start by specifying an input type.

// you can pass in a value
declare('tuna'); // Declare<string>

// or pass in a type directly
declare<string>(); // Declare<string>

Note: declare is analogous to expect in Jest.

The returned Declare object has a bunch of methods that can be usd to make assertions about the type.

To assert that the input exactly matches a certain type:

import {declare} from 'typejest';

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

If a declaration is not true, typejest will throw an error.

API

To assert that the input exactly matches a certain type:

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

To assert that the input extends a certain type:

const value = 'asdf';

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

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

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

Object types

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

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

declare<Dog>().partial; // Declare<Partial<Dog>>
declare<Dog>().required; // Declare<Partial<Dog>>
declare<Dog>().keyof; // Declare<keyof Dog>

declare<Dog>().pick<'name'>; // Declare<Pick<Dog, "name">>
declare<Dog>().pick('name'); // Declare<Pick<Dog, "name">>

declare<Dog>().omit<'name'>; // Declare<Omit<Dog, "name">>
declare<Dog>().omit('name'); // Declare<Omit<Dog, "name">>

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

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

Tuple types

The following assertion methods are available for tuple types:

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

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

Object types

The following assertion methods are available for function types:

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

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

Development

Made by @colinhacks. MIT licensed. Contributions welcome!