ts-data-forge 13.0.0 → 14.0.0

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

@@ -1,4 +1,6 @@
 import {
+  type ConstrainedList,
+  type HasLengthConstraint,
   type List,
   type NonEmptyArray,
   type NonEmptyTuple,
@@ -6,9 +8,9 @@ import {
 } from 'ts-type-forge';
 import { Uint32 } from '../../number/index.mjs';
 import { type SizeType } from '../../types.mjs';
+import { isEmpty } from './array-utils-length-bounded-array-guard.mjs';
 import { size } from './array-utils-size.mjs';
 import { sliceClamped } from './array-utils-slice-clamped.mjs';
-import { isEmpty } from './array-utils-validation.mjs';
 
 /**
  * Returns all elements of an array except the first one.
@@ -41,9 +43,9 @@ import { isEmpty } from './array-utils-validation.mjs';
  */
 export const tail = <const Ar extends readonly unknown[]>(
   array: Ar,
-): List.Tail<Ar> =>
+): ConstrainedList.Tail<Ar> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  array.slice(1) as unknown as List.Tail<Ar>;
+  array.slice(1) as unknown as ConstrainedList.Tail<Ar>;
 
 /**
  * Returns all elements of an array except the last one.
@@ -62,9 +64,11 @@ export const tail = <const Ar extends readonly unknown[]>(
  */
 export const butLast = <const Ar extends readonly unknown[]>(
   array: Ar,
-): List.ButLast<Ar> =>
+): ConstrainedList.ButLast<Ar> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  (isEmpty(array) ? [] : array.slice(0, -1)) as unknown as List.ButLast<Ar>;
+  (isEmpty(array)
+    ? []
+    : array.slice(0, -1)) as unknown as ConstrainedList.ButLast<Ar>;
 
 /**
  * Takes the first N elements from an array.
@@ -89,25 +93,29 @@ export function take<
 >(
   array: Ar,
   num: N,
-): N extends StructuralPrefixLength
-  ? List.Take<N, Ar>
-  : N extends SizeType.ArgArrPositive
-    ? Ar extends NonEmptyTuple<unknown>
-      ? NonEmptyArray<Ar[number]>
-      : readonly Ar[number][]
-    : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.Take<N, Ar>
+    : N extends SizeType.ArgArrPositive
+      ? Ar extends NonEmptyTuple<unknown>
+        ? NonEmptyArray<Ar[number]>
+        : readonly Ar[number][]
+      : readonly Ar[number][];
 
 export function take<N extends SizeType.ArgArr>(
   num: N,
 ): <const Ar extends readonly unknown[]>(
   array: Ar,
-) => N extends StructuralPrefixLength
-  ? List.Take<N, Ar>
-  : N extends SizeType.ArgArrPositive
-    ? Ar extends NonEmptyTuple<unknown>
-      ? NonEmptyArray<Ar[number]>
-      : readonly Ar[number][]
-    : readonly Ar[number][];
+) => HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.Take<N, Ar>
+    : N extends SizeType.ArgArrPositive
+      ? Ar extends NonEmptyTuple<unknown>
+        ? NonEmptyArray<Ar[number]>
+        : readonly Ar[number][]
+      : readonly Ar[number][];
 
 export function take<E>(
   ...args:
@@ -151,25 +159,29 @@ export function takeLast<
 >(
   array: Ar,
   num: N,
-): N extends StructuralPrefixLength
-  ? List.TakeLast<N, Ar>
-  : N extends SizeType.ArgArrPositive
-    ? Ar extends NonEmptyTuple<unknown>
-      ? NonEmptyArray<Ar[number]>
-      : readonly Ar[number][]
-    : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.TakeLast<N, Ar>
+    : N extends SizeType.ArgArrPositive
+      ? Ar extends NonEmptyTuple<unknown>
+        ? NonEmptyArray<Ar[number]>
+        : readonly Ar[number][]
+      : readonly Ar[number][];
 
 export function takeLast<N extends SizeType.ArgArr>(
   num: N,
 ): <const Ar extends readonly unknown[]>(
   array: Ar,
-) => N extends StructuralPrefixLength
-  ? List.TakeLast<N, Ar>
-  : N extends SizeType.ArgArrPositive
-    ? Ar extends NonEmptyTuple<unknown>
-      ? NonEmptyArray<Ar[number]>
-      : readonly Ar[number][]
-    : readonly Ar[number][];
+) => HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.TakeLast<N, Ar>
+    : N extends SizeType.ArgArrPositive
+      ? Ar extends NonEmptyTuple<unknown>
+        ? NonEmptyArray<Ar[number]>
+        : readonly Ar[number][]
+      : readonly Ar[number][];
 
 export function takeLast<E>(
   ...args:
@@ -214,16 +226,22 @@ export function skip<
 >(
   array: Ar,
   num: N,
-): N extends StructuralPrefixLength ? List.Skip<N, Ar> : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.Skip<N, Ar>
+    : readonly Ar[number][];
 
 // curried version
 export function skip<N extends SizeType.ArgArr>(
   num: N,
 ): <const Ar extends readonly unknown[]>(
   array: Ar,
-) => N extends StructuralPrefixLength
-  ? List.Skip<N, Ar>
-  : readonly Ar[number][];
+) => HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.Skip<N, Ar>
+    : readonly Ar[number][];
 
 export function skip<E>(
   ...args: readonly [readonly E[], SizeType.ArgArr] | readonly [SizeType.ArgArr]
@@ -265,18 +283,22 @@ export function skipLast<
 >(
   array: Ar,
   num: N,
-): N extends StructuralPrefixLength
-  ? List.SkipLast<N, Ar>
-  : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.SkipLast<N, Ar>
+    : readonly Ar[number][];
 
 // curried version
 export function skipLast<N extends SizeType.ArgArr>(
   num: N,
 ): <const Ar extends readonly unknown[]>(
   array: Ar,
-) => N extends StructuralPrefixLength
-  ? List.SkipLast<N, Ar>
-  : readonly Ar[number][];
+) => HasLengthConstraint<Ar> extends true
+  ? readonly Ar[number][]
+  : N extends StructuralPrefixLength
+    ? List.SkipLast<N, Ar>
+    : readonly Ar[number][];
 
 export function skipLast<E>(
   ...args:

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

@@ -1,3 +1,4 @@
+import { type MinLengthArray } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import {
   butLast,
@@ -219,3 +220,57 @@ describe('Arr slicing', () => {
     });
   });
 });
+
+/* Length-constrained inputs. `List.*` reports what it can see from a
+   fixed-length tuple, and a branded array's `length` is `number`, so it handed
+   the input type straight back — `tail` of an "at least 5" array claimed the
+   four-element result was still at least five. Never called; see the note in
+   `array-utils-modification.test.mts`. */
+export const slicingTypeChecks = (
+  brandedFive: MinLengthArray<5, string>,
+  brandedAndTuple: MinLengthArray<3, number> & readonly [1, 2, 3, 4, 5],
+): void => {
+  // The bound is recomputed rather than passed through.
+  const _tailed = tail(brandedFive);
+
+  expectType<typeof _tailed, MinLengthArray<4, string>>('~=');
+
+  const _butLasted = butLast(brandedFive);
+
+  expectType<typeof _butLasted, MinLengthArray<4, string>>('~=');
+
+  /* A brand intersected with an exact tuple keeps the positions too, so the
+     result is exact on both counts. */
+  const _tailedBoth = tail(brandedAndTuple);
+
+  expectType<(typeof _tailedBoth)[0], 2>('=');
+
+  expectType<(typeof _tailedBoth)['length'], 4>('=');
+
+  /* `take` / `takeLast` / `skip` / `skipLast` stay on the `List.*` path and give
+     a branded input the sound unconstrained answer instead of its stale brand.
+     They cannot use `ConstrainedList.Take` and friends: those rebuild the bounds
+     from `N` and cannot be instantiated against a still-generic `Ar` at all —
+     even with a literal `N` the deferred result is a union too complex to
+     represent. */
+  const _taken = take(brandedFive, 2);
+
+  expectType<typeof _taken, readonly string[]>('=');
+
+  const _skipped = skip(brandedFive, 2);
+
+  expectType<typeof _skipped, readonly string[]>('=');
+
+  // Plain tuples keep mapping exactly as before.
+  const _tailedTuple = tail([1, 2, 3] as const);
+
+  expectType<typeof _tailedTuple, readonly [2, 3]>('=');
+
+  const _butLastedTuple = butLast([1, 2, 3] as const);
+
+  expectType<typeof _butLastedTuple, readonly [1, 2]>('=');
+
+  const _takenTuple = take([1, 2, 3] as const, 2);
+
+  expectType<typeof _takenTuple, readonly [1, 2]>('=');
+};

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

