eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-safe-cast-to.md

@@ -0,0 +1,130 @@
+# prefer-ts-extras-safe-cast-to
+
+Prefer [`safeCastTo`](https://github.com/sindresorhus/ts-extras/blob/main/source/safe-cast-to.ts) from `ts-extras` over direct `as` assertions when the cast is already assignable.
+
+## Targeted pattern scope
+
+This rule focuses on direct `as T` and `<T>value` assertions that can be migrated to `safeCastTo<T>(value)` when the cast is assignable.
+
+- Type assertions (`as T` and `<T>value`) that are already assignable and can use `safeCastTo<T>(value)`.
+- `as` and angle-bracket (`<T>value`) assertions in runtime source files.
+- Only assertions where the source expression type is assignable to the asserted target type.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `safeCastTo<T>(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports assignable `as T` and `<T>value` assertion sites when `safeCastTo<T>(value)` is the intended replacement.
+
+- Type assertions (`as T` and `<T>value`) that are already assignable and can use `safeCastTo<T>(value)`.
+- `as` and angle-bracket (`<T>value`) assertions in runtime source files.
+- Only assertions where the source expression type is assignable to the asserted target type.
+
+## Why this rule exists
+
+`safeCastTo<T>(value)` keeps casts type-checked and prevents silently widening unsafe assertion patterns.
+
+## ❌ Incorrect
+
+```ts
+const nameValue = "Alice" as string;
+```
+
+## ✅ Correct
+
+```ts
+const nameValue = safeCastTo<string>("Alice");
+```
+
+## Behavior and migration notes
+
+- This rule only reports assertions where source type is assignable to target type.
+- Unsafe/non-assignable assertion patterns are intentionally not rewritten by this rule.
+- `safeCastTo` keeps the cast explicit while preserving assignability checks.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const resourceId = rawId as string;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const resourceId = safeCastTo<string>(rawId);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const port = safeCastTo<number>(env.PORT);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-safe-cast-to": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team forbids runtime casting helpers in favor of direct assertions.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/safe-cast-to.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/safe-cast-to.ts)
+
+````ts
+/**
+Constrain a value to the given type safely.
+
+Unlike `as`, this refuses incompatible casts at compile time. Use it to _narrow_ or _shape_ values while preserving type safety.
+
+@example
+```
+type Foo = {
+    a: string;
+    b?: number;
+};
+
+declare const possibleUndefined: Foo | undefined;
+
+const foo = possibleUndefined ?? safeCastTo<Partial<Foo>>({});
+console.log(foo.a ?? '', foo.b ?? 0);
+
+const bar = possibleUndefined ?? {};
+// @ts-expect-error
+console.log(bar.a ?? '', bar.b ?? 0);
+//             ^^^ Property 'a' does not exist on type '{}'.(2339)
+//                          ^^^ Property 'b' does not exist on type '{}'.(2339)
+```
+
+@category General
+*/
+````
+
+> **Rule catalog ID:** R032
+
+## Further reading
+
+- [`ts-extras` README](https://github.com/sindresorhus/ts-extras)
+- [`ts-extras` package reference](https://www.npmjs.com/package/ts-extras)
+- [TypeScript Handbook: Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)

package/docs/rules/prefer-ts-extras-set-has.md

@@ -0,0 +1,203 @@
+# prefer-ts-extras-set-has
+
+Prefer [`setHas`](https://github.com/sindresorhus/ts-extras/blob/main/source/set-has.ts) from `ts-extras` over `set.has(...)`.
+
+`setHas(...)` improves narrowing when checking membership in typed sets.
+
+## Targeted pattern scope
+
+This rule focuses on direct `set.has(value)` calls that can be migrated to `setHas(set, value)` with deterministic fixes.
+
+- `set.has(value)` call sites whose receiver resolves exclusively to `Set`/`ReadonlySet` branches and can use `setHas(set, value)`.
+
+Alias indirection, mixed unions with non-Set `has` methods (for example `Set | Map`), wrapper helpers, and non-canonical call shapes are excluded to keep `setHas(set, value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `set.has(value)` call sites when `setHas(set, value)` is the intended replacement.
+
+- `set.has(value)` call sites that can safely use `setHas(set, value)` without changing union-branch semantics.
+
+## Why this rule exists
+
+`setHas` provides a canonical membership-check helper with strong narrowing behavior for typed sets.
+
+- Set membership guards have one helper style.
+- Candidate values can narrow after guard checks.
+- Native/helper mixing is removed from set-heavy code.
+
+## ❌ Incorrect
+
+```ts
+const hasMonitor = monitorIds.has(candidateId);
+```
+
+## ✅ Correct
+
+```ts
+const hasMonitor = setHas(monitorIds, candidateId);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics match native `Set.prototype.has`.
+- Equality semantics still follow SameValueZero.
+- Narrowing benefits are strongest when checking unknown values against literal/unioned set members.
+- If your codebase intentionally needs plain-boolean membership checks (without exposing type-guard narrowing at every call site), wrap `setHas` once in a local helper and call the helper consistently.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (allowed.has(input)) {
+    use(input);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (setHas(allowed, input)) {
+    use(input);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const known = setHas(codes, candidate);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-set-has": "error",
+        },
+    },
+];
+```
+
+### Options
+
+This rule accepts a single options object:
+
+```ts
+type PreferTsExtrasSetHasOptions = {
+    /**
+     * Controls how union receivers are matched.
+     *
+     * - "allBranches": report only when every union branch is Set-like.
+     * - "anyBranch": report when at least one union branch is Set-like.
+     *
+     * @default "allBranches"
+     */
+    unionBranchMatchingMode?: "allBranches" | "anyBranch";
+};
+```
+
+Default configuration:
+
+```ts
+{
+    unionBranchMatchingMode: "allBranches",
+}
+```
+
+#### `unionBranchMatchingMode: "allBranches"` (default)
+
+Mixed unions are ignored to prevent noisy reports and unsafe replacements:
+
+```ts
+declare const values: Set<number> | Map<number, number>;
+const hasValue = values.has(2); // ✅ Not reported by default
+```
+
+#### `unionBranchMatchingMode: "anyBranch"`
+
+Mixed unions with Set-like branches are reported:
+
+```ts
+declare const values: Set<number> | Map<number, number>;
+const hasValue = values.has(2); // ❌ Reported
+```
+
+When this option is enabled, mixed-union reports are intentionally suggestion-free (no autofix and no suggested replacement), because `setHas(values, value)` may not type-check until you narrow to a Set-like branch first.
+
+Flat config example:
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-set-has": [
+                "error",
+                { unionBranchMatchingMode: "anyBranch" },
+            ],
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if native `.has()` calls are required by local conventions.
+
+You may also disable this rule in implementation-only layers that intentionally centralize `setHas` behind a boolean helper wrapper for stability and readability.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/set-has.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/set-has.ts)
+
+````ts
+/**
+A strongly-typed version of `Set#has()` that properly acts as a type guard.
+
+When `setHas` returns `true`, the type is narrowed to the set's element type.
+When it returns `false`, the type remains unchanged (i.e., `unknown` stays `unknown`).
+
+It was [rejected](https://github.com/microsoft/TypeScript/issues/42641#issuecomment-774168319) from being done in TypeScript itself.
+
+@example
+```
+import {setHas} from 'ts-extras';
+
+const values = ['a', 'b', 'c'] as const;
+const valueSet = new Set(values);
+const valueToCheck: unknown = 'a';
+
+if (setHas(valueSet, valueToCheck)) {
+    // We now know that the value is of type `typeof values[number]`.
+} else {
+    // The value remains `unknown`.
+}
+```
+
+@category Improved builtin
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R033
+
+## Further reading
+
+- [`ts-extras` README](https://github.com/sindresorhus/ts-extras)
+- [`ts-extras` package reference](https://www.npmjs.com/package/ts-extras)
+- [TypeScript Handbook: Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+
+## Adoption resources
+
+- [Rule adoption checklist](./guides/adoption-checklist.md)
+- [Rollout and fix safety](./guides/rollout-and-fix-safety.md)

package/docs/rules/prefer-ts-extras-string-split.md

@@ -0,0 +1,133 @@
+# prefer-ts-extras-string-split
+
+Prefer [`stringSplit`](https://github.com/sindresorhus/ts-extras/blob/main/source/string-split.ts) from `ts-extras` over `string.split(...)`.
+
+`stringSplit(...)` can preserve stronger tuple-like inference for literal separators.
+
+## Targeted pattern scope
+
+This rule focuses on direct `string.split(separator)` calls that can be migrated to `stringSplit(string, separator)` with deterministic fixes.
+
+- `string.split(separator)` call sites that can use `stringSplit(string, separator)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `stringSplit(string, separator)` migrations safe.
+
+## What this rule reports
+
+This rule reports `string.split(separator)` call sites when `stringSplit(string, separator)` is the intended replacement.
+
+- `string.split(separator)` call sites that can use `stringSplit(string, separator)`.
+
+## Why this rule exists
+
+`stringSplit` standardizes string tokenization and can preserve stronger typing for literal separators and known string shapes.
+
+- Split usage follows one helper style across modules.
+- Destructuring from split results is easier to type in strict code.
+- Native/helper split styles are not mixed.
+
+## ❌ Incorrect
+
+```ts
+const parts = monitorKey.split(":");
+```
+
+## ✅ Correct
+
+```ts
+const parts = stringSplit(monitorKey, ":");
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `String.prototype.split`.
+- Separator semantics (string/regex, limits) are preserved.
+- Literal-based tuple inference depends on the source string and separator types.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const [major, minor] = version.split(".");
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const [major, minor] = stringSplit(version, ".");
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const pathParts = stringSplit(route, "/");
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-string-split": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your code style standardizes on direct `.split()` usage.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/string-split.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/string-split.ts)
+
+````ts
+/**
+A strongly-typed version of `String#split()` that returns a tuple for literal strings.
+
+@example
+```
+import {stringSplit} from 'ts-extras';
+
+const parts = stringSplit('foo-bar-baz', '-');
+//=> ['foo', 'bar', 'baz']
+//   ^? ['foo', 'bar', 'baz']
+
+const [first, second] = stringSplit('top-left', '-');
+//=> first: 'top', second: 'left'
+
+const placement = 'top-start' as const;
+const side = stringSplit(placement, '-')[0];
+//=> 'top'
+//   ^? 'top'
+
+// Dynamic strings return string[]
+const dynamic: string = 'a-b-c';
+const dynamicParts = stringSplit(dynamic, '-');
+//=> string[]
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R034
+
+## Further reading
+
+- [`ts-extras` README](https://github.com/sindresorhus/ts-extras)
+- [`ts-extras` package reference](https://www.npmjs.com/package/ts-extras)
+- [TypeScript Handbook: Narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.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-abstract-constructor.md

@@ -0,0 +1,87 @@
+# prefer-type-fest-abstract-constructor
+
+Require TypeFest [`AbstractConstructor`](https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts) over explicit abstract constructor signatures.
+
+## Targeted pattern scope
+
+This rule reports explicit `abstract new (...args) => T` signatures and prefers `AbstractConstructor<T>` for abstract class constructor contracts.
+
+## What this rule reports
+
+- `abstract new (...args) => T` constructor type signatures.
+
+### Detection boundaries
+
+- ✅ Reports explicit abstract constructor signatures used directly in type positions.
+- ❌ Does not auto-fix when generic parameter mapping is ambiguous.
+
+## Why this rule exists
+
+`AbstractConstructor<T>` gives one canonical representation for abstract constructable class contracts.
+
+When teams mix explicit constructor signatures and helper aliases, higher-order APIs that accept class references become harder to standardize.
+
+## ❌ Incorrect
+
+```ts
+type ExplicitAbstractCtor = abstract new (host: string, port: number) => Service;
+```
+
+## ✅ Correct
+
+```ts
+import type { AbstractConstructor } from "type-fest";
+
+type ServiceAbstractCtor = AbstractConstructor<Service>;
+```
+
+## Behavior and migration notes
+
+- `AbstractConstructor<T>` models class values that cannot be instantiated directly but can be subclassed.
+- If your explicit signature encoded argument constraints, preserve them by adding a dedicated wrapper type.
+- Prefer canonical alias usage in plugin/public APIs that accept abstract class constructors.
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-abstract-constructor": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally prefers explicit abstract constructor signatures over TypeFest aliases.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/basic.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/basic.d.ts)
+
+```ts
+/**
+Matches an [`abstract class`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-2.html#abstract-construct-signatures) constructor.
+
+@category Class
+*/
+```
+
+> **Rule catalog ID:** R035
+
+## Further reading
+
+- [TypeFest README](https://github.com/sindresorhus/type-fest)
+- [TypeScript Handbook: Classes](https://www.typescriptlang.org/docs/handbook/2/classes.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-arrayable.md

@@ -0,0 +1,127 @@
+# prefer-type-fest-arrayable
+
+Require TypeFest [`Arrayable<T>`](https://github.com/sindresorhus/type-fest/blob/main/source/arrayable.d.ts) over `T | T[]` and `T | Array<T>` unions.
+
+## Targeted pattern scope
+
+This rule only matches the canonical value-or-array union spellings that TypeFest replaces with `Arrayable<T>`.
+
+- `T | T[]`
+- `T | Array<T>`
+
+Near-miss unions (extra members or mismatched element types) are excluded unless they are exact canonical forms.
+
+## What this rule reports
+
+This rule reports canonical value-or-array unions that should be rewritten as `Arrayable<T>`.
+
+- `T | T[]`
+- `T | Array<T>`
+
+## Why this rule exists
+
+`Arrayable<T>` is clearer and more consistent than repeating union patterns. It also aligns code with TypeFest utility conventions used by other rules in this plugin.
+
+## ❌ Incorrect
+
+```ts
+type Input = string | string[];
+```
+
+## ✅ Correct
+
+```ts
+type Input = Arrayable<string>;
+```
+
+## Behavior and migration notes
+
+- `Arrayable<T>` is the canonical form for value-or-array contracts.
+- It replaces both `T | T[]` and `T | Array<T>` spelling variants.
+- Keep this alias in public callback and option signatures to reduce repeated union boilerplate.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+type Input = number | Array<number>; // Union repeated inline across modules
+```
+
+### ✅ Correct — Additional example
+
+```ts
+type Input = Arrayable<number>;
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+type QueryParam = Arrayable<string>;
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-type-fest-arrayable": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if existing public type names must remain unchanged for compatibility.
+
+## Package documentation
+
+TypeFest package documentation:
+
+Source file: [`source/arrayable.d.ts`](https://github.com/sindresorhus/type-fest/blob/main/source/arrayable.d.ts)
+
+````ts
+/**
+Create a type that represents either the value or an array of the value.
+
+@see {@link Promisable}
+
+@example
+```
+import type {Arrayable} from 'type-fest';
+
+function bundle(input: string, output: Arrayable<string>) {
+    const outputList = Array.isArray(output) ? output : [output];
+
+    // …
+
+    for (const output of outputList) {
+        console.log(`write ${input} to: ${output}`);
+    }
+}
+
+bundle('src/index.js', 'dist/index.js');
+bundle('src/index.js', ['dist/index.cjs', 'dist/index.mjs']);
+```
+
+@category Array
+*/
+````
+
+> **Rule catalog ID:** R036
+
+## 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)