repoburg 1.1.0 → 1.1.1

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

@@ -0,0 +1,263 @@
+---
+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

@@ -0,0 +1,50 @@
+---
+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

@@ -0,0 +1,389 @@
+---
+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.