eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-type-fest-unknown-map.md

@@ -0,0 +1,123 @@
+# prefer-type-fest-unknown-map
+
+Require TypeFest [`UnknownMap`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-map.d.ts) over `ReadonlyMap<unknown, unknown>`.
+
+## Targeted pattern scope
+
+This rule targets explicit unknown-map spellings that TypeFest standardizes as `UnknownMap`.
+
+- `ReadonlyMap<unknown, unknown>` type references.
+
+Other collection contracts are left alone unless they match the exact unknown collection form listed below.
+
+## What this rule reports
+
+This rule reports unknown-map type forms that should migrate to `UnknownMap`.
+
+- `ReadonlyMap<unknown, unknown>` type references.
+
+## Why this rule exists
+
+`UnknownMap` communicates intent directly and keeps unknown-container aliases consistent with other TypeFest-first conventions in this plugin.
+
+## ❌ Incorrect
+
+```ts
+type Meta = ReadonlyMap<unknown, unknown>;
+```
+
+## ✅ Correct
+
+```ts
+type Meta = UnknownMap;
+```
+
+## Behavior and migration notes
+
+- `UnknownMap` is a canonical alias for maps with unknown key/value pairs.
+- Normalize map ingress contracts to one alias instead of repeating `ReadonlyMap<unknown, unknown>`.
+- Narrow key/value types at use sites after validating actual runtime shapes.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Store = ReadonlyMap<unknown, unknown>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Store = UnknownMap;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Metadata = UnknownMap;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-unknown-map": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if published contracts must preserve existing map alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/unknown-map.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-map.d.ts)
+
+````ts
+/**
+Represents a map with `unknown` key and value.
+
+Use case: You want a type that all maps can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownMap} from 'type-fest';
+
+type IsMap<T> = T extends UnknownMap ? true : false;
+
+type A = IsMap<Map<string, number>>;
+//=> true
+
+type B = IsMap<ReadonlyMap<number, string>>;
+//=> true
+
+type C = IsMap<string>;
+//=> false
+```
+
+@category Type
+*/
+````
+
+> **Rule catalog ID:** R070
+
+## 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-unknown-record.md

@@ -0,0 +1,130 @@
+# prefer-type-fest-unknown-record
+
+Prefers `UnknownRecord` from TypeFest over `Record<string, unknown>` in architecture-critical layers.
+
+## Targeted pattern scope
+
+This rule targets explicit unknown-record spellings that TypeFest standardizes as `UnknownRecord`.
+
+- `Record<string, unknown>` type references in configured boundary paths (for example shared contracts and IPC-adjacent layers).
+
+Other collection contracts are left alone unless they match the exact unknown collection form listed below.
+
+## What this rule reports
+
+This rule reports unknown-record type forms that should migrate to `UnknownRecord`.
+
+- `Record<string, unknown>` type references in configured boundary paths (for example shared contracts and IPC-adjacent layers).
+
+## Why this rule exists
+
+`UnknownRecord` conveys intent directly and keeps boundary contracts consistent with TypeFest-first typing conventions.
+
+## ❌ Incorrect
+
+```ts
+type Payload = Record<string, unknown>;
+```
+
+## ✅ Correct
+
+```ts
+type Payload = UnknownRecord;
+```
+
+## Behavior and migration notes
+
+- `UnknownRecord` is the canonical dictionary-like unknown-object alias in `type-fest`.
+- Standardize boundary object contracts on `UnknownRecord` instead of repeating `Record<string, unknown>`.
+- Keep runtime validation and field narrowing at call sites that consume unknown records.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Input = Record<string, unknown>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Input = UnknownRecord;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type EventPayload = UnknownRecord;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-unknown-record": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if a public contract requires preserving existing record alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/unknown-record.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-record.d.ts)
+
+````ts
+/**
+Represents an object with `unknown` value. You probably want this instead of `{}`.
+
+Use case: You have an object whose keys and values are unknown to you.
+
+@example
+```
+import type {UnknownRecord} from 'type-fest';
+
+function toJson(object: UnknownRecord) {
+    return JSON.stringify(object);
+}
+
+toJson({hello: 'world'}); // Ok
+
+function isObject(value: unknown): value is UnknownRecord {
+    return typeof value === 'object' && value !== null;
+}
+
+const value: unknown = {hello: 'world'};
+
+if (isObject(value)) {
+    const v = value;
+    //=> UnknownRecord
+}
+```
+
+@category Type
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R071
+
+## 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-unknown-set.md

@@ -0,0 +1,123 @@
+# prefer-type-fest-unknown-set
+
+Require TypeFest [`UnknownSet`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-set.d.ts) over `ReadonlySet<unknown>`.
+
+## Targeted pattern scope
+
+This rule targets explicit unknown-set spellings that TypeFest standardizes as `UnknownSet`.
+
+- `ReadonlySet<unknown>` type references.
+
+Other collection contracts are left alone unless they match the exact unknown collection form listed below.
+
+## What this rule reports
+
+This rule reports unknown-set type forms that should migrate to `UnknownSet`.
+
+- `ReadonlySet<unknown>` type references.
+
+## Why this rule exists
+
+`UnknownSet` provides a clearer shared alias for unknown-valued sets and keeps TypeFest utility usage consistent with other rules in this plugin.
+
+## ❌ Incorrect
+
+```ts
+type Keys = ReadonlySet<unknown>;
+```
+
+## ✅ Correct
+
+```ts
+type Keys = UnknownSet;
+```
+
+## Behavior and migration notes
+
+- `UnknownSet` is the canonical alias for unknown-valued readonly sets.
+- Normalize `ReadonlySet<unknown>` usage to one alias to avoid duplicate naming patterns.
+- Narrow member types after membership checks in consuming code.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Keys = ReadonlySet<unknown>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Keys = UnknownSet;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type DynamicSet = UnknownSet;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-unknown-set": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if exported type names must remain unchanged.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/unknown-set.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/unknown-set.d.ts)
+
+````ts
+/**
+Represents a set with `unknown` value.
+
+Use case: You want a type that all sets can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownSet} from 'type-fest';
+
+type IsSet<T> = T extends UnknownSet ? true : false;
+
+type A = IsSet<Set<string>>;
+//=> true
+
+type B = IsSet<ReadonlySet<number>>;
+//=> true
+
+type C = IsSet<string>;
+//=> false
+```
+
+@category Type
+*/
+````
+
+> **Rule catalog ID:** R072
+
+## 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-unwrap-tagged.md

