feat: add Collection#ensure

__tests__/collection.test.ts

@@ -435,3 +435,35 @@ describe('random thisArg tests', () => {
 		}, array);
 	});
 });
+
+describe('ensure() tests', () => {
+	function createTestCollection() {
+		return new Collection([
+			['a', 1],
+			['b', 2],
+		]);
+	}
+
+	test('set new value if key does not exist', () => {
+		const coll = createTestCollection();
+		coll.ensure('c', () => 3);
+		expect(coll.size).toStrictEqual(3);
+		expect(coll.get('c')).toStrictEqual(3);
+	});
+
+	test('return existing value if key exists', () => {
+		const coll = createTestCollection();
+		const ensureB = coll.ensure('b', () => 3);
+		const getB = coll.get('b');
+		expect(ensureB).toStrictEqual(2);
+		expect(getB).toStrictEqual(2);
+		expect(coll.size).toStrictEqual(2);
+	});
+
+	test('ensure with existing key should not change the collection', () => {
+		const coll = createTestCollection();
+		coll.ensure('a', () => 4);
+		expect(coll.size).toStrictEqual(2);
+		expect(coll.get('a')).toStrictEqual(1);
+	});
+});

src/index.ts

@@ -25,6 +25,24 @@ export interface Collection<K, V> extends Map<K, V> {
 export class Collection<K, V> extends Map<K, V> {
 	public static readonly default: typeof Collection = Collection;
 
+	/**
+	 * Obtains an element if the key exists, otherwise sets and returns the value provided by the default value generator.
+	 *
+	 * @param {*} key - The key to get from if it exists or set otherwise
+	 * @param {Function} defaultValueGenerator - A function that returns the ensured value
+	 *
+	 * @returns The existing value if any, otherwise the value provided by the default value generator.
+	 *
+	 * @example
+	 * collection.ensure(guildId, () => defaultGuildConfig);
+	 */
+	public ensure(key: K, defaultValueGenerator: (key: K, collection: this) => V): V | undefined {
+		if (this.has(key)) return this.get(key);
+		const defaultValue = defaultValueGenerator(key, this);
+		this.set(key, defaultValue);
+		return defaultValue;
+	}
+
 	/**
 	 * Checks if all of the elements exist in the collection.
 	 *