eslint-plugin-typefest 1.0.1

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

@@ -0,0 +1,138 @@
+# prefer-ts-extras-array-concat
+
+Prefer [`arrayConcat`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-concat.ts) from `ts-extras` over `array.concat(...)`.
+
+`arrayConcat(...)` preserves stronger tuple and readonly-array typing across generic flows.
+
+## Targeted pattern scope
+
+This rule focuses on direct `left.concat(right)` calls that can be migrated to `arrayConcat(left, right)` with deterministic fixes.
+
+- `left.concat(right)` call sites that can use `arrayConcat(left, right)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayConcat(left, right)` migrations safe.
+
+## What this rule reports
+
+This rule reports `left.concat(right)` call sites when `arrayConcat(left, right)` is the intended replacement.
+
+- `left.concat(right)` call sites that can use `arrayConcat(left, right)`.
+
+## Why this rule exists
+
+`arrayConcat` preserves tuple/readonly array typing better when concatenating heterogeneous arrays.
+
+- The output element type is inferred more predictably in generic utilities.
+- Concatenation style is consistent with other `ts-extras` array helpers.
+- Post-concat casts are needed less often.
+
+## ❌ Incorrect
+
+```ts
+const allIds = primaryIds.concat(secondaryIds);
+```
+
+## ✅ Correct
+
+```ts
+const allIds = arrayConcat(primaryIds, secondaryIds);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Array.prototype.concat`.
+- Concatenation is still shallow (no deep cloning).
+- Array arguments are flattened one level, matching native concat semantics.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const combined = left.concat(right);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const combined = arrayConcat(left, right);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const merged = arrayConcat(baseFlags, envFlags);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-concat": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase standardizes on native `.concat()` for framework interop.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-concat.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-concat.ts)
+
+````ts
+/**
+A strongly-typed version of `Array#concat()` that properly handles arrays of different types.
+
+TypeScript's built-in `Array#concat()` has issues with type inference when concatenating arrays of different types or empty arrays. This function provides proper type inference for heterogeneous array concatenation.
+
+Note: This function preserves array holes, matching the native `Array#concat()` behavior.
+
+@example
+```
+import {arrayConcat} from 'ts-extras';
+
+const strings = ['a', 'b'];
+const numbers = [1, 2];
+
+// TypeScript's built-in concat would error here
+const mixed = arrayConcat(strings, numbers);
+//=> ['a', 'b', 1, 2]
+//   ^? (string | number)[]
+
+// Works with tuples
+const tuple = arrayConcat(['x'] as const, [1] as const);
+//=> ['x', 1]
+//   ^? (1 | 'x')[]
+
+// Handles empty arrays correctly
+const withEmpty = arrayConcat([], ['hello']);
+//=> ['hello']
+//   ^? string[]
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R002
+
+## 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-find-last-index.md

@@ -0,0 +1,108 @@
+# prefer-ts-extras-array-find-last-index
+
+Prefer [`arrayFindLastIndex`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-find-last-index.ts) from `ts-extras` over `array.findLastIndex(...)`.
+
+`arrayFindLastIndex(...)` improves predicate inference in typed arrays.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.findLastIndex(predicate)` calls that can be migrated to `arrayFindLastIndex(array, predicate)` with deterministic fixes.
+
+- `array.findLastIndex(predicate)` call sites that can use `arrayFindLastIndex(array, predicate)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayFindLastIndex(array, predicate)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.findLastIndex(predicate)` call sites when `arrayFindLastIndex(array, predicate)` is the intended replacement.
+
+- `array.findLastIndex(predicate)` call sites that can use `arrayFindLastIndex(array, predicate)`.
+
+## Why this rule exists
+
+`arrayFindLastIndex` standardizes reverse index lookup and keeps call signatures aligned with other `ts-extras` search helpers.
+
+- Reverse index scans are explicit at the call site.
+- Search code avoids mixed native/helper patterns.
+- Index-based follow-up logic stays uniform across modules.
+
+## ❌ Incorrect
+
+```ts
+const index = monitors.findLastIndex((entry) => entry.id === targetId);
+```
+
+## ✅ Correct
+
+```ts
+const index = arrayFindLastIndex(monitors, (entry) => entry.id === targetId);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Array.prototype.findLastIndex`.
+- Search still proceeds from right to left.
+- If no element matches, the result is `-1`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const index = logs.findLastIndex((entry) => entry.level === "warn");
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const index = arrayFindLastIndex(logs, (entry) => entry.level === "warn");
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const retryIndex = arrayFindLastIndex(attempts, (attempt) => !attempt.success);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-find-last-index": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase has standardized on native `.findLastIndex()`.
+
+## Package documentation
+
+ts-extras package documentation:
+
+`ts-extras@0.17.x` does not currently expose `arrayFindLastIndex` in its published API, so there is no canonical `source/*.ts` link for this helper yet.
+
+Reference links:
+
+- [`ts-extras` API list (README)](https://github.com/sindresorhus/ts-extras/blob/main/readme.md#api)
+- [`ts-extras` source directory](https://github.com/sindresorhus/ts-extras/tree/main/source)
+
+> **Rule catalog ID:** R005
+
+## 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-find-last.md

@@ -0,0 +1,108 @@
+# prefer-ts-extras-array-find-last
+
+Prefer [`arrayFindLast`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-find-last.ts) from `ts-extras` over `array.findLast(...)`.
+
+`arrayFindLast(...)` improves predicate inference and value narrowing in typed arrays.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.findLast(predicate)` calls that can be migrated to `arrayFindLast(array, predicate)` with deterministic fixes.
+
+- `array.findLast(predicate)` call sites that can use `arrayFindLast(array, predicate)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayFindLast(array, predicate)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.findLast(predicate)` call sites when `arrayFindLast(array, predicate)` is the intended replacement.
+
+- `array.findLast(predicate)` call sites that can use `arrayFindLast(array, predicate)`.
+
+## Why this rule exists
+
+`arrayFindLast` makes reverse-direction predicate lookups explicit and keeps them aligned with the `ts-extras` helper style.
+
+- Reverse scans are easier to spot during code review.
+- Call signatures stay consistent with `arrayFind` / `arrayFindLastIndex`.
+- Utility code that depends on "latest match" is easier to audit.
+
+## ❌ Incorrect
+
+```ts
+const monitor = monitors.findLast((entry) => entry.id === targetId);
+```
+
+## ✅ Correct
+
+```ts
+const monitor = arrayFindLast(monitors, (entry) => entry.id === targetId);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Array.prototype.findLast`.
+- Search direction remains right-to-left.
+- Result is the matching element, or `undefined` if no match exists.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const latest = events.findLast((entry) => entry.type === "login");
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const latest = arrayFindLast(events, (entry) => entry.type === "login");
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const trailingError = arrayFindLast(logs, (entry) => entry.level === "error");
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-find-last": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team intentionally uses native `.findLast()` everywhere.
+
+## Package documentation
+
+ts-extras package documentation:
+
+`ts-extras@0.17.x` does not currently expose `arrayFindLast` in its published API, so there is no canonical `source/*.ts` link for this helper yet.
+
+Reference links:
+
+- [`ts-extras` API list (README)](https://github.com/sindresorhus/ts-extras/blob/main/readme.md#api)
+- [`ts-extras` source directory](https://github.com/sindresorhus/ts-extras/tree/main/source)
+
+> **Rule catalog ID:** R004
+
+## 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-find.md

@@ -0,0 +1,108 @@
+# prefer-ts-extras-array-find
+
+Prefer [`arrayFind`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-find.ts) from `ts-extras` over `array.find(...)`.
+
+`arrayFind(...)` improves predicate inference and value narrowing in typed arrays.
+
+## Targeted pattern scope
+
+This rule focuses on direct `array.find(predicate)` calls that can be migrated to `arrayFind(array, predicate)` with deterministic fixes.
+
+- `array.find(predicate)` call sites that can use `arrayFind(array, predicate)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `arrayFind(array, predicate)` migrations safe.
+
+## What this rule reports
+
+This rule reports `array.find(predicate)` call sites when `arrayFind(array, predicate)` is the intended replacement.
+
+- `array.find(predicate)` call sites that can use `arrayFind(array, predicate)`.
+
+## Why this rule exists
+
+`arrayFind` keeps predicate-driven lookup aligned with the other `ts-extras` helper APIs and improves inference in generic code.
+
+- Predicate call sites are standardized across modules.
+- Result types are easier to follow in utility layers.
+- Local type assertions after `find` calls are reduced.
+
+## ❌ Incorrect
+
+```ts
+const monitor = monitors.find((entry) => entry.id === targetId);
+```
+
+## ✅ Correct
+
+```ts
+const monitor = arrayFind(monitors, (entry) => entry.id === targetId);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Array.prototype.find`.
+- Search still returns the first matching element.
+- If no element matches, the result is `undefined`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const user = users.find((item) => item.id === userId);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const user = arrayFind(users, (item) => item.id === userId);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const firstError = arrayFind(logs, (entry) => entry.level === "error");
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-find": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team requires native `.find()` for consistency with existing shared APIs.
+
+## Package documentation
+
+ts-extras package documentation:
+
+`ts-extras@0.17.x` does not currently expose `arrayFind` in its published API, so there is no canonical `source/*.ts` link for this helper yet.
+
+Reference links:
+
+- [`ts-extras` API list (README)](https://github.com/sindresorhus/ts-extras/blob/main/readme.md#api)
+- [`ts-extras` source directory](https://github.com/sindresorhus/ts-extras/tree/main/source)
+
+> **Rule catalog ID:** R003
+
+## 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-first.md

@@ -0,0 +1,132 @@
+# prefer-ts-extras-array-first
+
+Require [`arrayFirst`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-first.ts) from `ts-extras` over direct `array[0]` access.
+
+## Targeted pattern scope
+
+This rule only matches direct first-element index access (`receiver[0]`) where the receiver expression can be reused unchanged in `arrayFirst(receiver)`.
+
+- Direct first-element access using index form (`array[0]`).
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports direct `receiver[0]` access sites that can be safely replaced with `arrayFirst(receiver)`.
+
+- Direct first-element access using index form (`array[0]`).
+
+## Why this rule exists
+
+`arrayFirst` makes first-element access explicit and keeps tuple/readonly inference consistent with the rest of the `ts-extras` helper set.
+
+- First-element lookups are easier to search and standardize.
+- Tuple-aware access patterns are consistent in shared utilities.
+- Teams avoid mixing helper-based and index-based first-item access.
+
+## ❌ Incorrect
+
+```ts
+const first = values[0];
+```
+
+## ✅ Correct
+
+```ts
+const first = arrayFirst(values);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches `array[0]` access.
+- Empty arrays still yield `undefined`.
+- This rule targets index access; optional chaining around access (`array?.[0]`) should be reviewed manually during migration.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const first = rows[0];
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const first = arrayFirst(rows);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const header = arrayFirst(headers);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-array-first": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if direct index access is required in performance-sensitive hotspots.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/array-first.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/array-first.ts)
+
+````ts
+/**
+Return the first item of an array with stronger typing for tuples.
+
+This mirrors getting `array[0]` but with better type safety and handling for empty arrays.
+
+@example
+```
+import {arrayFirst} from 'ts-extras';
+
+const tuple = ['abc', 123, true] as const;
+const first = arrayFirst(tuple);
+//=> 'abc'
+//   ^? 'abc'
+
+const array = ['a', 'b', 'c'];
+const maybeFirst = arrayFirst(array);
+//=> 'a'
+//   ^? string | undefined
+
+// Empty arrays
+const empty: string[] = [];
+const noFirst = arrayFirst(empty);
+//=> undefined
+//   ^? string | undefined
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R006
+
+## 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)