eslint-plugin-typefest 1.0.6 → 1.0.8

package/dist/rules/prefer-type-fest-union-to-intersection.js

@@ -0,0 +1,114 @@
+import { areEquivalentTypeNodes } from "../_internal/normalize-expression-text.js";
+import { reportWithOptionalFix } from "../_internal/rule-reporting.js";
+import { unwrapParenthesizedTypeNode } from "../_internal/type-reference-node.js";
+import { createTypedRule } from "../_internal/typed-rule.js";
+const isDistributiveConditionalExtendsType = (node) => {
+    const normalizedNode = unwrapParenthesizedTypeNode(node);
+    return (normalizedNode.type === "TSAnyKeyword" ||
+        normalizedNode.type === "TSUnknownKeyword");
+};
+const getSingleFunctionParameterType = (node) => {
+    if (node.params.length !== 1) {
+        return null;
+    }
+    const [onlyParameter] = node.params;
+    if (onlyParameter?.type !== "Identifier" ||
+        onlyParameter.typeAnnotation === undefined) {
+        return null;
+    }
+    return unwrapParenthesizedTypeNode(onlyParameter.typeAnnotation.typeAnnotation);
+};
+const matchesUnionToIntersectionTrueType = (node, inferredTypeParameterName, unionType) => {
+    const normalizedNode = unwrapParenthesizedTypeNode(node);
+    if (normalizedNode.type === "TSTypeReference" &&
+        normalizedNode.typeName.type === "Identifier" &&
+        normalizedNode.typeName.name === inferredTypeParameterName) {
+        return true;
+    }
+    if (normalizedNode.type !== "TSIntersectionType" ||
+        normalizedNode.types.length !== 2) {
+        return false;
+    }
+    const [leftType, rightType] = normalizedNode.types;
+    if (leftType === undefined || rightType === undefined) {
+        return false;
+    }
+    const isInferredIdentifier = (typeNode) => typeNode.type === "TSTypeReference" &&
+        typeNode.typeName.type === "Identifier" &&
+        typeNode.typeName.name === inferredTypeParameterName;
+    return ((isInferredIdentifier(leftType) &&
+        areEquivalentTypeNodes(unwrapParenthesizedTypeNode(rightType), unwrapParenthesizedTypeNode(unionType))) ||
+        (isInferredIdentifier(rightType) &&
+            areEquivalentTypeNodes(unwrapParenthesizedTypeNode(leftType), unwrapParenthesizedTypeNode(unionType))));
+};
+const isUnionToIntersectionEquivalent = (node) => {
+    if (node.falseType.type !== "TSNeverKeyword") {
+        return false;
+    }
+    const distributedWrapper = unwrapParenthesizedTypeNode(node.checkType);
+    if (distributedWrapper.type !== "TSConditionalType") {
+        return false;
+    }
+    if (distributedWrapper.falseType.type !== "TSNeverKeyword" ||
+        !isDistributiveConditionalExtendsType(distributedWrapper.extendsType)) {
+        return false;
+    }
+    const distributedTrueType = unwrapParenthesizedTypeNode(distributedWrapper.trueType);
+    if (distributedTrueType.type !== "TSFunctionType") {
+        return false;
+    }
+    const distributedParameterType = getSingleFunctionParameterType(distributedTrueType);
+    if (distributedParameterType === null ||
+        !areEquivalentTypeNodes(distributedParameterType, unwrapParenthesizedTypeNode(distributedWrapper.checkType))) {
+        return false;
+    }
+    const extractorFunctionType = unwrapParenthesizedTypeNode(node.extendsType);
+    if (extractorFunctionType.type !== "TSFunctionType") {
+        return false;
+    }
+    const extractorParameterType = getSingleFunctionParameterType(extractorFunctionType);
+    if (extractorParameterType?.type !== "TSInferType") {
+        return false;
+    }
+    return matchesUnionToIntersectionTrueType(node.trueType, extractorParameterType.typeParameter.name.name, distributedWrapper.checkType);
+};
+/**
+ * ESLint rule definition for `prefer-type-fest-union-to-intersection`.
+ */
+const preferTypeFestUnionToIntersectionRule = createTypedRule({
+    create(context) {
+        return {
+            TSConditionalType(node) {
+                if (!isUnionToIntersectionEquivalent(node)) {
+                    return;
+                }
+                reportWithOptionalFix({
+                    context,
+                    fix: null,
+                    messageId: "preferUnionToIntersection",
+                    node,
+                });
+            },
+        };
+    },
+    defaultOptions: [],
+    meta: {
+        deprecated: false,
+        docs: {
+            description: "require TypeFest UnionToIntersection over custom distributive conditional helpers that turn unions into intersections.",
+            frozen: false,
+            recommended: false,
+            requiresTypeChecking: false,
+            typefestConfigs: ["typefest.configs.experimental"],
+            url: "https://nick2bad4u.github.io/eslint-plugin-typefest/docs/rules/prefer-type-fest-union-to-intersection",
+        },
+        messages: {
+            preferUnionToIntersection: "Prefer `UnionToIntersection<Union>` from type-fest over custom distributive conditional helpers that convert a union into an intersection.",
+        },
+        schema: [],
+        type: "suggestion",
+    },
+    name: "prefer-type-fest-union-to-intersection",
+});
+export default preferTypeFestUnionToIntersectionRule;
+//# sourceMappingURL=prefer-type-fest-union-to-intersection.js.map

