TypeScript: TypeScript Type Assertions

Q: What is the difference between as const and readonly ?

readonly marks a single property as read-only. as const makes the entire object or array—at all levels—a literal type with readonly . const x = { a: 1 } as const is more concise than let x: { readonly a: 1 } and provides deep read-only protection.

Last updated: 2026-08-26

A type assertion tells the compiler, "I know the type of this value better than you do"—it does not change the runtime type, but only affects type checking at compile time.

1. Basics of Type Assertions

(1) Two Syntaxes

TYPESCRIPT

// as Grammar（Recommendations，JSX "Must" must be used in）
let value: any = "hello";
let length1: number = (value as string).length;

// Angle Bracket Syntax（Cannot be in JSX Used in）
let length2: number = (<string>value).length;

📌 Recommendation: Use the as syntax consistently. Bracket syntax conflicts with component tags in JSX/TSX, so as is a more universal choice.

(2) The Purpose of Assertions

Type "narrowing" or "broadening" assertions—tell TypeScript to treat a value as another compatible type:

TYPESCRIPT

// Narrow：From broad types to narrow types（Common）
let value: string | number = "hello";
let str = value as string;       // Tell the compiler"I'm sure this is string"
console.log(str.toUpperCase());  // ✅

// Broadening：From Narrow Types to Wide Types（Less commonly used）
let name = "Charlie" as string;    // "Charlie" Type from literal "Charlie" Generalize to string

(3) Assertions Do Not Change Runtime Types

TYPESCRIPT

let value: any = 42;
let str = value as string;       // The compile-time type is string
console.log(typeof str);         // "number" —— At runtime, it is still number！
// console.log(str.toUpperCase()); // Runtime Crash！number None toUpperCase

🔥 Core Principle: Type assertions do not perform any runtime conversions. They are merely type annotations at compile time. If an assertion fails, an error will still occur at runtime.

2. Common Assertion Scenarios

(1) DOM Element Types

TYPESCRIPT

// getElementById Back HTMLElement | null
let input = document.getElementById("myInput") as HTMLInputElement;
// After the assertion, you can use it directly. HTMLInputElement Properties of
console.log(input.value);        // ✅
console.log(input.placeholder);  // ✅

// A Safer Way to Write It——Check first null
let inputEl = document.getElementById("myInput");
if (inputEl instanceof HTMLInputElement) {
  console.log(inputEl.value);    // ✅ instanceof narrow，No assertion required
}

(2) API Response Types

TYPESCRIPT

interface User {
  id: number;
  name: string;
  email: string;
}

// JSON.parse Back any——Specify the type using an assertion
let response = JSON.parse('{"id":1,"name":"Charlie","email":"xiao@example.com"}') as User;
console.log(response.name);  // ✅ Type: string

// A Safer Way to Write It——Runtime Validation (See Lesson 26)
function isUser(obj: any): obj is User {
  return typeof obj.id === "number"
    && typeof obj.name === "string"
    && typeof obj.email === "string";
}

let data = JSON.parse('...');
if (isUser(data)) {
  console.log(data.name);  // ✅ Type Guard Narrowing，Safer than assertions
}

(3) Bypassing Unnecessary Attribute Checks

TYPESCRIPT

interface Config {
  host: string;
  port: number;
}

// Direct Assignment——Check for Unnecessary Attributes
// let cfg: Config = { host: "localhost", port: 3000, debug: true };  // ❌

// Method 1：Type Assertion Bypass
let cfg = { host: "localhost", port: 3000, debug: true } as Config;  // ✅

// Method 2：Assign a value to the variable first, then pass it（Using Structured Type Compatibility）
let options = { host: "localhost", port: 3000, debug: true };
let cfg2: Config = options;  // ✅ Variable assignments do not perform unnecessary property checks

▶ Example: Handling assertions for composite types

Output:

TEXT 📖 Display only

19
19

TYPESCRIPT

type SuccessResponse = {
  status: "success";
  data: { id: number; name: string };
};

type ErrorResponse = {
  status: "error";
  error: { code: number; message: string };
};

type ApiResponse = SuccessResponse | ErrorResponse;

function handleResponse(response: ApiResponse) {
  if (response.status === "success") {
    // Type Narrowing（Recommendations）
    console.log(response.data.name);
  } else {
    // Type Narrowing（Recommendations）
    console.log(response.error.message);
  }

  // Not recommended——Replace Narrowing with Assertions
  // let data = (response as SuccessResponse).data;  // Danger！
}

Output:

TEXT 📖 Display only

19
19

3. the const assertions

as const Have TypeScript infer the most precise literal type for a value + readonly:

(1) Basic Usage

TYPESCRIPT

// None as const——widening Inference
let obj = { host: "localhost", port: 3000 };
// Type：{ host: string; port: number }
obj.host = "other";  // ✅ Can be modified

// With as const — exact literals + readonly
let config = { host: "localhost", port: 3000 } as const;
// Type：{ readonly host: "localhost"; readonly port: 3000 }
// config.host = "other";  // ❌ readonly
// config.port = 8080;     // ❌ readonly

