@deessejs/type-testing

A micro library for compile-time type testing in TypeScript.

Installation

npm install @deessejs/type-testing

Or with pnpm:

pnpm add @deessejs/type-testing

Or with yarn:

yarn add @deessejs/type-testing

Quick Start

import { Equal, check, assert, expect } from '@deessejs/type-testing'

// Simple type equality
type Test = Equal<string, string>  // true

// Chainable API
check<string>().equals<string>()   // passes

// Assert with clear errors
assert<{ a: string }>().hasProperty('a')

// Expect syntax
expect<string, string>().toBeEqual()

Core Types

Type Equality

import { Equal, NotEqual, SimpleEqual } from '@deessejs/type-testing'

// Strict equality (handles any, never, etc.)
Equal<string, string>           // true
Equal<string, number>           // false

// Inequality check
NotEqual<string, number>        // true

// Simple equality (for plain objects)
SimpleEqual<{ a: string }, { a: string }>  // true

Special Type Detection

import {
  IsAny,
  IsNever,
  IsUnknown,
  IsVoid,
  IsUndefined,
  IsNull,
  IsNullable,
  IsOptional
} from '@deessejs/type-testing'

IsAny<any>                      // true
IsNever<never>                  // true
IsUnknown<unknown>             // true
IsVoid<void>                    // true
IsUndefined<undefined>          // true
IsNull<null>                    // true

// Nullable = null | undefined
IsNullable<string | null>       // true
IsNullable<string | undefined>  // true

// Optional = may include undefined
IsOptional<string | undefined> // true

Union, Tuple & Array

import { IsUnion, IsTuple, IsArray } from '@deessejs/type-testing'

// Unions
IsUnion<'a' | 'b'>               // true
IsUnion<'a'>                     // false

// Tuples (fixed-length arrays)
IsTuple<[string, number]>        // true
IsTuple<[]>                      // true
IsTuple<string[]>                // false

// Arrays (dynamic-length)
IsArray<string[]>                // true
IsArray<[string]>                // false

Type Inhabitation

import { IsInhabited, IsUninhabited } from '@deessejs/type-testing'

// Has at least one value
IsInhabited<string>              // true
IsInhabited<never>               // false

// Has no values (never)
IsUninhabited<never>             // true
IsUninhabited<string>            // false

Property Testing

import { HasProperty, PropertyType } from '@deessejs/type-testing'

// Check if type has a property
HasProperty<{ a: string }, 'a'>  // true
HasProperty<{ a: string }, 'b'>  // false

// Get property type
PropertyType<{ a: string }, 'a'> // string

Property Modifiers

import { IsReadonly, IsRequired, IsPublic, IsPrivate, IsProtected } from '@deessejs/type-testing'

// Check if all properties are readonly
IsReadonly<{ readonly a: string }>  // true
IsReadonly<{ a: string }>          // false

// Check if all properties are required
IsRequired<{ a: string }>          // true
IsRequired<{ a?: string }>        // false

// Check property visibility (uses naming convention)
IsPublic<{ a: string }, 'a'>       // true
IsPrivate<{ __private: string }, '__private'>  // true
IsProtected<{ _protected: string }, '_protected'> // true

Note: IsPublic, IsPrivate, and IsProtected use TypeScript's private field naming convention (__ prefix) and common JavaScript convention (_ prefix for protected). These are naming-convention-based checks, not actual TypeScript access modifiers (which don't exist for object properties).

Function Types

import { Parameters, ReturnType, Parameter } from '@deessejs/type-testing'

// Get parameters as tuple
Parameters<(a: string, b: number) => void>  // [string, number]

// Get return type
ReturnType<(a: string) => number>           // number

// Get parameter at index
Parameter<(a: string, b: number), 0>        // string
Parameter<(a: string, b: number), 1>         // number

Length

import { Length } from '@deessejs/type-testing'

Length<['a', 'b', 'c']>            // 3
Length<[]>                          // 0

Deep Type Manipulation

import { DeepReadonly, DeepPartial, RequiredKeys, OptionalKeys } from '@deessejs/type-testing'

// Make all properties readonly recursively
DeepReadonly<{ a: string; b: { c: number } }>
// { readonly a: string; readonly b: { readonly c: number } }

// Make all properties optional recursively
DeepPartial<{ a: string; b: { c: number } }>
// { a?: string; b?: { c?: number } | undefined }

