eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-assert-error.md

@@ -0,0 +1,147 @@
+# prefer-ts-extras-assert-error
+
+Require [`assertError`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-error.ts) from `ts-extras` over manual `instanceof Error` throw
+guards.
+
+## Targeted pattern scope
+
+This rule focuses on throw-only negative `instanceof Error` guards that map directly to `assertError(value)`.
+
+### Matched patterns
+
+- `if (!(value instanceof Error)) { throw ... }`
+
+Only `if` statements with no `else` branch and a throw-only consequent are
+reported.
+
+### Detection boundaries
+
+- ✅ Reports negative `instanceof Error` guards wrapped in `!()`.
+- ❌ Does not report positive-form patterns like `if (value instanceof Error) { ... } else { throw ... }`.
+- ❌ Does not report checks against custom error classes in this rule.
+- ❌ Does not auto-fix.
+
+These boundaries keep matching deterministic and avoid broad semantic overreach during migration.
+
+## What this rule reports
+
+Throw-only negative `instanceof Error` guards that can be replaced with `assertError(value)`.
+
+## Why this rule exists
+
+`assertError()` communicates intent directly: "this value must be an `Error`".
+That reduces repetitive custom guard code in `catch` pipelines.
+
+## ❌ Incorrect
+
+```ts
+if (!(error instanceof Error)) {
+    throw new TypeError("Expected Error");
+}
+```
+
+## ✅ Correct
+
+```ts
+assertError(error);
+```
+
+## Behavior and migration notes
+
+- `assertError(value)` narrows unknown caught values to `Error`.
+- This rule only targets throw-only negative guards with no `else` branch.
+- Positive-form or custom-error-class guards are intentionally out of scope.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (!(reason instanceof Error)) {
+    throw new TypeError("Expected Error instance");
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+assertError(reason);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+assertError(caughtValue);
+assertError(lastFailureReason);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-assert-error": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your project intentionally avoids runtime helper
+dependencies or enforces a different assertion utility layer.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/assert-error.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-error.ts)
+
+````ts
+/**
+Assert that the given value is an `Error`.
+
+If the value is not an `Error`, a helpful `TypeError` will be thrown.
+
+This can be useful as any value could potentially be thrown, but in practice, it's always an `Error`. However, because of this, TypeScript makes the caught error in a try/catch statement `unknown`, which is inconvenient to deal with.
+
+@example
+```
+import {assertError} from 'ts-extras';
+
+try {
+    fetchUnicorns();
+} catch (error: unknown) {
+    assertError(error);
+
+    // `error` is now of type `Error`
+
+    if (error.message === 'Failed to fetch') {
+        retry();
+        return;
+    }
+
+    throw error;
+}
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R012
+
+## 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-assert-present.md

@@ -0,0 +1,139 @@
+# prefer-ts-extras-assert-present
+
+Require [`assertPresent`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-present.ts) from `ts-extras` over manual `== null` throw guards.
+
+## Targeted pattern scope
+
+This rule focuses on throw-only nullish guards that map directly to `assertPresent(value)`.
+
+### Matched patterns
+
+- `if (value == null) { throw ... }`
+- `if (value === null || value === undefined) { throw ... }`
+- `if (value === undefined || value === null) { throw ... }`
+
+Only `if` statements that have no `else` branch and a throw-only consequent are
+reported.
+
+### Detection boundaries
+
+- ✅ Reports nullish guards written as `== null` or explicit `null/undefined` OR checks.
+- ❌ Does not report a `null`-only guard (`value === null`) or `undefined`-only guard.
+- ❌ Does not report branches that do more than throw.
+- ❌ Does not auto-fix.
+
+These boundaries keep matching deterministic and avoid broad semantic overreach during migration.
+
+## What this rule reports
+
+Throw-only nullish guard blocks that can be replaced with `assertPresent(value)`.
+
+## Why this rule exists
+
+`assertPresent()` communicates nullish-assertion intent and provides a reusable narrowing helper.
+
+This is a high-signal utility for request handlers and parsing layers where
+nullable inputs are common.
+
+## ❌ Incorrect
+
+```ts
+if (payload == null) {
+    throw new Error("Missing payload");
+}
+```
+
+## ✅ Correct
+
+```ts
+assertPresent(payload);
+```
+
+## Behavior and migration notes
+
+- `assertPresent(value)` narrows value to `NonNullable<T>`.
+- The rule covers nullish guards (`== null` or explicit `null || undefined`) with throw-only consequents.
+- Null-only or undefined-only assertions are intentionally left untouched.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (input === null || input === undefined) {
+    throw new TypeError("input is required");
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+assertPresent(input);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+assertPresent(currentUser);
+assertPresent(sessionId);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-assert-present": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your domain code requires custom error payloads inline at each nullish guard.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/assert-present.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-present.ts)
+
+````ts
+/**
+Assert that the given value is present (non-nullable), meaning it is neither `null` nor `undefined`.
+
+If the value is not present (`undefined` or `null`), a helpful `TypeError` will be thrown.
+
+@example
+```
+import {assertPresent} from 'ts-extras';
+
+const unicorn = 'unicorn';
+assertPresent(unicorn);
+
+const notUnicorn = null;
+assertPresent(notUnicorn);
+//=> TypeError: Expected a present value, got `null`
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R013
+
+## 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-defined-filter.md

@@ -0,0 +1,125 @@
+# prefer-ts-extras-is-defined-filter
+
+Require [`isDefined`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-defined.ts) from `ts-extras` in `Array.prototype.filter` callbacks instead of inline undefined checks.
+
+## Targeted pattern scope
+
+This rule only inspects inline `.filter(...)` predicates that perform explicit undefined checks.
+
+- Inline undefined predicates inside `.filter(...)`, including:
+- `filter((value) => value !== undefined)`
+- `filter((value) => typeof value !== "undefined")`
+- `filter((value): value is T => value !== undefined)`
+
+Named predicate references and broader callback logic are not matched unless they keep this exact inline-check structure.
+
+## What this rule reports
+
+This rule reports inline filter predicates that encode undefined checks and can be normalized with `isDefined`.
+
+- Inline undefined predicates inside `.filter(...)`, including:
+- `filter((value) => value !== undefined)`
+- `filter((value) => typeof value !== "undefined")`
+- `filter((value): value is T => value !== undefined)`
+
+## Why this rule exists
+
+`filter(isDefined)` is a canonical narrowing form that removes repeated callback boilerplate.
+
+- Filter chains are shorter and easier to scan.
+- Narrowing to defined values is consistent.
+- Inline predicate duplication is eliminated.
+
+## ❌ Incorrect
+
+```ts
+const values = inputs.filter((value) => value !== undefined);
+```
+
+## ✅ Correct
+
+```ts
+const values = inputs.filter(isDefined);
+```
+
+## Behavior and migration notes
+
+- `array.filter(isDefined)` keeps elements where value is not `undefined`.
+- Manual predicate bodies with additional side effects should not be auto-converted.
+- Non-filter undefined checks belong to `prefer-ts-extras-is-defined`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const ids = maybeIds.filter((id) => id !== undefined);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const ids = maybeIds.filter(isDefined);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const values = readings.filter(isDefined);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-defined-filter": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your filters intentionally use named local predicates for domain-specific semantics.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-defined.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-defined.ts)
+
+````ts
+/**
+Check whether a value is defined, meaning it is not `undefined`.
+
+This can be useful as a type guard, as for example, `[1, undefined].filter(Boolean)` does not always type-guard correctly.
+
+@example
+```
+import {isDefined} from 'ts-extras';
+
+[1, undefined, 2].filter(isDefined);
+//=> [1, 2]
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R015
+
+## 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-defined.md

@@ -0,0 +1,147 @@
+# prefer-ts-extras-is-defined
+
+Require [`isDefined`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-defined.ts) from `ts-extras` for direct undefined checks outside `Array.prototype.filter` callbacks.
+
+## Targeted pattern scope
+
+This rule scopes matching to direct undefined-check expressions outside `.filter(...)` callbacks.
+
+- Direct undefined checks outside `Array.prototype.filter` callbacks:
+- `value !== undefined`
+- `undefined !== value`
+- `typeof value !== "undefined"`
+- `value === undefined`
+
+Loose comparisons (`==` / `!=`) are intentionally ignored because they also match `null`, which is not equivalent to `isDefined(...)`.
+
+Filter callbacks are handled by the dedicated filter rule; broader boolean expressions are only matched when they keep these forms.
+
+## What this rule reports
+
+This rule reports direct undefined comparisons that should use `isDefined(...)` helpers.
+
+- Direct undefined checks outside `Array.prototype.filter` callbacks:
+- `value !== undefined`
+- `undefined !== value`
+- `typeof value !== "undefined"`
+- `value === undefined`
+
+## Why this rule exists
+
+`isDefined` turns repeated undefined comparisons into one canonical predicate.
+
+- Guard intent is explicit at call sites.
+- Narrowing style is consistent across modules.
+- Repeated inline comparison variants are removed.
+
+## ❌ Incorrect
+
+```ts
+if (value !== undefined) {
+    consume(value);
+}
+
+if (value === undefined) {
+    return;
+}
+```
+
+## ✅ Correct
+
+```ts
+if (isDefined(value)) {
+    consume(value);
+}
+
+if (!isDefined(value)) {
+    return;
+}
+```
+
+## Behavior and migration notes
+
+- `isDefined(value)` is equivalent to `value !== undefined`.
+- `!isDefined(value)` is equivalent to `value === undefined`.
+- Loose `value != undefined` and `value == undefined` checks are not auto-fixed by this rule because replacing them with `isDefined` would change runtime behavior for `null`.
+- Autofix is intentionally skipped for comparisons whose value resolves to `@typescript-eslint` AST node types (for example `TSESTree.Node | undefined`) to avoid pathological type-analysis performance cliffs in downstream lint passes.
+- Filter-specific patterns are intentionally covered by `prefer-ts-extras-is-defined-filter`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (sessionId !== undefined) {
+    connect(sessionId);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isDefined(sessionId)) {
+    connect(sessionId);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const hasValue = isDefined(input);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-defined": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team uses explicit `=== undefined` comparisons as a required style convention.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-defined.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-defined.ts)
+
+````ts
+/**
+Check whether a value is defined, meaning it is not `undefined`.
+
+This can be useful as a type guard, as for example, `[1, undefined].filter(Boolean)` does not always type-guard correctly.
+
+@example
+```
+import {isDefined} from 'ts-extras';
+
+[1, undefined, 2].filter(isDefined);
+//=> [1, 2]
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R014
+
+## 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-empty.md

@@ -0,0 +1,142 @@
+# prefer-ts-extras-is-empty
+
+Require [`isEmpty`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-empty.ts) from `ts-extras` over direct `array.length === 0` checks.
+
+## Targeted pattern scope
+
+This rule only matches strict zero-length comparisons against `.length` that can be rewritten as `isEmpty(array)`.
+
+- Direct empty-array checks using length equality:
+- `array.length === 0`
+- `0 === array.length`
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports strict empty-check comparisons that can be replaced with `isEmpty(array)`.
+
+- Direct empty-array checks using length equality:
+- `array.length === 0`
+- `0 === array.length`
+
+## Why this rule exists
+
+`isEmpty` gives one canonical emptiness predicate instead of repeated length comparisons.
+
+- Emptiness checks are easier to search and standardize.
+- Predicate style is consistent with other `ts-extras` guards.
+- Repeated comparison variants are removed from call sites.
+
+## ❌ Incorrect
+
+```ts
+if (items.length === 0) {
+    return;
+}
+```
+
+## ✅ Correct
+
+```ts
+if (isEmpty(items)) {
+    return;
+}
+```
+
+## Behavior and migration notes
+
+- `isEmpty(array)` is equivalent to `array.length === 0`.
+- Use `!isEmpty(array)` for non-empty checks.
+- This rule is about array emptiness checks, not object key-count checks.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (items.length === 0) {
+    return;
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isEmpty(items)) {
+    return;
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const hasRows = !isEmpty(rows);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-empty": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team requires direct `.length` comparisons for emptiness checks.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-empty.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-empty.ts)
+
+````ts
+/**
+Check whether an array is empty.
+
+This is useful because doing `array.length === 0` on its own won't work as a type-guard.
+
+@example
+```
+import {isEmpty} from 'ts-extras';
+
+isEmpty([1, 2, 3]);
+//=> false
+
+isEmpty([]);
+//=> true
+
+// Works with tuples
+const tuple: [string, number] | [] = Math.random() > 0.5 ? ['hello', 42] : [];
+if (isEmpty(tuple)) {
+    // tuple is now typed as []
+} else {
+    // tuple is now typed as [string, number]
+}
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R016
+
+## 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)