feat: add Collection#subtract() (#8393)

* feat: add `Collection#missing()`

* test: add test for `Collection#missing()`

* chore: rename `missing` to `complement`

* docs: fix name

* test: fix test name

Co-authored-by: Almeida <almeidx@pm.me>

* chore: sort alphabetically

* fix: edit condition

Co-authored-by: Almeida <almeidx@pm.me>

* refactor: rename to `subtract`

* docs: fix description

Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>

* fix: change condition

* fix: resolved eslint formatting error

Co-authored-by: Almeida <almeidx@pm.me>
Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Co-authored-by: Aura Román <kyradiscord@gmail.com>

packages/collection/__tests__/collection.test.ts

@@ -3,17 +3,17 @@
 import { describe, test, expect } from 'vitest';
 import { Collection } from '../src/index.js';
 
-type TestCollection = Collection<string, number>;
+type TestCollection<V> = Collection<string, V>;
 
-function createCollection(): TestCollection {
+function createCollection<V = number>(): TestCollection<V> {
 	return new Collection();
 }
 
-function createCollectionFrom(...entries: [key: string, value: number][]): TestCollection {
+function createCollectionFrom<V = number>(...entries: [key: string, value: V][]): TestCollection<V> {
 	return new Collection(entries);
 }
 
-function createTestCollection(): TestCollection {
+function createTestCollection(): TestCollection<number> {
 	return createCollectionFrom(['a', 1], ['b', 2], ['c', 3]);
 }
 
@@ -770,6 +770,19 @@ describe('sort() tests', () => {
 	});
 });
 
+describe('subtract() tests', () => {
+	const coll1 = createCollectionFrom(['a', 1], ['b', 2], ['c', 3], ['d', undefined]);
+	const coll2 = createCollectionFrom(['b', 2], ['c', 0]);
+
+	test('it returns a new collection', () => {
+		const c = coll1.subtract(coll2);
+		expect(c).toBeInstanceOf(Collection);
+		expect(c.size).toStrictEqual(3);
+
+		expect(c).toStrictEqual(createCollectionFrom(['a', 1], ['c', 3], ['d', undefined]));
+	});
+});
+
 describe('sweep() test', () => {
 	const coll = createTestCollection();
 

packages/collection/src/collection.ts

@@ -684,6 +684,22 @@ export class Collection<K, V> extends Map<K, V> {
 		return coll;
 	}
 
+	/**
+	 * The subtract method returns a new structure containing items where the keys and values of the original structure are not present in the other.
+	 *
+	 * @param other - The other Collection to filter against
+	 */
+	public subtract<T>(other: ReadonlyCollection<K, T>): Collection<K, V> {
+		const coll = new this.constructor[Symbol.species]<K, V>();
+		for (const [k, v] of this) {
+			if (!other.has(k) || !Object.is(v, other.get(k))) {
+				coll.set(k, v);
+			}
+		}
+
+		return coll;
+	}
+
 	/**
 	 * The difference method returns a new structure containing items where the key is present in one of the original structures but not the other.
 	 *