ts-data-forge 1.0.0

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

@@ -0,0 +1,169 @@
+import { expectType } from '../expect-type.mjs';
+import { Optional } from '../functional/optional.mjs';
+import { asInt32, asUint32 } from '../number/index.mjs';
+import { Arr } from './array-utils.mjs';
+
+describe('Arr search operations', () => {
+  describe('findIndex', () => {
+    test('should find index of matching element', () => {
+      const arr = ['a', 'b', 'c'];
+      const result = Arr.findIndex(arr, (x) => x === 'b');
+
+      expect(result).toBeGreaterThanOrEqual(0);
+      expectType<typeof result, SizeType.Arr | -1>('=');
+      expect(result).toBe(1);
+    });
+
+    test('should return None for no match', () => {
+      const arr = ['a', 'b', 'c'];
+      const result = Arr.findIndex(arr, (x) => x === 'd');
+
+      expect(result).toBe(-1);
+    });
+  });
+
+  describe('indexOf', () => {
+    test('should find index of element', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.indexOf(arr, 'b');
+
+      expect(result).toBeGreaterThanOrEqual(0);
+      if (result !== -1) {
+        expectType<typeof result, SizeType.Arr>('=');
+        expect(result).toBe(1);
+      }
+    });
+
+    test('should return -1 for non-existent element', () => {
+      const arr = ['a', 'b', 'c'];
+      const result = Arr.indexOf(arr, 'd');
+
+      expect(result).toBe(-1);
+    });
+  });
+
+  describe('indexOfFrom', () => {
+    test('should find index of element from specified index', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.indexOfFrom(arr, 'b', 2);
+
+      expect(result).toBeGreaterThanOrEqual(0);
+      if (result !== -1) {
+        expectType<typeof result, SizeType.Arr>('=');
+        expect(result).toBe(3);
+      }
+    });
+
+    test('should return -1 when element not found from index', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.indexOfFrom(arr, 'a', 1);
+
+      expect(result).toBe(-1);
+    });
+
+    test('should find first occurrence when fromIndex is 0', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.indexOfFrom(arr, 'b', 0);
+
+      expect(result).toBe(1);
+    });
+
+    test('should handle negative fromIndex', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.indexOfFrom(arr, 'b', -2);
+
+      expect(result).toBe(3);
+    });
+
+    test('should handle fromIndex beyond array length', () => {
+      const arr = ['a', 'b', 'c'];
+      const result = Arr.indexOfFrom(arr, 'a', 10);
+
+      expect(result).toBe(-1);
+    });
+  });
+
+  describe('lastIndexOf', () => {
+    test('should find last index of element', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.lastIndexOf(arr, 'b');
+
+      expect(result).toBeGreaterThanOrEqual(0);
+      if (result !== -1) {
+        expectType<typeof result, SizeType.Arr>('=');
+        expect(result).toBe(3);
+      }
+    });
+
+    test('should return -1 for non-existent element', () => {
+      const arr = ['a', 'b', 'c'];
+      const result = Arr.lastIndexOf(arr, 'd');
+
+      expect(result).toBe(-1);
+    });
+  });
+
+  describe('lastIndexOfFrom', () => {
+    test('should find last index of element from specified index', () => {
+      const arr = ['a', 'b', 'c', 'b', 'e'];
+      const result = Arr.lastIndexOfFrom(arr, 'b', 2);
+
+      expect(result).toBeGreaterThanOrEqual(0);
+      if (result !== -1) {
+        expectType<typeof result, SizeType.Arr>('=');
+        expect(result).toBe(1);
+      }
+    });
+
+    test('should return -1 when element not found before index', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.lastIndexOfFrom(arr, 'b', 0);
+
+      expect(result).toBe(-1);
+    });
+
+    test('should find last occurrence when fromIndex covers all elements', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.lastIndexOfFrom(arr, 'b', 10);
+
+      expect(result).toBe(3);
+    });
+
+    test('should handle negative fromIndex', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.lastIndexOfFrom(arr, 'b', -1);
+
+      expect(result).toBe(3);
+    });
+
+    test('should handle fromIndex of 0', () => {
+      const arr = ['a', 'b', 'c', 'b'];
+      const result = Arr.lastIndexOfFrom(arr, 'a', 0);
+
+      expect(result).toBe(0);
+    });
+  });
+
+  describe('at', () => {
+    test('should handle very large positive indices', () => {
+      const array = [1, 2, 3];
+      const result = Arr.at(array, asUint32(1000));
+      expect(Optional.isNone(result)).toBe(true);
+    });
+
+    test('should handle very large negative indices', () => {
+      const array = [1, 2, 3];
+      const result = Arr.at(array, asInt32(-1000));
+      expect(Optional.isNone(result)).toBe(true);
+    });
+
+    test('should work with valid indices', () => {
+      const array = [10, 20, 30];
+      const result = Arr.at(array, 1);
+      expect(Optional.isSome(result)).toBe(true);
+      if (Optional.isSome(result)) {
+        expect(result.value).toBe(20);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,335 @@
+import { expectType } from '../expect-type.mjs';
+import { Arr } from './array-utils.mjs';
+
+describe('Arr set operations', () => {
+  describe('eq', () => {
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.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 = Arr.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 = Arr.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 = Arr.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 = Arr.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 = Arr.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 = Arr.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 = Arr.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', () => {
+        expect(result).toBe(true);
+      });
+    }
+  });
+
+  describe('isSubset', () => {
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [3, 2] as const;
+
+      const result = Arr.isSubset(ys, xs);
+
+      expectType<typeof result, boolean>('=');
+
+      test('case 1', () => {
+        expect(result).toBe(true);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [3, 2, 4] as const;
+
+      const result = Arr.isSubset(ys, xs);
+
+      expectType<typeof result, boolean>('=');
+
+      test('case 2', () => {
+        expect(result).toBe(false);
+      });
+    }
+  });
+
+  describe('isSuperset', () => {
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [3, 2] as const;
+
+      const result = Arr.isSuperset(ys, xs);
+
+      expectType<typeof result, boolean>('=');
+
+      test('case 1', () => {
+        expect(result).toBe(false);
+      });
+
+      const result2 = Arr.isSuperset(xs, ys);
+
+      test('case 2', () => {
+        expect(result2).toBe(true);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [3, 2, 4] as const;
+
+      const result = Arr.isSuperset(ys, xs);
+
+      expectType<typeof result, boolean>('=');
+
+      test('case 3', () => {
+        expect(result).toBe(false);
+      });
+    }
+  });
+
+  describe('setIntersection', () => {
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [2, 3, 4] as const;
+      const result = Arr.setIntersection(xs, ys);
+      expectType<typeof result, readonly (2 | 3)[]>('=');
+      test('should return the intersection of two number arrays', () => {
+        expect(result).toStrictEqual([2, 3]);
+      });
+    }
+    {
+      const xs = ['a', 'b', 'c'] as const;
+      const ys = ['b', 'c', 'd'] as const;
+      const result = Arr.setIntersection(xs, ys);
+      expectType<typeof result, readonly ('b' | 'c')[]>('=');
+      test('should return the intersection of two string arrays', () => {
+        expect(result).toStrictEqual(['b', 'c']);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [4, 5, 6] as const;
+      const result = Arr.setIntersection(xs, ys);
+      expectType<typeof result, readonly never[]>('=');
+      test('should return an empty array if there is no intersection', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [] as const;
+      const result = Arr.setIntersection(xs, ys);
+      expectType<typeof result, readonly never[]>('=');
+      test('should return an empty array if one array is empty', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.setIntersection(xs, ys);
+      expectType<typeof result, readonly never[]>('=');
+      test('should return an empty array if the first array is empty', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+  });
+
+  describe('setDifference', () => {
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [2, 3, 4] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4)[]>('=');
+      test('should return the difference xs - ys for number arrays', () => {
+        expect(result).toStrictEqual([1]);
+      });
+    }
+    {
+      const xs = ['a', 'b', 'c'] as const;
+      const ys = ['b', 'c', 'd'] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly ('a' | 'b' | 'c' | 'd')[]>('=');
+      test('should return the difference xs - ys for string arrays', () => {
+        expect(result).toStrictEqual(['a']);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
+      test('should return an empty array if xs is a subset of ys', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [4, 5, 6] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
+      test('should return xs if there is no intersection', () => {
+        expect(result).toStrictEqual([1, 2, 3]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
+      test('should return xs if ys is empty', () => {
+        expect(result).toStrictEqual([1, 2, 3]);
+      });
+    }
+    {
+      const xs = [] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.setDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
+      test('should return an empty array if xs is empty', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+  });
+
+  describe('sortedNumSetDifference', () => {
+    {
+      const xs = [1, 2, 3, 5] as const;
+      const ys = [2, 3, 4] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
+      test('should return the difference for sorted number arrays (xs - ys)', () => {
+        expect(result).toStrictEqual([1, 5]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
+      test('should return an empty array if sets are equal', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [4, 5, 6] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
+      test('should return xs if no common elements', () => {
+        expect(result).toStrictEqual([1, 2, 3]);
+      });
+    }
+    {
+      const xs = [4, 5, 6] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5 | 6)[]>('=');
+      test('should return xs if no common elements (ys < xs)', () => {
+        expect(result).toStrictEqual([4, 5, 6]);
+      });
+    }
+    {
+      const xs = [1, 2, 3, 4, 5] as const;
+      const ys = [2, 4] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
+      test('should return correct difference when ys is subset of xs', () => {
+        expect(result).toStrictEqual([1, 3, 5]);
+      });
+    }
+    {
+      const xs = [2, 4] as const;
+      const ys = [1, 2, 3, 4, 5] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3 | 4 | 5)[]>('=');
+      test('should return empty array when xs is subset of ys', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [] as const;
+      const ys = [1, 2, 3] as const;
+      const result = Arr.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', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+    {
+      const xs = [1, 2, 3] as const;
+      const ys = [] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
+      test('should return xs if ys is empty', () => {
+        expect(result).toStrictEqual([1, 2, 3]);
+      });
+    }
+    {
+      const xs = [] as const;
+      const ys = [] as const;
+      const result = Arr.sortedNumSetDifference(xs, ys);
+      expectType<typeof result, readonly never[]>('='); // Type is `readonly number[]`
+      test('should return an empty array if both are empty', () => {
+        expect(result).toStrictEqual([]);
+      });
+    }
+  });
+});

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

@@ -0,0 +1,113 @@
+import { asInt32, asUint32 } from '../number/index.mjs';
+import { Arr } from './array-utils.mjs';
+
+describe('Arr', () => {
+  describe('sliceClamped', () => {
+    const list = [0, 1, 2, 3, 4] as const;
+
+    test.each([
+      {
+        start: 0,
+        end: 5,
+        expected: [0, 1, 2, 3, 4],
+      }, // normal
+      {
+        start: 0,
+        end: 6,
+        expected: [0, 1, 2, 3, 4],
+      }, // one side overflow
+      {
+        start: -1,
+        end: 5,
+        expected: [0, 1, 2, 3, 4],
+      }, // one side overflow
+      {
+        start: -1,
+        end: 6,
+        expected: [0, 1, 2, 3, 4],
+      }, // both sides overflow
+      {
+        start: 0,
+        end: 3,
+        expected: [0, 1, 2],
+      }, // normal
+      {
+        start: 1,
+        end: 3,
+        expected: [1, 2],
+      }, // normal
+      {
+        start: -1,
+        end: 3,
+        expected: [0, 1, 2],
+      }, // one side overflow
+      {
+        start: 3,
+        end: 5,
+        expected: [3, 4],
+      }, // normal
+      {
+        start: 3,
+        end: 6,
+        expected: [3, 4],
+      }, // one side overflow
+      {
+        start: 4,
+        end: 3,
+        expected: [],
+      }, // start > end
+      {
+        start: 0,
+        end: -1,
+        expected: [],
+      }, // start > end
+      {
+        start: -1,
+        end: -2,
+        expected: [],
+      }, // start > end
+      {
+        start: 6,
+        end: 9,
+        expected: [],
+      },
+      {
+        start: 6,
+        end: 3,
+        expected: [],
+      },
+    ] as const)('sliceClamped($start, $end)', ({ start, end, expected }) => {
+      expect(Arr.sliceClamped(list, start, end)).toStrictEqual(expected);
+    });
+
+    test('should slice with clamped indices', () => {
+      const array = [1, 2, 3, 4, 5];
+      const result = Arr.sliceClamped(array, 1, 3);
+      expect(result).toStrictEqual([2, 3]);
+    });
+
+    test('should clamp start index below 0', () => {
+      const array = [1, 2, 3, 4, 5];
+      const result = Arr.sliceClamped(array, -10, 3);
+      expect(result).toStrictEqual([1, 2, 3]);
+    });
+
+    test('should clamp end index above length', () => {
+      const array = [1, 2, 3, 4, 5];
+      const result = Arr.sliceClamped(array, asUint32(2), asUint32(100));
+      expect(result).toStrictEqual([3, 4, 5]);
+    });
+
+    test('should work with both indices out of range', () => {
+      const array = [1, 2, 3];
+      const result = Arr.sliceClamped(array, asInt32(-10), asUint32(100));
+      expect(result).toStrictEqual([1, 2, 3]);
+    });
+
+    test('should work with empty array', () => {
+      const array: readonly number[] = [];
+      const result = Arr.sliceClamped(array, 0, 5);
+      expect(result).toStrictEqual([]);
+    });
+  });
+});