ts-data-forge 5.0.0 → 5.1.0

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

@@ -12,85 +12,118 @@ describe('Arr set operations', () => {
   describe(eq, () => {
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return true for equal arrays of numbers', () => {
         expect(result).toBe(true);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [1, 2, 4] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return false for different arrays of numbers', () => {
         expect(result).toBe(false);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [1, 2] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return false for arrays of different lengths', () => {
         expect(result).toBe(false);
       });
     }
+
     {
       const xs = ['a', 'b'] as const;
+
       const ys = ['a', 'b'] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return true for equal arrays of strings', () => {
         expect(result).toBe(true);
       });
     }
+
     {
       const xs = [] as const;
+
       const ys = [] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return true for empty arrays', () => {
         expect(result).toBe(true);
       });
     }
+
     {
       const xs = [{ a: 1 }, { b: 2 }] as const;
+
       const ys = [{ a: 1 }, { b: 2 }] as const;
+
       // Default eq uses reference equality for objects
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return false for arrays of objects with default equality (reference check)', () => {
         expect(result).toBe(false);
       });
     }
+
     {
       const objA = { a: 1 };
+
       const objB = { b: 2 };
+
       const xs = [objA, objB] as const;
+
       const ys = [objA, objB] as const;
+
       const result = eq(xs, ys);
+
       expectType<typeof result, boolean>('=');
 
       test('should return true for arrays of same object references', () => {
         expect(result).toBe(true);
       });
     }
