feat(eslint-plugin): [restrict-plus-operands] add allow* options

packages/eslint-plugin/docs/rules/restrict-plus-operands.md

@@ -18,70 +18,159 @@ This rule reports when a `+` operation combines two values of different types, o
 ### ❌ Incorrect
 
 ```ts
-var foo = '5.5' + 5;
-var foo = 1n + 1;
+let foo = '5.5' + 5;
+let foo = 1n + 1;
 ```
 
 ### ✅ Correct
 
 ```ts
-var foo = parseInt('5.5', 10) + 10;
-var foo = 1n + 1n;
+let foo = parseInt('5.5', 10) + 10;
+let foo = 1n + 1n;
 ```
 
 ## Options
 
-### `checkCompoundAssignments`
+:::caution
+We generally recommend against using these options, as they limit which varieties of incorrect `+` usage can be checked.
 
-Examples of code for this rule with `{ checkCompoundAssignments: true }`:
+For example, instead of enabling the `allow*` options to concatenate strings and other values, use APIs akin to `console.log` that allow passing multiple values:
+
+```diff
+declare const value: boolean;
+
+- console.log("My value is: " + value);
++ console.log("My value is:", value;
+```
+
+:::
+
+### `allowAny`
+
+Examples of code for this rule with `{ allowAny: true }`:
 
 <!--tabs-->
 
 #### ❌ Incorrect
 
 ```ts
-/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+let fn = (a: number, b: []) => a + b;
+let fn = (a: string, b: []) => a + b;
+```
 
-let foo: string | undefined;
-foo += 'some data';
+#### ✅ Correct
 
-let bar: string = '';
-bar += 0;
+```ts
+let fn = (a: number, b: any) => a + b;
+let fn = (a: string, b: any) => a + b;
+```
+
+### `allowBoolean`
+
+Examples of code for this rule with `{ allowBoolean: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: string, b: unknown) => a + b;
 ```
 
 #### ✅ Correct
 
 ```ts
-/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+let fn = (a: number, b: boolean) => a + b;
+let fn = (a: string, b: boolean) => a + b;
+```
 
-let foo: number = 0;
-foo += 1;
+### `allowNullish`
 
-let bar = '';
-bar += 'test';
+Examples of code for this rule with `{ allowNullish: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: number, b: never) => a + b;
+let fn = (a: string, b: unknown) => a + b;
+let fn = (a: string, b: never) => a + b;
 ```
 
-### `allowAny`
+#### ✅ Correct
 
-Examples of code for this rule with `{ allowAny: true }`:
+```ts
+let fn = (a: number, b: undefined) => a + b;
+let fn = (a: number, b: null) => a + b;
+let fn = (a: string, b: undefined) => a + b;
+let fn = (a: string, b: null) => a + b;
+```
+
+### `allowNumberAndString`
+
+Examples of code for this rule with `{ allowNumberAndString: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: unknown) => a + b;
+let fn = (a: number, b: never) => a + b;
+```
+
+#### ✅ Correct
+
+```ts
+let fn = (a: number, b: string) => a + b;
+let fn = (a: number, b: number | string) => a + b;
+```
+
+### `allowRegExp`
+
+Examples of code for this rule with `{ allowRegExp: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+let fn = (a: number, b: RegExp) => a + b;
+```
+
+#### ✅ Correct
+
+```ts
+let fn = (a: string, b: RegExp) => a + b;
+```
+
+### `checkCompoundAssignments`
+
+Examples of code for this rule with `{ checkCompoundAssignments: true }`:
 
 <!--tabs-->
 
 #### ❌ Incorrect
 
 ```ts
-var fn = (a: any, b: boolean) => a + b;
-var fn = (a: any, b: []) => a + b;
-var fn = (a: any, b: {}) => a + b;
+let foo: string | undefined;
+foo += 'some data';
+
+let bar: string = '';
+bar += 0;
 ```
 
 #### ✅ Correct
 
 ```ts
-var fn = (a: any, b: any) => a + b;
-var fn = (a: any, b: string) => a + b;
-var fn = (a: any, b: bigint) => a + b;
-var fn = (a: any, b: number) => a + b;
+let foo: number = 0;
+foo += 1;
+
+let bar = '';
+bar += 'test';
 ```
 
 ## When Not To Use It