Merge pull request #46 from robonen/object-utils

Object utils

packages/stdlib/src/arrays/cluster/index.test.ts

@@ -4,31 +4,37 @@ import { cluster } from '.';
 describe('cluster', () => {
   it('cluster an array into subarrays of a specific size', () => {
     const result = cluster([1, 2, 3, 4, 5, 6, 7, 8], 3);
+
     expect(result).toEqual([[1, 2, 3], [4, 5, 6], [7, 8]]);
   });
 
   it('handle arrays that are not perfectly divisible by the size', () => {
     const result = cluster([1, 2, 3, 4, 5], 2);
+
     expect(result).toEqual([[1, 2], [3, 4], [5]]);
   });
 
   it('return an array with each element in its own subarray if size is 1', () => {
     const result = cluster([1, 2, 3, 4], 1);
+
     expect(result).toEqual([[1], [2], [3], [4]]);
   });
 
   it('return an array with a single subarray if size is greater than the array length', () => {
     const result = cluster([1, 2, 3], 5);
+
     expect(result).toEqual([[1, 2, 3]]);
   });
 
   it('return an empty array if size is less than or equal to 0', () => {
     const result = cluster([1, 2, 3, 4], -1);
+
     expect(result).toEqual([]);
   });
 
   it('return an empty array if the input array is empty', () => {
     const result = cluster([], 3);
+    
     expect(result).toEqual([]);
   });
 });

packages/stdlib/src/arrays/sum/index.test.ts

@@ -4,36 +4,43 @@ import { sum } from '.';
 describe('sum', () => {
   it('return the sum of all elements in a number array', () => {
     const result = sum([1, 2, 3, 4, 5]);
+
     expect(result).toBe(15);
   });
 
   it('return 0 for an empty array', () => {
     const result = sum([]);
+
     expect(result).toBe(0);
   });
 
   it('return the sum of all elements using a getValue function', () => {
     const result = sum([{ value: 1 }, { value: 2 }, { value: 3 }], (item) => item.value);
+
     expect(result).toBe(6);
   });
 
   it('handle arrays with negative numbers', () => {
     const result = sum([-1, -2, -3, -4, -5]);
+
     expect(result).toBe(-15);
   });
 
   it('handle arrays with mixed positive and negative numbers', () => {
     const result = sum([1, -2, 3, -4, 5]);
+
     expect(result).toBe(3);
   });
 
   it('handle arrays with floating point numbers', () => {
     const result = sum([1.5, 2.5, 3.5]);
+
     expect(result).toBe(7.5);
   });
 
   it('handle arrays with a getValue function returning floating point numbers', () => {
     const result = sum([{ value: 1.5 }, { value: 2.5 }, { value: 3.5 }], (item) => item.value);
+    
     expect(result).toBe(7.5);
   });
 });

packages/stdlib/src/arrays/unique/index.test.ts

@@ -4,6 +4,7 @@ import { unique } from '.';
 describe('unique', () => {
   it('return an array with unique numbers', () => {
     const result = unique([1, 2, 3, 3, 4, 5, 5, 6]);
+
     expect(result).toEqual([1, 2, 3, 4, 5, 6]);
   });
 
@@ -12,16 +13,19 @@ describe('unique', () => {
       [{ id: 1 }, { id: 2 }, { id: 1 }],
       (item) => item.id,
     );
+
     expect(result).toEqual([{ id: 1 }, { id: 2 }]);
   });
 
   it('return the same array if all elements are unique', () => {
     const result = unique([1, 2, 3, 4, 5]);
+
     expect(result).toEqual([1, 2, 3, 4, 5]);
   });
 
   it('handle arrays with different types of values', () => {
     const result = unique([1, '1', 2, '2', 2, 3, '3']);
+
     expect(result).toEqual([1, '1', 2, '2', 3, '3']);
   });
 
@@ -29,11 +33,13 @@ describe('unique', () => {
     const sym1 = Symbol('a');
     const sym2 = Symbol('b');
     const result = unique([sym1, sym2, sym1]);
+    
     expect(result).toEqual([sym1, sym2]);
   });
 
   it('return an empty array when given an empty array', () => {
     const result = unique([]);
+
     expect(result).toEqual([]);
   });
 });

packages/stdlib/src/index.ts

@@ -2,6 +2,7 @@ export * from './arrays';
 export * from './async';
 export * from './bits';
 export * from './math';
+export * from './objects';
 export * from './patterns';
 export * from './structs';
 export * from './text';

packages/stdlib/src/objects/index.ts

@@ -0,0 +1,2 @@
+export * from './omit';
+export * from './pick';