(2) `as const` for arrays

TYPESCRIPT

// Regular Arrays
let arr = [1, 2, 3];
// Type：number[]

// as const Array——become readonly Tuple
let tuple = [1, 2, 3] as const;
// Type：readonly [1, 2, 3]
// tuple[0] = 10;  // ❌ readonly
// tuple.push(4);  // ❌ readonly

(3) Practical Uses of `as const`—Defining Constants and Action Types

TYPESCRIPT

// Redux Stylistic action Type Definitions
const INCREMENT = "INCREMENT" as const;
const DECREMENT = "DECREMENT" as const;

// None as const → INCREMENT The type is string（Too wide）
// With as const → INCREMENT typee is "INCREMENT"（Exact Literals）

type Action = {
  type: typeof INCREMENT;
  payload: number;
} | {
  type: typeof DECREMENT;
  payload: number;
};

function reducer(state: number, action: Action): number {
  switch (action.type) {
    case "INCREMENT": return state + action.payload;
    case "DECREMENT": return state - action.payload;
  }
}

4. Not-empty assertion `!`

A non-null assertion tells TypeScript, "I'm certain this value is not null or undefined":

(1) Basic Usage

TYPESCRIPT

let value: string | null = "hello";

// Non-empty assertion——Tell the compiler"The value is not null"
console.log(value!.toUpperCase());  // ✅ Compilation successful

// Equivalent to asserting that
console.log((value as string).toUpperCase());

(2) Common Scenarios

TYPESCRIPT

// DOM Element
let el = document.getElementById("app");
el!.innerHTML = "Hello";  // Use ! to assert non-null

// Assignment After the Optional Chain
let user: { name?: string } = { name: "Charlie" };
let nameLength = user.name!.length;  // Assertion name No undefined

// Function Arguments
function process(value: string | undefined) {
  // We"Know"When called value It can't be... undefined
  console.log(value!.toUpperCase());
}

(3) Risks Associated with Non-empty Assertions

TYPESCRIPT

let value: string | null = null;

// Compilation successful！But it crashes during runtime——value Actually, it is null
// console.log(value!.toUpperCase());  // Runtime Error：Cannot read property of null

// ✅ A Safer Way to Write It——Check first
if (value !== null) {
  console.log(value.toUpperCase());  // Type Narrowing，Compilation+All operations are safe
}

💡 Recommendation: Non-null assertions should be a last resort. Whenever possible, use if for checks or ?. for optional chaining—these are safer alternatives. Use ! only when you are 100% certain the value is not null but the compiler cannot infer this.

5. Double Assertions and Assertion Restrictions

(1) Limitations of Assertions

TypeScript does not allow completely unrelated type assertions:

TYPESCRIPT

let value: string = "hello";

// ✅ string → string | number（From subtype to supertype，Compatibility）
let wide = value as string | number;

// ✅ string | number → string（From Parent Type to Child Type，May not be safe, but allowed）
let narrow = wide as string;

// ❌ string → number（Completely unrelated，Not allowed）
// let num = value as number;

(2) Double Assertion (Bypasses restrictions; highly discouraged)

TYPESCRIPT

let value: string = "hello";

// Through any Transit——Double Assertion
let num = value as unknown as number;  // Compilation successful！

// But at runtime value It's still string
console.log(typeof num);  // "string"
// num.toFixed(2);         // Runtime Crash！

⚠️ Warning: Double assertions (as unknown as T) completely bypass type safety checks. It’s equivalent to telling the compiler, “Never mind, I’ll take full responsibility”—which is incorrect in 99% of cases. If you find yourself needing to use double assertions, it’s highly likely that there’s a problem with your code design, and you should rethink your type structure.**

6. Best Practices for Assertions

(1) Priority Ordering

TEXT 📖 Display only

Type Narrowing（if/typeof/instanceof/in）  → Safest，Use as a priority
Type Guard（Custom is Function）           → Safety，Collapse Complex Types
Non-empty assertion !                          → Use with caution，When it is determined that the value is not empty
as Assertion                             → Use less，When there is a clear reason
as const                            → Recommended for constant definitions
Double Assertion as unknown as T            → Highly not recommended，99%This is incorrect usage.

(2) Assertion Safety Checklist

Before writing a as assertion, ask yourself three questions:

Can I use type narrowing instead? (if/typeof/instanceof)
Can I switch to optional chaining? (?.)
If an assertion fails, will the program crash at runtime?

If your answer to Question 3 is "Yes," consider a safer method.

▶ Example: Comparison of Safe vs. Unsafe Assertions

Output:

TEXT 📖 Display only

19
19

TYPESCRIPT

interface User {
  id: number;
  name: string;
  email: string;
}

// ❌ Unsafe——Blind assertions API Response
function fetchUser1(id: number): User {
  let data = JSON.parse(localStorage.getItem(`user:${id}`) ?? "{}") as User;
  return data;  // data May not match User Structure
}

