eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-json-value.md

@@ -0,0 +1,107 @@
+# prefer-type-fest-json-value
+
+Prefers TypeFest `JsonObject` for serialization-bound string-keyed record contracts.
+
+## Targeted pattern scope
+
+This rule targets boundary-layer `Record<string, unknown/any>` payload aliases that are intended to represent JSON-compatible values.
+
+- Payload/context-like contract aliases using `Record<string, unknown>`/`Record<string, any>` in JSON boundary folders.
+
+General-purpose records outside configured JSON boundaries are intentionally excluded.
+
+## What this rule reports
+
+This rule reports boundary payload aliases that should use `JsonObject`.
+
+- Payload/context-like contract aliases using `Record<string, unknown>`/`Record<string, any>` in JSON boundary folders.
+
+## Why this rule exists
+
+Serialization boundaries should declare JSON-compatible intent directly so type safety and runtime assumptions stay aligned.
+
+## ❌ Incorrect
+
+```ts
+type Payload = Record<string, unknown>;
+```
+
+## ✅ Correct
+
+```ts
+type Payload = JsonObject;
+```
+
+## Behavior and migration notes
+
+- `JsonObject` models JSON-compatible object payloads with string keys.
+- Use `JsonObject` when your boundary contract must stay object-shaped.
+- Replace open-ended `Record<string, unknown>`/`any` boundary contracts with `JsonObject` when schema intent is serialization.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type ConfigSnapshot = Record<string, unknown>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type ConfigSnapshot = JsonObject;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type CacheEntry = JsonObject;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-json-value": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if boundary contracts intentionally allow non-JSON runtime values.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/json-value.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/json-value.d.ts)
+
+```ts
+/**
+Matches any valid JSON value.
+
+@see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
+
+@category JSON
+*/
+```
+
+> **Rule catalog ID:** R046
+
+## 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-keys-of-union.md

