TypeScriptのtry catch: エラーの型と独自のエラー

TypeScriptはJavaScriptの try、catch、finally、throw を使います。TypeScript特有なのは catch の変数です。strict が有効なら型は unknown なので、使う前に何が throw されたかをチェックします。

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");
}

実行時の動き（スタックがどう巻き戻るか、どんな組み込みのエラー型があるか）は JavaScriptのtry/catch で説明しています。

catch の変数が unknown になる理由

JavaScriptは何でも throw できます。Error、文字列、数値、undefined、ライブラリのオブジェクトなどです。TypeScriptにはどれかわからないので、strict（useUnknownInCatchVariables フラグ）のもとでは変数は unknown になり、使う前に絞り込む必要があります:

// 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 がなければ e は any で、同じコードはコンパイルできますが、文字列が throw されると実行時におかしくなります。e.message は undefined になり、e.message.length のようにさらに奥を読むと TypeError が投げられます。型注釈で逃げることもできません。catch (e: Error) はエラー TS1196（Catch clause variable type annotation must be 'any' or 'unknown' if specified）です。

エラーを絞り込む

instanceof Error は、TypeError、SyntaxError、RangeError、自作のサブクラスなど、Error をもとにしたものすべてをカバーします。それ以外は値を文字列に変換して扱います。小さなヘルパーを作れば、呼び出し箇所を短く保てます:

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}

一部のエラーだけを処理する catch は、残りを投げ直すべきです: if (!(e instanceof ValidationError)) throw e;。未知のエラーを握りつぶすと、本当のバグが隠れてしまいます。

エラーを throw する

throw はどんな式でも受け付け、TypeScriptも制限しません。それでも Error オブジェクトを throw しましょう。スタックトレースを持ち、コードベースのあらゆる instanceof Error のチェックがそれに依存しています。

常に throw する関数の戻り値の型は never で、TypeScriptは呼び出しのあとの絞り込みにこれを使います:

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 以降、Error は cause を持つ2番目の引数を受け取り、低レベルのエラーを自分が throw するエラーにつなげられます: throw new Error("could not load settings", { cause: e })。呼び出し側は err.cause（型は unknown）を読めます。

独自のエラークラス

Error のサブクラスを作ると、呼び出し側が instanceof で失敗を区別でき、追加のデータも持たせられます。継承した name は "Error" で、ログや String(err) に表れるので、name を設定しましょう:

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

NotFoundError は HttpError でもあるので、いちばん具体的なクラスを先にチェックします。noImplicitOverride が有効でなければ、ここでの override 修飾子は任意です。

古いガイドでは、すべてのエラーのコンストラクターに Object.setPrototypeOf(this, new.target.prototype) を追加しています。これはクラスを ES5 の関数にコンパイルしていたときに、Error のサブクラスで instanceof が壊れたために必要だったものです。TypeScript 7 は target: "es5" をもうサポートしておらず（TS5108: Option 'target=ES5' has been removed が報告されます）、ES2015 以降では上の例のようにネイティブの class ... extends Error がそのまま動きます。

Result パターン

TypeScriptは関数がどのエラーを throw するかを追跡しないので、呼び出し側に処理を促すものは何もありません。想定される失敗（不正な入力、存在しないレコード）には、「成功か失敗か」を表す値を返すと、エラーが型システムに組み込まれます:

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 をチェックする前に r.value を読むとコンパイルエラーになります。それこそが狙いです。想定外のもの（バグ、切れた接続）には例外を、呼び出し側が判断しなければならない結果には Result の値を使いましょう。

非同期コードのエラー

reject された Promise は await の位置で throw されたエラーになるので、await を囲む try/catch も同じように動き、変数はやはり unknown です。唯一の違いは Promise の .catch() で、そのコールバックの引数は unknown ではなく any と型付けされているので、自分で型注釈を付けます（.catch((e: unknown) => ...)）。例は async/await を参照してください。

よくある間違い

• 絞り込まずに e.message を読む。 strict のもとではコンパイルできず、strict なしでは Error 以外が throw されたときに壊れます。
• すべてを捕まえて処理を続ける。 想定しているエラーを処理し、残りは投げ直しましょう。
• 独自のエラーに name を付け忘れる。 ログではどれも Error と表示されてしまいます。
• 文字列を throw する。 throw "failed" にはスタックトレースがなく、instanceof Error のチェックにも失敗します。