feat(utilities): add omitKeysFromObject utility function (#700)

* feat(utilities): add omitKeysFromObject utility function

---------

Co-authored-by: Aura <[email protected]>

.eslintrc

@@ -12,6 +12,12 @@
 			"rules": {
 				"@typescript-eslint/member-ordering": "off"
 			}
+		},
+		{
+			"files": ["packages/utilities/src/lib/omitKeysFromObject.ts"],
+			"rules": {
+				"@typescript-eslint/ban-types": "off"
+			}
 		}
 	]
 }

packages/utilities/package.json

@@ -469,6 +469,16 @@
 				"default": "./dist/cjs/lib/objectValues.cjs"
 			}
 		},
+		"./omitKeysFromObject": {
+			"import": {
+				"types": "./dist/esm/lib/omitKeysFromObject.d.mts",
+				"default": "./dist/esm/lib/omitKeysFromObject.mjs"
+			},
+			"require": {
+				"types": "./dist/cjs/lib/omitKeysFromObject.d.ts",
+				"default": "./dist/cjs/lib/omitKeysFromObject.cjs"
+			}
+		},
 		"./parseURL": {
 			"import": {
 				"types": "./dist/esm/lib/tryParseURL.d.mts",

packages/utilities/src/index.ts

@@ -30,6 +30,7 @@ export * from './lib/objectEntries';
 export * from './lib/objectKeys';
 export * from './lib/objectToTuples';
 export * from './lib/objectValues';
+export * from './lib/omitKeysFromObject';
 export * from './lib/partition';
 export * from './lib/pickRandom';
 export * from './lib/poll';

packages/utilities/src/lib/omitKeysFromObject.ts

@@ -0,0 +1,24 @@
+import { deepClone } from './deepClone';
+
+/**
+ * Clones the source object using {@link deepClone} then deletes the specified keys with {@link Reflect.deleteProperty}
+ *
+ * @template TO - The object type.
+ * @template KTO - The keys of the object type.
+ *
+ * @param source - The input object.
+ * @param keys - The keys to omit from the object.
+ * @returns A new object without the specified keys.
+ */
+export function omitKeysFromObject<Object extends object, ObjectKeys extends keyof Object>(
+	source: Object,
+	...keys: readonly ObjectKeys[]
+): Omit<Object, ObjectKeys> {
+	const clone = deepClone(source);
+
+	for (const key of keys) {
+		Reflect.deleteProperty(clone, key);
+	}
+
+	return clone;
+}

packages/utilities/tests/omitKeysFromObject.test.ts

@@ -0,0 +1,55 @@
+import { omitKeysFromObject } from '../src/lib/omitKeysFromObject';
+
+describe('omitKeysFromObject', () => {
+	test('GIVEN object and keys THEN returns object without specified keys', () => {
+		const source = { name: 'John', age: 30, city: 'New York' };
+		const result = omitKeysFromObject(source, 'age', 'city');
+		expect(result).toEqual({ name: 'John' });
+	});
+
+	test('GIVEN object and no keys THEN returns the same object', () => {
+		const source = { name: 'John', age: 30, city: 'New York' };
+		const result = omitKeysFromObject(source);
+		expect(result).toEqual(source);
+	});
+
+	test('GIVEN empty object and keys THEN returns empty object', () => {
+		const source = {};
+		// @ts-expect-error Testing invalid input
+		const result = omitKeysFromObject(source, 'age', 'city');
+		expect(result).toEqual({});
+	});
+
+	test('GIVEN an object with ES objects THEN returns object without specified keys', () => {
+		const source = {
+			one: new Map(),
+			two: new Set(),
+			three: new Date(),
+			four: new Uint8Array(),
+			five: new Error(),
+			six: new RegExp(''),
+			seven: []
+		};
+		const result = omitKeysFromObject(source, 'one', 'two', 'three', 'four', 'five', 'six', 'seven');
+		expect(result).toEqual({});
+	});
+
+	test('GIVEN keys as array THEN removes keys', () => {
+		const source = { name: 'John', age: 30, city: 'New York' };
+		// @ts-expect-error spreading Arrays gives "string" instead of "keyof T"
+		const result = omitKeysFromObject(source, ...['age', 'city']);
+		expect(result).toEqual({ name: 'John' });
+	});
+
+	test("GIVEN any source object THEN validates that the result isn't identical to the source", () => {
+		const source = { name: 'John', age: 30, city: 'New York' };
+		const result = omitKeysFromObject(source);
+		expect(result).not.toBe(source);
+	});
+
+	test("GIVEN any source object THEN validates that the source isn't modified", () => {
+		const source = { name: 'John', age: 30, city: 'New York' };
+		omitKeysFromObject(source);
+		expect(source).toEqual({ name: 'John', age: 30, city: 'New York' });
+	});
+});