eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-require-one-or-none.md

@@ -0,0 +1,165 @@
+# prefer-type-fest-require-one-or-none
+
+Require TypeFest [`RequireOneOrNone<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/require-one-or-none.d.ts) over imported aliases like `AtMostOne`.
+
+## Targeted pattern scope
+
+This rule reports imported `AtMostOne` aliases and prefers `RequireOneOrNone<T, Keys>` for zero-or-one selector constraints.
+
+Use this utility when a payload may omit all optional selectors, but must not
+provide two selectors at the same time.
+
+## What this rule reports
+
+- Type references that resolve to imported `AtMostOne` 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
+
+`RequireOneOrNone` is the canonical TypeFest utility for expressing “zero or exactly one” optional key constraints. Canonical naming keeps type utility usage predictable in public codebases.
+
+This pattern appears in query/filter payloads where no selector is valid but
+multiple selectors conflict.
+
+## ❌ Incorrect
+
+```ts
+import type { AtMostOne } from "type-aliases";
+
+type OptionalAuth = AtMostOne<{
+    token?: string;
+    apiKey?: string;
+}>;
+```
+
+## ✅ Correct
+
+```ts
+import type { RequireOneOrNone } from "type-fest";
+
+type OptionalAuth = RequireOneOrNone<{
+    token?: string;
+    apiKey?: string;
+}>;
+```
+
+## Behavior and migration notes
+
+- `RequireOneOrNone<T, Keys>` models selectors where zero is valid but more than one is invalid.
+- This rule targets alias names with equivalent semantics (`AtMostOne`).
+- Keep the key subset focused on mutually exclusive selectors to maintain readable contract intent.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { AtMostOne } from "custom-type-utils";
+
+type MonitorLookup = AtMostOne<
+    {
+        monitorId?: string;
+        slug?: string;
+    },
+    "monitorId" | "slug"
+>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { RequireOneOrNone } from "type-fest";
+
+type MonitorLookup = RequireOneOrNone<
+    {
+        monitorId?: string;
+        slug?: string;
+    },
+    "monitorId" | "slug"
+>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type SessionIdentity = RequireOneOrNone<
+    { userId?: string; guestId?: string },
+    "userId" | "guestId"
+>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-require-one-or-none": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing alias names are part of a published API contract.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/require-one-or-none.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/require-one-or-none.d.ts)
+
+````ts
+/**
+Create a type that requires exactly one of the given keys and disallows more, or none of the given keys. The remaining keys are kept as is.
+
+@example
+```
+import type {RequireOneOrNone} from 'type-fest';
+
+type Responder = RequireOneOrNone<{
+    text: () => string;
+    json: () => string;
+    secure: boolean;
+}, 'text' | 'json'>;
+
+const responder1: Responder = {
+    secure: true,
+};
+
+const responder2: Responder = {
+    text: () => '{"message": "hi"}',
+    secure: true,
+};
+
+const responder3: Responder = {
+    json: () => '{"message": "ok"}',
+    secure: true,
+};
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R059
+
+## 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-required-deep.md

@@ -0,0 +1,123 @@
+# prefer-type-fest-required-deep
+
+Require TypeFest [`RequiredDeep`](https://github.com/sindresorhus/type-fest/blob/main/source/required-deep.d.ts) over `DeepRequired` aliases.
+
+## Targeted pattern scope
+
+This rule reports `DeepRequired<T>` aliases and prefers `RequiredDeep<T>` for recursively required object shapes.
+
+## What this rule reports
+
+- Type references named `DeepRequired`.
+
+### Detection boundaries
+
+- ✅ Reports direct `DeepRequired<T>` references.
+- ❌ Does not auto-fix where legacy aliases treat nullable leaves differently.
+
+## Why this rule exists
+
+`RequiredDeep<T>` is the canonical TypeFest utility for recursively requiring nested properties.
+
+Using one utility name clarifies strict configuration and post-validation object contracts.
+
+## ❌ Incorrect
+
+```ts
+type StrictConfig = DeepRequired<AppConfig>;
+```
+
+## ✅ Correct
+
+```ts
+import type { RequiredDeep } from "type-fest";
+
+type StrictConfig = RequiredDeep<AppConfig>;
+```
+
+## Behavior and migration notes
+
+- `RequiredDeep<T>` recursively removes optional modifiers from nested properties.
+- Re-check generated API types if optionality was previously preserved in certain branches.
+- Combine with validation/parsing phases before exposing strict internal types.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-required-deep": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally standardizes `DeepRequired` naming instead of TypeFest.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/required-deep.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/required-deep.d.ts)
+
+````ts
+/**
+Create a type from another type with all keys and nested keys set to required.
+
+Use-cases:
+- Creating optional configuration interfaces where the underlying implementation still requires all options to be fully specified.
+- Modeling the resulting type after a deep merge with a set of defaults.
+
+@example
+```
+import type {RequiredDeep} from 'type-fest';
+
+type Settings = {
+    textEditor?: {
+        fontSize?: number;
+        fontColor?: string;
+        fontWeight?: number | undefined;
+    };
+    autocomplete?: boolean;
+    autosave?: boolean | undefined;
+};
+
+type RequiredSettings = RequiredDeep<Settings>;
+//=> {
+//     textEditor: {
+//         fontSize: number;
+//         fontColor: string;
+//         fontWeight: number | undefined;
+//     };
+//     autocomplete: boolean;
+//     autosave: boolean | undefined;
+// }
+```
+
+Note that types containing overloaded functions are not made deeply required due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
+
+@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+````
+
+> **Rule catalog ID:** R060
+
+## 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-schema.md

@@ -0,0 +1,161 @@
+# prefer-type-fest-schema
+
+Require TypeFest [`Schema<ObjectType, ValueType>`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts) over imported aliases like `RecordDeep`.
+
+## Targeted pattern scope
+
+This rule keeps deep object-shape transforms on the canonical `type-fest`
+utility: `Schema<ObjectType, ValueType>`.
+
+It is designed for consistency, not aggressive rewriting. Replacing third-party
+aliases such as `RecordDeep` with `Schema` is usually straightforward, but you
+should still validate semantics if your old utility had custom behavior.
+
+## What this rule reports
+
+- Imported `RecordDeep` aliases used as identifier type references.
+
+### Detection boundaries
+
+- ✅ Reports `import type { RecordDeep } ...` + `RecordDeep<...>` usage.
+- ❌ Does not report locally renamed imports (`RecordDeep as AliasRecordDeep`).
+- ❌ Does not report namespace-qualified usages such as `TypeUtils.RecordDeep<...>`.
+- ❌ Does not auto-fix.
+
+## Why this rule exists
+
+`Schema` is the canonical TypeFest utility for deep value-shape transformation across object types. Standardized naming helps readers recognize intent immediately.
+
+`type-fest` describes itself as **"A collection of essential TypeScript
+types"**. Using canonical names means engineers can jump directly between your
+code and upstream docs without translation.
+
+## ❌ Incorrect
+
+```ts
+import type { RecordDeep } from "type-aliases";
+
+type Flags = RecordDeep<Config, boolean>;
+```
+
+## ✅ Correct
+
+```ts
+import type { Schema } from "type-fest";
+
+type Flags = Schema<Config, boolean>;
+```
+
+## Behavior and migration notes
+
+- `Schema<ObjectType, ValueType>` recursively maps leaf value types while preserving object shape.
+- This rule targets imported alias names with overlapping semantics (`RecordDeep`).
+- Validate behavior if your previous alias implemented custom deep-mapping edge cases beyond `Schema`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { RecordDeep } from "custom-type-utils";
+
+type AuditMask = RecordDeep<UserProfile, "REDACTED">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { Schema } from "type-fest";
+
+type AuditMask = Schema<UserProfile, "REDACTED">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type FeatureFlags = Schema<EnvironmentConfig, boolean>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-schema": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing deep-shape aliases encode custom semantics that differ from `Schema`.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/schema.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts)
+
+````ts
+/**
+Create a deep version of another object type where property values are recursively replaced into a given value type.
+
+Use-cases:
+- Form validation: Define how each field should be validated.
+- Form settings: Define configuration for input fields.
+- Parsing: Define types that specify special behavior for specific fields.
+
+@example
+```
+import type {Schema} from 'type-fest';
+
+type User = {
+    id: string;
+    name: {
+        firstname: string;
+        lastname: string;
+    };
+    created: Date;
+    active: boolean;
+    passwordHash: string;
+    location: [latitude: number, longitude: number];
+};
+
+type UserMask = Schema<User, 'mask' | 'hide' | 'show'>;
+
+const userMaskSettings: UserMask = {
+    id: 'show',
+    name: {
+        firstname: 'show',
+        lastname: 'mask',
+    },
+    created: 'show',
+    active: 'show',
+    passwordHash: 'hide',
+    location: ['hide', 'hide'],
+};
+```
+
+@see {@link SchemaOptions}
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R061
+
+## 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-non-nullable.md

@@ -0,0 +1,145 @@
+# prefer-type-fest-set-non-nullable
+
+Require TypeFest [`SetNonNullable<T, Keys>`](https://github.com/sindresorhus/type-fest/blob/main/source/set-non-nullable.d.ts) over imported aliases like
+`NonNullableBy`.
+
+## Targeted pattern scope
+
+This rule scopes matching to imported legacy aliases that model the same semantics as `SetNonNullable<T, Keys>`.
+
+- Type references that resolve to imported `NonNullableBy` 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 `SetNonNullable<T, Keys>`.
+
+- Type references that resolve to imported `NonNullableBy` aliases.
+
+## Why this rule exists
+
+`SetNonNullable` is the canonical TypeFest utility for making selected keys
+non-nullable. Standardizing on canonical TypeFest naming keeps utility usage
+predictable in public TypeScript codebases.
+
+## ❌ Incorrect
+
+```ts
+import type { NonNullableBy } from "type-aliases";
+
+type PersistedUser = NonNullableBy<User, "id">;
+```
+
+## ✅ Correct
+
+```ts
+import type { SetNonNullable } from "type-fest";
+
+type PersistedUser = SetNonNullable<User, "id">;
+```
+
+## Behavior and migration notes
+
+- `SetNonNullable<T, Keys>` enforces non-nullability on selected keys while preserving the rest of the shape.
+- This rule targets imported alias names that duplicate the same semantics (`NonNullableBy`).
+- Use this utility for persisted/entity states where selected fields must be present and non-null after validation.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { NonNullableBy } from "type-aliases";
+
+type Persisted = NonNullableBy<User, "id">;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { SetNonNullable } from "type-fest";
+
+type Persisted = SetNonNullable<User, "id">;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type SafeOrder = SetNonNullable<Order, "orderId" | "createdAt">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-set-non-nullable": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing exported aliases must remain stable.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/set-non-nullable.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/set-non-nullable.d.ts)
+
+````ts
+/**
+Create a type that makes the given keys non-nullable, where the remaining keys are kept as is.
+
+If no keys are given, all keys will be made non-nullable.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some or all of the keys are non-nullable.
+
+@example
+```
+import type {SetNonNullable} from 'type-fest';
+
+type Foo = {
+    a: number | null;
+    b: string | undefined;
+    c?: boolean | null;
+};
+
+type SomeNonNullable = SetNonNullable<Foo, 'b' | 'c'>;
+// type SomeNonNullable = {
+//     a: number | null;
+//     b: string; // Can no longer be undefined.
+//     c?: boolean; // Can no longer be null, but is still optional.
+// }
+
+type AllNonNullable = SetNonNullable<Foo>;
+// type AllNonNullable = {
+//     a: number; // Can no longer be null.
+//     b: string; // Can no longer be undefined.
+//     c?: boolean; // Can no longer be null, but is still optional.
+// }
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R062
+
+## 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)