@@ -1,13 +1,17 @@
 import {
+  type BoundedLengthArray,
+  type ChangeArrayElement,
+  type ConstrainedList,
   type FixedLengthTuple,
+  type HasLengthConstraint,
   type IsFixedLengthList,
-  type List,
   type NonEmptyArray,
   type NonEmptyTuple,
   type PositiveInt,
   type PositiveUint32,
   type Primitive,
   type SafeUintWithSmallInt,
+  type SupportedLength,
   type WithSmallInt,
 } from 'ts-type-forge';
 import { IMap } from '../../collections/index.mjs';
@@ -20,8 +24,8 @@ import {
   type SizeType,
 } from '../../types.mjs';
 import { newArray, seq } from './array-utils-creation.mjs';
+import { isNonEmpty } from './array-utils-length-bounded-array-guard.mjs';
 import { size } from './array-utils-size.mjs';
-import { isNonEmpty } from './array-utils-validation.mjs';
 
 /**
  * Creates a new array by transforming each element with a mapping function.
@@ -45,14 +49,12 @@ import { isNonEmpty } from './array-utils-validation.mjs';
 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 }>;
+): ChangeArrayElement<Ar, B>;
 
 // curried version
 export function map<A, B>(
   mapFn: (a: A, index: SizeType.Arr) => B,
-): <const Ar extends readonly A[]>(
-  array: Ar,
-) => Readonly<{ [K in keyof Ar]: B }>;
+): <const Ar extends readonly A[]>(array: Ar) => ChangeArrayElement<Ar, B>;
 
 export function map<A, B>(
   ...args:
@@ -187,7 +189,7 @@ const scanImpl = <E, S>(
  */
 export const toReversed = <const Ar extends readonly unknown[]>(
   array: Ar,
-): List.Reverse<Ar> =>
+): ConstrainedList.Reverse<Ar> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   array.toReversed() as never;
 