// ✅ Safety——Runtime Validation + Type Guard
function isUser(obj: any): obj is User {
  return obj
    && typeof obj.id === "number"
    && typeof obj.name === "string"
    && typeof obj.email === "string";
}

function fetchUser2(id: number): User | null {
  let raw = localStorage.getItem(`user:${id}`);
  if (!raw) return null;

  let data = JSON.parse(raw);
  if (isUser(data)) {
    return data;  // ✅ Type Guard: Return safely after confirmation
  }
  return null;
}

Output:

TEXT 📖 Display only

No runtime output — demonstrates safe vs unsafe assertion patterns

▶ Example: as Syntax vs Angle-Bracket Syntax

Output:

TEXT 📖 Display only

19
19

TYPESCRIPT

let value: unknown = "Hello, TypeScript!";

// as syntax (recommended — works in JSX/TSX)
let len1: number = (value as string).length;

// Angle-bracket syntax (cannot be used in JSX)
let len2: number = (<string>value).length;

console.log(len1);  // 19
console.log(len2);  // 19

// Both produce identical runtime code —
// the choice is purely about JSX compatibility

Output:

TEXT 📖 Display only

19
19

❓ FAQ

Q What is the difference between a type assertion and a type conversion?

A A type assertion only affects type checking at compile time and does not change the value at runtime—x as string does not turn x into a string. A type conversion changes the type of a value at runtime—String(42) actually turns 42 into "42". TypeScript’s as is an assertion, not a conversion.

Q What is the difference between as const and readonly?

A readonly marks a single property as read-only. as const makes the entire object or array—at all levels—a literal type with readonly. const x = { a: 1 } as const is more concise than let x: { readonly a: 1 } and provides deep read-only protection.

Q When is it appropriate to use the non-empty assertion !?

A The most appropriate scenario is DOM manipulation—when you’re certain a particular element exists in the HTML but TypeScript cannot verify it. document.getElementById("app")!.innerHTML = "Hi" It’s appropriate when the page structure is known. In other scenarios, use an if statement for checking instead.

Q What are some legitimate uses for as unknown as T (double assertions)?

A Very few. The only reasonable scenario is when the type system truly cannot express the intended behavior (such as in certain complex generic operations or when third-party library type definitions contain bugs). However, 99% of double assertions can be avoided by redesigning the type structure.

📖 Summary

A type assertion as T tells the compiler to "treat the value as type T"—it takes effect at compile time and has no impact at runtime.
Common scenarios: DOM element types, API response types, bypassing unnecessary attribute checks
as const Inference of values as exact literals + readonly—recommended for constant definitions
Non-null assertion !: The assertion value is not null or undefined—use with caution; prioritize if checks
Double Assertion as unknown as T Completely bypasses type safety—highly discouraged
Use type narrowing > type guards > non-null assertions > as assertions in that order

📝 Exercises

Basic Problem (Difficulty ⭐): Use as const to define a direction constant DIRECTIONS = ["north", "south", "east", "west"] as const, then write a function that accepts a parameter of type typeof DIRECTIONS[number] to verify that only four direction values are valid.
Advanced Problem (Difficulty ⭐⭐): Write a function querySelector<T extends HTMLElement>(selector: string): T | null that uses document.querySelector(selector) as T | null internally. Then create a call that locates the input element and accesses the value property using a non-null assertion. Write a safer version that uses an if statement instead of the non-null assertion.
Challenge (Difficulty: ⭐⭐⭐): Implement a runtime type verification function validate<T>(schema: Schema, value: unknown): value is T that uses simple schema objects to describe verification rules (such as { name: "string", age: "number" }) and checks at runtime whether an unknown value matches; if it does, the type guard is narrowed to T. Compare this to as T and explain where the safety lies.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us

TypeScript: TypeScript Type Assertions

1. Basics of Type Assertions

(1) Two Syntaxes

(2) The Purpose of Assertions

(3) Assertions Do Not Change Runtime Types

2. Common Assertion Scenarios

(1) DOM Element Types

(2) API Response Types

(3) Bypassing Unnecessary Attribute Checks

▶ Example: Handling assertions for composite types

3. the const assertions

(1) Basic Usage

(2) as const for arrays

(3) Practical Uses of as const—Defining Constants and Action Types

4. Not-empty assertion !

(1) Basic Usage

(2) Common Scenarios

(3) Risks Associated with Non-empty Assertions

5. Double Assertions and Assertion Restrictions

(1) Limitations of Assertions

(2) Double Assertion (Bypasses restrictions; highly discouraged)

6. Best Practices for Assertions

(1) Priority Ordering

(2) Assertion Safety Checklist

▶ Example: Comparison of Safe vs. Unsafe Assertions

▶ Example: as Syntax vs Angle-Bracket Syntax

❓ FAQ

📖 Summary

📝 Exercises

🙏 帮我们做得更好

(2) `as const` for arrays

(3) Practical Uses of `as const`—Defining Constants and Action Types

4. Not-empty assertion `!`