asserttt: minimal API for testing types

---

Table of contents:

* Installation
* Use cases
* Complementary tools
* Usage
* API
* How does the code work?
* Related work

---

Installation

``js
npm install asserttt
`

asserttt has no non-dev dependencies!

Use cases

* Testing types
* Documenting TypeScript with code examples (e.g. via Markcheck)
* Support for TypeScript exercises, such as the ones provided by [Type](https://tsch.js.org).
* Testing that related types are consistent in normal code

Complementary tools

If a file contains type tests, it’s not enough to run it, we must also type-check it:

* tsx (TypeScript Execute) is a tool that type-checks files before running them.
* It works well with the Mocha test runner: example setup
* ts-expect-error performs two tasks:
* Checking if each @ts-expect-error annotation prevents the right kind of error
* Optional: reporting errors detected by TypeScript
* Markcheck tests Markdown code blocks.

Usage

`ts
import { type Assert, assertType, type Assignable, type Equal, type Extends, type Includes, type Not } from 'asserttt';

//========== Asserting types: Assert ==========

{
type Pair = [X, X];
type _1 = Assert Pair<'a'>, ['a', 'a']
>>;
type _2 = Assert Pair<'a'>, ['x', 'x']
>>>;
}

{
type _ = [
Assert>,

Assert, Object>>,
Assert, RegExp>>>,

Assert>,
Assert>,
];
}

//========== Asserting types of values: assertType(v) ==========

const n = 3 + 1;
assertType(n);
`

API

$3

* Assert
* assertType(value)

$3

Equality:

* Equal
* MutuallyAssignable
* PedanticEqual

Comparing/detecting types:

* Extends
* Assignable
* Includes
* IsAny

Boolean operations:

* Not

How does the code work?

$3

#### MutuallyAssignable

`ts
export type MutuallyAssignable =
[X, Y] extends [Y, X] ? true : false
;
`

* The brackets on the left-hand side of extends prevent distributivity.
* Almost what we want for checking equality, but any is equal to all types – which is problematic when testing types.

#### Equal: like MutuallyAssignable but any is only equal to itself

This Equal predicate works well for many use cases:

`ts
type Equal =
[IsAny, IsAny] extends [true, true] ? true
: [IsAny, IsAny] extends [false, false] ? MutuallyAssignable
: false
;
type IsAny = 0 extends (1 & T) ? true : false;
`

* Explanation of Equal
* Explanation of IsAny.

#### PedanticEqual: a popular hack with several downsides

`ts
type PedanticEqual =
(() => T extends X ? 1 : 2) extends // (A)
(() => T extends Y ? 1 : 2) ? true : false // (B)
;
`

It was suggested by Matt McCutchen (source). How does it work (source)?

In order to check whether the function type in line A extends the function type in line B, TypeScript has to compare the following two conditional types:

`ts
T extends X ? 1 : 2
T extends Y ? 1 : 2
`

Since T does not have a value, both conditional types are _deferred_. Assignability of two deferred conditional types is computed via the internal function isTypeIdenticalTo() and only true if:

1. Both have the same constraint.
2. Their “then” branches have the same type and their “else” branches have the same type.

Thanks to #1, X and Y are compared precisely.

This hack has several downsides: See test/pedantic-equal_test.ts for more information.

$3

`ts
type Assert<_T extends true> = void;
`

Alas, we can’t conditionally produce errors at the type level. That’s why we need to resort to a type parameter whose extends constraint requires it to be assignable to true.

(Idea by Blaine Bublitz)

Related work

* Package ts-expect inspired this package. It’s very similar. This package uses different names and has a utility type Assert (which doesn’t produce runtime code):
`ts
type _ = Assert>; // asserttt
expectType>(true); // ts-expect
`

* The type-challenges repository has a module with utility types for exercises. How is asserttt different?
* Smaller API
* Different names
* Implements boolean NOT via a helper type Not` (vs. two versions of the same utility type).

* eslint-plugin-expect-type supports an elegant notation but requires a special tool (eslint) for checking.