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

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/class-literal-property-style.md

@@ -0,0 +1,114 @@
+---
+description: 'Enforce that literals on classes are exposed in a consistent style.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/class-literal-property-style** for documentation.
+
+Some TypeScript applications store literal values on classes using fields with the `readonly` modifier to prevent them from being reassigned.
+When writing TypeScript libraries that could be used by JavaScript users, however, it's typically safer to expose these literals using `getter`s, since the `readonly` modifier is enforced at compile type.
+
+This rule aims to ensure that literals exposed by classes are done so consistently, in one of the two style described above.
+By default this rule prefers the `fields` style as it means JS doesn't have to setup & teardown a function closure.
+
+## Options
+
+:::note
+
+This rule only checks for constant _literal_ values (string, template string, number, bigint, boolean, regexp, null). It does not check objects or arrays, because a readonly field behaves differently to a getter in those cases. It also does not check functions, as it is a common pattern to use readonly fields with arrow function values as auto-bound methods.
+This is because these types can be mutated and carry with them more complex implications about their usage.
+
+:::
+
+### `"fields"`
+
+This style checks for any getter methods that return literal values, and requires them to be defined using fields with the `readonly` modifier instead.
+
+Examples of code with the `fields` style:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/class-literal-property-style: ["error", "fields"] */
+
+class Mx {
+  public static get myField1() {
+    return 1;
+  }
+
+  private get ['myField2']() {
+    return 'hello world';
+  }
+}
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/class-literal-property-style: ["error", "fields"] */
+
+class Mx {
+  public readonly myField1 = 1;
+
+  // not a literal
+  public readonly myField2 = [1, 2, 3];
+
+  private readonly ['myField3'] = 'hello world';
+
+  public get myField4() {
+    return `hello from ${window.location.href}`;
+  }
+}
+```
+
+### `"getters"`
+
+This style checks for any `readonly` fields that are assigned literal values, and requires them to be defined as getters instead.
+This style pairs well with the [`@typescript-eslint/prefer-readonly`](prefer-readonly.md) rule,
+as it will identify fields that can be `readonly`, and thus should be made into getters.
+
+Examples of code with the `getters` style:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/class-literal-property-style: ["error", "getters"] */
+
+class Mx {
+  readonly myField1 = 1;
+  readonly myField2 = `hello world`;
+  private readonly myField3 = 'hello world';
+}
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/class-literal-property-style: ["error", "getters"] */
+
+class Mx {
+  // no readonly modifier
+  public myField1 = 'hello';
+
+  // not a literal
+  public readonly myField2 = [1, 2, 3];
+
+  public static get myField3() {
+    return 1;
+  }
+
+  private get ['myField4']() {
+    return 'hello world';
+  }
+}
+```
+
+## When Not To Use It
+
+When you have no strong preference, or do not wish to enforce a particular style
+for how literal values are exposed by your classes.

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

