@alexlit/lint-kit 111.0.0 → 112.0.0

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-return-this-type.mdx

@@ -0,0 +1,93 @@
+---
+description: 'Enforce that `this` is used when only `this` type is returned.'
+---
+
+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/prefer-return-this-type** for documentation.
+
+[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) to facilitate it.
+Class methods that explicitly declare a return type of the class name instead of `this` make it harder for extending classes to call that method: the returned object will be typed as the base class, not the derived class.
+
+This rule reports when a class method declares a return type of that class name instead of `this`.
+
+```ts
+class Animal {
+  eat(): Animal {
+    //   ~~~~~~
+    // Either removing this type annotation or replacing
+    // it with `this` would remove the type error below.
+    console.log("I'm moving!");
+    return this;
+  }
+}
+
+class Cat extends Animal {
+  meow(): Cat {
+    console.log('Meow~');
+    return this;
+  }
+}
+
+const cat = new Cat();
+cat.eat().meow();
+//        ~~~~
+// Error: Property 'meow' does not exist on type 'Animal'.
+// because `eat` returns `Animal` and not all animals meow.
+```
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+class Foo {
+  f1(): Foo {
+    return this;
+  }
+  f2 = (): Foo => {
+    return this;
+  };
+  f3(): Foo | undefined {
+    return Math.random() > 0.5 ? this : undefined;
+  }
+}
+```
+
+</TabItem>
+<TabItem value="✅ 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;
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you don't use method chaining or explicit return values, you can safely turn this rule off.

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

@@ -0,0 +1,82 @@
+---
+description: 'Enforce using `String#startsWith` and `String#endsWith` over other equivalent methods of checking substrings.'
+---
+
+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/prefer-string-starts-ends-with** for documentation.
+
+There are multiple ways to verify if a string starts or ends with a specific string, such as `foo.indexOf('bar') === 0`.
+As of ES2015, the most common way in JavaScript is to use `String#startsWith` and `String#endsWith`.
+Keeping to those methods consistently helps with code readability.
+
+This rule reports when a string method can be replaced safely with `String#startsWith` or `String#endsWith`.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+declare const 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);
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+declare const foo: string;
+
+// starts with
+foo.startsWith('bar');
+
+// ends with
+foo.endsWith('bar');
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+### `allowSingleElementEquality`
+
+If switched to `'always'`, the rule will allow equality checks against the first or last character in a string.
+This can be preferable in projects that don't deal with special character encodings and prefer a more succinct style.
+
+The following code is considered incorrect by default, but is allowed with `allowSingleElementEquality: 'always'`:
+
+```ts option='{ "allowSingleElementEquality": "always" }' showPlaygroundButton
+declare const text: string;
+
+text[0] === 'a';
+text[0] === text[0].toUpperCase();
+text[0] === text[1];
+text[text.length - 1] === 'b';
+```
+
+## When Not To Use It
+
+If you don't mind which style of string checking is used, you can turn this rule off safely.
+However, keep in mind that inconsistent style can harm readability in a project.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-ts-expect-error.mdx

