@nr1e/commons 0.1.0 → 0.1.1-alpha.0

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/README.md

@@ -0,0 +1,23 @@
+---
+title: Overview
+sidebar_label: Overview
+pagination_next: null
+pagination_prev: null
+slug: /
+---
+
+`@typescript-eslint/eslint-plugin` includes over 100 rules that detect best practice violations, bugs, and/or stylistic issues specifically for TypeScript code.
+See [Configs](/linting/configs) for how to enable recommended rules using configs.
+
+## Supported Rules
+
+import RulesTable from "@site/src/components/RulesTable";
+
+<RulesTable ruleset="supported-rules" />
+
+## Extension Rules
+
+In some cases, ESLint provides a rule itself, but it doesn't support TypeScript syntax; either it crashes, or it ignores the syntax, or it falsely reports against it.
+In these cases, we create what we call an extension rule; a rule within our plugin that has the same functionality, but also supports TypeScript.
+
+<RulesTable ruleset="extension-rules" />

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/TEMPLATE.md

@@ -0,0 +1,26 @@
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/your-rule-name** for documentation.
+
+## Examples
+
+To fill out: tell us more about this rule.
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+// To fill out: incorrect code
+```
+
+### ✅ Correct
+
+```ts
+// To fill out: correct code
+```
+
+## When Not To Use It
+
+To fill out: why wouldn't you want to use this rule?
+For example if this rule requires a feature released in a certain TS version.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/adjacent-overload-signatures.md

@@ -0,0 +1,93 @@
+---
+description: 'Require that function overload signatures be consecutive.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/adjacent-overload-signatures** for documentation.
+
+Function overload signatures represent multiple ways a function can be called, potentially with different return types.
+It's typical for an interface or type alias describing a function to place all overload signatures next to each other.
+If Signatures placed elsewhere in the type are easier to be missed by future developers reading the code.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+declare namespace Foo {
+  export function foo(s: string): void;
+  export function foo(n: number): void;
+  export function bar(): void;
+  export function foo(sn: string | number): void;
+}
+
+type Foo = {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void;
+  foo(sn: string | number): void;
+};
+
+interface Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void;
+  foo(sn: string | number): void;
+}
+
+class Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  bar(): void {}
+  foo(sn: string | number): void {}
+}
+
+export function foo(s: string): void;
+export function foo(n: number): void;
+export function bar(): void;
+export function foo(sn: string | number): void;
+```
+
+### ✅ Correct
+
+```ts
+declare namespace Foo {
+  export function foo(s: string): void;
+  export function foo(n: number): void;
+  export function foo(sn: string | number): void;
+  export function bar(): void;
+}
+
+type Foo = {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void;
+  bar(): void;
+};
+
+interface Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void;
+  bar(): void;
+}
+
+class Foo {
+  foo(s: string): void;
+  foo(n: number): void;
+  foo(sn: string | number): void {}
+  bar(): void {}
+}
+
+export function bar(): void;
+export function foo(s: string): void;
+export function foo(n: number): void;
+export function foo(sn: string | number): void;
+```
+
+## When Not To Use It
+
+If you don't care about the general structure of the code, then you will not need this rule.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/array-type.md

