ts-data-forge 13.0.0 → 14.0.1

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, FixedLengthTuple<3, 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, FixedLengthTuple<3, '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,9 +1,11 @@
 import {
+  type ChangeArrayElement,
+  type ConstrainedList,
   type FixedLengthTuple,
   type Increment,
   type IsFixedLengthList,
   type NonEmptyArray,
-  type NonEmptyTuple,
+  type UnknownBrand,
 } from 'ts-type-forge';
 import { asPositiveUint32 } from '../../number/index.mjs';
 import { castMutable } from '../../others/index.mjs';
@@ -27,27 +29,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 +71,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 +83,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:
@@ -376,25 +355,33 @@ const toUnshiftedImpl = <Ar extends readonly unknown[], const V>(
  * assert.deepStrictEqual(filledCurried, ['x', 'x', 'x']);
  * ```
  */
+export function toFilled<
+  const Ar extends readonly unknown[] & UnknownBrand,
+  const V,
+>(array: Ar, value: V): ChangeArrayElement<Ar, V>;
+
+// For an array or tuple that carries no length brand the homomorphic mapping
+// already covers every case the conditional spelled out — a fixed-length tuple
+// keeps its length, `readonly [A, ...A[]]` stays non-empty, and `readonly A[]`
+// stays unbounded. Stating it directly is what keeps this usable from a
+// caller that is itself generic over the array: a conditional a *generic* `Ar`
+// cannot decide stays deferred, and its branded branch is then not assignable
+// to the caller's own mapping.
 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[];
+): Readonly<{ [K in keyof Ar]: V }>;
 
-// curried version
+// curried version — the two cases have to be overloads of the *returned*
+// function, spelled as an intersection of function types (see `Arr.map`).
 export function toFilled<const V>(
   value: V,
-): <const Ar extends readonly unknown[]>(
+): (<const Ar extends readonly unknown[] & UnknownBrand>(
   array: Ar,
-) => IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], V>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V>
-    : readonly V[];
+) => ChangeArrayElement<Ar, V>) &
+  (<const Ar extends readonly unknown[]>(
+    array: Ar,
+  ) => Readonly<{ [K in keyof Ar]: V }>);
 
 export function toFilled<E>(
   ...args: readonly [array: readonly E[], value: E] | readonly [value: E]
@@ -428,6 +415,20 @@ const toFilledImpl = <E,>(array: readonly E[], value: E): readonly E[] =>
  * assert.deepStrictEqual(filledPrefix, [8, 8, 2, 3, 4]);
  * ```
  */
+export function toRangeFilled<
+  const Ar extends readonly unknown[] & UnknownBrand,
+  const V,
+>(
+  array: Ar,
+  value: V,
+  fillRange: readonly [
+    start: ArgArrayIndexWithNegative<Ar>,
+    end: ArgArrayIndexWithNegative<Ar>,
+  ],
+): ChangeArrayElement<Ar, V | Ar[number]>;
+
+// See `toFilled` for why the unbranded case states the homomorphic mapping
+// directly instead of going through a conditional.
 export function toRangeFilled<const Ar extends readonly unknown[], const V>(
   array: Ar,
   value: V,
@@ -435,11 +436,7 @@ 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])[];
+): Readonly<{ [K in keyof Ar]: V | Ar[number] }>;
 
 // curried version
 export function toRangeFilled<const V>(
@@ -448,13 +445,12 @@ export function toRangeFilled<const V>(
     start: SizeType.ArgArrWithNegative,
     end: SizeType.ArgArrWithNegative,
   ],
-): <const Ar extends readonly unknown[]>(
+): (<const Ar extends readonly unknown[] & UnknownBrand>(
   array: Ar,
-) => IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], V | Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<V | Ar[number]>
-    : readonly (V | Ar[number])[];
+) => ChangeArrayElement<Ar, V | Ar[number]>) &
+  (<const Ar extends readonly unknown[]>(
+    array: Ar,
+  ) => Readonly<{ [K in keyof Ar]: V | Ar[number] }>);
 
 export function toRangeFilled<E, const V>(
   ...args:
@@ -499,3 +495,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>;