repoburg 1.3.98 → 1.3.99

package/backend/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-optional-chain.md

@@ -1,263 +0,0 @@
----
-description: 'Enforce using concise optional chain expressions instead of chained logical ands, negated logical ors, or empty objects.'
----
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/prefer-optional-chain** for documentation.
-
-`?.` optional chain expressions provide `undefined` if an object is `null` or `undefined`.
-Because the optional chain operator _only_ chains when the property value is `null` or `undefined`, it is much safer than relying upon logical AND operator chaining `&&`; which chains on any _truthy_ value.
-It is also often less code to use `?.` optional chaining than `&&` truthiness checks.
-
-This rule reports on code where an `&&` operator can be safely replaced with `?.` optional chaining.
-
-## Examples
-
-<!--tabs-->
-
-### ❌ Incorrect
-
-```ts
-foo && foo.a && foo.a.b && foo.a.b.c;
-foo && foo['a'] && foo['a'].b && foo['a'].b.c;
-foo && foo.a && foo.a.b && foo.a.b.method && foo.a.b.method();
-
-// With empty objects
-(((foo || {}).a || {}).b || {}).c;
-(((foo || {})['a'] || {}).b || {}).c;
-
-// With negated `or`s
-!foo || !foo.bar;
-!foo || !foo[bar];
-!foo || !foo.bar || !foo.bar.baz || !foo.bar.baz();
-
-// this rule also supports converting chained strict nullish checks:
-foo &&
-  foo.a != null &&
-  foo.a.b !== null &&
-  foo.a.b.c != undefined &&
-  foo.a.b.c.d !== undefined &&
-  foo.a.b.c.d.e;
-```
-
-### ✅ Correct
-
-```ts
-foo?.a?.b?.c;
-foo?.['a']?.b?.c;
-foo?.a?.b?.method?.();
-
-foo?.a?.b?.c?.d?.e;
-
-!foo?.bar;
-!foo?.[bar];
-!foo?.bar?.baz?.();
-```
-
-<!--/tabs-->
-
-## Options
-
-In the context of the descriptions below a "loose boolean" operand is any operand that implicitly coerces the value to a boolean.
-Specifically the argument of the not operator (`!loose`) or a bare value in a logical expression (`loose && looser`).
-
-### `allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing`
-
-When this option is `true`, the rule will not provide an auto-fixer for cases where the return type of the expression would change. For example for the expression `!foo || foo.bar` the return type of the expression is `true | T`, however for the equivalent optional chain `foo?.bar` the return type of the expression is `undefined | T`. Thus changing the code from a logical expression to an optional chain expression has altered the type of the expression.
-
-In some cases this distinction _may_ matter - which is why these fixers are considered unsafe - they may break the build! For example in the following code:
-
-```ts option='{ "allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing": true }' showPlaygroundButton
-declare const foo: { bar: boolean } | null | undefined;
-declare function acceptsBoolean(arg: boolean): void;
-
-// ✅ typechecks succesfully as the expression only returns `boolean`
-acceptsBoolean(foo != null && foo.bar);
-
-// ❌ typechecks UNSUCCESSFULLY as the expression returns `boolean | undefined`
-acceptsBoolean(foo?.bar);
-```
-
-This style of code isn't super common - which means having this option set to `true` _should_ be safe in most codebases. However we default it to `false` due to its unsafe nature. We have provided this option for convenience because it increases the autofix cases covered by the rule. If you set option to `true` the onus is entirely on you and your team to ensure that each fix is correct and safe and that it does not break the build.
-
-When this option is `false` unsafe cases will have suggestion fixers provided instead of auto-fixers - meaning you can manually apply the fix using your IDE tooling.
-
-### `checkAny`
-
-When this option is `true` the rule will check operands that are typed as `any` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkAny: true`
-
-```ts option='{ "checkAny": true }'
-declare const thing: any;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkAny: false`
-
-```ts option='{ "checkAny": false }'
-declare const thing: any;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `checkUnknown`
-
-When this option is `true` the rule will check operands that are typed as `unknown` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkUnknown: true`
-
-```ts option='{ "checkUnknown": true }'
-declare const thing: unknown;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkUnknown: false`
-
-```ts option='{ "checkUnknown": false }'
-declare const thing: unknown;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `checkString`
-
-When this option is `true` the rule will check operands that are typed as `string` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkString: true`
-
-```ts option='{ "checkString": true }'
-declare const thing: string;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkString: false`
-
-```ts option='{ "checkString": false }'
-declare const thing: string;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `checkNumber`
-
-When this option is `true` the rule will check operands that are typed as `number` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkNumber: true`
-
-```ts option='{ "checkNumber": true }'
-declare const thing: number;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkNumber: false`
-
-```ts option='{ "checkNumber": false }'
-declare const thing: number;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `checkBoolean`
-
-When this option is `true` the rule will check operands that are typed as `boolean` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkBoolean: true`
-
-```ts option='{ "checkBoolean": true }'
-declare const thing: boolean;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkBoolean: false`
-
-```ts option='{ "checkBoolean": false }'
-declare const thing: boolean;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `checkBigInt`
-
-When this option is `true` the rule will check operands that are typed as `bigint` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `checkBigInt: true`
-
-```ts option='{ "checkBigInt": true }'
-declare const thing: bigint;
-
-thing && thing.toString();
-```
-
-#### ✅ Correct for `checkBigInt: false`
-
-```ts option='{ "checkBigInt": false }'
-declare const thing: bigint;
-
-thing && thing.toString();
-```
-
-<!--/tabs-->
-
-### `requireNullish`
-
-When this option is `true` the rule will skip operands that are not typed with `null` and/or `undefined` when inspecting "loose boolean" operands.
-
-<!--tabs-->
-
-#### ❌ Incorrect for `requireNullish: true`
-
-```ts option='{ "requireNullish": true }'
-declare const thing1: string | null;
-thing1 && thing1.toString();
-```
-
-#### ✅ Correct for `requireNullish: true`
-
-```ts option='{ "requireNullish": true }'
-declare const thing1: string | null;
-thing1?.toString();
-
-declare const thing2: string;
-thing2 && thing2.toString();
-```
-
-<!--/tabs-->
-
-## When Not To Use It
-
-If your project is not accurately typed, such as if it's in the process of being converted to TypeScript or is susceptible to [trade-offs in control flow analysis](https://github.com/Microsoft/TypeScript/issues/9998), it may be difficult to enable this rule for particularly non-type-safe areas of code.
-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
-
-- [TypeScript 3.7 Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html)
-- [Optional Chaining Proposal](https://github.com/tc39/proposal-optional-chaining/)

package/backend/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-promise-reject-errors.md

@@ -1,50 +0,0 @@
----
-description: 'Require using Error objects as Promise rejection reasons.'
----
-
-> 🛑 This file is source code, not the primary documentation location! 🛑
->
-> See **https://typescript-eslint.io/rules/prefer-promise-reject-errors** for documentation.
-
-This rule extends the base [`eslint/prefer-promise-reject-errors`](https://eslint.org/docs/rules/prefer-promise-reject-errors) rule.
-It uses type information to enforce that `Promise`s are only rejected with `Error` objects.
-
-## Examples
-
-<!--tabs-->
-
-### ❌ 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);
-});
-```
-
-### ✅ 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());
-});
-```