@@ -0,0 +1,139 @@
+# prefer-type-fest-keys-of-union
+
+Require TypeFest [`KeysOfUnion<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/keys-of-union.d.ts) over imported aliases like `AllKeys`.
+
+## Targeted pattern scope
+
+This rule targets imported alias names used for "all keys across union members" extraction.
+
+## What this rule reports
+
+- Type references that resolve to imported `AllKeys` aliases.
+
+## Why this rule exists
+
+`KeysOfUnion` is the canonical TypeFest utility for extracting the full key union across object unions. Using canonical utility names improves readability and consistency.
+
+## ❌ Incorrect
+
+```ts
+import type { AllKeys } from "type-aliases";
+
+type Keys = AllKeys<Foo | Bar>;
+```
+
+## ✅ Correct
+
+```ts
+import type { KeysOfUnion } from "type-fest";
+
+type Keys = KeysOfUnion<Foo | Bar>;
+```
+
+## Behavior and migration notes
+
+- `KeysOfUnion<T>` includes keys that appear in any member of an object union.
+- This rule targets alias names with matching semantics (`AllKeys`).
+- Use this utility when discriminated unions require full key introspection across variants.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { AllKeys } from "type-aliases";
+
+type Keys = AllKeys<A | B>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { KeysOfUnion } from "type-fest";
+
+type Keys = KeysOfUnion<A | B>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type EventKeys = KeysOfUnion<CreateEvent | DeleteEvent>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-keys-of-union": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing alias names must remain for public API compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/keys-of-union.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/keys-of-union.d.ts)
+
+````ts
+/**
+Create a union of all keys from a given type, even those exclusive to specific union members.
+
+Unlike the native `keyof` keyword, which returns keys present in **all** union members, this type returns keys from **any** member.
+
+@link https://stackoverflow.com/a/49402091
+
+@example
+```
+import type {KeysOfUnion} from 'type-fest';
+
+type A = {
+    common: string;
+    a: number;
+};
+
+type B = {
+    common: string;
+    b: string;
+};
+
+type C = {
+    common: string;
+    c: boolean;
+};
+
+type Union = A | B | C;
+
+type CommonKeys = keyof Union;
+//=> 'common'
+
+type AllKeys = KeysOfUnion<Union>;
+//=> 'common' | 'a' | 'b' | 'c'
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R047
+
+## 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-literal-union.md

@@ -0,0 +1,118 @@
+# prefer-type-fest-literal-union
+
+Require TypeFest [`LiteralUnion`](https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts) over unions that mix primitive keywords with same-family literal members.
+
+## Targeted pattern scope
+
+This rule targets patterns like `"foo" | "bar" | string` and `200 | 404 | number`.
+
+Those unions are usually better expressed with `LiteralUnion`, which preserves literal IntelliSense while retaining primitive assignability.
+
+## What this rule reports
+
+- String literal unions that also include `string`.
+- Number literal unions that also include `number`.
+- Boolean literal unions that also include `boolean`.
+- Bigint literal unions that also include `bigint`.
+
+### Detection boundaries
+
+- ✅ Reports same-family literal-plus-primitive unions (for example `"a" | string`).
+- ❌ Does not rewrite cross-family unions (for example `"a" | number`).
+
+## Why this rule exists
+
+`LiteralUnion<Literals, Primitive>` preserves literal completions while still accepting the broad primitive type.
+
+This keeps APIs ergonomic for known values without over-constraining extension points.
+
+## ❌ Incorrect
+
+```ts
+type Environment = "dev" | "prod" | string;
+type HttpCode = 200 | 404 | number;
+```
+
+## ✅ Correct
+
+```ts
+import type { LiteralUnion } from "type-fest";
+
+type Environment = LiteralUnion<"dev" | "prod", string>;
+type HttpCode = LiteralUnion<200 | 404, number>;
+```
+
+## Behavior and migration notes
+
+- Use the second parameter to match the primitive family (`string`, `number`, `boolean`, `bigint`).
+- Preserve literal member intent by keeping the literal union in the first type argument.
+- Avoid this pattern for closed enums where broad primitive assignability is not wanted.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-literal-union": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team prefers explicit primitive-plus-literal unions and does not want the additional abstraction.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/literal-union.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts)
+
+````ts
+/**
+Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const petWithoutAutocomplete: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const petWithAutoComplete: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+````
+
+> **Rule catalog ID:** R048
+
+## Further reading
+
+- [TypeFest README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Literal Types](https://www.typescriptlang.org/docs/handbook/literal-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-merge-exclusive.md

@@ -0,0 +1,118 @@
+# prefer-type-fest-merge-exclusive
+
+Require TypeFest [`MergeExclusive`](https://github.com/sindresorhus/type-fest/blob/main/source/merge-exclusive.d.ts) over `XOR` aliases.
+
+## Targeted pattern scope
+
+This rule reports `XOR<...>` helper aliases and prefers `MergeExclusive<...>` for mutually exclusive object contracts.
+
+## What this rule reports
+
+- Type references named `XOR`.
+
+### Detection boundaries
+
+- ✅ Reports direct `XOR<...>` type references.
+- ❌ Does not auto-fix when project-local `XOR` semantics differ from `MergeExclusive`.
+
+## Why this rule exists
+
+`MergeExclusive<A, B>` is the canonical TypeFest utility for object-level XOR constraints.
+
+Unifying on one name reduces contract ambiguity in auth/selectors where two modes must be mutually exclusive.
+
+## ❌ Incorrect
+
+```ts
+type Selector = XOR<{ email: string }, { id: string }>;
+```
+
+## ✅ Correct
+
+```ts
+import type { MergeExclusive } from "type-fest";
+
+type Selector = MergeExclusive<{ email: string }, { id: string }>;
+```
+
+## Behavior and migration notes
+
+- `MergeExclusive` ensures overlapping key sets cannot be simultaneously satisfied.
+- Verify parity if your legacy `XOR` helper applied custom key normalization.
+- Keep mutually exclusive contract types near API boundaries to improve review clarity.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-merge-exclusive": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally standardizes `XOR` naming instead of TypeFest.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/merge-exclusive.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/merge-exclusive.d.ts)
+
+````ts
+/**
+Create a type that has mutually exclusive keys.
+
+This type was inspired by [this comment](https://github.com/Microsoft/TypeScript/issues/14094#issuecomment-373782604).
+
+This type works with a helper type, called `Without`. `Without<FirstType, SecondType>` produces a type that has only keys from `FirstType` which are not present on `SecondType` and sets the value type for these keys to `never`. This helper type is then used in `MergeExclusive` to remove keys from either `FirstType` or `SecondType`.
+
+@example
+```
+import type {MergeExclusive} from 'type-fest';
+
+type ExclusiveVariation1 = {
+    exclusive1: boolean;
+};
+
+type ExclusiveVariation2 = {
+    exclusive2: string;
+};
+
+type ExclusiveOptions = MergeExclusive<ExclusiveVariation1, ExclusiveVariation2>;
+
+let exclusiveOptions: ExclusiveOptions;
+
+exclusiveOptions = {exclusive1: true};
+// Works
+
+exclusiveOptions = {exclusive2: 'hi'};
+// Works
+
+// @ts-expect-error
+exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
+// Error
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R049
+
+## Further reading
+
+- [TypeFest README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Unions and Intersections](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.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-non-empty-tuple.md

@@ -0,0 +1,115 @@
+# prefer-type-fest-non-empty-tuple
+
+Require TypeFest [`NonEmptyTuple`](https://github.com/sindresorhus/type-fest/blob/main/source/non-empty-tuple.d.ts) over the ad-hoc `readonly [T, ...T[]]` tuple pattern.
+
+## Targeted pattern scope
+
+This rule targets ad-hoc tuple-rest patterns that encode non-empty collections.
+
+## What this rule reports
+
+- `readonly [T, ...T[]]`
+
+## Why this rule exists
+
+`NonEmptyTuple<T>` is a well-known TypeFest alias that communicates the intent of a non-empty tuple and keeps shared utility-type usage consistent across codebases.
+
+## ❌ Incorrect
+
+```ts
+type Names = readonly [string, ...string[]];
+```
+
+## ✅ Correct
+
+```ts
+type Names = NonEmptyTuple<string>;
+```
+
+## Behavior and migration notes
+
+- `NonEmptyTuple<T>` represents tuple/list contracts with at least one element.
+- This rule targets the explicit rest-tuple spelling (`readonly [T, ...T[]]`).
+- Keep element type aliases explicit when non-empty constraints are part of public API contracts.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Names = readonly [string, ...string[]];
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Names = NonEmptyTuple<string>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Steps = NonEmptyTuple<{ id: string }>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-non-empty-tuple": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing tuple spellings must remain for public compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/non-empty-tuple.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/non-empty-tuple.d.ts)
+
+````ts
+/**
+Matches any non-empty tuple.
+
+@example
+```
+import type {NonEmptyTuple} from 'type-fest';
+
+const sum = (...numbers: NonEmptyTuple<number>) => numbers.reduce((total, value) => total + value, 0);
+
+sum(1, 2, 3);
+// Ok
+
+// @ts-expect-error
+sum();
+// Error: Expected at least 1 arguments, but got 0.
+```
+
+@see {@link RequireAtLeastOne} for objects
+
+@category Array
+*/
+````
+
+> **Rule catalog ID:** R050
+
+## 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)