ts-data-forge 5.0.0 → 5.1.0

package/src/array/impl/array-utils-search.mts

@@ -14,9 +14,11 @@ import { asUint32 } from '../../number/index.mjs';
  * ];
  *
  * const found = Arr.find(users, (user) => user.id === 2);
+ *
  * const missing = Arr.find<{ id: number }>((user) => user.id === 3)(users);
  *
  * assert.deepStrictEqual(found, Optional.some({ id: 2, name: 'Grace' }));
+ *
  * assert.deepStrictEqual(missing, Optional.none);
  * ```
  */
@@ -55,6 +57,7 @@ export function find<E>(
   switch (args.length) {
     case 2: {
       const [array, predicate] = args;
+
       const foundIndex = array.findIndex(
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         predicate as () => boolean,
@@ -75,6 +78,7 @@ export function find<E>(
         : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
           Optional.some(array[foundIndex]!);
     }
+
     case 1: {
       const [predicate] = args;
 
@@ -97,9 +101,11 @@ export function find<E>(
  * const numbers = [1, 3, 2, 4, 5];
  *
  * const lastEven = Arr.findLast(numbers, (n) => n % 2 === 0);
+ *
  * const none = Arr.findLast<number>((n) => n > 10)(numbers);
  *
  * assert.deepStrictEqual(lastEven, Optional.some(4));
+ *
  * assert.deepStrictEqual(none, Optional.none);
  * ```
  */