@@ -224,11 +226,13 @@ export const toSorted = <const Ar extends readonly unknown[]>(
         comparator?: (x: Ar[number], y: Ar[number]) => number,
       ]
     : readonly [array: Ar, comparator: (x: Ar[number], y: Ar[number]) => number]
-): IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number]>
-    : readonly Ar[number][] =>
+): HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, Ar[number]>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], Ar[number]>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<Ar[number]>
+      : readonly Ar[number][] =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   array.toSorted(
     // eslint-disable-next-line total-functions/no-unsafe-type-assertion
@@ -282,21 +286,25 @@ export function toSortedBy<const Ar extends readonly unknown[]>(
   comparatorValueMapper: (value: Ar[number]) => number,
   // If the array elements are mapped to numbers, comparator is optional.
   comparator?: (x: number, y: number) => number,
-): IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number]>
-    : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, Ar[number]>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], Ar[number]>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<Ar[number]>
+      : readonly Ar[number][];
 
 export function toSortedBy<const Ar extends readonly unknown[], const V>(
   array: Ar,
   comparatorValueMapper: (value: Ar[number]) => V,
   comparator: (x: V, y: V) => number,
-): IsFixedLengthList<Ar> extends true
-  ? FixedLengthTuple<Ar['length'], Ar[number]>
-  : Ar extends NonEmptyTuple<unknown>
-    ? NonEmptyArray<Ar[number]>
-    : readonly Ar[number][];
+): HasLengthConstraint<Ar> extends true
+  ? ChangeArrayElement<Ar, Ar[number]>
+  : IsFixedLengthList<Ar> extends true
+    ? FixedLengthTuple<Ar['length'], Ar[number]>
+    : Ar extends NonEmptyTuple<unknown>
+      ? NonEmptyArray<Ar[number]>
+      : readonly Ar[number][];
 
 export function toSortedBy<E, const V>(
   array: readonly E[],
@@ -627,18 +635,24 @@ export function flatMap<A, B>(
  *
  * const triples = Arr.partition(3)(values);
  *
+ * // Every chunk is branded `BoundedLengthArray<1, N, …>` — `partition` never
+ * // emits an empty chunk — so the expected values are annotated with the
+ * // unbranded type.
  * const expectedPairs = [[1, 2], [3, 4], [5]] as const;
  *
- * assert.deepStrictEqual(pairs, expectedPairs);
+ * assert.deepStrictEqual<readonly (readonly number[])[]>(
+ *   pairs,
+ *   expectedPairs,
+ * );
  *
- * assert.deepStrictEqual(triples, [
+ * assert.deepStrictEqual<readonly (readonly number[])[]>(triples, [
  *   [1, 2, 3],
  *   [4, 5],
  * ]);
  *
  * const pairs2 = Arr.chunk([1, 2, 3, 4, 5, 6], 2);
  *
- * assert.deepStrictEqual(pairs2, [
+ * assert.deepStrictEqual<readonly (readonly number[])[]>(pairs2, [
  *   [1, 2],
  *   [3, 4],
  *   [5, 6],
@@ -646,17 +660,17 @@ export function flatMap<A, B>(
  * ```
  */
 export function partition<
-  N extends WithSmallInt<PositiveInt & SizeType.Arr>,
   E,
->(array: readonly E[], chunkSize: N): readonly (readonly E[])[];
+  N extends WithSmallInt<PositiveInt & SizeType.Arr>,
+>(array: readonly E[], chunkSize: N): readonly PartitionChunk<N, E>[];
 
 export function partition<N extends WithSmallInt<PositiveInt & SizeType.Arr>>(
   chunkSize: N,
-): <E>(array: readonly E[]) => readonly (readonly E[])[];
+): <E>(array: readonly E[]) => readonly PartitionChunk<N, E>[];
 
 export function partition<
-  N extends WithSmallInt<PositiveInt & SizeType.Arr>,
   E,
+  N extends WithSmallInt<PositiveInt & SizeType.Arr>,
 >(
   ...args:
     readonly [array: readonly E[], chunkSize: N] | readonly [chunkSize: N]
@@ -672,7 +686,20 @@ export function partition<
   }
 }
 
-const partitionImpl = <N extends WithSmallInt<PositiveInt & SizeType.Arr>, E>(
+/**
+ * Element type of {@link partition}'s result: a chunk holds between 1 and `N`
+ * elements. The lower bound is what makes this worth spelling out — `partition`
+ * never emits an empty chunk, so indexed access into a chunk is not
+ * `undefined` at position `0`, unlike with a plain `readonly E[]`.
+ *
+ * Falls back to {@link NonEmptyArray} when `N` is not a bound the brand can
+ * express, which keeps that lower bound in every case.
+ */
+type PartitionChunk<N, E> = N extends SupportedLength
+  ? BoundedLengthArray<1, N, E>
+  : NonEmptyArray<E>;
+
+const partitionImpl = <E, N extends WithSmallInt<PositiveInt & SizeType.Arr>>(
   array: readonly E[],
   chunkSize: N,
 ): readonly (readonly E[])[] =>
@@ -683,6 +710,13 @@ const partitionImpl = <N extends WithSmallInt<PositiveInt & SizeType.Arr>, E>(
         array.slice(chunkSize * i, chunkSize * (i + 1)),
       );
 
+/**
+ * Alias for `partition`.
+ *
+ * @see {@link partition}
+ */
+export const chunk = partition;
+
 /**
  * Concatenates two arrays.
  *
@@ -853,20 +887,13 @@ export const zip = <
 >(
   array1: Ar1,
   array2: Ar2,
-): List.Zip<Ar1, Ar2> =>
+): ConstrainedList.Zip<Ar1, Ar2> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   seq(Uint32.min(size(array1), size(array2))).map((i: Uint32) =>
     // Non-null assertion is safe here because `i` is always within bounds of both arrays up to the length of the shorter one.
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     tp(array1[i]!, array2[i]!),
-  ) as unknown as List.Zip<Ar1, Ar2>;
-
-/**
- * Alias for `partition`.
- *
- * @see {@link partition}
- */
-export const chunk = partition;
+  ) as unknown as ConstrainedList.Zip<Ar1, Ar2>;
 
 /**
  * Computes the cartesian product of arrays.

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

@@ -1,4 +1,9 @@
-import { type FixedLengthTuple, type NonEmptyArray } from 'ts-type-forge';
+import {
+  type BoundedLengthArray,
+  type FixedLengthTuple,
+  type MinLengthArray,
+  type NonEmptyArray,
+} from 'ts-type-forge';
 import { IMap } from '../../collections/index.mjs';
 import { expectType } from '../../expect-type.mjs';
 import { Optional } from '../../functional/index.mjs';
@@ -644,13 +649,15 @@ describe('Arr transformations', () => {
 
       expectType<
         typeof result,
-        readonly (readonly (
+        readonly BoundedLengthArray<
+          1,
+          4,
           1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
-        )[])[]
-      >('=');
+        >[]
+      >('~=');
 
       test('case 1', () => {
-        assert.deepStrictEqual(result, [
+        assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
           [1, 2, 3, 4],
           [5, 6, 7, 8],
           [9, 10, 11, 12],
@@ -663,13 +670,15 @@ describe('Arr transformations', () => {
 
       expectType<
         typeof result,
-        readonly (readonly (
+        readonly BoundedLengthArray<
+          1,
+          3,
           1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
-        )[])[]
-      >('=');
+        >[]
+      >('~=');
 
       test('case 2', () => {
-        assert.deepStrictEqual(result, [
+        assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
           [1, 2, 3],
           [4, 5, 6],
           [7, 8, 9],
@@ -683,13 +692,15 @@ describe('Arr transformations', () => {
 
       expectType<
         typeof result,
-        readonly (readonly (
+        readonly BoundedLengthArray<
+          1,
+          5,
           1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
-        )[])[]
-      >('=');
+        >[]
+      >('~=');
 
       test('case 3', () => {
-        assert.deepStrictEqual(result, [
+        assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
           [1, 2, 3, 4, 5],
           [6, 7, 8, 9, 10],
           [11, 12],
@@ -702,7 +713,7 @@ describe('Arr transformations', () => {
 
       const result = partition(numbers, 2);
 
-      assert.deepStrictEqual(result, [
+      assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
         [1, 2],
         [3, 4],
         [5, 6],
@@ -714,7 +725,11 @@ describe('Arr transformations', () => {
 
       const result = partition(numbers, 2);
 
-      assert.deepStrictEqual(result, [[1, 2], [3, 4], [5]]);
+      assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
+        [1, 2],
+        [3, 4],
+        [5],
+      ]);
     });
 
     test('should work with chunk size < 2 (returns empty)', () => {
@@ -731,7 +746,7 @@ describe('Arr transformations', () => {
 
       const result = partition(numbers, 5);
 
-      assert.deepStrictEqual(result, [[1, 2]]);
+      assert.deepStrictEqual<readonly (readonly number[])[]>(result, [[1, 2]]);
     });
 
     test('partition should work with empty array', () => {
@@ -1162,3 +1177,34 @@ describe('Arr transformations', () => {
     });
   });
 });
+
+/* `toReversed` is a known permutation, so the tuple half can be reversed
+   alongside the brand. It used to fall back to `ChangeArrayElement`, which kept
+   the length but collapsed the positions to their union. Never called; see the
+   note in `array-utils-modification.test.mts`. */
+export const reversedTypeChecks = (
+  brandedFive: MinLengthArray<5, string>,
+  brandedAndTuple: MinLengthArray<3, number> & readonly [1, 2, 3, 4, 5],
+): void => {
+  const _reversedBranded = toReversed(brandedFive);
+
+  expectType<typeof _reversedBranded, MinLengthArray<5, string>>('~=');
+
+  // Brand and positions both survive, and the positions really are reversed.
+  const _reversedBoth = toReversed(brandedAndTuple);
+
+  expectType<(typeof _reversedBoth)[0], 5>('=');
+
+  expectType<(typeof _reversedBoth)[4], 1>('=');
+
+  const _reversedTuple = toReversed([1, 2, 3] as const);
+
+  expectType<typeof _reversedTuple, readonly [3, 2, 1]>('=');
+
+  /* `toSorted` deliberately does NOT take this path: an arbitrary permutation
+     cannot keep positions, so the honest answer stays "same length, element
+     type widened to the union". */
+  const _sortedTuple = toSorted([1, 2, 3] as const);
+
+  expectType<typeof _sortedTuple, FixedLengthTuple<3, 1 | 2 | 3>>('~=');
+};