Runtime Interface Type Checks in TypeScript: Why `instanceof` Does Not Work

By the end of this page, you will understand why TypeScript interfaces disappear at runtime, why instanceof only works with classes and constructor functions, and how to perform safe runtime checks using type guards, property checks, and validation functions.

TypeScript has two worlds:

• Type world: used by the compiler for checking your code
• Runtime world: actual JavaScript values that exist when the program runs

An interface belongs only to the type world. It helps TypeScript verify that an object has the required shape during development, but it does not generate JavaScript code.

That is why this does not work:

interface A {
  member: string;
}

const a: any = { member: "foobar" };

// Error: A is not a runtime value
if (a instanceof A) {
  console.log(a.member);
}

instanceof is a runtime operator. It checks whether an object was created by a specific constructor function or class.

For example, this works because User exists at runtime:

class User {
  constructor(public member: ) {}
}

 u =  ();

.(u  ); 

Think of a TypeScript interface like a blueprint drawn on paper.

• While designing the program, the blueprint is useful.
• Once the building is finished, the blueprint is not part of the building.

At runtime, JavaScript only sees the finished building—the actual objects.

So if you ask JavaScript, "Was this object built from interface A?", it cannot answer, because the interface blueprint is gone.

A class is different. A class is more like a factory machine that still exists at runtime. That is why JavaScript can ask:

• "Was this object created by this factory?" → instanceof

For interfaces, you instead ask:

• "Does this object have the properties I expect?"

Core idea

Use a type guard function to check whether a value matches the structure of an interface.

Interface

interface A {
  member: string;
}

Type guard

function isA(value: any): value is A {
  return (
    value !== null &&
    typeof value === "object" &&
    typeof value.member === "string"
  );
}

Usage

const a: any = { member: "foobar" };

if (isA(a)) {
  console.log(a.member); // TypeScript now knows a is A
} else {
  console.log("Not an A");
}

Why works for classes only

Consider this code:

interface A {
  member: string;
}

function isA(value: unknown): value is A {
  return (
    typeof value === "object" &&
    value !== null &&
    "member" in value &&
    typeof (value as { member: unknown }).member === "string"
  );
}

const input: unknown = { member: "hello" };

if (isA(input)) {
  console.log(input.member);
}

Step-by-step

1. interface A defines the expected shape:

   • there must be a member
   • member must be a string

2. input is declared as .

Runtime shape checks are common whenever data comes from outside your program.

API responses

interface UserDto {
  id: number;
  name: string;
}

When you fetch JSON from an API, TypeScript cannot guarantee the server sent the correct shape. A runtime guard can verify it before use.

Local storage or session storage

Data read from storage may be missing fields, have old formats, or contain corrupted values.

Form input processing

User input is unpredictable. You may need to confirm that an object contains the required fields before processing it.

Parsing JSON

const parsed: unknown = JSON.parse(text);

After parsing, runtime validation is often necessary before treating the data as a known interface.

Plugin systems or configuration files

Apps often load configuration from external files. Checking shape at runtime helps prevent crashes.

Message passing

In frontend apps, workers, browser events, or postMessage payloads may need runtime validation before use.

In real projects, developers rarely check interfaces directly. Instead, they use a few common patterns.

1. Type guard functions

This is the most common pattern for lightweight validation.

function isA(value: unknown): value is A {
  return (
    typeof value === "object" &&
    value !== null &&
    "member" in value &&
    typeof (value as { member: unknown }).member === "string"
  );
}

2. Guard clauses

Validate early and return quickly.

function printMember(value: unknown) {
  if (!isA(value)) {
    throw new Error("Expected A");
  }

  console.log(value.member);
}

This keeps the rest of the function simple.

3. Validation at application boundaries

1. Trying to use instanceof with an interface

Broken code:

interface A {
  member: string;
}

const a: any = { member: "x" };

if (a instanceof A) {
  console.log(a.member);
}

Why it fails:

• A is not a runtime value
• interfaces are removed during compilation

Fix:

function isA(value: unknown): value is A {
  return (
    typeof value === "object" &&
    value !== null &&
    "member" in value &&
    typeof (value as { member: unknown }).member === "string"
  );
}

2. Confusing with runtime checking

Key rules

• Interfaces are compile-time only in TypeScript.
• Interfaces do not exist in generated JavaScript.
• instanceof works with classes, not interfaces.
• implements is used by classes to satisfy an interface at compile time.
• For runtime interface-like checks, use a type guard.

Basic pattern

interface A {
  member: string;
}

function isA(value: unknown): value is A {
  return (
    typeof value === "object" &&
    value !== null &&
    "member" in value &&
    typeof (value as { member: unknown }).member === "string"
  );
}

Use it like this

const value: unknown = { member: "hello" };

if ((value)) {
  .(value.);
}

Why does TypeScript say an interface does not exist in the current scope?

Because instanceof expects a runtime value, such as a class or constructor function. An interface is only a compile-time type, so it is not available as a JavaScript value.

Can I use instanceof with an interface in TypeScript?

No. instanceof only works with classes, constructor functions, and objects that exist at runtime.

How do I check whether an object matches an interface?

Write a type guard function that checks the required properties and their types.

Does implements perform runtime checking?

No. implements only tells the TypeScript compiler to verify that a class matches an interface.

Is value as MyInterface a runtime check?

No. A type assertion only changes what TypeScript assumes. It does not inspect the actual data.

Should I use any or unknown for incoming data?

Prefer unknown. It forces you to validate the value before using it.

What should I use for API response validation?

For simple cases, write a type guard. For larger or nested data, use a dedicated validation approach or schema library.

• Type guards — The main TypeScript feature used to narrow unknown values after runtime checks.
• Interfaces — Central to understanding compile-time shape checking in TypeScript.
• Classes — Important because instanceof works with classes but not interfaces.
• instanceof operator — Useful for runtime checks against class constructors.
• implements keyword — Often confused with runtime interface checking, but it is compile-time only.
• unknown vs any — Highly relevant when validating untrusted data safely.
• Type assertions — Related because many beginners confuse assertions with validation.
• Structural typing — Explains why TypeScript cares about object shape rather than explicit interface inheritance.