preserve-caught-error

Запрещает терять исходную перехваченную ошибку при повторном выбрасывании пользовательских ошибок

Разработчики JavaScript часто повторно выбрасывают ошибки в блоках catch, чтобы добавить контекст, но забывают сохранить исходную ошибку, из-за чего теряется отладочная информация.

Использование параметра cause при выбрасывании новых ошибок помогает сохранить исходную ошибку и полные цепочки ошибок, что упрощает отладку и отслеживание.

try {
	await fetch("https://xyz.com/resource");
} catch(error) {
	// Throw a more specific error without losing original context
	throw new Error("Failed to fetch resource", {
		cause: error
	});
}

Описание правила

Это правило требует использовать свойство cause при выбрасывании новой ошибки внутри блока catch.

Проверяются все встроенные error types, поддерживающие передачу cause.

Примеры неправильного кода для этого правила:

/* eslint preserve-caught-error: "error" */

// Not using the `cause` option
try {
    // ...
} catch (error) {
    throw new Error("Something went wrong: " + error.message);
}

// Throwing a new Error with unrelated cause
try {
	doSomething();
} catch (err) {
	const unrelated = new Error("other");
	throw new Error("Something failed", { cause: unrelated });
}

// Caught error is being lost partially due to destructuring
try {
	doSomething();
} catch({ message,...rest }){thrownewError(message);}

// Cause error is being shadowed by a closer scoped redeclaration.
try {
    doSomething();
} catch (error) {
    if (whatever) {
        const error = anotherError; // This declaration is the problem.
        throw new Error("Something went wrong", { cause: error });
    }
}

Примеры правильного кода для этого правила:

/* eslint preserve-caught-error: "error" */

try {
    // ...
} catch (error) {
    throw new Error("Something went wrong", { cause: error });
}

// When the thrown error is not directly related to the caught error.
try {
} catch (error) {
	foo = {
		bar() {
			// This throw is not directly related to the caught error.
			throw new Error("Something went wrong");
		}
	};
}

// No throw inside catch
try {
    doSomething();
} catch (e) {
    console.error(e);
}

// Ignoring the caught error at the parameter level
// This is valid by default, but this behavior can be changed
// by using the `requireCatchParameter` option discussed below.
try {
	doSomething();
} catch {
	throw new TypeError("Something went wrong");
}

Параметры

Это правило принимает один параметр — объект со следующим необязательным свойством:

• requireCatchParameter: требует, чтобы блоки catch всегда содержали параметр перехваченной ошибки, если задано значение true. По умолчанию это значение — false.

requireCatchParameter

Включение этого параметра требует, чтобы все блоки catch содержали параметр перехваченной ошибки. Это гарантирует, что перехваченная ошибка не будет отброшена на уровне параметра.

"preserve-caught-error": ["error", {
  "requireCatchParameter": true
}]

Пример неправильного кода для параметра { "requireCatchParameter": true }:

/* eslint preserve-caught-error: ["error", { "requireCatchParameter": true }] */

try {
	doSomething();
} catch { // Can't discard the error ❌
	throw new Error("Something went wrong");
}

Пример правильного кода для параметра { "requireCatchParameter": true }:

/* eslint preserve-caught-error: ["error", { "requireCatchParameter": true }] */

try {
	doSomething();
} catch(error) { // Error is being referenced ✅
	// Handling and re-throw logic
}

Когда не следует использовать это правило

Возможно, не стоит включать это правило, если:

• Вы используете собственный подход к обработке ошибок, при котором исходная ошибка намеренно не включается в повторно выбрасываемые ошибки (например, чтобы не раскрывать внутренние подробности или отдельно записывать исходную ошибку в журнал).

• Вы используете стороннюю или внутреннюю библиотеку обработки ошибок, которая сохраняет контекст ошибки с помощью нестандартных свойств (например, verror) вместо параметра cause.

• (В редких случаях) вы ориентируетесь на устаревшие среды, в которых параметр cause в конструкторах Error не поддерживается.

Версия

Это правило появилось в ESLint v9.35.0.

Дополнительная литература

Ресурсы

• Исходный код правила
• Исходный код тестов