Docs
gentleduck ttest

gentleduck ttest

TypeScript Type-Level Test Framework. Assert your types like you mean it, at compile time.

What is this?

ttest is a zero-runtime library for writing type-level tests in TypeScript.

You spend countless hours designing complex types and systems — ttest gives you a way to validate them with confidence.
No console.log, no runtime hacks, just pure type assertion at compile-time.

Features

  • Zero-runtime: Fully erased at compile time, no emitted JS.
  • Precise assertions: Verify assignability, equality, and inference.
  • IDE-friendly: Fails type-checking with helpful messages.
  • Works with your favorite setup (tsc, tsd, vitest + @ts-expect-error).
  • Designed for duck-typed systems, schema builders, type-safe APIs, and ORMs.

Installation

npm install --save-dev @gentleduck/ttest
npm install --save-dev @gentleduck/ttest

Quick Start

import { AssertTrue, Equal } from "@gentleduck/ttest";
 
type Schema = InferSchema<
  "CREATE TABLE users (id INT PRIMARY KEY, email TEXT NOT NULL)"
>;
 
type Test_Column = AssertTrue<
  Equal<Schema["email"], string>,
  'Expected SQL "TEXT" to infer as string'
>;
import { AssertTrue, Equal } from "@gentleduck/ttest";
 
type Schema = InferSchema<
  "CREATE TABLE users (id INT PRIMARY KEY, email TEXT NOT NULL)"
>;
 
type Test_Column = AssertTrue<
  Equal<Schema["email"], string>,
  'Expected SQL "TEXT" to infer as string'
>;

Why Not tsd or expect-type?

@gentleduck/ttest is inspired by them but designed for framework authors and type-heavy codebases:

  • Cleaner API for grouped tests.
  • More powerful inference testing.
  • Easier integration with custom toolchains.
  • It’s a duck thing 🦆, it fits your ecosystem.

Advanced Patterns

import { AssertTrue, Equal } from "@gentleduck/ttest";
import { XOR } from "@gentleduck/utils";
 
type X1 = XOR<
  { a: number; common: string },
  { b: boolean; common: string }
>;
 
// expected: { a: number } | { b: boolean }
type Test_X1 = AssertTrue<
  Equal<X1, { a: number } | { b: boolean }>,
  "Expected XOR to produce mutually exclusive union of properties"
>;
import { AssertTrue, Equal } from "@gentleduck/ttest";
import { XOR } from "@gentleduck/utils";
 
type X1 = XOR<
  { a: number; common: string },
  { b: boolean; common: string }
>;
 
// expected: { a: number } | { b: boolean }
type Test_X1 = AssertTrue<
  Equal<X1, { a: number } | { b: boolean }>,
  "Expected XOR to produce mutually exclusive union of properties"
>;

Philosophy

If you’re building a schema system, compiler, or framework, types are your architecture. You can’t trust what you can’t test. @gentleduck/ttest exists to close the feedback loop between your types and your logic.

Gentleduck HooksAccordion