TypeScript Try Catch: Hata Tipleri ve Özel Hatalar

TypeScript, JavaScript'in try, catch, finally ve throw yapılarını kullanır. TypeScript'e özgü kısım catch değişkenidir: strict açıkken tipi unknown'dır, bu yüzden kullanmadan önce neyin fırlatıldığını kontrol edersiniz.

function parsePort(text: string): number {
    const port = Number(text);
    if (!Number.isInteger(port) || port < 1 || port > 65535) {
        throw new RangeError(`invalid port: "${text}"`);
    }
    return port;
}

try {
    console.log(parsePort("8080")); // 8080
    console.log(parsePort("http")); // throws
} catch (e) {
    // e: unknown
    if (e instanceof Error) {
        console.log(`${e.name}: ${e.message}`); // RangeError: invalid port: "http"
    }
} finally {
    console.log("done");
}

Çalışma zamanı tarafı (stack'in nasıl çözüldüğü, hangi yerleşik hata tiplerinin olduğu) JavaScript try/catch sayfasında anlatılır.

catch Değişkeni Neden unknown

JavaScript her şeyi fırlatabilir: bir Error, bir string, bir number, undefined, bir kütüphaneden gelen bir nesne. TypeScript hangisi olduğunu bilemez, bu yüzden strict altında (useUnknownInCatchVariables bayrağı) değişken unknown'dır ve kullanmadan önce onu daraltmanız gerekir:

// This does not compile: e is unknown, so e.message is not allowed.
try {
    JSON.parse("{ broken");
} catch (e) {
    console.log("parse failed:", e.message);
}

index.ts(5,34): error TS18046: 'e' is of type 'unknown'.

strict olmadan e, any olur ve aynı kod derlenir, sonra bir string fırlatıldığında çalışma zamanında bozulur: e.message değeri undefined olur ve e.message.length gibi daha derine inen her şey bir TypeError fırlatır. İşaretlemeyle de kurtulamazsınız: catch (e: Error) yazmak TS1196 hatasıdır (Catch clause variable type annotation must be 'any' or 'unknown' if specified).

Hatayı Daraltmak

instanceof Error, TypeError, SyntaxError, RangeError ve kendi alt class'larınız dahil Error üzerine kurulu her şeyi kapsar. Geri kalan her şey için değeri string'e çevirmeye başvurun. Küçük bir yardımcı fonksiyon çağrı yerlerini kısa tutar:

function toError(value: unknown): Error {
    if (value instanceof Error) return value;
    if (typeof value === "string") return new Error(value);
    return new Error(`non-error thrown: ${JSON.stringify(value)}`);
}

const throwers: Array<() => void> = [
    () => JSON.parse("{"),
    () => { throw "plain string"; },
    () => { throw { code: 42 }; },
];

for (const run of throwers) {
    try {
        run();
    } catch (e) {
        const err = toError(e);
        console.log(err.constructor.name, "|", err.message);
    }
}
// SyntaxError | Expected property name or '}' in JSON at position 1 (line 1 column 2)
// Error | plain string
// Error | non-error thrown: {"code":42}

Yalnızca bazı hataları ele alan bir catch, geri kalanını yeniden fırlatmalıdır: if (!(e instanceof ValidationError)) throw e;. Bilinmeyen hataları yutmak gerçek bug'ları gizler.

Hata Fırlatmak

throw her ifadeyi kabul eder ve TypeScript bunu kısıtlamaz. Yine de Error nesneleri fırlatın: bir stack trace taşırlar ve kod tabanındaki her instanceof Error kontrolü buna dayanır.

Her zaman hata fırlatan bir fonksiyonun dönüş tipi never'dır ve TypeScript bunu çağrıdan sonraki daraltma için kullanır:

function fail(message: string): never {
    throw new Error(message);
}

function getEnv(env: Record<string, string | undefined>, key: string): string {
    const value = env[key];
    if (value === undefined) fail(`missing ${key}`);
    return value; // value: string, because fail() never returns
}

const env = { HOME: "/home/ada" };
console.log(getEnv(env, "HOME")); // /home/ada
try {
    getEnv(env, "PORT");
} catch (e) {
    if (e instanceof Error) console.log(e.message); // missing PORT
}

ES2022'den beri Error, cause içeren ikinci bir argüman alır; bu, alt seviyedeki bir hatayı sizin fırlattığınız hataya bağlar: throw new Error("could not load settings", { cause: e }). Çağıran err.cause değerini okuyabilir (tipi unknown).

Özel Hata Class'ları

Error'ın bir alt class'ı, çağıranların hataları instanceof ile ayırt etmesini ve ek veri taşımasını sağlar. name değerini ayarlayın, çünkü miras alınan değer "Error"'dır ve loglarda ve String(err) çıktısında görünür:

class HttpError extends Error {
    override name = "HttpError";

    constructor(readonly status: number, message: string, options?: ErrorOptions) {
        super(message, options);
    }
}

class NotFoundError extends HttpError {
    override name = "NotFoundError";

    constructor(resource: string) {
        super(404, `${resource} not found`);
    }
}

function handle(e: unknown): string {
    if (e instanceof NotFoundError) return `404 page for: ${e.message}`;
    if (e instanceof HttpError) return `HTTP ${e.status}: ${e.message}`;
    if (e instanceof Error) return `unexpected: ${e.message}`;
    return "unknown failure";
}

console.log(handle(new NotFoundError("user 7"))); // 404 page for: user 7 not found
console.log(handle(new HttpError(503, "maintenance"))); // HTTP 503: maintenance
console.log(handle(new TypeError("oops")));        // unexpected: oops

const wrapped = new HttpError(500, "db down", { cause: new Error("timeout") });
const cause = wrapped.cause; // unknown
console.log(String(wrapped), "| cause:", cause instanceof Error ? cause.message : cause);
// HttpError: db down | cause: timeout

Önce en özel class'ı kontrol edin, çünkü bir NotFoundError aynı zamanda bir HttpError'dır. noImplicitOverride açık değilse override belirteci burada isteğe bağlıdır.

Eski rehberler her hata constructor'ına Object.setPrototypeOf(this, new.target.prototype) ekler. Bu, class'lar ES5 fonksiyonlarına derlendiği ve Error alt class'larında instanceof bozulduğu dönemde gerekliydi. TypeScript 7 artık target: "es5" değerini desteklemez (TS5108: Option 'target=ES5' has been removed bildirir) ve ES2015 ya da sonrasıyla yukarıdaki gibi yerel class ... extends Error çalışır.

Result Kalıbı

TypeScript bir fonksiyonun hangi hataları fırlatabileceğini izlemez, bu yüzden çağıranlara onları ele almalarını hiçbir şey hatırlatmaz. Beklenen başarısızlıklar için (geçersiz girdi, eksik bir kayıt) "başarı ya da başarısızlık" diyen bir değer döndürmek, hatayı tip sisteminin içine taşır:

type Result<T, E = string> =
    | { ok: true; value: T }
    | { ok: false; error: E };

function parseAge(input: string): Result<number> {
    const n = Number(input);
    if (!Number.isInteger(n)) return { ok: false, error: `"${input}" is not a whole number` };
    if (n < 0 || n > 150) return { ok: false, error: `${n} is out of range` };
    return { ok: true, value: n };
}

for (const input of ["36", "abc", "200"]) {
    const r = parseAge(input);
    if (r.ok) {
        console.log("age:", r.value + 1); // r.value only exists when ok is true
    } else {
        console.log("error:", r.error);
    }
}
// age: 37
// error: "abc" is not a whole number
// error: 200 is out of range

r.ok kontrol edilmeden r.value okumak bir derleme hatasıdır ve amaç da budur. Beklenmedik durumlar (bug'lar, kopan bir bağlantı) için exception, çağıranın karar vermesi gereken sonuçlar için Result değerleri kullanın.

Async Kodda Hatalar

Reject olan bir promise, await noktasında fırlatılan bir hataya dönüşür; bu yüzden await etrafındaki try/catch aynı şekilde çalışır ve değişken yine unknown'dır. Tek fark bir promise üzerindeki .catch()'tir: callback parametresi unknown değil any olarak tiplenmiştir, bu yüzden onu kendiniz işaretleyin (.catch((e: unknown) => ...)). Örnekler için async/await sayfasına bakın.

Sık Yapılan Hatalar

• Daraltmadan e.message okumak. strict altında derlenmez; strict olmadan Error olmayan fırlatmalarda bozulur.
• Her şeyi yakalayıp devam etmek. Beklediğiniz hataları ele alın, geri kalanını yeniden fırlatın.
• Özel hatalarda name değerini unutmak. O zaman loglar hepsi için Error der.
• String fırlatmak. throw "failed" bir stack trace taşımaz ve instanceof Error kontrollerinden geçemez.