feat(array):

- added new differenceBy utility

README.md

@@ -6,7 +6,7 @@
 
 TypeLegend is a versatile and typesafe utility library designed to simplify common tasks in your TypeScript projects. With TypeLegend, you can harness the power of TypeScript's strong typing system to write safer and more maintainable code.
 
-- Total amount of typesafe utility functions: **92**
+- Total amount of typesafe utility functions: **93**
 - Total amount of typesafe utility classes: **9**
 
 ## Features

USAGE.md

@@ -15,6 +15,7 @@ Here are some of the utility functions and classes available in this library:
   - [diff](#diff)
   - [sample](#sample)
   - [intersect](#intersect)
+  - [differenceBy](#differenceby)
   - [zip](#zip)
   - [shuffle](#shuffle)
   - [chunk](#chunk)
@@ -211,6 +212,22 @@ the following utility functions are available in the `ArrayUtils` class, they ca
 ```
 
 
+### differenceBy
+```typescript
+/**
+ * Returns an array of values from `arr` that are not present in `values`,
+ * based on the result of applying `iteratee` function to each value.
+ *
+ * @template T The type of elements in the input array.
+ * @template U The type of elements returned by the `iteratee` function.
+ * @param  arr The input array to compare against.
+ * @param  values The array of values to exclude from the result.
+ * @param  iteratee The function to transform each value before comparison.
+ * @returns  An array of values from `arr` that are not present in `values`.
+*/
+```
+
+
 ### zip
 ```typescript
 /**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "typelegend",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "module": "dist/index.mjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/array/differenceBy.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns an array of values from `arr` that are not present in `values`,
+ * based on the result of applying `iteratee` function to each value.
+ *
+ * @template T The type of elements in the input array.
+ * @template U The type of elements returned by the `iteratee` function.
+ * @param {T[]} arr The input array to compare against.
+ * @param {T[]} values The array of values to exclude from the result.
+ * @param {(value: T) => U} iteratee The function to transform each value before comparison.
+ * @returns {T[]} An array of values from `arr` that are not present in `values`.
+ */
+export function differenceBy<T, U>(
+	arr: T[],
+	values: T[],
+	iteratee: (value: T) => U,
+): T[] {
+	const set = new Set(values.map(iteratee));
+	return arr.filter((a) => !set.has(iteratee(a)));
+}

src/array/index.ts

@@ -3,6 +3,7 @@ import { union } from "./union";
 import { diff } from "./diff";
 import { sample } from "./sample";
 import { intersect } from "./intersect";
+import { differenceBy } from "./differenceBy";
 import { zip } from "./zip";
 import { shuffle } from "./shuffle";
 import { chunk } from "./chunk";
@@ -18,6 +19,7 @@ export class ArrayUtils {
   static diff: typeof diff = diff;
   static sample: typeof sample = sample;
   static intersect: typeof intersect = intersect;
+  static differenceBy: typeof differenceBy = differenceBy;
   static zip: typeof zip = zip;
   static shuffle: typeof shuffle = shuffle;
   static chunk: typeof chunk = chunk;
@@ -33,6 +35,7 @@ export { union } from "./union";
 export { diff } from "./diff";
 export { sample } from "./sample";
 export { intersect } from "./intersect";
+export { differenceBy } from "./differenceBy";
 export { zip } from "./zip";
 export { shuffle } from "./shuffle";
 export { chunk } from "./chunk";

test/array/differenceBy.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { differenceBy } from "../../src/array/differenceBy";
+
+describe("differenceBy", () => {
+	it("should return an array of values from `arr` that are not present in `values` based on the result of applying `iteratee` function", () => {
+		const arr = [1, 2, 3, 4, 5];
+		const values = [2, 4, 6];
+		const iteratee = (value: number) => value % 2;
+		const expected = [1, 3, 5];
+		expect(differenceBy(arr, values, iteratee)).toEqual(expected);
+	});
+
+	it("should return an empty array if `arr` is empty", () => {
+		const arr: number[] = [];
+		const values = [2, 4, 6];
+		const iteratee = (value: number) => value % 2;
+		const expected: number[] = [];
+		expect(differenceBy(arr, values, iteratee)).toEqual(expected);
+	});
+
+	it("should return `arr` if `values` is empty", () => {
+		const arr = [1, 2, 3, 4, 5];
+		const values: number[] = [];
+		const iteratee = (value: number) => value % 2;
+		const expected = [1, 2, 3, 4, 5];
+		expect(differenceBy(arr, values, iteratee)).toEqual(expected);
+	});
+
+	it("should return an empty array if `arr` and `values` are empty", () => {
+		const arr: number[] = [];
+		const values: number[] = [];
+		const iteratee = (value: number) => value % 2;
+		const expected: number[] = [];
+		expect(differenceBy(arr, values, iteratee)).toEqual(expected);
+	});
+});