ts-data-forge 3.3.0 → 3.3.1

package/src/array/{array-utils-creation.test.mts → impl/array-utils-creation.test.mts}

@@ -1,102 +1,111 @@
-import { expectType } from '../expect-type.mjs';
-import { range } from '../iterator/index.mjs';
-import { asNonZeroSafeInt, asUint32 } from '../number/index.mjs';
-import { Arr } from './array-utils.mjs';
+import { expectType } from '../../expect-type.mjs';
+import { range as rangeIterator } from '../../iterator/index.mjs';
+import { asNonZeroSafeInt, asUint32 } from '../../number/index.mjs';
+import {
+  copy,
+  create,
+  generate,
+  generateAsync,
+  newArray,
+  range,
+  seq,
+  zeros,
+} from './array-utils-creation.mjs';
 
 describe('Arr creations', () => {
   describe('zeros', () => {
     test('fixed length', () => {
-      const result = Arr.zeros(3);
+      const result = zeros(3);
       expectType<typeof result, readonly [0, 0, 0]>('=');
       expect(result).toStrictEqual([0, 0, 0]);
     });
 
     test('fixed length (empty)', () => {
-      const result = Arr.zeros(0);
+      const result = zeros(0);
       expectType<typeof result, readonly []>('=');
       expect(result).toStrictEqual([]);
     });
 
     test('unknown length', () => {
       const n: number = 3;
-      const result = Arr.zeros(asUint32(n));
+      const result = zeros(asUint32(n));
       expectType<typeof result, readonly 0[]>('=');
       expect(result).toStrictEqual([0, 0, 0]);
     });
 
     test('should create array with zero length', () => {
-      const result = Arr.zeros(0);
+      const result = zeros(0);
       expect(result).toStrictEqual([]);
       expect(result).toHaveLength(0);
     });
 
     test('should create large arrays', () => {
-      const result = Arr.zeros(asUint32(1000));
+      const result = zeros(asUint32(1000));
       expect(result).toHaveLength(1000);
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       expect(result.every((x) => x === 0)).toBe(true);
     });
 
     test('should work with curried version', () => {
-      const createTenZeros = Arr.zeros(10);
+      const createTenZeros = zeros(10);
       expect(createTenZeros).toStrictEqual([0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
     });
   });
 
   describe('seq', () => {
     test('fixed length', () => {
-      const result = Arr.seq(5);
+      const result = seq(5);
       expectType<typeof result, readonly [0, 1, 2, 3, 4]>('=');
       expect(result).toStrictEqual([0, 1, 2, 3, 4]);
     });
 
     test('fixed length (empty)', () => {
-      const result = Arr.seq(0);
+      const result = seq(0);
       expectType<typeof result, readonly []>('=');
       expect(result).toStrictEqual([]);
     });
 
     test('unknown length', () => {
       const n: number = 3;
-      const result = Arr.seq(asUint32(n));
+      const result = seq(asUint32(n));
       expectType<typeof result, readonly SizeType.Arr[]>('=');
       expect(result).toStrictEqual([0, 1, 2]);
     });
 
     test('should create sequence with zero length', () => {
-      const result = Arr.seq(0);
+      const result = seq(0);
       expect(result).toStrictEqual([]);
     });
 
     test('should create sequence with large length', () => {
-      const result = Arr.seq(asUint32(100));
+      const result = seq(asUint32(100));
       expect(result).toHaveLength(100);
       expect(result[0]).toBe(0);
       expect(result[99]).toBe(99);
     });
 
     test('should work with curried version', () => {
-      const createFiveSeq = Arr.seq(5);
+      const createFiveSeq = seq(5);
       expect(createFiveSeq).toStrictEqual([0, 1, 2, 3, 4]);
     });
   });
 
   describe('create', () => {
     test('fixed length with primitive value', () => {
-      const result = Arr.create(3, 'a');
+      const result = create(3, 'a');
       expectType<typeof result, readonly ['a', 'a', 'a']>('=');
       expect(result).toStrictEqual(['a', 'a', 'a']);
     });
 
     test('fixed length with null', () => {
-      const result = Arr.create(2, null);
+      const result = create(2, null);
       expectType<typeof result, readonly [null, null]>('=');
       expect(result).toStrictEqual([null, null]);
     });
 
     test('fixed length with object (shallow copy)', () => {
       const obj = { id: 1 };
-      const result = Arr.create(2, obj);
+      const result = create(2, obj);
       expectType<typeof result, readonly [{ id: number }, { id: number }]>(
         '~=',
       );
@@ -106,40 +115,40 @@ describe('Arr creations', () => {
     });
 
     test('fixed length (empty)', () => {
-      const result = Arr.create(0, 123);
+      const result = create(0, 123);
       expectType<typeof result, readonly []>('=');
       expect(result).toStrictEqual([]);
     });
 
     test('unknown length', () => {
       const n: number = 2;
-      const result = Arr.create(asUint32(n), true);
+      const result = create(asUint32(n), true);
       expectType<typeof result, readonly true[]>('=');
       expect(result).toStrictEqual([true, true]);
     });
 
     test('should create array with function values', () => {
       const fn = (): string => 'test';
-      const result = Arr.create(3, fn);
+      const result = create(3, fn);
       expect(result).toStrictEqual([fn, fn, fn]);
       expect(result[0]).toBe(fn);
     });
 
     test('should create array with object values', () => {
       const obj = { a: 1 };
-      const result = Arr.create(2, obj);
+      const result = create(2, obj);
       expect(result).toStrictEqual([obj, obj]);
       expect(result[0]).toBe(obj); // Same reference
     });
 
     test('should create empty array when length is 0', () => {
-      const result = Arr.create(0, 'value');
+      const result = create(0, 'value');
       expect(result).toStrictEqual([]);
     });
 
     test('newArray is alias for create', () => {
-      const created1 = Arr.create(3, 'test');
-      const created2 = Arr.newArray(3, 'test');
+      const created1 = create(3, 'test');
+      const created2 = newArray(3, 'test');
       expect(created1).toStrictEqual(created2);
       expect(created1).toStrictEqual(['test', 'test', 'test']);
     });
@@ -148,7 +157,7 @@ describe('Arr creations', () => {
   describe('copy', () => {
     test('should create a shallow copy of an array of primitives', () => {
       const original = [1, 2, 3] as const;
-      const copied = Arr.copy(original);
+      const copied = copy(original);
       expectType<typeof copied, readonly [1, 2, 3]>('=');
       expect(copied).toStrictEqual(original);
       expect(copied).not.toBe(original);
@@ -158,7 +167,7 @@ describe('Arr creations', () => {
       const obj1 = { id: 1 };
       const obj2 = { id: 2 };
       const original = [obj1, obj2] as const;
-      const copied = Arr.copy(original);
+      const copied = copy(original);
 
       expectType<typeof copied, readonly [{ id: number }, { id: number }]>('=');
       expect(copied).toStrictEqual(original);
@@ -169,7 +178,7 @@ describe('Arr creations', () => {
 
     test('should create a copy of an empty array', () => {
       const original = [] as const;
-      const copied = Arr.copy(original);
+      const copied = copy(original);
       expectType<typeof copied, readonly []>('=');
       expect(copied).toStrictEqual(original);
       expect(copied).not.toBe(original);
@@ -177,7 +186,7 @@ describe('Arr creations', () => {
 
     test('should create a copy of an array with mixed types', () => {
       const original = [1, 'hello', true, null, undefined] as const;
-      const copied = Arr.copy(original);
+      const copied = copy(original);
       expectType<typeof copied, readonly [1, 'hello', true, null, undefined]>(
         '=',
       );
@@ -187,7 +196,7 @@ describe('Arr creations', () => {
 
     test('should handle unknown array type', () => {
       const mut_original: number[] = [1, 2, 3];
-      const copied = Arr.copy(mut_original);
+      const copied = copy(mut_original);
       expectType<typeof copied, number[]>('=');
       expect(copied).toStrictEqual(mut_original);
       expect(copied).not.toBe(mut_original);
@@ -199,7 +208,7 @@ describe('Arr creations', () => {
 
     test('should create shallow copy of array', () => {
       const original = [1, 2, 3] as const;
-      const copied = Arr.copy(original);
+      const copied = copy(original);
       expectType<typeof copied, readonly [1, 2, 3]>('=');
       expect(copied).toStrictEqual(original);
       expect(copied).not.toBe(original);
@@ -207,14 +216,14 @@ describe('Arr creations', () => {
 
     test('should work with empty array', () => {
       const empty = [] as const;
-      const copied = Arr.copy(empty);
+      const copied = copy(empty);
       expect(copied).toStrictEqual([]);
       expect(copied).not.toBe(empty);
     });
 
     test('should preserve array type', () => {
       const mixed = [1, 'hello', true] as const;
-      const copied = Arr.copy(mixed);
+      const copied = copy(mixed);
       expectType<typeof copied, readonly [1, 'hello', true]>('=');
       expect(copied).toStrictEqual([1, 'hello', true]);
     });
@@ -222,51 +231,51 @@ describe('Arr creations', () => {
 
   describe('range', () => {
     test('start < end, step = 1 (default)', () => {
-      const result = Arr.range(1, 5);
+      const result = range(1, 5);
       expectType<typeof result, readonly [1, 2, 3, 4]>('=');
       expect(result).toStrictEqual([1, 2, 3, 4]);
     });
 
     test('start === end, step = 1 (default)', () => {
-      const result = Arr.range(3, 3);
+      const result = range(3, 3);
       expectType<typeof result, readonly []>('=');
       expect(result).toStrictEqual([]);
     });
 
     test('start > end, step = 1 (default)', () => {
-      const result = Arr.range(5, 1);
+      const result = range(5, 1);
       expectType<typeof result, readonly []>('=');
       expect(result).toStrictEqual([]);
     });
 
     test('start < end, step > 1', () => {
-      const result = Arr.range(0, 6, 2);
+      const result = range(0, 6, 2);
       expectType<typeof result, readonly SafeUint[]>('='); // Type is less specific with explicit step
       expect(result).toStrictEqual([0, 2, 4]);
     });
 
     test('start < end, step > 1, not reaching end', () => {
-      const result = Arr.range(0, 5, 2);
+      const result = range(0, 5, 2);
       expect(result).toStrictEqual([0, 2, 4]);
     });
 
     test('start > end, step < 0', () => {
-      const result = Arr.range(5, 0, -1);
+      const result = range(5, 0, -1);
       expect(result).toStrictEqual([5, 4, 3, 2, 1]);
     });
 
     test('start > end, step < 0, not reaching end', () => {
-      const result = Arr.range(5, 1, -2);
+      const result = range(5, 1, -2);
       expect(result).toStrictEqual([5, 3]);
     });
 
     test('start < end, step < 0 (empty result)', () => {
-      const result = Arr.range(1, 5, -1);
+      const result = range(1, 5, -1);
       expect(result).toStrictEqual([]);
     });
 
     test('start > end, step > 0 (empty result)', () => {
-      const result = Arr.range(5, 1, 1);
+      const result = range(5, 1, 1);
       expect(result).toStrictEqual([]);
     });
 
@@ -274,7 +283,7 @@ describe('Arr creations', () => {
       const start: number = 1;
       const end: number = 4;
       const step: number = 1;
-      const result = Arr.range(
+      const result = range(
         asUint32(start),
         asUint32(end),
         asNonZeroSafeInt(step),
@@ -284,7 +293,7 @@ describe('Arr creations', () => {
     });
 
     test('range(1, 3)', () => {
-      const result = Arr.range(1, 3);
+      const result = range(1, 3);
 
       expectType<typeof result, readonly [1, 2]>('=');
 
@@ -292,7 +301,7 @@ describe('Arr creations', () => {
     });
 
     test('range(1, 3, 1)', () => {
-      const result = Arr.range(1, 3, 1);
+      const result = range(1, 3, 1);
 
       expectType<typeof result, readonly [1, 2]>('=');
 
@@ -300,7 +309,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0, 0)', () => {
-      const result = Arr.range(0, 0);
+      const result = range(0, 0);
 
       expectType<typeof result, readonly []>('=');
 
@@ -308,7 +317,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0, 1)', () => {
-      const result = Arr.range(0, 1);
+      const result = range(0, 1);
 
       expectType<typeof result, readonly [0]>('=');
 
@@ -316,7 +325,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0, -1)', () => {
-      const result = Arr.range(0, -1);
+      const result = range(0, -1);
 
       expectType<typeof result, readonly SafeInt[]>('=');
 
@@ -324,7 +333,7 @@ describe('Arr creations', () => {
     });
 
     test('range(SmallUint, SmallUint)', () => {
-      const result = Arr.range<SmallUint, SmallUint>(0, 1);
+      const result = range<SmallUint, SmallUint>(0, 1);
 
       expectType<
         typeof result,
@@ -375,7 +384,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0 | 1 | 2, 1 | 2 | 3)', () => {
-      const result = Arr.range<0 | 1 | 2, 1 | 2 | 3>(0, 1);
+      const result = range<0 | 1 | 2, 1 | 2 | 3>(0, 1);
 
       expectType<typeof result, readonly (0 | 1 | 2)[]>('=');
 
@@ -383,7 +392,7 @@ describe('Arr creations', () => {
     });
 
     test('range(2|3, 5|6|7)', () => {
-      const result = Arr.range<2 | 3, 5 | 6 | 7>(2, 5);
+      const result = range<2 | 3, 5 | 6 | 7>(2, 5);
 
       expectType<typeof result, readonly (2 | 3 | 4 | 5 | 6)[]>('=');
 
@@ -391,7 +400,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0, 10, 2)', () => {
-      const result = Arr.range(0, 10, 2);
+      const result = range(0, 10, 2);
 
       expectType<typeof result, readonly SafeUint[]>('=');
 
@@ -399,7 +408,7 @@ describe('Arr creations', () => {
     });
 
     test('range(0, 11, 2)', () => {
-      const result = Arr.range(0, 11, 2);
+      const result = range(0, 11, 2);
 
       expectType<typeof result, readonly SafeUint[]>('=');
 
@@ -407,7 +416,7 @@ describe('Arr creations', () => {
     });
 
     test('range(1, 12, 2)', () => {
-      const result = Arr.range(1, 12, 2);
+      const result = range(1, 12, 2);
 
       expectType<typeof result, readonly SafeUint[]>('=');
 
@@ -418,25 +427,25 @@ describe('Arr creations', () => {
     // and doesn't validate inputs in this way
 
     test('should handle range with step larger than difference', () => {
-      const result = Arr.range(0, 5, 10);
+      const result = range(0, 5, 10);
       expect(result).toStrictEqual([0]);
     });
 
     test('should handle negative step with increasing range', () => {
-      const result = Arr.range(0, 5, -1);
+      const result = range(0, 5, -1);
       expect(result).toStrictEqual([]); // Should be empty when step direction conflicts
     });
 
     test('should work with basic range functionality', () => {
       // Test basic range functionality without currying assumptions
-      const result = Arr.range(0, 5, 1);
+      const result = range(0, 5, 1);
       expect(result).toStrictEqual([0, 1, 2, 3, 4]);
     });
   });
 
   describe('generate', () => {
     test('basic generator usage', () => {
-      const result = Arr.generate<number>(function* () {
+      const result = generate<number>(function* () {
         yield 1;
         yield 2;
         yield 3;
@@ -447,7 +456,7 @@ describe('Arr creations', () => {
     });
 
     test('generator with yield*', () => {
-      const result = Arr.generate<number>(function* () {
+      const result = generate<number>(function* () {
         yield 1;
         yield* [2, 3];
         yield 4;
@@ -458,7 +467,7 @@ describe('Arr creations', () => {
     });
 
     test('empty generator', () => {
-      const result = Arr.generate<string>(function* () {
+      const result = generate<string>(function* () {
         // No yields
       });
 
@@ -468,7 +477,7 @@ describe('Arr creations', () => {
 
     test('generator with conditional logic', () => {
       const condition = true as boolean; // Simulating a condition
-      const result = Arr.generate<number>(function* () {
+      const result = generate<number>(function* () {
         yield 1;
         if (condition) {
           yield 2;
@@ -482,7 +491,7 @@ describe('Arr creations', () => {
 
     test('generator with early return', () => {
       const condition = true as boolean; // Simulating a condition
-      const result = Arr.generate<number>(function* () {
+      const result = generate<number>(function* () {
         yield 1;
         if (condition) {
           return; // Early return is OK
@@ -495,7 +504,7 @@ describe('Arr creations', () => {
     });
 
     test('generator with complex data types', () => {
-      const result = Arr.generate<{ id: number; name: string }>(function* () {
+      const result = generate<{ id: number; name: string }>(function* () {
         yield { id: 1, name: 'Alice' };
         yield { id: 2, name: 'Bob' };
       });
@@ -508,7 +517,7 @@ describe('Arr creations', () => {
     });
 
     test('generator with different types', () => {
-      const result = Arr.generate<string | number>(function* () {
+      const result = generate<string | number>(function* () {
         yield 'hello';
         yield 42;
         yield 'world';
@@ -519,8 +528,8 @@ describe('Arr creations', () => {
     });
 
     test('generator with loops', () => {
-      const result = Arr.generate<number>(function* () {
-        for (const i of range(3)) {
+      const result = generate<number>(function* () {
+        for (const i of rangeIterator(3)) {
           yield i;
         }
       });
@@ -530,11 +539,51 @@ describe('Arr creations', () => {
     });
   });
 
-  describe('size/length', () => {
-    test('length should be alias for size', () => {
-      const array = [1, 2, 3];
-      expect(Arr.length(array)).toBe(Arr.size(array));
-      expect(Arr.length(array)).toBe(3);
+  describe('generateAsync', () => {
+    test('should generate array from async generator', async () => {
+      // eslint-disable-next-line @typescript-eslint/require-await
+      const result = await generateAsync<number>(async function* () {
+        yield 1;
+        yield 2;
+        yield 3;
+      });
+
+      expectType<typeof result, readonly number[]>('=');
+      expect(result).toStrictEqual([1, 2, 3]);
+    });
+
+    test('should handle async operations in generator', async () => {
+      const result = await generateAsync<string>(async function* () {
+        await Promise.resolve();
+        yield 'a';
+        await Promise.resolve();
+        yield 'b';
+        await Promise.resolve();
+        yield 'c';
+      });
+
+      expect(result).toStrictEqual(['a', 'b', 'c']);
+    });
+
+    test('should generate empty array from empty async generator', async () => {
+      const result = await generateAsync<number>(async function* () {
+        // Empty generator
+      });
+
+      expect(result).toStrictEqual([]);
+    });
+
+    test('should handle async generator with delays', async () => {
+      const result = await generateAsync<number>(async function* () {
+        // eslint-disable-next-line functional/no-let
+        for (let i = 0; i < 3; i++) {
+          // eslint-disable-next-line no-promise-executor-return, no-await-in-loop
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          yield i;
+        }
+      });
+
+      expect(result).toStrictEqual([0, 1, 2]);
     });
   });
 });

package/src/array/impl/array-utils-element-access.mts

@@ -0,0 +1,115 @@
+import { Optional, pipe } from '../../functional/index.mjs';
+
+/**
+ * Safely retrieves an element at a given index from an array, returning an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters: readonly string[] = ['a', 'b', 'c'];
+ *
+ * const two = Arr.at(letters, 1);
+ * const last = Arr.at(-1)(letters);
+ * const missing = Arr.at(letters, 5);
+ *
+ * assert.deepStrictEqual(two, Optional.some('b'));
+ * assert.deepStrictEqual(last, Optional.some('c'));
+ * assert.deepStrictEqual(missing, Optional.none);
+ * ```
+ */
+export function at<const Ar extends readonly unknown[]>(
+  array: Ar,
+  index: ArgArrayIndexWithNegative<Ar>,
+): Optional<Ar[number]>;
+
+// Curried version
+
+export function at(
+  index: SizeType.ArgArrWithNegative,
+): <E>(array: readonly E[]) => Optional<E>;
+
+export function at<E>(
+  ...args:
+    | readonly [array: readonly E[], index: SizeType.ArgArrWithNegative]
+    | readonly [index: SizeType.ArgArrWithNegative]
+): Optional<E> | ((array: readonly E[]) => Optional<E>) {
+  switch (args.length) {
+    case 2: {
+      const [array, index] = args;
+      return pipe(index < 0 ? array.length + index : index).map(
+        (normalizedIndex) =>
+          normalizedIndex < 0 || normalizedIndex >= array.length
+            ? Optional.none
+            : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+              Optional.some(array[normalizedIndex]!),
+      ).value;
+    }
+    case 1: {
+      const [index] = args;
+      return (array) => at(array, index);
+    }
+  }
+}
+
+/**
+ * Returns the first element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const users = [{ id: 1 }, { id: 2 }];
+ * const empty: { id: number }[] = [];
+ *
+ * const first = Arr.head(users);
+ * const none = Arr.head(empty);
+ *
+ * assert.deepStrictEqual(first, Optional.some({ id: 1 }));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+export const head = <const Ar extends readonly unknown[]>(
+  array: Ar,
+): Ar extends readonly []
+  ? Optional.None
+  : Ar extends readonly [infer E, ...unknown[]]
+    ? Optional.Some<E>
+    : Ar extends NonEmptyArray<infer E>
+      ? Optional.Some<E>
+      : Optional<Ar[number]> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (array.length === 0 ? Optional.none : Optional.some(array.at(0))) as never;
+
+/**
+ * Returns the last element of an array as an Optional.
+ *
+ * @example
+ *
+ * ```ts
+ * const queue = ['first', 'second'];
+ * const emptyQueue: string[] = [];
+ *
+ * const lastValue = Arr.last(queue);
+ * const none = Arr.last(emptyQueue);
+ *
+ * assert.deepStrictEqual(lastValue, Optional.some('second'));
+ * assert.deepStrictEqual(none, Optional.none);
+ * ```
+ */
+export const last = <const Ar extends readonly unknown[]>(
+  array: Ar,
+): Ar extends readonly []
+  ? Optional.None
+  : Ar extends readonly [...unknown[], infer E]
+    ? Optional.Some<E>
+    : Ar extends NonEmptyArray<infer E>
+      ? Optional.Some<E>
+      : Optional<Ar[number]> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  (array.length === 0 ? Optional.none : Optional.some(array.at(-1))) as never;
+
+/**
+ * Alias for `head`.
+ *
+ * @see {@link head}
+ */
+export const first = head;