expect-type

Compared to other projects like tsd, ts-expect, or type-plus, expect-type provides:

• Fluent API: A Jest-inspired syntax that clearly distinguishes between actual and expected types.
• Intuitive Inversion: Easily negate assertions using .not (e.g., expectTypeOf(...).not.toBeAny()).
• Strict Generics: Proper and strict handling of generic type checks.
• First-class Support: Specialized support for any, unknown, and never, as well as object properties, function parameters/returns, constructor parameters, class instances, array items, and nullable types.
• Relationship Matching: Support for "is-a" relationships using .toExtend<T>() rather than just exact equality.
• Zero Tooling Overhead: No CLI, IDE extensions, or extra build steps required. Assertions are checked at compile time via tsc and appear directly in your IDE.
• Lightweight: A small implementation with no dependencies.

Because assertions are written fluently, error messages can sometimes appear to be describing the 'expected' type rather than the 'actual' type.

For .toEqualTypeOf / .toMatchTypeOf: If you see a message like Type 'string' is not assignable to type '"Expected: string, Actual: number"', do not take it literally. Look at the property name and the human-readable string inside the quotes. It is telling you: Expected: string, Actual: number.

For .toBe... methods: These fail by resolving to a non-callable type. An error like Type 'ExpectString<number>' has no call signatures means you asserted a number should be a string.

Best Practice: To get the clearest error messages, use type arguments instead of concrete objects whenever possible:

• Better: expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()
• Worse: expectTypeOf({a: 1}).toEqualTypeOf({a: ''})

If you must compare two concrete values, use typeof: expectTypeOf(one).toEqualTypeOf<typeof two>()

For functions, you can drill down into specific parts of the signature:

• .parameters: Returns a union of all parameter arrays (up to 10 overloads).
• .parameter(n): Targets a specific parameter by index.
• .returns: Targets the return type.
• .resolves: Used with Promises to check the resolved value type.
• .toBeCallableWith(...args): Asserts that a function can be called with specific arguments. It also returns a type that allows you to narrow down the return type based on those arguments.

Note: For overloaded functions, expect-type provides better support than native TypeScript Parameters<T> by returning a union of all overloads.

type Factorize = {
  (input: number): number[]
  (input: bigint): bigint[]
}

// Check all overloads
expectTypeOf<Factorize>().parameters.toEqualTypeOf<[number] | [bigint]>()

// Narrow return type based on input
expectTypeOf<Factorize>().toBeCallableWith(6).returns.toEqualTypeOf<number[]>()

// Check Promise resolution
expectTypeOf(Promise.resolve(123)).resolves.toBeNumber()

Use these three methods to assert object relationships, but choose the one that matches your intent:

• .toEqualTypeOf<T>(): Performs a strict equality check. The types must be identical. It fails if there are excess properties or missing properties.
• .toMatchObjectType<T>(): Performs a strict check on a subset of keys. It succeeds if the object contains at least the keys defined in T, even if it has extra properties. This is usually preferred for object testing.
• .toExtend<T>(): Checks for an "is-a" relationship. It succeeds if the actual type is a subtype of the expected type.

Note: All three methods fail if properties defined in the expected type are missing from the actual type.

// Strict equality (fails on excess properties)
expectTypeOf({a: 1, b: 1}).toEqualTypeOf<{a: number}>()

// Partial match (allows extra properties)
expectTypeOf({a: 1, b: 1}).toMatchObjectType<{a: number}>()

// Subtype check (is-a relationship)
type Fruit = {type: 'Fruit'; edible: boolean}
type Apple = {type: 'Fruit'; name: 'Apple'; edible: true}
expectTypeOf<Apple>().toExtend<Fruit>()

When you have a large, complex object and don't know where a bad type (like any or never) is lurking, use .branded.inspect(). This performs a deep walk of the type and reports the paths to the problematic types.

Usage:

• Use it to find any or never (default).
• You can specify findType: 'unknown' to search for unknown types.
• Warning: This is a heavy operation. It can cause the TypeScript compiler to give up if the type is excessively deep. Use it for debugging or validation, but avoid committing it to source control if possible.

Comparison:

• Use .toBeAny() when you know exactly which property should be any.
• Use .branded.inspect() when you are searching for a needle in a haystack.

const bad = (metadata: string) => ({
  meta: {
    parsed: JSON.parse(metadata), // any!
  },
})

// Finds the path to the 'any' type
expectTypeOf(bad).returns.branded.inspect({
  foundProps: {
    '.meta.parsed': 'any',
  },
})