migrate

Lodash の移行と互換性ガイド

Lodash から es-toolkit への移行と、strict API と compat API の違いを、実際のソースコードに基づいてユーザーに案内します。

入力

$ARGUMENTS — 移行する Lodash コード、特定の関数名、または strict と compat に関する質問です。

主な概念

es-toolkit（strict）：利用ケースの 85％を想定した、独自の方針に基づくシンプルな API です。バンドルサイズは小さく、設計上、特殊なケースでは Lodash と動作が異なる場合があります。新しい関数はここに追加されます。

es-toolkit/compat：定められた範囲内で、Lodash のテストとの完全な互換性を目指します。対象外の動作（暗黙的な型変換、プロトタイプの変更など）については、docs/compatibility.md を参照してください。

ソースコードを最初に確認する理由

strict と compat の違いを確実に把握するには、ユーザーのプロジェクトにインストールされているバージョンを確認するしかありません。このスキルは単独のディレクトリとしてインストールされている場合があるため、es-toolkit のリポジトリや、同階層にある docs ディレクトリが利用できると決めつけないでください。

ワークフロー

特定の関数または Lodash コードが提示された場合

1. 入力から Lodash の関数を特定する

使用されている Lodash の関数と、そのインポート方法を抽出します。

2. インストール済みパッケージで利用可能か確認する

es-toolkit に依存しているパッケージのディレクトリから実行します。モノレポでは、通常、リポジトリのルートではなくワークスペースパッケージから実行します。プロジェクトが Yarn Plug'n'Play を使用している場合は、node の代わりに yarn node を使用します。

例の関数名を、入力で見つかった Lodash の関数に置き換えます。

node --input-type=module -e "
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const names = ['get', 'chunk', 'map'];
const pkg = require('es-toolkit/package.json');
const entries = Object.keys(pkg.exports)
  .filter(subpath => subpath !== './package.json' && !subpath.includes('*'))
  .map(subpath => subpath === '.' ? 'es-toolkit' : 'es-toolkit/' + subpath.slice(2));
const modules = await Promise.all(entries.map(entry => import(entry).catch(() => null)));
if (modules.every(module => module == null)) {
  console.error('es-toolkit is not resolvable from ' + process.cwd());
  process.exit(1);
}
for (const name of names) {
  const found = entries.filter((_, index) => modules[index] != null && name in modules[index]);
  console.log(name.padEnd(20), found.join(', ') || 'NOT AVAILABLE');
}
"

関数が複数のエントリーポイントに存在する場合があるため、結果を最後まで確認してください。es-toolkit/types は型専用であり、ランタイムインポートでは確認できません。

次のコマンドでパッケージのメタデータを解決してから、dist/ ディレクトリ内の宣言ファイルを読み、正確なシグネチャと JSDoc を確認します。従来型の node_modules パスにあると決めつけないでください。

node -e "console.log(require.resolve('es-toolkit/package.json'))"

現在のプロジェクトが es-toolkit のソースリポジトリ自体である場合は、ビルド済みパッケージを必要とせず、src/{category}/{fn}.ts、src/compat/{category}/{fn}.ts と、それぞれのテストを直接確認してください。

3. 適切な移行方法を判断する

シナリオ	推奨事項
関数が両方に存在し、動作も同じ	es-toolkit を使用します（バンドルサイズが小さくなります）
関数が両方に存在するが、動作が異なる	違いを説明し、ユーザーに選んでもらいます
compat のみに存在する	es-toolkit/compat を使用します
どちらにも存在しない	Lodash を使い続けるか、最新の JavaScript で代替する方法を提案します

関数が compat にしか存在しない場合（get、set、has など）は、その理由を説明してください。es-toolkit は、最新の JavaScript（オプショナルチェーン ?.、Object.hasOwn() など）で置き換えられる関数を実装していません。

4. 移行前後のコードを生成する

各関数について、以下を示してください。

