@alexlit/lint-kit 111.0.0 → 112.0.0

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx

@@ -0,0 +1,403 @@
+---
+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`
+
+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.
+
+Each item must be one of:
+
+- A type defined in a file (`{from: "file", name: "Foo", path: "src/foo-file.ts"}` with `path` being an optional path relative to the project root directory)
+- A type from the default library (`{from: "lib", name: "Foo"}`)
+- A type from a package (`{from: "package", name: "Foo", package: "foo-lib"}`, this also works for types defined in a typings package).
+
+Additionally, a type may be defined just as a simple string, which then matches the type independently of its origin.
+
+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`
+
+This option allows you to enable or disable the checking of parameter properties.
+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`
+
+This option allows you to ignore parameters which don't explicitly specify a type. 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 }'
+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 }'
+export interface CallbackOptions {
+  prop: string;
+}
+type Callback = (options: CallbackOptions) => void;
+type AcceptsCallback = (callback: Callback) => void;
+
+export const acceptsCallback: AcceptsCallback;
+```
+
+</details>
+
+</TabItem>
+</Tabs>
+
+### `treatMethodsAsReadonly`
+
+This option allows you to treat all mutable methods as though they were readonly. 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.

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

@@ -0,0 +1,111 @@
+---
+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`
+
+You may pass `"onlyInlineLambdas": true` as a rule option within an object to restrict checking only to members immediately assigned a lambda value.
+
+```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/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-reduce-type-parameter.mdx

@@ -0,0 +1,66 @@
+---
+description: 'Enforce using type parameter when calling `Array#reduce` instead of casting.'
+---
+
+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 casting.
+
+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.

package/packages/config-eslint/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-regexp-exec.mdx

@@ -0,0 +1,52 @@
+---
+description: 'Enforce `RegExp#exec` over `String#match` if no global flag is provided.'
+---
+
+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-regexp-exec** for documentation.
+
+`String#match` is defined to work the same as `RegExp#exec` when the regular expression does not include the `g` flag.
+Keeping to consistently using one of the two can help improve code readability.
+
+This rule reports when a `String#match` call can be replaced with an equivalent `RegExp#exec`.
+
+> `RegExp#exec` may also be slightly faster than `String#match`; this is the reason to choose it as the preferred usage.
+
+## Examples
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+'something'.match(/thing/);
+
+'some things are just things'.match(/thing/);
+
+const text = 'something';
+const search = /thing/;
+text.match(search);
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+/thing/.exec('something');
+
+'some things are just things'.match(/thing/g);
+
+const text = 'something';
+const search = /thing/;
+search.exec(text);
+```
+
+</TabItem>
+</Tabs>
+
+## 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.