packages/stdlib/src/objects/omit/index.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { omit } from '.';
+
+describe('omit', () => {
+  it('omit a single key from the object', () => {
+    const result = omit({ a: 1, b: 2, c: 3 }, 'a');
+
+    expect(result).toEqual({ b: 2, c: 3 });
+  });
+
+  it('omit multiple keys from the object', () => {
+    const result = omit({ a: 1, b: 2, c: 3 }, ['a', 'b']);
+
+    expect(result).toEqual({ c: 3 });
+  });
+
+  it('return the same object if no keys are omitted', () => {
+    const result = omit({ a: 1, b: 2, c: 3 }, []);
+
+    expect(result).toEqual({ a: 1, b: 2, c: 3 });
+  });
+
+  it('not modify the original object', () => {
+    const obj = { a: 1, b: 2, c: 3 };
+    const result = omit(obj, 'a');
+
+    expect(obj).toEqual({ a: 1, b: 2, c: 3 });
+    expect(result).toEqual({ b: 2, c: 3 });
+  });
+
+  it('handle an empty object', () => {
+    const result = omit({}, 'a' as any);
+
+    expect(result).toEqual({});
+  });
+
+  it('handle non-existent keys gracefully', () => {
+    const result = omit({ a: 1, b: 2, c: 3 } as Record<string, number>, 'd');
+
+    expect(result).toEqual({ a: 1, b: 2, c: 3 });
+  });
+
+  it('handle null gracefully', () => {
+    const emptyTarget = omit(null as any, 'a');
+    const emptyKeys = omit({ a: 1 }, null as any);
+
+    expect(emptyTarget).toEqual({});
+    expect(emptyKeys).toEqual({ a: 1 });
+  });
+});

packages/stdlib/src/objects/omit/index.ts

@@ -0,0 +1,38 @@
+import { isArray, type Arrayable } from '../../types';
+
+/**
+ * @name omit
+ * @category Objects
+ * @description Returns a new object with the specified keys omitted
+ * 
+ * @param {object} target - The object to omit keys from
+ * @param {Arrayable<keyof Target>} keys - The keys to omit
+ * @returns {Omit<Target, Key>} The new object with the specified keys omitted
+ * 
+ * @example
+ * omit({ a: 1, b: 2, c: 3 }, 'a') // => { b: 2, c: 3 }
+ * 
+ * @example
+ * omit({ a: 1, b: 2, c: 3 }, ['a', 'b']) // => { c: 3 }
+ * 
+ * @since 0.0.3
+ */
+export function omit<Target extends object, Key extends keyof Target>(
+  target: Target,
+  keys: Arrayable<Key>
+): Omit<Target, Key> {
+  const result = { ...target };
+
+  if (!target || !keys)
+    return result;
+
+  if (isArray(keys)) {
+    for (const key of keys) {
+      delete result[key];
+    }
+  } else {
+    delete result[keys];
+  }
+
+  return result;
+}

packages/stdlib/src/objects/pick/index.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { pick } from '.';
+
+describe('pick', () => {
+  it('pick a single key', () => {
+    const result = pick({ a: 1, b: 2, c: 3 }, 'a');
+
+    expect(result).toEqual({ a: 1 });
+  });
+
+  it('pick multiple keys', () => {
+    const result = pick({ a: 1, b: 2, c: 3 }, ['a', 'b']);
+
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+
+  it('return an empty object when no keys are provided', () => {
+    const result = pick({ a: 1, b: 2 }, []);
+
+    expect(result).toEqual({});
+  });
+
+  it('handle non-existent keys by setting them to undefined', () => {
+    const result = pick({ a: 1, b: 2 }, ['a', 'c'] as any);
+
+    expect(result).toEqual({ a: 1, c: undefined });
+  });
+
+  it('return an empty object if target is null or undefined', () => {
+    const emptyTarget = pick(null as any, 'a');
+    const emptyKeys = pick({ a: 1 }, null as any);
+
+    expect(emptyTarget).toEqual({});
+    expect(emptyKeys).toEqual({});
+  });
+});

packages/stdlib/src/objects/pick/index.ts

@@ -0,0 +1,38 @@
+import { isArray, type Arrayable } from '../../types';
+
+/**
+ * @name pick
+ * @category Objects
+ * @description Returns a partial copy of an object containing only the keys specified
+ * 
+ * @param {object} target - The object to pick keys from
+ * @param {Arrayable<keyof Target>} keys - The keys to pick
+ * @returns {Pick<Target, Key>} The new object with the specified keys picked
+ * 
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, 'a') // => { a: 1 }
+ * 
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, ['a', 'b']) // => { a: 1, b: 2 }
+ * 
+ * @since 0.0.3
+ */
+export function pick<Target extends object, Key extends keyof Target>(
+  target: Target,
+  keys: Arrayable<Key>
+): Pick<Target, Key> {
+  const result = {} as Pick<Target, Key>;
+
+  if (!target || !keys)
+    return result;
+
+  if (isArray(keys)) {
+    for (const key of keys) {
+      result[key] = target[key];
+    }
+  } else {
+    result[keys] = target[keys];
+  }
+
+  return result;
+}

packages/stdlib/src/structs/stack/index.ts

@@ -84,7 +84,7 @@ export class Stack<T> implements Iterable<T>, AsyncIterable<T> {
 
     /**
      * Pops an element from the stack
-     * @returns {T} The element popped from the stack
+     * @returns {T | undefined} The element popped from the stack
      */
     public pop() {
         return this.stack.pop();
@@ -92,7 +92,7 @@ export class Stack<T> implements Iterable<T>, AsyncIterable<T> {
 
     /**
      * Peeks at the top element of the stack
-     * @returns {T} The top element of the stack
+     * @returns {T | undefined} The top element of the stack
      */
     public peek() {
         if (this.isEmpty)