ts-data-forge 13.0.0 → 14.0.0

package/src/array/impl/array-utils-length-constraint-preservation.test.mts

@@ -0,0 +1,287 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type FixedLengthTuple,
+  type MaxLengthArray,
+  type MinLengthArray,
+  type Seq,
+} from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import { copy, create, seq, zeros } from './array-utils-creation.mjs';
+import {
+  asBoundedLengthArray,
+  asFixedLengthArray,
+  asMaxLengthArray,
+  asMinLengthArray,
+} from './array-utils-length-bounded-array-cast.mjs';
+import {
+  set,
+  toFilled,
+  toRangeFilled,
+  toUpdated,
+} from './array-utils-modification.mjs';
+import {
+  map,
+  partition,
+  toReversed,
+  toSorted,
+  toSortedBy,
+} from './array-utils-transformation.mjs';
+
+describe('map preserves length constraints', () => {
+  test('a branded input keeps its constraint', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [0, 1, 2, 3]);
+
+    const result = map(input, (value) => `#${String(value)}`);
+
+    expectType<typeof result, MinLengthArray<3, string>>('~=');
+
+    // The structural prefix survives, so in-range access is not `undefined`.
+    const first: string = result[0];
+
+    assert.deepStrictEqual(first, '#0');
+
+    assert.deepStrictEqual<readonly string[]>(result, ['#0', '#1', '#2', '#3']);
+  });
+
+  test('a fixed-length branded input keeps its exact length', () => {
+    const input: FixedLengthArray<3, number> = asFixedLengthArray(
+      3,
+      [255, 128, 0],
+    );
+
+    const result = map(input, (value) => value / 255);
+
+    expectType<typeof result, FixedLengthArray<3, number>>('~=');
+
+    const length: 3 = result.length;
+
+    assert.deepStrictEqual(length, 3);
+  });
+
+  test('a minimum above the structural prefix cap survives, clamped like MinLengthArray itself', () => {
+    const input: MinLengthArray<12, number> = asMinLengthArray(
+      12,
+      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+    );
+
+    const result = map(input, String);
+
+    expectType<typeof result, MinLengthArray<12, string>>('~=');
+
+    assert.deepStrictEqual<readonly string[]>(result, [
+      '0',
+      '1',
+      '2',
+      '3',
+      '4',
+      '5',
+      '6',
+      '7',
+      '8',
+      '9',
+      '10',
+      '11',
+    ]);
+  });
+
+  test('a plain tuple still maps element-wise', () => {
+    const result = map([1, 2, 3] as const, String);
+
+    expectType<typeof result, readonly [string, string, string]>('=');
+
+    assert.deepStrictEqual(result, ['1', '2', '3']);
+  });
+
+  test('a plain array still maps to a plain array', () => {
+    const input: readonly number[] = [1, 2, 3] as const;
+
+    const result = map(input, String);
+
+    expectType<typeof result, readonly string[]>('=');
+
+    assert.deepStrictEqual(result, ['1', '2', '3']);
+  });
+
+  test('an upper bound survives too', () => {
+    const input: MaxLengthArray<5, number> = asMaxLengthArray(5, [1, 2]);
+
+    const result = map(input, String);
+
+    expectType<typeof result, MaxLengthArray<5, string>>('~=');
+
+    assert.deepStrictEqual<readonly string[]>(result, ['1', '2']);
+  });
+
+  test('both bounds survive together', () => {
+    const input: BoundedLengthArray<2, 5, number> = asBoundedLengthArray(
+      2,
+      5,
+      [1, 2],
+    );
+
+    const result = map(input, String);
+
+    expectType<typeof result, BoundedLengthArray<2, 5, string>>('~=');
+
+    assert.deepStrictEqual<readonly string[]>(result, ['1', '2']);
+  });
+});
+
+describe('other length-preserving utilities preserve length constraints', () => {
+  test('toSorted keeps the brand', () => {
+    const input: FixedLengthArray<3, number> = asFixedLengthArray(3, [3, 1, 2]);
+
+    const result = toSorted(input, (x, y) => x - y);
+
+    expectType<typeof result, FixedLengthArray<3, number>>('~=');
+
+    assert.deepStrictEqual<readonly number[]>(result, [1, 2, 3]);
+  });
+
+  test('toSortedBy keeps the brand', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [3, 1, 2]);
+
+    const result = toSortedBy(input, (x) => x);
+
+    expectType<typeof result, MinLengthArray<3, number>>('~=');
+
+    assert.deepStrictEqual<readonly number[]>(result, [1, 2, 3]);
+  });
+
+  test('set keeps the brand and widens only the element type', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [0, 1, 2]);
+
+    const result = set(input, 1, 'x');
+
+    expectType<typeof result, MinLengthArray<3, number | 'x'>>('~=');
+
+    assert.deepStrictEqual<readonly (number | string)[]>(result, [0, 'x', 2]);
+  });
+
+  test('toUpdated keeps the brand and widens only the element type', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [0, 1, 2]);
+
+    const result = toUpdated(input, 1, (prev) => `#${String(prev)}`);
+
+    expectType<typeof result, MinLengthArray<3, number | `#${string}`>>('~=');
+
+    assert.deepStrictEqual<readonly (number | string)[]>(result, [0, '#1', 2]);
+  });
+
+  test('toRangeFilled keeps the brand', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [0, 1, 2]);
+
+    const result = toRangeFilled(input, 'x', [0, 2]);
+
+    expectType<typeof result, MinLengthArray<3, number | 'x'>>('~=');
+
+    assert.deepStrictEqual<readonly (number | string)[]>(result, ['x', 'x', 2]);
+  });
+
+  test('toFilled keeps the brand with the fill type', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [0, 1, 2]);
+
+    const result = toFilled(input, 'x');
+
+    expectType<typeof result, MinLengthArray<3, 'x'>>('~=');
+
+    assert.deepStrictEqual<readonly string[]>(result, ['x', 'x', 'x']);
+  });
+
+  test('toReversed keeps the brand', () => {
+    const input: MinLengthArray<3, number> = asMinLengthArray(3, [1, 2, 3, 4]);
+
+    const result = toReversed(input);
+
+    expectType<typeof result, MinLengthArray<3, number>>('~=');
+
+    // The structural prefix survives the reversal too.
+    const first: number = result[0];
+
+    assert.deepStrictEqual(first, 4);
+
+    assert.deepStrictEqual<readonly number[]>(result, [4, 3, 2, 1]);
+  });
+
+  test('toReversed still reverses a plain tuple at the type level', () => {
+    const result = toReversed([1, 'two', true] as const);
+
+    expectType<typeof result, readonly [true, 'two', 1]>('=');
+
+    assert.deepStrictEqual(result, [true, 'two', 1]);
+  });
+
+  test('copy keeps the brand, because it returns the input type', () => {
+    const input: FixedLengthArray<3, number> = asFixedLengthArray(3, [1, 2, 3]);
+
+    const result = copy(input);
+
+    expectType<typeof result, FixedLengthArray<3, number>>('=');
+
+    assert.deepStrictEqual<readonly number[]>(result, [1, 2, 3]);
+  });
+});
+
+describe('partition reports the bounds of each chunk', () => {
+  test('a chunk is non-empty and at most the chunk size long', () => {
+    const result = partition([1, 2, 3, 4, 5] as const, 2);
+
+    expectType<
+      typeof result,
+      readonly BoundedLengthArray<1, 2, 1 | 2 | 3 | 4 | 5>[]
+    >('~=');
+
+    // The lower bound is the point: the first element of a chunk is never
+    // `undefined`, unlike with the plain `readonly E[]` this used to return.
+    const [firstChunk] = result;
+
+    // The outer array is unbounded, so this narrows away its `undefined`; the
+    // chunk's own first element needs no such check.
+    assert.isTrue(firstChunk !== undefined);
+
+    const first: 1 | 2 | 3 | 4 | 5 = firstChunk[0];
+
+    assert.deepStrictEqual(first, 1);
+
+    assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
+      [1, 2],
+      [3, 4],
+      [5],
+    ]);
+  });
+});
+
+describe('creation utilities report an exact length past their tuple range', () => {
+  const zeros12 = zeros(12);
+
+  const seq12 = seq(12);
+
+  test('create is branded with the exact length', () => {
+    const result = create(12, 'x');
+
+    expectType<typeof result, FixedLengthArray<12, 'x'>>('~=');
+
+    assert.deepStrictEqual(result.length, 12);
+  });
+
+  test('a length still inside the tuple range keeps its exact tuple type', () => {
+    const result = create(3, 'x');
+
+    expectType<typeof result, readonly ['x', 'x', 'x']>('=');
+
+    assert.deepStrictEqual(result, ['x', 'x', 'x']);
+  });
+
+  test('zeros and seq keep their tuple type across their whole literal range', () => {
+    // `SizeType.ArgArr` only carries literals up to `SmallUint`, which these
+    // two already expand into a tuple, so there is no branded case to add.
+    expectType<typeof zeros12, FixedLengthTuple<12, 0>>('=');
+
+    expectType<typeof seq12, Seq<12>>('=');
+
+    assert.deepStrictEqual(zeros12.length, 12);
+
+    assert.deepStrictEqual(seq12.length, 12);
+  });
+});

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