@@ -0,0 +1,103 @@
+---
+description: 'Require consistently using either `T[]` or `Array<T>` for arrays.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/array-type** for documentation.
+
+TypeScript provides two equivalent ways to define an array type: `T[]` and `Array<T>`.
+The two styles are functionally equivalent.
+Using the same style consistently across your codebase makes it easier for developers to read and understand array types.
+
+## Options
+
+The default config will enforce that all mutable and readonly arrays use the `'array'` syntax.
+
+### `"array"`
+
+Always use `T[]` or `readonly T[]` for all array types.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const x: Array<string> = ['a', 'b'];
+const y: ReadonlyArray<string> = ['a', 'b'];
+```
+
+#### ✅ Correct
+
+```ts
+const x: string[] = ['a', 'b'];
+const y: readonly string[] = ['a', 'b'];
+```
+
+### `"generic"`
+
+Always use `Array<T>` or `ReadonlyArray<T>` for all array types.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const x: string[] = ['a', 'b'];
+const y: readonly string[] = ['a', 'b'];
+```
+
+#### ✅ Correct
+
+```ts
+const x: Array<string> = ['a', 'b'];
+const y: ReadonlyArray<string> = ['a', 'b'];
+```
+
+### `"array-simple"`
+
+Use `T[]` or `readonly T[]` for simple types (i.e. types which are just primitive names or type references).
+Use `Array<T>` or `ReadonlyArray<T>` for all other types (union types, intersection types, object types, function types, etc).
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const a: (string | number)[] = ['a', 'b'];
+const b: { prop: string }[] = [{ prop: 'a' }];
+const c: (() => void)[] = [() => {}];
+const d: Array<MyType> = ['a', 'b'];
+const e: Array<string> = ['a', 'b'];
+const f: ReadonlyArray<string> = ['a', 'b'];
+```
+
+#### ✅ Correct
+
+```ts
+const a: Array<string | number> = ['a', 'b'];
+const b: Array<{ prop: string }> = [{ prop: 'a' }];
+const c: Array<() => void> = [() => {}];
+const d: MyType[] = ['a', 'b'];
+const e: string[] = ['a', 'b'];
+const f: readonly string[] = ['a', 'b'];
+```
+
+## Combination Matrix
+
+This matrix lists all possible option combinations and their expected results for different types of Arrays.
+
+| defaultOption  | readonlyOption | Array with simple type | Array with non simple type | Readonly array with simple type | Readonly array with non simple type |
+| -------------- | -------------- | ---------------------- | -------------------------- | ------------------------------- | ----------------------------------- |
+| `array`        |                | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array`        | `array`        | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array`        | `array-simple` | `number[]`             | `(Foo & Bar)[]`            | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array`        | `generic`      | `number[]`             | `(Foo & Bar)[]`            | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` |                | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` | `array`        | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `array-simple` | `array-simple` | `number[]`             | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `array-simple` | `generic`      | `number[]`             | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      |                | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      | `array`        | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `readonly (Foo & Bar)[]`            |
+| `generic`      | `array-simple` | `Array<number>`        | `Array<Foo & Bar>`         | `readonly number[]`             | `ReadonlyArray<Foo & Bar>`          |
+| `generic`      | `generic`      | `Array<number>`        | `Array<Foo & Bar>`         | `ReadonlyArray<number>`         | `ReadonlyArray<Foo & Bar>`          |

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/await-thenable.md

