es-toolkit-eslint-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aliaksandr Zasim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# es-toolkit-eslint-plugin
+
+An ESLint plugin that actively suggests [es-toolkit](https://es-toolkit.dev) utilities in
+place of verbose hand-written JS/TS.
+
+Rules are **report-only** (no auto-fix) and lean on
+[esquery](https://eslint.org/docs/latest/extend/selectors) selectors to keep detection
+declarative and minimal.
+
+> [!WARNING]
+> **Early stage.** This project is at a very early stage and under active development.
+> False positives are possible.
+> Try it out and [file issues](https://github.com/syxov/es-toolkit-eslint-plugin/issues).
+
+> Requires **ESLint 10** (flat config).
+
+## Install
+
+```sh
+pnpm add -D es-toolkit-eslint-plugin
+```
+
+## Usage
+
+```js
+// eslint.config.js
+import esToolkit from 'es-toolkit-eslint-plugin';
+
+export default [
+  {
+    files: ['**/*.{js,ts}'],
+    plugins: { 'es-toolkit': esToolkit },
+    rules: {
+      'es-toolkit/prefer-clamp': 'error',
+    },
+  },
+];
+```
+
+Or extend the bundled config:
+
+```js
+import esToolkit from 'es-toolkit-eslint-plugin';
+
+export default [esToolkit.configs.recommended];
+```
+
+## Rules
+
+| Rule                                                   | Description                                              |
+| ------------------------------------------------------ | -------------------------------------------------------- |
+| [`prefer-clamp`](docs/rules/prefer-clamp.md)           | Prefer `clamp` over nested `Math.min`/`Math.max`.        |
+| [`prefer-compact`](docs/rules/prefer-compact.md)       | Prefer `compact` over `.filter(Boolean)`.                |
+| [`prefer-delay`](docs/rules/prefer-delay.md)           | Prefer `delay` over `new Promise` + `setTimeout`.        |
+| [`prefer-is-empty`](docs/rules/prefer-is-empty.md)     | Prefer `isEmpty` over `Object.keys(obj).length === 0`.   |
+| [`prefer-is-equal`](docs/rules/prefer-is-equal.md)     | Prefer `isEqual` over comparing `JSON.stringify` output. |
+| [`prefer-last`](docs/rules/prefer-last.md)             | Prefer `last` over `arr[arr.length - 1]`.                |
+| [`prefer-random-int`](docs/rules/prefer-random-int.md) | Prefer `randomInt` over `Math.floor(Math.random() * …)`. |
+| [`prefer-range`](docs/rules/prefer-range.md)           | Prefer `range` over manual index-array construction.     |
+| [`prefer-sample`](docs/rules/prefer-sample.md)         | Prefer `sample` over random-index array access.          |
+| [`prefer-uniq`](docs/rules/prefer-uniq.md)             | Prefer `uniq` over `new Set` round-trips.                |
+
+## Development
+
+```sh
+pnpm install
+pnpm test      # vitest + RuleTester
+pnpm build     # tsc -> dist/
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'prefer-clamp': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferClamp", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-compact': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferCompact", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-delay': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferDelay", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-is-empty': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferIsEmpty", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-is-equal': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferIsEqual", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-last': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferLast", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-random-int': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferRandomInt", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-range': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferRange", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-sample': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferSample", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'prefer-uniq': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferUniq", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+    };
+    configs: {};
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,44 @@
+import { preferClamp } from './rules/prefer-clamp.js';
+import { preferCompact } from './rules/prefer-compact.js';
+import { preferDelay } from './rules/prefer-delay.js';
+import { preferIsEmpty } from './rules/prefer-is-empty.js';
+import { preferIsEqual } from './rules/prefer-is-equal.js';
+import { preferLast } from './rules/prefer-last.js';
+import { preferRandomInt } from './rules/prefer-random-int.js';
+import { preferRange } from './rules/prefer-range.js';
+import { preferSample } from './rules/prefer-sample.js';
+import { preferUniq } from './rules/prefer-uniq.js';
+const plugin = {
+    meta: { name: 'es-toolkit-eslint-plugin', version: '1.0.0' },
+    rules: {
+        'prefer-clamp': preferClamp,
+        'prefer-compact': preferCompact,
+        'prefer-delay': preferDelay,
+        'prefer-is-empty': preferIsEmpty,
+        'prefer-is-equal': preferIsEqual,
+        'prefer-last': preferLast,
+        'prefer-random-int': preferRandomInt,
+        'prefer-range': preferRange,
+        'prefer-sample': preferSample,
+        'prefer-uniq': preferUniq,
+    },
+    configs: {},
+};
+plugin.configs = {
+    recommended: {
+        plugins: { 'es-toolkit': plugin },
+        rules: {
+            'es-toolkit/prefer-clamp': 'error',
+            'es-toolkit/prefer-compact': 'error',
+            'es-toolkit/prefer-delay': 'error',
+            'es-toolkit/prefer-is-empty': 'error',
+            'es-toolkit/prefer-is-equal': 'error',
+            'es-toolkit/prefer-last': 'error',
+            'es-toolkit/prefer-random-int': 'error',
+            'es-toolkit/prefer-range': 'error',
+            'es-toolkit/prefer-sample': 'error',
+            'es-toolkit/prefer-uniq': 'error',
+        },
+    },
+};
+export default plugin;

package/dist/rules/prefer-clamp.d.ts

@@ -0,0 +1,3 @@
+export declare const preferClamp: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferClamp", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-clamp.js

@@ -0,0 +1,25 @@
+import { createRule } from '../utils/create-rule.js';
+const mathCall = (method) => `CallExpression[callee.object.name="Math"][callee.property.name="${method}"][arguments.length=2]`;
+// A clamp is an outer Math call wrapping the opposite Math call as a direct argument:
+// Math.min(Math.max(value, lower), upper) or Math.max(Math.min(value, upper), lower).
+const clampPattern = (outer, inner) => `${mathCall(outer)}:has(> ${mathCall(inner)})`;
+export const preferClamp = createRule({
+    name: 'prefer-clamp',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `clamp` from es-toolkit over nested `Math.min`/`Math.max`.',
+        },
+        schema: [],
+        messages: {
+            preferClamp: 'Prefer `clamp` from es-toolkit instead of nesting `Math.min`/`Math.max`.',
+        },
+    },
+    create(context) {
+        const report = (node) => context.report({ node, messageId: 'preferClamp' });
+        return {
+            [clampPattern('min', 'max')]: report,
+            [clampPattern('max', 'min')]: report,
+        };
+    },
+});

package/dist/rules/prefer-compact.d.ts

@@ -0,0 +1,3 @@
+export declare const preferCompact: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferCompact", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-compact.js

@@ -0,0 +1,20 @@
+import { createRule } from '../utils/create-rule.js';
+const filterBoolean = 'CallExpression[callee.property.name="filter"][arguments.length=1][arguments.0.name="Boolean"]';
+export const preferCompact = createRule({
+    name: 'prefer-compact',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `compact` from es-toolkit over `.filter(Boolean)`.',
+        },
+        schema: [],
+        messages: {
+            preferCompact: 'Prefer `compact` from es-toolkit instead of `.filter(Boolean)`.',
+        },
+    },
+    create(context) {
+        return {
+            [filterBoolean]: (node) => context.report({ node, messageId: 'preferCompact' }),
+        };
+    },
+});

package/dist/rules/prefer-delay.d.ts

@@ -0,0 +1,3 @@
+export declare const preferDelay: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferDelay", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-delay.js

@@ -0,0 +1,34 @@
+import { createRule } from '../utils/create-rule.js';
+// `new Promise(resolve => setTimeout(resolve, ms))` — a single-param executor whose
+// expression body is a two-argument `setTimeout` whose first argument is an identifier.
+const promisifiedTimeout = 'NewExpression[callee.name="Promise"][arguments.length=1] > ArrowFunctionExpression[params.length=1][params.0.type="Identifier"][body.callee.name="setTimeout"][body.arguments.length=2][body.arguments.0.type="Identifier"]';
+export const preferDelay = createRule({
+    name: 'prefer-delay',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `delay` from es-toolkit over `new Promise` + `setTimeout`.',
+        },
+        schema: [],
+        messages: {
+            preferDelay: 'Prefer `delay` from es-toolkit instead of wrapping `setTimeout` in a `new Promise`.',
+        },
+    },
+    create(context) {
+        return {
+            [promisifiedTimeout](node) {
+                const [param] = node.params;
+                const { body } = node;
+                // Confirm the timeout callback IS the promise's own `resolve` (a pure delay).
+                if (body.type !== 'CallExpression')
+                    return;
+                const [callback] = body.arguments;
+                if (param.type === 'Identifier'
+                    && callback.type === 'Identifier'
+                    && param.name === callback.name) {
+                    context.report({ node: node.parent, messageId: 'preferDelay' });
+                }
+            },
+        };
+    },
+});

package/dist/rules/prefer-is-empty.d.ts

@@ -0,0 +1,3 @@
+export declare const preferIsEmpty: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferIsEmpty", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-is-empty.js

@@ -0,0 +1,24 @@
+import { createRule } from '../utils/create-rule.js';
+const objectKeysLength = (side) => `[${side}.property.name="length"][${side}.object.callee.object.name="Object"][${side}.object.callee.property.name="keys"]`;
+// `Object.keys(obj).length === 0`, in either operand order.
+const keysLengthZero = (zero, keys) => `BinaryExpression[operator=/^===?$/][${zero}.value=0]${objectKeysLength(keys)}`;
+export const preferIsEmpty = createRule({
+    name: 'prefer-is-empty',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `isEmpty` from es-toolkit over `Object.keys(obj).length === 0`.',
+        },
+        schema: [],
+        messages: {
+            preferIsEmpty: 'Prefer `isEmpty` from es-toolkit instead of `Object.keys(obj).length === 0`.',
+        },
+    },
+    create(context) {
+        const report = (node) => context.report({ node, messageId: 'preferIsEmpty' });
+        return {
+            [keysLengthZero('right', 'left')]: report,
+            [keysLengthZero('left', 'right')]: report,
+        };
+    },
+});

package/dist/rules/prefer-is-equal.d.ts

@@ -0,0 +1,3 @@
+export declare const preferIsEqual: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferIsEqual", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-is-equal.js

@@ -0,0 +1,22 @@
+import { createRule } from '../utils/create-rule.js';
+const stringify = (side) => `[${side}.callee.object.name="JSON"][${side}.callee.property.name="stringify"]`;
+// `JSON.stringify(a) === JSON.stringify(b)` (or `!==`) is a fragile deep-equality check.
+const stringifyComparison = `BinaryExpression[operator=/^[!=]==?$/]${stringify('left')}${stringify('right')}`;
+export const preferIsEqual = createRule({
+    name: 'prefer-is-equal',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `isEqual` from es-toolkit over comparing `JSON.stringify` results.',
+        },
+        schema: [],
+        messages: {
+            preferIsEqual: 'Prefer `isEqual` from es-toolkit instead of comparing `JSON.stringify` output.',
+        },
+    },
+    create(context) {
+        return {
+            [stringifyComparison]: (node) => context.report({ node, messageId: 'preferIsEqual' }),
+        };
+    },
+});

package/dist/rules/prefer-last.d.ts

@@ -0,0 +1,3 @@
+export declare const preferLast: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferLast", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-last.js

@@ -0,0 +1,21 @@
+import { createRule } from '../utils/create-rule.js';
+// `arr[arr.length - 1]`: a computed access whose index is `<something>.length - 1`.
+const lastIndex = 'MemberExpression[computed=true][property.operator="-"][property.right.value=1][property.left.property.name="length"]';
+export const preferLast = createRule({
+    name: 'prefer-last',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `last` from es-toolkit over `arr[arr.length - 1]`.',
+        },
+        schema: [],
+        messages: {
+            preferLast: 'Prefer `last` from es-toolkit instead of indexing with `arr.length - 1`.',
+        },
+    },
+    create(context) {
+        return {
+            [lastIndex]: (node) => context.report({ node, messageId: 'preferLast' }),
+        };
+    },
+});

package/dist/rules/prefer-random-int.d.ts

@@ -0,0 +1,3 @@
+export declare const preferRandomInt: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferRandomInt", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-random-int.js

@@ -0,0 +1,22 @@
+import { createRule } from '../utils/create-rule.js';
+const random = 'CallExpression[callee.object.name="Math"][callee.property.name="random"]';
+// `Math.floor(Math.random() * X)`. A `.length` multiplier is left to `prefer-sample`.
+const floorRandom = `CallExpression[callee.object.name="Math"][callee.property.name="floor"][arguments.length=1]:has(> BinaryExpression[operator="*"]:has(> ${random}):not(:has(> MemberExpression[property.name="length"])))`;
+export const preferRandomInt = createRule({
+    name: 'prefer-random-int',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `randomInt` from es-toolkit over `Math.floor(Math.random() * …)`.',
+        },
+        schema: [],
+        messages: {
+            preferRandomInt: 'Prefer `randomInt` from es-toolkit instead of `Math.floor(Math.random() * …)`.',
+        },
+    },
+    create(context) {
+        return {
+            [floorRandom]: (node) => context.report({ node, messageId: 'preferRandomInt' }),
+        };
+    },
+});

package/dist/rules/prefer-range.d.ts

@@ -0,0 +1,3 @@
+export declare const preferRange: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferRange", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-range.js

@@ -0,0 +1,37 @@
+import { createRule } from '../utils/create-rule.js';
+// `[...Array(n).keys()]` — a spread of the index iterator of a freshly sized array.
+const spreadArrayKeys = 'ArrayExpression[elements.length=1][elements.0.type="SpreadElement"][elements.0.argument.type="CallExpression"][elements.0.argument.callee.property.name="keys"][elements.0.argument.callee.object.callee.name="Array"]';
+// `Array.from({ length: n }, (_, i) => i)` — the mapper returning its index is verified below.
+const arrayFromLength = 'CallExpression[callee.object.name="Array"][callee.property.name="from"][arguments.length=2][arguments.0.type="ObjectExpression"][arguments.0.properties.0.key.name="length"][arguments.1.params.length=2][arguments.1.body.type="Identifier"]';
+export const preferRange = createRule({
+    name: 'prefer-range',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `range` from es-toolkit over manual index-array construction.',
+        },
+        schema: [],
+        messages: {
+            preferRange: 'Prefer `range` from es-toolkit instead of building an index array by hand.',
+        },
+    },
+    create(context) {
+        const report = (node) => context.report({ node, messageId: 'preferRange' });
+        return {
+            [spreadArrayKeys]: report,
+            [arrayFromLength](node) {
+                const mapper = node.arguments[1];
+                if (mapper.type !== 'ArrowFunctionExpression'
+                    && mapper.type !== 'FunctionExpression')
+                    return;
+                const index = mapper.params[1];
+                // Only a mapper that returns its own index parameter yields `range(n)`.
+                if (index?.type === 'Identifier'
+                    && mapper.body.type === 'Identifier'
+                    && mapper.body.name === index.name) {
+                    report(node);
+                }
+            },
+        };
+    },
+});

package/dist/rules/prefer-sample.d.ts

@@ -0,0 +1,3 @@
+export declare const preferSample: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferSample", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-sample.js

@@ -0,0 +1,21 @@
+import { createRule } from '../utils/create-rule.js';
+// `arr[Math.floor(Math.random() * arr.length)]` — a random index into an array's length.
+const randomIndex = 'MemberExpression[computed=true][property.callee.object.name="Math"][property.callee.property.name="floor"]:has(CallExpression[callee.object.name="Math"][callee.property.name="random"]):has(MemberExpression[property.name="length"])';
+export const preferSample = createRule({
+    name: 'prefer-sample',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `sample` from es-toolkit over random-index array access.',
+        },
+        schema: [],
+        messages: {
+            preferSample: 'Prefer `sample` from es-toolkit instead of indexing with a random index.',
+        },
+    },
+    create(context) {
+        return {
+            [randomIndex]: (node) => context.report({ node, messageId: 'preferSample' }),
+        };
+    },
+});

package/dist/rules/prefer-uniq.d.ts

@@ -0,0 +1,3 @@
+export declare const preferUniq: import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferUniq", readonly unknown[], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};

package/dist/rules/prefer-uniq.js

@@ -0,0 +1,25 @@
+import { createRule } from '../utils/create-rule.js';
+const set = 'NewExpression[callee.name="Set"][arguments.length=1]';
+// Both `[...new Set(arr)]` and `Array.from(new Set(arr))` deduplicate an array.
+const spreadSet = 'ArrayExpression[elements.length=1][elements.0.type="SpreadElement"][elements.0.argument.type="NewExpression"][elements.0.argument.callee.name="Set"][elements.0.argument.arguments.length=1]';
+const arrayFromSet = `CallExpression[callee.object.name="Array"][callee.property.name="from"][arguments.length=1]:has(> ${set})`;
+export const preferUniq = createRule({
+    name: 'prefer-uniq',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prefer `uniq` from es-toolkit over `new Set` round-trips.',
+        },
+        schema: [],
+        messages: {
+            preferUniq: 'Prefer `uniq` from es-toolkit instead of round-tripping through `new Set`.',
+        },
+    },
+    create(context) {
+        const report = (node) => context.report({ node, messageId: 'preferUniq' });
+        return {
+            [spreadSet]: report,
+            [arrayFromSet]: report,
+        };
+    },
+});

package/dist/utils/create-rule.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const createRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/utils/create-rule.js

@@ -0,0 +1,2 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export const createRule = ESLintUtils.RuleCreator(name => `https://github.com/syxov/es-toolkit-eslint-plugin/blob/main/docs/rules/${name}.md`);

package/docs/rules/prefer-clamp.md

@@ -0,0 +1,41 @@
+# prefer-clamp
+
+Prefer [`clamp`](https://es-toolkit.dev/reference/math/clamp.html) from es-toolkit over
+nested `Math.min`/`Math.max`.
+
+`clamp(value, minimum, maximum)` is exactly `Math.min(Math.max(value, minimum), maximum)`,
+so the nested form is more verbose and harder to read than the named utility.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — any two-bound clamp idiom where a `Math.min`
+call wraps a `Math.max` call (or vice versa) as a direct argument.
+
+### ❌ Incorrect
+
+```js
+Math.min(Math.max(value, lower), upper);
+Math.max(Math.min(value, upper), lower);
+Math.min(upper, Math.max(value, lower)); // argument order does not matter
+```
+
+### ✅ Correct
+
+```js
+import { clamp } from 'es-toolkit';
+
+clamp(value, lower, upper);
+
+// Not a clamp — left untouched:
+Math.min(a, b);
+Math.min(Math.min(a, b), c);
+```
+
+## Limitations
+
+- **Syntactic match.** `Math` is matched by name, so a shadowed local variable named
+  `Math` could produce a false positive. This is rare in practice.
+- **Two-bound form only.** The single-bound `Math.min(a, b)` / `Math.max(a, b)` form is
+  intentionally not reported — it is too common and ambiguous to flag reliably.
+- **No auto-fix by design.** The fix requires adding an `import { clamp } from 'es-toolkit'`
+  and choosing argument order, so the rule only reports.

package/docs/rules/prefer-compact.md

@@ -0,0 +1,38 @@
+# prefer-compact
+
+Prefer [`compact`](https://es-toolkit.dev/reference/array/compact.html) from es-toolkit
+over `.filter(Boolean)`.
+
+`compact(arr)` removes all falsy values (`false`, `null`, `0`, `''`, `undefined`, `NaN`) —
+exactly what `arr.filter(Boolean)` does, but named and (in TypeScript) better typed.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — a single-argument `.filter(Boolean)` call.
+
+### ❌ Incorrect
+
+```js
+arr.filter(Boolean);
+items.filter(Boolean).map(x => x.id);
+```
+
+### ✅ Correct
+
+```js
+import { compact } from 'es-toolkit';
+
+compact(arr);
+
+// Not a falsy filter — left untouched:
+arr.filter(x => x);
+arr.map(Boolean);
+```
+
+## Limitations
+
+- **Syntactic match.** A shadowed local `Boolean` could produce a false positive. This is
+  rare in practice.
+- **TypeScript bonus.** Beyond readability, `compact` narrows nullable element types, while
+  `filter(Boolean)` often leaves them un-narrowed.
+- **No auto-fix by design.** The fix requires adding an `import { compact } from 'es-toolkit'`.

package/docs/rules/prefer-delay.md

@@ -0,0 +1,42 @@
+# prefer-delay
+
+Prefer [`delay`](https://es-toolkit.dev/reference/promise/delay.html) from es-toolkit over
+wrapping `setTimeout` in a `new Promise`.
+
+`delay(ms)` returns a promise that resolves after `ms` milliseconds — the same thing as the
+hand-rolled `new Promise((resolve) => setTimeout(resolve, ms))` sleep idiom.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — a `new Promise` whose single-parameter
+executor immediately calls `setTimeout` with that same parameter as the callback.
+
+### ❌ Incorrect
+
+```js
+new Promise(resolve => setTimeout(resolve, 1000));
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+```
+
+### ✅ Correct
+
+```js
+import { delay } from 'es-toolkit';
+
+await delay(1000);
+
+// Not a pure delay — left untouched:
+new Promise(resolve => setTimeout(doWork, 1000)); // runs work, not just a delay
+new Promise(resolve => {
+  setTimeout(resolve, ms); // block-bodied executor, see Limitations
+});
+```
+
+## Limitations
+
+- **Expression-body executor only.** The block-bodied form
+  `new Promise((resolve) => { setTimeout(resolve, ms); })` and wrapped forms like
+  `setTimeout(() => resolve(), ms)` are not reported, to keep the rule precise.
+- **Identity-checked.** The rule reports only when `setTimeout`'s callback is the promise's
+  own `resolve` parameter, so `setTimeout(doWork, ms)` inside a `new Promise` is left alone.
+- **No auto-fix by design.** The fix requires adding an `import { delay } from 'es-toolkit'`.

package/docs/rules/prefer-is-empty.md

@@ -0,0 +1,40 @@
+# prefer-is-empty
+
+Prefer [`isEmpty`](https://es-toolkit.dev/reference/predicate/isEmpty.html) from es-toolkit
+over `Object.keys(obj).length === 0`.
+
+`isEmpty(obj)` answers "does this object have no own enumerable keys?" directly, without
+allocating an intermediate keys array.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — an equality comparison of
+`Object.keys(...).length` against `0`, in either operand order.
+
+### ❌ Incorrect
+
+```js
+Object.keys(obj).length === 0;
+0 === Object.keys(obj).length;
+```
+
+### ✅ Correct
+
+```js
+import { isEmpty } from 'es-toolkit';
+
+isEmpty(obj);
+
+// Not in scope — left untouched:
+Object.keys(obj).length === 1;
+Object.values(obj).length === 0;
+arr.length === 0;
+```
+
+## Limitations
+
+- **`Object.keys` only.** `Object.values(...)`/`Object.entries(...)` length checks and bare
+  `arr.length === 0` / `str.length === 0` are intentionally **not** flagged — they are too
+  common and clear to rewrite reliably.
+- **Syntactic match.** A shadowed local `Object` could produce a false positive.
+- **No auto-fix by design.** The fix requires adding an `import { isEmpty } from 'es-toolkit'`.

package/docs/rules/prefer-is-equal.md

@@ -0,0 +1,41 @@
+# prefer-is-equal
+
+Prefer [`isEqual`](https://es-toolkit.dev/reference/predicate/isEqual.html) from es-toolkit
+over comparing `JSON.stringify` output.
+
+Comparing `JSON.stringify(a) === JSON.stringify(b)` is a common but fragile deep-equality
+check: it depends on key order, silently drops `undefined`/functions, and throws on circular
+references. `isEqual(a, b)` performs a real structural comparison.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — an equality/inequality comparison whose both
+operands are `JSON.stringify(...)` calls.
+
+### ❌ Incorrect
+
+```js
+JSON.stringify(a) === JSON.stringify(b);
+JSON.stringify(x) !== JSON.stringify(y);
+```
+
+### ✅ Correct
+
+```js
+import { isEqual } from 'es-toolkit';
+
+isEqual(a, b);
+
+// Not a stringify-based comparison — left untouched:
+JSON.stringify(a) === b;
+JSON.parse(a) === JSON.parse(b);
+```
+
+## Limitations
+
+- **Both operands must be `JSON.stringify`.** Comparing one stringified value against
+  something else is not reported.
+- **Key-order caveat is the point.** `JSON.stringify` equality is order-sensitive and
+  lossy — that fragility is exactly why this rule flags it in favor of `isEqual`.
+- **No auto-fix by design.** The fix requires adding an `import { isEqual } from 'es-toolkit'`
+  (and inverting with `!` for the `!==` case).

package/docs/rules/prefer-last.md

@@ -0,0 +1,41 @@
+# prefer-last
+
+Prefer [`last`](https://es-toolkit.dev/reference/array/last.html) from es-toolkit over
+`arr[arr.length - 1]`.
+
+`last(arr)` reads as "the last element"; `arr[arr.length - 1]` repeats the array and forces
+the reader to compute the index.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — a computed member access whose index is
+`<something>.length - 1`.
+
+### ❌ Incorrect
+
+```js
+arr[arr.length - 1];
+items[items.length - 1];
+```
+
+### ✅ Correct
+
+```js
+import { last } from 'es-toolkit';
+
+last(arr);
+
+// Not a last-element access — left untouched:
+arr[arr.length - 2];
+arr[i - 1];
+arr.at(-1); // the native equivalent, also fine
+```
+
+## Limitations
+
+- **Object identity is not checked.** The selector matches the shape `a[b.length - 1]`, so
+  the rare case where the indexed array and the `.length` array differ would also be
+  reported.
+- **Native alternative.** `arr.at(-1)` is a concise built-in; this rule suggests es-toolkit's
+  `last` to keep call sites consistent with the rest of the toolkit.
+- **No auto-fix by design.** The fix requires adding an `import { last } from 'es-toolkit'`.

package/docs/rules/prefer-random-int.md

@@ -0,0 +1,43 @@
+# prefer-random-int
+
+Prefer [`randomInt`](https://es-toolkit.dev/reference/math/randomInt.html) from es-toolkit
+over `Math.floor(Math.random() * …)`.
+
+The `Math.floor(Math.random() * n)` family is the classic hand-rolled random-integer
+formula; `randomInt` names the intent and removes the off-by-one foot-guns.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — `Math.floor(...)` applied to a multiplication
+that contains `Math.random()`. A `.length` multiplier is left to
+[`prefer-sample`](./prefer-sample.md) instead.
+
+### ❌ Incorrect
+
+```js
+Math.floor(Math.random() * 6);
+Math.floor(Math.random() * (max - min + 1)) + min;
+```
+
+### ✅ Correct
+
+```js
+import { randomInt } from 'es-toolkit';
+
+randomInt(0, 6);
+
+// Not this rule's concern — left untouched:
+Math.random(); // a float in [0, 1)
+Math.round(Math.random() * n); // rounds, not floors
+arr[Math.floor(Math.random() * arr.length)]; // see prefer-sample
+```
+
+## Limitations
+
+- **Bounds differ.** The inclusive idiom `Math.floor(Math.random() * (max - min + 1)) + min`
+  yields `[min, max]`, whereas `randomInt(min, max)` yields `[min, max)`. Adjust the upper
+  bound when rewriting.
+- **`floor` only.** The `Math.round(...)` variant is not reported (it has a non-uniform
+  distribution and is a different intent).
+- **Syntactic match.** A shadowed local `Math` could produce a false positive.
+- **No auto-fix by design.** The fix requires adding an `import { randomInt } from 'es-toolkit'`.

package/docs/rules/prefer-range.md

@@ -0,0 +1,42 @@
+# prefer-range
+
+Prefer [`range`](https://es-toolkit.dev/reference/math/range.html) from es-toolkit over
+hand-built index arrays.
+
+`range(n)` produces `[0, 1, …, n - 1]`. The manual equivalents — `[...Array(n).keys()]` and
+`Array.from({ length: n }, (_, i) => i)` — are noisier ways to say the same thing.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — two index-array idioms:
+
+- `[...Array(n).keys()]`
+- `Array.from({ length: n }, (_, i) => i)` (a mapper that returns its own index)
+
+### ❌ Incorrect
+
+```js
+[...Array(n).keys()];
+Array.from({ length: n }, (_, i) => i);
+```
+
+### ✅ Correct
+
+```js
+import { range } from 'es-toolkit';
+
+range(n);
+
+// Not a plain index range — left untouched:
+Array.from({ length: n }); // array of holes, not 0…n-1
+Array.from({ length: n }, (_, i) => i * 2); // transformed → range(n).map(...)
+[...arr.keys()]; // keys of an existing array
+```
+
+## Limitations
+
+- **Identity-mapper only.** Only the mapper that returns its index parameter (→ `range(n)`)
+  is reported; transformed mappers and `range`'s `start`/`step` variants are not.
+- **Syntactic match.** A shadowed local `Array` could produce a false positive. This is
+  rare in practice.
+- **No auto-fix by design.** The fix requires adding an `import { range } from 'es-toolkit'`.

package/docs/rules/prefer-sample.md

@@ -0,0 +1,39 @@
+# prefer-sample
+
+Prefer [`sample`](https://es-toolkit.dev/reference/array/sample.html) from es-toolkit over
+random-index array access.
+
+`sample(arr)` returns a random element; `arr[Math.floor(Math.random() * arr.length)]` spells
+out the same idea by hand and repeats the array.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — a computed access whose index is
+`Math.floor(Math.random() * …length)`.
+
+### ❌ Incorrect
+
+```js
+arr[Math.floor(Math.random() * arr.length)];
+items[Math.floor(Math.random() * items.length)];
+```
+
+### ✅ Correct
+
+```js
+import { sample } from 'es-toolkit';
+
+sample(arr);
+
+// Not a random element pick — left untouched:
+arr[Math.floor(Math.random() * 3)]; // fixed range, see prefer-random-int
+arr[i];
+```
+
+## Limitations
+
+- **Object identity is not checked.** The selector matches `a[Math.floor(Math.random() *
+b.length)]`, so the rare case where the indexed array and the `.length` array differ would
+  also be reported.
+- **Syntactic match.** A shadowed local `Math` could produce a false positive.
+- **No auto-fix by design.** The fix requires adding an `import { sample } from 'es-toolkit'`.

package/docs/rules/prefer-uniq.md

@@ -0,0 +1,41 @@
+# prefer-uniq
+
+Prefer [`uniq`](https://es-toolkit.dev/reference/array/uniq.html) from es-toolkit over
+round-tripping an array through `new Set`.
+
+`[...new Set(arr)]` and `Array.from(new Set(arr))` exist only to deduplicate; `uniq(arr)`
+states that intent directly.
+
+## Rule details
+
+This rule reports — it does **not** auto-fix — an array literal spreading a single
+`new Set(x)`, or `Array.from(new Set(x))` with no mapper.
+
+### ❌ Incorrect
+
+```js
+[...new Set(arr)];
+Array.from(new Set(arr));
+```
+
+### ✅ Correct
+
+```js
+import { uniq } from 'es-toolkit';
+
+uniq(arr);
+
+// Not a dedupe round-trip — left untouched:
+new Set(arr);
+[...arr];
+Array.from(new Set(arr), x => x * 2); // a map, not plain uniq
+```
+
+## Limitations
+
+- **Syntactic match.** `Set`/`Array` are matched by name, so shadowed locals could produce
+  a false positive. This is rare in practice.
+- **Single-argument `Set` only.** `[...new Set()]` (empty) is not reported.
+- **`Array.from(set, mapFn)`** is intentionally skipped — the second argument transforms
+  the result, so it is not a plain `uniq`.
+- **No auto-fix by design.** The fix requires adding an `import { uniq } from 'es-toolkit'`.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "es-toolkit-eslint-plugin",
+  "version": "0.1.0",
+  "description": "ESLint plugin that suggests es-toolkit utilities in place of verbose JS/TS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "es-toolkit"
+  ],
+  "license": "MIT",
+  "author": "Aliaksandr Zasim",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syxov/es-toolkit-eslint-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/syxov/es-toolkit-eslint-plugin/issues"
+  },
+  "homepage": "https://github.com/syxov/es-toolkit-eslint-plugin#readme",
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "eslint": ">=10"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/rule-tester": "^8.0.0",
+    "eslint": "^10.0.0",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write . --experimental-cli --log-level=error",
+    "release": "pnpm publish --access public"
+  }
+}