@nr1e/commons 0.1.0-alpha.1 → 0.1.1-alpha.0

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-boolean-literal-compare.md

@@ -0,0 +1,133 @@
+---
+description: 'Disallow unnecessary equality comparisons against boolean literals.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-boolean-literal-compare** for documentation.
+
+Comparing boolean values to boolean literals is unnecessary: those comparisons result in the same booleans.
+Using the boolean values directly, or via a unary negation (`!value`), is more concise and clearer.
+
+This rule ensures that you do not include unnecessary comparisons with boolean literals.
+A comparison is considered unnecessary if it checks a boolean literal against any variable with just the `boolean` type.
+A comparison is **_not_** considered unnecessary if the type is a union of booleans (`string | boolean`, `SomeObject | boolean`, etc.).
+
+## Examples
+
+:::note
+Throughout this page, only strict equality (`===` and `!==`) are used in the examples.
+However, the implementation of the rule does not distinguish between strict and loose equality.
+Any example below that uses `===` would be treated the same way if `==` was used, and `!==` would be treated the same way if `!=` was used.
+:::
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+declare const someCondition: boolean;
+if (someCondition === true) {
+}
+```
+
+### ✅ Correct
+
+```ts
+declare const someCondition: boolean;
+if (someCondition) {
+}
+
+declare const someObjectBoolean: boolean | Record<string, unknown>;
+if (someObjectBoolean === true) {
+}
+
+declare const someStringBoolean: boolean | string;
+if (someStringBoolean === true) {
+}
+```
+
+## Options
+
+This rule always checks comparisons between a boolean variable and a boolean
+literal. Comparisons between nullable boolean variables and boolean literals
+are **not** checked by default.
+
+### `allowComparingNullableBooleansToTrue`
+
+Examples of code for this rule with `{ allowComparingNullableBooleansToTrue: false }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+declare const someUndefinedCondition: boolean | undefined;
+if (someUndefinedCondition === true) {
+}
+
+declare const someNullCondition: boolean | null;
+if (someNullCondition !== true) {
+}
+```
+
+#### ✅ Correct
+
+```ts
+declare const someUndefinedCondition: boolean | undefined;
+if (someUndefinedCondition) {
+}
+
+declare const someNullCondition: boolean | null;
+if (!someNullCondition) {
+}
+```
+
+### `allowComparingNullableBooleansToFalse`
+
+Examples of code for this rule with `{ allowComparingNullableBooleansToFalse: false }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+declare const someUndefinedCondition: boolean | undefined;
+if (someUndefinedCondition === false) {
+}
+
+declare const someNullCondition: boolean | null;
+if (someNullCondition !== false) {
+}
+```
+
+#### ✅ Correct
+
+```ts
+declare const someUndefinedCondition: boolean | undefined;
+if (someUndefinedCondition ?? true) {
+}
+
+declare const someNullCondition: boolean | null;
+if (!(someNullCondition ?? true)) {
+}
+```
+
+## Fixer
+
+|            Comparison             | Fixer Output                    | Notes                                                                               |
+| :-------------------------------: | ------------------------------- | ----------------------------------------------------------------------------------- |
+|       `booleanVar === true`       | `booleanVar`                    |                                                                                     |
+|       `booleanVar !== true`       | `!booleanVar`                   |                                                                                     |
+|      `booleanVar === false`       | `!booleanVar`                   |                                                                                     |
+|      `booleanVar !== false`       | `booleanVar`                    |                                                                                     |
+|   `nullableBooleanVar === true`   | `nullableBooleanVar`            | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
+|   `nullableBooleanVar !== true`   | `!nullableBooleanVar`           | Only checked/fixed if the `allowComparingNullableBooleansToTrue` option is `false`  |
+| `!(nullableBooleanVar === false)` | `nullableBooleanVar ?? true`    | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
+| `!(nullableBooleanVar !== false)` | `!(nullableBooleanVar ?? true)` | Only checked/fixed if the `allowComparingNullableBooleansToFalse` option is `false` |
+
+## Not To Use It
+
+Do not use this rule when `strictNullChecks` is disabled.
+ESLint is not able to distinguish between `false` and `undefined` or `null` values.
+This can cause unintended code changes when using autofix.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-condition.md

@@ -0,0 +1,103 @@
+---
+description: 'Disallow conditionals where the type is always truthy or always falsy.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-condition** for documentation.
+
+Any expression being used as a condition must be able to evaluate as truthy or falsy in order to be considered "necessary".
+Conversely, any expression that always evaluates to truthy or always evaluates to falsy, as determined by the type of the expression, is considered unnecessary and will be flagged by this rule.
+
+The following expressions are checked:
+
+- Arguments to the `&&`, `||` and `?:` (ternary) operators
+- Conditions for `if`, `for`, `while`, and `do-while` statements
+- Base values of optional chain expressions
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+function head<T>(items: T[]) {
+  // items can never be nullable, so this is unnecessary
+  if (items) {
+    return items[0].toUpperCase();
+  }
+}
+
+function foo(arg: 'bar' | 'baz') {
+  // arg is never nullable or empty string, so this is unnecessary
+  if (arg) {
+  }
+}
+
+function bar<T>(arg: string) {
+  // arg can never be nullish, so ?. is unnecessary
+  return arg?.length;
+}
+
+// Checks array predicate return types, where possible
+[
+  [1, 2],
+  [3, 4],
+].filter(t => t); // number[] is always truthy
+```
+
+### ✅ Correct
+
+```ts
+function head<T>(items: T[]) {
+  // Necessary, since items.length might be 0
+  if (items.length) {
+    return items[0].toUpperCase();
+  }
+}
+
+function foo(arg: string) {
+  // Necessary, since foo might be ''.
+  if (arg) {
+  }
+}
+
+function bar(arg?: string | null) {
+  // Necessary, since arg might be nullish
+  return arg?.length;
+}
+
+[0, 1, 2, 3].filter(t => t); // number can be truthy or falsy
+```
+
+## Options
+
+### `allowConstantLoopConditions`
+
+Example of correct code for `{ allowConstantLoopConditions: true }`:
+
+```ts
+while (true) {}
+for (; true; ) {}
+do {} while (true);
+```
+
+### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing`
+
+If this is set to `false`, then the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.
+
+Without `strictNullChecks`, TypeScript essentially erases `undefined` and `null` from the types. This means when this rule inspects the types from a variable, **it will not be able to tell that the variable might be `null` or `undefined`**, which essentially makes this rule useless.
+
+You should be using `strictNullChecks` to ensure complete type-safety in your codebase.
+
+If for some reason you cannot turn on `strictNullChecks`, but still want to use this rule - you can use this option to allow it - but know that the behavior of this rule is _undefined_ with the compiler option turned off. We will not accept bug reports if you are using this option.
+
+## When Not To Use It
+
+The main downside to using this rule is the need for type information.
+
+## Related To
+
+- ESLint: [no-constant-condition](https://eslint.org/docs/rules/no-constant-condition) - `no-unnecessary-condition` is essentially a stronger version of `no-constant-condition`, but requires type information.
+- [strict-boolean-expressions](./strict-boolean-expressions.md) - a more opinionated version of `no-unnecessary-condition`. `strict-boolean-expressions` enforces a specific code style, while `no-unnecessary-condition` is about correctness.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-qualifier.md

@@ -0,0 +1,51 @@
+---
+description: 'Disallow unnecessary namespace qualifiers.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-qualifier** for documentation.
+
+Members of TypeScript enums and namespaces are generally retrieved as qualified property lookups: e.g. `Enum.member`.
+However, when accessed within their parent enum or namespace, the qualifier is unnecessary: e.g. just `member` instead of `Enum.member`.
+This rule reports when an enum or namespace qualifier is unnecessary.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+enum A {
+  B,
+  C = A.B,
+}
+```
+
+```ts
+namespace A {
+  export type B = number;
+  const x: A.B = 3;
+}
+```
+
+### ✅ Correct
+
+```ts
+enum A {
+  B,
+  C = B,
+}
+```
+
+```ts
+namespace A {
+  export type B = number;
+  const x: B = 3;
+}
+```
+
+## When Not To Use It
+
+If you don't care about having unneeded enum or namespace qualifiers, then you don't need to use this rule.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-type-arguments.md

@@ -0,0 +1,73 @@
+---
+description: 'Disallow type arguments that are equal to the default.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-type-arguments** for documentation.
+
+Type parameters in TypeScript may specify a default value.
+For example:
+
+```ts
+function f<T = number>(...) {...}
+```
+
+It is redundant to provide an explicit type parameter equal to that default: e.g. calling `f<number>(...)`.
+This rule reports when an explicitly specified type argument is the default for that type parameter.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+function f<T = number>() {}
+f<number>();
+```
+
+```ts
+function g<T = number, U = string>() {}
+g<string, string>();
+```
+
+```ts
+class C<T = number> {}
+new C<number>();
+
+class D extends C<number> {}
+```
+
+```ts
+interface I<T = number> {}
+class Impl implements I<number> {}
+```
+
+### ✅ Correct
+
+```ts
+function f<T = number>() {}
+f();
+f<string>();
+```
+
+```ts
+function g<T = number, U = string>() {}
+g<string>();
+g<number, number>();
+```
+
+```ts
+class C<T = number> {}
+new C();
+new C<string>();
+
+class D extends C {}
+class D extends C<string> {}
+```
+
+```ts
+interface I<T = number> {}
+class Impl implements I<string> {}
+```

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-type-assertion.md

@@ -0,0 +1,77 @@
+---
+description: 'Disallow type assertions that do not change the type of an expression.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-type-assertion** for documentation.
+
+TypeScript can be told an expression is a different type than expected using `as` type assertions.
+Leaving `as` assertions in the codebase increases visual clutter and harms code readability, so it's generally best practice to remove them if they don't change the type of an expression.
+This rule reports when a type assertion does not change the type of an expression.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const foo = 3;
+const bar = foo!;
+```
+
+```ts
+const foo = <3>3;
+```
+
+```ts
+type Foo = 3;
+const foo = <Foo>3;
+```
+
+```ts
+type Foo = 3;
+const foo = 3 as Foo;
+```
+
+```ts
+function foo(x: number): number {
+  return x!; // unnecessary non-null
+}
+```
+
+### ✅ Correct
+
+```ts
+const foo = <number>3;
+```
+
+```ts
+const foo = 3 as number;
+```
+
+```ts
+const foo = 'foo' as const;
+```
+
+```ts
+function foo(x: number | undefined): number {
+  return x!;
+}
+```
+
+## Options
+
+### `typesToIgnore`
+
+With `@typescript-eslint/no-unnecessary-type-assertion: ["error", { typesToIgnore: ['Foo'] }]`, the following is **correct** code":
+
+```ts
+type Foo = 3;
+const foo: Foo = 3;
+```
+
+## When Not To Use It
+
+If you don't care about having no-op type assertions in your code, then you can turn off this rule.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unnecessary-type-constraint.md

@@ -0,0 +1,55 @@
+---
+description: 'Disallow unnecessary constraints on generic types.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unnecessary-type-constraint** for documentation.
+
+Generic type parameters (`<T>`) in TypeScript may be "constrained" with an [`extends` keyword](https://www.typescriptlang.org/docs/handbook/generics.html#generic-constraints).
+When no `extends` is provided, type parameters default a constraint to `unknown`.
+It is therefore redundant to `extend` from `any` or `unknown`.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+interface FooAny<T extends any> {}
+
+interface FooUnknown<T extends unknown> {}
+
+type BarAny<T extends any> = {};
+
+type BarUnknown<T extends unknown> = {};
+
+class BazAny<T extends any> {
+  quxAny<U extends any>() {}
+}
+
+const QuuxAny = <T extends any>() => {};
+
+function QuuzAny<T extends any>() {}
+```
+
+### ✅ Correct
+
+```ts
+interface Foo<T> {}
+
+type Bar<T> = {};
+
+class Baz<T> {
+  qux<U> { }
+}
+
+const Quux = <T>() => {};
+
+function Quuz<T>() {}
+```
+
+## When Not To Use It
+
+If you don't care about the specific styles of your type constraints, or never use them in the first place, then you will not need this rule.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unsafe-argument.md

@@ -0,0 +1,83 @@
+---
+description: 'Disallow calling a function with a value with type `any`.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unsafe-argument** for documentation.
+
+The `any` type in TypeScript is a dangerous "escape hatch" from the type system.
+Using `any` disables many type checking rules and is generally best used only as a last resort or when prototyping code.
+
+Despite your best intentions, the `any` type can sometimes leak into your codebase.
+Calling a function with an `any` typed argument creates a potential safety hole and source of bugs.
+
+This rule disallows calling a function with `any` in its arguments.
+That includes spreading arrays or tuples with `any` typed elements as function arguments.
+
+This rule also compares generic type argument types to ensure you don't pass an unsafe `any` in a generic position to a receiver that's expecting a specific type.
+For example, it will error if you pass `Set<any>` as an argument to a parameter declared as `Set<string>`.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+declare function foo(arg1: string, arg2: number, arg3: string): void;
+
+const anyTyped = 1 as any;
+
+foo(...anyTyped);
+foo(anyTyped, 1, 'a');
+
+const anyArray: any[] = [];
+foo(...anyArray);
+
+const tuple1 = ['a', anyTyped, 'b'] as const;
+foo(...tuple1);
+
+const tuple2 = [1] as const;
+foo('a', ...tuple, anyTyped);
+
+declare function bar(arg1: string, arg2: number, ...rest: string[]): void;
+const x = [1, 2] as [number, ...number[]];
+foo('a', ...x, anyTyped);
+
+declare function baz(arg1: Set<string>, arg2: Map<string, string>): void;
+foo(new Set<any>(), new Map<any, string>());
+```
+
+### ✅ Correct
+
+```ts
+declare function foo(arg1: string, arg2: number, arg3: string): void;
+
+foo('a', 1, 'b');
+
+const tuple1 = ['a', 1, 'b'] as const;
+foo(...tuple1);
+
+declare function bar(arg1: string, arg2: number, ...rest: string[]): void;
+const array: string[] = ['a'];
+bar('a', 1, ...array);
+
+declare function baz(arg1: Set<string>, arg2: Map<string, string>): void;
+foo(new Set<string>(), new Map<string, string>());
+```
+
+<!--/tabs-->
+
+There are cases where the rule allows passing an argument of `any` to `unknown`.
+
+Example of `any` to `unknown` assignment that are allowed:
+
+```ts
+declare function foo(arg1: unknown, arg2: Set<unkown>, arg3: unknown[]): void;
+foo(1 as any, new Set<any>(), [] as any[]);
+```
+
+## Related To
+
+- [`no-explicit-any`](./no-explicit-any.md)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-unsafe-assignment.md

@@ -0,0 +1,86 @@
+---
+description: 'Disallow assigning a value with type `any` to variables and properties.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-unsafe-assignment** for documentation.
+
+The `any` type in TypeScript is a dangerous "escape hatch" from the type system.
+Using `any` disables many type checking rules and is generally best used only as a last resort or when prototyping code.
+
+Despite your best intentions, the `any` type can sometimes leak into your codebase.
+Assigning an `any` typed value to a variable can be hard to pick up on, particularly if it leaks in from an external library.
+
+This rule disallows assigning `any` to a variable, and assigning `any[]` to an array destructuring.
+
+This rule also compares generic type argument types to ensure you don't pass an unsafe `any` in a generic position to a receiver that's expecting a specific type.
+For example, it will error if you assign `Set<any>` to a variable declared as `Set<string>`.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const x = 1 as any,
+  y = 1 as any;
+const [x] = 1 as any;
+const [x] = [] as any[];
+const [x] = [1 as any];
+[x] = [1] as [any];
+
+function foo(a = 1 as any) {}
+class Foo {
+  constructor(private a = 1 as any) {}
+}
+class Foo {
+  private a = 1 as any;
+}
+
+// generic position examples
+const x: Set<string> = new Set<any>();
+const x: Map<string, string> = new Map<string, any>();
+const x: Set<string[]> = new Set<any[]>();
+const x: Set<Set<Set<string>>> = new Set<Set<Set<any>>>();
+```
+
+### ✅ Correct
+
+```ts
+const x = 1,
+  y = 1;
+const [x] = [1];
+[x] = [1] as [number];
+
+function foo(a = 1) {}
+class Foo {
+  constructor(private a = 1) {}
+}
+class Foo {
+  private a = 1;
+}
+
+// generic position examples
+const x: Set<string> = new Set<string>();
+const x: Map<string, string> = new Map<string, string>();
+const x: Set<string[]> = new Set<string[]>();
+const x: Set<Set<Set<string>>> = new Set<Set<Set<string>>>();
+```
+
+<!--/tabs-->
+
+There are cases where the rule allows assignment of `any` to `unknown`.
+
+Example of `any` to `unknown` assignment that are allowed:
+
+```ts
+const x: unknown = y as any;
+const x: unknown[] = y as any[];
+const x: Set<unknown> = y as Set<any>;
+```
+
+## Related To
+
+- [`no-explicit-any`](./no-explicit-any.md)