refactor: change separate tools by category

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

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+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([]);
+  });
+});

core/stdlib/src/arrays/cluster/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @name cluster
+ * @category Arrays
+ * @description Cluster an array into subarrays of a specific size
+ * 
+ * @param {Value[]} arr The array to cluster
+ * @param {number} size The size of each cluster
+ * @returns {Value[][]} The clustered array
+ * 
+ * @example
+ * cluster([1, 2, 3, 4, 5, 6, 7, 8], 3) // => [[1, 2, 3], [4, 5, 6], [7, 8]]
+ * 
+ * @example
+ * cluster([1, 2, 3, 4], -1) // => []
+ * 
+ * @since 0.0.3
+ */
+export function cluster<Value>(arr: Value[], size: number): Value[][] {
+  if (size <= 0) return [];
+
+  const clusterLength = Math.ceil(arr.length / size);
+
+  return Array.from({ length: clusterLength }, (_, i) => arr.slice(i * size, i * size + size));
+}

core/stdlib/src/arrays/first/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { first } from '.';
+
+describe('first', () => {
+  it('return the first element of a non-empty array', () => {
+    expect(first([1, 2, 3])).toBe(1);
+    expect(first(['a', 'b', 'c'])).toBe('a');
+  });
+
+  it('return undefined for an empty array without a default value', () => {
+    expect(first([])).toBeUndefined();
+  });
+
+  it('return the default value for an empty array with a default value', () => {
+    expect(first([], 42)).toBe(42);
+    expect(first([], 'default')).toBe('default');
+  });
+
+  it('return the first element even if a default value is provided', () => {
+    expect(first([1, 2, 3], 42)).toBe(1);
+    expect(first(['a', 'b', 'c'], 'default')).toBe('a');
+  });
+});

core/stdlib/src/arrays/first/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @name first
+ * @category Arrays
+ * @description Returns the first element of an array
+ * 
+ * @param {Value[]} arr The array to get the first element from
+ * @param {Value} [defaultValue] The default value to return if the array is empty
+ * @returns {Value | undefined} The first element of the array, or the default value if the array is empty
+ * 
+ * @example
+ * first([1, 2, 3]); // => 1
+ * 
+ * @example
+ * first([]); // => undefined
+ * 
+ * @since 0.0.3
+ */
+export function first<Value>(arr: Value[], defaultValue?: Value) {
+    return arr[0] ?? defaultValue;
+}

core/stdlib/src/arrays/index.ts

@@ -0,0 +1,5 @@
+export * from './cluster';
+export * from './first';
+export * from './last';
+export * from './sum';
+export * from './unique';

core/stdlib/src/arrays/last/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { last } from '.';
+
+describe('last', () => {
+  it('return the last element of a non-empty array', () => {
+    expect(last([1, 2, 3, 4, 5])).toBe(5);
+    expect(last(['a', 'b', 'c'])).toBe('c');
+  });
+
+  it('return undefined if the array is empty and no default value is provided', () => {
+    expect(last([])).toBeUndefined();
+  });
+
+  it('return the default value for an empty array with a default value', () => {
+    expect(last([], 42)).toBe(42);
+    expect(last([], 'default')).toBe('default');
+  });
+
+  it('return the first element even if a default value is provided', () => {
+    expect(last([1, 2, 3], 42)).toBe(3);
+    expect(last(['a', 'b', 'c'], 'default')).toBe('c');
+  });
+});

core/stdlib/src/arrays/last/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @name last
+ * @section Arrays
+ * @description Gets the last element of an array
+ * 
+ * @param {Value[]} arr The array to get the last element of
+ * @param {Value} [defaultValue] The default value to return if the array is empty
+ * @returns {Value | undefined} The last element of the array, or the default value if the array is empty
+ * 
+ * @example
+ * last([1, 2, 3, 4, 5]); // => 5
+ * 
+ * @example
+ * last([], 3); // => 3
+ * 
+ * @since 0.0.3
+ */
+export function last<Value>(arr: Value[], defaultValue?: Value) {
+  return arr[arr.length - 1] ?? defaultValue;
+}

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

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+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);
+  });
+});

core/stdlib/src/arrays/sum/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @name sum
+ * @category Arrays
+ * @description Returns the sum of all the elements in an array
+ * 
+ * @param {Value[]} array - The array to sum
+ * @param {(item: Value) => number} [getValue] - A function that returns the value to sum from each element in the array
+ * @returns {number} The sum of all the elements in the array
+ * 
+ * @example
+ * sum([1, 2, 3, 4, 5]) // => 15
+ * 
+ * sum([{ value: 1 }, { value: 2 }, { value: 3 }], (item) => item.value) // => 6
+ * 
+ * @since 0.0.3
+ */
+export function sum<Value extends number>(array: Value[]): number;
+export function sum<Value>(array: Value[], getValue: (item: Value) => number): number;
+export function sum<Value>(array: Value[], getValue?: (item: Value) => number): number {
+  // This check is necessary because the overload without the getValue argument
+  // makes tree-shaking based on argument types possible
+  if (!getValue)
+    return array.reduce((acc, item) => acc + (item as number), 0);
+
+  return array.reduce((acc, item) => acc + getValue(item), 0);
+}

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

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+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]);
+  });
+
+  it('return an array with unique objects based on id', () => {
+    const result = 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']);
+  });
+
+  it('handle arrays with symbols', () => {
+    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([]);
+  });
+});

core/stdlib/src/arrays/unique/index.ts

@@ -0,0 +1,33 @@
+export type UniqueKey = string | number | symbol;
+export type Extractor<Value, Key extends UniqueKey> = (value: Value) => Key;
+
+/**
+ * @name unique
+ * @category Arrays
+ * @description Returns a new array with unique values from the original array
+ * 
+ * @param {Value[]} array - The array to filter
+ * @param {Function} [extractor] - The function to extract the value to compare
+ * @returns {Value[]} - The new array with unique values
+ * 
+ * @example
+ * unique([1, 2, 3, 3, 4, 5, 5, 6]) //=> [1, 2, 3, 4, 5, 6]
+ * 
+ * @example
+ * unique([{ id: 1 }, { id: 2 }, { id: 1 }], (a, b) => a.id === b.id) //=> [{ id: 1 }, { id: 2 }]
+ * 
+ * @since 0.0.3
+ */
+export function unique<Value, Key extends UniqueKey>(
+  array: Value[],
+  extractor?: Extractor<Value, Key>,
+) {
+  const values = new Map<Key, Value>();
+
+  for (const value of array) {
+    const key = extractor ? extractor(value) : value as any;
+    values.set(key, value);
+  }
+
+  return Array.from(values.values());
+}