eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-is-equal-type.md

@@ -0,0 +1,144 @@
+# prefer-ts-extras-is-equal-type
+
+Prefer [`isEqualType`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-equal-type.ts) from `ts-extras` over `IsEqual<T, U>` boolean assertion variables.
+
+## Targeted pattern scope
+
+This rule targets one assertion pattern: `IsEqual<T, U>` variables initialized with literal `true`/`false`, and rewrites them to `isEqualType<T, U>()`.
+
+The focus is narrow on assertion-style declarations so migration stays deterministic and avoids changing unrelated type aliases.
+
+## What this rule reports
+
+This rule intentionally targets a narrow assertion pattern:
+
+- Variables typed as `IsEqual<T, U>` and initialized with boolean literals (`true`/`false`).
+- Namespace-qualified `type-fest` forms such as `TypeFest.IsEqual<T, U>`.
+
+### Detection boundaries
+
+- ✅ Reports `const x: IsEqual<A, B> = true`.
+- ✅ Reports namespace imports (`TypeFest.IsEqual<A, B>`).
+- ❌ Does not report type aliases (`type X = IsEqual<A, B>`).
+- ❌ Does not report variables initialized from expressions (`someCondition`) instead of boolean literals.
+
+## Why this rule exists
+
+`isEqualType<T, U>()` expresses compile-time type equality checks for assertion-style code and avoids manual boolean literal scaffolding.
+
+This makes test/fixture code easier to scan because type assertions look like
+explicit calls instead of pseudo-runtime constants.
+
+## ❌ Incorrect
+
+```ts
+import type { IsEqual } from "type-fest";
+
+const typeCheck: IsEqual<Foo, Bar> = true;
+```
+
+## ✅ Correct
+
+```ts
+import { isEqualType } from "ts-extras";
+
+const typeCheck = isEqualType<Foo, Bar>();
+```
+
+## Behavior and migration notes
+
+- Reported declarations are compile-time assertions; they are not runtime equality checks.
+- `isEqualType<T, U>()` keeps assertion intent while removing manual boolean literal scaffolding.
+- Expression-initialized `IsEqual<T, U>` variables are intentionally out of scope for this rule.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+import type * as TypeFest from "type-fest";
+
+const dtoMatchesModel: TypeFest.IsEqual<UserDto, UserModel> = true;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+import { isEqualType } from "ts-extras";
+
+const dtoMatchesModel = isEqualType<UserDto, UserModel>();
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const idsAreEqual = isEqualType<Id, string>();
+const payloadsAreEqual = isEqualType<ApiPayload, InternalPayload>();
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-equal-type": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project prefers `type-fest` assertion types directly in declarations and does not want function-form assertion helpers.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-equal-type.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-equal-type.ts)
+
+````ts
+/**
+Check if two types are equal at compile time.
+
+Returns a boolean type (`true` or `false`) at compile time based on whether the types are equal.
+At runtime, this returns nothing (`void`) since it's purely a compile-time utility.
+
+@example
+```
+import {isEqualType} from 'ts-extras';
+
+// Type-level comparison
+const result1 = isEqualType<string, string>(); // Type: true
+const result2 = isEqualType<string, number>(); // Type: false
+
+// Value-level comparison
+const string1 = 'hello';
+const string2 = 'world';
+const number = 42;
+const result3 = isEqualType(string1, string2); // Type: true (both strings)
+const result4 = isEqualType(string1, number);  // Type: false (different types)
+```
+
+@note The runtime value is `void`. This function is designed for compile-time type checking only, not runtime behavior.
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R017
+
+## 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-is-finite.md

@@ -0,0 +1,116 @@
+# prefer-ts-extras-is-finite
+
+Prefer [`isFinite`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-finite.ts) from `ts-extras` over `Number.isFinite(...)`.
+
+This keeps predicate usage consistent with other `ts-extras` narrowing helpers.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Number.isFinite(value)` calls that can be migrated to `isFinite(value)` with deterministic fixes.
+
+- `Number.isFinite(value)` call sites that can use `isFinite(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `isFinite(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Number.isFinite(value)` call sites when `isFinite(value)` is the intended replacement.
+
+- `Number.isFinite(value)` call sites that can use `isFinite(value)`.
+
+## Why this rule exists
+
+`isFinite` keeps numeric predicate usage aligned with the rest of the `ts-extras` guard set.
+
+- Numeric validation helpers use one naming/style convention.
+- Native/helper mixing in guard-heavy code is reduced.
+- Number guard logic stays consistent across modules.
+
+## ❌ Incorrect
+
+```ts
+const isValid = Number.isFinite(value);
+```
+
+## ✅ Correct
+
+```ts
+const isValid = isFinite(value);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Number.isFinite`.
+- Only numbers are considered; numeric strings are not coerced.
+- `NaN`, `Infinity`, and `-Infinity` still return `false`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (Number.isFinite(metric)) {
+    consume(metric);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isFinite(metric)) {
+    consume(metric);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const valid = isFinite(durationMs);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-finite": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team explicitly standardizes on native `Number.isFinite` calls.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-finite.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-finite.ts)
+
+```ts
+/**
+A strongly-typed version of `Number.isFinite()`.
+
+@category Improved builtin
+@category Type guard
+*/
+```
+
+> **Rule catalog ID:** R018
+
+## 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-is-infinite.md

@@ -0,0 +1,134 @@
+# prefer-ts-extras-is-infinite
+
+Require [`isInfinite`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-infinite.ts) from `ts-extras` over direct Infinity equality checks.
+
+## Targeted pattern scope
+
+This rule only matches direct equality checks against infinity constants that can be collapsed into `isInfinite(value)`.
+
+- Direct infinity equality checks:
+- `value === Infinity`
+- `value === Number.POSITIVE_INFINITY`
+- `value === Number.NEGATIVE_INFINITY`
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports direct infinity equality checks that can be replaced with `isInfinite(value)`.
+
+- Direct infinity equality checks:
+- `value === Infinity`
+- `value === Number.POSITIVE_INFINITY`
+- `value === Number.NEGATIVE_INFINITY`
+
+## Why this rule exists
+
+`isInfinite` replaces constant-based comparisons with one explicit predicate.
+
+- Infinity checks follow one helper pattern.
+- Mixed positive/negative infinity comparisons are normalized.
+- Numeric guard code is easier to audit.
+
+## ❌ Incorrect
+
+```ts
+const infinite = value === Infinity || value === Number.NEGATIVE_INFINITY;
+```
+
+## ✅ Correct
+
+```ts
+const infinite = isInfinite(value);
+```
+
+## Behavior and migration notes
+
+- `isInfinite(value)` covers both `Infinity` and `-Infinity`.
+- Finite numbers and `NaN` return `false`.
+- This rule targets direct equality checks, not broader numeric validation chains.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const bad = value === Infinity || value === Number.NEGATIVE_INFINITY;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const bad = isInfinite(value);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+if (isInfinite(rate)) {
+    throw new Error("invalid rate");
+}
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-infinite": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if direct infinity constant comparisons are required in generated code.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-infinite.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-infinite.ts)
+
+````ts
+/**
+Check whether a value is infinite.
+
+@example
+```
+import {isInfinite} from 'ts-extras';
+
+isInfinite(Number.POSITIVE_INFINITY);
+//=> true
+
+isInfinite(Number.NEGATIVE_INFINITY);
+//=> true
+
+isInfinite(42);
+//=> false
+
+isInfinite(Number.NaN);
+//=> false
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R019
+
+## 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-is-integer.md

