eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-set-optional.md

@@ -0,0 +1,133 @@
+# prefer-type-fest-set-optional
+
+Require TypeFest [`SetOptional<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts) over imported aliases like `PartialBy`.
+
+## Targeted pattern scope
+
+This rule scopes matching to imported legacy aliases that model the same semantics as `SetOptional<T, Keys>`.
+
+- Type references that resolve to imported `PartialBy` aliases.
+
+Locally defined lookalikes or unrelated type references are excluded unless they resolve to the targeted imported alias.
+
+## What this rule reports
+
+This rule reports imported alias usages that should migrate to `SetOptional<T, Keys>`.
+
+- Type references that resolve to imported `PartialBy` aliases.
+
+## Why this rule exists
+
+`SetOptional` is the canonical TypeFest utility for making selected keys optional. Standardizing on it improves discoverability and keeps utility naming consistent across projects.
+
+## ❌ Incorrect
+
+```ts
+import type { PartialBy } from "type-aliases";
+
+type PartialUser = PartialBy<User, "email">;
+```
+
+## ✅ Correct
+
+```ts
+import type { SetOptional } from "type-fest";
+
+type PartialUser = SetOptional<User, "email">;
+```
+
+## Behavior and migration notes
+
+- `SetOptional<T, Keys>` marks a selected subset of keys optional while preserving all other key modifiers.
+- This rule targets imported alias names that represent the same semantics (`PartialBy`).
+- Use this utility for draft/update shapes where only specific fields become optional.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { PartialBy } from "type-aliases";
+
+type Draft = PartialBy<User, "email">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { SetOptional } from "type-fest";
+
+type Draft = SetOptional<User, "email">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type PartialAddress = SetOptional<Address, "line2">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-set-optional": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if external contracts require preserving existing aliases.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/set-optional.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/set-optional.d.ts)
+
+````ts
+/**
+Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are optional.
+
+@example
+```
+import type {SetOptional} from 'type-fest';
+
+type Foo = {
+    a: number;
+    b?: string;
+    c: boolean;
+};
+
+type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
+// type SomeOptional = {
+//     a: number;
+//     b?: string; // Was already optional and still is.
+//     c?: boolean; // Is now optional.
+// }
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R063
+
+## 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-set-readonly.md

@@ -0,0 +1,136 @@
+# prefer-type-fest-set-readonly
+
+Require TypeFest [`SetReadonly<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/set-readonly.d.ts) over imported aliases like
+`ReadonlyBy`.
+
+## Targeted pattern scope
+
+This rule scopes matching to imported legacy aliases that model the same semantics as `SetReadonly<T, Keys>`.
+
+- Type references that resolve to imported `ReadonlyBy` aliases.
+
+Locally defined lookalikes or unrelated type references are excluded unless they resolve to the targeted imported alias.
+
+## What this rule reports
+
+This rule reports imported alias usages that should migrate to `SetReadonly<T, Keys>`.
+
+- Type references that resolve to imported `ReadonlyBy` aliases.
+
+## Why this rule exists
+
+`SetReadonly` is the canonical TypeFest utility for making selected keys
+readonly. Canonical naming improves discoverability and consistency across
+projects.
+
+## ❌ Incorrect
+
+```ts
+import type { ReadonlyBy } from "type-aliases";
+
+type ImmutableUser = ReadonlyBy<User, "id">;
+```
+
+## ✅ Correct
+
+```ts
+import type { SetReadonly } from "type-fest";
+
+type ImmutableUser = SetReadonly<User, "id">;
+```
+
+## Behavior and migration notes
+
+- `SetReadonly<T, Keys>` applies readonly modifiers to selected keys only.
+- This rule targets imported aliases with equivalent semantics (`ReadonlyBy`).
+- Use it for immutable identity fields while keeping the rest of a shape mutable.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { ReadonlyBy } from "type-aliases";
+
+type Frozen = ReadonlyBy<User, "id">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { SetReadonly } from "type-fest";
+
+type Frozen = SetReadonly<User, "id">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type ImmutableAudit = SetReadonly<AuditEntry, "timestamp" | "actor">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-set-readonly": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing exported alias names must be preserved.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/set-readonly.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/set-readonly.d.ts)
+
+````ts
+/**
+Create a type that makes the given keys readonly. The remaining keys are kept as is.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are readonly.
+
+@example
+```
+import type {SetReadonly} from 'type-fest';
+
+type Foo = {
+    a: number;
+    readonly b: string;
+    c: boolean;
+};
+
+type SomeReadonly = SetReadonly<Foo, 'b' | 'c'>;
+// type SomeReadonly = {
+//     a: number;
+//     readonly b: string; // Was already readonly and still is.
+//     readonly c: boolean; // Is now readonly.
+// }
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R064
+
+## 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-set-required.md

@@ -0,0 +1,140 @@
+# prefer-type-fest-set-required
+
+Require TypeFest [`SetRequired<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/set-required.d.ts) over imported aliases like
+`RequiredBy`.
+
+## Targeted pattern scope
+
+This rule scopes matching to imported legacy aliases that model the same semantics as `SetRequired<T, Keys>`.
+
+- Type references that resolve to imported `RequiredBy` aliases.
+
+Locally defined lookalikes or unrelated type references are excluded unless they resolve to the targeted imported alias.
+
+## What this rule reports
+
+This rule reports imported alias usages that should migrate to `SetRequired<T, Keys>`.
+
+- Type references that resolve to imported `RequiredBy` aliases.
+
+## Why this rule exists
+
+`SetRequired` is the canonical TypeFest utility for making selected keys
+required. Standardizing on TypeFest naming reduces semantic drift between
+utility libraries.
+
+## ❌ Incorrect
+
+```ts
+import type { RequiredBy } from "type-aliases";
+
+type CompleteUser = RequiredBy<User, "id">;
+```
+
+## ✅ Correct
+
+```ts
+import type { SetRequired } from "type-fest";
+
+type CompleteUser = SetRequired<User, "id">;
+```
+
+## Behavior and migration notes
+
+- `SetRequired<T, Keys>` forces selected optional keys to be required.
+- This rule targets imported aliases with equivalent semantics (`RequiredBy`).
+- Use this utility in post-validation and persisted-domain types where selected fields become mandatory.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { RequiredBy } from "type-aliases";
+
+type Complete = RequiredBy<User, "id">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { SetRequired } from "type-fest";
+
+type Complete = SetRequired<User, "id">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Persisted = SetRequired<Order, "id" | "status">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-set-required": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing exported alias names are part of a compatibility contract.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/set-required.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/set-required.d.ts)
+
+````ts
+/**
+Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are required.
+
+@example
+```
+import type {SetRequired} from 'type-fest';
+
+type Foo = {
+    a?: number;
+    b: string;
+    c?: boolean;
+};
+
+type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
+// type SomeRequired = {
+//     a?: number;
+//     b: string; // Was already required and still is.
+//     c: boolean; // Is now required.
+// }
+
+// Set specific indices in an array to be required.
+type ArrayExample = SetRequired<[number?, number?, number?], 0 | 1>;
+//=> [number, number, number?]
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R065
+
+## 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-simplify.md

@@ -0,0 +1,168 @@
+# prefer-type-fest-simplify
+
+Require TypeFest [`Simplify<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts) over imported `Prettify<T>` / `Expand<T>` aliases.
+
+## Targeted pattern scope
+
+This rule only matches type references that resolve to imported `Prettify` or `Expand` aliases and can be rewritten as `Simplify<T>`.
+
+- Type references that resolve to imported `Prettify` aliases.
+- Type references that resolve to imported `Expand` aliases.
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports imported `Prettify` / `Expand` alias usages that should be replaced with `Simplify<T>`.
+
+- Type references that resolve to imported `Prettify` aliases.
+- Type references that resolve to imported `Expand` aliases.
+
+## Why this rule exists
+
+`Simplify` is the canonical flattening utility provided by type-fest. Standardizing on it reduces utility-name churn across codebases and keeps helper usage consistent with TypeFest defaults.
+
+## ❌ Incorrect
+
+```ts
+import type { Prettify } from "type-aliases";
+
+type ViewModel = Prettify<Base & Extra>;
+```
+
+## ✅ Correct
+
+```ts
+import type { Simplify } from "type-fest";
+
+type ViewModel = Simplify<Base & Extra>;
+```
+
+## Behavior and migration notes
+
+- `Simplify<T>` normalizes intersections and mapped-type output into a flattened object shape for editor display and assignability workflows.
+- This rule targets imported alias names with overlapping semantics (`Prettify`, `Expand`).
+- Keep aliases only when they intentionally add semantics beyond plain type flattening.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { Expand } from "type-aliases";
+
+type UIModel = Expand<Base & Extra>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { Simplify } from "type-fest";
+
+type UIModel = Simplify<Base & Extra>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type ApiModel = Simplify<ResponseBase & ResponseExtra>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-simplify": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if internal tooling depends on existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/simplify.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts)
+
+````ts
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+    top: number;
+    left: number;
+};
+
+type SizeProps = {
+    width: number;
+    height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+    foo: number;
+    bar?: string;
+    baz: number | undefined;
+}
+
+type SomeType = {
+    foo: number;
+    bar?: string;
+    baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+declare function fn(object: Record<string, unknown>): void;
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+// @ts-expect-error
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see {@link SimplifyDeep}
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R066
+
+## 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)