eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-array-includes.md

@@ -0,0 +1,135 @@
+# prefer-ts-extras-array-includes
+
+Prefer [`arrayIncludes`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-includes.ts) from `ts-extras` over `array.includes(...)`.
+
+`arrayIncludes(...)` improves inference and narrowing when checking whether unknown values belong to a known tuple/array.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.includes(value)` calls that can be migrated to `arrayIncludes(array, value)` with deterministic fixes.
+
+- `array.includes(value)` call sites that can use `arrayIncludes(array, value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayIncludes(array, value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.includes(value)` call sites when `arrayIncludes(array, value)` is the intended replacement.
+
+- `array.includes(value)` call sites that can use `arrayIncludes(array, value)`.
+
+## Why this rule exists
+
+`arrayIncludes` is especially useful when checking if an unknown value belongs to a known literal tuple.
+
+- Membership checks can narrow candidate values in control flow.
+- Guard logic is consistent with other `ts-extras` predicates.
+- Native `.includes` call sites that need manual casts are reduced.
+
+## ❌ Incorrect
+
+```ts
+const hasStatus = statuses.includes(inputStatus);
+```
+
+## ✅ Correct
+
+```ts
+const hasStatus = arrayIncludes(statuses, inputStatus);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics follow native `Array.prototype.includes`.
+- Comparison uses SameValueZero (`NaN` matches `NaN`, `+0` equals `-0`).
+- Return type remains boolean, with improved narrowing behavior when array values are literal unions.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (roles.includes(candidate)) {
+    grantAccess(candidate);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (arrayIncludes(roles, candidate)) {
+    grantAccess(candidate);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const isKnownStatus = arrayIncludes(statuses, value);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-includes": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase intentionally standardizes on native `.includes()`.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-includes.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-includes.ts)
+
+````ts
+/**
+A strongly-typed version of `Array#includes()` that properly acts as a type guard.
+
+When `arrayIncludes` returns `true`, the type is narrowed to the array'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/26255#issuecomment-748211891) from being done in TypeScript itself.
+
+@example
+```
+import {arrayIncludes} from 'ts-extras';
+
+const values = ['a', 'b', 'c'] as const;
+const valueToCheck: unknown = 'a';
+
+if (arrayIncludes(values, 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:** R007
+
+## 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-array-join.md

@@ -0,0 +1,132 @@
+# prefer-ts-extras-array-join
+
+Prefer [`arrayJoin`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-join.ts) from `ts-extras` over `array.join(...)`.
+
+`arrayJoin(...)` can preserve stronger tuple-aware typing when joining array values.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.join(separator)` calls that can be migrated to `arrayJoin(array, separator)` with deterministic fixes.
+
+- `array.join(separator)` call sites that can use `arrayJoin(array, separator)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayJoin(array, separator)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.join(separator)` call sites when `arrayJoin(array, separator)` is the intended replacement.
+
+- `array.join(separator)` call sites that can use `arrayJoin(array, separator)`.
+
+## Why this rule exists
+
+`arrayJoin` keeps string assembly consistent and can preserve stronger string typing when arrays and separators are literals.
+
+- Join operations use one helper style across modules.
+- Literal-based join results are inferred more precisely in typed utilities.
+- Join-heavy code paths avoid mixed native/helper patterns.
+
+## ❌ Incorrect
+
+```ts
+const key = segments.join(":");
+```
+
+## ✅ Correct
+
+```ts
+const key = arrayJoin(segments, ":");
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Array.prototype.join`.
+- Missing separator still defaults to `","`.
+- `null` and `undefined` entries are converted to empty strings, matching native behavior.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const route = segments.join("/");
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const route = arrayJoin(segments, "/");
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const csv = arrayJoin(columns, ",");
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-join": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase requires native `.join()` for API consistency.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-join.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-join.ts)
+
+````ts
+/**
+A strongly-typed version of `Array#join()` that preserves literal string types.
+
+The built-in `Array#join()` always returns `string`, losing type information. This function returns a properly-typed template literal when given a tuple of literals.
+
+@example
+```
+import {arrayJoin} from 'ts-extras';
+
+// Literal types are preserved automatically
+const joined = arrayJoin(['foo', 'bar', 'baz'], '-');
+//=> 'foo-bar-baz'
+//   ^? 'foo-bar-baz'
+
+const dotPath = arrayJoin(['a', 'b', 'c'], '.');
+//=> 'a.b.c'
+//   ^? 'a.b.c'
+
+// Dynamic arrays return string
+const dynamic: string[] = ['a', 'b'];
+const dynamicJoined = arrayJoin(dynamic, '-');
+//=> string
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R008
+
+## 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-array-last.md

@@ -0,0 +1,132 @@
+# prefer-ts-extras-array-last
+
+Require [`arrayLast`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-last.ts) from `ts-extras` over direct `array[array.length - 1]` access.
+
+## Targeted pattern scope
+
+This rule only matches direct last-element index access (`receiver[receiver.length - 1]`) where the receiver expression can be reused unchanged in `arrayLast(receiver)`.
+
+- Direct last-element index patterns (`array[array.length - 1]`).
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports direct `receiver[receiver.length - 1]` access sites that can be safely replaced with `arrayLast(receiver)`.
+
+- Direct last-element index patterns (`array[array.length - 1]`).
+
+## Why this rule exists
+
+`arrayLast` makes last-element access explicit and keeps type inference behavior consistent with other `ts-extras` array helpers.
+
+- Last-element access is easier to audit in large codebases.
+- Tuple/readonly array access patterns are standardized.
+- Helper-driven access reduces repeated inline index arithmetic.
+
+## ❌ Incorrect
+
+```ts
+const last = values[values.length - 1];
+```
+
+## ✅ Correct
+
+```ts
+const last = arrayLast(values);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches `array[array.length - 1]`.
+- Empty arrays still produce `undefined`.
+- Equivalent index expressions with extra wrappers should be reviewed manually during migration.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const last = rows[rows.length - 1];
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const last = arrayLast(rows);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const lastStep = arrayLast(steps);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-last": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if direct index expressions are mandated by local style rules.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-last.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-last.ts)
+
+````ts
+/**
+Return the last item of an array with stronger typing for tuples.
+
+This provides better type safety than `array[array.length - 1]` or `array.at(-1)`.
+
+@example
+```
+import {arrayLast} from 'ts-extras';
+
+const tuple = ['abc', 123, true] as const;
+const last = arrayLast(tuple);
+//=> true
+//   ^? true
+
+const array = ['a', 'b', 'c'];
+const maybeLast = arrayLast(array);
+//=> 'c'
+//   ^? string | undefined
+
+// Empty arrays
+const empty: string[] = [];
+const noLast = arrayLast(empty);
+//=> undefined
+//   ^? string | undefined
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R009
+
+## 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-as-writable.md

@@ -0,0 +1,124 @@
+# prefer-ts-extras-as-writable
+
+Prefer [`asWritable`](https://github.com/sindresorhus/ts-extras/blob/main/source/as-writable.ts) from `ts-extras` over `Writable<...>` type assertions.
+
+## Targeted pattern scope
+
+This rule focuses on mutation-intent type assertions that map directly to `asWritable(value)`.
+
+### Matched patterns
+
+- `as` assertions where the asserted type is `Writable<...>` imported from `type-fest`.
+- Namespace-qualified assertions such as `TypeFest.Writable<...>` when `TypeFest` comes from `type-fest`.
+
+### Detection boundaries
+
+- ✅ Reports `Writable`-based type assertions that are direct helper replacements.
+- ❌ Does not report unrelated `as` assertions with non-`Writable` target types.
+
+These boundaries keep matching deterministic and avoid broad semantic overreach during migration.
+
+## What this rule reports
+
+`Writable<...>`-based type assertions that can be replaced with `asWritable(value)`.
+
+## Why this rule exists
+
+`asWritable(value)` communicates intent directly and keeps mutation-intent casts aligned with the `ts-extras` helper API.
+
+## ❌ Incorrect
+
+```ts
+import type { Writable } from "type-fest";
+
+const writableUser = readonlyUser as Writable<User>;
+```
+
+## ✅ Correct
+
+```ts
+import { asWritable } from "ts-extras";
+
+const writableUser = asWritable(readonlyUser);
+```
+
+## Behavior and migration notes
+
+- `asWritable(value)` preserves runtime behavior while expressing mutability intent through one helper.
+- Direct `as Writable<T>` / `as TypeFest.Writable<T>` assertions are reported.
+- This rule does not rewrite unrelated type assertions.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const mutable = config as Writable<typeof config>;
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const mutable = asWritable(config);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const draft = asWritable(readonlyDraft);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-as-writable": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if mutation boundaries are enforced through explicit type assertions by policy.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/as-writable.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/as-writable.ts)
+
+````ts
+/**
+Cast the given value to be [`Writable`](https://github.com/sindresorhus/type-fest/blob/main/source/writable.d.ts).
+
+This is useful because of a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/45618#issuecomment-908072756).
+
+@example
+```
+import {asWritable} from 'ts-extras';
+
+const writableContext = asWritable((await import('x')).context);
+```
+
+@category General
+*/
+````
+
+> **Rule catalog ID:** R010
+
+## 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-defined.md

@@ -0,0 +1,140 @@
+# prefer-ts-extras-assert-defined
+
+Require [`assertDefined`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-defined.ts) from `ts-extras` over manual undefined-guard throw blocks.
+
+## Targeted pattern scope
+
+This rule focuses on throw-only undefined guards that map directly to `assertDefined(value)`.
+
+### Matched patterns
+
+- `if (value === undefined) throw ...`
+- `if (undefined === value) throw ...`
+- `if (value == undefined) throw ...`
+- `if (undefined == value) throw ...`
+
+Only `if` statements that have no `else` branch and a throw-only consequent are
+reported.
+
+### Detection boundaries
+
+- ✅ Reports direct undefined-equality guards with throw-only consequents.
+- ❌ Does not report guards that return, log, or perform additional statements.
+- ❌ Does not report `typeof value === "undefined"` patterns.
+- ❌ Does not auto-fix.
+
+These boundaries keep matching deterministic and avoid broad semantic overreach during migration.
+
+## What this rule reports
+
+Throw-only undefined guard blocks that can be replaced with `assertDefined(value)`.
+
+## Why this rule exists
+
+`assertDefined()` expresses the intent of narrowing away `undefined` and centralizes assertion behavior.
+
+In large services, inline guards often diverge in error types/messages. Using
+`assertDefined` gives one recognizable pattern while preserving narrowing.
+
+## ❌ Incorrect
+
+```ts
+if (token === undefined) {
+    throw new Error("Token is required");
+}
+```
+
+## ✅ Correct
+
+```ts
+assertDefined(token);
+```
+
+## Behavior and migration notes
+
+- `assertDefined(value)` narrows away `undefined` after the assertion.
+- This rule intentionally targets throw-only guards without `else` branches.
+- `typeof value === "undefined"` checks are intentionally out of scope.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (undefined == monitorId) {
+    throw new TypeError("monitorId is required");
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+assertDefined(monitorId);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+assertDefined(config.apiKey);
+assertDefined(config.baseUrl);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-assert-defined": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your error-handling layer requires custom throw logic in each guard block.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/assert-defined.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/assert-defined.ts)
+
+````ts
+/**
+Assert that the given value is defined, meaning it is not `undefined`.
+
+If the value is `undefined`, a helpful `TypeError` will be thrown.
+
+@example
+```
+import {assertDefined} from 'ts-extras';
+
+const unicorn = 'unicorn';
+assertDefined(unicorn);
+
+const notUnicorn = undefined;
+assertDefined(notUnicorn);
+//=> TypeError: Expected a defined value, got `undefined`
+```
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R011
+
+## 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)