ts-data-forge 3.3.0 → 4.0.0

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

@@ -0,0 +1,434 @@
+import { asPositiveUint32 } from '../../number/index.mjs';
+import { castMutable } from '../../others/index.mjs';
+import { copy, create } from './array-utils-creation.mjs';
+
+/**
+ * Returns a new array with an element at the specified index replaced.
+ *
+ * @example
+ *
+ * ```ts
+ * const scores: number[] = [10, 20, 30];
+ *
+ * const updated = Arr.set(scores, 1, 25);
+ *
+ * assert.deepStrictEqual(updated, [10, 25, 30]);
+ * ```
+ */
+export function set<const Ar extends readonly unknown[], const V = Ar[number]>(
+  array: Ar,
+  index: ArgArrayIndex<Ar>,
+  newValue: V,
+): IsFixedLengthList<Ar> extends true
+  ? Readonly<{ [K in keyof Ar]: Ar[K] | V }>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<Ar[number] | V>
+    : readonly (Ar[number] | V)[];
+
+// curried version
+export function set<const V>(
+  index: SizeType.ArgArr,
+  newValue: V,
+): <const Ar extends readonly unknown[]>(
+  array: Ar,
+) => IsFixedLengthList<Ar> extends true
+  ? Readonly<{ [K in keyof Ar]: Ar[K] | V }>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<Ar[number] | V>
+    : readonly (Ar[number] | V)[];
+
+export function set<E, const V = E>(
+  ...args:
+    | readonly [array: readonly E[], index: SizeType.ArgArr, newValue: V]
+    | readonly [index: SizeType.ArgArr, newValue: V]
+): readonly (E | V)[] | ((array: readonly E[]) => readonly (E | V)[]) {
+  switch (args.length) {
+    case 3: {
+      const [array, index, newValue] = args;
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      return (array as (E | V)[]).with(index, newValue);
+    }
+    case 2: {
+      const [index, newValue] = args;
+      return (array) => set(array, index, newValue);
+    }
+  }
+}
+
+/**
+ * Returns a new array with an element at the specified index updated by applying a function.
+ *
+ * @example
+ *
+ * ```ts
+ * const temperatures: number[] = [20, 21, 22];
+ *
+ * const increased = Arr.toUpdated(temperatures, 1, (value) => value + 5);
+ * const incrementLast = Arr.toUpdated<number>(
+ *   2,
+ *   (value) => value + 1,
+ * )(temperatures);
+ *
+ * assert.deepStrictEqual(increased, [20, 26, 22]);
+ * assert.deepStrictEqual(incrementLast, [20, 21, 23]);
+ * ```
+ */
+export function toUpdated<
+  const Ar extends readonly unknown[],
+  const V = Ar[number],
+>(
+  array: Ar,
+  index: ArgArrayIndex<Ar>,
+  updater: (prev: Ar[number]) => V,
+): IsFixedLengthList<Ar> extends true
+  ? Readonly<{ [K in keyof Ar]: Ar[K] | V }>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<Ar[number] | V>
+    : readonly (Ar[number] | V)[];
+
+// curried version
+export function toUpdated<E, const V = E>(
+  index: SizeType.ArgArr,
+  updater: (prev: E) => V,
+): <const Ar extends readonly E[]>(
+  array: Ar,
+) => IsFixedLengthList<Ar> extends true
+  ? Readonly<{ [K in keyof Ar]: Ar[K] | V }>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<Ar[number] | V>
+    : readonly (Ar[number] | V)[];
+
+export function toUpdated<E, V = E>(
+  ...args:
+    | readonly [
+        array: readonly E[],
+        index: SizeType.ArgArr,
+        updater: (prev: E) => V,
+      ]
+    | readonly [index: SizeType.ArgArr, updater: (prev: E) => V]
+): readonly (E | V)[] | ((array: readonly E[]) => readonly (E | V)[]) {
+  switch (args.length) {
+    case 3: {
+      const [array, index, updater] = args;
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion, total-functions/no-unsafe-type-assertion
+      return (array as (E | V)[]).with(index, updater(array[index]!));
+    }
+    case 2: {
+      const [index, updater] = args;
+      return (array) => toUpdated(array, index, updater);
+    }
+  }
+}
+
+/**
+ * Returns a new array with a value inserted at the specified index.
+ *
+ * @example
+ *
+ * ```ts
+ * const numbers = [1, 2, 4] as const;
+ *
+ * const withThree = Arr.toInserted(numbers, 2, 3);
+ * const appendFive = Arr.toInserted(3, 5)(numbers);
+ *
+ * assert.deepStrictEqual(withThree, [1, 2, 3, 4]);
+ * assert.deepStrictEqual(appendFive, [1, 2, 4, 5]);
+ * ```
+ */
+export function toInserted<
+  const Ar extends readonly unknown[],
+  const V = Ar[number],
+>(
+  array: Ar,
+  index: ArgArrayIndexWithNegative<Ar>,
+  newValue: V,
+): IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<CastToNumber<Increment<Ar['length']>>, Ar[number] | V>
+  : NonEmptyArray<Ar[number] | V>;
+
+// curried version
+export function toInserted<const V>(
+  index: SizeType.ArgArrWithNegative,
+  newValue: V,
+): <const Ar extends readonly unknown[]>(
+  array: Ar,
+) => IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<CastToNumber<Increment<Ar['length']>>, Ar[number] | V>
+  : NonEmptyArray<Ar[number] | V>;
+
+export function toInserted<E, const V = E>(
+  ...args:
+    | readonly [
+        array: readonly E[],
+        index: SizeType.ArgArrWithNegative,
+        newValue: V,
+      ]
+    | readonly [index: SizeType.ArgArrWithNegative, newValue: V]
+): NonEmptyArray<E | V> | ((array: readonly E[]) => NonEmptyArray<E | V>) {
+  switch (args.length) {
+    case 3: {
+      const [array, index, newValue] = args;
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      return (array as readonly (E | V)[]).toSpliced(
+        index,
+        0,
+        newValue,
+      ) as unknown as NonEmptyArray<E | V>;
+    }
+    case 2: {
+      const [index, newValue] = args;
+      return (array) => toInserted(array, index, newValue);
+    }
+  }
+}
+
+type CastToNumber<T> = T extends number ? T : never;
+
+/**
+ * Returns a new array with the element at the specified index removed.
+ *
+ * @example
+ *
+ * ```ts
+ * const letters = ['a', 'b', 'c', 'd'] as const;
+ *
+ * const withoutSecond = Arr.toRemoved(letters, 1);
+ * const withoutFirstCurried = Arr.toRemoved(0)(letters);
+ *
+ * assert.deepStrictEqual(withoutSecond, ['a', 'c', 'd']);
+ * assert.deepStrictEqual(withoutFirstCurried, ['b', 'c', 'd']);
+ * ```
+ */
+export function toRemoved<const Ar extends readonly unknown[]>(
+  array: Ar,
+  index: ArgArrayIndexWithNegative<Ar>,
+): readonly Ar[number][];
+
+export function toRemoved(
+  index: SizeType.ArgArrWithNegative,
+): <E>(array: readonly E[]) => readonly E[];
+
+export function toRemoved<E>(
+  ...args:
+    | readonly [array: readonly E[], index: SizeType.ArgArrWithNegative]
+    | readonly [index: SizeType.ArgArrWithNegative]
+): readonly E[] | ((array: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [array, index] = args;
+      return array.toSpliced(index, 1);
+    }
+    case 1: {
+      const [index] = args;
+      return (array) => toRemoved(array, index);
+    }
+  }
+}
+
+/**
+ * Returns a new array with a value appended to the end.
+ *
+ * @example
+ *
+ * ```ts
+ * const base = [1, 2] as const;
+ *
+ * const appended = Arr.toPushed(base, 3);
+ * const appendedCurried = Arr.toPushed(4)(base);
+ *
+ * assert.deepStrictEqual(appended, [1, 2, 3]);
+ * assert.deepStrictEqual(appendedCurried, [1, 2, 4]);
+ * ```
+ */
+export function toPushed<const Ar extends readonly unknown[], const V>(
+  array: Ar,
+  newValue: V,
+): readonly [...Ar, V];
+
+export function toPushed<const V>(
+  newValue: V,
+): <const Ar extends readonly unknown[]>(array: Ar) => readonly [...Ar, V];
+
+export function toPushed<const Ar extends readonly unknown[], const V>(
+  ...args: readonly [array: Ar, newValue: V] | readonly [newValue: V]
+): readonly [...Ar, V] | ((array: Ar) => readonly [...Ar, V]) {
+  switch (args.length) {
+    case 2: {
+      const [array, newValue] = args;
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      return array.toSpliced(array.length, 0, newValue) as unknown as readonly [
+        ...Ar,
+        V,
+      ];
+    }
+    case 1: {
+      const [newValue] = args;
+      return (array) => toPushed(array, newValue);
+    }
+  }
+}
+
+/**
+ * Returns a new array with a value prepended to the beginning.
+ *
+ * @example
+ *
+ * ```ts
+ * const base = [2, 3] as const;
+ *
+ * const prefixed = Arr.toUnshifted(base, 1);
+ * const prefixedCurried = Arr.toUnshifted(0)(base);
+ *
+ * assert.deepStrictEqual(prefixed, [1, 2, 3]);
+ * assert.deepStrictEqual(prefixedCurried, [0, 2, 3]);
+ * ```
+ */
+export function toUnshifted<const Ar extends readonly unknown[], const V>(
+  array: Ar,
+  newValue: V,
+): readonly [V, ...Ar];
+
+export function toUnshifted<const V>(
+  newValue: V,
+): <const Ar extends readonly unknown[]>(array: Ar) => readonly [V, ...Ar];
+
+export function toUnshifted<Ar extends readonly unknown[], const V>(
+  ...args: readonly [array: Ar, newValue: V] | readonly [newValue: V]
+): readonly [V, ...Ar] | ((array: Ar) => readonly [V, ...Ar]) {
+  switch (args.length) {
+    case 2: {
+      const [array, newValue] = args;
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      return array.toSpliced(0, 0, newValue) as unknown as readonly [V, ...Ar];
+    }
+    case 1: {
+      const [newValue] = args;
+      return (array) => toUnshifted(array, newValue);
+    }
+  }
+}
+
+/**
+ * Returns a new array with all elements replaced by the specified value.
+ *
+ * @example
+ *
+ * ```ts
+ * const base = [1, 2, 3];
+ *
+ * const filled = Arr.toFilled(base, 0);
+ * const filledCurried = Arr.toFilled('x')(base);
+ *
+ * assert.deepStrictEqual(filled, [0, 0, 0]);
+ * assert.deepStrictEqual(filledCurried, ['x', 'x', 'x']);
+ * ```
+ */
+export function toFilled<const Ar extends readonly unknown[], const V>(
+  array: Ar,
+  value: V,
+): IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<Ar['length'], V>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<V>
+    : readonly V[];
+
+// curried version
+export function toFilled<const V>(
+  value: V,
+): <const Ar extends readonly unknown[]>(
+  array: Ar,
+) => IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<Ar['length'], V>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<V>
+    : readonly V[];
+
+export function toFilled<E>(
+  ...args: readonly [array: readonly E[], value: E] | readonly [value: E]
+): readonly E[] | ((array: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [array, value] = args;
+      return create(asPositiveUint32(array.length), value);
+    }
+    case 1: {
+      const [value] = args;
+      return (array) => toFilled(array, value);
+    }
+  }
+}
+
+/**
+ * Returns a new array with elements in the specified range replaced by the specified value.
+ *
+ * @example
+ *
+ * ```ts
+ * const base = [0, 1, 2, 3, 4];
+ *
+ * const filledMiddle = Arr.toRangeFilled(base, 9, [1, 4]);
+ * const filledPrefix = Arr.toRangeFilled(8, [0, 2])(base);
+ *
+ * assert.deepStrictEqual(filledMiddle, [0, 9, 9, 9, 4]);
+ * assert.deepStrictEqual(filledPrefix, [8, 8, 2, 3, 4]);
+ * ```
+ */
+export function toRangeFilled<const Ar extends readonly unknown[], const V>(
+  array: Ar,
+  value: V,
+  fillRange: readonly [
+    start: ArgArrayIndexWithNegative<Ar>,
+    end: ArgArrayIndexWithNegative<Ar>,
+  ],
+): IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<Ar['length'], V | Ar[number]>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<V | Ar[number]>
+    : readonly (V | Ar[number])[];
+
+// curried version
+export function toRangeFilled<const V>(
+  value: V,
+  fillRange: readonly [
+    start: SizeType.ArgArrWithNegative,
+    end: SizeType.ArgArrWithNegative,
+  ],
+): <const Ar extends readonly unknown[]>(
+  array: Ar,
+) => IsFixedLengthList<Ar> extends true
+  ? ArrayOfLength<Ar['length'], V | Ar[number]>
+  : Ar extends NonEmptyArray<unknown>
+    ? NonEmptyArray<V | Ar[number]>
+    : readonly (V | Ar[number])[];
+
+export function toRangeFilled<E, const V>(
+  ...args:
+    | readonly [
+        array: readonly E[],
+        value: V,
+        fillRange: readonly [
+          start: SizeType.ArgArrWithNegative,
+          end: SizeType.ArgArrWithNegative,
+        ],
+      ]
+    | readonly [
+        value: V,
+        fillRange: readonly [
+          start: SizeType.ArgArrWithNegative,
+          end: SizeType.ArgArrWithNegative,
+        ],
+      ]
+): readonly (E | V)[] | ((array: readonly E[]) => readonly (E | V)[]) {
+  switch (args.length) {
+    case 3: {
+      const [array, value, [start, end]] = args;
+      const mut_cp: (E | V)[] = castMutable(copy(array));
+      mut_cp.fill(value, start, end);
+      return mut_cp;
+    }
+    case 2: {
+      const [value, fillRange] = args;
+      return (array) => toRangeFilled(array, value, fillRange);
+    }
+  }
+}

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