@@ -0,0 +1,40 @@
+---
+description: 'Disallow awaiting a value that is not a Thenable.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/await-thenable** for documentation.
+
+A "Thenable" value is an object which has a `then` method, such as a Promise.
+The `await` keyword is generally used to retrieve the result of calling a Thenable's `then` method.
+
+If the `await` keyword is used on a value that is not a Thenable, the value is directly resolved immediately.
+While doing so is valid JavaScript, it is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+await 'value';
+
+const createValue = () => 'value';
+await createValue();
+```
+
+### ✅ Correct
+
+```ts
+await Promise.resolve('value');
+
+const createValue = async () => 'value';
+await createValue();
+```
+
+## When Not To Use It
+
+If you want to allow code to `await` non-Promise values.
+This is generally not preferred, but can sometimes be useful for visual consistency.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-ts-comment.md

@@ -0,0 +1,148 @@
+---
+description: 'Disallow `@ts-<directive>` comments or require descriptions after directives.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-ts-comment** for documentation.
+
+TypeScript provides several directive comments that can be used to alter how it processes files.
+Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall.
+Instead, it's generally better to correct the types of code, to make directives unnecessary.
+
+The directive comments supported by TypeScript are:
+
+```ts
+// @ts-expect-error
+// @ts-ignore
+// @ts-nocheck
+// @ts-check
+```
+
+This rule lets you set which directive comments you want to allow in your codebase.
+
+## Options
+
+By default, only `@ts-check` is allowed, as it enables rather than suppresses errors.
+
+### `ts-expect-error`, `ts-ignore`, `ts-nocheck`, `ts-check` directives
+
+A value of `true` for a particular directive means that this rule will report if it finds any usage of said directive.
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+if (false) {
+  // @ts-ignore: Unreachable code error
+  console.log('hello');
+}
+if (false) {
+  /*
+  @ts-ignore: Unreachable code error
+  */
+  console.log('hello');
+}
+```
+
+#### ✅ Correct
+
+```ts
+if (false) {
+  // Compiler warns about unreachable code error
+  console.log('hello');
+}
+```
+
+### `allow-with-description`
+
+A value of `'allow-with-description'` for a particular directive means that this rule will report if it finds a directive that does not have a description following the directive (on the same line).
+
+For example, with `{ 'ts-expect-error': 'allow-with-description' }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+if (false) {
+  // @ts-expect-error
+  console.log('hello');
+}
+if (false) {
+  /* @ts-expect-error */
+  console.log('hello');
+}
+```
+
+#### ✅ Correct
+
+```ts
+if (false) {
+  // @ts-expect-error: Unreachable code error
+  console.log('hello');
+}
+if (false) {
+  /*
+  @ts-expect-error: Unreachable code error
+  */
+  console.log('hello');
+}
+```
+
+### `descriptionFormat`
+
+For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed.
+
+For example, with `{ 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+// @ts-expect-error: the library definition is wrong
+const a = doSomething('hello');
+```
+
+#### ✅ Correct
+
+```ts
+// @ts-expect-error: TS1234 because the library definition is wrong
+const a = doSomething('hello');
+```
+
+### `minimumDescriptionLength`
+
+Use `minimumDescriptionLength` to set a minimum length for descriptions when using the `allow-with-description` option for a directive.
+
+For example, with `{ 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 }` the following pattern is:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+if (false) {
+  // @ts-expect-error: TODO
+  console.log('hello');
+}
+```
+
+#### ✅ Correct
+
+```ts
+if (false) {
+  // @ts-expect-error The rationale for this override is described in issue #1337 on GitLab
+  console.log('hello');
+}
+```
+
+## When Not To Use It
+
+If you want to use all of the TypeScript directives.
+
+## Further Reading
+
+- TypeScript [Type Checking JavaScript Files](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html)

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-tslint-comment.md

@@ -0,0 +1,39 @@
+---
+description: 'Disallow `// tslint:<rule-flag>` comments.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-tslint-comment** for documentation.
+
+Useful when migrating from TSLint to ESLint. Once TSLint has been removed, this rule helps locate TSLint annotations (e.g. `// tslint:disable`).
+
+> See the [TSLint rule flags docs](https://palantir.github.io/tslint/usage/rule-flags) for reference.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```js
+/* tslint:disable */
+/* tslint:enable */
+/* tslint:disable:rule1 rule2 rule3... */
+/* tslint:enable:rule1 rule2 rule3... */
+// tslint:disable-next-line
+someCode(); // tslint:disable-line
+// tslint:disable-next-line:rule1 rule2 rule3...
+```
+
+### ✅ Correct
+
+```js
+// This is a comment that just happens to mention tslint
+/* This is a multiline comment that just happens to mention tslint */
+someCode(); // This is a comment that just happens to mention tslint
+```
+
+## When Not To Use It
+
+If you are still using TSLint.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/ban-types.md

@@ -0,0 +1,183 @@
+---
+description: 'Disallow certain types.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/ban-types** for documentation.
+
+Some built-in types have aliases, while some types are considered dangerous or harmful.
+It's often a good idea to ban certain types to help with consistency and safety.
+
+This rule bans specific types and can suggest alternatives.
+Note that it does not ban the corresponding runtime objects from being used.
+
+## Examples
+
+Examples of code with the default options:
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+// use lower-case primitives for consistency
+const str: String = 'foo';
+const bool: Boolean = true;
+const num: Number = 1;
+const symb: Symbol = Symbol('foo');
+const bigInt: BigInt = 1n;
+
+// use a proper function type
+const func: Function = () => 1;
+
+// use safer object types
+const lowerObj: Object = {};
+const capitalObj: Object = { a: 'string' };
+
+const curly1: {} = 1;
+const curly2: {} = { a: 'string' };
+```
+
+### ✅ Correct
+
+```ts
+// use lower-case primitives for consistency
+const str: string = 'foo';
+const bool: boolean = true;
+const num: number = 1;
+const symb: symbol = Symbol('foo');
+const bigInt: bigint = 1n;
+
+// use a proper function type
+const func: () => number = () => 1;
+
+// use safer object types
+const lowerObj: object = {};
+const capitalObj: { a: string } = { a: 'string' };
+
+const curly1: number = 1;
+const curly2: Record<'a', string> = { a: 'string' };
+```
+
+## Options
+
+The default options provide a set of "best practices", intended to provide safety and standardization in your codebase:
+
+- Don't use the upper-case primitive types, you should use the lower-case types for consistency.
+- Avoid the `Function` type, as it provides little safety for the following reasons:
+  - It provides no type safety when calling the value, which means it's easy to provide the wrong arguments.
+  - It accepts class declarations, which will fail when called, as they are called without the `new` keyword.
+- Avoid the `Object` and `{}` types, as they mean "any non-nullish value".
+  - This is a point of confusion for many developers, who think it means "any object type".
+  - See [this comment for more information](https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-675156492).
+
+<details>
+<summary>Default Options</summary>
+
+```ts
+const defaultTypes = {
+  String: {
+    message: 'Use string instead',
+    fixWith: 'string',
+  },
+  Boolean: {
+    message: 'Use boolean instead',
+    fixWith: 'boolean',
+  },
+  Number: {
+    message: 'Use number instead',
+    fixWith: 'number',
+  },
+  Symbol: {
+    message: 'Use symbol instead',
+    fixWith: 'symbol',
+  },
+  BigInt: {
+    message: 'Use bigint instead',
+    fixWith: 'bigint',
+  },
+  Function: {
+    message: [
+      'The `Function` type accepts any function-like value.',
+      'It provides no type safety when calling the function, which can be a common source of bugs.',
+      'It also accepts things like class declarations, which will throw at runtime as they will not be called with `new`.',
+      'If you are expecting the function to accept certain arguments, you should explicitly define the function shape.',
+    ].join('\n'),
+  },
+  // object typing
+  Object: {
+    message: [
+      'The `Object` type actually means "any non-nullish value", so it is marginally better than `unknown`.',
+      '- If you want a type meaning "any object", you probably want `object` instead.',
+      '- If you want a type meaning "any value", you probably want `unknown` instead.',
+      '- If you really want a type meaning "any non-nullish value", you probably want `NonNullable<unknown>` instead.',
+    ].join('\n'),
+    suggest: ['object', 'unknown', 'NonNullable<unknown>'],
+  },
+  '{}': {
+    message: [
+      '`{}` actually means "any non-nullish value".',
+      '- If you want a type meaning "any object", you probably want `object` instead.',
+      '- If you want a type meaning "any value", you probably want `unknown` instead.',
+      '- If you want a type meaning "empty object", you probably want `Record<string, never>` instead.',
+      '- If you really want a type meaning "any non-nullish value", you probably want `NonNullable<unknown>` instead.',
+    ].join('\n'),
+    suggest: [
+      'object',
+      'unknown',
+      'Record<string, never>',
+      'NonNullable<unknown>',
+    ],
+  },
+};
+```
+
+</details>
+
+### `types`
+
+An object whose keys are the types you want to ban, and the values are error messages.
+
+The type can either be a type name literal (`Foo`), a type name with generic parameter instantiation(s) (`Foo<Bar>`), the empty object literal (`{}`), or the empty tuple type (`[]`).
+
+The values can be:
+
+- A string, which is the error message to be reported; or
+- `false` to specifically un-ban this type (useful when you are using `extendDefaults`); or
+- An object with the following properties:
+  - `message: string` - the message to display when the type is matched.
+  - `fixWith?: string` - a string to replace the banned type with when the fixer is run. If this is omitted, no fix will be done.
+  - `suggest?: string[]` - a list of suggested replacements for the banned type.
+
+### `extendDefaults`
+
+If you're specifying custom `types`, you can set this to `true` to extend the default `types` configuration. This is a convenience option to save you copying across the defaults when adding another type.
+
+If this is `false`, the rule will _only_ use the types defined in your configuration.
+
+Example configuration:
+
+```jsonc
+{
+  "@typescript-eslint/ban-types": [
+    "error",
+    {
+      "types": {
+        // add a custom message to help explain why not to use it
+        "Foo": "Don't use Foo because it is unsafe",
+
+        // add a custom message, AND tell the plugin how to fix it
+        "OldAPI": {
+          "message": "Use NewAPI instead",
+          "fixWith": "NewAPI"
+        },
+
+        // un-ban a type that's banned by default
+        "{}": false
+      },
+      "extendDefaults": true
+    }
+  ]
+}
+```

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/block-spacing.md

@@ -0,0 +1,12 @@
+---
+description: 'Disallow or enforce spaces inside of blocks after opening block and before closing block.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/block-spacing** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/block-spacing`](https://eslint.org/docs/rules/block-spacing) rule.
+This version adds support for TypeScript related blocks (interfaces, object type literals and enums).

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/brace-style.md

@@ -0,0 +1,12 @@
+---
+description: 'Enforce consistent brace style for blocks.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/brace-style** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/brace-style`](https://eslint.org/docs/rules/brace-style) rule.
+It adds support for `enum`, `interface`, `namespace` and `module` declarations.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/camelcase.md

@@ -0,0 +1,10 @@
+:::danger Deprecated
+
+This rule has been deprecated in favour of the [`naming-convention`](./naming-convention.md) rule.
+
+:::
+
+<!--
+This doc file has been left on purpose because `camelcase` is a core eslint rule.
+This exists to help direct people to the replacement rule.
+-->