Assertion function
- TypeScript course
- Advanced
- Lesson 38/57
- 4 min
Learn assertion functions with asserts.
Assertion function
An assertion function uses a return type of the form asserts x is T. When the function completes normally, TypeScript narrows the parameter to type T; if the condition fails, the function throws. While a type guard returns true/false, an assertion function either narrows or throws.
function assertString(x: unknown): asserts x is string {
if (typeof x !== "string") {
throw new Error("Expected string");
}
}
function upper(v: unknown): string {
assertString(v);
return v.toUpperCase(); // v: string
}Assert vs is
A type guard with is is a function returning true/false and narrows in an if condition. An assertion function with asserts narrows by completing or throwing; no if needed. Assert is useful when you want to stop execution on error.
// type guard
function isString(x: unknown): x is string {
return typeof x === "string";
}
// assertion function
function assertString(x: unknown): asserts x is string {
if (typeof x !== "string") throw new Error("not string");
}
function upper(v: unknown): string {
assertString(v); // next line: v is string
return v.toUpperCase();
}Practice Handle unknown with assertString
Define an assertString(x: unknown): asserts x is string function (with throw new Error("not string") when typeof x !== "string"). Write an upper(v: unknown): string function: first call assertString(v), then return v.toUpperCase(). Print the result via console.log(upper("hello")).
Starter code
// assertString fonksiyonunu tanımla (asserts x is string, throw içersin)
// upper(v: unknown): string fonksiyonunu assertString ile yaz
// upper("hello") sonucunu yazdırSample solution
function assertString(x: unknown): asserts x is string {
if (typeof x !== "string") {
throw new Error("not string");
}
}
function upper(v: unknown): string {
assertString(v);
return v.toUpperCase();
}
console.log(upper("hello"));Expected output
HELLO
Questions and answers
Review the lesson questions together with their answers. To test yourself, solve the lesson interactively.
1 How does a return type of asserts x is T behave?
- It auto-generates the T type
- The function returns true/false
- It does nothing at runtime
- When the function completes it narrows x to T; otherwise a throw is expected Correct answer
Explanation: The asserts x is T return type narrows x to T when the function completes normally; if it throws, the flow stops and no narrowing happens. No if condition is needed.
2 Assertion with asserts
function assertString(x: unknown): ____ {
if (typeof x !== "string") throw new Error("not string");
}function assertString(x: unknown): asserts x is string {
if (typeof x !== "string") throw new Error("not string");
}Explanation: The asserts x is string return type tells TypeScript that x is a string when the function completes; if it throws, no narrowing happens.
3 Assertion function parts
| Term | Meaning |
|---|---|
asserts x is T |
assertion function return type |
assertString(v) |
narrows v to string if completes |
throw new Error |
when condition fails |
is ile type guard |
returns true/false |