eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-async-return-type.md

@@ -0,0 +1,117 @@
+# prefer-type-fest-async-return-type
+
+Require TypeFest [`AsyncReturnType<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/async-return-type.d.ts) over `Awaited<ReturnType<T>>` compositions.
+
+## Targeted pattern scope
+
+This rule targets nested built-in utility compositions used for async return extraction.
+
+## What this rule reports
+
+- Type references shaped like `Awaited<ReturnType<T>>`.
+
+## Why this rule exists
+
+`AsyncReturnType<T>` is easier to scan and more explicit about intent than stacking two utility types. Using the TypeFest alias also keeps async return extraction conventions consistent across the codebase.
+
+## ❌ Incorrect
+
+```ts
+type Output = Awaited<ReturnType<typeof fetchData>>;
+```
+
+## ✅ Correct
+
+```ts
+type Output = AsyncReturnType<typeof fetchData>;
+```
+
+## Behavior and migration notes
+
+- `AsyncReturnType<F>` is the canonical replacement for `Awaited<ReturnType<F>>` in function-return extraction.
+- This rule targets the exact composition shape rather than all uses of `Awaited` or `ReturnType`.
+- Keep direct built-in utilities when you intentionally need non-function or partially-unwrapped patterns.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Data = Awaited<ReturnType<typeof fetchUser>>; // Repeated built-in composition
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Data = AsyncReturnType<typeof fetchUser>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type MutationResult = AsyncReturnType<typeof saveSettings>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-async-return-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if explicit built-in utility composition is required for local style consistency.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/async-return-type.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/async-return-type.d.ts)
+
+````ts
+/**
+Unwrap the return type of a function that returns a `Promise`.
+
+There has been [discussion](https://github.com/microsoft/TypeScript/pull/35998) about implementing this type in TypeScript.
+
+@example
+```ts
+import type {AsyncReturnType} from 'type-fest';
+
+declare function asyncFunction(): Promise<{foo: string}>;
+
+// This type resolves to the unwrapped return type of `asyncFunction`.
+type Value = AsyncReturnType<typeof asyncFunction>;
+//=> {foo: string}
+
+declare function doSomething(value: Value): void;
+
+const value = await asyncFunction();
+doSomething(value);
+```
+
+@category Async
+*/
+````
+
+> **Rule catalog ID:** R037
+
+## 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-conditional-pick.md

@@ -0,0 +1,140 @@
+# prefer-type-fest-conditional-pick
+
+Require TypeFest [`ConditionalPick<T, Condition>`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-pick.d.ts) over imported aliases like `PickByTypes`.
+
+## Targeted pattern scope
+
+This rule targets imported alias names that mirror TypeFest conditional property selection semantics.
+
+## What this rule reports
+
+- Type references that resolve to imported `PickByTypes` aliases.
+
+## Why this rule exists
+
+`ConditionalPick` is the canonical TypeFest utility for selecting fields by value type. Standardizing on TypeFest naming improves discoverability and improves consistency.
+
+## ❌ Incorrect
+
+```ts
+import type { PickByTypes } from "type-aliases";
+
+type StringProps = PickByTypes<User, string>;
+```
+
+## ✅ Correct
+
+```ts
+import type { ConditionalPick } from "type-fest";
+
+type StringProps = ConditionalPick<User, string>;
+```
+
+## Behavior and migration notes
+
+- `ConditionalPick<T, Condition>` selects keys whose value types extend `Condition`.
+- This rule targets alias names with equivalent semantics (`PickByTypes`).
+- Keep aliases only when they intentionally add behavior beyond simple conditional key filtering.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { PickByTypes } from "type-aliases";
+
+type StringFields = PickByTypes<User, string>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { ConditionalPick } from "type-fest";
+
+type StringFields = ConditionalPick<User, string>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type DateFields = ConditionalPick<User, Date>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-conditional-pick": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if compatibility requirements force existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/conditional-pick.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/conditional-pick.d.ts)
+
+````ts
+/**
+Pick keys from the shape that matches the given `Condition`.
+
+This is useful when you want to create a new type from a specific subset of an existing type. For example, you might want to pick all the primitive properties from a class and form a new automatically derived type.
+
+@example
+```
+import type {Primitive, ConditionalPick} from 'type-fest';
+
+class Awesome {
+    constructor(public name: string, public successes: number, public failures: bigint) {}
+
+    run() {
+        // do something
+    }
+}
+
+type PickPrimitivesFromAwesome = ConditionalPick<Awesome, Primitive>;
+//=> {name: string; successes: number; failures: bigint}
+```
+
+@example
+```
+import type {ConditionalPick} from 'type-fest';
+
+type Example = {
+    a: string;
+    b: string | number;
+    c: () => void;
+    d: {};
+};
+
+type StringKeysOnly = ConditionalPick<Example, string>;
+//=> {a: string}
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R038
+
+## 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-constructor.md

@@ -0,0 +1,87 @@
+# prefer-type-fest-constructor
+
+Require TypeFest [`Constructor`](https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts) over explicit constructor signatures.
+
+## Targeted pattern scope
+
+This rule reports explicit `new (...args) => T` signatures and prefers `Constructor<T>` for newable class contracts.
+
+## What this rule reports
+
+- `new (...args) => T` constructor type signatures.
+
+### Detection boundaries
+
+- ✅ Reports explicit non-abstract constructor signatures in type positions.
+- ❌ Does not auto-fix when argument-generic relationships need manual preservation.
+
+## Why this rule exists
+
+`Constructor<T>` is a canonical alias for class factory contracts.
+
+Using one alias across modules keeps dependency-injection and class-registry types uniform.
+
+## ❌ Incorrect
+
+```ts
+type ExplicitCtor = new (host: string, port: number) => Service;
+```
+
+## ✅ Correct
+
+```ts
+import type { Constructor } from "type-fest";
+
+type ServiceCtor = Constructor<Service>;
+```
+
+## Behavior and migration notes
+
+- `Constructor<T>` expresses "newable" class values that produce `T`.
+- Preserve specialized argument tuples with wrapper types when replacing explicit signatures.
+- Prefer this alias in public APIs to avoid repeated constructor signature boilerplate.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-constructor": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally prefers explicit constructor signatures over TypeFest aliases.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/basic.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts)
+
+```ts
+/**
+Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+
+@category Class
+*/
+```
+
+> **Rule catalog ID:** R039
+
+## Further reading
+
+- [TypeFest README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Classes](https://www.typescriptlang.org/docs/handbook/2/classes.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-except.md

@@ -0,0 +1,231 @@
+# prefer-type-fest-except
+
+Require TypeFest [`Except<T, K>`](https://github.com/sindresorhus/type-fest/blob/main/source/except.d.ts) over `Omit<T, K>` when removing keys from object types.
+
+## Targeted pattern scope
+
+This rule targets `Omit<T, K>` object-shaping references and imported aliases such as `HomomorphicOmit` that can be replaced by the TypeFest canonical utility.
+
+## What this rule reports
+
+- Type references shaped like `Omit<T, K>`.
+- Type references that resolve to imported `HomomorphicOmit` aliases.
+
+### Detection boundaries
+
+- ✅ Reports built-in `Omit<T, K>` by default.
+- ✅ Reports imported aliases with direct named imports.
+- ❌ Does not report namespace-qualified aliases.
+- ✅ Auto-fixes imported alias references to `Except` when replacement is syntactically safe.
+- ❌ Does not auto-fix built-in `Omit<T, K>` references.
+- ✅ Built-in `Omit<T, K>` coverage is configurable with `enforceBuiltinOmit`.
+
+## Why this rule exists
+
+`Except<T, K>` from type-fest models omitted keys more strictly and keeps object-shaping conventions aligned with other TypeFest utilities used in this plugin.
+
+## ❌ Incorrect
+
+```ts
+type PublicUser = Omit<User, "password">;
+```
+
+## ✅ Correct
+
+```ts
+type PublicUser = Except<User, "password">;
+```
+
+## Behavior and migration notes
+
+- `Except<T, K>` is the canonical object-key removal utility in this plugin's type-fest style.
+- Migrate direct `Omit<T, K>` aliases in shared contracts to keep one naming convention.
+- Review constraint behavior if existing helper wrappers add semantics beyond key omission.
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTypeFestExceptOptions = {
+    /**
+     * Whether to report built-in Omit<T, K> usages.
+     *
+     * @default true
+     */
+    enforceBuiltinOmit?: boolean;
+};
+```
+
+Default configuration:
+
+```ts
+{
+    enforceBuiltinOmit: true,
+}
+```
+
+Flat config setup (default behavior):
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-except": [
+                "error",
+                { enforceBuiltinOmit: true },
+            ],
+        },
+    },
+];
+```
+
+#### `enforceBuiltinOmit: true` (default)
+
+Reports both built-in `Omit<T, K>` and imported aliases.
+
+#### `enforceBuiltinOmit: false`
+
+Reports imported aliases, but ignores built-in `Omit<T, K>`:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-except": [
+                "error",
+                { enforceBuiltinOmit: false },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { HomomorphicOmit } from "type-aliases";
+
+type A = Omit<User, "password">; // ✅ Not reported
+type B = HomomorphicOmit<User, "password">; // ❌ Reported
+```
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type PublicUser = Omit<User, "password" | "token">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type PublicUser = Except<User, "password" | "token">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Internalless = Except<ApiResponse, "internal">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-except": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if public type contracts intentionally expose `Omit` as part of the API surface.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/except.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/except.d.ts)
+
+````ts
+/**
+Create a type from an object type without certain keys.
+
+We recommend setting the `requireExactProps` option to `true`.
+
+This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
+
+This type was proposed to the TypeScript team, which declined it, saying they prefer that libraries implement stricter versions of the built-in types ([microsoft/TypeScript#30825](https://github.com/microsoft/TypeScript/issues/30825#issuecomment-523668235)).
+
+@example
+```
+import type {Except} from 'type-fest';
+
+type Foo = {
+    a: number;
+    b: string;
+};
+
+type FooWithoutA = Except<Foo, 'a'>;
+//=> {b: string}
+
+// @ts-expect-error
+const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
+// errors: 'a' does not exist in type '{ b: string; }'
+
+type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
+//=> {a: number} & Partial<Record<'b', never>>
+
+// @ts-expect-error
+const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
+// errors at 'b': Type 'string' is not assignable to type 'undefined'.
+
+// The `Omit` utility type doesn't work when omitting specific keys from objects containing index signatures.
+
+// Consider the following example:
+
+type UserData = {
+    [metadata: string]: string;
+    email: string;
+    name: string;
+    role: 'admin' | 'user';
+};
+
+// `Omit` clearly doesn't behave as expected in this case:
+type PostPayload = Omit<UserData, 'email'>;
+//=> {[x: string]: string; [x: number]: string}
+
+// In situations like this, `Except` works better.
+// It simply removes the `email` key while preserving all the other keys.
+type PostPayloadFixed = Except<UserData, 'email'>;
+//=> {[x: string]: string; name: string; role: 'admin' | 'user'}
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R040
+
+## 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)