ts-data-forge 13.0.0 → 14.0.1

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,18 @@
 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 UnknownBrand,
   type WithSmallInt,
 } from 'ts-type-forge';
 import { IMap } from '../../collections/index.mjs';
@@ -20,8 +25,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.
@@ -42,17 +47,41 @@ import { isNonEmpty } from './array-utils-validation.mjs';
  * assert.deepStrictEqual(indexed, ['0:1', '1:2', '2:3']);
  * ```
  */
+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[]>(
+): (<const Ar extends readonly A[] & UnknownBrand>(
   array: Ar,
-) => Readonly<{ [K in keyof Ar]: B }>;
+) => ChangeArrayElement<Ar, B>) &
+  (<const Ar extends readonly A[]>(
+    array: Ar,
+  ) => Readonly<{ [K in keyof Ar]: B }>);
 
 export function map<A, B>(
   ...args:
@@ -187,7 +216,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 +253,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 +313,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 +662,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 +687,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 +713,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 +737,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 +914,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.