eslint-plugin-typefest 1.0.1

package/docs/rules/prefer-ts-extras-object-from-entries.md

@@ -0,0 +1,131 @@
+# prefer-ts-extras-object-from-entries
+
+Prefer [`objectFromEntries`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-from-entries.ts) from `ts-extras` over `Object.fromEntries(...)`.
+
+`objectFromEntries(...)` preserves stronger key/value typing and avoids local casting after entry reconstruction.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Object.fromEntries(entries)` calls that can be migrated to `objectFromEntries(entries)` with deterministic fixes.
+
+- `Object.fromEntries(entries)` call sites that can use `objectFromEntries(entries)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `objectFromEntries(entries)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Object.fromEntries(entries)` call sites when `objectFromEntries(entries)` is the intended replacement.
+
+- `Object.fromEntries(entries)` call sites that can use `objectFromEntries(entries)`.
+
+## Why this rule exists
+
+`objectFromEntries` improves the reconstructed object type when building objects from typed entry tuples.
+
+- Reconstructed key/value relationships are preserved more consistently.
+- Follow-up casting after reconstruction is needed less often.
+- Object reconstruction uses one explicit helper across modules.
+
+## ❌ Incorrect
+
+```ts
+const statusById = Object.fromEntries(statusEntries);
+```
+
+## ✅ Correct
+
+```ts
+const statusById = objectFromEntries(statusEntries);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Object.fromEntries`.
+- Duplicate keys keep the last assigned entry, matching native behavior.
+- Input must still be iterable entry pairs (`[key, value]`).
+- If your entries are already widened to `[string, unknown]`, resulting object types remain broad.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const config = Object.fromEntries(entries);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const config = objectFromEntries(entries);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const grouped = objectFromEntries(pairs);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-from-entries": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if you must keep direct `Object.fromEntries` calls for interop or platform constraints.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-from-entries.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-from-entries.ts)
+
+````ts
+/**
+A strongly-typed version of `Object.fromEntries()`.
+
+This is useful since `Object.fromEntries()` always returns `{[key: string]: T}`. This function returns a strongly-typed object from the given array of entries.
+
+- [TypeScript issues about this](https://github.com/microsoft/TypeScript/issues/35745)
+
+@example
+```
+import {objectFromEntries} from 'ts-extras';
+
+const stronglyTypedObjectFromEntries = objectFromEntries([
+    ['a', 123],
+    ['b', 'someString'],
+    ['c', true],
+]);
+//=> {a: number; b: string; c: boolean}
+
+const untypedEntries = Object.fromEntries([['a', 123], ['b', 'someString'], ['c', true]]);
+//=> {[key: string]: unknown}
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R027
+
+## 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-has-in.md

@@ -0,0 +1,141 @@
+# prefer-ts-extras-object-has-in
+
+Require [`objectHasIn`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-has-in.ts) from `ts-extras` over `Reflect.has()`.
+
+## Targeted pattern scope
+
+This rule only matches direct `Reflect.has(object, key)` calls where both arguments can be forwarded unchanged to `objectHasIn(object, key)`.
+
+- `Reflect.has(object, key)` calls.
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports `Reflect.has(object, key)` calls that can be replaced with `objectHasIn(object, key)`.
+
+- `Reflect.has(object, key)` calls.
+
+## Why this rule exists
+
+`objectHasIn()` provides stronger TypeScript narrowing for key-existence checks while preserving inherited-property semantics.
+
+- Use this when inherited members should count as present.
+- Reduces cast-heavy follow-up property access.
+- Keeps prototype-aware checks consistent across modules.
+
+## ❌ Incorrect
+
+```ts
+if (Reflect.has(record, key)) {
+    console.log(record[key as keyof typeof record]);
+}
+```
+
+## ✅ Correct
+
+```ts
+if (objectHasIn(record, key)) {
+    console.log(record[key]);
+}
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Reflect.has` and `key in object` (prototype chain included).
+- Prefer `objectHasOwn` if inherited members should be excluded.
+- For security-sensitive payload validation, confirm that inherited properties are acceptable.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (Reflect.has(input, "name")) {
+    console.log((input as { name: unknown }).name);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (objectHasIn(input, "name")) {
+    console.log(input.name);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const canAccess = objectHasIn(candidate, key);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-has-in": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if checks must be own-property-only, or if runtime helper dependencies are disallowed in your environment.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-has-in.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-has-in.ts)
+
+````ts
+/**
+Check if an object has a property (including inherited) and narrow the object type.
+
+This function performs __object narrowing__ - it adds the checked property to the object's type, allowing safe property access. Uses the `in` operator to check the entire prototype chain.
+
+Unlike `objectHasOwn` (own properties only) and `keyIn` (key narrowing), this narrows the _object_ type to include inherited properties.
+
+@example
+```
+import {objectHasIn} from 'ts-extras';
+
+const data: unknown = {foo: 1};
+
+if (objectHasIn(data, 'foo')) {
+    // `data` is now: unknown & {foo: unknown}
+    console.log(data.foo); // Safe access
+}
+
+// Also checks prototype chain
+if (objectHasIn(data, 'toString')) {
+    // `data` is now: unknown & {toString: unknown}
+    console.log(data.toString); // Safe access to inherited method
+}
+```
+
+@note This uses the `in` operator and checks the entire prototype chain, but blocks `__proto__` and `constructor` for security.
+
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R028
+
+## 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-has-own.md

@@ -0,0 +1,137 @@
+# prefer-ts-extras-object-has-own
+
+Require [`objectHasOwn`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-has-own.ts) from `ts-extras` over `Object.hasOwn` when checking own properties.
+
+## Targeted pattern scope
+
+This rule only matches direct `Object.hasOwn(object, key)` calls where both arguments can be forwarded unchanged to `objectHasOwn(object, key)`.
+
+- Calls to `Object.hasOwn(...)` in runtime source files and typed rule fixtures.
+
+Syntactically similar alternatives are intentionally out of scope unless they preserve the same AST shape.
+
+## What this rule reports
+
+This rule reports `Object.hasOwn(object, key)` calls that can be replaced with `objectHasOwn(object, key)`.
+
+- Calls to `Object.hasOwn(...)` in runtime source files and typed rule fixtures.
+
+## Why this rule exists
+
+`objectHasOwn` is a type guard that narrows the object to include the checked property. This makes downstream access safer and reduces manual casts after own-property checks.
+
+- Prefer this when you only want **own** properties.
+- Avoids repetitive `(obj as { prop: ... }).prop` casts after checks.
+- Makes guard intent explicit for reviewers.
+
+## ❌ Incorrect
+
+```ts
+if (Object.hasOwn(record, key)) {
+    console.log(record[key as keyof typeof record]);
+}
+```
+
+## ✅ Correct
+
+```ts
+if (objectHasOwn(record, key)) {
+    console.log(record[key]);
+}
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Object.hasOwn` (prototype chain is **not** considered).
+- Useful for untrusted inputs where inherited members should not count.
+- If your current code uses `Reflect.has` or `in`, confirm that own-only checks are acceptable before migration.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+if (Object.hasOwn(data, "id")) {
+    console.log((data as { id: unknown }).id);
+}
+```
+
+### ✅ Correct — Additional example
+
+```ts
+if (objectHasOwn(data, "id")) {
+    console.log(data.id);
+}
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const isOwn = objectHasOwn(record, field);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-has-own": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if you intentionally rely on prototype-chain checks (`in`/`Reflect.has`) or if runtime helper dependencies are disallowed in your environment.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-has-own.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-has-own.ts)
+
+````ts
+/**
+A strongly-typed version of `Object.hasOwn()` that narrows the object type.
+
+This function performs __object narrowing__ for own properties only - it adds the checked property to the object's type, allowing safe property access. Does not check the prototype chain.
+
+Unlike `objectHasIn` (includes inherited) and `keyIn` (key narrowing), this narrows the _object_ type to include only own properties.
+
+@example
+```
+import {objectHasOwn} from 'ts-extras';
+
+const data: unknown = {foo: 1};
+
+if (objectHasOwn(data, 'foo')) {
+    // `data` is now: unknown & {foo: unknown}
+    console.log(data.foo); // Safe access to own property
+}
+
+objectHasOwn({}, 'toString');
+//=> false (inherited property, not own)
+```
+
+@category Improved builtin
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R029
+
+## 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-keys.md

@@ -0,0 +1,127 @@
+# prefer-ts-extras-object-keys
+
+Prefer [`objectKeys`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-keys.ts) from `ts-extras` over `Object.keys(...)`.
+
+`objectKeys(...)` preserves stronger key typing and avoids repeated casts in iteration paths.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Object.keys(value)` calls that can be migrated to `objectKeys(value)` with deterministic fixes.
+
+- `Object.keys(value)` call sites that can use `objectKeys(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `objectKeys(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Object.keys(value)` call sites when `objectKeys(value)` is the intended replacement.
+
+- `Object.keys(value)` call sites that can use `objectKeys(value)`.
+
+## Why this rule exists
+
+`objectKeys` improves key typing for indexed access and iteration paths.
+
+- Fewer `as Array<keyof T>` casts in loops.
+- Safer indexed reads after key iteration.
+- One canonical helper for key iteration patterns.
+
+## ❌ Incorrect
+
+```ts
+const keys = Object.keys(monitorConfig);
+```
+
+## ✅ Correct
+
+```ts
+const keys = objectKeys(monitorConfig);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Object.keys` (own enumerable string keys only).
+- Symbol keys are excluded, same as native behavior.
+- Numeric keys are still returned as strings, matching native output.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const keys = Object.keys(model);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const keys = objectKeys(model);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+for (const key of objectKeys(theme)) {
+    void key;
+}
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-keys": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if you must keep direct `Object.keys` calls for interop constraints.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-keys.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-keys.ts)
+
+````ts
+/**
+A strongly-typed version of `Object.keys()`.
+
+This is useful since `Object.keys()` always returns an array of strings. This function returns a strongly-typed array of the keys of the given object.
+
+- [Explanation](https://stackoverflow.com/questions/55012174/why-doesnt-object-keys-return-a-keyof-type-in-typescript)
+- [TypeScript issues about this](https://github.com/microsoft/TypeScript/issues/45390)
+
+@example
+```
+import {objectKeys} from 'ts-extras';
+
+const stronglyTypedItems = objectKeys({a: 1, b: 2, c: 3}); // => Array<'a' | 'b' | 'c'>
+const untypedItems = Object.keys({a: 1, b: 2, c: 3}); // => Array<string>
+```
+
+@category Improved builtin
+@category Type guard
+*/
+````
+
+> **Rule catalog ID:** R030
+
+## 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-values.md