@@ -1,5 +1,8 @@
 import {
+  type ChangeArrayElement,
+  type ConstrainedList,
   type FixedLengthTuple,
+  type HasLengthConstraint,
   type Increment,
   type IsFixedLengthList,
   type NonEmptyArray,
@@ -27,27 +30,17 @@ import { copy, create } from './array-utils-creation.mjs';
  * 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 NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number] | V>
-    : readonly (Ar[number] | V)[];
+export function set<
+  const Ar extends readonly unknown[],
+  const I extends ArgArrayIndex<Ar>,
+  const V = Ar[number],
+>(array: Ar, index: I, newValue: V): ReplacedAt<Ar, I, V>;
 
 // curried version
-export function set<const V>(
-  index: SizeType.ArgArr,
+export function set<const I extends SizeType.ArgArr, const V>(
+  index: I,
   newValue: V,
-): <const Ar extends readonly unknown[]>(
-  array: Ar,
-) => IsFixedLengthList<Ar> extends true
-  ? Readonly<{ [K in keyof Ar]: Ar[K] | V }>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number] | V>
-    : readonly (Ar[number] | V)[];
+): <const Ar extends readonly unknown[]>(array: Ar) => ReplacedAt<Ar, I, V>;
 
 export function set<E, const V = E>(
   ...args:
@@ -79,7 +72,7 @@ const setImpl = <E, const V = E>(
  *
  * const increased = Arr.toUpdated(temperatures, 1, (value) => value + 5);
  *
- * const incrementLast = Arr.toUpdated<number>(
+ * const incrementLast = Arr.toUpdated<2, number>(
  *   2,
  *   (value) => value + 1,
  * )(temperatures);
@@ -91,28 +84,15 @@ const setImpl = <E, const V = E>(
  */
 export function toUpdated<
   const Ar extends readonly unknown[],
+  const I extends ArgArrayIndex<Ar>,
   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 NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number] | V>
-    : readonly (Ar[number] | V)[];
+>(array: Ar, index: I, updater: (prev: Ar[number]) => V): ReplacedAt<Ar, I, V>;
 
 // curried version
-export function toUpdated<E, const V = E>(
-  index: SizeType.ArgArr,
+export function toUpdated<const I extends SizeType.ArgArr, E, const V = E>(
+  index: I,
   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 NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number] | V>
-    : readonly (Ar[number] | V)[];
+): <const Ar extends readonly E[]>(array: Ar) => ReplacedAt<Ar, I, V>;
 
 export function toUpdated<E, V = E>(
   ...args:
@@ -379,22 +359,26 @@ const toUnshiftedImpl = <Ar extends readonly unknown[], const V>(
 export function toFilled<const Ar extends readonly unknown[], const V>(
   array: Ar,
   value: V,
-): IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], V>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V>
-    : readonly V[];
+): HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, V>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], V>
+    : Ar extends NonEmptyTuple<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
-  ? FixedLengthTuple<Ar['length'], V>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V>
-    : readonly V[];
+) => HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, V>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], V>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<V>
+      : readonly V[];
 
 export function toFilled<E>(
   ...args: readonly [array: readonly E[], value: E] | readonly [value: E]
@@ -435,11 +419,13 @@ export function toRangeFilled<const Ar extends readonly unknown[], const V>(
     start: ArgArrayIndexWithNegative<Ar>,
     end: ArgArrayIndexWithNegative<Ar>,
   ],
-): IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], V | Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V | Ar[number]>
-    : readonly (V | Ar[number])[];
+): HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, V | Ar[number]>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], V | Ar[number]>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<V | Ar[number]>
+      : readonly (V | Ar[number])[];
 
 // curried version
 export function toRangeFilled<const V>(
@@ -450,11 +436,13 @@ export function toRangeFilled<const V>(
   ],
 ): <const Ar extends readonly unknown[]>(
   array: Ar,
-) => IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], V | Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V | Ar[number]>
-    : readonly (V | Ar[number])[];
+) => HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, V | Ar[number]>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], V | Ar[number]>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<V | Ar[number]>
+      : readonly (V | Ar[number])[];
 
 export function toRangeFilled<E, const V>(
   ...args:
@@ -499,3 +487,30 @@ const toRangeFilledImpl = <E, const V>(
 
   return mut_cp;
 };
+
+/**
+ * The result of replacing the element at `I` of `Ar` with a `V`.
+ *
+ * `ConstrainedList.SetAt` replaces exactly one position when the index pins
+ * one, which is what makes `Arr.set(xs, 1, v)` report `readonly [a, V, c]`
+ * instead of widening every position to `a | V`.
+ *
+ * A union index needs the weaker answer, and this used to guard for it here:
+ * `ArgArrayIndex<Ar>` for a tuple is the union of its indices, so
+ * `Arr.set(tuple, someIndex, v)` with `someIndex: 0 | 2` binds `I = 0 | 2`, and
+ * the upstream `List.SetAt` used to answer `readonly [V, b, V]` — a type that
+ * *neither* possible runtime result satisfies, since the call replaces one
+ * position or the other and never both.
+ *
+ * ts-type-forge 9.1.1 fixes that at the source and widens the candidate
+ * positions itself, so the guard is gone. Upstream is the more precise of the
+ * two: it widens only the positions the index can name, where the guard here
+ * widened all of them — `Arr.set(t, i, 'x')` with `i: 0 | 2` on
+ * `readonly [1, 2, 3]` now keeps the middle element at `2` rather than
+ * reporting `2 | 'x'`.
+ */
+type ReplacedAt<
+  Ar extends readonly unknown[],
+  I extends number,
+  V,
+> = ConstrainedList.SetAt<I, V, Ar>;

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

@@ -1,6 +1,13 @@
-import { type FixedLengthTuple, type NonEmptyArray } from 'ts-type-forge';
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type FixedLengthTuple,
+  type MinLengthArray,
+  type NonEmptyArray,
+} from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { asUint32 } from '../../number/index.mjs';
+import { type SizeType } from '../../types.mjs';
 import {
   set,
   toFilled,
@@ -18,7 +25,7 @@ describe('Arr modifications', () => {
 
     const result = toUpdated(xs, 1, (x) => x + 2);
 
-    expectType<typeof result, FixedLengthTuple<3, number>>('=');
+    expectType<typeof result, readonly [1, number, 3]>('=');
 
     test('case 1', () => {
       assert.deepStrictEqual(result, [1, 4, 3]);
@@ -305,7 +312,7 @@ describe('Arr modifications', () => {
   describe(set, () => {
     const result = set([1, 2, 3], 1, 4);
 
-    expectType<typeof result, readonly [1 | 4, 2 | 4, 3 | 4]>('=');
+    expectType<typeof result, readonly [1, 4, 3]>('=');
 
     test('case 1', () => {
       assert.deepStrictEqual(result, [1, 4, 3]);
@@ -316,9 +323,7 @@ describe('Arr modifications', () => {
 
       const withString = set(nums, 1, 'two');
 
-      expectType<typeof withString, readonly [1 | 'two', 2 | 'two', 3 | 'two']>(
-        '=',
-      );
+      expectType<typeof withString, readonly [1, 'two', 3]>('=');
 
       assert.deepStrictEqual(withString, [1, 'two', 3]);
     });
@@ -348,3 +353,85 @@ describe('Arr modifications', () => {
     });
   });
 });
+
+/* `Arr.set` / `Arr.toUpdated` across the input shapes the positional
+   `ConstrainedList.SetAt` annotation has to cope with; the suite previously
+   covered only the plain-tuple case. Written as an unexported-by-value function
+   so the assertions get real overload resolution — it is never called, and the
+   branded shapes have no runtime representation to build. */
+export const setTypeChecks = (
+  shapeTuple: readonly [1, 2, 3],
+  shapeArray: readonly number[],
+  shapeMutableArray: readonly number[],
+  shapeBranded: MinLengthArray<3, string>,
+  shapeBounded: BoundedLengthArray<2, 5, string>,
+  shapeFixed: FixedLengthArray<3, string>,
+  shapeBrandedTuple: MinLengthArray<3, number> & readonly [1, 2, 3, 4, 5],
+  unionIndex: 0 | 2,
+  widenedIndex: SizeType.ArgArr,
+): void => {
+  /* Plain tuple — the point of the positional form: only the touched position
+     changes, the rest keep their literal types. */
+  const _onTuple = set(shapeTuple, 1, 'x');
+
+  expectType<typeof _onTuple, readonly [1, 'x', 3]>('=');
+
+  // Plain array: no positions to pin, so the element type widens.
+  const _onArray = set(shapeArray, widenedIndex, 'x');
+
+  expectType<typeof _onArray, readonly (number | 'x')[]>('=');
+
+  // A mutable array is not brand-carrying, and behaves like the readonly one.
+  const _onMutable = set(shapeMutableArray, widenedIndex, 'x');
+
+  expectType<typeof _onMutable, readonly (number | 'x')[]>('=');
+
+  /* Branded with no exact tuple: the length constraint survives, and with no
+     positions to pin the element type absorbs the new value. */
+  const _onBranded = set(shapeBranded, 1, 'x');
+
+  expectType<typeof _onBranded, MinLengthArray<3, string>>('<=');
+
+  const _onBounded = set(shapeBounded, 1, 'x');
+
+  expectType<typeof _onBounded, BoundedLengthArray<2, 5, string>>('<=');
+
+  // Fixed length: brand *and* exact positions both survive.
+  const _onFixed = set(shapeFixed, 1, 'x');
+
+  expectType<
+    typeof _onFixed,
+    FixedLengthArray<3, string> & readonly [string, 'x', string]
+  >('~=');
+
+  /* Brand intersected with an exact tuple — the shape `Arr.isMinLengthArray`
+     produces. All three survive: the brand, the exact length, and the
+     positions, the last as a structural conjunct beside the widened one. */
+  const _onBrandedTuple = set(shapeBrandedTuple, 1, 'x');
+
+  expectType<(typeof _onBrandedTuple)[0], 1>('=');
+
+  expectType<(typeof _onBrandedTuple)[1], 'x'>('=');
+
+  expectType<(typeof _onBrandedTuple)[4], 5>('=');
+
+  expectType<(typeof _onBrandedTuple)['length'], 5>('=');
+
+  /* A union index must NOT be replaced positionally. The call sets one of the
+     positions and never both, so `readonly ['x', 2, 'x']` — what the upstream
+     `List.SetAt` used to answer for a union index — is a type that no possible
+     result satisfies. ts-type-forge 9.1.1 widens the candidate positions
+     instead, and only those: index 1 is not among `0 | 2`, so it stays `2`. */
+  const _onUnionIndex = set(shapeTuple, unionIndex, 'x');
+
+  expectType<typeof _onUnionIndex, readonly [1 | 'x', 2, 3 | 'x']>('=');
+
+  // `toUpdated` follows `set`, with the updater's return as the value.
+  const _updatedTuple = toUpdated(shapeTuple, 1, (x) => x + 1);
+
+  expectType<typeof _updatedTuple, readonly [1, number, 3]>('=');
+
+  const _updatedUnion = toUpdated(shapeTuple, unionIndex, (x) => x + 1);
+
+  expectType<typeof _updatedUnion, readonly [number, 2, number]>('=');
+};

package/src/array/impl/array-utils-reducing-value.mts

@@ -11,7 +11,7 @@ import {
   type SizeType,
   type Some,
 } from '../../types.mjs';
-import { isNonEmpty } from './array-utils-validation.mjs';
+import { isNonEmpty } from './array-utils-length-bounded-array-guard.mjs';
 
 /**
  * Finds the minimum value in an array.
@@ -543,22 +543,22 @@ export function sum(array: readonly number[]): number {
  */
 export function sumBy(array: readonly [], mapFn: (item: unknown) => number): 0;
 
-export function sumBy<N extends Uint, E>(
+export function sumBy<E, N extends Uint>(
   array: readonly E[],
   mapFn: (item: E) => N,
 ): Uint;
 
-export function sumBy<N extends Int, E>(
+export function sumBy<E, N extends Int>(
   array: readonly E[],
   mapFn: (item: E) => N,
 ): Int;
 
-export function sumBy<N extends number, E>(
+export function sumBy<E, N extends number>(
   array: readonly E[],
   mapFn: (item: E) => N,
 ): number;
 
-export function sumBy<N extends number, E>(
+export function sumBy<E, N extends number>(
   array: readonly E[],
   mapFn: (item: E) => N,
 ): number {