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

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-explicit-any.md

@@ -0,0 +1,174 @@
+---
+description: 'Disallow the `any` type.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-explicit-any** 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.
+This rule reports on explicit uses of the `any` keyword as a type annotation.
+
+> TypeScript's `--noImplicitAny` compiler option prevents an implied `any`, but doesn't prevent `any` from being explicitly used the way this rule does.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const age: any = 'seventeen';
+```
+
+```ts
+const ages: any[] = ['seventeen'];
+```
+
+```ts
+const ages: Array<any> = ['seventeen'];
+```
+
+```ts
+function greet(): any {}
+```
+
+```ts
+function greet(): any[] {}
+```
+
+```ts
+function greet(): Array<any> {}
+```
+
+```ts
+function greet(): Array<Array<any>> {}
+```
+
+```ts
+function greet(param: Array<any>): string {}
+```
+
+```ts
+function greet(param: Array<any>): Array<any> {}
+```
+
+### ✅ Correct
+
+```ts
+const age: number = 17;
+```
+
+```ts
+const ages: number[] = [17];
+```
+
+```ts
+const ages: Array<number> = [17];
+```
+
+```ts
+function greet(): string {}
+```
+
+```ts
+function greet(): string[] {}
+```
+
+```ts
+function greet(): Array<string> {}
+```
+
+```ts
+function greet(): Array<Array<string>> {}
+```
+
+```ts
+function greet(param: Array<string>): string {}
+```
+
+```ts
+function greet(param: Array<string>): Array<string> {}
+```
+
+## Options
+
+### `ignoreRestArgs`
+
+A boolean to specify if arrays from the rest operator are considered okay. `false` by default.
+
+Examples of **incorrect** code for the `{ "ignoreRestArgs": false }` option:
+
+```ts
+/*eslint @typescript-eslint/no-explicit-any: ["error", { "ignoreRestArgs": false }]*/
+
+function foo1(...args: any[]): void {}
+function foo2(...args: readonly any[]): void {}
+function foo3(...args: Array<any>): void {}
+function foo4(...args: ReadonlyArray<any>): void {}
+
+declare function bar(...args: any[]): void;
+
+const baz = (...args: any[]) => {};
+const qux = function (...args: any[]) {};
+
+type Quux = (...args: any[]) => void;
+type Quuz = new (...args: any[]) => void;
+
+interface Grault {
+  (...args: any[]): void;
+}
+interface Corge {
+  new (...args: any[]): void;
+}
+interface Garply {
+  f(...args: any[]): void;
+}
+```
+
+Examples of **correct** code for the `{ "ignoreRestArgs": true }` option:
+
+```ts
+/*eslint @typescript-eslint/no-explicit-any: ["error", { "ignoreRestArgs": true }]*/
+
+function foo1(...args: any[]): void {}
+function foo2(...args: readonly any[]): void {}
+function foo3(...args: Array<any>): void {}
+function foo4(...args: ReadonlyArray<any>): void {}
+
+declare function bar(...args: any[]): void;
+
+const baz = (...args: any[]) => {};
+const qux = function (...args: any[]) {};
+
+type Quux = (...args: any[]) => void;
+type Quuz = new (...args: any[]) => void;
+
+interface Grault {
+  (...args: any[]): void;
+}
+interface Corge {
+  new (...args: any[]): void;
+}
+interface Garply {
+  f(...args: any[]): void;
+}
+```
+
+## When Not To Use It
+
+If an unknown type or a library without typings is used
+and you want to be able to specify `any`.
+
+## Related To
+
+- [`no-unsafe-argument`](./no-unsafe-argument.md)
+- [`no-unsafe-assignment`](./no-unsafe-assignment.md)
+- [`no-unsafe-call`](./no-unsafe-call.md)
+- [`no-unsafe-member-access`](./no-unsafe-member-access.md)
+- [`no-unsafe-return`](./no-unsafe-return.md)
+
+## Further Reading
+
+- TypeScript [any type](https://www.typescriptlang.org/docs/handbook/basic-types.html#any)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-extra-non-null-assertion.md

@@ -0,0 +1,52 @@
+---
+description: 'Disallow extra non-null assertions.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-extra-non-null-assertion** for documentation.
+
+The `!` non-null assertion operator in TypeScript is used to assert that a value's type does not include `null` or `undefined`.
+Using the operator any more than once on a single value does nothing.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const foo: { bar: number } | null = null;
+const bar = foo!!!.bar;
+```
+
+```ts
+function foo(bar: number | undefined) {
+  const bar: number = bar!!!;
+}
+```
+
+```ts
+function foo(bar?: { n: number }) {
+  return bar!?.n;
+}
+```
+
+### ✅ Correct
+
+```ts
+const foo: { bar: number } | null = null;
+const bar = foo!.bar;
+```
+
+```ts
+function foo(bar: number | undefined) {
+  const bar: number = bar!;
+}
+```
+
+```ts
+function foo(bar?: { n: number }) {
+  return bar?.n;
+}
+```

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-extra-parens.md