@@ -0,0 +1,22 @@
+---
+description: 'Require or disallow trailing commas.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/comma-dangle** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/comma-dangle`](https://eslint.org/docs/rules/comma-dangle) rule.
+It adds support for TypeScript syntax.
+
+See the [ESLint documentation](https://eslint.org/docs/rules/comma-dangle) for more details on the `comma-dangle` rule.
+
+## How to Use
+
+In addition to the options supported by the `comma-dangle` rule in ESLint core, the rule adds the following options:
+
+- `"enums"` is for trailing comma in enum. (e.g. `enum Foo = {Bar,}`)
+- `"generics"` is for trailing comma in generic. (e.g. `function foo<T,>() {}`)
+- `"tuples"` is for trailing comma in tuple. (e.g. `type Foo = [string,]`)

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

@@ -0,0 +1,12 @@
+---
+description: 'Enforce consistent spacing before and after commas.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/comma-spacing** for documentation.
+
+## Examples
+
+This rule extends the base [`eslint/comma-spacing`](https://eslint.org/docs/rules/comma-spacing) rule.
+It adds support for trailing comma in a types parameters list.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/consistent-generic-constructors.md

@@ -0,0 +1,73 @@
+---
+description: 'Enforce specifying generic type arguments on type annotation or constructor name of a constructor call.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-generic-constructors** for documentation.
+
+When constructing a generic class, you can specify the type arguments on either the left-hand side (as a type annotation) or the right-hand side (as part of the constructor call):
+
+```ts
+// Left-hand side
+const map: Map<string, number> = new Map();
+
+// Right-hand side
+const map = new Map<string, number>();
+```
+
+This rule ensures that type arguments appear consistently on one side of the declaration.
+Keeping to one side consistently improve code readability.
+
+> The rule never reports when there are type parameters on both sides, or neither sides of the declaration.
+> It also doesn't report if the names of the type annotation and the constructor don't match.
+
+## Options
+
+- `constructor` _(default)_: type arguments that **only** appear on the type annotation are disallowed.
+- `type-annotation`: type arguments that **only** appear on the constructor are disallowed.
+
+### `constructor`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const map: Map<string, number> = new Map();
+const set: Set<string> = new Set();
+```
+
+#### ✅ Correct
+
+```ts
+const map = new Map<string, number>();
+const map: Map<string, number> = new MyMap();
+const set = new Set<string>();
+const set = new Set();
+const set: Set<string> = new Set<string>();
+```
+
+### `type-annotation`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const map = new Map<string, number>();
+const set = new Set<string>();
+```
+
+#### ✅ Correct
+
+```ts
+const map: Map<string, number> = new Map();
+const set: Set<string> = new Set();
+const set = new Set();
+const set: Set<string> = new Set<string>();
+```
+
+## When Not To Use It
+
+You can turn this rule off if you don't want to enforce one kind of generic constructor style over the other.

package/node_modules/@typescript-eslint/eslint-plugin/docs/rules/consistent-indexed-object-style.md

@@ -0,0 +1,80 @@
+---
+description: 'Require or disallow the `Record` type.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-indexed-object-style** for documentation.
+
+TypeScript supports defining arbitrary object keys using an index signature. TypeScript also has a builtin type named `Record` to create an empty object defining only an index signature. For example, the following types are equal:
+
+```ts
+interface Foo {
+  [key: string]: unknown;
+}
+
+type Foo = {
+  [key: string]: unknown;
+};
+
+type Foo = Record<string, unknown>;
+```
+
+Keeping to one declaration form consistently improve code readability.
+
+## Options
+
+- `"record"` _(default)_: only allow the `Record` type.
+- `"index-signature"`: only allow index signatures.
+
+### `record`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/consistent-indexed-object-style: ["error", "record"] */
+
+interface Foo {
+  [key: string]: unknown;
+}
+
+type Foo = {
+  [key: string]: unknown;
+};
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/consistent-indexed-object-style: ["error", "record"] */
+
+type Foo = Record<string, unknown>;
+```
+
+### `index-signature`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/consistent-indexed-object-style: ["error", "index-signature"] */
+
+type Foo = Record<string, unknown>;
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/consistent-indexed-object-style: ["error", "index-signature"] */
+
+interface Foo {
+  [key: string]: unknown;
+}
+
+type Foo = {
+  [key: string]: unknown;
+};
+```

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

@@ -0,0 +1,108 @@
+---
+description: 'Enforce consistent usage of type assertions.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-type-assertions** for documentation.
+
+TypeScript provides two syntaxes for "type assertions":
+
+- Angle brackets: `<Type>value`
+- As: `value as Type`
+
+This rule aims to standardize the use of type assertion style across the codebase.
+Keeping to one syntax consistently helps with code readability.
+
+:::note
+Type assertions are also commonly referred as "type casting" in TypeScript.
+However, that term is technically slightly different to what is understood by type casting in other languages.
+Type assertions are a way to say to the TypeScript compiler, _"I know better than you, it's actually this different type!"_.
+:::
+
+[`const` assertions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions) are always allowed by this rule.
+Examples of them include `let x = "hello" as const;` and `let x = <const>"hello";`.
+
+## Options
+
+### `assertionStyle`
+
+This option defines the expected assertion style. Valid values for `assertionStyle` are:
+
+- `as` will enforce that you always use `... as foo`.
+- `angle-bracket` will enforce that you always use `<foo>...`
+- `never` will enforce that you do not do any type assertions.
+
+Most codebases will want to enforce not using `angle-bracket` style because it conflicts with JSX syntax, and is confusing when paired with generic syntax.
+
+Some codebases like to go for an extra level of type safety, and ban assertions altogether via the `never` option.
+
+### `objectLiteralTypeAssertions`
+
+Always prefer `const x: T = { ... };` to `const x = { ... } as T;` (or similar with angle brackets). The type assertion in the latter case is either unnecessary or will probably hide an error.
+
+The compiler will warn for excess properties with this syntax, but not missing _required_ fields. For example: `const x: { foo: number } = {};` will fail to compile, but `const x = {} as { foo: number }` will succeed.
+
+The const assertion `const x = { foo: 1 } as const`, introduced in TypeScript 3.4, is considered beneficial and is ignored by this option.
+
+Assertions to `any` are also ignored by this option.
+
+Examples of code for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const x = { ... } as T;
+
+function foo() {
+  return { ... } as T;
+}
+```
+
+#### ✅ Correct
+
+```ts
+const x: T = { ... };
+const y = { ... } as any;
+const z = { ... } as unknown;
+
+function foo(): T {
+  return { ... };
+}
+```
+
+<!--/tabs-->
+
+Examples of code for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' }`:
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+const x = { ... } as T;
+
+function foo() {
+  return { ... } as T;
+}
+```
+
+#### ✅ Correct
+
+```tsx
+const x: T = { ... };
+const y = { ... } as any;
+const z = { ... } as unknown;
+foo({ ... } as T);
+new Clazz({ ... } as T);
+function foo() { throw { bar: 5 } as Foo }
+const foo = <Foo props={{ ... } as Bar}/>;
+```
+
+<!--/tabs-->
+
+## When Not To Use It
+
+If you do not want to enforce consistent type assertions.

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

@@ -0,0 +1,82 @@
+---
+description: 'Enforce type definitions to consistently use either `interface` or `type`.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-type-definitions** for documentation.
+
+TypeScript provides two common ways to define an object type: `interface` and `type`.
+
+```ts
+// type alias
+type T1 = {
+  a: string;
+  b: number;
+};
+
+// interface keyword
+interface T2 {
+  a: string;
+  b: number;
+}
+```
+
+The two are generally very similar, and can often be used interchangeably.
+Using the same type declaration style consistently helps with code readability.
+
+## Options
+
+- `"interface"` _(default)_: enforce using `interface`s for object type definitions.
+- `"type"`: enforce using `type`s for object type definitions.
+
+### `interface`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/consistent-type-definitions: ["error", "interface"] */
+
+type T = { x: number };
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/consistent-type-definitions: ["error", "interface"] */
+
+type T = string;
+type Foo = string | {};
+
+interface T {
+  x: number;
+}
+```
+
+### `type`
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+/* eslint @typescript-eslint/consistent-type-definitions: ["error", "type"] */
+
+interface T {
+  x: number;
+}
+```
+
+#### ✅ Correct
+
+```ts
+/* eslint @typescript-eslint/consistent-type-definitions: ["error", "type"] */
+
+type T = { x: number };
+```
+
+## When Not To Use It
+
+If you specifically want to use an interface or type literal for stylistic reasons, you can disable this rule.

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

@@ -0,0 +1,100 @@
+---
+description: 'Enforce consistent usage of type exports.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-type-exports** for documentation.
+
+TypeScript allows specifying a `type` keyword on exports to indicate that the export exists only in the type system, not at runtime.
+This allows transpilers to drop exports without knowing the types of the dependencies.
+
+> See [Blog > Consistent Type Exports and Imports: Why and How](/blog/consistent-type-imports-and-exports-why-and-how) for more details.
+
+## Examples
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+interface ButtonProps {
+  onClick: () => void;
+}
+
+class Button implements ButtonProps {
+  onClick = () => console.log('button!');
+}
+
+export { Button, ButtonProps };
+```
+
+### ✅ Correct
+
+```ts
+interface ButtonProps {
+  onClick: () => void;
+}
+
+class Button implements ButtonProps {
+  onClick = () => console.log('button!');
+}
+
+export { Button };
+export type { ButtonProps };
+```
+
+## Options
+
+### `fixMixedExportsWithInlineTypeSpecifier`
+
+When this is set to true, the rule will autofix "mixed" export cases using TS 4.5's "inline type specifier".
+If you are using a TypeScript version less than 4.5, then you will not be able to use this option.
+
+For example the following code:
+
+```ts
+const x = 1;
+type T = number;
+
+export { x, T };
+```
+
+With `{fixMixedExportsWithInlineTypeSpecifier: true}` will be fixed to:
+
+```ts
+const x = 1;
+type T = number;
+
+export { x, type T };
+```
+
+With `{fixMixedExportsWithInlineTypeSpecifier: false}` will be fixed to:
+
+```ts
+const x = 1;
+type T = number;
+
+export type { T };
+export { x };
+```
+
+<!--tabs-->
+
+### ❌ Incorrect
+
+```ts
+export { Button } from 'some-library';
+export type { ButtonProps } from 'some-library';
+```
+
+### ✅ Correct
+
+```ts
+export { Button, type ButtonProps } from 'some-library';
+```
+
+## When Not To Use It
+
+- If you specifically want to use both export kinds for stylistic reasons, you can disable this rule.
+- If you use `--isolatedModules` the compiler would error if a type is not re-exported using `export type`. If you also don't wish to enforce one style over the other, you can disable this rule.

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

@@ -0,0 +1,105 @@
+---
+description: 'Enforce consistent usage of type imports.'
+---
+
+> 🛑 This file is source code, not the primary documentation location! 🛑
+>
+> See **https://typescript-eslint.io/rules/consistent-type-imports** for documentation.
+
+TypeScript allows specifying a `type` keyword on imports to indicate that the export exists only in the type system, not at runtime.
+This allows transpilers to drop imports without knowing the types of the dependencies.
+
+> See [Blog > Consistent Type Exports and Imports: Why and How](/blog/consistent-type-imports-and-exports-why-and-how) for more details.
+
+## Options
+
+### `prefer`
+
+This option defines the expected import kind for type-only imports. Valid values for `prefer` are:
+
+- `type-imports` will enforce that you always use `import type Foo from '...'` except referenced by metadata of decorators. It is the default.
+- `no-type-imports` will enforce that you always use `import Foo from '...'`.
+
+Examples of **correct** code with `{prefer: 'type-imports'}`, and **incorrect** code with `{prefer: 'no-type-imports'}`.
+
+```ts
+import type { Foo } from 'Foo';
+import type Bar from 'Bar';
+type T = Foo;
+const x: Bar = 1;
+```
+
+Examples of **incorrect** code with `{prefer: 'type-imports'}`, and **correct** code with `{prefer: 'no-type-imports'}`.
+
+```ts
+import { Foo } from 'Foo';
+import Bar from 'Bar';
+type T = Foo;
+const x: Bar = 1;
+```
+
+### `fixStyle`
+
+This option defines the expected type modifier to be added when an import is detected as used only in the type position. Valid values for `fixStyle` are:
+
+- `separate-type-imports` will add the type keyword after the import keyword `import type { A } from '...'`. It is the default.
+- `inline-type-imports` will inline the type keyword `import { type A } from '...'` and is only available in TypeScript 4.5 and onwards. See [documentation here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names 'TypeScript 4.5 documentation on type modifiers and import names').
+
+<!--tabs-->
+
+#### ❌ Incorrect
+
+```ts
+import { Foo } from 'Foo';
+import Bar from 'Bar';
+type T = Foo;
+const x: Bar = 1;
+```
+
+#### ✅ With `separate-type-imports`
+
+```ts
+import type { Foo } from 'Foo';
+import type Bar from 'Bar';
+type T = Foo;
+const x: Bar = 1;
+```
+
+#### ✅ With `inline-type-imports`
+
+```ts
+import { type Foo } from 'Foo';
+import type Bar from 'Bar';
+type T = Foo;
+const x: Bar = 1;
+```
+
+<!--tabs-->
+
+### `disallowTypeAnnotations`
+
+If `true`, type imports in type annotations (`import()`) are not allowed.
+Default is `true`.
+
+Examples of **incorrect** code with `{disallowTypeAnnotations: true}`:
+
+```ts
+type T = import('Foo').Foo;
+const x: import('Bar') = 1;
+```
+
+## Usage with `emitDecoratorMetadata`
+
+The `emitDecoratorMetadata` compiler option changes the code the TypeScript emits. In short - it causes TypeScript to create references to value imports when they are used in a type-only location. If you are using `emitDecoratorMetadata` then our tooling will require additional information in order for the rule to work correctly.
+
+If you are using [type-aware linting](https://typescript-eslint.io/linting/typed-linting), then you just need to ensure that the `tsconfig.json` you've configured for `parserOptions.project` has `emitDecoratorMetadata` turned on. Otherwise you can explicitly tell our tooling to analyze your code as if the compiler option was turned on [by setting `parserOptions.emitDecoratorMetadata` to `true`](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/README.md#parseroptionsemitdecoratormetadata).
+
+## When Not To Use It
+
+- If you specifically want to use both import kinds for stylistic reasons, you can disable this rule.
+
+## Related To
+
+- [`no-import-type-side-effects`](./no-import-type-side-effects.md)
+- [`import/consistent-type-specifier-style`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/consistent-type-specifier-style.md)
+- [`import/no-duplicates` with `{"prefer-inline": true}`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-duplicates.md#inline-type-imports)