eslint-plugin-typefest 1.0.6 → 1.0.7

package/docs/rules/prefer-type-fest-distributed-omit.md

@@ -0,0 +1,92 @@
+# prefer-type-fest-distributed-omit
+
+Prefer [`DistributedOmit`](https://github.com/sindresorhus/type-fest/blob/main/source/distributed-omit.d.ts) from `type-fest` over distributive conditional helpers built from `Omit`.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on the common helper shape that distributes `Omit` over a union manually:
+
+- `Union extends unknown ? Omit<Union, Key> : never`
+- `Union extends any ? Omit<Union, Key> : never`
+
+It intentionally ignores ordinary non-distributive `Omit` usage and unrelated conditional helpers.
+
+## What this rule reports
+
+This rule reports conditional helpers when all of the following are true:
+
+- the false branch is `never`
+- the conditional distributes over the checked type with `extends unknown` or `extends any`
+- the true branch is exactly `Omit<CheckedType, KeyType>`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`DistributedOmit<ObjectType, KeyType>` makes the union-preserving behavior explicit.
+
+- Readers do not need to mentally simulate the distributive conditional.
+- The Type-Fest helper explains why this is different from plain `Omit`.
+- Consistent adoption reduces duplicate one-off helpers across a codebase.
+
+## ❌ Incorrect
+
+```ts
+type WithoutKeys<Union, Key extends PropertyKey> =
+    Union extends unknown ? Omit<Union, Key> : never;
+```
+
+## ✅ Correct
+
+```ts
+import type {DistributedOmit} from "type-fest";
+
+type WithoutKeys<Union, Key extends PropertyKey> =
+    DistributedOmit<Union, Key>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the narrow distributive-`Omit` helper pattern.
+- It does not report ordinary `Omit<T, K>` usage.
+- It does not try to prove that your generic key constraints match Type-Fest exactly; it only reports the direct structural helper pattern.
+
+## 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 to keep a local distributive helper name or if you intentionally avoid Type-Fest for these object-union utilities.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/distributed-omit.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/distributed-omit.d.ts)
+
+```ts
+import type {DistributedOmit} from "type-fest";
+
+type Result<Union, Key extends PropertyKey> = DistributedOmit<Union, Key>;
+```
+
+> **Rule catalog ID:** R090
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Conditional Types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html)
+- [TypeScript Handbook: Omit](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)
+
+## 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-distributed-pick.md

@@ -0,0 +1,92 @@
+# prefer-type-fest-distributed-pick
+
+Prefer [`DistributedPick`](https://github.com/sindresorhus/type-fest/blob/main/source/distributed-pick.d.ts) from `type-fest` over distributive conditional helpers built from `Pick`.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on the common helper shape that distributes `Pick` over a union manually:
+
+- `Union extends unknown ? Pick<Union, Key> : never`
+- `Union extends any ? Pick<Union, Extract<Key, keyof Union>> : never`
+
+It intentionally ignores ordinary non-distributive `Pick` usage and unrelated conditional helpers.
+
+## What this rule reports
+
+This rule reports conditional helpers when all of the following are true:
+
+- the false branch is `never`
+- the conditional distributes over the checked type with `extends unknown` or `extends any`
+- the true branch is exactly `Pick<CheckedType, KeyType>` or `Pick<CheckedType, Extract<KeyType, keyof CheckedType>>`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`DistributedPick<ObjectType, KeyType>` makes the union-preserving behavior explicit.
+
+- The helper reads as a named concept instead of a conditional-type trick.
+- It communicates why plain `Pick` is not enough for union-heavy object types.
+- Standardizing on the upstream utility reduces local helper drift.
+
+## ❌ Incorrect
+
+```ts
+type OnlyKeys<Union, Key extends PropertyKey> =
+    Union extends unknown ? Pick<Union, Key> : never;
+```
+
+## ✅ Correct
+
+```ts
+import type {DistributedPick} from "type-fest";
+
+type OnlyKeys<Union, Key extends PropertyKey> =
+    DistributedPick<Union, Key>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the narrow distributive-`Pick` helper pattern.
+- It accepts the `Extract<Key, keyof Union>` variant because that is a common way to keep the built-in `Pick` constraint satisfied.
+- It does not report plain `Pick<T, K>` 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 project prefers a local helper name for distributive picking or if you intentionally avoid Type-Fest for object-union utilities.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/distributed-pick.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/distributed-pick.d.ts)
+
+```ts
+import type {DistributedPick} from "type-fest";
+
+type Result<Union, Key extends PropertyKey> = DistributedPick<Union, Key>;
+```
+
+> **Rule catalog ID:** R091
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Conditional Types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html)
+- [TypeScript Handbook: Pick](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys)
+
+## 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-merge.md

