eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-is-present.md

@@ -0,0 +1,143 @@
+# prefer-ts-extras-is-present
+
+Require [`isPresent`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-present.ts) from `ts-extras` for direct nullish checks outside `Array.prototype.filter` callbacks.
+
+## Targeted pattern scope
+
+This rule scopes matching to direct nullish-check expressions outside `.filter(...)` callbacks.
+
+- Direct nullish checks outside `Array.prototype.filter` callbacks:
+- `value != null`
+- `value == null`
+- `value !== null && value !== undefined`
+- `value === null || value === undefined`
+
+Filter callbacks are handled by the dedicated filter rule; larger boolean expressions are only matched when they keep these shapes.
+
+## What this rule reports
+
+This rule reports direct nullish comparisons that should use `isPresent(...)` helpers.
+
+- Direct nullish checks outside `Array.prototype.filter` callbacks:
+- `value != null`
+- `value == null`
+- `value !== null && value !== undefined`
+- `value === null || value === undefined`
+
+## Why this rule exists
+
+`isPresent` gives one canonical predicate for non-nullish checks and reduces mixed null/undefined comparison styles.
+
+- Nullish guard intent is explicit.
+- Narrowing to `NonNullable<T>` follows one convention.
+- Verbose inline nullish checks are removed.
+
+## ❌ Incorrect
+
+```ts
+if (value != null) {
+    consume(value);
+}
+
+if (value === null || value === undefined) {
+    return;
+}
+```
+
+## ✅ Correct
+
+```ts
+if (isPresent(value)) {
+    consume(value);
+}
+
+if (!isPresent(value)) {
+    return;
+}
+```
+
+## Behavior and migration notes
+
+- `isPresent(value)` means value is neither `null` nor `undefined`.
+- `!isPresent(value)` is the nullish guard equivalent.
+- Filter-specific nullish patterns are covered by `prefer-ts-extras-is-present-filter`.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (profile != null) {
+    render(profile);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isPresent(profile)) {
+    render(profile);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const available = isPresent(cacheEntry);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-present": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your code style requires explicit `=== null` / `=== undefined` branches.
+
+## 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:** R021
+
+## 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-safe-integer.md

@@ -0,0 +1,116 @@
+# prefer-ts-extras-is-safe-integer
+
+Prefer [`isSafeInteger`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-safe-integer.ts) from `ts-extras` over `Number.isSafeInteger(...)`.
+
+This keeps predicate usage consistent with other `ts-extras` narrowing helpers.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Number.isSafeInteger(value)` calls that can be migrated to `isSafeInteger(value)` with deterministic fixes.
+
+- `Number.isSafeInteger(value)` call sites that can use `isSafeInteger(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `isSafeInteger(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Number.isSafeInteger(value)` call sites when `isSafeInteger(value)` is the intended replacement.
+
+- `Number.isSafeInteger(value)` call sites that can use `isSafeInteger(value)`.
+
+## Why this rule exists
+
+`isSafeInteger` standardizes safe-integer validation and keeps numeric guard usage consistent with other `ts-extras` helpers.
+
+- Safety-bound checks use one helper convention.
+- Predicate style is consistent with `isInteger` and `isFinite`.
+- Guard code for IDs/counters avoids mixed native/helper forms.
+
+## ❌ Incorrect
+
+```ts
+const isSafe = Number.isSafeInteger(value);
+```
+
+## ✅ Correct
+
+```ts
+const isSafe = isSafeInteger(value);
+```
+
+## Behavior and migration notes
+
+- Runtime behavior matches native `Number.isSafeInteger`.
+- Values outside `Number.MIN_SAFE_INTEGER` / `Number.MAX_SAFE_INTEGER` return `false`.
+- Non-number values are not coerced.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (Number.isSafeInteger(quantity)) {
+    persist(quantity);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (isSafeInteger(quantity)) {
+    persist(quantity);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const supported = isSafeInteger(index);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-is-safe-integer": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your team enforces native `Number.isSafeInteger` calls.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/is-safe-integer.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/is-safe-integer.ts)
+
+```ts
+/**
+A strongly-typed version of `Number.isSafeInteger()`.
+
+@category Improved builtin
+@category Type guard
+*/
+```
+
+> **Rule catalog ID:** R023
+
+## 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-key-in.md

@@ -0,0 +1,150 @@
+# prefer-ts-extras-key-in
+
+Prefer [`keyIn`](https://github.com/sindresorhus/ts-extras/blob/main/source/key-in.ts) from `ts-extras` over `key in object` checks.
+
+`keyIn(...)` provides better key narrowing for dynamic property checks.
+
+## Targeted pattern scope
+
+This rule focuses on direct `key in object` expressions that can be migrated to `keyIn(key, object)` with deterministic fixes.
+
+- Native `key in object` expressions that can use `keyIn(key, object)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `keyIn(key, object)` migrations safe.
+
+## What this rule reports
+
+This rule reports `key in object` expressions when `keyIn(key, object)` is the intended replacement.
+
+- Native `key in object` expressions that can use `keyIn(key, object)`.
+
+## Why this rule exists
+
+`keyIn` expresses key-membership checks with a helper that improves key narrowing in typed code.
+
+- Dynamic key checks have one canonical form.
+- Guarded property access needs fewer casts.
+- Membership guards are easier to audit in review.
+
+## ❌ Incorrect
+
+```ts
+if (key in payload) {
+    // ...
+}
+```
+
+## ✅ Correct
+
+```ts
+if (keyIn(key, payload)) {
+    // ...
+}
+```
+
+## Behavior and migration notes
+
+- Runtime semantics match the `in` operator for property existence on object/prototype chains.
+- `keyIn` is useful when key values start as `string`/`PropertyKey` and need narrowing.
+- If your code intentionally requires direct `in` syntax (for style or tooling), keep native checks.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (candidate in record) {
+    console.log(record[candidate as keyof typeof record]);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (keyIn(candidate, record)) {
+    console.log(record[candidate]);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const canRead = keyIn(data, selectedKey);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-key-in": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if direct `in` expressions are required by coding standards.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/key-in.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/key-in.ts)
+
+````ts
+/**
+Check if a key exists in an object and narrow the key type.
+
+This function performs __key narrowing__ - it narrows the key variable to only keys that actually exist in the object. Uses the `in` operator to check the entire prototype chain.
+
+When `keyIn` returns `true`, the key is narrowed to keys that exist in the object.
+When it returns `false`, the key type remains unchanged.
+
+Unlike `objectHasIn` and `objectHasOwn` (both do object narrowing), this narrows the _key_ type, making it useful for validating union types of possible keys.
+
+@example
+```
+import {keyIn} from 'ts-extras';
+
+const object = {foo: 1, bar: 2};
+const key = 'foo' as 'foo' | 'bar' | 'baz';
+
+if (keyIn(object, key)) {
+    // `key` is now: 'foo' | 'bar' (narrowed from union)
+    console.log(object[key]); // Safe access
+} else {
+    // `key` remains: 'foo' | 'bar' | 'baz' (unchanged)
+}
+
+// Works with symbols
+const symbol = Symbol.for('myKey');
+const objectWithSymbol = {[symbol]: 'value'};
+if (keyIn(objectWithSymbol, symbol)) {
+    // symbol is narrowed to existing symbol keys
+}
+```
+
+@note This uses the `in` operator and checks the prototype chain, but blocks `__proto__` and `constructor` for security.
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R024
+
+## 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-not.md

@@ -0,0 +1,138 @@
+# prefer-ts-extras-not
+
+Require [`not`](https://github.com/sindresorhus/ts-extras/blob/main/source/not.ts) from `ts-extras` over inline negated predicate callbacks in `filter` calls.
+
+## Targeted pattern scope
+
+This rule focuses on direct `.filter(...)` callbacks that negate a predicate and can be migrated to `not(predicate)` with deterministic fixes.
+
+- Inline negated predicate callbacks in `.filter(...)` that can use `not(predicate)`.
+- `array.filter((value) => !predicate(value))`
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `not(predicate)` migrations safe.
+
+## What this rule reports
+
+This rule reports `.filter(...)` call sites when `not(predicate)` is the intended replacement.
+
+- Inline negated predicate callbacks in `.filter(...)` that can use `not(predicate)`.
+- `array.filter((value) => !predicate(value))`
+
+## Why this rule exists
+
+`not(predicate)` communicates intent directly and preserves predicate-based typing in a reusable helper.
+
+## ❌ Incorrect
+
+```ts
+const activeUsers = users.filter((user) => !isArchived(user));
+```
+
+## ✅ Correct
+
+```ts
+const activeUsers = users.filter(not(isArchived));
+```
+
+## Behavior and migration notes
+
+- `not(predicate)` preserves predicate inversion intent in one reusable helper.
+- This rule targets inline negation wrappers inside `filter` callbacks.
+- Callbacks that do extra work beyond predicate negation should be reviewed manually.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const active = users.filter((user) => !isArchived(user));
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const active = users.filter(not(isArchived));
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const nonEmpty = values.filter(not(isEmptyValue));
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-not": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if your codebase requires explicit inline callback bodies for readability.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/not.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/not.ts)
+
+````ts
+/**
+Invert a type predicate function.
+
+This utility allows you to create the inverse of any type guard function, using TypeScript's `Exclude` utility type to properly narrow types.
+
+@example
+```
+import {not} from 'ts-extras';
+
+const isNullish = (value: unknown): value is null | undefined => value == null;
+
+const isNotNullish = not(isNullish);
+
+const values = [1, null, 2, undefined, 3];
+const defined = values.filter(isNotNullish);
+//=> [1, 2, 3]
+// with type number[]
+
+// Works with any type guard
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+const isNotString = not(isString);
+
+declare const mixedValue: string | number | boolean;
+if (isNotString(mixedValue)) {
+    mixedValue;
+    //=> number | boolean
+}
+```
+
+@note TypeScript may fail to narrow types in nested branches, with mutated variables, or when using `Exclude` with complex union types. See:
+- https://github.com/microsoft/TypeScript/issues/44901
+- https://github.com/microsoft/TypeScript/issues/43589
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R025
+
+## 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-object-entries.md

@@ -0,0 +1,130 @@
+# prefer-ts-extras-object-entries
+
+Prefer [`objectEntries`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-entries.ts) from `ts-extras` over `Object.entries(...)`.
+
+`objectEntries(...)` preserves stronger key/value typing for object iteration and reduces local casting noise.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Object.entries(value)` calls that can be migrated to `objectEntries(value)` with deterministic fixes.
+
+- `Object.entries(value)` call sites that can use `objectEntries(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `objectEntries(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Object.entries(value)` call sites when `objectEntries(value)` is the intended replacement.
+
+- `Object.entries(value)` call sites that can use `objectEntries(value)`.
+
+## Why this rule exists
+
+`objectEntries` gives better static typing for entry iteration, especially when the object has known keys.
+
+- Key unions are preserved more consistently in loops.
+- Value access in tuple destructuring needs fewer local casts.
+- Team code converges on one explicit runtime helper for entry iteration.
+
+## ❌ Incorrect
+
+```ts
+const pairs = Object.entries(siteStatusById);
+```
+
+## ✅ Correct
+
+```ts
+const pairs = objectEntries(siteStatusById);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics stay aligned with `Object.entries` (own enumerable string-keyed entries only).
+- Property order behavior remains the same as native `Object.entries`.
+- Symbol keys are still excluded, just like native behavior.
+- For loosely typed inputs (for example `Record<string, unknown>`), key type remains broad (`string`).
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const entries = Object.entries(settings);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const entries = objectEntries(settings);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+for (const [key, value] of objectEntries(env)) {
+    void key;
+    void value;
+}
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-entries": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if you must use native `Object.entries` directly for interop constraints.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-entries.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-entries.ts)
+
+````ts
+/**
+A strongly-typed version of `Object.entries()`.
+
+This is useful since `Object.entries()` always returns an array of `Array<[string, T]>`. This function returns a strongly-typed array of the entries of the given object.
+
+- [TypeScript issues about this](https://github.com/microsoft/TypeScript/pull/12253)
+
+@example
+```
+import {objectEntries} from 'ts-extras';
+
+const stronglyTypedEntries = objectEntries({a: 1, b: 2, c: 3});
+//=> Array<['a' | 'b' | 'c', number]>
+
+const untypedEntries = Object.entries({a: 1, b: 2, c: 3});
+//=> Array<[string, number]>
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R026
+
+## 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)