--- name: type-assertions description: Type assertion patterns using @kitz/assert. Triggers on type-level tests, .test-d.ts files, or when asserting TypeScript types. --- # Type Assertions ## Import ```typescript import { Assert } from '@kitz/assert' ``` ## Builder Pattern Assertions use a fluent builder: `Assert..(expected).().on(actual)` ### Relators (Required First) | Relator | Meaning | | -------- | --------------------------- | | `.exact` | Types must be identical | | `.equiv` | Bidirectional assignability | | `.sub` | Actual extends expected | ### Unary Matchers (No Expected Type) ```typescript 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 ```typescript // Value-level (preferred) Assert.exact.of(expected).on(actual) // Type-level only Assert.exact.ofAs().onAs() // 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) ```typescript // 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 ```typescript // Extract return type Assert.exact.string.returned.on(fn) // ReturnType is string // Extract awaited type Assert.exact.string.awaited.on(promise) // Awaited 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: ```typescript // 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().onAs() Assert.exact.ofAs().onAs() // @ts-expect-error - type mismatch Assert.exact.ofAs().onAs() ``` ## Avoid ```typescript // DON'T use type-level only assertions in test blocks test('bad', () => { type _ = Assert.exact.of // Short-circuits on first error }) ```

type-assertions

Install this skill

Comments