es-toolkit/compat 完全ガイドLodash から es-toolkit への段階的移行と 100% 互換性の仕組み【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkites-toolkit/compatは、Lodash 配下の実装コードと照らし合わせながら解説します。読了後には、既存プロジェクトで Lodash 依存を安全に剥がし、バンドルサイズと実行速度の両面で改善する実践手順を組み立てられるようになります。es-toolkit/compat とはes-toolkit/compatは、Lodash と同じインターフェースと動作を提供するモジュールです。Lodash を使っている既存のコードをそのままにしたまま、少しずつes-toolkitへ移行できるように作られています。// lodash と同じ呼び出しの形を es-toolkit/compat でそのまま使えます import { chunk } from es-toolkit/compat; chunk([1, 2, 3, 4], 0); // [] を返します。lodash と同じです。新しいプロジェクトでこれから導入する場合や、既存プロジェクトで Lodash を使っていない場合は、es-toolkit本体の利用が推奨されます。compat はあくまで「すでに Lodash に依存しているコード」を対象とした移行経路です。v1.39.3 から Lodash と 100% の互換性を保証::: tip ✅ 1.39.3 から Lodash と 100% の互換性を保証しています Lodash 自身のテストコードをそのまま通過します。動作は同じまま、より軽く高速です。 :::この互換性保証は、公式ドキュメントに明記されている通り、Lodash 本体のテストスイートをそのまま通過することで裏付けられています。es-toolkit 側のテスト基盤にもこの思想が反映されており、package.jsonのtransformスクリプトjscodeshift -t ./.scripts/tests/transform-lodash-test.tsによって Lodash 由来のテストコードを変換・実行する仕組みが整備されています。マイグレーションの流れ既存のコードから Lodash を取り除くときは、次の 2 段階の流れが推奨されています。lodash/lodash-esの import パスをes-toolkit/compatに変える。呼び出し側のコードはそのままでよい。時間をかけて呼び出し側を整理しつつ、import をes-toolkitに切り替える。すべて移行できれば、バンドルがより小さく、より高速になる。この 2 段階方式の利点は、一度にすべての呼び出しを書き換える必要がないことです。まず import の差し替えだけで「Lodash 依存」を「es-toolkit/compat 依存」に置き換え、その後の通常の開発フローの中で関数単位・モジュール単位で型安全なes-toolkit本体へ置き換えていく、という漸進的移行が可能になります。移行の完了形compat から es-toolkit 本体へes-toolkit/compatは Lodash と 1:1 の API 形状を持つため、移行が進むと「もう compat の互換挙動すら不要」なコードが増えてきます。その時点で本体 API への切り替えを行います。このとき、compat にしか存在しない非推奨関数も一緒に整理対象となります後述の「es-toolkitとの違い」を参照。関数を個別にインポートするlodash/mergeと同じように、compat のすべての関数は関数ごとのエントリーポイントからもインポートできます。es-toolkit/compat全体ではなく、その関数に必要なファイルだけが読み込まれます。import merge from es-toolkit/compat/merge;これは、ツリーシェイキングが使えない環境で特に役立ちます。具体的には次のようなケースです。CommonJS のrequire()呼び出しReact Nativeバンドラーなしで Node.js 上で直接実行するコードconst merge require(es-toolkit/compat/merge);パッケージ exports から見るエントリーポイント設計個別インポートはpackage.jsonのexportsフィールドで正式に宣言されています。./compat/*エントリに対して、import 時は./compat/*.mjsと型定義./compat/*.d.mtsが、require 時は./compat/*.jsと型定義./compat/*.d.tsが解決される構成です。このため、ESM と CommonJS のどちらの環境でも、es-toolkit/compat/mergeのようなパスで単一関数だけを取り込むことが保証されています。なお、ルートの./compatエントリsrc/compat/index.tsは、配下の compat.ts をexport *で再エクスポートし、さらに toolkit.ts で定義されたtoolkitオブジェクトをdefaultとして公開します。export * from ./compat.ts; export { toolkit as default } from ./toolkit.ts;toolkitは関数オブジェクトに compat の全関数をObject.assignしたもので、Lodash の_(value)呼び出しに相当するエントリポイントです。partial/partialRightにはplaceholderプロパティも設定されていますtoolkit.ts。es-toolkitとの違いcompat と本体の違いは、以下の 3 点に整理されています。API の形Lodash と 1:1 で一致しています。暗黙的な型変換、さまざまな引数の形、非推奨のヘルパーまでそのまま含まれます。es-toolkitは型安全で整理された形だけを提供します。バンドルサイズと速度es-toolkitより少し大きく、少し遅いです。Lodash と動作を合わせるための追加処理が入っているためです。非推奨の関数Lodash で非推奨になった関数も互換性のためにcompatには残っていますが、es-toolkitには含まれません。マイグレーション中に一緒に整理してください。つまり compat は「互換性」を、本体は「モダンで型安全な API」をそれぞれ最優先しており、この使い分けが移行の設計思想そのものです。関数ごとの詳細なドキュメントは互換性リファレンスを参照してください。リファレンスはカテゴリごとに分冊されており、docs/ja/compat/reference/array 以下の各関数ページから実装状況や使用例を確認できます。設計原則::: infoes-toolkit/compatの設計原則の方向性は変わる可能性があります。 :::対象とする機能100% の機能一致を目指す範囲es-toolkit/compatは、次の機能についてlodashと 100% 同じ機能を提供することを目指しています。lodashのテストケースとして書かれている機能types/lodashまたはtypes/lodash-esの型から推測できる機能lodashからes-toolkitへコードをマイグレーションする際に見つかった機能の違いIssues ページに報告してください対象外の機能意図的に含めない仕様一方、以下はes-toolkit/compatの対象外です。暗黙的な型変換空文字列を 0 または false に変換するような動作特殊なケースに最適化された実装sortedUniq のように、ソートされた配列だけを受け取る関数Array.prototypeのような組み込みオブジェクトのプロトタイプが変更されたケースへの対応JavaScript Realm への対応メソッドチェーン_(arr).map(...).filter(...)のようなメソッドチェーンこの「対象外」の設計は、src/compat/index.ts のモジュールドキュメントにも明記されています。とくに暗黙的な型変換空文字列を 0 や false に変換する等は「安全でない機能」として意図的に省略され、compatが「Lodash の振る舞いを 100% 模倣する」ことと「危険な仕様まで再現しない」ことを両立させています。また、対象外の関数がソース上もコメントアウトされていることは、実装状況の裏付けとして確認できます。例えば compat.ts では、ソート済み配列専用のsortedUniq/sortedUniqByがコメントアウトされた状態で残されています。ソースコードで確認する compat の実装スタイルcompat の関数は、本体実装をラップしつつ Lodash 特有のエッジケースを吸収する構造になっています。代表例として chunk の実装を見てみましょう。export function chunkT(arr: ArrayLikeT | null | undefined, size 1): T[][] { size Math.max(Math.floor(size), 0); if (size 0 || !isArrayLike(arr) || Number.isNaN(size)) { return []; } const array toArray(arr); if (array.length 0) { return []; } if (!isFinite(size)) { return [array]; } return chunkToolkit(array, size); }ここから読み取れる compat の実装方針は次の通りです。本体の再利用実際の分割処理は../../array/chunk.ts本体のchunkに委譲し、compat 側は引数の正規化だけを担当します。バンドルサイズの増加を抑える工夫です。Lodash との挙動一致size 0で[]を返す、sizeがNaNなら[]、Infinityなら配列全体を 1 つにまとめて返す、null/undefined/ 配列ライクでない値は[]を返す、といった Lodash のエッジケースをすべて再現しています。内部ヘルパーの活用isArrayLikeやtoArrayは src/compat/_internal に置かれた compat 専用の内部ヘルパーで、Lodash 互換の判定・変換を行います。同様に merge は、本体のmergeWithを内部で呼び出す多重定義オーバーロード付きの関数として実装されており、可変長のソースオブジェクトを受け取る Lodash の呼び出し形に対応しています。また compat が公開する関数は 300 近くにのぼり、compat.ts で一括再エクスポートされています。カテゴリは以下の通りです。arraychunk、difference、groupBy、orderBy、pull、sortedIndex系、union、uniq、zip系などfunctiondebounce、throttle、curry、flow、memoize、once、partial系などmathadd、clamp、inRange、random、range、sum系などobjectassign系、clone系、defaults系、get、merge系、omit、pick、set系などpredicateisArray、isEqual、isMatch系、isNil、isPlainObjectなどstringcamelCase、kebabCase、snakeCase、template、trim系、wordsなどutildefaultTo、iteratee、times、toNumber、uniqueIdなど実装状況::: info 以下の絵文字で、各機能の現在の状態を表しています。✅: 完了実装されており、lodash のテストコードをすべて通過しています: レビュー中実装されていますが、lodash のテストコードでテストされていません❌: 未実装「レビュー中」と書かれていても、すでに lodash と 100% 同じ機能を提供している場合があります。 :::実装状況の詳細は、compat の導入ページに埋め込まれたCompatibilityStatus langja/コンポーネントVitePress の動的コンポーネントで確認できます。このコンポーネントは、docs/ja/compat/reference 以下の関数別リファレンスの存在と整合する形で、各関数のステータスを一覧表示します。ステータス確認時の実務的な指針は次の通りです。✅ の関数は、Lodash のテストコードをそのまま通過しているため、lodashからes-toolkit/compatへの import 差し替えがそのまま安全に行えます。 の関数は実装済みですが Lodash のテストコードでの検証が未実施のため、移行時には当該関数の挙動を既存テストで確認すると安心です。❌ の関数は未実装のため、es-toolkit/compatへの差し替え対象外です。該当する関数がコードベースに残っている場合は、移行計画に含める必要があります。まとめcompat を活用した移行の実践ポイント本記事で見てきた内容を実践に落とし込む際の要点は、次の 3 つです。まず import パスの差し替えだけを行うlodash/lodash-es→es-toolkit/compatの置換は、呼び出し側コードを一切変更せずに実行できます。ツリーシェイキングが効かない環境CommonJS、React Native、バンドラーなしの Node.jsでは、es-toolkit/compat/merge形式の関数別エントリポイントを利用します。互換レイヤーはあくまで中間地点compat は本体よりわずかに大きく遅く、非推奨関数も含みます。移行の最終目標はes-toolkit本体への切り替えであり、compat はそのための安全な足場です。対象外仕様を事前に把握する暗黙的な型変換やメソッドチェーン、sortedUniqのような特殊実装は compat の対象外です。移行前にコードベース内でこれらの利用箇所を洗い出しておくことで、移行途中の挙動差分を防げます。互換性の裏付けは、Lodash のテストスイート通過v1.39.3 以降の公式保証と、src/compat 配下の実装コードの両方から確認できます。既存の Lodash 依存に悩んでいるプロジェクトは、まず import パスの差し替えから始めてみてください。【免费下载链接】es-toolkitA modern JavaScript utility library thats 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考