package/dist/rules/prefer-type-fest-union-to-intersection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefer-type-fest-union-to-intersection.js","sourceRoot":"","sources":["../../src/rules/prefer-type-fest-union-to-intersection.ts"],"names":[],"mappings":"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"}

package/docs/rules/getting-started.md

@@ -64,7 +64,8 @@ Use this pattern when you only extend rules and want full control over parser se
 2. Fix violations in small batches.
 3. Move to `recommended-type-checked` when you are ready for typed rules.
 4. Move to `strict` once your baseline is stable.
-5. Use `all` only when you explicitly want every rule, including experimental rules.
+5. Use `all` when you want every stable rule.
+6. Use `experimental` only when you want report-only candidate rules under active evaluation.
 
 ## Need a subset instead of a full preset?
 

package/docs/rules/guides/preset-selection-strategy.md

@@ -53,6 +53,13 @@ Choose this when:
 - You want full plugin coverage and can manage incremental cleanup.
 - You actively maintain migration and suppression hygiene.
 
+### `experimental`
+
+Choose this when:
+
+- You want everything from `all` plus lower-confidence candidate rules.
+- You are comfortable evaluating report-only diagnostics before broader rollout.
+
 ### Domain overlays
 
 Layer these when they match your codebase goals:

package/docs/rules/overview.md

@@ -39,6 +39,7 @@ That is enough for TypeScript files (`**/*.{ts,tsx,mts,cts}`).
 | 🟠 `typefest.configs["recommended-type-checked"]` | [Recommended (type-checked)](./presets/recommended-type-checked.md) |
 | 🔴 `typefest.configs.strict`                      | [Strict](./presets/strict.md)                                       |
 | 🟣 `typefest.configs.all`                         | [All](./presets/all.md)                                             |
+| 🧪 `typefest.configs.experimental`                | [Experimental](./presets/experimental.md)                           |
 | 💠 `typefest.configs["type-fest/types"]`          | [type-fest/types](./presets/type-fest-types.md)                     |
 | ✴️ `typefest.configs["ts-extras/type-guards"]`    | [ts-extras/type-guards](./presets/ts-extras-type-guards.md)         |
 

package/docs/rules/prefer-ts-extras-object-map-values.md