@@ -0,0 +1,128 @@
+# prefer-ts-extras-object-values
+
+Prefer [`objectValues`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-values.ts) from `ts-extras` over `Object.values(...)`.
+
+`objectValues(...)` preserves stronger value typing and keeps value iteration contracts explicit.
+
+## Targeted pattern scope
+
+This rule focuses on direct `Object.values(value)` calls that can be migrated to `objectValues(value)` with deterministic fixes.
+
+- `Object.values(value)` call sites that can use `objectValues(value)`.
+
+Alias indirection, wrapper helpers, and non-canonical call shapes are excluded to keep `objectValues(value)` migrations safe.
+
+## What this rule reports
+
+This rule reports `Object.values(value)` call sites when `objectValues(value)` is the intended replacement.
+
+- `Object.values(value)` call sites that can use `objectValues(value)`.
+
+## Why this rule exists
+
+`objectValues` improves value typing during iteration and post-processing.
+
+- Value unions are preserved more consistently.
+- Downstream map/filter code needs fewer local casts.
+- Value extraction style stays consistent across modules.
+
+## ❌ Incorrect
+
+```ts
+const values = Object.values(siteStateMap);
+```
+
+## ✅ Correct
+
+```ts
+const values = objectValues(siteStateMap);
+```
+
+## Behavior and migration notes
+
+- Runtime semantics align with `Object.values` (own enumerable string-keyed values).
+- Symbol-keyed values remain excluded, matching native behavior.
+- For broadly typed records, resulting value types remain broad.
+
+## Additional examples
+
+### ❌ Incorrect — Additional example
+
+```ts
+const values = Object.values(features);
+```
+
+### ✅ Correct — Additional example
+
+```ts
+const values = objectValues(features);
+```
+
+### ✅ Correct — Repository-wide usage
+
+```ts
+const labels = objectValues(enumLikeObject);
+```
+
+## ESLint flat config example
+
+```ts
+import typefest from "eslint-plugin-typefest";
+
+export default [
+    {
+        plugins: { typefest },
+        rules: {
+            "typefest/prefer-ts-extras-object-values": "error",
+        },
+    },
+];
+```
+
+## When not to use it
+
+Disable this rule if direct `Object.values` calls are required for interop constraints.
+
+## Package documentation
+
+ts-extras package documentation:
+
+Source file: [`source/object-values.ts`](https://github.com/sindresorhus/ts-extras/blob/main/source/object-values.ts)
+
+````ts
+/**
+A strongly-typed version of `Object.values()`.
+
+This is useful since `Object.values()` always returns `T[]`. This function returns a strongly-typed array of the values of the given object.
+
+- [TypeScript issues about this](https://github.com/microsoft/TypeScript/pull/12253)
+
+@example
+```
+import {objectValues} from 'ts-extras';
+
+const object: {a: number; b?: string} = {a: 1, b: 'hello'};
+
+const stronglyTypedValues = objectValues(object);
+//=> Array<number | string>
+
+const untypedValues = Object.values(object);
+//=> Array<string | number | undefined>
+```
+
+@category Improved builtin
+*/
+````
+
+> **Rule catalog ID:** R031
+
+## 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)