eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-omit-index-signature.md

@@ -0,0 +1,196 @@
+# prefer-type-fest-omit-index-signature
+
+Require TypeFest [`OmitIndexSignature<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/omit-index-signature.d.ts) over imported aliases like
+`RemoveIndexSignature`.
+
+## Targeted pattern scope
+
+This rule targets imported alias names used for removing index signatures from object types.
+
+## What this rule reports
+
+- Type references that resolve to imported `RemoveIndexSignature` aliases.
+
+## Why this rule exists
+
+`OmitIndexSignature` is the canonical TypeFest utility for stripping index
+signatures while preserving explicitly-declared fields. Using the canonical
+name improves consistency across utility libraries.
+
+## ❌ Incorrect
+
+```ts
+import type { RemoveIndexSignature } from "type-zoo";
+
+type StrictUser = RemoveIndexSignature<User>;
+```
+
+## ✅ Correct
+
+```ts
+import type { OmitIndexSignature } from "type-fest";
+
+type StrictUser = OmitIndexSignature<User>;
+```
+
+## Behavior and migration notes
+
+- `OmitIndexSignature<T>` strips broad index signatures while preserving explicit properties.
+- This rule targets alias names with equivalent semantics (`RemoveIndexSignature`).
+- Use it when converting permissive dictionary-like types into explicit contract shapes.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { RemoveIndexSignature } from "type-zoo";
+
+type Explicit = RemoveIndexSignature<User>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { OmitIndexSignature } from "type-fest";
+
+type Explicit = OmitIndexSignature<User>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type PublicModel = OmitIndexSignature<ModelWithIndex>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-omit-index-signature": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if external contract compatibility requires existing alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/omit-index-signature.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/omit-index-signature.d.ts)
+
+````ts
+/**
+Omit any index signatures from the given object type, leaving only explicitly defined properties.
+
+This is the counterpart of `PickIndexSignature`.
+
+Use-cases:
+- Remove overly permissive signatures from third-party types.
+
+This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
+It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
+
+(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
+
+```
+const indexed: Record<string, unknown> = {}; // Allowed
+
+// @ts-expect-error
+const keyed: Record<'foo', unknown> = {}; // Error
+// TS2739: Type '{}' is missing the following properties from type 'Record<"foo" | "bar", unknown>': foo, bar
+```
+
+Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:
+
+```
+type Indexed = {} extends Record<string, unknown>
+    ? '✅ `{}` is assignable to `Record<string, unknown>`'
+    : '❌ `{}` is NOT assignable to `Record<string, unknown>`';
+
+type IndexedResult = Indexed;
+//=> '✅ `{}` is assignable to `Record<string, unknown>`'
+
+type Keyed = {} extends Record<'foo' | 'bar', unknown>
+    ? '✅ `{}` is assignable to `Record<\'foo\' | \'bar\', unknown>`'
+    : '❌ `{}` is NOT assignable to `Record<\'foo\' | \'bar\', unknown>`';
+
+type KeyedResult = Keyed;
+//=> '❌ `{}` is NOT assignable to `Record<\'foo\' | \'bar\', unknown>`'
+```
+
+Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
+
+```
+type OmitIndexSignature<ObjectType> = {
+    [KeyType in keyof ObjectType // Map each key of `ObjectType`...
+    ]: ObjectType[KeyType]; // ...to its original value, i.e. `OmitIndexSignature<Foo> == Foo`.
+};
+```
+
+...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
+
+```
+type OmitIndexSignature<ObjectType> = {
+    [KeyType in keyof ObjectType
+    // Is `{}` assignable to `Record<KeyType, unknown>`?
+    as {} extends Record<KeyType, unknown>
+        ? never // ✅ `{}` is assignable to `Record<KeyType, unknown>`
+        : KeyType // ❌ `{}` is NOT assignable to `Record<KeyType, unknown>`
+    ]: ObjectType[KeyType];
+};
+```
+
+If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
+
+@example
+```
+import type {OmitIndexSignature} from 'type-fest';
+
+type Example = {
+    // These index signatures will be removed.
+    [x: string]: any;
+    [x: number]: any;
+    [x: symbol]: any;
+    [x: `head-${string}`]: string;
+    [x: `${string}-tail`]: string;
+    [x: `head-${string}-tail`]: string;
+    [x: `${bigint}`]: string;
+    [x: `embedded-${number}`]: string;
+
+    // These explicitly defined keys will remain.
+    foo: 'bar';
+    qux?: 'baz';
+};
+
+type ExampleWithoutIndexSignatures = OmitIndexSignature<Example>;
+//=> {foo: 'bar'; qux?: 'baz'}
+```
+
+@see {@link PickIndexSignature}
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R051
+
+## 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-partial-deep.md

@@ -0,0 +1,133 @@
+# prefer-type-fest-partial-deep
+
+Require TypeFest [`PartialDeep`](https://github.com/sindresorhus/type-fest/blob/main/source/partial-deep.d.ts) over `DeepPartial` aliases.
+
+## Targeted pattern scope
+
+This rule reports `DeepPartial<T>` aliases and prefers `PartialDeep<T>` for recursive optional patch types.
+
+## What this rule reports
+
+- Type references named `DeepPartial`.
+
+### Detection boundaries
+
+- ✅ Reports direct `DeepPartial<T>` type references.
+- ❌ Does not auto-fix where project-local aliases have non-TypeFest semantics.
+
+## Why this rule exists
+
+`PartialDeep<T>` is the canonical TypeFest utility for recursive optionality.
+
+Using a single name for deep patch semantics makes update/persistence DTOs easier to audit.
+
+## ❌ Incorrect
+
+```ts
+type Patch = DeepPartial<AppConfig>;
+```
+
+## ✅ Correct
+
+```ts
+import type { PartialDeep } from "type-fest";
+
+type Patch = PartialDeep<AppConfig>;
+```
+
+## Behavior and migration notes
+
+- `PartialDeep<T>` recursively marks nested properties optional.
+- Validate parity if your legacy alias excluded arrays, maps, or sets.
+- Prefer narrowing the patch surface with `Pick`/`Except` before applying deep optionality.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-partial-deep": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally standardizes `DeepPartial` naming instead of TypeFest.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/partial-deep.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/partial-deep.d.ts)
+
+````ts
+/**
+Create a type from another type with all keys and nested keys set to optional.
+
+Use-cases:
+- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
+- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
+
+@example
+```
+import type {PartialDeep} from 'type-fest';
+
+let settings = {
+    textEditor: {
+        fontSize: 14,
+        fontColor: '#000000',
+        fontWeight: 400,
+    },
+    autocomplete: false,
+    autosave: true,
+};
+
+const applySavedSettings = (savedSettings: PartialDeep<typeof settings>) => (
+    {...settings, ...savedSettings, textEditor: {...settings.textEditor, ...savedSettings.textEditor}}
+);
+
+settings = applySavedSettings({textEditor: {fontWeight: 500}});
+```
+
+By default, this does not affect elements in array and tuple types. You can change this by passing `{recurseIntoArrays: true}` as the second type argument:
+
+```
+import type {PartialDeep} from 'type-fest';
+
+type Shape = {
+    dimensions: [number, number];
+};
+
+const partialShape: PartialDeep<Shape, {recurseIntoArrays: true}> = {
+    dimensions: [], // OK
+};
+
+partialShape.dimensions = [15]; // OK
+```
+
+@see {@link PartialDeepOptions}
+
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+````
+
+> **Rule catalog ID:** R052
+
+## 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-primitive.md

@@ -0,0 +1,106 @@
+# prefer-type-fest-primitive
+
+Require TypeFest [`Primitive`](https://github.com/sindresorhus/type-fest/blob/main/source/primitive.d.ts) over explicit unions of primitive keyword types.
+
+## Targeted pattern scope
+
+This rule targets full primitive keyword unions used as standalone scalar aliases.
+
+## What this rule reports
+
+- Unions composed of all primitive keyword types:
+  - `string`
+  - `number`
+  - `bigint`
+  - `boolean`
+  - `symbol`
+  - `null`
+  - `undefined`
+
+## Why this rule exists
+
+`Primitive` communicates intent directly and avoids repeating a long union in multiple places.
+
+## ❌ Incorrect
+
+```ts
+type PrimitiveValue = string | number | bigint | boolean | symbol | null | undefined;
+```
+
+## ✅ Correct
+
+```ts
+type PrimitiveValue = Primitive;
+```
+
+## Behavior and migration notes
+
+- `Primitive` covers all JS primitive categories: `string`, `number`, `bigint`, `boolean`, `symbol`, `null`, `undefined`.
+- This rule targets unions that include the complete primitive set.
+- Keep explicit subsets when domain semantics require only a subset of primitive categories.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Scalar = string | number | bigint | boolean | symbol | null | undefined;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Scalar = Primitive;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type LeafValue = Primitive;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-primitive": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if explicit primitive unions are part of a published API contract.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/primitive.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/primitive.d.ts)
+
+```ts
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+```
+
+> **Rule catalog ID:** R053
+
+## 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-promisable.md

@@ -0,0 +1,246 @@
+# prefer-type-fest-promisable
+
+Require TypeFest [`Promisable<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/promisable.d.ts) for sync-or-async callback contracts currently expressed as `Promise<T> | T` unions.
+
+## Targeted pattern scope
+
+This rule narrows matching to strict two-member Promise/base unions where `Promisable<T>` is the canonical replacement.
+
+- Type unions shaped like `Promise<T> | T` in architecture-critical runtime layers.
+
+Multi-member unions and Promise-adjacent variants stay out of scope unless they exactly match the authored pair form.
+
+## What this rule reports
+
+This rule reports strict `Promise<T> | T`-shaped unions that should be expressed as `Promisable<T>`.
+
+- Type unions shaped like `Promise<T> | T` in architecture-critical runtime layers.
+- Type references that resolve to imported legacy aliases such as `MaybePromise`.
+
+### Detection boundaries
+
+- ✅ Reports strict `Promise<T> | T` / `T | Promise<T>` unions by default.
+- ✅ Reports imported legacy aliases such as `MaybePromise` by default.
+- ❌ Does not report namespace-qualified aliases.
+- ✅ Auto-fixes imported legacy alias references when replacement is syntactically safe.
+- ❌ Does not auto-fix `Promise<T> | T` union declarations.
+- ✅ Enforcement surface is configurable with `enforcePromiseUnions` and `enforceLegacyAliases`.
+
+## Why this rule exists
+
+`Promisable<T>` communicates intent directly, keeps callback contracts consistent, and avoids repeating equivalent sync-or-async unions throughout the codebase.
+
+## ❌ Incorrect
+
+```ts
+type HookResult = Promise<Result> | Result;
+```
+
+## ✅ Correct
+
+```ts
+type HookResult = Promisable<Result>;
+```
+
+## Behavior and migration notes
+
+- `Promisable<T>` captures sync-or-async return contracts in one reusable alias.
+- It normalizes both `Promise<T> | T` and `T | Promise<T>` forms.
+- Use this alias in hook/callback contracts where callers may return either immediate or async values.
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTypeFestPromisableOptions = {
+    /**
+     * Whether to report imported legacy aliases such as MaybePromise.
+     *
+     * @default true
+     */
+    enforceLegacyAliases?: boolean;
+
+    /**
+     * Whether to report Promise<T> | T sync-or-async unions.
+     *
+     * @default true
+     */
+    enforcePromiseUnions?: boolean;
+};
+```
+
+Default configuration:
+
+```ts
+{
+    enforceLegacyAliases: true,
+    enforcePromiseUnions: true,
+}
+```
+
+Flat config setup (default behavior):
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-promisable": [
+                "error",
+                {
+                    enforceLegacyAliases: true,
+                    enforcePromiseUnions: true,
+                },
+            ],
+        },
+    },
+];
+```
+
+#### `enforcePromiseUnions: false`
+
+Ignores union-shaped contracts while still enforcing legacy aliases:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-promisable": [
+                "error",
+                {
+                    enforceLegacyAliases: true,
+                    enforcePromiseUnions: false,
+                },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { MaybePromise } from "type-aliases";
+
+type A = Promise<Result> | Result; // ✅ Not reported
+type B = MaybePromise<Result>; // ❌ Reported
+```
+
+#### `enforceLegacyAliases: false`
+
+Ignores legacy aliases while still enforcing union-shaped contracts:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-promisable": [
+                "error",
+                {
+                    enforceLegacyAliases: false,
+                    enforcePromiseUnions: true,
+                },
+            ],
+        },
+    },
+];
+```
+
+```ts
+import type { MaybePromise } from "type-aliases";
+
+type A = MaybePromise<Result>; // ✅ Not reported
+type B = Promise<Result> | Result; // ❌ Reported
+```
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type MaybeAsync = Result | Promise<Result>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type MaybeAsync = Promisable<Result>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type HookOutput = Promisable<void>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-promisable": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if runtime policy requires explicitly spelling out promise unions.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/promisable.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/promisable.d.ts)
+
+````ts
+/**
+Create a type that represents either the value or the value wrapped in `PromiseLike`.
+
+Use-cases:
+- A function accepts a callback that may either return a value synchronously or may return a promised value.
+- This type could be the return type of `Promise#then()`, `Promise#catch()`, and `Promise#finally()` callbacks.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {Promisable} from 'type-fest';
+
+async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
+    const entry = await getLogEntry();
+    console.log(entry);
+}
+
+await logger(() => 'foo');
+await logger(() => Promise.resolve('bar'));
+```
+
+@category Async
+*/
+````
+
+> **Rule catalog ID:** R054
+
+## 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)