package/backend/node_modules/@typescript-eslint/eslint-plugin/docs/rules/prefer-readonly-parameter-types.md

@@ -1,389 +0,0 @@
----
-description: 'Require function parameters to be typed as `readonly` to prevent accidental mutation of inputs.'
----
-
-> 🛑 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-->
-
-### ❌ 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;
-}
-```
-
-### ✅ 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;
-}
-```
-
-## 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": [
-    "$",
-    { "source": "file", "name": "Foo" },
-    { "source": "lib", "name": "HTMLElement" },
-    { "from": "package", "name": "Bar", "package": "bar-lib" }
-  ]
-}
-```
-
-<!--tabs-->
-
-#### ❌ Incorrect
-
-```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"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":["$",{"source":"file","name":"Foo"},{"source":"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) {}
-```
-
-#### ✅ Correct
-
-```ts option='{"allow":["$",{"source":"file","name":"Foo"},{"source":"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":["$",{"source":"file","name":"Foo"},{"source":"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":["$",{"source":"file","name":"Foo"},{"source":"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) {}
-```
-
-### `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-->
-
-#### ❌ Incorrect
-
-```ts option='{ "checkParameterProperties": true }'
-class Foo {
-  constructor(private paramProp: string[]) {}
-}
-```
-
-#### ✅ Correct
-
-```ts option='{ "checkParameterProperties": true }'
-class Foo {
-  constructor(private paramProp: readonly string[]) {}
-}
-```
-
-<!--/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-->
-
-#### ❌ 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>
-
-#### ✅ 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>
-
-### `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-->
-
-#### ❌ Incorrect
-
-```ts option='{ "treatMethodsAsReadonly": false }'
-type MyType = {
-  readonly prop: string;
-  method(): string; // note: this method is mutable
-};
-function foo(arg: MyType) {}
-```
-
-#### ✅ 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) {}
-```
-
-<!--/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.