@@ -0,0 +1,12 @@
+---
+description: 'Disallow unnecessary parentheses.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-extra-parens** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/no-extra-parens`](https://eslint.org/docs/rules/no-extra-parens) rule.
+It adds support for TypeScript type assertions.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-extra-semi.md

@@ -0,0 +1,12 @@
+---
+description: 'Disallow unnecessary semicolons.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-extra-semi** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/no-extra-semi`](https://eslint.org/docs/rules/no-extra-semi) rule.
+It adds support for class properties.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-extraneous-class.md

@@ -0,0 +1,294 @@
+---
+description: 'Disallow classes used as namespaces.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-extraneous-class** for documentation.
+
+This rule reports when a class has no non-static members, such as for a class used exclusively as a static namespace.
+
+Users who come from a [OOP](https://en.wikipedia.org/wiki/Object-oriented_programming) paradigm may wrap their utility functions in an extra class, instead of putting them at the top level of an ECMAScript module.
+Doing so is generally unnecessary in JavaScript and TypeScript projects.
+
+- Wrapper classes add extra cognitive complexity to code without adding any structural improvements
+  - Whatever would be put on them, such as utility functions, are already organized by virtue of being in a module.
+  - As an alternative, you can `import * as ...` the module to get all of them in a single object.
+- IDEs can't provide as good suggestions for static class or namespace imported properties when you start typing property names
+- It's more difficult to statically analyze code for unused variables, etc. when they're all on the class (see: [Finding dead code (and dead types) in TypeScript](https://effectivetypescript.com/2020/10/20/tsprune)).
+
+This rule also reports classes that have only a constructor and no fields.
+Those classes can generally be replaced with a standalone function.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+class StaticConstants {
+  static readonly version = 42;
+
+  static isProduction() {
+    return process.env.NODE_ENV === 'production';
+  }
+}
+
+class HelloWorldLogger {
+  constructor() {
+    console.log('Hello, world!');
+  }
+}
+```
+
+### ✅ Correct
+
+```ts
+export const version = 42;
+
+export function isProduction() {
+  return process.env.NODE_ENV === 'production';
+}
+
+function logHelloWorld() {
+  console.log('Hello, world!');
+}
+```
+
+## Alternatives
+
+### Individual Exports (Recommended)
+
+Instead of using a static utility class we recommend you individually export the utilities from your module.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+export class Utilities {
+  static util1() {
+    return Utilities.util3();
+  }
+
+  static util2() {
+    /* ... */
+  }
+
+  static util3() {
+    /* ... */
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+export function util1() {
+  return util3();
+}
+
+export function util2() {
+  /* ... */
+}
+
+export function util3() {
+  /* ... */
+}
+```
+
+### Namespace Imports (Not Recommended)
+
+If you strongly prefer to have all constructs from a module available as properties of a single object, you can `import * as` the module.
+This is known as a "namespace import".
+Namespace imports are sometimes preferable because they keep all properties nested and don't need to be changed as you start or stop using various properties from the module.
+
+However, namespace imports are impacted by these downsides:
+
+- They also don't play as well with tree shaking in modern bundlers
+- They require a name prefix before each property's usage
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+// utilities.ts
+export class Utilities {
+  static sayHello() {
+    console.log('Hello, world!');
+  }
+}
+
+// consumers.ts
+import { Utilities } from './utilities';
+
+Utilities.sayHello();
+```
+
+#### ⚠️ Namespace Imports
+
+```ts
+// utilities.ts
+export function sayHello() {
+  console.log('Hello, world!');
+}
+
+// consumers.ts
+import * as utilities from './utilities';
+
+utilities.sayHello();
+```
+
+#### ✅ Standalone Imports
+
+```ts
+// utilities.ts
+export function sayHello() {
+  console.log('Hello, world!');
+}
+
+// consumers.ts
+import { sayHello } from './utilities';
+
+sayHello();
+```
+
+### Notes on Mutating Variables
+
+One case you need to be careful of is exporting mutable variables.
+While class properties can be mutated externally, exported variables are always constant.
+This means that importers can only ever read the first value they are assigned and cannot write to the variables.
+
+Needing to write to an exported variable is very rare and is generally considered a code smell.
+If you do need it you can accomplish it using getter and setter functions:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+export class Utilities {
+  static mutableCount = 1;
+
+  static incrementCount() {
+    Utilities.mutableCount += 1;
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+let mutableCount = 1;
+
+export function getMutableCount() {
+  return mutableField;
+}
+
+export function incrementCount() {
+  mutableField += 1;
+}
+```
+
+## Options
+
+This rule normally bans classes that are empty (have no constructor or fields).
+The rule's options each add an exemption for a specific type of class.
+
+### `allowConstructorOnly`
+
+`allowConstructorOnly` adds an exemption for classes that have only a constructor and no fields.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class NoFields {}
+```
+
+#### ✅ Correct
+
+```ts
+class NoFields {
+  constructor() {
+    console.log('Hello, world!');
+  }
+}
+```
+
+### `allowEmpty`
+
+The `allowEmpty` option adds an exemption for classes that are entirely empty.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class NoFields {
+  constructor() {
+    console.log('Hello, world!');
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+class NoFields {}
+```
+
+### `allowStaticOnly`
+
+The `allowStaticOnly` option adds an exemption for classes that only contain static members.
+
+:::caution
+We strongly recommend against the `allowStaticOnly` exemption.
+It works against this rule's primary purpose of discouraging classes used only for static members.
+:::
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class EmptyClass {}
+```
+
+#### ✅ Correct
+
+```ts
+class NotEmptyClass {
+  static version = 42;
+}
+```
+
+### `allowWithDecorator`
+
+The `allowWithDecorator` option adds an exemption for classes that contain a member decorated with a `@` decorator.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+class Constants {
+  static readonly version = 42;
+}
+```
+
+#### ✅ Correct
+
+```ts
+class Constants {
+  @logOnRead()
+  static readonly version = 42;
+}
+```
+
+## When Not To Use It
+
+You can disable this rule if you are unable -or unwilling- to switch off using classes as namespaces.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-floating-promises.md

@@ -0,0 +1,106 @@
+---
+description: 'Require Promise-like statements to be handled appropriately.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-floating-promises** for documentation.
+
+A "floating" Promise is one that is created without any code set up to handle any errors it might throw.
+Floating Promises can cause several issues, such as improperly sequenced operations, ignored Promise rejections, and more.
+
+This rule reports when a Promise is created and not properly handled.
+Valid ways of handling a Promise-valued statement include:
+
+- `await`ing it
+- `return`ing it
+- Calling its `.then()` with two arguments
+- Calling its `.catch()` with one argument
+
+:::tip
+`no-floating-promises` only detects unhandled Promise _statements_.
+See [`no-misused-promises`](./no-misused-promises.md) for detecting code that provides Promises to _logical_ locations such as if statements.
+:::
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+const promise = new Promise((resolve, reject) => resolve('value'));
+promise;
+
+async function returnsPromise() {
+  return 'value';
+}
+returnsPromise().then(() => {});
+
+Promise.reject('value').catch();
+
+Promise.reject('value').finally();
+```
+
+### ✅ Correct
+
+```ts
+const promise = new Promise((resolve, reject) => resolve('value'));
+await promise;
+
+async function returnsPromise() {
+  return 'value';
+}
+returnsPromise().then(
+  () => {},
+  () => {},
+);
+
+Promise.reject('value').catch(() => {});
+
+Promise.reject('value').finally(() => {});
+```
+
+## Options
+
+### `ignoreVoid`
+
+This allows you to stop the rule reporting promises consumed with void operator.
+This can be a good way to explicitly mark a promise as intentionally not awaited.
+
+Examples of **correct** code for this rule with `{ ignoreVoid: true }`:
+
+```ts
+async function returnsPromise() {
+  return 'value';
+}
+void returnsPromise();
+
+void Promise.reject('value');
+```
+
+With this option set to `true`, and if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option.
+
+### `ignoreIIFE`
+
+This allows you to skip checking of async IIFEs (Immediately Invocated function Expressions).
+
+Examples of **correct** code for this rule with `{ ignoreIIFE: true }`:
+
+```ts
+await(async function () {
+  await res(1);
+})();
+
+(async function () {
+  await res(1);
+})();
+```
+
+## When Not To Use It
+
+If you do not use Promise-like values in your codebase, or want to allow them to remain unhandled.
+
+## Related To
+
+- [`no-misused-promises`](./no-misused-promises.md)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/no-for-in-array.md

@@ -0,0 +1,56 @@
+---
+description: 'Disallow iterating over an array with a for-in loop.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/no-for-in-array** for documentation.
+
+A for-in loop (`for (var i in o)`) iterates over the properties of an Object.
+While it is legal to use for-in loops with array types, it is not common.
+for-in will iterate over the indices of the array as strings, omitting any "holes" in
+the array.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```js
+declare const array: string[];
+
+for (const i in array) {
+  console.log(array[i]);
+}
+
+for (const i in array) {
+  console.log(i, array[i]);
+}
+```
+
+### ✅ Correct
+
+```js
+declare const array: string[];
+
+for (const value of array) {
+  console.log(value);
+}
+
+for (let i = 0; i < array.length; i += 1) {
+  console.log(i, array[i]);
+}
+
+array.forEach((value, i) => {
+  console.log(i, value);
+})
+
+for (const [i, value] of array.entries()) {
+  console.log(i, value);
+}
+```
+
+## When Not To Use It
+
+If you want to iterate through a loop using the indices in an array as strings, you can turn off this rule.