// Get keys of required properties
RequiredKeys<{ a: string; b?: number }>  // 'a'

// Get keys of optional properties
OptionalKeys<{ a: string; b?: number }>  // 'b'

Constructor & Abstract Types

import { IsConstructor, IsAbstract } from '@deessejs/type-testing'

class Foo {}
abstract class Bar {}

IsConstructor<typeof Foo>    // true
IsConstructor<Foo>          // false (instance)
IsAbstract<typeof Bar>      // true
IsAbstract<typeof Foo>     // false

Special Equality

import { IsNeverEqual } from '@deessejs/type-testing'

// Check if both types are never
// Differs from Equal<never, never> which returns false
IsNeverEqual<never, never>     // true
IsNeverEqual<any, any>        // false (any is not never)

Runtime Type Checking

The library also provides runtime type checking utilities:

import {
  // Type check functions returning TypeCheckResult objects
  isString,
  isNumber,
  isBoolean,
  isObject,
  isArray,
  isNull,
  isUndefined,

  // Boolean type guards (for use in conditionals)
  isStringGuard,
  isNumberGuard,
  isBooleanGuard,
  isObjectGuard,
  isArrayGuard,
  isNullGuard,
  isUndefinedGuard,
  isSymbolGuard,
  isBigIntGuard,
  isFunctionGuard
} from '@deessejs/type-testing'

// TypeCheckResult objects
const stringResult = isString('hello')
stringResult.matches   // true
stringResult.value     // 'hello'
stringResult.typeName   // 'string'

// Boolean type guards
if (isStringGuard(value)) {
  // value is narrowed to string here
}

Chainable API

check() - Soft type checking

import { check } from '@deessejs/type-testing'

// Type equality
check<string>().equals<string>()           // passes
check<string>().equals<number>()            // fails at compile time

// Type extends
check<string>().extends<string>()          // passes
check<string>().extends<any>()              // passes

// Property check
check<{ a: string }>().hasProperty('a')    // passes
check<{ a: string }>().hasProperty('b')     // fails

// Special types
check<any>().isAny()                        // passes
check<never>().isNever()                    // passes
check<unknown>().isUnknown()                // passes

// Nullable/Optional
check<string | null>().isNullable()         // passes
check<string | undefined>().isOptional()     // passes

// Union/Tuple/Array
check<'a' | 'b'>().isUnion()                // passes
check<[string, number]>().isTuple()         // passes
check<string[]>().isArray()                  // passes

assert() - Strict type checking

Similar to check() but throws at compile time on failure with a clearer error message.

import { assert } from '@deessejs/type-testing'

// Fails with a clear error message
assert<string>().equals<number>()           // compile error
assert<{ a: string }>().hasProperty('b')    // compile error

expect() - BDD-style API

import { expect } from '@deessejs/type-testing'

// Compare two types
expect<string, string>().toBeEqual()         // passes
expect<string, number>().toBeNotEqual()     // passes

// Type extends
expect<string>().toExtend<string>()          // passes

// Special types
expect<any>().toBeAny()                      // passes
expect<never>().toBeNever()                  // passes

// Nullable/Optional
expect<string | null>().toBeNullable()       // passes
expect<string | undefined>().toBeOptional()  // passes

Vitest Integration

The library provides a native Vitest integration with custom matchers for a more familiar testing experience.

Installation

npm install @deessejs/type-testing

Quick Start

import { expectType } from '@deessejs/type-testing/vitest'

// Type equality
expectType<string>().toBeType<string>()
expectType<string>().toNotBeType<number>()

// Type extends
expectType<string>().toExtend<string>()
expectType<string>().toNotExtend<number>()

// Property check
expectType<{ a: string }>().toHaveProperty('a')

// Special types
expectType<any>().toBeAny()
expectType<never>().toBeNever()
expectType<unknown>().toBeUnknown()
expectType<void>().toBeVoid()
expectType<undefined>().toBeUndefined()
expectType<null>().toBeNull()

// Nullable/Optional
expectType<string | null>().toBeNullable()
expectType<{ a?: string }>().toBeOptional()

// Structure
expectType<string | number>().toBeUnion()
expectType<[string, number]>().toBeTuple()
expectType<string[]>().toBeArray()

// Inhabitation
expectType<string>().toBeInhabited()
expectType<never>().toBeUninhabited()

Using with Vitest's expect.extend

You can also extend Vitest's expect with the matchers:

