eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-if.md

@@ -0,0 +1,217 @@
+# prefer-type-fest-if
+
+Require TypeFest [`If`](https://github.com/sindresorhus/type-fest/blob/main/source/if.d.ts) + `Is*` utilities over deprecated aliases like `IfAny`,
+`IfNever`, `IfUnknown`, `IfNull`, and `IfEmptyObject`.
+
+## Targeted pattern scope
+
+This rule reports deprecated `IfAny`/`IfNever`/`IfUnknown`/`IfNull`/`IfEmptyObject` aliases and migrates usage to canonical `If<Is*>` patterns from `type-fest`.
+
+It is intentionally strict about naming consistency and intentionally conservative
+about fixing. Rewriting `IfAny<T, A, B>` into `If<IsAny<T>, A, B>` is a
+structural transform, not a safe one-token rename.
+
+## What this rule reports
+
+- Imported type aliases used as identifier type references:
+  - `IfAny`
+  - `IfNever`
+  - `IfUnknown`
+  - `IfNull`
+  - `IfEmptyObject`
+
+### Detection boundaries
+
+- ✅ Reports `import type { IfAny } ...` followed by `IfAny<...>` usage.
+- ❌ Does not report locally renamed imports (`import type { IfAny as AliasIfAny } ...`).
+- ❌ Does not report namespace-qualified references like `TypeUtils.IfAny<...>` (the matcher targets identifier references).
+- ❌ Does not auto-fix because replacement requires rebuilding type arguments.
+
+## Why this rule exists
+
+These aliases are deprecated in TypeFest. The canonical pattern is to use
+`If<...>` with the corresponding `Is*` utility (for example, `If<IsAny<T>, ...>`).
+
+In practice, teams that keep old aliases around end up with mixed style across
+packages (`IfAny`, `IfUnknown`, custom wrappers). This rule prevents that drift.
+
+## ❌ Incorrect
+
+```ts
+import type { IfAny } from "type-fest";
+
+type Result = IfAny<T, "any", "not-any">;
+```
+
+## ✅ Correct
+
+```ts
+import type { If, IsAny } from "type-fest";
+
+type Result = If<IsAny<T>, "any", "not-any">;
+```
+
+## Behavior and migration notes
+
+- Deprecated aliases map to `If<Is*>` forms (`IfAny` → `If<IsAny<...>>`, etc.).
+- This rule intentionally does not auto-fix because argument restructuring must be explicit and reviewable.
+- Keep migration focused on parity: preserve branch types and generic parameter order during conversion.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { IfUnknown } from "custom-type-utils";
+
+type ParseMode<T> = IfUnknown<T, "strict", "lenient">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { If, IsUnknown } from "type-fest";
+
+type ParseMode<T> = If<IsUnknown<T>, "strict", "lenient">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+import type { If, IsNull } from "type-fest";
+
+type NullLabel<T> = If<IsNull<T>, "nullable", "non-nullable">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-if": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if legacy alias naming must be preserved for compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/if.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/if.d.ts)
+
+````ts
+/**
+An if-else-like type that resolves depending on whether the given `boolean` type is `true` or `false`.
+
+Use-cases:
+- You can use this in combination with `Is*` types to create an if-else-like experience. For example, `If<IsAny<any>, 'is any', 'not any'>`.
+
+Note:
+- Returns a union of if branch and else branch if the given type is `boolean` or `any`. For example, `If<boolean, 'Y', 'N'>` will return `'Y' | 'N'`.
+- Returns the else branch if the given type is `never`. For example, `If<never, 'Y', 'N'>` will return `'N'`.
+
+@example
+```
+import type {If} from 'type-fest';
+
+type A = If<true, 'yes', 'no'>;
+//=> 'yes'
+
+type B = If<false, 'yes', 'no'>;
+//=> 'no'
+
+type C = If<boolean, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type D = If<any, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type E = If<never, 'yes', 'no'>;
+//=> 'no'
+```
+
+@example
+```
+import type {If, IsAny, IsNever} from 'type-fest';
+
+type A = If<IsAny<unknown>, 'is any', 'not any'>;
+//=> 'not any'
+
+type B = If<IsNever<never>, 'is never', 'not never'>;
+//=> 'is never'
+```
+
+@example
+```
+import type {If, IsEqual} from 'type-fest';
+
+type IfEqual<T, U, IfBranch, ElseBranch> = If<IsEqual<T, U>, IfBranch, ElseBranch>;
+
+type A = IfEqual<string, string, 'equal', 'not equal'>;
+//=> 'equal'
+
+type B = IfEqual<string, number, 'equal', 'not equal'>;
+//=> 'not equal'
+```
+
+Note: Sometimes using the `If` type can make an implementation non–tail-recursive, which can impact performance. In such cases, it’s better to use a conditional directly. Refer to the following example:
+
+@example
+```
+import type {If, IsEqual, StringRepeat} from 'type-fest';
+
+type HundredZeroes = StringRepeat<'0', 100>;
+
+// The following implementation is not tail recursive
+type Includes<S extends string, Char extends string> =
+    S extends `${infer First}${infer Rest}`
+        ? If<IsEqual<First, Char>,
+            'found',
+            Includes<Rest, Char>>
+        : 'not found';
+
+// Hence, instantiations with long strings will fail
+// @ts-expect-error
+type Fails = Includes<HundredZeroes, '1'>;
+//           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Error: Type instantiation is excessively deep and possibly infinite.
+
+// However, if we use a simple conditional instead of `If`, the implementation becomes tail-recursive
+type IncludesWithoutIf<S extends string, Char extends string> =
+    S extends `${infer First}${infer Rest}`
+        ? IsEqual<First, Char> extends true
+            ? 'found'
+            : IncludesWithoutIf<Rest, Char>
+        : 'not found';
+
+// Now, instantiations with long strings will work
+type Works = IncludesWithoutIf<HundredZeroes, '1'>;
+//=> 'not found'
+```
+
+@category Type Guard
+@category Utilities
+*/
+````
+
+> **Rule catalog ID:** R041
+
+## 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-iterable-element.md

@@ -0,0 +1,170 @@
+# prefer-type-fest-iterable-element
+
+Require TypeFest [`IterableElement<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/iterable-element.d.ts) over imported aliases like `SetElement`, `SetEntry`, and `SetValues`.
+
+## Targeted pattern scope
+
+This rule focuses on imported legacy iterable helper aliases that TypeFest now models via `IterableElement`.
+
+- Type references that resolve to imported `SetElement` aliases.
+- Type references that resolve to imported `SetEntry` aliases.
+- Type references that resolve to imported `SetValues` aliases.
+
+Unrelated type references and aliases from non-targeted imports are intentionally left untouched.
+
+## What this rule reports
+
+This rule reports imported iterable helper aliases that should be consolidated to `IterableElement`.
+
+- Type references that resolve to imported `SetElement` aliases.
+- Type references that resolve to imported `SetEntry` aliases.
+- Type references that resolve to imported `SetValues` aliases.
+
+## Why this rule exists
+
+`IterableElement` is the canonical TypeFest utility for extracting element types from iterable collections. Consolidating on one name makes collection type extraction patterns easier to audit and maintain.
+
+## ❌ Incorrect
+
+```ts
+import type { SetElement } from "type-aliases";
+
+type Value = SetElement<Set<string>>;
+```
+
+## ✅ Correct
+
+```ts
+import type { IterableElement } from "type-fest";
+
+type Value = IterableElement<Set<string>>;
+```
+
+## Behavior and migration notes
+
+- This rule targets imported alias names that duplicate `IterableElement` semantics (`SetElement`, `SetEntry`, `SetValues`).
+- Standardize on `IterableElement<T>` for sync and async iterable extraction patterns.
+- Keep legacy alias names only when external libraries expose them as a required public API.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { SetElement } from "type-aliases";
+
+type Item = SetElement<Set<number>>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { IterableElement } from "type-fest";
+
+type Item = IterableElement<Set<number>>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type StreamChunk = IterableElement<AsyncIterable<string>>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-iterable-element": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if compatibility requires preserving external alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/iterable-element.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/iterable-element.d.ts)
+
+````ts
+/**
+Get the element type of an `Iterable`/`AsyncIterable`. For example, `Array`, `Set`, `Map`, generator, stream, etc.
+
+This can be useful, for example, if you want to get the type that is yielded in a generator function. Often the return type of those functions are not specified.
+
+This type works with both `Iterable`s and `AsyncIterable`s, so it can be use with synchronous and asynchronous generators.
+
+Here is an example of `IterableElement` in action with a generator function:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+function * iAmGenerator() {
+    yield 1;
+    yield 2;
+}
+
+type MeNumber = IterableElement<ReturnType<typeof iAmGenerator>>;
+```
+
+And here is an example with an async generator:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+async function * iAmGeneratorAsync() {
+    yield 'hi';
+    yield true;
+}
+
+type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>;
+```
+
+Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces.
+
+An example with an array of strings:
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+type MeString = IterableElement<string[]>;
+```
+
+@example
+```
+import type {IterableElement} from 'type-fest';
+
+const fruits = new Set(['🍎', '🍌', '🍉'] as const);
+
+type Fruit = IterableElement<typeof fruits>;
+//=> '🍎' | '🍌' | '🍉'
+```
+
+@category Iterable
+*/
+````
+
+> **Rule catalog ID:** R042
+
+## 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-json-array.md

@@ -0,0 +1,107 @@
+# prefer-type-fest-json-array
+
+Require TypeFest [`JsonArray`](https://github.com/sindresorhus/type-fest/blob/main/source/json-value.d.ts) over explicit `JsonValue` array-union aliases.
+
+## Targeted pattern scope
+
+This rule matches explicit JSON array alias spellings where `JsonArray` communicates intent directly.
+
+- `JsonValue[] | readonly JsonValue[]`
+- `Array<JsonValue> | ReadonlyArray<JsonValue>`
+
+This rule intentionally excludes other array aliases and non-JSON payload array forms.
+
+## What this rule reports
+
+This rule reports explicit `JsonValue` array alias forms that should use `JsonArray`.
+
+- `JsonValue[] | readonly JsonValue[]`
+- `Array<JsonValue> | ReadonlyArray<JsonValue>`
+
+## Why this rule exists
+
+`JsonArray` communicates JSON array intent directly and avoids repeating equivalent array union shapes.
+
+## ❌ Incorrect
+
+```ts
+type Payload = JsonValue[] | readonly JsonValue[];
+```
+
+## ✅ Correct
+
+```ts
+type Payload = JsonArray;
+```
+
+## Behavior and migration notes
+
+- `JsonArray` is the canonical alias for JSON arrays in `type-fest`.
+- Keep `JsonValue[] | readonly JsonValue[]` usage out of shared contracts to avoid duplicate representations.
+- Prefer one canonical alias per concept to reduce type alias drift across packages.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Payload = Array<JsonValue>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Payload = JsonArray;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type SerializedRows = JsonArray;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-json-array": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if public APIs must preserve existing custom alias names for compatibility.
+
+## 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 a JSON array.
+
+@category JSON
+*/
+```
+
+> **Rule catalog ID:** R043
+
+## 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-json-object.md

@@ -0,0 +1,107 @@
+# prefer-type-fest-json-object
+
+Require TypeFest [`JsonObject`](https://github.com/sindresorhus/type-fest/blob/main/source/json-value.d.ts) over equivalent explicit `Record<string, JsonValue>` aliases.
+
+## Targeted pattern scope
+
+This rule targets direct `Record<string, JsonValue>` aliases used as JSON object contracts.
+
+- `Record<string, JsonValue>`
+
+Broader record aliases and structurally different object constraints are intentionally left unchanged.
+
+## What this rule reports
+
+This rule reports `Record<string, JsonValue>` aliases that should use `JsonObject`.
+
+- `Record<string, JsonValue>`
+
+## Why this rule exists
+
+`JsonObject` communicates intent directly and avoids repeating verbose JSON object alias patterns.
+
+## ❌ Incorrect
+
+```ts
+type Payload = Record<string, JsonValue>;
+```
+
+## ✅ Correct
+
+```ts
+type Payload = JsonObject;
+```
+
+## Behavior and migration notes
+
+- `JsonObject` is equivalent in intent to `Record<string, JsonValue>` for JSON object contracts.
+- Standardize on `JsonObject` for shared payload/config types to avoid repeating low-level dictionary syntax.
+- Keep runtime validation separate; this rule only normalizes compile-time type naming.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Payload = Record<string, JsonValue>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Payload = JsonObject;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type EventAttributes = JsonObject;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-json-object": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if a published API requires preserving existing alias names.
+
+## 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 a JSON object.
+
+This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category JSON
+*/
+```
+
+> **Rule catalog ID:** R044
+
+## 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-json-primitive.md

@@ -0,0 +1,105 @@
+# prefer-type-fest-json-primitive
+
+Require TypeFest [`JsonPrimitive`](https://github.com/sindresorhus/type-fest/blob/main/source/json-value.d.ts) over explicit JSON primitive keyword unions.
+
+## Targeted pattern scope
+
+This rule narrows matching to explicit primitive-union spellings that TypeFest captures as `JsonPrimitive`.
+
+- `boolean | null | number | string` unions (in any order)
+
+Non-primitive additions and alias-expanded unions are out of scope unless they exactly preserve the primitive set.
+
+## What this rule reports
+
+This rule reports primitive-only unions that should be rewritten as `JsonPrimitive`.
+
+- `boolean | null | number | string` unions (in any order)
+
+## Why this rule exists
+
+`JsonPrimitive` communicates JSON primitive intent directly and avoids repeating equivalent keyword-union definitions.
+
+## ❌ Incorrect
+
+```ts
+type Scalar = string | number | boolean | null;
+```
+
+## ✅ Correct
+
+```ts
+type Scalar = JsonPrimitive;
+```
+
+## Behavior and migration notes
+
+- `JsonPrimitive` covers `string | number | boolean | null`.
+- The union order in source code is irrelevant; this rule targets the shape, not token order.
+- Keep this alias for scalar JSON domains while using `JsonValue` for full recursive JSON values.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type PrimitiveValue = string | number | boolean | null;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type PrimitiveValue = JsonPrimitive;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Cell = JsonPrimitive;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-json-primitive": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing exported aliases must remain stable.
+
+## 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 primitive value.
+
+@category JSON
+*/
+```
+
+> **Rule catalog ID:** R045
+
+## 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)