@@ -0,0 +1,76 @@
+---
+description: 'Enforce using `@ts-expect-error` over `@ts-ignore`.'
+---
+
+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/prefer-ts-expect-error** for documentation.
+
+TypeScript allows you to suppress all errors on a line by placing a comment starting with `@ts-ignore` or `@ts-expect-error` immediately before the erroring line.
+The two directives work the same, except `@ts-expect-error` causes a type error if placed before a line that's not erroring in the first place.
+
+This means it's 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.
+
+## Examples
+
+This rule reports any usage of `@ts-ignore`, including a fixer to replace with `@ts-expect-error`.
+
+<Tabs>
+<TabItem value="❌ 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];
+};
+```
+
+</TabItem>
+<TabItem value="✅ 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];
+};
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you are compiling against multiple versions of TypeScript and using `@ts-ignore` to ignore version-specific type errors, this rule might get in your way.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) for those specific situations instead of completely disabling this rule.
+
+## Further Reading
+
+- [Original Implementing PR](https://github.com/microsoft/TypeScript/pull/36014)

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/promise-function-async.mdx

@@ -0,0 +1,144 @@
+---
+description: 'Require any function or method that returns a Promise to be marked async.'
+---
+
+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/promise-function-async** for documentation.
+
+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.
+
+> When functions return unions of `Promise` and non-`Promise` types implicitly, it is usually a mistake—this rule flags those cases. If it is intentional, make the return type explicitly to allow the rule to pass.
+
+## Examples
+
+Examples of code for this rule
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+const arrowFunctionReturnsPromise = () => Promise.resolve('value');
+
+function functionReturnsPromise() {
+  return Promise.resolve('value');
+}
+
+function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
+  return p ? 'value' : Promise.resolve('value');
+}
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+const arrowFunctionReturnsPromise = async () => Promise.resolve('value');
+
+async function functionReturnsPromise() {
+  return Promise.resolve('value');
+}
+
+// An explicit return type that is not Promise means this function cannot be made async, so it is ignored by the rule
+function functionReturnsUnionWithPromiseExplicitly(
+  p: boolean,
+): string | Promise<string> {
+  return p ? 'value' : Promise.resolve('value');
+}
+
+async function functionReturnsUnionWithPromiseImplicitly(p: boolean) {
+  return p ? 'value' : Promise.resolve('value');
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+### `allowAny`
+
+Whether to ignore functions that return `any` and `unknown`.
+If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors.
+
+Examples of code with `{ "allowAny": false }`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "allowAny": false }'
+const returnsAny = () => ({}) as any;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "allowAny": false }'
+const returnsAny = async () => ({}) as any;
+```
+
+</TabItem>
+</Tabs>
+
+### `allowedPromiseNames`
+
+For projects that use constructs other than the global built-in `Promise` for asynchronous code.
+This option allows specifying string names of classes or interfaces that cause a function to be checked as well.
+
+Examples of code with `{ "allowedPromiseNames": ["Bluebird"] }`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = () => new Bluebird(() => {});
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "allowedPromiseNames": ["Bluebird"] }'
+import { Bluebird } from 'bluebird';
+
+const returnsBluebird = async () => new Bluebird(() => {});
+```
+
+</TabItem>
+</Tabs>
+
+### `checkArrowFunctions`
+
+Whether to check arrow functions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionDeclarations`
+
+Whether to check standalone function declarations.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkFunctionExpressions`
+
+Whether to check inline function expressions.
+`true` by default, but can be set to `false` to ignore them.
+
+### `checkMethodDeclarations`
+
+Whether to check methods on classes and object literals
+`true` by default, but can be set to `false` to ignore them.
+
+## When Not To Use It
+
+This rule can be difficult to enable on projects that use APIs which require functions to always be `async`.
+You might consider using [ESLint disable comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) along with filing issues on your dependencies for those specific situations instead of completely disabling this rule.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/quotes.mdx

@@ -0,0 +1,13 @@
+---
+description: 'Enforce the consistent use of either backticks, double, or single quotes.'
+---
+
+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/quotes** for documentation.
+
+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.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-array-sort-compare.mdx

@@ -0,0 +1,87 @@
+---
+description: 'Require `Array#sort` and `Array#toSorted` calls to always provide a `compareFunction`.'
+---
+
+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/require-array-sort-compare** for documentation.
+
+When called without a compare function, `Array#sort()` and `Array#toSorted()` converts all non-undefined array elements into strings and then compares said strings based off their UTF-16 code units [[ECMA specification](https://www.ecma-international.org/ecma-262/9.0/#sec-sortcompare)].
+
+The result is that elements are sorted alphabetically, regardless of their type.
+For example, when sorting numbers, this results in a "10 before 2" order:
+
+```ts
+[1, 2, 3, 10, 20, 30].sort(); //→ [1, 10, 2, 20, 3, 30]
+```
+
+This rule reports on any call to the sort methods that do not provide a `compare` argument.
+
+## Examples
+
+This rule aims to ensure all calls of the native sort methods provide a `compareFunction`, while ignoring calls to user-defined methods.
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+const array: any[];
+const stringArray: string[];
+
+array.sort();
+
+// String arrays should be sorted using `String#localeCompare`.
+stringArray.sort();
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+const array: any[];
+const userDefinedType: { sort(): void };
+
+array.sort((a, b) => a - b);
+array.sort((a, b) => a.localeCompare(b));
+
+userDefinedType.sort();
+```
+
+</TabItem>
+</Tabs>
+
+## Options
+
+### `ignoreStringArrays`
+
+Examples of code for this rule with `{ ignoreStringArrays: true }`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "ignoreStringArrays": true }'
+const one = 1;
+const two = 2;
+const three = 3;
+[one, two, three].sort();
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "ignoreStringArrays": true }'
+const one = '1';
+const two = '2';
+const three = '3';
+[one, two, three].sort();
+```
+
+</TabItem>
+</Tabs>
+
+## When Not To Use It
+
+If you intentionally want your arrays to be always sorted in a string-like manner, you can turn this rule off safely.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/require-await.mdx

@@ -0,0 +1,25 @@
+---
+description: 'Disallow async functions which have no `await` expression.'
+---
+
+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/require-await** for documentation.
+
+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
+
+Examples of **correct** code for this rule:
+
+```ts
+async function returnsPromise1() {
+  return Promise.resolve(1);
+}
+
+const returnsPromise2 = () => returnsPromise1();
+```