eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-tagged-brands.md

@@ -0,0 +1,278 @@
+# prefer-type-fest-tagged-brands
+
+Prefers TypeFest `Tagged` for branded primitive identifiers over ad-hoc `__brand`/`__tag` intersection patterns.
+
+## Targeted pattern scope
+
+This rule targets ad-hoc brand-marker intersections and legacy alias names used for branded primitives.
+
+## What this rule reports
+
+- Type aliases that use intersection branding with explicit brand-marker fields.
+- Type references that resolve to imported `Opaque` / `Branded` aliases.
+- Existing `Tagged` usage is ignored.
+
+### Detection boundaries
+
+- ✅ Reports ad-hoc brand-marker intersections by default.
+- ✅ Reports imported `Opaque` / `Branded` aliases by default.
+- ❌ Does not report namespace-qualified alias usage.
+- ✅ Auto-fixes imported legacy alias references to `Tagged` when replacement is syntactically safe.
+- ❌ Does not auto-fix ad-hoc intersection branding declarations.
+- ✅ Enforcement surface is configurable with `enforceAdHocBrandIntersections` and `enforceLegacyAliases`.
+
+## Why this rule exists
+
+`Tagged` provides a standard, reusable branded-type approach that improves consistency and readability.
+
+## ❌ Incorrect
+
+```ts
+type UserId = string & { readonly __brand: "UserId" };
+```
+
+## ✅ Correct
+
+```ts
+type UserId = Tagged<string, "UserId">;
+```
+
+## Behavior and migration notes
+
+- `Tagged<Base, Tag>` standardizes branded identity types.
+- This rule targets both structural brand fields (`__brand`, `__tag`) and legacy alias references (`Opaque`, `Branded`).
+- Use canonical `Tagged` aliases for IDs and domain markers to keep branding semantics consistent across packages.
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTypeFestTaggedBrandsOptions = {
+    /**
+     * Whether to report structural ad-hoc branding intersections.
+     *
+     * @default true
+     */
+    enforceAdHocBrandIntersections?: boolean;
+
+    /**
+     * Whether to report imported legacy aliases like Opaque/Branded.
+     *
+     * @default true
+     */
+    enforceLegacyAliases?: boolean;
+};
+```
+
+Default configuration:
+
+```ts
+{
+    enforceAdHocBrandIntersections: true,
+    enforceLegacyAliases: true,
+}
+```
+
+Flat config setup (default behavior):
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tagged-brands": [
+                "error",
+                {
+                    enforceAdHocBrandIntersections: true,
+                    enforceLegacyAliases: true,
+                },
+            ],
+        },
+    },
+];
+```
+
+#### `enforceAdHocBrandIntersections: false`
+
+Ignores structural ad-hoc intersections, while still reporting legacy aliases:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tagged-brands": [
+                "error",
+                {
+                    enforceAdHocBrandIntersections: false,
+                    enforceLegacyAliases: true,
+                },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { Opaque } from "type-aliases";
+
+type A = string & { readonly __brand: "UserId" }; // ✅ Not reported
+type B = Opaque<string, "UserId">; // ❌ Reported
+```
+
+#### `enforceLegacyAliases: false`
+
+Ignores imported `Opaque`/`Branded` aliases, while still reporting ad-hoc intersections:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tagged-brands": [
+                "error",
+                {
+                    enforceAdHocBrandIntersections: true,
+                    enforceLegacyAliases: false,
+                },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { Opaque } from "type-aliases";
+
+type A = Opaque<string, "UserId">; // ✅ Not reported
+type B = string & { readonly __brand: "UserId" }; // ❌ Reported
+```
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type OrderId = string & { readonly __tag: "OrderId" };
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type OrderId = Tagged<string, "OrderId">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type TenantId = Tagged<string, "TenantId">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tagged-brands": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing brand encodings must remain for backward compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/tagged.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/tagged.d.ts)
+
+````ts
+/**
+Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for distinct concepts in your program that should not be interchangeable, even if their runtime values have the same type. (See examples.)
+
+A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
+
+[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
+
+A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
+
+A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
+  - the underlying (untagged) type of `A` is assignable to the underlying type of `B`;
+    - `A` contains at least all the tags `B` has;
+    - and the metadata type for each of `A`'s tags is assignable to the metadata type of `B`'s corresponding tag.
+
+There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
+    - [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
+    - [Microsoft/TypeScript#4895](https://github.com/microsoft/TypeScript/issues/4895)
+    - [Microsoft/TypeScript#33290](https://github.com/microsoft/TypeScript/pull/33290)
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+type AccountNumber = Tagged<number, 'AccountNumber'>;
+type AccountBalance = Tagged<number, 'AccountBalance'>;
+
+function createAccountNumber(): AccountNumber {
+    // As you can see, casting from a `number` (the underlying type being tagged) is allowed.
+    return 2 as AccountNumber;
+}
+
+declare function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance;
+
+// This will compile successfully.
+getMoneyForAccount(createAccountNumber());
+
+// But this won't, because it has to be explicitly passed as an `AccountNumber` type!
+// Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
+// @ts-expect-error
+getMoneyForAccount(2);
+
+// You can also use tagged values like their underlying, untagged type.
+// I.e., this will compile successfully because an `AccountNumber` can be used as a regular `number`.
+// In this sense, the underlying base type is not hidden, which differentiates tagged types from opaque types in other languages.
+const accountNumber = createAccountNumber() + 2;
+```
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+// You can apply multiple tags to a type by using `Tagged` repeatedly.
+type Url = Tagged<string, 'URL'>;
+type SpecialCacheKey = Tagged<Url, 'SpecialCacheKey'>;
+
+// You can also pass a union of tag names, so this is equivalent to the above, although it doesn't give you the ability to assign distinct metadata to each tag.
+type SpecialCacheKey2 = Tagged<string, 'URL' | 'SpecialCacheKey'>;
+```
+
+@category Type
+*/
+````
+
+> **Rule catalog ID:** R067
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` npm documentation](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)

package/docs/rules/prefer-type-fest-tuple-of.md

@@ -0,0 +1,250 @@
+# prefer-type-fest-tuple-of
+
+Require `Readonly<TupleOf<Length, Element>>` over imported aliases like
+`ReadonlyTuple`.
+
+## Targeted pattern scope
+
+This rule targets deprecated `ReadonlyTuple` and `Tuple` alias usage.
+
+## What this rule reports
+
+- Type references that resolve to imported `ReadonlyTuple` aliases.
+- Type references that resolve to imported `Tuple` aliases.
+
+### Detection boundaries
+
+- ✅ Reports imported aliases with direct named imports.
+- ❌ Does not report namespace-qualified alias usage.
+- ✅ Auto-fixes imported alias references to canonical `TupleOf` forms when replacement is syntactically safe.
+- ✅ Alias coverage is configurable with `enforcedAliasNames`.
+
+## Why this rule exists
+
+`ReadonlyTuple` is deprecated in TypeFest. The canonical replacement is
+`Readonly<TupleOf<Length, Element>>`, which keeps readonly semantics explicit
+while using the supported tuple utility.
+
+## ❌ Incorrect
+
+```ts
+import type { ReadonlyTuple } from "type-fest";
+
+type Digits = ReadonlyTuple<number, 4>;
+```
+
+## ✅ Correct
+
+```ts
+import type { TupleOf } from "type-fest";
+
+type Digits = Readonly<TupleOf<4, number>>;
+```
+
+## Behavior and migration notes
+
+- `ReadonlyTuple<Element, Length>` is deprecated in favor of `Readonly<TupleOf<Length, Element>>`.
+- `Tuple<Element, Length>` is deprecated in favor of `TupleOf<Length, Element>`.
+- This rule migrates deprecated TypeFest tuple naming toward supported utilities.
+- Keep readonly wrapping explicit so mutability intent remains visible at call sites.
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTypeFestTupleOfOptions = {
+    /**
+     * Legacy alias names that this rule will report and replace.
+     *
+     * @default ["ReadonlyTuple", "Tuple"]
+     */
+    enforcedAliasNames?: ("ReadonlyTuple" | "Tuple")[];
+};
+```
+
+Default configuration:
+
+```ts
+{
+    enforcedAliasNames: ["ReadonlyTuple", "Tuple"],
+}
+```
+
+Flat config setup (default behavior):
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tuple-of": [
+                "error",
+                { enforcedAliasNames: ["ReadonlyTuple", "Tuple"] },
+            ],
+        },
+    },
+];
+```
+
+#### `enforcedAliasNames: ["ReadonlyTuple", "Tuple"]` (default)
+
+Reports both legacy aliases.
+
+#### `enforcedAliasNames: ["Tuple"]`
+
+Reports only `Tuple` and ignores `ReadonlyTuple`:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tuple-of": [
+                "error",
+                { enforcedAliasNames: ["Tuple"] },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { ReadonlyTuple, Tuple } from "type-aliases";
+
+type A = ReadonlyTuple<string, 3>; // ✅ Not reported
+type B = Tuple<string, 3>; // ❌ Reported
+```
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { ReadonlyTuple } from "type-fest";
+
+type IPv4 = ReadonlyTuple<number, 4>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { TupleOf } from "type-fest";
+
+type IPv4 = Readonly<TupleOf<4, number>>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type RGB = TupleOf<3, number>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-tuple-of": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if compatibility constraints require preserving deprecated aliases.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/tuple-of.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/tuple-of.d.ts)
+
+````ts
+/**
+Create a tuple type of the specified length with elements of the specified type.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type RGB = TupleOf<3, number>;
+//=> [number, number, number]
+
+type Line = TupleOf<2, {x: number; y: number}>;
+//=> [{x: number; y: number}, {x: number; y: number}]
+
+type TicTacToeBoard = TupleOf<3, TupleOf<3, 'X' | 'O' | null>>;
+//=> [['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null]]
+```
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type Range<Start extends number, End extends number> = Exclude<keyof TupleOf<End>, keyof TupleOf<Start>>;
+
+type ZeroToFour = Range<0, 5>;
+//=> '0' | '1' | '2' | '3' | '4'
+
+type ThreeToEight = Range<3, 9>;
+//=> '5' | '3' | '4' | '6' | '7' | '8'
+```
+
+Note: If the specified length is the non-literal `number` type, the result will not be a tuple but a regular array.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type StringArray = TupleOf<number, string>;
+//=> string[]
+```
+
+Note: If the type for elements is not specified, it will default to `unknown`.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type UnknownTriplet = TupleOf<3>;
+//=> [unknown, unknown, unknown]
+```
+
+Note: If the specified length is negative, the result will be an empty tuple.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type EmptyTuple = TupleOf<-3, string>;
+//=> []
+```
+
+Note: If you need a readonly tuple, simply wrap this type with `Readonly`, for example, to create `readonly [number, number, number]` use `Readonly<TupleOf<3, number>>`.
+
+@category Array
+*/
+````
+
+> **Rule catalog ID:** R068
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` npm documentation](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)

package/docs/rules/prefer-type-fest-unknown-array.md

@@ -0,0 +1,126 @@
+# prefer-type-fest-unknown-array
+
+Require TypeFest [`UnknownArray`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-array.d.ts) over `readonly unknown[]` and `ReadonlyArray<unknown>`.
+
+## Targeted pattern scope
+
+This rule targets explicit unknown-array spellings that TypeFest standardizes as `UnknownArray`.
+
+- `readonly unknown[]`
+- `ReadonlyArray<unknown>`
+
+Other collection contracts are left alone unless they match the exact unknown collection form listed below.
+
+## What this rule reports
+
+This rule reports unknown-array type forms that should migrate to `UnknownArray`.
+
+- `readonly unknown[]`
+- `ReadonlyArray<unknown>`
+
+## Why this rule exists
+
+`UnknownArray` provides a clearer, shared alias for unknown element arrays and keeps utility-type usage consistent with other TypeFest-first conventions.
+
+## ❌ Incorrect
+
+```ts
+type Values = readonly unknown[];
+```
+
+## ✅ Correct
+
+```ts
+type Values = UnknownArray;
+```
+
+## Behavior and migration notes
+
+- `UnknownArray` is the canonical alias for readonly unknown-element arrays in `type-fest` style.
+- This rule normalizes `readonly unknown[]` and `ReadonlyArray<unknown>` into one shared name.
+- Use this alias for untyped collection ingress points before narrowing.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Input = readonly unknown[];
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Input = UnknownArray;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type PayloadList = UnknownArray;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-unknown-array": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if external API signatures must preserve existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/unknown-array.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-array.d.ts)
+
+````ts
+/**
+Represents an array with `unknown` value.
+
+Use case: You want a type that all arrays can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownArray} from 'type-fest';
+
+type IsArray<T> = T extends UnknownArray ? true : false;
+
+type A = IsArray<['foo']>;
+//=> true
+
+type B = IsArray<readonly number[]>;
+//=> true
+
+type C = IsArray<string>;
+//=> false
+```
+
+@category Type
+@category Array
+*/
+````
+
+> **Rule catalog ID:** R069
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` npm documentation](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)