@@ -0,0 +1,133 @@
+# prefer-type-fest-unwrap-tagged
+
+Require TypeFest [`UnwrapTagged`](https://github.com/sindresorhus/type-fest/blob/main/source/tagged.d.ts) over imported aliases like `UnwrapOpaque`.
+
+## Targeted pattern scope
+
+This rule targets deprecated `UnwrapOpaque` alias usage.
+
+## What this rule reports
+
+- Type references that resolve to imported `UnwrapOpaque` aliases.
+
+## Why this rule exists
+
+`UnwrapOpaque` is deprecated in TypeFest in favor of `UnwrapTagged`.
+Standardizing on the canonical utility avoids deprecated API usage and keeps
+types aligned with current TypeFest docs.
+
+## ❌ Incorrect
+
+```ts
+import type { UnwrapOpaque } from "type-fest";
+
+type RawId = UnwrapOpaque<UserId>;
+```
+
+## ✅ Correct
+
+```ts
+import type { UnwrapTagged } from "type-fest";
+
+type RawId = UnwrapTagged<UserId>;
+```
+
+## Behavior and migration notes
+
+- `UnwrapTagged<T>` is the supported replacement for deprecated `UnwrapOpaque<T>`.
+- Use it when branded/tagged identifiers need to be converted back to raw underlying types.
+- Keep unwrap operations localized near serialization and interop boundaries.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type { UnwrapOpaque } from "type-fest";
+
+type RawId = UnwrapOpaque<UserId>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import type { UnwrapTagged } from "type-fest";
+
+type RawId = UnwrapTagged<UserId>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type RawOrderId = UnwrapTagged<OrderId>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-unwrap-tagged": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if compatibility requirements force retention of deprecated alias names.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/tagged.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/tagged.d.ts)
+
+````ts
+/**
+Revert a tagged type back to its original type by removing all tags.
+
+Why is this necessary?
+
+1. Use a `Tagged` type as object keys
+2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
+
+@example
+```
+import type {Tagged, UnwrapTagged} from 'type-fest';
+
+type AccountType = Tagged<'SAVINGS' | 'CHECKING', 'AccountType'>;
+
+const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
+    SAVINGS: 99,
+    CHECKING: 0.1,
+};
+
+// Without UnwrapTagged, the following expression would throw a type error.
+const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
+
+// Attempting to pass an non-Tagged type to UnwrapTagged will raise a type error.
+// @ts-expect-error
+type WontWork = UnwrapTagged<string>;
+```
+
+@category Type
+*/
+````
+
+> **Rule catalog ID:** R073
+
+## 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-value-of.md

@@ -0,0 +1,121 @@
+# prefer-type-fest-value-of
+
+Require TypeFest [`ValueOf<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/value-of.d.ts) over direct `T[keyof T]` indexed-access unions when extracting object value unions.
+
+## Targeted pattern scope
+
+This rule narrows matching to indexed-access type shapes that are semantically equivalent to `ValueOf<T>`.
+
+- Type-level indexed access patterns shaped like `T[keyof T]`.
+
+Indexed accesses with additional constraints or non-equivalent key domains are intentionally excluded.
+
+## What this rule reports
+
+This rule reports `T[keyof T]`-style indexed-access aliases that should use `ValueOf<T>`.
+
+- Type-level indexed access patterns shaped like `T[keyof T]`.
+
+## Why this rule exists
+
+`ValueOf<T>` is clearer and more intent-revealing than repeating indexed-access unions. It also keeps value-union typing conventions consistent with other TypeFest-based utility types in the codebase.
+
+## ❌ Incorrect
+
+```ts
+type Values = User[keyof User];
+```
+
+## ✅ Correct
+
+```ts
+type Values = ValueOf<User>;
+```
+
+## Behavior and migration notes
+
+- `ValueOf<T>` replaces raw `T[keyof T]` value-union extraction patterns.
+- Use keyed form `ValueOf<T, K>` when you need a subset of value types.
+- Standardize on this alias in shared type utilities to avoid repeated indexed-access spelling.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type StatusValue = StatusMap[keyof StatusMap];
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type StatusValue = ValueOf<StatusMap>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type Selected = ValueOf<User, "id" | "email">;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-value-of": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if explicit indexed-access expressions are required in a published API.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/value-of.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/value-of.d.ts)
+
+````ts
+/**
+Create a union of the given object's values, and optionally specify which keys to get the values from.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31438) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {ValueOf} from 'type-fest';
+
+type A = ValueOf<{id: number; name: string; active: boolean}>;
+//=> string | number | boolean
+
+type B = ValueOf<{id: number; name: string; active: boolean}, 'name'>;
+//=> string
+
+type C = ValueOf<{id: number; name: string; active: boolean}, 'id' | 'name'>;
+//=> string | number
+```
+
+@category Object
+*/
+````
+
+> **Rule catalog ID:** R074
+
+## 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)