xo 0.46.2 → 0.48.0

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-regexp-exec.md

@@ -0,0 +1,63 @@
+# `prefer-regexp-exec`
+
+Enforce that `RegExp#exec` is used instead of `String#match` if no global flag is provided.
+
+As `String#match` is defined to be the same as `RegExp#exec` when the regular expression does not include the `g` flag, prefer a consistent usage.
+
+## Rule Details
+
+This rule is aimed at enforcing a consistent way to apply regular expressions to strings.
+
+From [`String#match` on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match):
+
+> If the regular expression does not include the g flag, returns the same result as `RegExp.exec()`.
+
+`RegExp#exec` may also be slightly faster than `String#match`; this is the reason to choose it as the preferred usage.
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+'something'.match(/thing/);
+
+'some things are just things'.match(/thing/);
+
+const text = 'something';
+const search = /thing/;
+text.match(search);
+```
+
+### ✅ Correct
+
+```ts
+/thing/.exec('something');
+
+'some things are just things'.match(/thing/g);
+
+const text = 'something';
+const search = /thing/;
+search.exec(text);
+```
+
+## Options
+
+There are no options.
+
+```json
+{
+  "@typescript-eslint/prefer-regexp-exec": "error"
+}
+```
+
+## When Not To Use It
+
+If you prefer consistent use of `String#match` for both, with `g` flag and without it, you can turn this rule off.
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-return-this-type.md