@@ -1,11 +1,20 @@
-import { expectType } from '../expect-type.mjs';
-import { asUint32 } from '../number/index.mjs';
-import { Arr } from './array-utils.mjs';
+import { expectType } from '../../expect-type.mjs';
+import { asUint32 } from '../../number/index.mjs';
+import {
+  set,
+  toFilled,
+  toInserted,
+  toPushed,
+  toRangeFilled,
+  toRemoved,
+  toUnshifted,
+  toUpdated,
+} from './array-utils-modification.mjs';
 
 describe('Arr modifications', () => {
   describe('toUpdated', () => {
     const xs = [1, 2, 3] as const;
-    const result = Arr.toUpdated(xs, 1, (x) => x + 2);
+    const result = toUpdated(xs, 1, (x) => x + 2);
 
     expectType<typeof result, ArrayOfLength<3, number>>('=');
 
@@ -18,7 +27,7 @@ describe('Arr modifications', () => {
     const xs = [1, 2, 3] as const;
 
     test('case 1', () => {
-      const result = Arr.toInserted(xs, 1, 5);
+      const result = toInserted(xs, 1, 5);
 
       expectType<typeof result, ArrayOfLength<4, 1 | 2 | 3 | 5>>('=');
 
@@ -26,7 +35,7 @@ describe('Arr modifications', () => {
     });
 
     test('case 2 (insert head)', () => {
-      const result = Arr.toInserted(xs, 0, 5);
+      const result = toInserted(xs, 0, 5);
 
       expectType<typeof result, ArrayOfLength<4, 1 | 2 | 3 | 5>>('=');
 
@@ -34,7 +43,11 @@ describe('Arr modifications', () => {
     });
 
     test('case 3 (insert tail)', () => {
-      const result = Arr.toInserted(['a', 'b', 'c'], asUint32(999), 5);
+      const result = toInserted(
+        ['a', 'b', 'c'] as readonly string[],
+        asUint32(999),
+        5,
+      );
 
       expectType<typeof result, NonEmptyArray<string | 5>>('=');
 
@@ -45,7 +58,7 @@ describe('Arr modifications', () => {
   describe('toRemoved', () => {
     test('case 1', () => {
       const xs = [1, 2, 3] as const;
-      const result = Arr.toRemoved(xs, 1);
+      const result = toRemoved(xs, 1);
 
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
@@ -54,7 +67,7 @@ describe('Arr modifications', () => {
 
     test('case 2 (remove head)', () => {
       const xs = [1, 2, 3] as const;
-      const result = Arr.toRemoved(xs, 0);
+      const result = toRemoved(xs, 0);
 
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
@@ -63,7 +76,7 @@ describe('Arr modifications', () => {
 
     test('case 3 (remove tail)', () => {
       const xs = [1, 2, 3] as const;
-      const result = Arr.toRemoved(xs, 2);
+      const result = toRemoved(xs, 2);
 
       expectType<typeof result, readonly (1 | 2 | 3)[]>('=');
 
@@ -72,7 +85,7 @@ describe('Arr modifications', () => {
 
     test('case 4 (number[])', () => {
       const xs: number[] = [1, 2, 3];
-      const result = Arr.toRemoved(xs, 5);
+      const result = toRemoved(xs, 5);
 
       expectType<typeof result, readonly number[]>('=');
 
@@ -83,7 +96,7 @@ describe('Arr modifications', () => {
   describe('toPushed', () => {
     test('case 1', () => {
       const xs = [1, 2, 3] as const;
-      const result = Arr.toPushed(xs, 4 as const);
+      const result = toPushed(xs, 4 as const);
 
       expectType<typeof result, readonly [1, 2, 3, 4]>('=');
 
@@ -92,7 +105,7 @@ describe('Arr modifications', () => {
 
     test('case 2', () => {
       const xs: number[] = [1, 2, 3];
-      const result = Arr.toPushed(xs, 4 as const);
+      const result = toPushed(xs, 4 as const);
 
       expectType<typeof result, readonly [...number[], 4]>('=');
 
@@ -104,7 +117,7 @@ describe('Arr modifications', () => {
     test('case 1', () => {
       const xs = [1, 2, 3] as const;
 
-      const result = Arr.toUnshifted(xs, 4 as const);
+      const result = toUnshifted(xs, 4 as const);
 
       expectType<typeof result, readonly [4, 1, 2, 3]>('=');
 
@@ -114,7 +127,7 @@ describe('Arr modifications', () => {
     test('case 2', () => {
       const xs: number[] = [1, 2, 3];
 
-      const result = Arr.toUnshifted(xs, 4 as const);
+      const result = toUnshifted(xs, 4 as const);
 
       expectType<typeof result, readonly [4, ...number[]]>('=');
 
@@ -125,13 +138,13 @@ describe('Arr modifications', () => {
   describe('toFilled', () => {
     test('should fill entire array with value', () => {
       const arr = [1, 2, 3, 4, 5];
-      const result = Arr.toFilled(arr, 0);
+      const result = toFilled(arr, 0);
 
       expect(result).toStrictEqual([0, 0, 0, 0, 0]);
     });
 
     test('should work with curried version', () => {
-      const fillWithZero = Arr.toFilled(0);
+      const fillWithZero = toFilled(0);
       const arr = [1, 2, 3];
       const result = fillWithZero(arr);
 
@@ -142,35 +155,35 @@ describe('Arr modifications', () => {
   describe('toRangeFilled', () => {
     test('should fill array with range', () => {
       const arr = [1, 2, 3, 4, 5];
-      const result = Arr.toRangeFilled(arr, 0, [1, 4]);
+      const result = toRangeFilled(arr, 0, [1, 4]);
 
       expect(result).toStrictEqual([1, 0, 0, 0, 5]);
     });
 
     test('should fill with range starting from 0', () => {
       const arr = [1, 2, 3, 4, 5];
-      const result = Arr.toRangeFilled(arr, 9, [0, 3]);
+      const result = toRangeFilled(arr, 9, [0, 3]);
 
       expect(result).toStrictEqual([9, 9, 9, 4, 5]);
     });
 
     test('should handle empty range', () => {
       const arr = [1, 2, 3];
-      const result = Arr.toRangeFilled(arr, 0, [2, 2]);
+      const result = toRangeFilled(arr, 0, [2, 2]);
 
       expect(result).toStrictEqual([1, 2, 3]);
     });
 
     test('should clamp range to array bounds', () => {
       const arr = [1, 2, 3];
-      const result = Arr.toRangeFilled(arr, 0, [1, 10]);
+      const result = toRangeFilled(arr, 0, [1, 10]);
 
       expect(result).toStrictEqual([1, 0, 0]);
     });
 
     test('should handle negative start (clamped to 0)', () => {
       const arr = [1, 2, 3];
-      const result = Arr.toRangeFilled(arr, 9, [-5, 2]);
+      const result = toRangeFilled(arr, 9, [-5, 2]);
 
       expect(result).toStrictEqual([9, 9, 3]);
     });
@@ -179,19 +192,19 @@ describe('Arr modifications', () => {
       const arr = [1, 2, 3];
 
       // @ts-expect-error start must be an integer
-      expect(Arr.toRangeFilled(arr, 0, [1.5, 3])).toStrictEqual([1, 0, 0]);
+      expect(toRangeFilled(arr, 0, [1.5, 3])).toStrictEqual([1, 0, 0]);
     });
 
     test('A non-integer ending value should result in a type error', () => {
       const arr = [1, 2, 3];
 
       // @ts-expect-error end must be an integer
-      expect(Arr.toRangeFilled(arr, 0, [1, 2.5])).toStrictEqual([1, 0, 3]);
+      expect(toRangeFilled(arr, 0, [1, 2.5])).toStrictEqual([1, 0, 3]);
     });
   });
 
   describe('set', () => {
-    const result = Arr.set([1, 2, 3], 1, 4);
+    const result = set([1, 2, 3], 1, 4);
 
     expectType<typeof result, readonly [1 | 4, 2 | 4, 3 | 4]>('=');
 
@@ -201,7 +214,7 @@ describe('Arr modifications', () => {
 
     test('should work with different value types', () => {
       const nums = [1, 2, 3] as const;
-      const withString = Arr.set(nums, 1, 'two');
+      const withString = set(nums, 1, 'two');
       expectType<typeof withString, readonly [1 | 'two', 2 | 'two', 3 | 'two']>(
         '=',
       );
@@ -210,13 +223,13 @@ describe('Arr modifications', () => {
 
     test('should work at index 0', () => {
       const tuple = ['a', 'b', 'c'] as const;
-      const updated = Arr.set(tuple, 0, 'A');
+      const updated = set(tuple, 0, 'A');
       expect(updated).toStrictEqual(['A', 'b', 'c']);
     });
 
     test('should work at last index', () => {
       const tuple = ['a', 'b', 'c'] as const;
-      const updated = Arr.set(tuple, 2, 'C');
+      const updated = set(tuple, 2, 'C');
       expect(updated).toStrictEqual(['a', 'b', 'C']);
     });
   });