import { expect, test } from 'vitest'
import { toBeType, toHaveProperty } from '@deessejs/type-testing/vitest'

expect.extend({ toBeType, toHaveProperty })

test('type checks', () => {
  expect<string>().toBeType<string>()
  expect<{ a: string }>().toHaveProperty('a')
})

Setup File

For automatic matcher registration, add the setup file to your Vitest config:

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['@deessejs/type-testing/vitest/setup']
  }
})

Or import it in your setup file:

// setup.ts
import '@deessejs/type-testing/vitest/setup'

Available Matchers

| Matcher | Description | |---------|-------------| | toBeType<T>() | Asserts type equality | | toNotBeType<T>() | Asserts type inequality | | toExtend<T>() | Asserts type extends another | | toNotExtend<T>() | Asserts type does not extend another | | toHaveProperty<K>() | Asserts property exists | | toBeAny() | Asserts type is any | | toBeNever() | Asserts type is never | | toBeUnknown() | Asserts type is unknown | | toBeVoid() | Asserts type is void | | toBeUndefined() | Asserts type is undefined | | toBeNull() | Asserts type is null | | toBeNullable() | Asserts type is nullable | | toBeOptional() | Asserts type is optional | | toBeUnion() | Asserts type is a union | | toBeTuple() | Asserts type is a tuple | | toBeArray() | Asserts type is an array | | toBeInhabited() | Asserts type is inhabited | | toBeUninhabited() | Asserts type is uninhabited |

Note: The toNotBeType matcher follows a different pattern than standard Vitest (not.toBeType). This is intentional as it provides better TypeScript inference. Use toNotBeType instead of .not.toBeType.

Compile-time Assertions

ExpectTrue & ExpectEqual

import { ExpectTrue, ExpectEqual } from '@deessejs/type-testing'

// Assert a type is true
type Test1 = ExpectTrue<true>                // true

// Assert equality - throws if not equal
type Test2 = ExpectEqual<string, string>    // string

// Using with type tests
type IsString<T> = ExpectEqual<T, string>
type Result = IsString<string>              // string (passes)

expectFalse

import { expectFalse } from '@deessejs/type-testing'

// Assert T is false at compile time
expectFalse<false>()                        // passes
expectFalse<true>()                         // compile error

API Reference

Types

| Type | Description | |------|-------------| | Equal<T, U> | Strict equality check | | NotEqual<T, U> | Inequality check | | SimpleEqual<T, U> | Simple equality for plain types | | IsNeverEqual<T, U> | Check if both types are never | | IsAny<T> | Check if type is any | | IsNever<T> | Check if type is never | | IsUnknown<T> | Check if type is unknown | | IsVoid<T> | Check if type is void | | IsUndefined<T> | Check if type is undefined | | IsNull<T> | Check if type is null | | IsNullable<T> | Check if type is null \| undefined | | IsOptional<T> | Check if type may be undefined | | IsUnion<T> | Check if type is a union | | IsTuple<T> | Check if type is a tuple | | IsArray<T> | Check if type is an array | | IsInhabited<T> | Check if type has at least one value | | IsUninhabited<T> | Check if type has no values | | HasProperty<T, K> | Check if type has property K | | PropertyType<T, K> | Get type of property K | | IsReadonly<T> | Check if all properties are readonly | | IsRequired<T> | Check if all properties are required | | IsPublic<T, K> | Check if property is public | | IsPrivate<T, K> | Check if property is private (naming convention) | | IsProtected<T, K> | Check if property is protected (naming convention) | | DeepReadonly<T> | Make all properties readonly recursively | | DeepPartial<T> | Make all properties optional recursively | | RequiredKeys<T> | Get keys of required properties | | OptionalKeys<T> | Get keys of optional properties | | Parameters<T> | Get function parameters as tuple | | ReturnType<T> | Get function return type | | Parameter<T, N> | Get parameter at index N | | IsConstructor<T> | Check if type is a constructor | | IsAbstract<T> | Check if type is abstract | | Length<T> | Get tuple/array length | | ExpectTrue<T> | Assert T is true | | ExpectEqual<T, U> | Assert T equals U |

Functions

| Function | Description | |----------|-------------| | check<T>() | Create a chainable type checker | | assert<T>() | Create an assert type checker (throws on failure) | | expect<T, U>() | Create an expect-style type checker | | expectFalse<T>() | Assert T is false at compile time |

License

MIT