• 利用可能な場所：es-toolkit および／または es-toolkit/compat
• ドキュメントへのリンク：https://es-toolkit.dev/reference/{category}/{fn}.html（strict）または https://es-toolkit.dev/compat/reference/{category}/{fn}.html（compat）
• 移行前（lodash）と移行後（es-toolkit）のコード例
• ソースコードで確認した動作上の違い
• 機能比較表：API の機能を並べて比較します（例：キャンセル対応、flush、maxWait、戻り値、AbortSignal、コールバックの引数）。両方の実装を確認し、対応するオプションをすべて特定して、次のような表にまとめてください。

機能	lodash	es-toolkit	es-toolkit/compat
（各オプション／機能を列挙）	✅/❌	✅/❌	✅/❌

• 「どれを使うべきか」：機能比較に基づき、状況に応じた指針を示してください。たとえば、「基本的な debounce だけが必要なら es-toolkit、cancel／flush に依存するなら compat、X が必要なら lodash を使い続けてください」のようにします。

多くの関数を移行する場合は、関数ごとにテンプレートを繰り返すのではなく、概要表を使用してください。

5. インポートの置き換えをまとめて提示する

最終的なインポート変換を、1 つのブロックにまとめて示してください。

5a. 大規模な移行に向けた自動化パターンを提案する

多くのファイルを移行する場合は、実用的な自動化方法を紹介してください。

• バンドラーのエイリアス：webpack または Vite の resolve.alias を設定し、ソースファイルを変更せずに、ビルド時に lodash のインポート先を置き換えます。

  // vite.config.js or webpack.config.js
  resolve: { alias: { 'lodash': 'es-toolkit/compat' } }
  

• ESLint ルール：no-restricted-imports を使って、移行後に残っている lodash のインポートに警告またはエラーを出します。
• Codemod：体系的な AST ベースの変換には、移行パターンが複雑な場合、jscodeshift などのツールを紹介します。

6. バンドルサイズへの影響を説明する

strict と compat のインポートはいずれもツリーシェイク可能であることを説明します。ただし、正確なサイズやパフォーマンスの数値を提示するのは、ユーザーのプロジェクトを計測した場合、または es-toolkit のソースチェックアウトにある最新のベンチマークデータを確認した場合に限ります。それ以外の場合は、公式のバンドルサイズとパフォーマンスのページにリンクしてください。

特定の関数がない場合（移行戦略の概要）

次の 3 つの移行方法を含む、戦略的な概要を提示してください。

• オプション A：es-toolkit に直接移行 — 新規または小規模なプロジェクト向け
• オプション B：compat を経由して段階的に移行 — 大規模なコードベース向け（レガシー環境では推奨）
• オプション C：併用 — 実用的なアプローチ

各オプションについて、トレードオフの比較表を含めてください。

要素	オプション A（strict）	オプション B（compat）	オプション C（併用）
コード変更量	大	小	中
バンドルサイズ削減	最大	中程度	変動
リスクレベル	高（動作の違い）	低（lodash と互換）	中
保守作業の負担	低（すっきりした API）	中（compat の追跡）	高（2 つの API）

compat 専用の関数：src/compat/ を検索して、src/（strict）には存在しない関数を探してください。compat からのみ利用できることがわかるよう、代表的な例を列挙してください（例：get、set、has）。

具体的な動作の違いについては、抽象的な説明ではなく、実際の例を示すために、代表的な関数の組み合わせ（例：chunk、debounce）をソースコードで確認してください。

ドキュメントへのリンク

• 移行の概要：https://es-toolkit.dev/compat/intro.html
• バンドルサイズ：https://es-toolkit.dev/bundle-size.html
• パフォーマンス：https://es-toolkit.dev/performance.html

関数のページには、次の形式を使用してください。

• strict：https://es-toolkit.dev/reference/{category}/{fn}.html
• compat：https://es-toolkit.dev/compat/reference/{category}/{fn}.html
• fp：https://es-toolkit.dev/fp/reference/{fn}.html

ページが存在するか確信がない場合は、推測してリンクを記載せず、省略してください。