type-assertions

library1.1.0jsnpmunverified

type-assertions is a JavaScript package providing a suite of assertion utilities specifically designed for testing TypeScript types at compile-time. It enables developers to write unit-like tests for their type definitions, ensuring that types behave as expected and catch regressions when refactoring complex type logic. The current stable version is 1.1.0, released in August 2019. This package has a very slow release cadence, with only two minor releases since its inception, indicating a stable and focused utility. Its primary differentiator is its reliance on the TypeScript compiler to validate assertions, providing compile-time feedback rather than runtime checks, which is ideal for validating type system intricacies.

testing type-stubs

npm install type-assertions

github ↗package ↗

INSTALL

IMPORT

SIG · TYPE-ASSERTIONS

type-assertions

testingjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import * as ta from 'type-assertions';

✗ const ta = require('type-assertions');

The library primarily exports types and the `assert` function. Using `require` directly for CommonJS environments will likely result in a `TypeError` at runtime because the `assert` function is meant for compile-time type checking and doesn't perform any runtime logic.

assert

✓ import { assert } from 'type-assertions';

While `import * as ta` is common, the `assert` function can be destructured directly. This function is a no-op at runtime and exists purely for its type-level effects.

Equal

✓ import type { Equal } from 'type-assertions';

For type-only imports like `Equal`, `Not`, `Extends`, and `UnionIncludesExact`, using `import type` is best practice to ensure these imports are entirely stripped from the JavaScript output, preventing potential runtime issues and optimizing bundle size.

Demonstrates how to import and use various type assertions like `Equal`, `Not`, `Extends`, and `UnionIncludesExact` within a TypeScript file to validate type relationships at compile time.

import * as ta from 'type-assertions'; // Assertions that should pass (no compile errors) ta.assert<ta.Not<ta.Equal<{x: 1}, never>>>(); ta.assert<ta.Not<ta.Equal<never, {x: 1}>>>(); ta.assert<ta.Not<ta.Equal<{x: 1}, {y: 1}>>>(); ta.assert<ta.Not<ta.Equal<{y: 1}, {x: 1}>>>(); ta.assert<ta.Extends<{x: 1}, any>>(); ta.assert<ta.Not<ta.Extends<any, {x: 1}>>>(); ta.assert<ta.UnionIncludesExact<string | number, string>>(); // Example of an assertion that would cause a compile-time error: // ta.assert<ta.Equal<string, number>>(); // Example of a failing union assertion // ta.assert<ta.UnionIncludesExact<string | number, 'hello'>>(); console.log('Type assertions passed (no compile errors were detected).');

Debug

Known issues

gotchaThis library performs checks exclusively at TypeScript compile-time. There are no runtime effects, and the `assert` function compiles down to a no-op in JavaScript. It will not throw errors or provide feedback at runtime.

fix

Use a TypeScript compiler (e.g., `tsc`) to run your type-tests. Failures will manifest as standard TypeScript compilation errors.

affects: >=1.0.0

gotchaAssertions made with `type-assertions` are subject to the behavior and limitations of the TypeScript compiler version being used. Newer TypeScript features or stricter checks in later versions might alter the outcome of certain type assertions.

fix

Specify a consistent TypeScript version in your project's `package.json` to ensure reproducible type-test results across environments and builds. Regularly test against new TypeScript versions before upgrading.

affects: >=1.0.0

gotchaThe `Extends<A, B>` assertion checks if type `A` is assignable to type `B`. This is not always equivalent to `A` being a *subtype* of `B`, especially with `any`, `unknown`, or conditional types. It strictly checks assignability.

fix

Carefully consider the implications of assignability versus strict subtyping. For precise subtyping checks, you might need to construct more complex conditional types using `[A] extends [B] ? ...` patterns, though `type-assertions` might not provide direct utilities for all such nuances.

affects: >=1.0.0

gotchaThere is no built-in reporting mechanism or test runner integration for `type-assertions`. Test results are solely conveyed through the presence or absence of TypeScript compilation errors.

fix

Integrate TypeScript compilation into your CI/CD pipeline. A successful `tsc --noEmit` run without errors indicates all type assertions passed. Tools like `ts-jest` or custom scripts can run `tsc` and report errors.

affects: >=1.0.0

Errors

Common errors & fixes

TS2345: Argument of type 'false' is not assignable to parameter of type 'true'.

A type assertion failed. For example, `ta.assert<ta.Equal<string, number>>()` would fail because `string` is not equal to `number`.

fix

The assertion itself is incorrect for the types being tested, or the types being tested do not meet the expected contract. Review the types involved and adjust either the type definitions or the assertion logic.

TypeError: (0 , type_assertions_1.assert) is not a function

Attempting to call the `assert` function at runtime in a JavaScript environment. The `assert` function is purely a type-level construct and has no runtime implementation.

fix

Ensure that `type-assertions` is only used within TypeScript files and that `assert` calls are stripped out during compilation to JavaScript. Do not attempt to invoke `assert` at runtime.

TS2749: 'Equal' refers to a value, but is being used as a type here. Did you mean 'typeof Equal'?

Using `Equal` (or other type utilities) as a type parameter without importing it correctly, or incorrectly mixing value and type imports.

fix

Use `import type { Equal } from 'type-assertions';` for type-only imports or ensure you are using the namespace import correctly, e.g., `ta.Equal<A, B>` after `import * as ta from 'type-assertions';`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ForbesLindesay/type-assertions ↗

packagehttps://www.npmjs.com/package/type-assertions ↗