npm install asserttt---
Table of contents:
* Installation
* Use cases
* Complementary tools
* Usage
* API
* How does the code work?
* Related work
---
``js`
npm install asserttt
asserttt has no non-dev dependencies!
* 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
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.
`ts
import { type Assert, assertType, type Assignable, type Equal, type Extends, type Includes, type Not } from 'asserttt';
//========== Asserting types: Assert ==========
{
type Pair
type _1 = Assert
>>;
type _2 = Assert
>>>;
}
{
type _ = [
Assert
Assert
Assert
Assert
Assert
];
}
//========== Asserting types of values: assertType
const n = 3 + 1;
assertType
`
* AssertassertType
*
Equality:
* EqualMutuallyAssignable
* PedanticEqual
*
Comparing/detecting types:
* ExtendsAssignable
* Includes
* IsAny
*
Boolean operations:
* Not
#### MutuallyAssignable
`ts`
export type MutuallyAssignable
[X, Y] extends [Y, X] ? true : false
;
* The brackets on the left-hand side of extends prevent distributivity.any
* Almost what we want for checking equality, but 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
: false
;
type IsAny
* Explanation of Equal
* Explanation of IsAny
#### PedanticEqual: a popular hack with several downsides
`ts`
type PedanticEqual
(
(
;
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.
`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)
* 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
expectType
* 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.