eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-readonly-deep.md

@@ -0,0 +1,151 @@
+# prefer-type-fest-readonly-deep
+
+Require TypeFest [`ReadonlyDeep`](https://github.com/sindresorhus/type-fest/blob/main/source/readonly-deep.d.ts) over `DeepReadonly` aliases.
+
+## Targeted pattern scope
+
+This rule reports `DeepReadonly<T>` aliases and prefers `ReadonlyDeep<T>` for recursive immutability contracts.
+
+## What this rule reports
+
+- Type references named `DeepReadonly`.
+
+### Detection boundaries
+
+- ✅ Reports direct `DeepReadonly<T>` type references.
+- ❌ Does not auto-fix when legacy helper semantics differ for containers.
+
+## Why this rule exists
+
+`ReadonlyDeep<T>` is TypeFest's canonical deep immutability utility.
+
+Canonical naming prevents mixed deep-readonly conventions in shared contract packages.
+
+## ❌ Incorrect
+
+```ts
+type Config = DeepReadonly<AppConfig>;
+```
+
+## ✅ Correct
+
+```ts
+import type { ReadonlyDeep } from "type-fest";
+
+type Config = ReadonlyDeep<AppConfig>;
+```
+
+## Behavior and migration notes
+
+- `ReadonlyDeep<T>` recursively applies readonly semantics to nested structures.
+- Verify behavior for maps/sets/tuples if your prior alias had custom handling.
+- Prefer applying deep readonly at API boundaries where mutation should be prevented.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-readonly-deep": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally standardizes `DeepReadonly` naming instead of TypeFest.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/readonly-deep.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/readonly-deep.d.ts)
+
+````ts
+/**
+Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
+
+This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {ReadonlyDeep} from 'type-fest';
+
+declare const foo: {
+    a: string;
+    b: {c: number};
+    d: Array<{e: number}>;
+};
+
+foo.a = 'bar'; // Allowed
+
+foo.b = {c: 3}; // Allowed
+
+foo.b.c = 4; // Allowed
+
+foo.d = [{e: 5}]; // Allowed
+
+foo.d.push({e: 6}); // Allowed
+
+const last = foo.d.at(-1);
+if (last) {
+    last.e = 7; // Allowed
+}
+
+declare const readonlyFoo: ReadonlyDeep<typeof foo>;
+
+// @ts-expect-error
+readonlyFoo.a = 'bar';
+// Error: Cannot assign to 'a' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.b = {c: 3};
+// Error: Cannot assign to 'b' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.b.c = 4;
+// Error: Cannot assign to 'c' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.d = [{e: 5}];
+// Error: Cannot assign to 'd' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.d.push({e: 6});
+// Error: Property 'push' does not exist on type 'ReadonlyArray<{readonly e: number}>'.
+
+const readonlyLast = readonlyFoo.d.at(-1);
+if (readonlyLast) {
+    // @ts-expect-error
+    readonlyLast.e = 8;
+    // Error: Cannot assign to 'e' because it is a read-only property.
+}
+```
+
+Note that types containing overloaded functions are not made deeply readonly due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
+
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+````
+
+> **Rule catalog ID:** R055
+
+## Further reading
+
+- [TypeFest README](https://github.com/sindresorhus/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-require-all-or-none.md

@@ -0,0 +1,149 @@
+# prefer-type-fest-require-all-or-none
+
+Require TypeFest [`RequireAllOrNone<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/require-all-or-none.d.ts) over imported aliases like
+`AllOrNone` or `AllOrNothing`.
+
+## Targeted pattern scope
+
+This rule reports imported `AllOrNone`/`AllOrNothing` aliases and prefers `RequireAllOrNone<T, Keys>` for atomic key-group constraints.
+
+Use this utility when fields only make sense as a complete set (for example,
+`username` + `password`, or `country` + `vatId`).
+
+## What this rule reports
+
+- Type references that resolve to imported `AllOrNone` aliases.
+- Type references that resolve to imported `AllOrNothing` aliases.
+
+### Detection boundaries
+
+- ✅ Reports imported aliases with direct named imports.
+- ❌ Does not report namespace-qualified alias usage.
+- ❌ Does not auto-fix.
+
+## Why this rule exists
+
+`RequireAllOrNone` is the canonical TypeFest utility for expressing atomic key
+groups (either every key in the group exists, or none of them do). Canonical
+naming reduces semantic drift across utility libraries.
+
+This is one of the easiest places for contract bugs to hide in API request
+types. A single canonical utility makes these constraints explicit.
+
+## ❌ Incorrect
+
+```ts
+import type { AllOrNone } from "type-aliases";
+
+type Credentials = AllOrNone<User, "username" | "password">;
+```
+
+## ✅ Correct
+
+```ts
+import type { RequireAllOrNone } from "type-fest";
+
+type Credentials = RequireAllOrNone<User, "username" | "password">;
+```
+
+## Behavior and migration notes
+
+- `RequireAllOrNone<T, Keys>` enforces atomic key groups (all keys present together or all omitted).
+- This rule targets alias names that encode the same constraint (`AllOrNone`, `AllOrNothing`).
+- Keep key-group definitions explicit and colocated with contract types to avoid drift.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { AllOrNothing } from "custom-type-utils";
+
+type BillingIdentity = AllOrNothing<OrderInput, "country" | "vatId">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { RequireAllOrNone } from "type-fest";
+
+type BillingIdentity = RequireAllOrNone<OrderInput, "country" | "vatId">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type OAuthPair = RequireAllOrNone<AuthInput, "clientId" | "clientSecret">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-all-or-none": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing exported aliases must stay unchanged for compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/require-all-or-none.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/require-all-or-none.d.ts)
+
+````ts
+/**
+Create a type that requires all of the given keys or none of the given keys. The remaining keys are kept as is.
+
+Use-cases:
+- Creating interfaces for components with mutually-inclusive keys.
+
+The caveat with `RequireAllOrNone` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireAllOrNone` can't do anything to prevent extra keys it doesn't know about.
+
+@example
+```
+import type {RequireAllOrNone} from 'type-fest';
+
+type Responder = {
+    text?: () => string;
+    json?: () => string;
+    secure: boolean;
+};
+
+const responder1: RequireAllOrNone<Responder, 'text' | 'json'> = {
+    secure: true,
+};
+
+const responder2: RequireAllOrNone<Responder, 'text' | 'json'> = {
+    text: () => '{"message": "hi"}',
+    json: () => '{"message": "ok"}',
+    secure: true,
+};
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R056
+
+## 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-require-at-least-one.md

@@ -0,0 +1,155 @@
+# prefer-type-fest-require-at-least-one
+
+Require TypeFest [`RequireAtLeastOne<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/require-at-least-one.d.ts) over imported aliases like
+`AtLeastOne`.
+
+## Targeted pattern scope
+
+This rule reports imported `AtLeastOne` aliases and prefers `RequireAtLeastOne<T, Keys>` for at-least-one field requirements.
+
+It is especially valuable for search DTOs and patch/update payloads where
+empty objects should be rejected at compile time.
+
+## What this rule reports
+
+- Type references that resolve to imported `AtLeastOne` aliases.
+
+### Detection boundaries
+
+- ✅ Reports imported aliases with direct named imports.
+- ❌ Does not report namespace-qualified aliases.
+- ❌ Does not auto-fix.
+
+## Why this rule exists
+
+`RequireAtLeastOne` is the canonical TypeFest utility for enforcing at least one
+required key among a set of optional candidates. Standardizing on canonical
+TypeFest naming keeps public type contracts easier to understand and maintain.
+
+For user-facing APIs, this avoids accepting meaningless payloads like `{}`
+where at least one filter field is required.
+
+## ❌ Incorrect
+
+```ts
+import type { AtLeastOne } from "type-aliases";
+
+type Update = AtLeastOne<User>;
+```
+
+## ✅ Correct
+
+```ts
+import type { RequireAtLeastOne } from "type-fest";
+
+type Update = RequireAtLeastOne<User>;
+```
+
+## Behavior and migration notes
+
+- `RequireAtLeastOne<T, Keys>` prevents empty-object payloads when at least one selector is required.
+- This rule targets alias names with equivalent semantics (`AtLeastOne`).
+- Use keyed variants for large object types to constrain only the fields that participate in the requirement.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { AtLeastOne } from "custom-type-utils";
+
+type UserSearch = AtLeastOne<
+    {
+        email?: string;
+        id?: string;
+        username?: string;
+    },
+    "email" | "id" | "username"
+>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { RequireAtLeastOne } from "type-fest";
+
+type UserSearch = RequireAtLeastOne<
+    {
+        email?: string;
+        id?: string;
+        username?: string;
+    },
+    "email" | "id" | "username"
+>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type ProfilePatch = RequireAtLeastOne<
+    { avatarUrl?: string; displayName?: string; bio?: string },
+    "avatarUrl" | "displayName" | "bio"
+>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-at-least-one": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if published contracts must preserve existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/require-at-least-one.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/require-at-least-one.d.ts)
+
+````ts
+/**
+Create a type that requires at least one of the given keys. The remaining keys are kept as is.
+
+@example
+```
+import type {RequireAtLeastOne} from 'type-fest';
+
+type Responder = {
+    text?: () => string;
+    json?: () => string;
+    secure?: boolean;
+};
+
+const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
+    json: () => '{"message": "ok"}',
+    secure: true,
+};
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R057
+
+## 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-require-exactly-one.md

@@ -0,0 +1,240 @@
+# prefer-type-fest-require-exactly-one
+
+Require TypeFest [`RequireExactlyOne<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/require-exactly-one.d.ts) over imported aliases like `OneOf` or `RequireOnlyOne`.
+
+## Targeted pattern scope
+
+This rule reports imported `OneOf`/`RequireOnlyOne` aliases and prefers `RequireExactlyOne<T, Keys>` for XOR-style object constraints.
+
+Use this when callers must choose one mode, not multiple modes (for example,
+`id` _or_ `slug`, `apiKey` _or_ `token`).
+
+## What this rule reports
+
+- Type references that resolve to imported `OneOf` aliases.
+- Type references that resolve to imported `RequireOnlyOne` aliases.
+
+### Detection boundaries
+
+- ✅ Reports imported aliases with direct named imports.
+- ❌ Does not report namespace-qualified alias usage.
+- ✅ Auto-fixes imported alias references to `RequireExactlyOne` when replacement is syntactically safe.
+- ✅ Alias coverage is configurable with `enforcedAliasNames`.
+
+## Why this rule exists
+
+`RequireExactlyOne` is the canonical TypeFest utility for enforcing exactly one active key among a set. Using the canonical name reduces semantic drift between utility libraries.
+
+This is one of the most error-prone constraints in hand-written unions. Using a
+known utility keeps intent obvious and consistent.
+
+## ❌ Incorrect
+
+```ts
+import type { OneOf } from "type-aliases";
+
+type Auth = OneOf<{
+    token?: string;
+    apiKey?: string;
+}>;
+```
+
+## ✅ Correct
+
+```ts
+import type { RequireExactlyOne } from "type-fest";
+
+type Auth = RequireExactlyOne<{
+    token?: string;
+    apiKey?: string;
+}>;
+```
+
+## Behavior and migration notes
+
+- `RequireExactlyOne<T, Keys>` encodes XOR object modes where one and only one key can be active.
+- This rule targets alias names with matching semantics (`OneOf`, `RequireOnlyOne`).
+- Keep the participating key set small and explicit to avoid hard-to-read error messages in consuming code.
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTypeFestRequireExactlyOneOptions = {
+    /**
+     * Legacy alias names that this rule will report and replace.
+     *
+     * @default ["OneOf", "RequireOnlyOne"]
+     */
+    enforcedAliasNames?: ("OneOf" | "RequireOnlyOne")[];
+};
+```
+
+Default configuration:
+
+```ts
+{
+    enforcedAliasNames: ["OneOf", "RequireOnlyOne"],
+}
+```
+
+Flat config setup (default behavior):
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-exactly-one": [
+                "error",
+                { enforcedAliasNames: ["OneOf", "RequireOnlyOne"] },
+            ],
+        },
+    },
+];
+```
+
+#### `enforcedAliasNames: ["OneOf", "RequireOnlyOne"]` (default)
+
+Reports both legacy aliases.
+
+#### `enforcedAliasNames: ["RequireOnlyOne"]`
+
+Reports only `RequireOnlyOne` and ignores `OneOf`:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-exactly-one": [
+                "error",
+                { enforcedAliasNames: ["RequireOnlyOne"] },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { OneOf, RequireOnlyOne } from "type-aliases";
+
+type A = OneOf<{ a?: string; b?: number }>; // ✅ Not reported
+type B = RequireOnlyOne<{ a?: string; b?: number }>; // ❌ Reported
+```
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { RequireOnlyOne } from "custom-type-utils";
+
+type LookupInput = RequireOnlyOne<
+    {
+        id?: string;
+        slug?: string;
+        externalRef?: string;
+    },
+    "id" | "slug" | "externalRef"
+>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { RequireExactlyOne } from "type-fest";
+
+type LookupInput = RequireExactlyOne<
+    {
+        id?: string;
+        slug?: string;
+        externalRef?: string;
+    },
+    "id" | "slug" | "externalRef"
+>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type AuthInput = RequireExactlyOne<
+    { token?: string; apiKey?: string; oauthCode?: string },
+    "token" | "apiKey" | "oauthCode"
+>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-exactly-one": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if compatibility requirements force existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/require-exactly-one.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/require-exactly-one.d.ts)
+
+````ts
+/**
+Create a type that requires exactly one of the given keys and disallows more. The remaining keys are kept as is.
+
+Use-cases:
+- Creating interfaces for components that only need one of the keys to display properly.
+- Declaring generic keys in a single place for a single use-case that gets narrowed down via `RequireExactlyOne`.
+
+The caveat with `RequireExactlyOne` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireExactlyOne` can't do anything to prevent extra keys it doesn't know about.
+
+@example
+```
+import type {RequireExactlyOne} from 'type-fest';
+
+type Responder = {
+    text: () => string;
+    json: () => string;
+    secure: boolean;
+};
+
+const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
+    // Adding a `text` key here would cause a compile error.
+
+    json: () => '{"message": "ok"}',
+    secure: true,
+};
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R058
+
+## 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)