es-toolkit の unionBy 完全ガイドmapper 関数による配列の和集合と重複除去を徹底解説【免费下载链接】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-toolkitunionByは、特定の関数mapperで変換した値を基準に、2 つの配列の「一意な要素」を含む新しい配列を作る es-toolkit の配列ユーティリティです。オブジェクト配列のidやcategoryなどの任意のキーを基準にした和集合を、元の並び順を保ったまま高速に求めることができます。本記事では、公式ドキュメントの使い方に加え、unionBy の実装 や uniqBy の内部処理、FP 版・lodash 互換版のソースコードまで掘り下げて解説します。unionBy とは何かunionByは es-toolkit が提供する配列関数で、2 つの配列を受け取り、mapper 関数が返す値が同じ要素を同一とみなして重複を除去した和集合を返します。単純な値の一致ではなく「変換後の値」で比較する点が最大の特徴で、オブジェクト配列を特定のプロパティで比較したい場合に特に有効です。const unified unionBy(arr1, arr2, mapper);入力arr1とarr2の 2 つの配列比較基準mapper関数が各要素から生成するキー出力重複が除かれた新しい配列元の配列は変更されません戻り値の要素の並びは、最初に出現した順序が維持されます。つまりarr1の要素が優先され、その後にarr2のうち新しい要素だけが追加されます。基本的な使い方オブジェクト配列を id でマージするmapper関数が返す値が同じであれば同一の要素として扱われるため、オブジェクト配列を特定のプロパティを基準に重複なく結合できます。import { unionBy } from es-toolkit/array; // idを基準にオブジェクトの和集合を求めます。 const users1 [ { id: 1, name: Alice }, { id: 2, name: Bob }, ]; const users2 [ { id: 2, name: Bob }, { id: 3, name: Charlie }, ]; unionBy(users1, users2, user user.id); // Returns: [{ id: 1, name: Alice }, { id: 2, name: Bob }, { id: 3, name: Charlie }]users2に含まれる{ id: 2, name: Bob }はusers1に既に存在するため除外され、新規の{ id: 3, name: Charlie }だけが追加されます。結果の並びはusers1の要素 → 新しい要素の順です。数値の余剰modを基準にした和集合mapper は単純なプロパティ参照だけでなく、任意の変換処理を書けます。たとえば数値を 3 で割った余りをキーにすると、次のようにすべての要素が「重複」と判定されます。import { unionBy } from es-toolkit/array; const nums1 [1, 2, 3]; const nums2 [4, 5, 6]; unionBy(nums1, nums2, x x % 3); // Returns: [1, 2, 3] // 1 % 3 1, 2 % 3 2, 3 % 3 0で、 // 4 % 3 1, 5 % 3 2, 6 % 3 0なので、すべて重複します。1と4、2と5、3と6はそれぞれ同じキー余りを生成するため、nums2側の要素はすべて捨てられ、[1, 2, 3]が返ります。複雑な基準カテゴリでの和集合カスタム比較関数を使えば、複合的な条件でも和集合を求められます。たとえば商品配列をcategoryで比較する場合、priceが異なっていても同じカテゴリなら同一とみなされます。import { unionBy } from es-toolkit/array; const products1 [ { category: electronics, price: 100 }, { category: books, price: 20 }, ]; const products2 [ { category: electronics, price: 150 }, { category: toys, price: 30 }, ]; // カテゴリを基準に和集合を求めます。 unionBy(products1, products2, product product.category); // Returns: [ // { category: electronics, price: 100 }, // { category: books, price: 20 }, // { category: toys, price: 30 } // ]products2のelectronicsprice: 150はproducts1のelectronicsprice: 100と同一キーになるため除外され、booksとtoysが追加された結果になります。先頭側の配列の要素が優先されるため、price が 100 の方が残る点に注目してください。パラメータと戻り値公式ドキュメントdocs/ja/reference/array/unionBy.mdに定義されたシグネチャは次のとおりです。パラメータ引数型説明arr1T[]結合する最初の配列arr2T[]結合する2番目の配列mapper(item: T) U各要素を比較する値に変換する関数戻り値型T[]内容mapper関数が返した値を基準に重複が除かれた、2 つの配列の和集合TypeScript のジェネリクスでは、Tが配列要素の型、Uが mapper が生成する比較キーの型に対応しますunionBy.ts の型定義。Uは数値・文字列・オブジェクトなど何でも構いません。内部実装uniqBy への委譲と Map による O(n) 処理実際の処理は非常にシンプルです。src/array/unionBy.ts の本体はわずか 1 行で、arr1とarr2を連結した後にuniqByへ委譲しています。export function unionByT, U(arr1: readonly T[], arr2: readonly T[], mapper: (item: T) U): T[] { return uniqBy(arr1.concat(arr2), mapper); }つまりunionBy(arr1, arr2, mapper)はuniqBy(arr1.concat(arr2), mapper)と完全に等価です。配列の結合にはconcatを使うため、元のarr1/arr2は変更されません。続く重複除去処理は src/array/uniqBy.ts で実装されています。ここではMapを使ってキーの存在判定を行っており、Setを含むあらゆるデータ構造をキーとして利用できるのがポイントです。export function uniqByT, U(arr: readonly T[], mapper: (item: T, index: number, array: readonly T[]) U): T[] { const map new MapU, T(); for (let i 0; i arr.length; i) { const item arr[i]; const key mapper(item, i, arr); if (!map.has(key)) { map.set(key, item); } } return Array.from(map.values()); }この実装から以下の性質が読み取れます。計算量は O(n)Map.has/Map.setが平均 O(1) のため、配列全体を一度走査するだけで済み、indexOfベースの O(n²) な実装より高速です。最初の出現が優先されるmap.has(key)が true になった時点で以降の要素はスキップされるため、「先に現れた要素が勝つ」というルールが自然に実現されます。SameValueZero 比較Mapのキー比較に従うため、NaN同士も同一として扱われ、0と-0も区別されません。ちなみに、uniqBy.ts の実装 では mapper に(item, index, array)の 3 引数が渡されます。一方、unionByの公開シグネチャでは(item: T) Uとして公開されていますが、実装上は内部のuniqByがインデックスと配列を追加で渡しているため、mapper 内でインデックスを使うことも可能です。テストで確認する動作仕様unionBy.spec.ts には、es-toolkit のユニットテストvitest 製が定義されています。describe(unionBy, () { it(should work with a mapper, () { expect(unionBy([2.1], [1.2, 2.3], Math.floor)).toEqual([2.1, 1.2]); expect(unionBy([{ x: 1 }], [{ x: 2 }, { x: 1 }], ({ x }) x)).toEqual([{ x: 1 }, { x: 2 }]); }); });このテストから、次の 2 つの保証が確認できます。Math.floorを mapper に渡すと、2.1と2.3が同じキー2になるため[2.1, 1.2]が返る数値の丸めによる重複除去。オブジェクトのプロパティxをキーにすると、重複する{ x: 1 }が 1 つにまとまる最初の要素{ x: 1 }が残る。FP 版カリー化された unionByes-toolkit には関数型プログラミング向けの FP 版も用意されています。src/fp/array/unionBy.ts では、引数の順序が入れ替わり、pipeと組み合わせて使える形になっています。import { pipe, unionBy } from es-toolkit/fp; pipe([{ id: 1 }], unionBy([{ id: 1 }, { id: 2 }], item item.id)); // [{ id: 1 }, { id: 2 }]FP 版のシグネチャはunionBy(secondArray, mapper)で、「パイプされた配列」とsecondArrayの和集合を返す関数を生成します。パイプされた配列の要素がsecondArrayより優先される点は通常版と同じですFP 版の実装 が通常版のunionByToolkitを呼び出しているのが確認できます。lodash 互換版複数配列と文字列・部分オブジェクト指定さらに、src/compat/array/unionBy.ts には lodash 互換のunionByも存在します。こちらは通常版と異なり、3 つ以上の配列を渡せ、iteratee として文字列プロパティ名や部分オブジェクトも指定できます。// プロパティ名を直接指定lodash と同じ書き方 unionBy([{ x: 1 }], [{ x: 2 }, { x: 1 }], x); // [{ x: 1 }, { x: 2 }] // 3 つの配列を扱う unionBy([2.1], [1.2, 2.3], [3.4], [4.5], Math.floor); // [2.1, 1.2, 3.4, 4.5]互換版の実装では、渡された配列をflattenArrayLikeで連結した後にuniqByへ渡し、iteratee はiteratee()とary()で正規化されますsrc/compat/array/unionBy.ts。lodash からの移行を検討している場合は、この互換版を使うことで既存コードをほぼそのまま維持できます。関連関数との使い分け関数特徴使いどころunionBy2 つの配列を mapper 基準で重複除去して結合オブジェクト配列を特定キーでマージしたいときunion2 つの配列を値そのもので重複除去して結合プリミティブ値のみでよいときuniqBy1 つの配列内の重複を mapper 基準で除去単一配列の重複だけを除去したいときuniq1 つの配列内の重複を値そのもので除去単一配列のプリミティブ重複除去unionBy(arr1, arr2, mapper)はuniqBy(arr1.concat(arr2), mapper)と等価です。2 つ以上の配列を扱う場合や、プロパティ名の文字列指定・部分オブジェクト指定が必要な場合は、compat 版の unionBy を検討してください。なお、これらの関数はすべて src/array/index.ts からes-toolkit/arrayとして一括エクスポートされているため、import { unionBy } from es-toolkit/array;の 1 行で利用開始できます。まとめunionByは、mapper 関数による「変換後の値」を比較キーとして 2 つの配列の和集合を返す、es-toolkit の中でも実用性の高い配列ユーティリティです。シグネチャunionBy(arr1, arr2, mapper)→T[]内部実装uniqBy(arr1.concat(arr2), mapper)への委譲。Mapによる O(n) の重複除去と「最初の出現優先」を保証応用es-toolkit/fpからはカリー化版、es-toolkit/compatからは lodash 互換の複数配列版文字列・部分オブジェクト iteratee 対応が利用可能参考実装src/array/unionBy.ts / src/array/uniqBy.ts / unionBy.spec.tsAPI の詳細は公式ドキュメント docs/ja/reference/array/unionBy.md を、最新の動作仕様は src/array/unionBy.spec.ts を確認してください。【免费下载链接】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），仅供参考