@@ -0,0 +1,116 @@
+# prefer-ts-extras-is-integer
+
+Prefer [`isInteger`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-integer.ts) from `ts-extras` over `Number.isInteger(...)`.
+
+This keeps predicate usage consistent with other `ts-extras` narrowing helpers.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Number.isInteger(value)` calls that can be migrated to `isInteger(value)` with deterministic fixes.
+
+- `Number.isInteger(value)` call sites that can use `isInteger(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `isInteger(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Number.isInteger(value)` call sites when `isInteger(value)` is the intended replacement.
+
+- `Number.isInteger(value)` call sites that can use `isInteger(value)`.
+
+## Why this rule exists
+
+`isInteger` standardizes whole-number validation with the rest of the `ts-extras` numeric predicate family.
+
+- Numeric guard naming is consistent.
+- Native/helper predicate mixing is reduced.
+- Integer validation reads the same across services and packages.
+
+## ❌ Incorrect
+
+```ts
+const isWhole = Number.isInteger(value);
+```
+
+## ✅ Correct
+
+```ts
+const isWhole = isInteger(value);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Number.isInteger`.
+- Decimal numbers still return `false`.
+- Numeric strings are not coerced to numbers.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (Number.isInteger(retryCount)) {
+    useRetries(retryCount);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isInteger(retryCount)) {
+    useRetries(retryCount);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const whole = isInteger(userInput);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-integer": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase requires direct `Number.isInteger` usage.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-integer.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-integer.ts)
+
+```ts
+/**
+A strongly-typed version of `Number.isInteger()`.
+
+@category Improved builtin
+@category Type guard
+*/
+```
+
+> **Rule catalog ID:** R020
+
+## 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-is-present-filter.md

@@ -0,0 +1,125 @@
+# prefer-ts-extras-is-present-filter
+
+Require [`isPresent`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-present.ts) from `ts-extras` in `Array.prototype.filter` callbacks instead of inline nullish checks.
+
+## Targeted pattern scope
+
+This rule only inspects inline `.filter(...)` predicates that perform explicit nullish checks.
+
+- Inline nullish predicates inside `.filter(...)`, including:
+- `filter((value) => value != null)`
+- `filter((value): value is T => value !== null)`
+- `filter((value): value is T => value !== null && value !== undefined)`
+
+Named predicate references and broader callback logic are not matched unless they preserve this nullish-check shape.
+
+## What this rule reports
+
+This rule reports inline filter predicates that encode nullish checks and can be normalized with `isPresent`.
+
+- Inline nullish predicates inside `.filter(...)`, including:
+- `filter((value) => value != null)`
+- `filter((value): value is T => value !== null)`
+- `filter((value): value is T => value !== null && value !== undefined)`
+
+## Why this rule exists
+
+`filter(isPresent)` is the canonical pattern for removing nullish values in pipelines.
+
+- Filtering logic is consistent across collections.
+- Non-nullish narrowing is explicit in one helper name.
+- Repeated null/undefined callback expressions are removed.
+
+## ❌ Incorrect
+
+```ts
+const values = inputs.filter((value) => value != null);
+```
+
+## ✅ Correct
+
+```ts
+const values = inputs.filter(isPresent);
+```
+
+## Behavior and migration notes
+
+- `array.filter(isPresent)` removes `null` and `undefined` entries.
+- Callbacks with extra side effects should be reviewed before replacement.
+- Non-filter nullish checks belong to `prefer-ts-extras-is-present`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const rows = maybeRows.filter((row) => row != null);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const rows = maybeRows.filter(isPresent);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const values = list.filter(isPresent);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-present-filter": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your filters intentionally use domain-specific predicate wrappers.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-present.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-present.ts)
+
+````ts
+/**
+Check whether a value is present (non-nullable), meaning it is neither `null` nor `undefined`.
+
+This can be useful as a type guard, as for example, `[1, null].filter(Boolean)` does not always type-guard correctly.
+
+@example
+```
+import {isPresent} from 'ts-extras';
+
+[1, null, 2, undefined].filter(isPresent);
+//=> [1, 2]
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R022
+
+## 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)