Using Assertion Functions in TypeScript (TS 3.7+)
Introduction
TypeScript 3.7 introduced a small but powerful feature: assertion functions. These are runtime helpers that inform the TypeScript compiler about refined types after a runtime check. For intermediate developers building robust applications, assertion functions let you centralize validation logic, improve type narrowing, and eliminate redundant type casts without scattering casts or negating type safety. In this tutorial you'll learn how assertion functions work, when to prefer them over type predicates or inline checks, and how to integrate them with real-world patterns like class constructors, DOM code, async flows, and untyped third-party data.
We'll cover language syntax, common idioms, and step-by-step examples that emphasize practical tradeoffs. Expect actionable snippets for validating primitives, complex objects, tuple/rest inputs, and "this" assertions on prototypes. We also show how to compose assertion functions, make them generic, type runtime guarantees for built-ins like Date or RegExp, and how to use them safely in library code. By the end you will be able to write assertion helpers that both enforce runtime invariants and satisfy TypeScript's control-flow analysis.
This guide assumes you know basic TypeScript typing, generics, union/intersection types, and how TypeScript narrows types. We include references to related topics so you can deepen your knowledge in adjacent areas such as typing variadic parameters, typing DOM elements, and typing third-party libraries for safer interop.
Background & Context
An assertion function is declared with a return type using the new "asserts" syntax: instead of returning a boolean, it throws on failure and narrows the input type for the remainder of the control flow. For example:
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== 'string') throw new TypeError('Expected string')
}After calling this function, TypeScript knows that value is a string in the subsequent code path. This works well in complex flows where inline checks are awkward or duplicated. Assertion functions are especially valuable in constructors, library boundaries, runtime validation layers, and when bridging untyped inputs into typed code.
Because assertion functions affect compile-time narrowing while performing runtime verification, they occupy a unique spot between type predicates and runtime validators. They are erased at runtime except for whatever code you write inside them, so you still pay the runtime cost of checking, but you gain stronger static typing with clearer intent.
Key links in the rest of this article point to related topics—such as handling variadic parameter types, typing DOM elements, or wrapping third-party APIs—so you can follow up on adjacent challenges.
Key Takeaways
- Assertion functions use the
assertsreturn annotation to refine types after runtime checks. - They are most useful when you want guaranteed narrowing without returning booleans.
- You can assert ordinary parameters,
this, or generic constraints. - Compose assertion functions for complex shapes and reuse across your codebase.
- Be mindful of control-flow, exceptions, and when narrowing does not apply.
- Use assertion functions at boundaries: constructors, untyped data, APIs, and DOM handling.
Prerequisites & Setup
You should have TypeScript 3.7 or newer installed. A typical setup uses tsconfig with strict enabled to get the best narrowing and error detection. If you run examples locally, a simple project scaffold with npm init -y and npm install typescript --save-dev is enough; add a tsconfig.json with at least target set to ES2019 and strict: true.
An editor with TypeScript language service (VS Code recommended) will show immediate type narrowing results. If you work with DOM code, also enable dom in lib to get correct DOM types. For advanced scenarios involving variadic parameter typing or this modifications, review related guides on typing rest arguments and this handling to ensure your helpers integrate smoothly.
Main Tutorial Sections
1) Basic assertion functions: syntax and simple examples
Assertion functions use the asserts return annotation. The signature is function name(arg: T): asserts arg is NarrowedT. Implementations throw when the check fails. For example:
function assertIsNumber(x: unknown): asserts x is number {
if (typeof x !== 'number') throw new TypeError('Expected number')
}
const raw: unknown = JSON.parse('"42"')
// Validate and narrow:
assertIsNumber(raw)
// After calling, raw is a number from the compiler's perspectiveThis pattern reduces repeated if checks and removes the need for as casts scattered across the codebase. Use descriptive error messages and include contextual info to aid debugging.
2) Asserting complex object shapes
For POJOs (plain objects), assertion functions can validate multiple properties and nested structures. Implement checks in a readable order and throw upon the first mismatch, or collect errors and throw a composed error for better UX:
type User = { id: number; name: string }
function assertIsUser(u: any): asserts u is User {
if (u == null || typeof u !== 'object') throw new TypeError('Expected object')
if (typeof u.id !== 'number') throw new TypeError('Missing numeric id')
if (typeof u.name !== 'string') throw new TypeError('Missing name')
}This is useful when receiving untyped JSON. For third-party libraries with complex return shapes, wrap and assert to convert them into well-typed entities. See our guide on Typing Third-Party Libraries with Complex APIs — A Practical Guide for strategies when external types are incomplete or unsafe.
3) Generic assertion helpers
Generics let you write reusable assertion utilities. Often you want to assert that a value is one of several types or conforming to a generic constraint:
function assertArrayOf<T>(value: unknown, elementAssert: (v: unknown) => asserts v is T): asserts value is T[] {
if (!Array.isArray(value)) throw new TypeError('Expected array')
for (const el of value) elementAssert(el)
}
// Usage
function assertIsString(x: unknown): asserts x is string {
if (typeof x !== 'string') throw new TypeError('Expected string')
}
const data: unknown = JSON.parse('["a","b"]')
assertArrayOf<string>(data, assertIsString)
// data is string[] nowCombining small, focused assertion functions composes well and keeps implementations testable.
4) Assertion functions and rest/tuple parameters
When writing functions that accept variable arguments, assertions help validate the runtime shape. This pairs nicely with TypeScript variadic tuple types—see the deeper treatment in Typing Functions That Accept a Variable Number of Arguments (Tuples and Rest).
Example: validate an argument list follows a pattern:
type Args = [string, number?, boolean?]
function assertArgsIsPattern(args: unknown[]): asserts args is Args {
if (typeof args[0] !== 'string') throw new TypeError('First arg must be string')
if (args[1] !== undefined && typeof args[1] !== 'number') throw new TypeError('Second arg must be number if present')
}
function log(...args: unknown[]) {
assertArgsIsPattern(args)
const [s, n] = args
// s is string, n is number | undefined
}Use assertion functions to bridge runtime validations with tuple/rest typings for safer APIs.
5) Asserting this and prototype methods
You can write assertion functions that refine this using the asserts this is T form. These are useful for prototype methods or functions that expect to be called with a certain this shape. For a deeper look at this typing patterns, review Typing Functions That Modify this (ThisParameterType, OmitThisParameter).
class Widget {
element: HTMLElement | null = null
ensureElement(): asserts this is { element: HTMLElement } {
if (!this.element) throw new Error('Widget has no element')
}
render() {
this.ensureElement()
// now this.element is HTMLElement
this.element.textContent = 'Hello'
}
}Be careful when using arrow functions; they do not get a this type and cannot be used to declare this assertions.
6) Assertion functions for built-in objects
When working with built-in objects like Date or RegExp, you often need runtime checks for well-formedness. Assertion functions can encapsulate those checks and help the compiler narrow types. If you work frequently with Date, check our notes in Typing Built-in Objects in TypeScript: Math, Date, RegExp, and More.
function assertIsDate(value: unknown): asserts value is Date {
if (!(value instanceof Date) || Number.isNaN(value.getTime())) throw new TypeError('Invalid Date')
}
const v: unknown = new Date('invalid')
assertIsDate(v) // throws for invalid dateClear, small validators make downstream logic safer and more self-documenting.
7) Integrating assertion functions with DOM code
In DOM-heavy applications, you often start with generic event targets or query selectors returning Element | null. Assertion functions let you convert that to a concrete element type after verification. For advanced DOM typing and patterns, see Typing DOM Elements and Events in TypeScript (Advanced).
function assertElement<T extends Element>(el: Element | null, ctor: { new(): T } | ((x: Element) => x is T)): asserts el is T {
if (!el) throw new Error('Element not found')
if (!(el instanceof (ctor as any))) throw new Error('Element is not expected type')
}
const maybeBtn = document.querySelector('#submit')
assertElement<HTMLButtonElement>(maybeBtn, HTMLButtonElement)
maybeBtn.disabled = true // safeThis removes repetitive null checks and explicit casts all over your event handlers.
8) Assertion functions with async flows and iterators
When validation is part of async processing—deserializing streamed JSON, or validating values produced by an async iterator—it helps to have assertion helpers you can call as values arrive. For complex async iteration patterns, refer to Typing Async Iterators and Async Iterables in TypeScript — Practical Guide.
async function processStream(it: AsyncIterable<unknown>) {
for await (const item of it) {
assertIsExpectedShape(item)
// now TypeScript narrows item here
handle(item)
}
}Using assertion helpers in an async loop keeps types precise without complicating control flow for callers.
9) Wrapping untyped libraries and runtime validation
At application boundaries you often consume untyped or loosely typed libraries. Assertion functions help transform those loose values into typed entities your code depends on. Pair this with patterns from Typing Third-Party Libraries with Complex APIs — A Practical Guide for a robust strategy.
// Suppose `lib.fetchUser()` returns any const result: any = lib.fetchUser() assertIsUser(result) useUser(result) // now typed
Document your assertions as the place where trust boundaries are enforced and add tests for those functions so runtime guarantees remain stable.
Advanced Techniques
Once you master the basics, several advanced patterns unlock greater flexibility. First, use composable assertion functions: build small leaf assertions and combine them in object or collection validators. Second, write assertion factories that create specialized validators for runtime-configured schemas. Third, use assertion functions together with TypeScript's branded types to ensure opaque identity across boundaries. Fourth, in performance-sensitive paths, minimize expensive checks inside tight loops: validate once and rely on trusted execution for repeated use. Also, when integrating with higher-order functions or decorators, ensure that assertion functions are applied before type-sensitive transformations.
If you need to assert shapes across class hierarchies or decorators, you can write this assertion helpers for prototypes. When debugging runtime failures from assertions, source-map-aware tools and the techniques covered in Debugging TypeScript Code (Source Maps Revisited) will help map exceptions back to TS sources. Finally, integrate assertion functions with your test suites; assertors are small functions with high coverage value and they often surface edge cases before they reach production.
Best Practices & Common Pitfalls
Do:
- Keep assertion functions small and single-responsibility.
- Provide clear, actionable error messages including key context.
- Test assertion functions thoroughly, including edge cases.
- Use assertions at boundaries where untrusted data enters your system.
Don't:
- Overuse assertions to patch weak typings inside large internal modules; prefer correct typing when possible.
- Rely on assertion functions to replace full schema validation in hostile environments—use dedicated validators for public APIs.
- Expect assertions to run at compile time; they are runtime checks that inform compile-time narrowing.
Common pitfalls:
- Forgetting that narrowing only applies in control-flow paths after the assertion call. For example, if you throw and catch within the same block, type narrowing may not persist where you expect.
- Using assertions in expressions that the compiler cannot connect to the narrowed variable (e.g., asserting properties of a different binding or lost reference). Ensure you assert the same variable name the compiler tracks.
- Arrow functions cannot declare
thisparameters, sothisassertions need to be declared on functions or methods that have an explicitthistype.
When in doubt, read small examples and inspect TypeScript's diagnostics—this often clarifies where narrowing is applied.
Real-World Applications
Assertion functions shine in these scenarios:
- API clients: validate HTTP responses before passing data into domain logic.
- Library boundaries: wrap untyped third-party outputs into typed shapes as a trust boundary.
- UI code: assert DOM queries and event targets to simplify component logic; for deeper DOM patterns, consult Typing DOM Elements and Events in TypeScript (Advanced).
- CLI tools and scripts: assert process input and environment variables early in startup to fail fast.
- Stream processing: validate chunks or items produced from async iterators, integrating techniques from Typing Async Iterators and Async Iterables in TypeScript — Practical Guide.
In many systems you will combine assertion functions with configuration-driven validators, caching validated items, and using assertion functions sparingly in performance hot paths while still keeping reliable guarantees.
Conclusion & Next Steps
Assertion functions are a compact, pragmatic tool to bridge runtime validation and TypeScript's static type system. Use them at trust boundaries, compose them for complex shapes, and prefer small, well-tested assertors over ad-hoc casts. Next, deepen your skillset by looking at patterns for variadic parameter typing and this transformations—two areas that frequently pair with assertions. Consider adding a thin validation layer at your API boundaries and include assertion function tests in your CI pipeline to keep guarantees stable.
Recommended reading: our guides on Typing Functions That Accept a Variable Number of Arguments (Tuples and Rest), Typing Functions That Modify this (ThisParameterType, OmitThisParameter), and Typing Third-Party Libraries with Complex APIs — A Practical Guide.
Enhanced FAQ
Q1: When should I use an assertion function instead of a type predicate that returns boolean?
A1: Use assertion functions when you want to throw on invalid input and have the compiler treat the code after the call as narrowed without an additional if branch. Type predicates that return boolean are better when you want conditional code paths without exceptions or when you prefer functional-style checks that can be composed in expressions. Assertion functions are ideal at boundaries where failure should be fatal or handled by a higher-level error handler.
Q2: Can assertion functions be used for narrowing class fields inside constructors?
A2: Yes. They are commonly used in constructors to validate inputs and ensure this invariants. A pattern is to call assertion helpers early in the constructor to guarantee fields are initialized with valid values. For constructor typing strategies and patterns, see Typing Class Constructors in TypeScript — A Comprehensive Guide.
Q3: Do assertion functions affect runtime performance?
A3: Assertion functions perform runtime checks you write, so they cost what your code costs. The TypeScript compiler erases the asserts annotation, leaving only your runtime checks. In tight loops or hot paths, avoid repeated heavy validations—validate once and assume trust afterward. Also, consider optional checks in development builds and stripped checks in production if performance is critical, but only with caution.
Q4: Can I assert that a value is a specific tuple or variadic shape?
A4: Yes. You can write assertion functions that validate arrays and their element types, and then annotate the return type as asserts value is [A,B?,C?] or similar. This pairs nicely with variadic tuple patterns covered in Typing Functions That Accept a Variable Number of Arguments (Tuples and Rest). Careful ordering of checks and precise error messages help debugging.
Q5: How do this assertions work and when are they useful?
A5: Declare asserts this is T on a method or function with an explicit this parameter. After calling the method, the compiler treats the surrounding this as T for the remainder of the control flow. This is useful in prototypes and classes where an operation ensures the object reaches a certain state. For deeper patterns, read Typing Functions That Modify this (ThisParameterType, OmitThisParameter).
Q6: How do assertion functions interact with try/catch control flow?
A6: If an assertion function throws and you catch that error, the compiler cannot assume the assertion succeeded in the catch branch. Narrowing only applies to code paths that occur after a successful, non-throwing call. If you catch and continue, the variable remains in its original type for the compiler unless you restructure control flow to call assertions in places that guarantee success.
Q7: Are assertion functions suitable as a full validation library replacement?
A7: Not always. For complex, hostile inputs (user uploads, public APIs), a dedicated validation library that provides schema generation, detailed errors, and performance optimizations may be more appropriate. Assertion functions are lightweight and best used where you want a simple, tested contract at boundaries. For richer schema needs, combine assertion functions with validated schemas or consider runtime validators.
Q8: How should I test assertion functions?
A8: Test both success cases and all meaningful failure modes. For each assertion function, include unit tests that pass valid inputs and assert no throw, and tests that pass invalid inputs and assert the specific error message or type is thrown. Because assertions are small and centralized, their tests pay off by preventing subtle downstream typing bugs.
Q9: Can I assert results from iterators and async iterators?
A9: Yes—call assertion functions inside your iterator consumer or inside an async loop. For patterns and typing async flows, see Typing Async Iterators and Async Iterables in TypeScript — Practical Guide. This is useful when consuming streaming data where each chunk must be validated before processing.
Q10: Any debugging tips when an assertion doesn't narrow as expected?
A10: Ensure the assertion call is on the exact variable the compiler tracks. Avoid aliasing the variable before asserting. Check that your TypeScript strict options are enabled—some narrowing behaviors depend on stricter flags. If narrowing still fails, create a minimal reproduction; it's often a subtle control-flow shape, and tools from Debugging TypeScript Code (Source Maps Revisited) can help find where runtime and compile-time behavior diverge.
If you want hands-on examples, try converting a few small validation blocks in your codebase into assertion functions and add tests around them. For adjacent concepts like variadic typing, this patterns, or DOM typings, see the linked guides throughout this article to expand your TypeScript toolbox.