ts-data-forge 14.0.0 → 14.0.1

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:

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

@@ -12,6 +12,7 @@ import {
   type Primitive,
   type SafeUintWithSmallInt,
   type SupportedLength,
+  type UnknownBrand,
   type WithSmallInt,
 } from 'ts-type-forge';
 import { IMap } from '../../collections/index.mjs';
@@ -46,15 +47,41 @@ import { size } from './array-utils-size.mjs';
  * assert.deepStrictEqual(indexed, ['0:1', '1:2', '2:3']);
  * ```
  */
-export function map<const Ar extends readonly unknown[], B>(
+export function map<const Ar extends readonly unknown[] & UnknownBrand, B>(
   array: Ar,
   mapFn: (a: Ar[number], index: ArrayIndex<Ar>) => B,
 ): ChangeArrayElement<Ar, B>;
 
+// A plain array or tuple carries no length brand, so the homomorphic mapping
+// is the whole answer. Stating it directly — rather than going through
+// `ChangeArrayElement`, whose `HasLengthConstraint` test a *generic* `Ar`
+// cannot decide — is what keeps `map` usable inside a function that is itself
+// generic over the tuple: a deferred conditional is not assignable to the
+// caller's own `{ [K in keyof Ar]: B }`, while this is.
+export function map<const Ar extends readonly unknown[], B>(
+  array: Ar,
+  mapFn: (a: Ar[number], index: ArrayIndex<Ar>) => B,
+): Readonly<{ [K in keyof Ar]: B }>;
+
 // curried version
+//
+// The two cases have to be overloads *of the returned function*, not two
+// overloads of `map` itself: both curried signatures take the same single
+// argument, so overload resolution would always pick the first and the second
+// would be dead.
+//
+// Spelled as an intersection of two function types rather than one object type
+// carrying two call signatures — the `convert-to-readonly` codemod wraps an
+// inline object type in `Readonly<…>`, and a mapped type drops call
+// signatures, which would leave the curried form with none at all.
 export function map<A, B>(
   mapFn: (a: A, index: SizeType.Arr) => B,
-): <const Ar extends readonly A[]>(array: Ar) => ChangeArrayElement<Ar, B>;
+): (<const Ar extends readonly A[] & UnknownBrand>(
+  array: Ar,
+) => ChangeArrayElement<Ar, B>) &
+  (<const Ar extends readonly A[]>(
+    array: Ar,
+  ) => Readonly<{ [K in keyof Ar]: B }>);
 
 export function map<A, B>(
   ...args:

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

@@ -3,11 +3,13 @@ import {
   type FixedLengthTuple,
   type MinLengthArray,
   type NonEmptyArray,
+  type NonEmptyTuple,
 } from 'ts-type-forge';
 import { IMap } from '../../collections/index.mjs';
 import { expectType } from '../../expect-type.mjs';
 import { Optional } from '../../functional/index.mjs';
 import { SafeUint } from '../../number/index.mjs';
+import { asMinLengthArray } from './array-utils-length-bounded-array-cast.mjs';
 import {
   cartesianProduct,
   concat,
@@ -52,7 +54,7 @@ describe('Arr transformations', () => {
 
       const mappedMixed = map(mixed, (x) => typeof x);
 
-      expectType<typeof mappedMixed, readonly [string, string, string]>('<=');
+      expectType<typeof mappedMixed, FixedLengthTuple<3, string>>('<=');
 
       assert.deepStrictEqual(mappedMixed, ['number', 'string', 'boolean']);
     });
@@ -62,12 +64,37 @@ describe('Arr transformations', () => {
 
       const mappedWithIndex = map(tuple, (x, i) => `${i}:${x}`);
 
-      expectType<typeof mappedWithIndex, readonly [string, string, string]>(
-        '<=',
-      );
+      expectType<typeof mappedWithIndex, FixedLengthTuple<3, string>>('<=');
 
       assert.deepStrictEqual(mappedWithIndex, ['0:a', '1:b', '2:c']);
     });
+
+    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 `map` has to report the homomorphic
+      // mapping directly for a parameter that carries no length brand.
+      const mapValues = <const T extends readonly Readonly<{ v: unknown }>[]>(
+        boxes: T,
+      ): Readonly<{ [K in keyof T]: unknown }> => map(boxes, (b) => b.v);
+
+      const result = mapValues([{ v: 1 }, { v: 'a' }] as const);
+
+      expectType<typeof result, FixedLengthTuple<2, unknown>>('=');
+
+      assert.deepStrictEqual<FixedLengthTuple<2, unknown>>(result, [1, 'a']);
+    });
+
+    test('should keep the length brand of a branded array', () => {
+      const lower: MinLengthArray<2, number> = asMinLengthArray(2, [1, 2, 3]);
+
+      const mappedLower = map(lower, String);
+
+      expectType<typeof mappedLower, MinLengthArray<2, string>>('~=');
+
+      // 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 string[]>(mappedLower, ['1', '2', '3']);
+    });
   });
 
   describe(scan, () => {
@@ -76,7 +103,7 @@ describe('Arr transformations', () => {
 
       const runningSum = scan(numbers, (acc, curr) => acc + curr, 0);
 
-      expectType<typeof runningSum, readonly [number, ...number[]]>('<=');
+      expectType<typeof runningSum, NonEmptyTuple<number>>('<=');
 
       assert.deepStrictEqual<readonly number[]>(runningSum, [0, 1, 3, 6, 10]);
     });
@@ -134,7 +161,7 @@ describe('Arr transformations', () => {
 
       const result = scan(strings, (acc, curr) => acc + curr.length, 0);
 
-      expectType<typeof result, readonly [number, ...number[]]>('<=');
+      expectType<typeof result, NonEmptyTuple<number>>('<=');
 
       assert.deepStrictEqual<readonly number[]>(result, [0, 1, 2, 3]);
     });
@@ -1015,7 +1042,7 @@ describe('Arr transformations', () => {
 
       const zipped = zip(xs, ys);
 
-      expectType<typeof zipped, readonly (readonly [number, number])[]>('=');
+      expectType<typeof zipped, readonly FixedLengthTuple<2, number>[]>('=');
 
       test('case 2', () => {
         assert.deepStrictEqual(zipped, [[1, 4]]);

package/src/collections/imap.mts

@@ -549,7 +549,7 @@ type IMapInterface<K extends MapSetKeyType, V> = Readonly<{
    * const entries = [
    *   ['k1', 'v1'],
    *   ['k2', 'v2'],
-   * ] as const satisfies readonly (readonly [string, string])[];
+   * ] as const satisfies readonly FixedLengthTuple<2, string>[];
    *
    * const map = IMap.create(entries);
    *

package/src/collections/iset-mapped.mts

@@ -1,5 +1,9 @@
 /* eslint-disable unicorn/prefer-iterator-to-array-at-end */
-import { type ReadonlyRecord, type WidenLiteral } from 'ts-type-forge';
+import {
+  type FixedLengthTuple,
+  type ReadonlyRecord,
+  type WidenLiteral,
+} from 'ts-type-forge';
 import { asUint32 } from '../number/index.mjs';
 import { type MapSetKeyType, type SizeType } from '../types.mjs';
 
@@ -788,7 +792,7 @@ type ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{
    *
    * @returns An iterable iterator of entries.
    */
-  entries: () => IterableIterator<readonly [K, K]>;
+  entries: () => IterableIterator<FixedLengthTuple<2, K>>;
 
   // Conversion
 
@@ -1444,7 +1448,7 @@ class ISetMappedClass<K, KM extends MapSetKeyType>
   }
 
   /** @inheritdoc */
-  *entries(): IterableIterator<readonly [K, K]> {
+  *entries(): IterableIterator<FixedLengthTuple<2, K>> {
     for (const km of this.#set) {
       // JavaScript Set's entries() yields [value, value]
       const a = this.#fromKey(km);

package/src/collections/iset.mts

@@ -1,5 +1,9 @@
 /* eslint-disable unicorn/prefer-iterator-to-array-at-end */
-import { type ReadonlyRecord, type WidenLiteral } from 'ts-type-forge';
+import {
+  type FixedLengthTuple,
+  type ReadonlyRecord,
+  type WidenLiteral,
+} from 'ts-type-forge';
 import { asUint32 } from '../number/index.mjs';
 import { unknownToString } from '../others/index.mjs';
 import { type MapSetKeyType, type SizeType } from '../types.mjs';
@@ -460,7 +464,7 @@ type ISetInterface<K extends MapSetKeyType> = Readonly<{
    *
    * @returns An iterable iterator of entries.
    */
-  entries: () => IterableIterator<readonly [K, K]>;
+  entries: () => IterableIterator<FixedLengthTuple<2, K>>;
 
   // Conversion
 
@@ -913,7 +917,7 @@ class ISetClass<K extends MapSetKeyType> implements ISet<K>, Iterable<K> {
   }
 
   /** @inheritdoc */
-  entries(): IterableIterator<readonly [K, K]> {
+  entries(): IterableIterator<FixedLengthTuple<2, K>> {
     return this.#set.entries();
   }
 

package/src/collections/iset.test.mts

@@ -1,4 +1,9 @@
-import { type DeepReadonly, type Primitive } from 'ts-type-forge';
+import {
+  type DeepReadonly,
+  type FixedLengthTuple,
+  type MutableFixedLengthTuple,
+  type Primitive,
+} from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
 import { isString } from '../guard/index.mjs';
 import { type MapSetKeyType } from '../types.mjs';
@@ -974,13 +979,11 @@ describe('ISet.entries', () => {
 
     expectType<
       typeof s0.entries,
-      () => IterableIterator<readonly [1 | 2 | 3, 1 | 2 | 3]>
+      () => IterableIterator<FixedLengthTuple<2, 1 | 2 | 3>>
     >('<=');
 
-    const result: DeepReadonly<[1 | 2 | 3, 1 | 2 | 3][]> = Array.from(
-      s0.entries(),
-      (x) => [x[0], x[1]],
-    );
+    const result: DeepReadonly<MutableFixedLengthTuple<2, 1 | 2 | 3>[]> =
+      Array.from(s0.entries(), (x) => [x[0], x[1]]);
 
     assert.deepStrictEqual(
       result.toSorted((a, b) => a[0] - b[0]),

package/src/number/num-arithmetic-types.mts

@@ -75,8 +75,10 @@ export type LevelOf<N> = [N] extends [SafeInt]
 
 // --- boolean fact algebra over a sign ----------------------------------------
 
-type And<A extends boolean, B extends boolean> = [A, B] extends [true, true]
-  ? true
+type And<A extends boolean, B extends boolean> = [A] extends [true]
+  ? [B] extends [true]
+    ? true
+    : false
   : false;
 
 type Or<A extends boolean, B extends boolean> = true extends A | B
@@ -170,8 +172,10 @@ type DivLevel<LA extends Level, LB extends Level> = 'number' extends LA | LB
 /** Floor division yields an integer; the safe range is preserved. */
 type DivIntLevel<LA extends Level, LB extends Level> = 'number' extends LA | LB
   ? 'number'
-  : [LA, LB] extends ['safeint', 'safeint']
-    ? 'safeint'
+  : [LA] extends ['safeint']
+    ? [LB] extends ['safeint']
+      ? 'safeint'
+      : 'int'
     : 'int';
 
 // --- reconstruction (sign, level) -> canonical brand -------------------------

package/src/number/num.test.mts

@@ -1,11 +1,11 @@
-import { type NonZeroNumber } from 'ts-type-forge';
+import { type FixedLengthTuple, type NonZeroNumber } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
 import { pipe, Result } from '../functional/index.mjs';
 import { asNonZeroFiniteNumber } from './branded-types/index.mjs';
 import { Num } from './num.mjs';
 
 const testClamp = (
-  [a, b]: readonly [number, number],
+  [a, b]: FixedLengthTuple<2, number>,
   target: number,
   expected: number,
 ): void => {