Type Assertions

Import

import { Assert } from '@kitz/assert'

Builder Pattern

Assertions use a fluent builder: Assert.<relator>.<matcher>(expected).<setting>().on(actual)

Relators (Required First)

| Relator | Meaning | | -------- | --------------------------- | | .exact | Types must be identical | | .equiv | Bidirectional assignability | | .sub | Actual extends expected |

Unary Matchers (No Expected Type)

Assert.exact.any.on(value) // value is any
Assert.exact.unknown.on(value) // value is unknown
Assert.exact.never.on(value) // value is never
Assert.exact.empty.on(value) // value is {}

Binary Matchers

// Value-level (preferred)
Assert.exact.of(expected).on(actual)

// Type-level only
Assert.exact.ofAs<Expected>().onAs<Actual>()

// Shorthand matchers
Assert.exact.string.on(value)
Assert.exact.number.on(value)
Assert.exact.boolean.on(value)
Assert.exact.bigint.on(value)
Assert.exact.symbol.on(value)
Assert.exact.null.on(value)
Assert.exact.undefined.on(value)
Assert.exact.void.on(value)
Assert.exact.object.on(value)
Assert.exact.function.on(value)

Settings (Optional)

// Negate assertion
Assert.exact.of(string).not.on(value) // value is NOT string

// Control type inference
Assert.exact.of(expected).inferNarrow().on(actual) // narrow inference
Assert.exact.of(expected).inferWide().on(actual) // wide inference
Assert.exact.of(expected).inferAuto().on(actual) // default

Extractors

// Extract return type
Assert.exact.string.returned.on(fn) // ReturnType<fn> is string

// Extract awaited type
Assert.exact.string.awaited.on(promise) // Awaited<promise> is string

// Extract parameters
Assert.exact.of([string, number]).parameters.on(fn)

// Extract array element
Assert.exact.string.array.on(arr) // arr is string[]

Preferred Pattern

ALWAYS prefer value-level API - it reports ALL failures simultaneously:

// In .test.ts files
test('types', () => {
  const value = getValue()
  Assert.exact.string.on(value)
  Assert.exact.of({ a: 1 }).on(obj)
})

// In .test-d.ts files (pure type-level)
Assert.exact.ofAs<string>().onAs<string>()
Assert.exact.ofAs<number>().onAs<number>()

// @ts-expect-error - type mismatch
Assert.exact.ofAs<string>().onAs<number>()

Avoid

// DON'T use type-level only assertions in test blocks
test('bad', () => {
  type _ = Assert.exact.of<string, number> // Short-circuits on first error
})