ts-data-forge 13.0.0 → 14.0.1

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

@@ -1,8 +1,15 @@
-import { type FixedLengthTuple, type NonEmptyArray } from 'ts-type-forge';
+import {
+  type BoundedLengthArray,
+  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,
@@ -47,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']);
     });
@@ -57,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, () => {
@@ -71,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]);
     });
@@ -129,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]);
     });
@@ -644,13 +676,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 +697,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 +719,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 +740,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 +752,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 +773,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', () => {
@@ -1000,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]]);
@@ -1162,3 +1204,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>>('~=');
+};

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

@@ -1,13 +1,4 @@
-import {
-  type BoolOr,
-  type BoundedLengthTuple,
-  type FixedLengthArray,
-  type FixedLengthTuple,
-  type MaxLengthTuple,
-  type MinLengthArray,
-  type MinLengthTuple,
-  type TypeEq,
-} from 'ts-type-forge';
+import { type BoolOr, type IsAny, type IsUnknown } from 'ts-type-forge';
 import { asUint32, Num } from '../../number/index.mjs';
 import { type ArrayIndex, type SizeType } from '../../types.mjs';
 
@@ -34,8 +25,7 @@ export const isArray = <E,>(value: E): value is FilterArray<E> =>
   Array.isArray(value);
 
 type FilterArray<T> = T extends T
-  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    BoolOr<TypeEq<T, unknown>, TypeEq<T, any>> extends true
+  ? BoolOr<IsUnknown<T>, IsAny<T>> extends true
     ? Cast<readonly unknown[], T>
     : T extends readonly unknown[]
       ? T
@@ -46,156 +36,6 @@ type Cast<A, B> = A extends B ? A : never;
 
 // validation
 
-/**
- * Type guard that checks if an array is empty.
- *
- * @example
- *
- * ```ts
- * const emptyNumbers: readonly number[] = [] as const;
- *
- * const words = ['Ada', 'Lovelace'] as const;
- *
- * assert.isTrue(Arr.isEmpty(emptyNumbers));
- *
- * assert.isFalse(Arr.isEmpty(words));
- *
- * if (Arr.isEmpty(emptyNumbers)) {
- *   // `isEmpty` narrows to the branded `FixedLengthArray<0, number>`, so the
- *   // expected value is annotated with the unbranded type.
- *   assert.deepStrictEqual<readonly number[]>(emptyNumbers, []);
- * }
- * ```
- */
-export const isEmpty = <Xs extends readonly unknown[]>(
-  array: Xs,
-): array is FixedLengthArray<0, Xs[number]> & Xs => array.length === 0;
-
-/**
- * Type guard that checks if an array is non-empty.
- *
- * @example
- *
- * ```ts
- * const users: readonly Readonly<{ id: number }>[] = [{ id: 1 }] as const;
- *
- * const emptyUsers: readonly Readonly<{ id: number }>[] = [] as const;
- *
- * assert.isTrue(Arr.isNonEmpty(users));
- *
- * assert.isFalse(Arr.isNonEmpty(emptyUsers));
- *
- * if (Arr.isNonEmpty(users)) {
- *   assert.deepStrictEqual(users[0], { id: 1 });
- * }
- * ```
- */
-export const isNonEmpty = <Xs extends readonly unknown[]>(
-  array: Xs,
-): array is MinLengthArray<1, Xs[number]> & Xs => array.length > 0;
-
-/**
- * Checks if an array has a specific length.
- *
- * @example
- *
- * ```ts
- * const pair: readonly number[] = [1, 2] as const;
- *
- * const triple: readonly number[] = [1, 2, 3] as const;
- *
- * assert.isTrue(Arr.isFixedLengthTuple(pair, 2));
- *
- * assert.isFalse(Arr.isFixedLengthTuple(triple, 2));
- *
- * if (Arr.isFixedLengthTuple(pair, 2)) {
- *   assert.deepStrictEqual(pair, [1, 2]);
- * }
- * ```
- */
-export const isFixedLengthTuple = <E, N extends SizeType.ArgArr>(
-  array: readonly E[],
-  len: N,
-): array is FixedLengthTuple<N, E> => array.length === len;
-
-/**
- * Checks if an array has at least a specific length.
- *
- * @example
- *
- * ```ts
- * const queue: readonly string[] = ['task-1', 'task-2'] as const;
- *
- * const emptyQueue: readonly string[] = [] as const;
- *
- * assert.isTrue(Arr.isMinLengthTuple(queue, 1));
- *
- * assert.isFalse(Arr.isMinLengthTuple(emptyQueue, 1));
- *
- * if (Arr.isMinLengthTuple(queue, 1)) {
- *   assert.isTrue(queue[0] === 'task-1');
- * }
- * ```
- */
-export const isMinLengthTuple = <E, N extends SizeType.ArgArr>(
-  array: readonly E[],
-  len: N,
-): array is MinLengthTuple<N, E> => array.length >= len;
-
-/**
- * Checks if an array has at most a specific length.
- *
- * @example
- *
- * ```ts
- * const pair: readonly number[] = [1, 2] as const;
- *
- * const triple: readonly number[] = [1, 2, 3] as const;
- *
- * assert.isTrue(Arr.isMaxLengthTuple(pair, 2));
- *
- * assert.isFalse(Arr.isMaxLengthTuple(triple, 2));
- *
- * if (Arr.isMaxLengthTuple(pair, 2)) {
- *   assert.isTrue(pair.length <= 2);
- * }
- * ```
- */
-export const isMaxLengthTuple = <E, N extends SizeType.ArgArr>(
-  array: readonly E[],
-  len: N,
-): array is MaxLengthTuple<N, E> => array.length <= len;
-
-/**
- * Checks if an array's length is within a specific inclusive range.
- *
- * @example
- *
- * ```ts
- * const pair: readonly number[] = [1, 2] as const;
- *
- * const quad: readonly number[] = [1, 2, 3, 4] as const;
- *
- * assert.isTrue(Arr.isBoundedLengthTuple(pair, 1, 3));
- *
- * assert.isFalse(Arr.isBoundedLengthTuple(quad, 1, 3));
- *
- * if (Arr.isBoundedLengthTuple(pair, 1, 3)) {
- *   assert.isTrue(pair.length >= 1 && pair.length <= 3);
- * }
- * ```
- */
-export const isBoundedLengthTuple = <
-  E,
-  Min extends SizeType.ArgArr,
-  Max extends SizeType.ArgArr,
->(
-  array: readonly E[],
-  min: Min,
-  max: Max,
-): array is BoundedLengthTuple<Min, Max, E> =>
-  array.length >= min && array.length <= max;
-
 /**
  * Tests whether all elements in an array pass a test implemented by a predicate.
  *