feat(eslint-plugin): deprecate no-throw-literal and add a renamed onl…

…y-throw-error (typescript-eslint#8701)

* feat(eslint-plugin): deprecate no-throw-literal and add a renamed only-throw-error

* Update packages/eslint-plugin/docs/rules/no-throw-literal.mdx

Co-authored-by: YeonJuan <yeonjuan93@naver.com>

* Updated options snapshot

* Update packages/eslint-plugin/docs/rules/no-throw-literal.mdx

Co-authored-by: auvred <61150013+auvred@users.noreply.github.com>

---------

Co-authored-by: YeonJuan <yeonjuan93@naver.com>
Co-authored-by: auvred <61150013+auvred@users.noreply.github.com>

packages/eslint-plugin/docs/rules/no-throw-literal.mdx

@@ -12,104 +12,14 @@ import TabItem from '@theme/TabItem';
 It is considered good practice to only `throw` the `Error` object itself or an object using the `Error` object as base objects for user-defined exceptions.
 The fundamental benefit of `Error` objects is that they automatically keep track of where they were built and originated.
 
-This rule restricts what can be thrown as an exception. When it was first created, it only prevented literals from being thrown (hence the name), but it has now been expanded to only allow expressions which have a possibility of being an `Error` object. With the `allowThrowingAny` and `allowThrowingUnknown`, it can be configured to only allow throwing values which are guaranteed to be an instance of `Error`.
+This rule restricts what can be thrown as an exception.
 
-## Examples
+:::warning
+This rule is being renamed to [`only-throw-error`](./only-throw-error.mdx).
+When it was first created, it only prevented literals from being thrown (hence the name), but it has now been expanded to only allow expressions which have a possibility of being an `Error` object.
+With the `allowThrowingAny` and `allowThrowingUnknown` options, it can be configured to only allow throwing values which are guaranteed to be an instance of `Error`.
 
-This rule is aimed at maintaining consistency when throwing exception by disallowing to throw literals and other expressions which cannot possibly be an `Error` object.
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-throw 'error';
-
-throw 0;
-
-throw undefined;
-
-throw null;
-
-const err = new Error();
-throw 'an ' + err;
-
-const err = new Error();
-throw `${err}`;
-
-const err = '';
-throw err;
-
-function err() {
-  return '';
-}
-throw err();
-
-const foo = {
-  bar: '',
-};
-throw foo.bar;
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-throw new Error();
-
-throw new Error('error');
-
-const e = new Error('error');
-throw e;
-
-try {
-  throw new Error('error');
-} catch (e) {
-  throw e;
-}
-
-const err = new Error();
-throw err;
-
-function err() {
-  return new Error();
-}
-throw err();
-
-const foo = {
-  bar: new Error(),
-};
-throw foo.bar;
-
-class CustomError extends Error {
-  // ...
-}
-throw new CustomError();
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-This rule adds the following options:
-
-```ts
-interface Options {
-  /**
-   * Whether to always allow throwing values typed as `any`.
-   */
-  allowThrowingAny?: boolean;
-
-  /**
-   * Whether to always allow throwing values typed as `unknown`.
-   */
-  allowThrowingUnknown?: boolean;
-}
-
-const defaultOptions: Options = {
-  allowThrowingAny: false,
-  allowThrowingUnknown: false,
-};
-```
+The current name `no-throw-literal` will be removed in a future major version of typescript-eslint.
+:::
 
 {/* Intentionally Omitted: When Not To Use It */}

packages/eslint-plugin/docs/rules/only-throw-error.mdx

@@ -0,0 +1,115 @@
+---
+description: 'Disallow throwing non-`Error` values as exceptions.'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/only-throw-error** for documentation.
+
+It is considered good practice to only `throw` the `Error` object itself or an object using the `Error` object as base objects for user-defined exceptions.
+The fundamental benefit of `Error` objects is that they automatically keep track of where they were built and originated.
+
+This rule restricts what can be thrown as an exception.
+
+## Examples
+
+This rule is aimed at maintaining consistency when throwing exception by disallowing to throw literals and other expressions which cannot possibly be an `Error` object.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+throw 'error';
+
+throw 0;
+
+throw undefined;
+
+throw null;
+
+const err = new Error();
+throw 'an ' + err;
+
+const err = new Error();
+throw `${err}`;
+
+const err = '';
+throw err;
+
+function err() {
+  return '';
+}
+throw err();
+
+const foo = {
+  bar: '',
+};
+throw foo.bar;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+throw new Error();
+
+throw new Error('error');
+
+const e = new Error('error');
+throw e;
+
+try {
+  throw new Error('error');
+} catch (e) {
+  throw e;
+}
+
+const err = new Error();
+throw err;
+
+function err() {
+  return new Error();
+}
+throw err();
+
+const foo = {
+  bar: new Error(),
+};
+throw foo.bar;
+
+class CustomError extends Error {
+  // ...
+}
+throw new CustomError();
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+This rule adds the following options:
+
+```ts
+interface Options {
+  /**
+   * Whether to always allow throwing values typed as `any`.
+   */
+  allowThrowingAny?: boolean;
+
+  /**
+   * Whether to always allow throwing values typed as `unknown`.
+   */
+  allowThrowingUnknown?: boolean;
+}
+
+const defaultOptions: Options = {
+  allowThrowingAny: false,
+  allowThrowingUnknown: false,
+};
+```
+
+{/* Intentionally Omitted: When Not To Use It */}

packages/eslint-plugin/src/configs/all.ts

@@ -90,8 +90,6 @@ export = {
     'no-shadow': 'off',
     '@typescript-eslint/no-shadow': 'error',
     '@typescript-eslint/no-this-alias': 'error',
-    'no-throw-literal': 'off',
-    '@typescript-eslint/no-throw-literal': 'error',
     '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
     '@typescript-eslint/no-unnecessary-condition': 'error',
     '@typescript-eslint/no-unnecessary-qualifier': 'error',
@@ -118,6 +116,8 @@ export = {
     '@typescript-eslint/no-useless-template-literals': 'error',
     '@typescript-eslint/no-var-requires': 'error',
     '@typescript-eslint/non-nullable-type-assertion-style': 'error',
+    'no-throw-literal': 'off',
+    '@typescript-eslint/only-throw-error': 'error',
     '@typescript-eslint/parameter-properties': 'error',
     '@typescript-eslint/prefer-as-const': 'error',
     'prefer-destructuring': 'off',

packages/eslint-plugin/src/configs/disable-type-checked.ts

@@ -41,6 +41,7 @@ export = {
     '@typescript-eslint/no-unsafe-unary-minus': 'off',
     '@typescript-eslint/no-useless-template-literals': 'off',
     '@typescript-eslint/non-nullable-type-assertion-style': 'off',
+    '@typescript-eslint/only-throw-error': 'off',
     '@typescript-eslint/prefer-destructuring': 'off',
     '@typescript-eslint/prefer-find': 'off',
     '@typescript-eslint/prefer-includes': 'off',

packages/eslint-plugin/src/configs/strict-type-checked-only.ts

@@ -23,8 +23,6 @@ export = {
     '@typescript-eslint/no-misused-promises': 'error',
     '@typescript-eslint/no-mixed-enums': 'error',
     '@typescript-eslint/no-redundant-type-constituents': 'error',
-    'no-throw-literal': 'off',
-    '@typescript-eslint/no-throw-literal': 'error',
     '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
     '@typescript-eslint/no-unnecessary-condition': 'error',
     '@typescript-eslint/no-unnecessary-type-arguments': 'error',
@@ -36,6 +34,8 @@ export = {
     '@typescript-eslint/no-unsafe-member-access': 'error',
     '@typescript-eslint/no-unsafe-return': 'error',
     '@typescript-eslint/no-useless-template-literals': 'error',
+    'no-throw-literal': 'off',
+    '@typescript-eslint/only-throw-error': 'error',
     '@typescript-eslint/prefer-includes': 'error',
     'prefer-promise-reject-errors': 'off',
     '@typescript-eslint/prefer-promise-reject-errors': 'error',

packages/eslint-plugin/src/configs/strict-type-checked.ts

@@ -44,8 +44,6 @@ export = {
     '@typescript-eslint/no-non-null-assertion': 'error',
     '@typescript-eslint/no-redundant-type-constituents': 'error',
     '@typescript-eslint/no-this-alias': 'error',
-    'no-throw-literal': 'off',
-    '@typescript-eslint/no-throw-literal': 'error',
     '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
     '@typescript-eslint/no-unnecessary-condition': 'error',
     '@typescript-eslint/no-unnecessary-type-arguments': 'error',
@@ -64,6 +62,8 @@ export = {
     '@typescript-eslint/no-useless-constructor': 'error',
     '@typescript-eslint/no-useless-template-literals': 'error',
     '@typescript-eslint/no-var-requires': 'error',
+    'no-throw-literal': 'off',
+    '@typescript-eslint/only-throw-error': 'error',
     '@typescript-eslint/prefer-as-const': 'error',
     '@typescript-eslint/prefer-includes': 'error',
     '@typescript-eslint/prefer-literal-enum-member': 'error',

packages/eslint-plugin/src/rules/index.ts

@@ -101,6 +101,7 @@ import noUselessTemplateLiterals from './no-useless-template-literals';
 import noVarRequires from './no-var-requires';
 import nonNullableTypeAssertionStyle from './non-nullable-type-assertion-style';
 import objectCurlySpacing from './object-curly-spacing';
+import onlyThrowError from './only-throw-error';
 import paddingLineBetweenStatements from './padding-line-between-statements';
 import parameterProperties from './parameter-properties';
 import preferAsConst from './prefer-as-const';
@@ -245,6 +246,7 @@ export default {
   'no-var-requires': noVarRequires,
   'non-nullable-type-assertion-style': nonNullableTypeAssertionStyle,
   'object-curly-spacing': objectCurlySpacing,
+  'only-throw-error': onlyThrowError,
   'padding-line-between-statements': paddingLineBetweenStatements,
   'parameter-properties': parameterProperties,
   'prefer-as-const': preferAsConst,

packages/eslint-plugin/src/rules/no-throw-literal.ts

@@ -23,9 +23,10 @@ export default createRule<Options, MessageIds>({
   name: 'no-throw-literal',
   meta: {
     type: 'problem',
+    deprecated: true,
+    replacedBy: ['@typescript-eslint/only-throw-error'],
     docs: {
       description: 'Disallow throwing literals as exceptions',
-      recommended: 'strict',
       extendsBaseRule: true,
       requiresTypeChecking: true,
     },