+
     {
       const xs = [{ a: 1 }, { b: 2 }] as const;
+
       const ys = [{ a: 1 }, { b: 2 }] as const;
+
       const result = eq(
         xs,
         ys,
         (o1, o2) => JSON.stringify(o1) === JSON.stringify(o2),
       );
+
       expectType<typeof result, boolean>('=');
 
       test('should return true for arrays of objects with custom equality function', () => {
@@ -102,6 +135,7 @@ describe('Arr set operations', () => {
   describe(isSubset, () => {
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [3, 2] as const;
 
       const result = isSubset(ys, xs);
@@ -112,8 +146,10 @@ describe('Arr set operations', () => {
         expect(result).toBe(true);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [3, 2, 4] as const;
 
       const result = isSubset(ys, xs);
@@ -129,6 +165,7 @@ describe('Arr set operations', () => {
   describe(isSuperset, () => {
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [3, 2] as const;
 
       const result = isSuperset(ys, xs);
@@ -145,8 +182,10 @@ describe('Arr set operations', () => {
         expect(result2).toBe(true);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [3, 2, 4] as const;
 
       const result = isSuperset(ys, xs);
@@ -162,48 +201,67 @@ describe('Arr set operations', () => {
   describe(setIntersection, () => {
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [2, 3, 4] as const;
+
       const result = setIntersection(xs, ys);
+
       expectType<typeof result, readonly (2 | 3)[]>('=');
 
       test('should return the intersection of two number arrays', () => {
         assert.deepStrictEqual(result, [2, 3]);
       });
     }
+
     {
       const xs = ['a', 'b', 'c'] as const;
+
       const ys = ['b', 'c', 'd'] as const;
+
       const result = setIntersection(xs, ys);
+
       expectType<typeof result, readonly ('b' | 'c')[]>('=');
 
       test('should return the intersection of two string arrays', () => {
         assert.deepStrictEqual(result, ['b', 'c']);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [4, 5, 6] as const;
+
       const result = setIntersection(xs, ys);
+
       expectType<typeof result, readonly never[]>('=');
 
       test('should return an empty array if there is no intersection', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [] as const;
+
       const result = setIntersection(xs, ys);
+
       expectType<typeof result, readonly never[]>('=');
 
       test('should return an empty array if one array is empty', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = setIntersection(xs, ys);
+
       expectType<typeof result, readonly never[]>('=');
 
       test('should return an empty array if the first array is empty', () => {
@@ -215,58 +273,81 @@ describe('Arr set operations', () => {
   describe(setDifference, () => {
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [2, 3, 4] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4)[]>('=');
 
       test('should return the difference xs - ys for number arrays', () => {
         assert.deepStrictEqual(result, [1]);
       });
     }
+
     {
       const xs = ['a', 'b', 'c'] as const;
+
       const ys = ['b', 'c', 'd'] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly ('a' | 'b' | 'c' | 'd')[]>('=');
 
       test('should return the difference xs - ys for string arrays', () => {
         assert.deepStrictEqual(result, ['a']);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
       test('should return an empty array if xs is a subset of ys', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [4, 5, 6] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
 
       test('should return xs if there is no intersection', () => {
         assert.deepStrictEqual(result, [1, 2, 3]);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
       test('should return xs if ys is empty', () => {
         assert.deepStrictEqual(result, [1, 2, 3]);
       });
     }
+
     {
       const xs = [] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = setDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
       test('should return an empty array if xs is empty', () => {
@@ -278,88 +359,123 @@ describe('Arr set operations', () => {
   describe(sortedNumSetDifference, () => {
     {
       const xs = [1, 2, 3, 5] as const;
+
       const ys = [2, 3, 4] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
 
       test('should return the difference for sorted number arrays (xs - ys)', () => {
         assert.deepStrictEqual(result, [1, 5]);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
       test('should return an empty array if sets are equal', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [4, 5, 6] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
 
       test('should return xs if no common elements', () => {
         assert.deepStrictEqual(result, [1, 2, 3]);
       });
     }
+
     {
       const xs = [4, 5, 6] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
 
       test('should return xs if no common elements (ys < xs)', () => {
         assert.deepStrictEqual(result, [4, 5, 6]);
       });
     }
+
     {
       const xs = [1, 2, 3, 4, 5] as const;
+
       const ys = [2, 4] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
 
       test('should return correct difference when ys is subset of xs', () => {
         assert.deepStrictEqual(result, [1, 3, 5]);
       });
     }
+
     {
       const xs = [2, 4] as const;
+
       const ys = [1, 2, 3, 4, 5] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
 
       test('should return empty array when xs is subset of ys', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [] as const;
+
       const ys = [1, 2, 3] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('='); // Type is `readonly number[]` due to `ys`
 
       test('should return an empty array if xs is empty', () => {
         assert.deepStrictEqual(result, []);
       });
     }
+
     {
       const xs = [1, 2, 3] as const;
+
       const ys = [] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
       test('should return xs if ys is empty', () => {
         assert.deepStrictEqual(result, [1, 2, 3]);
       });
     }
+
     {
       const xs = [] as const;
+
       const ys = [] as const;
+
       const result = sortedNumSetDifference(xs, ys);
+
       expectType<typeof result, readonly never[]>('='); // Type is `readonly number[]`
 
       test('should return an empty array if both are empty', () => {

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

@@ -5,12 +5,15 @@
  *
  * ```ts
  * const numbers = [1, 2, 3] as const;
+ *
  * const letters: string[] = [];
  *
  * const sizeOfNumbers = Arr.size(numbers);
+ *
  * const sizeOfLetters = Arr.size(letters);
  *
  * assert(sizeOfNumbers === 3);
+ *
  * assert(sizeOfLetters === 0);
  * ```
  */

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

@@ -5,6 +5,7 @@ describe('size/length', () => {
     const array = [1, 2, 3];
 
     expect(size(array)).toBe(array.length);
+
     expect(length(array)).toBe(3);
   });
 });

package/src/array/impl/array-utils-slice-clamped.mts

@@ -9,9 +9,11 @@ import { Num } from '../../number/index.mjs';
  * const letters = ['a', 'b', 'c', 'd', 'e'];
  *
  * const lastThree = Arr.sliceClamped(letters, -3, 10);
+ *
  * const middleTwo = Arr.sliceClamped(1, 3)(letters);
  *
  * assert.deepStrictEqual(lastThree, ['a', 'b', 'c', 'd', 'e']);
+ *
  * assert.deepStrictEqual(middleTwo, ['b', 'c']);
  * ```
  */
@@ -38,13 +40,18 @@ export function sliceClamped<E>(
   switch (args.length) {
     case 3: {
       const [array, start, end] = args;
+
       const startClamped = Num.clamp(0, array.length)(start);
+
       // Ensure endClamped is not less than startClamped.
       const endClamped = Num.clamp(startClamped, array.length)(end);
+
       return array.slice(startClamped, endClamped);
     }
+
     case 2: {
       const [start, end] = args;
+
       return (array) => sliceClamped(array, start, end);
     }
   }

package/src/array/impl/array-utils-slice-clamped.test.mts

@@ -80,27 +80,34 @@ describe('Arr', () => {
     test('should be type error for index overflow for fixed length array', () => {
       {
         const array = [1, 2, 3, 4, 5] as const;
+
         // @ts-expect-error end index is out of bounds
         const result = sliceClamped(array, 0, 6);
 
         assert.deepStrictEqual(result, array);
       }
+
       {
         const array = [1, 2, 3, 4, 5] as const;
+
         // @ts-expect-error end index is out of bounds
         const result = sliceClamped(array, 0, -6);
 
         assert.deepStrictEqual(result, []);
       }
+
       {
         const array = [1, 2, 3, 4, 5] as const;
+
         // @ts-expect-error start index is out of bounds
         const result = sliceClamped(array, -6, 5);
 
         assert.deepStrictEqual(result, array);
       }
+
       {
         const array = [1, 2, 3, 4, 5] as const;
+
         // @ts-expect-error start index is out of bounds
         const result = sliceClamped(array, 6, 5);
 
@@ -110,6 +117,7 @@ describe('Arr', () => {
 
     test('should slice with clamped indices', () => {
       const array = [1, 2, 3, 4, 5];
+
       const result = sliceClamped(array, 1, 3);
 
       assert.deepStrictEqual(result, [2, 3]);
@@ -117,6 +125,7 @@ describe('Arr', () => {
 
     test('should clamp start index below 0', () => {
       const array = [1, 2, 3, 4, 5];
+
       const result = sliceClamped(array, -10, 3);
 
       assert.deepStrictEqual(result, [1, 2, 3]);
@@ -124,6 +133,7 @@ describe('Arr', () => {
 
     test('should clamp end index above length', () => {
       const array = [1, 2, 3, 4, 5];
+
       const result = sliceClamped(array, asUint32(2), asUint32(100));
 
       assert.deepStrictEqual(result, [3, 4, 5]);
@@ -131,6 +141,7 @@ describe('Arr', () => {
 
     test('should work with both indices out of range', () => {
       const array = [1, 2, 3];
+
       const result = sliceClamped(array, asInt32(-10), asUint32(100));
 
       assert.deepStrictEqual(result, [1, 2, 3]);
@@ -138,9 +149,18 @@ describe('Arr', () => {
 
     test('should work with empty array', () => {
       const array: readonly number[] = [];
+
       const result = sliceClamped(array, 0, 5);
 
       assert.deepStrictEqual(result, []);
     });
+
+    test('should work with curried version', () => {
+      const slice1to3 = sliceClamped(1, 3);
+
+      const result = slice1to3([10, 20, 30, 40, 50]);
+
+      assert.deepStrictEqual(result, [20, 30]);
+    });
   });
 });

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

@@ -11,18 +11,23 @@ import { isEmpty } from './array-utils-validation.mjs';
  * ```ts
  * {
  *   const scientists = ['Ada', 'Grace', 'Katherine'] as const;
+ *
  *   const remainder = Arr.tail(scientists);
  *
  *   assert.deepStrictEqual(remainder, ['Grace', 'Katherine']);
+ *
  *   assert(remainder.length === 2);
  * }
+ *
  * {
  *   const values = [1, 2, 3] as const;
  *
  *   const remainder = Arr.rest(values);
+ *
  *   const emptyRemainder = Arr.rest([1] as const);
  *
  *   assert.deepStrictEqual(remainder, [2, 3] as const);
+ *
  *   assert.deepStrictEqual(emptyRemainder, [] as const);
  * }
  * ```
@@ -40,9 +45,11 @@ export const tail = <const Ar extends readonly unknown[]>(
  *
  * ```ts
  * const queue = ['task-1', 'task-2', 'task-3'] as const;
+ *
  * const withoutLast = Arr.butLast(queue);
  *
  * assert.deepStrictEqual(withoutLast, ['task-1', 'task-2']);
+ *
  * assert(withoutLast.length === 2);
  * ```
  */
@@ -61,9 +68,11 @@ export const butLast = <const Ar extends readonly unknown[]>(
  * const values = [1, 2, 3, 4];
  *
  * const firstTwo = Arr.take(values, 2);
+ *
  * const firstThree = Arr.take(3)(values);
  *
  * assert.deepStrictEqual(firstTwo, [1, 2]);
+ *
  * assert.deepStrictEqual(firstThree, [1, 2, 3]);
  * ```
  */
@@ -101,10 +110,13 @@ export function take<E>(
   switch (args.length) {
     case 2: {
       const [array, num] = args;
+
       return sliceClamped(array, 0, num);
     }
+
     case 1: {
       const [num] = args;
+
       return (array) => take(array, num);
     }
   }
@@ -119,9 +131,11 @@ export function take<E>(
  * const values = [1, 2, 3, 4];
  *
  * const lastTwo = Arr.takeLast(values, 2);
+ *
  * const lastThree = Arr.takeLast(3)(values);
  *
  * assert.deepStrictEqual(lastTwo, [3, 4]);
+ *
  * assert.deepStrictEqual(lastThree, [2, 3, 4]);
  * ```
  */
@@ -159,10 +173,13 @@ export function takeLast<E>(
   switch (args.length) {
     case 2: {
       const [array, num] = args;
+
       return sliceClamped(array, Uint32.sub(size(array), num), size(array));
     }
+
     case 1: {
       const [num] = args;
+
       return (array) => takeLast(array, num);
     }
   }
@@ -177,9 +194,11 @@ export function takeLast<E>(
  * const values = ['a', 'b', 'c', 'd'] as const;
  *
  * const withoutFirstTwo = Arr.skip(values, 2);
+ *
  * const withoutFirstThree = Arr.skip(3)(values);
  *
  * assert.deepStrictEqual(withoutFirstTwo, ['c', 'd']);
+ *
  * assert.deepStrictEqual(withoutFirstThree, ['d']);
  * ```
  */
@@ -204,10 +223,13 @@ export function skip<E>(
   switch (args.length) {
     case 2: {
       const [array, num] = args;
+
       return sliceClamped(array, num, size(array));
     }
+
     case 1: {
       const [num] = args;
+
       return (array) => skip(array, num);
     }
   }
@@ -222,9 +244,11 @@ export function skip<E>(
  * const values = ['a', 'b', 'c', 'd'];
  *
  * const withoutLastTwo = Arr.skipLast(values, 2);
+ *
  * const withoutLastThree = Arr.skipLast(3)(values);
  *
  * assert.deepStrictEqual(withoutLastTwo, ['a', 'b']);
+ *
  * assert.deepStrictEqual(withoutLastThree, ['a']);
  * ```
  */
@@ -251,10 +275,13 @@ export function skipLast<E>(
   switch (args.length) {
     case 2: {
       const [array, num] = args;
+
       return sliceClamped(array, 0, Uint32.sub(size(array), num));
     }
+
     case 1: {
       const [num] = args;
+
       return (array) => skipLast(array, num);
     }
   }