@@ -0,0 +1,146 @@
+# prefer-ts-extras-object-map-values
+
+Prefer [`objectMapValues`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-map-values.ts) from `ts-extras` over key-preserving `objectFromEntries(objectEntries(...).map(...))` chains.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on `ts-extras` entry pipelines whose callback preserves the original key and only changes the value.
+
+- `objectFromEntries(objectEntries(value).map(([key, item]) => [key, nextValue]))`
+- the same shape with a block body that immediately returns `[key, nextValue]`
+
+It intentionally skips broader patterns that can encode different intent.
+
+## What this rule reports
+
+This rule reports ts-extras object remapping chains when all of the following are true:
+
+- the outer call is `objectFromEntries(...)`
+- the inner source is `objectEntries(...)`
+- the intermediate step is a direct `.map(...)` call
+- the callback is an arrow function with a strict `[key, value]` tuple parameter
+- the callback returns a two-item tuple whose first item is the original `key`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`objectMapValues` reduces noise in a common value-only remapping pattern.
+
+- The callback contract matches the intent directly: `(value, key) => nextValue`.
+- Readers do not need to mentally unpack an entries pipeline to see that keys stay the same.
+- The code avoids a temporary array of tuples in authored source.
+
+Because this pattern appears in semantically different forms, the rule stays narrow on purpose and reports only equivalent key-preserving remaps.
+
+## ❌ Incorrect
+
+```ts
+import {objectEntries, objectFromEntries} from "ts-extras";
+
+const statusById = {
+    alpha: "up",
+    beta: "down",
+} as const;
+
+const labels = objectFromEntries(
+    objectEntries(statusById).map(([key, value]) => [key, `${key}:${value}`])
+);
+```
+
+## ✅ Correct
+
+```ts
+import {objectMapValues} from "ts-extras";
+
+const statusById = {
+    alpha: "up",
+    beta: "down",
+} as const;
+
+const labels = objectMapValues(
+    statusById,
+    (value, key) => `${key}:${value}`
+);
+```
+
+## Behavior and migration notes
+
+- This rule only reports chains that preserve the original key unchanged.
+- It ignores native `Object.entries` / `Object.fromEntries` pipelines to avoid overlapping with the stable `objectEntries` and `objectFromEntries` adoption rules.
+- It ignores `.map(...)` calls that pass a `thisArg`, because `objectMapValues` does not have an equivalent callback binding parameter.
+- It ignores function-expression callbacks for now, because the experimental rule avoids assuming `this` behavior is irrelevant.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import {objectEntries, objectFromEntries} from "ts-extras";
+
+const statusById = {
+    alpha: "up",
+    beta: "down",
+} as const;
+
+const uppercased = objectFromEntries(
+    objectEntries(statusById).map(([key, value]) => [key, value.toUpperCase()])
+);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import {objectMapValues} from "ts-extras";
+
+const statusById = {
+    alpha: "up",
+    beta: "down",
+} as const;
+
+const uppercased = objectMapValues(statusById, (value) => value.toUpperCase());
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [typefest.configs.experimental];
+```
+
+## When not to use it
+
+Disable this rule if your team prefers explicit entry-tuple pipelines for readability, or if the remapping logic changes keys often enough that `objectMapValues` is not the dominant style.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-map-values.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-map-values.ts)
+
+```ts
+import {objectMapValues} from "ts-extras";
+
+const object = {a: 1, b: 2, c: 3};
+
+const mapped = objectMapValues(object, value => String(value));
+//=> {a?: string; b?: string; c?: string}
+```
+
+> **Rule catalog ID:** R086
+
+## Further reading
+
+- [`ts-extras` README](https://github.com/sindresorhus/ts-extras)
+- [`ts-extras` package reference](https://www.npmjs.com/package/ts-extras)
+- [MDN: Array.prototype.map()](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+- [MDN: Object.fromEntries()](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)
+- [Preset selection strategy](./guides/preset-selection-strategy.md)

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

@@ -0,0 +1,93 @@
+# prefer-type-fest-asyncify
+
+Prefer [`Asyncify`](https://github.com/sindresorhus/type-fest/blob/main/source/asyncify.d.ts) from `type-fest` over manual asyncified function-type wrappers.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on two narrow shapes:
+
+- direct function-type wrappers of the form `(...args: Parameters<Function>) => Promise<Awaited<ReturnType<Function>>>`
+- `SetReturnType<Function, Promise<Awaited<ReturnType<Function>>>>` compositions
+
+It intentionally skips broader promise-returning wrappers so the report signal stays specific to `Asyncify`.
+
+## What this rule reports
+
+This rule reports when all of the following are true:
+
+- the wrapper keeps the original parameter list through `Parameters<Function>` or `SetReturnType<Function, ...>`
+- the new return type is exactly `Promise<Awaited<ReturnType<Function>>>`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`Asyncify<Function>` communicates the intent directly.
+
+- Readers can tell immediately that a synchronous function type is being boxed into an async equivalent.
+- The helper avoids repeating the `Promise<Awaited<ReturnType<...>>>` boilerplate.
+- It composes naturally with other Type-Fest function helpers.
+
+## ❌ Incorrect
+
+```ts
+type AsyncVersion<Function_ extends (...arguments_: any[]) => any> =
+    (...arguments_: Parameters<Function_>) =>
+        Promise<Awaited<ReturnType<Function_>>>;
+```
+
+## ✅ Correct
+
+```ts
+import type {Asyncify} from "type-fest";
+
+type AsyncVersion<Function_ extends (...arguments_: any[]) => any> =
+    Asyncify<Function_>;
+```
+
+## Behavior and migration notes
+
+- This rule intentionally overlaps with `SetReturnType` only for the exact asyncified return shape, and it takes precedence there.
+- It reports both the raw wrapper and the `SetReturnType<..., Promise<Awaited<ReturnType<...>>>>` composition.
+- It ignores non-async `SetReturnType` usage.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [typefest.configs.experimental];
+```
+
+## When not to use it
+
+Disable this rule if your team prefers the explicit wrapper signature or if you want to reserve `Asyncify` for only a subset of wrapper types.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/asyncify.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/asyncify.d.ts)
+
+```ts
+import type {Asyncify} from "type-fest";
+
+type AsyncVersion<Function_ extends (...arguments_: any[]) => any> =
+    Asyncify<Function_>;
+```
+
+> **Rule catalog ID:** R093
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Awaited](https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype)
+- [TypeScript Handbook: ReturnType](https://www.typescriptlang.org/docs/handbook/utility-types.html#returntypetype)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)
+- [Preset selection strategy](./guides/preset-selection-strategy.md)

package/docs/rules/prefer-type-fest-conditional-except.md

@@ -0,0 +1,141 @@
+# prefer-type-fest-conditional-except
+
+Prefer [`ConditionalExcept`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-except.d.ts) from `type-fest` over `Except<Base, ConditionalKeys<Base, Condition>>` compositions.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on direct `type-fest` compositions that already use both `Except` and `ConditionalKeys` together.
+
+- `Except<Base, ConditionalKeys<Base, Condition>>`
+- the same shape when `Except` and `ConditionalKeys` are imported under local aliases from `type-fest`
+
+It intentionally skips builtin `Omit<Base, ConditionalKeys<Base, Condition>>` shapes to avoid overlapping with the stable `prefer-type-fest-except` rule.
+
+## What this rule reports
+
+This rule reports `type-fest` compositions when all of the following are true:
+
+- the outer type reference resolves to `Except`
+- the second type argument resolves to `ConditionalKeys`
+- the base type passed to `Except` matches the base type passed to `ConditionalKeys`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`ConditionalExcept<Base, Condition>` expresses the intent of conditional omission directly.
+
+- Readers do not need to mentally expand two helper types to understand the result.
+- The single helper form is shorter and easier to scan in large type aliases.
+- The intent stays aligned with the upstream Type-Fest utility that already models this exact composition.
+
+## ❌ Incorrect
+
+```ts
+import type {ConditionalKeys, Except} from "type-fest";
+
+type Example = {
+    count: number;
+    enabled: boolean;
+    name: string;
+};
+
+type NonStrings = Except<Example, ConditionalKeys<Example, string>>;
+```
+
+## ✅ Correct
+
+```ts
+import type {ConditionalExcept} from "type-fest";
+
+type Example = {
+    count: number;
+    enabled: boolean;
+    name: string;
+};
+
+type NonStrings = ConditionalExcept<Example, string>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the direct `Except<..., ConditionalKeys<...>>` composition.
+- It ignores builtin `Omit` forms on purpose to avoid duplicate reporting with `prefer-type-fest-except`.
+- It ignores compositions where the `ConditionalKeys` base type does not exactly match the `Except` base type.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type {ConditionalKeys as MatchingKeys, Except as StrictExcept} from "type-fest";
+
+type Example = {
+    count: number;
+    enabled: boolean;
+    name: string;
+};
+
+type NonStrings = StrictExcept<Example, MatchingKeys<Example, string>>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type {ConditionalExcept} from "type-fest";
+
+type Example = {
+    count: number;
+    enabled: boolean;
+    name: string;
+};
+
+type NonStrings = ConditionalExcept<Example, string>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [typefest.configs.experimental];
+```
+
+## When not to use it
+
+Disable this rule if your team prefers explicit helper-type composition over the shorter canonical alias, or if you want `Except` and `ConditionalKeys` to stay visible for teaching purposes.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/conditional-except.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-except.d.ts)
+
+```ts
+import type {ConditionalExcept} from "type-fest";
+
+type Example = {
+    a: string;
+    b: string | number;
+    c: () => void;
+};
+
+type NonStringKeysOnly = ConditionalExcept<Example, string>;
+//=> {b: string | number; c: () => void}
+```
+
+> **Rule catalog ID:** R087
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` package reference](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Conditional Types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)
+- [Preset selection strategy](./guides/preset-selection-strategy.md)

package/docs/rules/prefer-type-fest-conditional-keys.md

@@ -0,0 +1,93 @@
+# prefer-type-fest-conditional-keys
+
+Prefer [`ConditionalKeys`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-keys.d.ts) from `type-fest` over manual `keyof`-remapped key filters.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on the common pattern that filters keys by value condition through `keyof` over a mapped type:
+
+- `keyof { [K in keyof Base as Base[K] extends Condition ? K : never]: ... }`
+
+It intentionally skips more elaborate helpers that involve strictness wrappers, tuple-to-object conversions, or additional conditional layers.
+
+## What this rule reports
+
+This rule reports `keyof`-wrapped mapped types when all of the following are true:
+
+- the key constraint is `keyof Base`
+- the key remap condition is `Base[K] extends Condition ? K : never`
+- the outer type operator is `keyof`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`ConditionalKeys<Base, Condition>` is easier to read than the raw remapping recipe.
+
+- The helper name explains the intent immediately.
+- Readers do not need to mentally evaluate the mapped type and outer `keyof`.
+- Standardizing on Type-Fest reduces duplicated local helper patterns.
+
+## ❌ Incorrect
+
+```ts
+type KeysMatching<Base, Condition> = keyof {
+    [Key in keyof Base as Base[Key] extends Condition
+        ? Key
+        : never]: never;
+};
+```
+
+## ✅ Correct
+
+```ts
+import type {ConditionalKeys} from "type-fest";
+
+type KeysMatching<Base, Condition> = ConditionalKeys<Base, Condition>;
+```
+
+## Behavior and migration notes
+
+- This rule targets only the narrow `keyof`-remapped key-filter pattern.
+- It ignores plain mapped types that are not wrapped in `keyof`.
+- It also ignores more elaborate Type-Fest-internal strictness variants to avoid speculative reporting.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [typefest.configs.experimental];
+```
+
+## When not to use it
+
+Disable this rule if your project prefers the explicit remapped-key form or if your helper intentionally diverges from Type-Fest semantics.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/conditional-keys.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-keys.d.ts)
+
+```ts
+import type {ConditionalKeys} from "type-fest";
+
+type KeysMatching<Base, Condition> = ConditionalKeys<Base, Condition>;
+```
+
+> **Rule catalog ID:** R095
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Mapped Types](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html)
+- [TypeScript Handbook: Conditional Types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)
+- [Preset selection strategy](./guides/preset-selection-strategy.md)