@@ -138,6 +144,7 @@ export function findLast<E>(
   switch (args.length) {
     case 2: {
       const [array, predicate] = args;
+
       const foundIndex = array.findLastIndex(
         // eslint-disable-next-line total-functions/no-unsafe-type-assertion
         predicate as () => boolean,
@@ -158,6 +165,7 @@ export function findLast<E>(
         : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
           Optional.some(array[foundIndex]!);
     }
+
     case 1: {
       const [predicate] = args;
 
@@ -180,12 +188,14 @@ export function findLast<E>(
  * const letters = ['a', 'b', 'c'];
  *
  * const indexOfB = Arr.findIndex(letters, (letter) => letter === 'b');
+ *
  * // eslint-disable-next-line unicorn/prefer-array-index-of
  * const indexOfMissing = Arr.findIndex<string>((letter) => letter === 'z')(
  *   letters,
  * );
  *
  * assert(indexOfB === 1);
+ *
  * assert(indexOfMissing === -1);
  * ```
  */
@@ -219,6 +229,7 @@ export function findIndex<E>(
   switch (args.length) {
     case 2: {
       const [array, predicate] = args;
+
       return pipe(
         array.findIndex(
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
@@ -226,8 +237,10 @@ export function findIndex<E>(
         ),
       ).map((idx) => (idx >= 0 ? asUint32(idx) : -1)).value;
     }
+
     case 1: {
       const [predicate] = args;
+
       return (array) => findIndex(array, predicate);
     }
   }
@@ -242,10 +255,12 @@ export function findIndex<E>(
  * const letters = ['a', 'b', 'c', 'b'];
  *
  * const lastIndexOfB = Arr.findLastIndex(letters, (letter) => letter === 'b');
+ *
  * // eslint-disable-next-line unicorn/prefer-array-index-of
  * const notFound = Arr.findLastIndex<string>((letter) => letter === 'z')(letters);
  *
  * assert(lastIndexOfB === 3);
+ *
  * assert(notFound === -1);
  * ```
  */
@@ -279,6 +294,7 @@ export function findLastIndex<E>(
   switch (args.length) {
     case 2: {
       const [array, predicate] = args;
+
       return pipe(
         array.findLastIndex(
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
@@ -286,8 +302,10 @@ export function findLastIndex<E>(
         ),
       ).map((idx) => (idx >= 0 ? asUint32(idx) : -1)).value;
     }
+
     case 1: {
       const [predicate] = args;
+
       return (array) => findLastIndex(array, predicate);
     }
   }
@@ -302,14 +320,18 @@ export function findLastIndex<E>(
  * const fruits = ['apple', 'banana', 'orange', 'banana'];
  *
  * const indexOfBanana = Arr.indexOf(fruits, 'banana');
+ *
  * const indexOfGrape = Arr.indexOf(fruits, 'grape');
  *
  * // Curried version
  * const findApple = Arr.indexOf('apple');
+ *
  * const indexOfApple = findApple(fruits);
  *
  * console.log(indexOfBanana); // => 1
+ *
  * console.log(indexOfGrape); // => -1
+ *
  * console.log(indexOfApple); // => 0
  * ```
  */
@@ -332,10 +354,13 @@ export function indexOf<E>(
       const [array, searchElement] = args;
 
       const index = array.indexOf(searchElement);
+
       return index !== -1 ? asUint32(index) : -1;
     }
+
     case 1: {
       const [searchElement] = args;
+
       return (array) => indexOf(array, searchElement);
     }
   }
@@ -351,18 +376,24 @@ export function indexOf<E>(
  *
  * // Search for 'banana' starting from index 1
  * const firstBanana = Arr.indexOfFrom(fruits, 'banana', 1);
+ *
  * // Search for 'banana' starting from index 2
  * const secondBanana = Arr.indexOfFrom(fruits, 'banana', 2);
+ *
  * // Element not found
  * const notFound = Arr.indexOfFrom(fruits, 'grape', 0);
  *
  * // Curried version
  * const findBananaFrom2 = Arr.indexOfFrom('banana', 2);
+ *
  * const index = findBananaFrom2(fruits);
  *
  * console.log(firstBanana); // => 1
+ *
  * console.log(secondBanana); // => 3
+ *
  * console.log(notFound); // => -1
+ *
  * console.log(index); // => 3
  * ```
  */
@@ -389,11 +420,15 @@ export function indexOfFrom<E>(
   switch (args.length) {
     case 3: {
       const [array, searchElement, fromIndex] = args;
+
       const index = array.indexOf(searchElement, fromIndex);
+
       return index !== -1 ? asUint32(index) : -1;
     }
+
     case 2: {
       const [searchElement, fromIndex] = args;
+
       return (array) => indexOfFrom(array, searchElement, fromIndex);
     }
   }
@@ -408,16 +443,22 @@ export function indexOfFrom<E>(
  * const fruits = ['apple', 'banana', 'orange', 'banana'];
  *
  * const lastBanana = Arr.lastIndexOf(fruits, 'banana');
+ *
  * const lastApple = Arr.lastIndexOf(fruits, 'apple');
+ *
  * const notFound = Arr.lastIndexOf(fruits, 'grape');
  *
  * // Curried version
  * const findLastBanana = Arr.lastIndexOf('banana');
+ *
  * const index = findLastBanana(fruits);
  *
  * console.log(lastBanana); // => 3
+ *
  * console.log(lastApple); // => 0
+ *
  * console.log(notFound); // => -1
+ *
  * console.log(index); // => 3
  * ```
  */
@@ -438,11 +479,15 @@ export function lastIndexOf<E>(
   switch (args.length) {
     case 2: {
       const [array, searchElement] = args;
+
       const index = array.lastIndexOf(searchElement);
+
       return index !== -1 ? asUint32(index) : -1;
     }
+
     case 1: {
       const [searchElement] = args;
+
       return (array) => lastIndexOf(array, searchElement);
     }
   }
@@ -458,18 +503,24 @@ export function lastIndexOf<E>(
  *
  * // Search backwards for 'banana' from index 3
  * const lastBananaFrom3 = Arr.lastIndexOfFrom(fruits, 'banana', 3);
+ *
  * // Search backwards for 'banana' from index 2
  * const lastBananaFrom2 = Arr.lastIndexOfFrom(fruits, 'banana', 2);
+ *
  * // Element not found
  * const notFound = Arr.lastIndexOfFrom(fruits, 'grape', 2);
  *
  * // Curried version
  * const findBananaFrom3 = Arr.lastIndexOfFrom('banana', 3);
+ *
  * const index = findBananaFrom3(fruits);
  *
  * console.log(lastBananaFrom3); // => 3
+ *
  * console.log(lastBananaFrom2); // => 1
+ *
  * console.log(notFound); // => -1
+ *
  * console.log(index); // => 3
  * ```
  */
@@ -501,8 +552,10 @@ export function lastIndexOfFrom<E>(
 
       return index !== -1 ? asUint32(index) : -1;
     }
+
     case 2: {
       const [searchElement, fromIndex] = args;
+
       return (array) => lastIndexOfFrom(array, searchElement, fromIndex);
     }
   }

package/src/array/impl/array-utils-search.test.mts

@@ -15,14 +15,17 @@ describe('Arr search operations', () => {
   describe(find, () => {
     test('should find first element matching predicate', () => {
       const numbers = [1, 2, 3, 4, 5];
+
       const firstEven = find(numbers, (n) => n % 2 === 0);
 
       expect(Optional.isSome(firstEven)).toBe(true);
+
       expect(Optional.unwrap(firstEven)).toBe(2);
     });
 
     test('should return None when no element matches', () => {
       const odds = [1, 3, 5];
+
       const firstEven = find(odds, (n) => n % 2 === 0);
 
       expect(Optional.isNone(firstEven)).toBe(true);
@@ -30,18 +33,23 @@ describe('Arr search operations', () => {
 
     test('should work with curried version', () => {
       const isEven = (n: number): boolean => n % 2 === 0;
+
       const findEven = find<number>(isEven);
 
       const result1 = findEven([1, 2, 3]);
+
       const result2 = findEven([1, 3, 5]);
 
       expect(Optional.isSome(result1)).toBe(true);
+
       expect(Optional.unwrap(result1)).toBe(2);
+
       expect(Optional.isNone(result2)).toBe(true);
     });
 
     test('should work with type guard predicate', () => {
       const values: readonly (string | number)[] = [1, 'a', 2, 'b'];
+
       const firstString = find(
         values,
         (x): x is string => typeof x === 'string',
@@ -50,11 +58,13 @@ describe('Arr search operations', () => {
       expectType<typeof firstString, Optional<string>>('=');
 
       expect(Optional.isSome(firstString)).toBe(true);
+
       expect(Optional.unwrap(firstString)).toBe('a');
     });
 
     test('should provide index and array to predicate', () => {
       const numbers = [10, 20, 30];
+
       const foundWithIndex = find(numbers, (value, index, arr) => {
         expect(arr).toBe(numbers);
 
@@ -66,6 +76,7 @@ describe('Arr search operations', () => {
 
     test('should return first match when multiple elements match', () => {
       const numbers = [2, 4, 6, 8];
+
       const firstEven = find(numbers, (n) => n % 2 === 0);
 
       expect(Optional.unwrap(firstEven)).toBe(2);
@@ -73,6 +84,7 @@ describe('Arr search operations', () => {
 
     test('should work with empty array', () => {
       const empty: readonly number[] = [];
+
       const result = find(empty, () => true);
 
       expect(Optional.isNone(result)).toBe(true);
@@ -82,14 +94,17 @@ describe('Arr search operations', () => {
   describe(findLast, () => {
     test('should find last element matching predicate', () => {
       const numbers = [1, 2, 3, 4, 5];
+
       const lastEven = findLast(numbers, (n) => n % 2 === 0);
 
       expect(Optional.isSome(lastEven)).toBe(true);
+
       expect(Optional.unwrap(lastEven)).toBe(4);
     });
 
     test('should return None when no element matches', () => {
       const odds = [1, 3, 5];
+
       const lastEven = findLast(odds, (n) => n % 2 === 0);
 
       expect(Optional.isNone(lastEven)).toBe(true);
@@ -97,15 +112,19 @@ describe('Arr search operations', () => {
 
     test('should work with curried version', () => {
       const isPositive = (n: number): boolean => n > 0;
+
       const findLastPositive = findLast(isPositive);
+
       const result = findLastPositive([-1, 2, -3, 4]);
 
       expect(Optional.isSome(result)).toBe(true);
+
       expect(Optional.unwrap(result)).toBe(4);
     });
 
     test('should work with empty array', () => {
       const empty: number[] = [];
+
       const result = findLast(empty, (n) => n > 0);
 
       expect(Optional.isNone(result)).toBe(true);
@@ -113,6 +132,7 @@ describe('Arr search operations', () => {
 
     test('should pass index and array to predicate', () => {
       const numbers = [10, 20, 30, 40];
+
       const lastWithIndex2 = findLast(numbers, (_, idx, arr) => {
         expect(arr).toBe(numbers);
 
@@ -124,6 +144,7 @@ describe('Arr search operations', () => {
 
     test('should find last occurrence', () => {
       const numbers = [1, 2, 2, 3, 2, 4];
+
       const lastTwo = findLast(numbers, (n) => n === 2);
 
       expect(Optional.unwrap(lastTwo)).toBe(2);
@@ -138,6 +159,7 @@ describe('Arr search operations', () => {
   describe(findIndex, () => {
     test('should find index of matching element', () => {
       const arr = ['a', 'b', 'c'];
+
       const result = findIndex(arr, (x) => x === 'b');
 
       expect(result).toBeGreaterThanOrEqual(0);
@@ -149,6 +171,7 @@ describe('Arr search operations', () => {
 
     test('should return None for no match', () => {
       const arr = ['a', 'b', 'c'];
+
       const result = findIndex(arr, (x) => x === 'd');
 
       expect(result).toBe(-1);
@@ -158,6 +181,7 @@ describe('Arr search operations', () => {
   describe(findLastIndex, () => {
     test('should find last index matching predicate', () => {
       const numbers = [1, 2, 3, 4, 2, 5];
+
       const lastTwoIndex = findLastIndex(numbers, (n) => n === 2);
 
       expect(lastTwoIndex).toBe(4);
@@ -165,6 +189,7 @@ describe('Arr search operations', () => {
 
     test('should return -1 when no element matches', () => {
       const odds = [1, 3, 5];
+
       const lastEvenIndex = findLastIndex(odds, (n) => n % 2 === 0);
 
       expect(lastEvenIndex).toBe(-1);
@@ -172,7 +197,9 @@ describe('Arr search operations', () => {
 
     test('should work with curried version', () => {
       const isPositive = (n: number): boolean => n > 0;
+
       const findLastPositiveIndex = findLastIndex(isPositive);
+
       const result = findLastPositiveIndex([-1, 2, -3, 4, -5]);
 
       expect(result).toBe(3); // index of last positive number (4)
@@ -180,6 +207,7 @@ describe('Arr search operations', () => {
 
     test('should work with empty array', () => {
       const empty: number[] = [];
+
       const result = findLastIndex(empty, (n) => n > 0);
 
       expect(result).toBe(-1);
@@ -187,6 +215,7 @@ describe('Arr search operations', () => {
 
     test('should pass index and array to predicate', () => {
       const numbers = [10, 20, 30, 40];
+
       const lastWithIndex2OrHigher = findLastIndex(numbers, (_, idx, arr) => {
         expect(arr).toBe(numbers);
 
@@ -204,6 +233,7 @@ describe('Arr search operations', () => {
         { id: 4, active: false },
         { id: 5, active: true },
       ];
+
       const lastActiveIndex = findLastIndex(data, (item) => item.active);
 
       expect(lastActiveIndex).toBe(4); // last active item
@@ -211,6 +241,7 @@ describe('Arr search operations', () => {
 
     test('should work with tuples', () => {
       const tuple = [10, 20, 30, 20, 40] as const;
+
       const lastTwentyIndex = findLastIndex(tuple, (x) => x === 20);
 
       expect(lastTwentyIndex).toBe(3); // last occurrence of 20
@@ -219,10 +250,12 @@ describe('Arr search operations', () => {
     test('should search from end to beginning', () => {
       // Verify search order by using side effects
       const numbers = [1, 2, 3, 4, 5];
+
       const mut_searchOrder: number[] = [];
 
       findLastIndex(numbers, (val, idx) => {
         mut_searchOrder.push(idx);
+
         return val === 3;
       });
 
@@ -232,15 +265,19 @@ describe('Arr search operations', () => {
 
     test('should handle single element array', () => {
       const single = [42];
+
       const foundIndex = findLastIndex(single, (n) => n === 42);
+
       const notFoundIndex = findLastIndex(single, (n) => n === 0);
 
       expect(foundIndex).toBe(0);
+
       expect(notFoundIndex).toBe(-1);
     });
 
     test('should work with string arrays', () => {
       const words = ['hello', 'world', 'test', 'hello', 'end'];
+
       const lastHelloIndex = findLastIndex(words, (word) => word === 'hello');
 
       expect(lastHelloIndex).toBe(3);
@@ -250,6 +287,7 @@ describe('Arr search operations', () => {
   describe(indexOf, () => {
     test('should find index of element', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = indexOf(arr, 'b');
 
       expect(result).toBeGreaterThanOrEqual(0);
@@ -263,6 +301,7 @@ describe('Arr search operations', () => {
 
     test('should return -1 for non-existent element', () => {
       const arr = ['a', 'b', 'c'];
+
       const result = indexOf(arr, 'd');
 
       expect(result).toBe(-1);
@@ -272,6 +311,7 @@ describe('Arr search operations', () => {
   describe(indexOfFrom, () => {
     test('should find index of element from specified index', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = indexOfFrom(arr, 'b', 2);
 
       expect(result).toBeGreaterThanOrEqual(0);
@@ -285,6 +325,7 @@ describe('Arr search operations', () => {
 
     test('should return -1 when element not found from index', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = indexOfFrom(arr, 'a', 1);
 
       expect(result).toBe(-1);
@@ -292,6 +333,7 @@ describe('Arr search operations', () => {
 
     test('should find first occurrence when fromIndex is 0', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = indexOfFrom(arr, 'b', 0);
 
       expect(result).toBe(1);
@@ -299,6 +341,7 @@ describe('Arr search operations', () => {
 
     test('should handle negative fromIndex', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = indexOfFrom(arr, 'b', -2);
 
       expect(result).toBe(3);
@@ -306,6 +349,7 @@ describe('Arr search operations', () => {
 
     test('should handle fromIndex beyond array length', () => {
       const arr = ['a', 'b', 'c'];
+
       const result = indexOfFrom(arr, 'a', 10);
 
       expect(result).toBe(-1);
@@ -315,6 +359,7 @@ describe('Arr search operations', () => {
   describe(lastIndexOf, () => {
     test('should find last index of element', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = lastIndexOf(arr, 'b');
 
       expect(result).toBeGreaterThanOrEqual(0);
@@ -328,6 +373,7 @@ describe('Arr search operations', () => {
 
     test('should return -1 for non-existent element', () => {
       const arr = ['a', 'b', 'c'];
+
       const result = lastIndexOf(arr, 'd');
 
       expect(result).toBe(-1);
@@ -337,6 +383,7 @@ describe('Arr search operations', () => {
   describe(lastIndexOfFrom, () => {
     test('should find last index of element from specified index', () => {
       const arr = ['a', 'b', 'c', 'b', 'e'];
+
       const result = lastIndexOfFrom(arr, 'b', 2);
 
       expect(result).toBeGreaterThanOrEqual(0);
@@ -350,6 +397,7 @@ describe('Arr search operations', () => {
 
     test('should return -1 when element not found before index', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = lastIndexOfFrom(arr, 'b', 0);
 
       expect(result).toBe(-1);
@@ -357,6 +405,7 @@ describe('Arr search operations', () => {
 
     test('should find last occurrence when fromIndex covers all elements', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = lastIndexOfFrom(arr, 'b', 10);
 
       expect(result).toBe(3);
@@ -364,6 +413,7 @@ describe('Arr search operations', () => {
 
     test('should handle negative fromIndex', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = lastIndexOfFrom(arr, 'b', -1);
 
       expect(result).toBe(3);
@@ -371,6 +421,7 @@ describe('Arr search operations', () => {
 
     test('should handle fromIndex of 0', () => {
       const arr = ['a', 'b', 'c', 'b'];
+
       const result = lastIndexOfFrom(arr, 'a', 0);
 
       expect(result).toBe(0);

package/src/array/impl/array-utils-set-op.mts

@@ -5,10 +5,13 @@
  *
  * ```ts
  * const numbers = [1, 2, 3] as const;
+ *
  * const sameNumbers = [1, 2, 3] as const;
+ *
  * const differentNumbers = [1, 2, 4] as const;
  *
  * assert.ok(Arr.eq(numbers, sameNumbers));
+ *
  * assert.notOk(Arr.eq(numbers, differentNumbers));
  * ```
  */
@@ -35,10 +38,13 @@ export const equal = eq;
  *
  * ```ts
  * const subset = [1, 2] as const;
+ *
  * const superset = [1, 2, 3] as const;
+ *
  * const notSubset = [2, 4] as const;
  *
  * assert.ok(Arr.isSubset(subset, superset));
+ *
  * assert.notOk(Arr.isSubset(notSubset, superset));
  * ```
  */
@@ -58,11 +64,15 @@ export const isSubset = <E1 extends Primitive, E2 extends Primitive = E1>(
  *
  * ```ts
  * const potentialSuperset = ['a', 'b', 'c'] as const;
+ *
  * const subset = ['a', 'c'] as const;
+ *
  * const notSuperset = ['a', 'd'] as const;
  *
  * assert.ok(Arr.isSuperset(potentialSuperset, subset));
+ *
  * assert.notOk(Arr.isSuperset(subset, potentialSuperset));
+ *
  * assert.notOk(Arr.isSuperset(potentialSuperset, notSuperset));
  * ```
  */
@@ -78,6 +88,7 @@ export const isSuperset = <E1 extends Primitive, E2 extends Primitive = E1>(
  *
  * ```ts
  * const refs = ['Ada', 'Alan', 'Grace'] as const;
+ *
  * const attendees = ['Grace', 'Alan', 'Barbara'] as const;
  *
  * const both = Arr.setIntersection(refs, attendees);
@@ -102,6 +113,7 @@ export const setIntersection = <
  *
  * ```ts
  * const baseline = [1, 2, 3, 4] as const;
+ *
  * const removed = [2, 4] as const;
  *
  * const remaining = Arr.setDifference(baseline, removed);
@@ -121,6 +133,7 @@ export const setDifference = <E extends Primitive>(
  *
  * ```ts
  * const upcoming = [1, 3, 5, 7, 9] as const;
+ *
  * const completed = [3, 4, 7] as const;
  *
  * const remaining = Arr.sortedNumSetDifference(upcoming, completed);
@@ -135,27 +148,33 @@ export const sortedNumSetDifference = <E extends number>(
   sortedList2: readonly E[],
 ): readonly E[] => {
   const mut_result: E[] = [];
+
   let mut_it1 = 0; // iterator for sortedList1
+
   let mut_it2 = 0; // iterator for sortedList2
 
   while (mut_it1 < sortedList1.length && mut_it2 < sortedList2.length) {
     // Non-null assertions are safe due to loop condition
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const val1 = sortedList1[mut_it1]!;
+
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const val2 = sortedList2[mut_it2]!;
 
     if (val1 === val2) {
       mut_it1 += 1;
+
       mut_it2 += 1;
     } else if (val1 < val2) {
       mut_result.push(val1);
+
       mut_it1 += 1;
     } else {
       // val1 > val2
       mut_it2 += 1;
     }
   }
+
   // Add remaining elements from sortedList1
   for (; mut_it1 < sortedList1.length; mut_it1 += 1) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion