@typescript-eslint/eslint-plugin 8.33.1-alpha.5 → 8.33.1

package/docs/rules/prefer-promise-reject-errors.mdx

@@ -1,78 +0,0 @@
----
-description: 'Require using Error objects as Promise rejection reasons.'
----
-
-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-promise-reject-errors** for documentation.
-
-It uses type information to enforce that `Promise`s are only rejected with `Error` objects.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-Promise.reject('error');
-
-const err = new Error();
-Promise.reject('an ' + err);
-
-new Promise((resolve, reject) => reject('error'));
-
-new Promise((resolve, reject) => {
-  const err = new Error();
-  reject('an ' + err);
-});
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-Promise.reject(new Error());
-
-class CustomError extends Error {
-  // ...
-}
-Promise.reject(new CustomError());
-
-new Promise((resolve, reject) => reject(new Error()));
-
-new Promise((resolve, reject) => {
-  class CustomError extends Error {
-    // ...
-  }
-  return reject(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,
-};
-```

package/docs/rules/prefer-readonly-parameter-types.mdx

@@ -1,408 +0,0 @@
----
-description: 'Require function parameters to be typed as `readonly` to prevent accidental mutation of inputs.'
----
-
-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-readonly-parameter-types** for documentation.
-
-Mutating function arguments can lead to confusing, hard to debug behavior.
-Whilst it's easy to implicitly remember to not modify function arguments, explicitly typing arguments as readonly provides clear contract to consumers.
-This contract makes it easier for a consumer to reason about if a function has side-effects.
-
-This rule allows you to enforce that function parameters resolve to readonly types.
-A type is considered readonly if:
-
-- it is a primitive type (`string`, `number`, `boolean`, `symbol`, or an enum),
-- it is a function signature type,
-- it is a readonly array type whose element type is considered readonly.
-- it is a readonly tuple type whose elements are all considered readonly.
-- it is an object type whose properties are all marked as readonly, and whose values are all considered readonly.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-function array1(arg: string[]) {} // array is not readonly
-function array2(arg: readonly string[][]) {} // array element is not readonly
-function array3(arg: [string, number]) {} // tuple is not readonly
-function array4(arg: readonly [string[], number]) {} // tuple element is not readonly
-// the above examples work the same if you use ReadonlyArray<T> instead
-
-function object1(arg: { prop: string }) {} // property is not readonly
-function object2(arg: { readonly prop: string; prop2: string }) {} // not all properties are readonly
-function object3(arg: { readonly prop: { prop2: string } }) {} // nested property is not readonly
-// the above examples work the same if you use Readonly<T> instead
-
-interface CustomArrayType extends ReadonlyArray<string> {
-  prop: string; // note: this property is mutable
-}
-function custom1(arg: CustomArrayType) {}
-
-interface CustomFunction {
-  (): void;
-  prop: string; // note: this property is mutable
-}
-function custom2(arg: CustomFunction) {}
-
-function union(arg: string[] | ReadonlyArray<number[]>) {} // not all types are readonly
-
-// rule also checks function types
-interface Foo {
-  (arg: string[]): void;
-}
-interface Foo {
-  new (arg: string[]): void;
-}
-const x = { foo(arg: string[]): void {} };
-function foo(arg: string[]);
-type Foo = (arg: string[]) => void;
-interface Foo {
-  foo(arg: string[]): void;
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-function array1(arg: readonly string[]) {}
-function array2(arg: readonly (readonly string[])[]) {}
-function array3(arg: readonly [string, number]) {}
-function array4(arg: readonly [readonly string[], number]) {}
-// the above examples work the same if you use ReadonlyArray<T> instead
-
-function object1(arg: { readonly prop: string }) {}
-function object2(arg: { readonly prop: string; readonly prop2: string }) {}
-function object3(arg: { readonly prop: { readonly prop2: string } }) {}
-// the above examples work the same if you use Readonly<T> instead
-
-interface CustomArrayType extends ReadonlyArray<string> {
-  readonly prop: string;
-}
-function custom1(arg: Readonly<CustomArrayType>) {}
-// interfaces that extend the array types are not considered arrays, and thus must be made readonly.
-
-interface CustomFunction {
-  (): void;
-  readonly prop: string;
-}
-function custom2(arg: CustomFunction) {}
-
-function union(arg: readonly string[] | ReadonlyArray<number>) {}
-
-function primitive1(arg: string) {}
-function primitive2(arg: number) {}
-function primitive3(arg: boolean) {}
-function primitive4(arg: unknown) {}
-function primitive5(arg: null) {}
-function primitive6(arg: undefined) {}
-function primitive7(arg: any) {}
-function primitive8(arg: never) {}
-function primitive9(arg: string | number | undefined) {}
-
-function fnSig(arg: () => void) {}
-
-enum Foo {
-  a,
-  b,
-}
-function enumArg(arg: Foo) {}
-
-function symb1(arg: symbol) {}
-const customSymbol = Symbol('a');
-function symb2(arg: typeof customSymbol) {}
-
-// function types
-interface Foo {
-  (arg: readonly string[]): void;
-}
-interface Foo {
-  new (arg: readonly string[]): void;
-}
-const x = { foo(arg: readonly string[]): void {} };
-function foo(arg: readonly string[]);
-type Foo = (arg: readonly string[]) => void;
-interface Foo {
-  foo(arg: readonly string[]): void;
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `allow`
-
-{/* insert option description */}
-
-Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types.
-
-This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier).
-
-Examples of code for this rule with:
-
-```json
-{
-  "allow": [
-    { "from": "file", "name": "Foo" },
-    { "from": "lib", "name": "HTMLElement" },
-    { "from": "package", "name": "Bar", "package": "bar-lib" }
-  ]
-}
-```
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{"allow":[{"from":"file","name":"Foo"},{"from":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-interface ThisIsMutable {
-  prop: string;
-}
-
-interface Wrapper {
-  sub: ThisIsMutable;
-}
-
-interface WrapperWithOther {
-  readonly sub: Foo;
-  otherProp: string;
-}
-
-// Incorrect because ThisIsMutable is not readonly
-function fn1(arg: ThisIsMutable) {}
-
-// Incorrect because Wrapper.sub is not readonly
-function fn2(arg: Wrapper) {}
-
-// Incorrect because WrapperWithOther.otherProp is not readonly and not in the allowlist
-function fn3(arg: WrapperWithOther) {}
-```
-
-```ts option='{"allow":[{"from":"file","name":"Foo"},{"from":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-import { Foo } from 'some-lib';
-import { Bar } from 'incorrect-lib';
-
-interface HTMLElement {
-  prop: string;
-}
-
-// Incorrect because Foo is not a local type
-function fn1(arg: Foo) {}
-
-// Incorrect because HTMLElement is not from the default library
-function fn2(arg: HTMLElement) {}
-
-// Incorrect because Bar is not from "bar-lib"
-function fn3(arg: Bar) {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{"allow":[{"from":"file","name":"Foo"},{"from":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-interface Foo {
-  prop: string;
-}
-
-interface Wrapper {
-  readonly sub: Foo;
-  readonly otherProp: string;
-}
-
-// Works because Foo is allowed
-function fn1(arg: Foo) {}
-
-// Works even when Foo is nested somewhere in the type, with other properties still being checked
-function fn2(arg: Wrapper) {}
-```
-
-```ts option='{"allow":[{"from":"file","name":"Foo"},{"from":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-import { Bar } from 'bar-lib';
-
-interface Foo {
-  prop: string;
-}
-
-// Works because Foo is a local type
-function fn1(arg: Foo) {}
-
-// Works because HTMLElement is from the default library
-function fn2(arg: HTMLElement) {}
-
-// Works because Bar is from "bar-lib"
-function fn3(arg: Bar) {}
-```
-
-```ts option='{"allow":[{"from":"file","name":"Foo"},{"from":"lib","name":"HTMLElement"},{"from":"package","name":"Bar","package":"bar-lib"}]}'
-import { Foo } from './foo';
-
-// Works because Foo is still a local type - it has to be in the same package
-function fn(arg: Foo) {}
-```
-
-</TabItem>
-</Tabs>
-
-### `checkParameterProperties`
-
-{/* insert option description */}
-
-Because parameter properties create properties on the class, it may be undesirable to force them to be readonly.
-
-Examples of code for this rule with `{checkParameterProperties: true}`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "checkParameterProperties": true }'
-class Foo {
-  constructor(private paramProp: string[]) {}
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "checkParameterProperties": true }'
-class Foo {
-  constructor(private paramProp: readonly string[]) {}
-}
-```
-
-</TabItem>
-</Tabs>
-
-Examples of **correct** code for this rule with `{checkParameterProperties: false}`:
-
-```ts option='{ "checkParameterProperties": false }' showPlaygroundButton
-class Foo {
-  constructor(
-    private paramProp1: string[],
-    private paramProp2: readonly string[],
-  ) {}
-}
-```
-
-### `ignoreInferredTypes`
-
-{/* insert option description */}
-
-This may be desirable in cases where an external dependency specifies a callback with mutable parameters, and manually annotating the callback's parameters is undesirable.
-
-Examples of code for this rule with `{ignoreInferredTypes: true}`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "ignoreInferredTypes": true }' skipValidation
-import { acceptsCallback, CallbackOptions } from 'external-dependency';
-
-acceptsCallback((options: CallbackOptions) => {});
-```
-
-<details>
-<summary>external-dependency.d.ts</summary>
-
-```ts option='{ "ignoreInferredTypes": true }'
-export interface CallbackOptions {
-  prop: string;
-}
-type Callback = (options: CallbackOptions) => void;
-type AcceptsCallback = (callback: Callback) => void;
-
-export const acceptsCallback: AcceptsCallback;
-```
-
-</details>
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "ignoreInferredTypes": true }'
-import { acceptsCallback } from 'external-dependency';
-
-acceptsCallback(options => {});
-```
-
-<details>
-<summary>external-dependency.d.ts</summary>
-
-```ts option='{ "ignoreInferredTypes": true }' skipValidation
-export interface CallbackOptions {
-  prop: string;
-}
-type Callback = (options: CallbackOptions) => void;
-type AcceptsCallback = (callback: Callback) => void;
-
-export const acceptsCallback: AcceptsCallback;
-```
-
-</details>
-
-</TabItem>
-</Tabs>
-
-### `treatMethodsAsReadonly`
-
-{/* insert option description */}
-
-This may be desirable when you are never reassigning methods.
-
-Examples of code for this rule with `{treatMethodsAsReadonly: false}`:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "treatMethodsAsReadonly": false }'
-type MyType = {
-  readonly prop: string;
-  method(): string; // note: this method is mutable
-};
-function foo(arg: MyType) {}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "treatMethodsAsReadonly": false }'
-type MyType = Readonly<{
-  prop: string;
-  method(): string;
-}>;
-function foo(arg: MyType) {}
-
-type MyOtherType = {
-  readonly prop: string;
-  readonly method: () => string;
-};
-function bar(arg: MyOtherType) {}
-```
-
-</TabItem>
-</Tabs>
-
-Examples of **correct** code for this rule with `{treatMethodsAsReadonly: true}`:
-
-```ts option='{ "treatMethodsAsReadonly": true }' showPlaygroundButton
-type MyType = {
-  readonly prop: string;
-  method(): string; // note: this method is mutable
-};
-function foo(arg: MyType) {}
-```
-
-## When Not To Use It
-
-If your project does not attempt to enforce strong immutability guarantees of parameters, you can avoid this rule.
-
-This rule is very strict on what it considers mutable.
-Many types that describe themselves as readonly are considered mutable because they have mutable properties such as arrays or tuples.
-To work around these limitations, you might need to use the rule's options.
-In particular, the [`allow` option](#allow) can explicitly mark a type as readonly.

package/docs/rules/prefer-readonly.mdx

@@ -1,111 +0,0 @@
----
-description: "Require private members to be marked as `readonly` if they're never modified outside of the constructor."
----
-
-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-readonly** for documentation.
-
-Private member variables (whether using the `private` modifier or private `#` fields) are never permitted to be modified outside of their declaring class.
-If that class never modifies their value, they may safely be marked as `readonly`.
-
-This rule reports on private members are marked as `readonly` if they're never modified outside of the constructor.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-class Container {
-  // These member variables could be marked as readonly
-  private neverModifiedMember = true;
-  private onlyModifiedInConstructor: number;
-  #neverModifiedPrivateField = 3;
-
-  public constructor(
-    onlyModifiedInConstructor: number,
-    // Private parameter properties can also be marked as readonly
-    private neverModifiedParameter: string,
-  ) {
-    this.onlyModifiedInConstructor = onlyModifiedInConstructor;
-  }
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-class Container {
-  // Public members might be modified externally
-  public publicMember: boolean;
-
-  // Protected members might be modified by child classes
-  protected protectedMember: number;
-
-  // This is modified later on by the class
-  private modifiedLater = 'unchanged';
-
-  public mutate() {
-    this.modifiedLater = 'mutated';
-  }
-
-  // This is modified later on by the class
-  #modifiedLaterPrivateField = 'unchanged';
-
-  public mutatePrivateField() {
-    this.#modifiedLaterPrivateField = 'mutated';
-  }
-}
-```
-
-</TabItem>
-</Tabs>
-
-## Options
-
-### `onlyInlineLambdas`
-
-{/* insert option description */}
-
-```jsonc
-{
-  "@typescript-eslint/prefer-readonly": [
-    "error",
-    { "onlyInlineLambdas": true },
-  ],
-}
-```
-
-Example of code for the `{ "onlyInlineLambdas": true }` options:
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts option='{ "onlyInlineLambdas": true }'
-class Container {
-  private onClick = () => {
-    /* ... */
-  };
-}
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts option='{ "onlyInlineLambdas": true }'
-class Container {
-  private neverModifiedPrivate = 'unchanged';
-}
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-If you aren't trying to enforce strong immutability guarantees, this rule may be too restrictive for your project.

package/docs/rules/prefer-reduce-type-parameter.mdx

@@ -1,66 +0,0 @@
----
-description: 'Enforce using type parameter when calling `Array#reduce` instead of using a type assertion.'
----
-
-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-reduce-type-parameter** for documentation.
-
-It's common to call `Array#reduce` with a generic type, such as an array or object, as the initial value.
-Since these values are empty, their types are not usable:
-
-- `[]` has type `never[]`, which can't have items pushed into it as nothing is type `never`
-- `{}` has type `{}`, which doesn't have an index signature and so can't have properties added to it
-
-A common solution to this problem is to use an `as` assertion on the initial value.
-While this will work, it's not the most optimal solution as type assertions have subtle effects on the underlying types that can allow bugs to slip in.
-
-A better solution is to pass the type in as a generic type argument to `Array#reduce` explicitly.
-This means that TypeScript doesn't have to try to infer the type, and avoids the common pitfalls that come with assertions.
-
-This rule looks for calls to `Array#reduce`, and reports if an initial value is being passed & asserted.
-It will suggest instead pass the asserted type to `Array#reduce` as a generic type argument.
-
-## Examples
-
-<Tabs>
-<TabItem value="❌ Incorrect">
-
-```ts
-[1, 2, 3].reduce((arr, num) => arr.concat(num * 2), [] as number[]);
-
-['a', 'b'].reduce(
-  (accum, name) => ({
-    ...accum,
-    [name]: true,
-  }),
-  {} as Record<string, boolean>,
-);
-```
-
-</TabItem>
-<TabItem value="✅ Correct">
-
-```ts
-[1, 2, 3].reduce<number[]>((arr, num) => arr.concat(num * 2), []);
-
-['a', 'b'].reduce<Record<string, boolean>>(
-  (accum, name) => ({
-    ...accum,
-    [name]: true,
-  }),
-  {},
-);
-```
-
-</TabItem>
-</Tabs>
-
-## When Not To Use It
-
-This rule can sometimes be difficult to work around when creating objects using a `.reduce`.
-See [[prefer-reduce-type-parameter] unfixable reporting #3440](https://github.com/typescript-eslint/typescript-eslint/issues/3440) for more details.
-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.