@@ -0,0 +1,161 @@
+# prefer-type-fest-merge
+
+Prefer [`Merge`](https://github.com/sindresorhus/type-fest/blob/main/source/merge.d.ts) from `type-fest` over `Except<Destination, keyof Source> & Source` intersections.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on direct merge-style intersections that already use `Except` from `type-fest` to remove overridden keys before intersecting with the overriding source type.
+
+- `Except<Destination, keyof Source> & Source`
+- `Source & Except<Destination, keyof Source>`
+
+It intentionally skips builtin `Omit` forms and broader intersections to avoid overlapping with stable rules and to keep the report signal narrow.
+
+## What this rule reports
+
+This rule reports intersections when all of the following are true:
+
+- one intersection member resolves to `Except`
+- the second type argument to `Except` is exactly `keyof Source`
+- the sibling intersection member is exactly `Source`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`Merge<Destination, Source>` states the override relationship directly.
+
+- Readers do not need to unpack an `Except`-plus-intersection recipe.
+- The canonical helper signals that the second type wins on overlapping keys.
+- The upstream utility also simplifies the resulting object type for tooling display.
+
+## ❌ Incorrect
+
+```ts
+import type {Except} from "type-fest";
+
+type Base = {
+    id: string;
+    name: string;
+};
+
+type Overrides = {
+    name: number;
+    readonly ok: true;
+};
+
+type Combined = Except<Base, keyof Overrides> & Overrides;
+```
+
+## ✅ Correct
+
+```ts
+import type {Merge} from "type-fest";
+
+type Base = {
+    id: string;
+    name: string;
+};
+
+type Overrides = {
+    name: number;
+    readonly ok: true;
+};
+
+type Combined = Merge<Base, Overrides>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the exact `Except<Destination, keyof Source> & Source` pattern.
+- It ignores `Omit<Destination, keyof Source> & Source` so it does not double-report with `prefer-type-fest-except`.
+- It ignores intersections whose sibling type does not match the `keyof` operand exactly.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type {Except as StrictExcept} from "type-fest";
+
+type Base = {
+    id: string;
+    name: string;
+};
+
+type Overrides = {
+    name: number;
+    readonly ok: true;
+};
+
+type Combined = Overrides & StrictExcept<Base, keyof Overrides>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type {Merge} from "type-fest";
+
+type Base = {
+    id: string;
+    name: string;
+};
+
+type Overrides = {
+    name: number;
+    readonly ok: true;
+};
+
+type Combined = Merge<Base, Overrides>;
+```
+
+## 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 `Except<..., keyof ...> & ...` construction, or if you want to keep the override mechanism visible in source types.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/merge.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/merge.d.ts)
+
+```ts
+import type {Merge} from "type-fest";
+
+type Foo = {
+    a: string;
+    b: number;
+};
+
+type Bar = {
+    a: number;
+    c: boolean;
+};
+
+type FooBar = Merge<Foo, Bar>;
+//=> {a: number; b: number; c: boolean}
+```
+
+> **Rule catalog ID:** R088
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` package reference](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Intersection Types](https://www.typescriptlang.org/docs/handbook/2/objects.html#intersection-types)
+
+## 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-pick-index-signature.md

@@ -0,0 +1,93 @@
+# prefer-type-fest-pick-index-signature
+
+Prefer [`PickIndexSignature`](https://github.com/sindresorhus/type-fest/blob/main/source/pick-index-signature.d.ts) from `type-fest` over manual mapped types that keep only index signatures.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on the canonical mapped-type counterpart to `PickIndexSignature`:
+
+- `{ [K in keyof T as {} extends Record<K, unknown> ? K : never]: T[K] }`
+
+It intentionally skips the inverse `OmitIndexSignature` pattern and broader remapping logic.
+
+## What this rule reports
+
+This rule reports mapped types when all of the following are true:
+
+- the key constraint is `keyof ObjectType`
+- the key remap condition is `{} extends Record<Key, unknown> ? Key : never`
+- the mapped value is `ObjectType[Key]`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`PickIndexSignature<ObjectType>` names the intent directly.
+
+- Readers do not need to decode the `Record<Key, unknown>` trick.
+- The helper makes it obvious that only index signatures survive.
+- Using the upstream utility keeps this niche pattern consistent across a codebase.
+
+## ❌ Incorrect
+
+```ts
+type IndexOnly<ObjectType> = {
+    [Key in keyof ObjectType as {} extends Record<Key, unknown>
+        ? Key
+        : never]: ObjectType[Key];
+};
+```
+
+## ✅ Correct
+
+```ts
+import type {PickIndexSignature} from "type-fest";
+
+type IndexOnly<ObjectType> = PickIndexSignature<ObjectType>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the narrow canonical mapped-type pattern.
+- It intentionally ignores the inverse `{} extends Record<Key, unknown> ? never : Key` form because that belongs to `OmitIndexSignature`, not `PickIndexSignature`.
+- It also ignores broader remapped types that do more than keep index signatures.
+
+## 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 mapped type or if you want to reserve `PickIndexSignature` for only a subset of object utility code.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/pick-index-signature.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/pick-index-signature.d.ts)
+
+```ts
+import type {PickIndexSignature} from "type-fest";
+
+type IndexOnly<ObjectType> = PickIndexSignature<ObjectType>;
+```
+
+> **Rule catalog ID:** R094
+
+## 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: keyof](https://www.typescriptlang.org/docs/handbook/2/keyof-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-set-return-type.md

@@ -0,0 +1,93 @@
+# prefer-type-fest-set-return-type
+
+Prefer [`SetReturnType`](https://github.com/sindresorhus/type-fest/blob/main/source/set-return-type.d.ts) from `type-fest` over direct function-type wrappers built from `Parameters`.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on direct function-type wrappers of the form:
+
+- `(...args: Parameters<Function>) => Result`
+
+It intentionally skips the async-specific `Promise<Awaited<ReturnType<Function>>>` shape so the more specific `prefer-type-fest-asyncify` rule can handle that case.
+
+## What this rule reports
+
+This rule reports function types when all of the following are true:
+
+- the function type has exactly one rest parameter
+- that rest parameter is typed as `Parameters<Function>`
+- the return type is not the original `ReturnType<Function>`
+- the return type is not the `Asyncify` shape `Promise<Awaited<ReturnType<Function>>>`
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`SetReturnType<Function, Result>` states the transformation directly.
+
+- Readers can see that only the return type changes.
+- The helper is easier to reuse consistently across wrapper types.
+- It avoids repeating the same `Parameters<...>` boilerplate in local helper types.
+
+## ❌ Incorrect
+
+```ts
+type WithResult<Function_ extends (...arguments_: any[]) => any, Result> =
+    (...arguments_: Parameters<Function_>) => Result;
+```
+
+## ✅ Correct
+
+```ts
+import type {SetReturnType} from "type-fest";
+
+type WithResult<Function_ extends (...arguments_: any[]) => any, Result> =
+    SetReturnType<Function_, Result>;
+```
+
+## Behavior and migration notes
+
+- This rule targets the narrow rest-parameter form `(...args: Parameters<F>) => R`.
+- It ignores ordinary handwritten function types with explicit parameters.
+- It intentionally defers asyncified wrappers to `prefer-type-fest-asyncify`.
+
+## 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 to spell out the wrapper function type explicitly or if you need a custom helper name for return-type rewrites.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/set-return-type.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/set-return-type.d.ts)
+
+```ts
+import type {SetReturnType} from "type-fest";
+
+type Wrapped<Function_ extends (...arguments_: any[]) => any> =
+    SetReturnType<Function_, string>;
+```
+
+> **Rule catalog ID:** R092
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Parameters](https://www.typescriptlang.org/docs/handbook/utility-types.html#parameterstype)
+- [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-stringified.md

@@ -0,0 +1,134 @@
+# prefer-type-fest-stringified
+
+Prefer [`Stringified`](https://github.com/sindresorhus/type-fest/blob/main/source/stringified.d.ts) from `type-fest` over manual mapped types of the form `{ [K in keyof T]: string }`.
+
+This rule lives only in the experimental preset and reports without autofixing.
+
+## Targeted pattern scope
+
+This rule focuses on direct mapped types that convert every property value in a source object type to `string`.
+
+- `{ [Key in keyof T]: string }`
+
+It intentionally skips mapped types with readonly modifiers, optional modifiers, key remapping, or non-string value expressions.
+
+## What this rule reports
+
+This rule reports mapped types when all of the following are true:
+
+- the key constraint is exactly `keyof T`
+- the mapped value type is exactly `string`
+- there is no key remapping
+- there are no readonly or optional mapped modifiers
+
+The rule is currently **report-only**. It does not autofix or suggest a replacement yet.
+
+## Why this rule exists
+
+`Stringified<T>` names the transformation directly.
+
+- The helper is shorter than repeating the mapped-type recipe inline.
+- The intent is easier to recognize in form models and serialization layers.
+- The shared utility keeps the codebase consistent when the same transformation appears in multiple places.
+
+## ❌ Incorrect
+
+```ts
+type Car = {
+    model: string;
+    speed: number;
+};
+
+type CarForm = { [Key in keyof Car]: string };
+```
+
+## ✅ Correct
+
+```ts
+import type {Stringified} from "type-fest";
+
+type Car = {
+    model: string;
+    speed: number;
+};
+
+type CarForm = Stringified<Car>;
+```
+
+## Behavior and migration notes
+
+- This rule only reports the exact mapped-type shape `{ [Key in keyof T]: string }`.
+- It ignores mapped types that also change key names or property modifiers.
+- It ignores mapped types whose value side is not exactly `string`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Payload = {
+    attemptCount: number;
+    success: boolean;
+};
+
+type PayloadForm = { [Key in keyof Payload]: string };
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type {Stringified} from "type-fest";
+
+type Payload = {
+    attemptCount: number;
+    success: boolean;
+};
+
+type PayloadForm = Stringified<Payload>;
+```
+
+## 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 inline mapped types for one-off transformations, or if the mapped type needs to evolve beyond the exact `Stringified<T>` shape.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/stringified.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/stringified.d.ts)
+
+```ts
+import type {Stringified} from "type-fest";
+
+type Car = {
+    model: string;
+    speed: number;
+};
+
+const carForm: Stringified<Car> = {
+    model: "Foo",
+    speed: "101",
+};
+```
+
+> **Rule catalog ID:** R089
+
+## Further reading
+
+- [`type-fest` README](https://github.com/sindresorhus/type-fest)
+- [`type-fest` package reference](https://www.npmjs.com/package/type-fest)
+- [TypeScript Handbook: Mapped Types](https://www.typescriptlang.org/docs/handbook/2/mapped-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)