feat: add union, intersection, and difference list utilities (#9)

Author: marchsabino

deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bytebury/toolkit",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"exports": "./mod.ts",
 	"tasks": {
 		"dev": "deno test --watch"

src/core.ts

@@ -382,8 +382,10 @@ export function inRange(value: number, min: number, max: number): boolean {
  * Splits an array into chunks of a fixed size.
  *
  * @example
+ * ```ts
  * chunk([1,2,3,4,5,6,7], 3); // [[1,2,3],[4,5,6],[7]]
  * chunk(['a','b','c','d'], 2); // [['a','b'], ['c','d']]
+ * ```
  */
 export function chunk<T>(arr: T[], size: number): T[][] {
   if (size <= 0) throw new Error("chunk size must be > 0");
@@ -394,3 +396,53 @@ export function chunk<T>(arr: T[], size: number): T[][] {
   }
   return result;
 }
+
+/**
+ * Returns the union of multiple arrays.
+ *
+ * @example
+ * ```ts
+ * union([1,2,3], [2,3,4]); // [1,2,3,4]
+ * union(['a','b','c'], ['b','c','d']); // ['a','b','c','d']
+ * ```
+ */
+export function union<T>(...lists: T[][]): T[] {
+  return [...new Set(lists.flat())];
+}
+
+/**
+ * Returns the difference of multiple arrays.
+ *
+ * @example
+ * ```ts
+ * difference([1,2,3], [2,3,4]); // [1]
+ * difference(['a','b','c'], ['b','c','d']); // ['a']
+ * ```
+ */
+export function difference<T>(...lists: T[][]): T[] {
+  const set = new Set(lists[0]);
+  for (const list of lists.slice(1)) {
+    for (const item of list) {
+      set.delete(item);
+    }
+  }
+  return Array.from(set);
+}
+
+/**
+ * Returns the intersection of multiple arrays.
+ *
+ * @example
+ * ```ts
+ * intersection([1,2,3], [2,3,4]); // [2,3]
+ * intersection(['a','b','c'], ['b','c','d']); // ['b','c']
+ * ```
+ */
+export function intersection<T>(...lists: T[][]): T[] {
+  if (lists.length === 0) return [];
+
+  return lists.reduce((acc, current) => {
+    const currentSet = new Set(current);
+    return acc.filter((item) => currentSet.has(item));
+  });
+}

src/core_test.ts

@@ -9,10 +9,12 @@ import {
 import {
   chunk,
   clone,
+  difference,
   distinct,
   falsy,
   first,
   inRange,
+  intersection,
   isEmpty,
   isEqual,
   isEqualIgnoreCase,
@@ -28,6 +30,7 @@ import {
   sample,
   stringify,
   truthy,
+  union,
   unique,
 } from "../src/core.ts";
 import type { NonEmptyList } from "./utility_types.ts";
@@ -308,3 +311,18 @@ Deno.test("chunk", () => {
   assertStrictEquals(chunk([1, 2, 3], 2)[0].length, 2);
   assertStrictEquals(chunk([1, 2, 3], 2)[1].length, 1);
 });
+
+Deno.test("difference", () => {
+  assertStrictEquals(difference([1, 2, 3], [2, 3, 4]).length, 1);
+  assertStrictEquals(difference(["a", "b", "c"], ["b", "c", "d"]).length, 1);
+});
+
+Deno.test("intersection", () => {
+  assertStrictEquals(intersection([1, 2, 3], [2, 3, 4]).length, 2);
+  assertStrictEquals(intersection(["a", "b", "c"], ["b", "c", "d"]).length, 2);
+});
+
+Deno.test("union", () => {
+  assertStrictEquals(union([1, 2, 3], [2, 3, 4]).length, 4);
+  assertStrictEquals(union(["a", "b", "c"], ["b", "c", "d"]).length, 4);
+});