`instanceof guard` în TypeScript

x instanceof Clasa verifică dacă obiectul a fost creat din clasă și restrânge tipul la acea clasă.

Sintaxă

if (x instanceof Clasa) { /* x este Clasa */ }

Ce face `instanceof guard`

instanceof verifică la rulare dacă un obiect a fost creat cu new dintr-o anumită clasă (sau dintr-o clasă derivată). TypeScript folosește rezultatul: în ramura adevărată, variabila are tipul clasei. Funcționează cu clasele tale și cu cele predefinite: Date, Error, Map, RegExp, HTMLElement.

Cel mai des îl vei folosi în catch, unde eroarea are tipul unknown: if (e instanceof Error) îți dă acces la e.message. Pentru erori proprii, creezi clase care extind Error și le deosebești cu instanceof.

instanceof nu funcționează cu interfețe sau aliasuri de tip, pentru că acestea nu există la rulare. Nici cu obiecte literale ({ ... }), care nu au fost create dintr-o clasă; pentru ele folosește in sau un predicat.

Exemple

Exemplul 1: Erori proprii deosebite cu instanceof

class EroareValidare extends Error {
    constructor(public camp: string, mesaj: string) {
        super(mesaj);
    }
}
class EroareRetea extends Error {
    constructor(public cod: number) {
        super(`Server indisponibil (${cod})`);
    }
}

function proceseaza(pas: number): void {
    if (pas === 1) throw new EroareValidare("email", "Adresa nu are @");
    if (pas === 2) throw new EroareRetea(503);
    throw "ceva neprevăzut";
}

for (const pas of [1, 2, 3]) {
    try {
        proceseaza(pas);
    } catch (e) {
        if (e instanceof EroareValidare) console.log(`Câmpul ${e.camp}: ${e.message}`);
        else if (e instanceof EroareRetea) console.log(`Cod ${e.cod}, reîncearcă`);
        else console.log("Necunoscut:", e);
    }
}

Rezultat

Câmpul email: Adresa nu are @
Cod 503, reîncearcă
Necunoscut: ceva neprevăzut

Exemplul 2: Date sau text

function zi(x: Date | string): string {
    const d = x instanceof Date ? x : new Date(x);
    return d.toLocaleDateString("ro-RO", { timeZone: "UTC", day: "numeric", month: "long", year: "numeric" });
}

console.log(zi(new Date(Date.UTC(2026, 11, 1))));
console.log(zi("2026-10-19"));

Rezultat

1 decembrie 2026
19 octombrie 2026

Exemplul 3: instanceof cu o interfață

interface Elev {
    nume: string;
}
function f(x: Elev | string) {
    if (x instanceof Elev) console.log("este elev");
}
f("Ana");

Eroarea afișată de tsc

exemplu.mts(5,22): error TS2693: 'Elev' only refers to a type, but is being used as a value here.

Greșeli frecvente

Te aștepți ca un obiect primit ca JSON să fie instanceof clasa ta. După JSON.parse ai obiecte simple; trebuie create explicit cu new.
Verifici clasa de bază înaintea celei derivate într-un șir de if. Prima verificare prinde și derivatele; pune clasele specifice primele.

Comenzi înrudite

type guards: Verificări la rulare pe care TypeScript le înțelege și după care știe tipul exact al unei valori.
typeof guard: Verificarea typeof x === „string” (sau „number”, „boolean”…) restrânge tipul la primitivul respectiv.
in guard: „cheie” in x verifică dacă obiectul are proprietatea și restrânge union-ul la variantele care o au.
class: Clasele din JavaScript, cu tipuri pe câmpuri, constructor și metode, plus modificatori de acces și interfețe.
extends: O clasă moștenește câmpurile și metodele altei clase; o interfață preia proprietățile altor interfețe.

Ce face instanceof guard