@@ -0,0 +1,104 @@
+# `prefer-return-this-type`
+
+Enforce that `this` is used when only `this` type is returned.
+
+[Method chaining](https://en.wikipedia.org/wiki/Method_chaining) is a common pattern in OOP languages and TypeScript provides a special [polymorphic this type](https://www.typescriptlang.org/docs/handbook/2/classes.html#this-types).
+If any type other than `this` is specified as the return type of these chaining methods, TypeScript will fail to cast it when invoking in subclass.
+
+```ts
+class Animal {
+  eat(): Animal {
+    console.log("I'm moving!");
+    return this;
+  }
+}
+
+class Cat extends Animal {
+  meow(): Cat {
+    console.log('Meow~');
+    return this;
+  }
+}
+
+const cat = new Cat();
+// Error: Property 'meow' does not exist on type 'Animal'.
+// because `eat` returns `Animal` and not all animals meow.
+cat.eat().meow();
+
+// the error can be fixed by removing the return type of `eat` or use `this` as the return type.
+class Animal {
+  eat(): this {
+    console.log("I'm moving!");
+    return this;
+  }
+}
+
+class Cat extends Animal {
+  meow(): this {
+    console.log('Meow~');
+    return this;
+  }
+}
+
+const cat = new Cat();
+// no errors. Because `eat` returns `Cat` now
+cat.eat().meow();
+```
+
+## Rule Details
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+class Foo {
+  f1(): Foo {
+    return this;
+  }
+  f2 = (): Foo => {
+    return this;
+  };
+  f3(): Foo | undefined {
+    return Math.random() > 0.5 ? this : undefined;
+  }
+}
+```
+
+### ✅ Correct
+
+```ts
+class Foo {
+  f1(): this {
+    return this;
+  }
+  f2() {
+    return this;
+  }
+  f3 = (): this => {
+    return this;
+  };
+  f4 = () => {
+    return this;
+  };
+}
+
+class Base {}
+class Derived extends Base {
+  f(): Base {
+    return this;
+  }
+}
+```
+
+## When Not To Use It
+
+If you don't use method chaining or explicit return values, you can safely turn this rule off.
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-string-starts-ends-with.md

@@ -0,0 +1,66 @@
+# `prefer-string-starts-ends-with`
+
+Enforce the use of `String#startsWith` and `String#endsWith` instead of other equivalent methods of checking substrings.
+
+There are multiple ways to verify if a string starts or ends with a specific string, such as `foo.indexOf('bar') === 0`.
+
+Since ES2015 has added `String#startsWith` and `String#endsWith`, this rule reports other ways to be consistent.
+
+## Rule Details
+
+This rule is aimed at enforcing a consistent way to check whether a string starts or ends with a specific string.
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+let foo: string;
+
+// starts with
+foo[0] === 'b';
+foo.charAt(0) === 'b';
+foo.indexOf('bar') === 0;
+foo.slice(0, 3) === 'bar';
+foo.substring(0, 3) === 'bar';
+foo.match(/^bar/) != null;
+/^bar/.test(foo);
+
+// ends with
+foo[foo.length - 1] === 'b';
+foo.charAt(foo.length - 1) === 'b';
+foo.lastIndexOf('bar') === foo.length - 3;
+foo.slice(-3) === 'bar';
+foo.substring(foo.length - 3) === 'bar';
+foo.match(/bar$/) != null;
+/bar$/.test(foo);
+```
+
+### ✅ Correct
+
+```ts
+foo.startsWith('bar');
+foo.endsWith('bar');
+```
+
+## Options
+
+There are no options.
+
+```json
+{
+  "@typescript-eslint/prefer-string-starts-ends-with": "error"
+}
+```
+
+## When Not To Use It
+
+If you don't mind that style, you can turn this rule off safely.
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-ts-expect-error.md

@@ -0,0 +1,77 @@
+# `prefer-ts-expect-error`
+
+Recommends using `@ts-expect-error` over `@ts-ignore`.
+
+TypeScript allows you to suppress all errors on a line by placing a single-line comment or a comment block line starting with `@ts-ignore` immediately before the erroring line.
+While powerful, there is no way to know if a `@ts-ignore` is actually suppressing an error without manually investigating what happens when the `@ts-ignore` is removed.
+
+This means its easy for `@ts-ignore`s to be forgotten about, and remain in code even after the error they were suppressing is fixed.
+This is dangerous, as if a new error arises on that line it'll be suppressed by the forgotten about `@ts-ignore`, and so be missed.
+
+To address this, TS3.9 ships with a new single-line comment directive: `// @ts-expect-error`.
+
+This directive operates in the same manner as `@ts-ignore`, but will error if the line it's meant to be suppressing doesn't actually contain an error, making it a lot safer.
+
+## Rule Details
+
+This rule looks for usages of `@ts-ignore`, and flags them to be replaced with `@ts-expect-error`.
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+// @ts-ignore
+const str: string = 1;
+
+/**
+ * Explaining comment
+ *
+ * @ts-ignore */
+const multiLine: number = 'value';
+
+/** @ts-ignore */
+const block: string = 1;
+
+const isOptionEnabled = (key: string): boolean => {
+  // @ts-ignore: if key isn't in globalOptions it'll be undefined which is false
+  return !!globalOptions[key];
+};
+```
+
+### ✅ Correct
+
+```ts
+// @ts-expect-error
+const str: string = 1;
+
+/**
+ * Explaining comment
+ *
+ * @ts-expect-error */
+const multiLine: number = 'value';
+
+/** @ts-expect-error */
+const block: string = 1;
+
+const isOptionEnabled = (key: string): boolean => {
+  // @ts-expect-error: if key isn't in globalOptions it'll be undefined which is false
+  return !!globalOptions[key];
+};
+```
+
+## When Not To Use It
+
+If you are **NOT** using TypeScript 3.9 (or greater), then you will not be able to use this rule, as the directive is not supported
+
+## Further Reading
+
+- [Original Implementing PR](https://github.com/microsoft/TypeScript/pull/36014)
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [ ] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/promise-function-async.md

@@ -0,0 +1,78 @@
+# `promise-function-async`
+
+Requires any function or method that returns a Promise to be marked async.
+
+Requires any function or method that returns a Promise to be marked async.
+Ensures that each function is only capable of:
+
+- returning a rejected promise, or
+- throwing an Error object.
+
+In contrast, non-`async` `Promise` - returning functions are technically capable of either.
+Code that handles the results of those functions will often need to handle both cases, which can get complex.
+This rule's practice removes a requirement for creating code to handle both cases.
+
+## Rule Details
+
+Examples of code for this rule
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const arrowFunctionReturnsPromise = () => Promise.resolve('value');
+
+function functionReturnsPromise() {
+  return Promise.resolve('value');
+}
+```
+
+### ✅ Correct
+
+```ts
+const arrowFunctionReturnsPromise = async () => Promise.resolve('value');
+
+async function functionReturnsPromise() {
+  return Promise.resolve('value');
+}
+```
+
+## Options
+
+Options may be provided as an object with:
+
+- `allowAny` to indicate that `any` or `unknown` shouldn't be considered Promises (`true` by default).
+- `allowedPromiseNames` to indicate any extra names of classes or interfaces to be considered Promises when returned.
+
+In addition, each of the following properties may be provided, and default to `true`:
+
+- `checkArrowFunctions`
+- `checkFunctionDeclarations`
+- `checkFunctionExpressions`
+- `checkMethodDeclarations`
+
+```json
+{
+  "@typescript-eslint/promise-function-async": [
+    "error",
+    {
+      "allowedPromiseNames": ["Thenable"],
+      "checkArrowFunctions": true,
+      "checkFunctionDeclarations": true,
+      "checkFunctionExpressions": true,
+      "checkMethodDeclarations": true
+    }
+  ]
+}
+```
+
+## Related To
+
+- TSLint: [promise-function-async](https://palantir.github.io/tslint/rules/promise-function-async)
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/quotes.md

@@ -0,0 +1,34 @@
+# `quotes`
+
+Enforce the consistent use of either backticks, double, or single quotes.
+
+## Rule Details
+
+This rule extends the base [`eslint/quotes`](https://eslint.org/docs/rules/quotes) rule.
+It adds support for TypeScript features which allow quoted names, but not backtick quoted names.
+
+## How to Use
+
+```jsonc
+{
+  // note you must disable the base rule as it can report incorrect errors
+  "quotes": "off",
+  "@typescript-eslint/quotes": ["error"]
+}
+```
+
+## Options
+
+See [`eslint/quotes` options](https://eslint.org/docs/rules/quotes#options).
+
+<sup>
+
+Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/main/docs/rules/quotes.md)
+
+</sup>
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [x] 🔧 Fixable
+- [ ] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-array-sort-compare.md

@@ -0,0 +1,105 @@
+# `require-array-sort-compare`
+
+Requires `Array#sort` calls to always provide a `compareFunction`.
+
+This rule prevents invoking the `Array#sort()` method without providing a `compare` argument.
+
+When called without a compare function, `Array#sort()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units.
+
+The result is that elements are sorted alphabetically, regardless of their type.
+When sorting numbers, this results in the classic "10 before 2" order:
+
+```ts
+[1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
+```
+
+This also means that `Array#sort` does not always sort consistently, as elements may have custom `#toString` implementations that are not deterministic; this trap is noted in the language specification thusly:
+
+:::note
+Method calls performed by the `ToString` abstract operations in steps 5 and 7 have the potential to cause `SortCompare` to not behave as a consistent comparison function.
+
+https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare
+:::
+
+## Rule Details
+
+This rule aims to ensure all calls of the native `Array#sort` method provide a `compareFunction`, while ignoring calls to user-defined `sort` methods.
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const array: any[];
+const stringArray: string[];
+
+array.sort();
+
+// String arrays should be sorted using `String#localeCompare`.
+stringArray.sort();
+```
+
+### ✅ Correct
+
+```ts
+const array: any[];
+const userDefinedType: { sort(): void };
+
+array.sort((a, b) => a - b);
+array.sort((a, b) => a.localeCompare(b));
+
+userDefinedType.sort();
+```
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+```ts
+type Options = {
+  /**
+   * If true, an array which all elements are string is ignored.
+   */
+  ignoreStringArrays?: boolean;
+};
+
+const defaults = {
+  ignoreStringArrays: false,
+};
+```
+
+### `ignoreStringArrays`
+
+Examples of code for this rule with `{ ignoreStringArrays: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const one = 1;
+const two = 2;
+const three = 3;
+[one, two, three].sort();
+```
+
+#### ✅ Correct
+
+```ts
+const one = '1';
+const two = '2';
+const three = '3';
+[one, two, three].sort();
+```
+
+## When Not To Use It
+
+If you understand the language specification enough, you can turn this rule off safely.
+
+## Attributes
+
+- [ ] ✅ Recommended
+- [ ] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-await.md

@@ -0,0 +1,44 @@
+# `require-await`
+
+Disallow async functions which have no `await` expression.
+
+## Rule Details
+
+This rule extends the base [`eslint/require-await`](https://eslint.org/docs/rules/require-await) rule.
+It uses type information to add support for `async` functions that return a `Promise`.
+
+Examples of **correct** code for this rule:
+
+```ts
+async function returnsPromise1() {
+  return Promise.resolve(1);
+}
+
+const returnsPromise2 = () => returnsPromise1();
+```
+
+## How to Use
+
+```jsonc
+{
+  // note you must disable the base rule as it can report incorrect errors
+  "require-await": "off",
+  "@typescript-eslint/require-await": "error"
+}
+```
+
+## Options
+
+See [`eslint/require-await` options](https://eslint.org/docs/rules/require-await#options).
+
+<sup>
+
+Taken with ❤️ [from ESLint core](https://github.com/eslint/eslint/blob/main/docs/rules/require-await.md)
+
+</sup>
+
+## Attributes
+
+- [x] ✅ Recommended
+- [ ] 🔧 Fixable
+- [x] 💭 Requires type information

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/restrict-plus-operands.md

@@ -0,0 +1,112 @@
+# `restrict-plus-operands`
+
+When adding two variables, operands must both be of type number or of type string.
+
+## Rule Details
+
+Examples of code for this rule:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+var foo = '5.5' + 5;
+var foo = 1n + 1;
+```
+
+### ✅ Correct
+
+```ts
+var foo = parseInt('5.5', 10) + 10;
+var foo = 1n + 1n;
+```
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+```ts
+type Options = {
+  // if true, check compound assignments (`+=`)
+  checkCompoundAssignments?: boolean;
+  // if true, 'any' itself and `string`,`bigint`, `number` is allowed.
+  allowAny?: boolean;
+};
+
+const defaults = {
+  checkCompoundAssignments: false,
+  allowAny: false,
+};
+```
+
+### `checkCompoundAssignments`
+
+Examples of code for this rule with `{ checkCompoundAssignments: true }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+
+let foo: string | undefined;
+foo += 'some data';
+
+let bar: string = '';
+bar += 0;
+```
+
+#### ✅ Correct
+
+```ts
+/*eslint @typescript-eslint/restrict-plus-operands: ["error", { "checkCompoundAssignments": true }]*/
+
+let foo: number = 0;
+foo += 1;
+
+let bar = '';
+bar += 'test';
+```
+
+### `allowAny`
+
+Examples of code for this rule with `{ allowAny: 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;
+```
+
+#### ✅ 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;
+```
+
+## How to Use
+
+```json
+{
+  "@typescript-eslint/restrict-plus-operands": "error"
+}
+```
+
+## Related To
+
+- TSLint: [restrict-plus-operands](https://palantir.github.io/tslint/rules/restrict-plus-operands/)
+
+## Attributes
+
+- [x] ✅ Recommended
+- [ ] 🔧 Fixable
+- [x] 💭 Requires type information