ts-data-forge 13.0.0 → 14.0.1

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

@@ -1,6 +1,14 @@
-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 { asMinLengthArray } from './array-utils-length-bounded-array-cast.mjs';
 import {
   set,
   toFilled,
@@ -18,7 +26,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]);
@@ -236,6 +244,45 @@ describe('Arr modifications', () => {
 
       assert.deepStrictEqual(result, [0, 0, 0]);
     });
+
+    test('should preserve the tuple shape under a generic parameter', () => {
+      // A caller that is itself generic over the tuple cannot resolve a
+      // conditional return type, so the unbranded overload has to state the
+      // homomorphic mapping directly.
+      const blank = <const T extends readonly number[]>(
+        xs: T,
+      ): Readonly<{ [K in keyof T]: 0 }> => toFilled(xs, 0);
+
+      const result = blank([1, 2, 3] as const);
+
+      expectType<typeof result, FixedLengthTuple<3, 0>>('=');
+
+      assert.deepStrictEqual<FixedLengthTuple<3, 0>>(result, [0, 0, 0]);
+    });
+
+    test('should preserve the tuple shape under a generic parameter when curried', () => {
+      const blank = <const T extends readonly number[]>(
+        xs: T,
+      ): Readonly<{ [K in keyof T]: 0 }> => toFilled(0)(xs);
+
+      const result = blank([1, 2] as const);
+
+      expectType<typeof result, FixedLengthTuple<2, 0>>('=');
+
+      assert.deepStrictEqual<FixedLengthTuple<2, 0>>(result, [0, 0]);
+    });
+
+    test('should keep the length brand of a branded array', () => {
+      const lower: MinLengthArray<2, number> = asMinLengthArray(2, [1, 2, 3]);
+
+      const filled = toFilled(lower, 0);
+
+      expectType<typeof filled, MinLengthArray<2, 0>>('~=');
+
+      // The brand is not part of the runtime value, so compare structurally —
+      // the type argument is what widens it, no intermediate binding needed.
+      assert.deepStrictEqual<readonly number[]>(filled, [0, 0, 0]);
+    });
   });
 
   describe(toRangeFilled, () => {
@@ -263,6 +310,18 @@ describe('Arr modifications', () => {
       assert.deepStrictEqual(result, [1, 2, 3]);
     });
 
+    test('should preserve the tuple shape under a generic parameter', () => {
+      const blankMiddle = <const T extends readonly number[]>(
+        xs: T,
+      ): Readonly<{ [K in keyof T]: number }> => toRangeFilled(xs, 0, [1, 2]);
+
+      const result = blankMiddle([1, 2, 3] as const);
+
+      expectType<typeof result, FixedLengthTuple<3, number>>('=');
+
+      assert.deepStrictEqual<FixedLengthTuple<3, number>>(result, [1, 0, 3]);
+    });
+
     test('should clamp range to array bounds', () => {
       const arr = [1, 2, 3] as readonly number[];
 
@@ -305,7 +364,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 +375,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 +405,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 {

package/src/array/impl/array-utils-shape-invariants.test.mts

@@ -0,0 +1,284 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type FixedLengthTuple,
+  type MaxLengthArray,
+  type MaxLengthOf,
+  type MinLengthArray,
+  type MinLengthOf,
+} from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import {
+  asBoundedLengthArray,
+  asFixedLengthArray,
+  asMaxLengthArray,
+  asMinLengthArray,
+} from './array-utils-length-bounded-array-cast.mjs';
+import { toFilled, toRangeFilled } from './array-utils-modification.mjs';
+import { map, toReversed, toSorted } from './array-utils-transformation.mjs';
+
+/**
+ * Invariant-based coverage for the array -> array transforms.
+ *
+ * Rather than pinning an expected type for every (brand x shape x context)
+ * combination — which is a large table whose expected side is easy to derive
+ * from the implementation and therefore prove nothing — this asserts the small
+ * set of properties every shape-preserving transform must satisfy, across a
+ * fixed list of sample inputs that covers the axes.
+ *
+ * The properties are:
+ *
+ * 1. **Length** — the result reports the same `length` as the input.
+ * 2. **Bounds** — a length brand on the input survives onto the result.
+ * 3. **Generic context** — from a caller that is itself generic over the
+ *    array, the result is assignable to the caller's own homomorphic mapping.
+ *
+ * Property 3 is the one with no coverage before this file, and is what the
+ * `Arr.map` regression fixed in this PR violated: a conditional return type a
+ * generic `Ar` cannot decide stays deferred, and its brand-carrying branch is
+ * then not assignable to the caller's mapping.
+ */
+
+// The sample inputs. Between them they cover the axes: empty / singleton /
+// fixed tuple / non-empty tuple / unbounded array on the shape axis, and
+// unbranded / lower bound / upper bound / both / exact on the brand axis.
+const emptyTuple: readonly [] = [] as const;
+
+const singleton: readonly [1] = [1] as const;
+
+const fixedTuple: readonly [1, 2, 3] = [1, 2, 3] as const;
+
+const nonEmptyTuple: readonly [1, ...number[]] = [1, 2, 3] as const;
+
+const plainArray: readonly number[] = [1, 2, 3] as const;
+
+const lowerBounded: MinLengthArray<2, number> = asMinLengthArray(2, [1, 2, 3]);
+
+const upperBounded: MaxLengthArray<5, number> = asMaxLengthArray(5, [1, 2, 3]);
+
+const bounded: BoundedLengthArray<2, 5, number> = asBoundedLengthArray(
+  2,
+  5,
+  [1, 2, 3],
+);
+
+const exactLength: FixedLengthArray<3, number> = asFixedLengthArray(
+  3,
+  [1, 2, 3],
+);
+
+/**
+ * Property 3 — generic context.
+ *
+ * Each of these is an assertion by construction: the annotated return type is
+ * the caller's own homomorphic mapping, so the declaration only compiles while
+ * the transform reports something assignable to it. There is nothing to run.
+ *
+ * Only the transforms that satisfy this today are listed. `toSorted`,
+ * `toSortedBy`, `toReversed`, `toUpdated`, `tail`, `butLast` and `zip` do not
+ * yet — see the PR description for why each one resists the same fix. Add them
+ * here as they are fixed; that is what makes this list the coverage record.
+ */
+
+const mapInGenericContext = <const T extends readonly number[]>(
+  xs: T,
+): Readonly<{ [K in keyof T]: string }> => map(xs, String);
+
+const mapCurriedInGenericContext = <const T extends readonly number[]>(
+  xs: T,
+): Readonly<{ [K in keyof T]: string }> => map(String)(xs);
+
+const toFilledInGenericContext = <const T extends readonly number[]>(
+  xs: T,
+): Readonly<{ [K in keyof T]: 0 }> => toFilled(xs, 0);
+
+const toFilledCurriedInGenericContext = <const T extends readonly number[]>(
+  xs: T,
+): Readonly<{ [K in keyof T]: 0 }> => toFilled(0)(xs);
+
+const toRangeFilledInGenericContext = <const T extends readonly number[]>(
+  xs: T,
+): Readonly<{ [K in keyof T]: number }> => toRangeFilled(xs, 0, [0, 1]);
+
+describe('Arr shape invariants', () => {
+  // The type-level assertions below are checked by `tsc`; this pins the same
+  // property at runtime, so a transform that silently drops or adds an element
+  // fails here even where the type says otherwise.
+  test('every shape-preserving transform keeps the length at runtime', () => {
+    const input = [3, 1, 2] as const;
+
+    assert.deepStrictEqual<FixedLengthTuple<5, 3>>(
+      [
+        map(input, String).length,
+        toFilled(input, 0).length,
+        toRangeFilled(input, 0, [1, 2]).length,
+        toSorted(input).length,
+        toReversed(input).length,
+      ] as const,
+      [3, 3, 3, 3, 3] as const,
+    );
+  });
+
+  test('the generic-context callers agree with their annotations', () => {
+    const input = [3, 1, 2] as const;
+
+    assert.deepStrictEqual<FixedLengthTuple<3, string>>(
+      mapInGenericContext(input),
+      ['3', '1', '2'],
+    );
+
+    assert.deepStrictEqual<FixedLengthTuple<3, string>>(
+      mapCurriedInGenericContext(input),
+      ['3', '1', '2'],
+    );
+
+    assert.deepStrictEqual<FixedLengthTuple<3, 0>>(
+      toFilledInGenericContext(input),
+      [0, 0, 0],
+    );
+
+    assert.deepStrictEqual<FixedLengthTuple<3, 0>>(
+      toFilledCurriedInGenericContext(input),
+      [0, 0, 0],
+    );
+
+    assert.deepStrictEqual<FixedLengthTuple<3, number>>(
+      toRangeFilledInGenericContext(input),
+      [0, 1, 2],
+    );
+  });
+});
+
+// `map` — property 1 (length) across every unbranded sample.
+{
+  const _a = map(emptyTuple, String);
+
+  const _b = map(singleton, String);
+
+  const _c = map(fixedTuple, String);
+
+  const _d = map(nonEmptyTuple, String);
+
+  const _e = map(plainArray, String);
+
+  expectType<(typeof _a)['length'], (typeof emptyTuple)['length']>('=');
+
+  expectType<(typeof _b)['length'], (typeof singleton)['length']>('=');
+
+  expectType<(typeof _c)['length'], (typeof fixedTuple)['length']>('=');
+
+  expectType<(typeof _d)['length'], (typeof nonEmptyTuple)['length']>('=');
+
+  expectType<(typeof _e)['length'], (typeof plainArray)['length']>('=');
+}
+
+// `map` — property 2 (bounds) across every branded sample.
+{
+  const _a = map(lowerBounded, String);
+
+  const _b = map(upperBounded, String);
+
+  const _c = map(bounded, String);
+
+  const _d = map(exactLength, String);
+
+  expectType<MinLengthOf<typeof _a>, MinLengthOf<typeof lowerBounded>>('=');
+
+  expectType<MaxLengthOf<typeof _b>, MaxLengthOf<typeof upperBounded>>('=');
+
+  expectType<MinLengthOf<typeof _c>, MinLengthOf<typeof bounded>>('=');
+
+  expectType<MaxLengthOf<typeof _c>, MaxLengthOf<typeof bounded>>('=');
+
+  expectType<MinLengthOf<typeof _d>, MinLengthOf<typeof exactLength>>('=');
+
+  expectType<MaxLengthOf<typeof _d>, MaxLengthOf<typeof exactLength>>('=');
+}
+
+// `toFilled` — properties 1 and 2.
+{
+  const _a = toFilled(fixedTuple, 0);
+
+  const _b = toFilled(nonEmptyTuple, 0);
+
+  const _c = toFilled(plainArray, 0);
+
+  const _d = toFilled(lowerBounded, 0);
+
+  const _e = toFilled(bounded, 0);
+
+  expectType<(typeof _a)['length'], (typeof fixedTuple)['length']>('=');
+
+  expectType<(typeof _b)['length'], (typeof nonEmptyTuple)['length']>('=');
+
+  expectType<(typeof _c)['length'], (typeof plainArray)['length']>('=');
+
+  expectType<MinLengthOf<typeof _d>, MinLengthOf<typeof lowerBounded>>('=');
+
+  expectType<MinLengthOf<typeof _e>, MinLengthOf<typeof bounded>>('=');
+
+  expectType<MaxLengthOf<typeof _e>, MaxLengthOf<typeof bounded>>('=');
+}
+
+// `toRangeFilled` — properties 1 and 2.
+{
+  const _a = toRangeFilled(fixedTuple, 0, [1, 2]);
+
+  const _b = toRangeFilled(plainArray, 0, [0, 1]);
+
+  const _c = toRangeFilled(lowerBounded, 0, [0, 1]);
+
+  expectType<(typeof _a)['length'], (typeof fixedTuple)['length']>('=');
+
+  expectType<(typeof _b)['length'], (typeof plainArray)['length']>('=');
+
+  expectType<MinLengthOf<typeof _c>, MinLengthOf<typeof lowerBounded>>('=');
+}
+
+// `toSorted` — properties 1 and 2. Sorting neither adds nor drops elements, so
+// it is held to the same contract even though it is not fixed for property 3.
+{
+  const _a = toSorted(fixedTuple);
+
+  const _b = toSorted(nonEmptyTuple);
+
+  const _c = toSorted(plainArray);
+
+  const _d = toSorted(lowerBounded);
+
+  const _e = toSorted(bounded);
+
+  expectType<(typeof _a)['length'], (typeof fixedTuple)['length']>('=');
+
+  expectType<(typeof _b)['length'], (typeof nonEmptyTuple)['length']>('=');
+
+  expectType<(typeof _c)['length'], (typeof plainArray)['length']>('=');
+
+  expectType<MinLengthOf<typeof _d>, MinLengthOf<typeof lowerBounded>>('=');
+
+  expectType<MinLengthOf<typeof _e>, MinLengthOf<typeof bounded>>('=');
+
+  expectType<MaxLengthOf<typeof _e>, MaxLengthOf<typeof bounded>>('=');
+}
+
+// `toReversed` — properties 1 and 2. Reversal permutes, so the length and the
+// bounds are exactly what must not move.
+{
+  const _a = toReversed(fixedTuple);
+
+  const _b = toReversed(plainArray);
+
+  const _c = toReversed(lowerBounded);
+
+  const _d = toReversed(bounded);
+
+  expectType<(typeof _a)['length'], (typeof fixedTuple)['length']>('=');
+
+  expectType<(typeof _b)['length'], (typeof plainArray)['length']>('=');
+
+  expectType<MinLengthOf<typeof _c>, MinLengthOf<typeof lowerBounded>>('=');
+
+  expectType<MinLengthOf<typeof _d>, MinLengthOf<typeof bounded>>('=');
+
+  expectType<MaxLengthOf<typeof _d>, MaxLengthOf<typeof bounded>>('=');
+}

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

@@ -1,3 +1,4 @@
+import { type FixedLengthTuple } from 'ts-type-forge';
 import { Num } from '../../number/index.mjs';
 import { type ArgArrayIndexWithNegative, type SizeType } from '../../types.mjs';
 
@@ -36,7 +37,7 @@ export function sliceClamped<E>(
         SizeType.ArgArrWithNegative,
         SizeType.ArgArrWithNegative,
       ]
-    | readonly [SizeType.ArgArrWithNegative, SizeType.ArgArrWithNegative]
+    | FixedLengthTuple<2, SizeType.ArgArrWithNegative>
 ): readonly E[] | ((array: readonly E[]) => readonly E[]) {
   switch (args.length) {
     case 3: