ts-data-forge 13.0.0 → 14.0.1

package/src/array/impl/array-utils-length-bounded-tuple-guard.mts

@@ -0,0 +1,266 @@
+import {
+  type BoundedLengthTuple,
+  type FixedLengthTuple,
+  type MaxLengthTuple,
+  type MinLengthTuple,
+} from 'ts-type-forge';
+import { type SizeType } from '../../types.mjs';
+
+/**
+ * Type guard that checks if an array is empty, narrowing it to the structural
+ * empty tuple.
+ *
+ * This is the structural counterpart of `isEmpty`: it narrows to `readonly []`
+ * rather than to the branded `FixedLengthArray<0, E>`. Prefer `isEmpty` unless
+ * you specifically need the structural type.
+ *
+ * @example
+ *
+ * ```ts
+ * const values: readonly number[] = [] as const;
+ *
+ * assert.isTrue(Arr.isEmptyTuple(values));
+ *
+ * assert.isFalse(Arr.isEmptyTuple([1] as const));
+ * ```
+ *
+ * @template E - The element type.
+ * @param array - The array to check.
+ * @returns `true` if `array.length === 0`. When `true`, TypeScript narrows
+ *   `array` to `readonly []`.
+ */
+export const isEmptyTuple = <E,>(array: readonly E[]): array is readonly [] =>
+  array.length === 0;
+
+/**
+ * Type guard that checks if an array is non-empty, narrowing it to the
+ * structural non-empty tuple.
+ *
+ * This is the structural counterpart of `isNonEmpty`: it narrows to
+ * `MinLengthTuple<1, E>` rather than to the branded `MinLengthArray<1, E>`.
+ * Prefer `isNonEmpty` unless you specifically need the structural type.
+ *
+ * @example
+ *
+ * ```ts
+ * const values: readonly number[] = [1, 2] as const;
+ *
+ * assert.isTrue(Arr.isNonEmptyTuple(values));
+ *
+ * assert.isFalse(Arr.isNonEmptyTuple([] as const));
+ * ```
+ *
+ * @template E - The element type.
+ * @param array - The array to check.
+ * @returns `true` if `array.length >= 1`. When `true`, TypeScript narrows
+ *   `array` to `MinLengthTuple<1, E>`.
+ */
+export const isNonEmptyTuple = <E,>(
+  array: readonly E[],
+): array is MinLengthTuple<1, E> => array.length >= 1;
+
+/**
+ * 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(2, pair));
+ *
+ * assert.isFalse(Arr.isFixedLengthTuple(2, triple));
+ *
+ * if (Arr.isFixedLengthTuple(2, pair)) {
+ *   assert.deepStrictEqual(pair, [1, 2]);
+ * }
+ * ```
+ */
+export function isFixedLengthTuple<N extends SizeType.ArgArr, E>(
+  len: N,
+  array: readonly E[],
+): array is FixedLengthTuple<N, E>;
+
+// Curried version
+export function isFixedLengthTuple<N extends SizeType.ArgArr>(
+  len: N,
+): <E>(array: readonly E[]) => array is FixedLengthTuple<N, E>;
+
+export function isFixedLengthTuple(
+  ...args:
+    | readonly [len: SizeType.ArgArr, array: readonly unknown[]]
+    | readonly [len: SizeType.ArgArr]
+): boolean | ((array: readonly unknown[]) => boolean) {
+  switch (args.length) {
+    case 2:
+      return hasFixedLength(args[0], args[1]);
+
+    case 1:
+      return (array) => hasFixedLength(args[0], array);
+  }
+}
+
+const hasFixedLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => 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(1, queue));
+ *
+ * assert.isFalse(Arr.isMinLengthTuple(1, emptyQueue));
+ *
+ * if (Arr.isMinLengthTuple(1, queue)) {
+ *   assert.isTrue(queue[0] === 'task-1');
+ * }
+ * ```
+ */
+export function isMinLengthTuple<N extends SizeType.ArgArr, E>(
+  len: N,
+  array: readonly E[],
+): array is MinLengthTuple<N, E>;
+
+// Curried version
+export function isMinLengthTuple<N extends SizeType.ArgArr>(
+  len: N,
+): <E>(array: readonly E[]) => array is MinLengthTuple<N, E>;
+
+export function isMinLengthTuple(
+  ...args:
+    | readonly [len: SizeType.ArgArr, array: readonly unknown[]]
+    | readonly [len: SizeType.ArgArr]
+): boolean | ((array: readonly unknown[]) => boolean) {
+  switch (args.length) {
+    case 2:
+      return hasMinLength(args[0], args[1]);
+
+    case 1:
+      return (array) => hasMinLength(args[0], array);
+  }
+}
+
+const hasMinLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => 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(2, pair));
+ *
+ * assert.isFalse(Arr.isMaxLengthTuple(2, triple));
+ *
+ * if (Arr.isMaxLengthTuple(2, pair)) {
+ *   assert.isTrue(pair.length <= 2);
+ * }
+ * ```
+ */
+export function isMaxLengthTuple<N extends SizeType.ArgArr, E>(
+  len: N,
+  array: readonly E[],
+): array is MaxLengthTuple<N, E>;
+
+// Curried version
+export function isMaxLengthTuple<N extends SizeType.ArgArr>(
+  len: N,
+): <E>(array: readonly E[]) => array is MaxLengthTuple<N, E>;
+
+export function isMaxLengthTuple(
+  ...args:
+    | readonly [len: SizeType.ArgArr, array: readonly unknown[]]
+    | readonly [len: SizeType.ArgArr]
+): boolean | ((array: readonly unknown[]) => boolean) {
+  switch (args.length) {
+    case 2:
+      return hasMaxLength(args[0], args[1]);
+
+    case 1:
+      return (array) => hasMaxLength(args[0], array);
+  }
+}
+
+const hasMaxLength = (
+  len: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => 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(1, 3, pair));
+ *
+ * assert.isFalse(Arr.isBoundedLengthTuple(1, 3, quad));
+ *
+ * if (Arr.isBoundedLengthTuple(1, 3, pair)) {
+ *   assert.isTrue(pair.length >= 1 && pair.length <= 3);
+ * }
+ * ```
+ */
+export function isBoundedLengthTuple<
+  Min extends SizeType.ArgArr,
+  Max extends SizeType.ArgArr,
+  E,
+>(
+  min: Min,
+  max: Max,
+  array: readonly E[],
+): array is BoundedLengthTuple<Min, Max, E>;
+
+// Curried version
+export function isBoundedLengthTuple<
+  Min extends SizeType.ArgArr,
+  Max extends SizeType.ArgArr,
+>(
+  min: Min,
+  max: Max,
+): <E>(array: readonly E[]) => array is BoundedLengthTuple<Min, Max, E>;
+
+export function isBoundedLengthTuple(
+  ...args:
+    | readonly [
+        min: SizeType.ArgArr,
+        max: SizeType.ArgArr,
+        array: readonly unknown[],
+      ]
+    | readonly [min: SizeType.ArgArr, max: SizeType.ArgArr]
+): boolean | ((array: readonly unknown[]) => boolean) {
+  switch (args.length) {
+    case 3:
+      return isWithinBounds(args[0], args[1], args[2]);
+
+    case 2:
+      return (array) => isWithinBounds(args[0], args[1], array);
+  }
+}
+
+const isWithinBounds = (
+  min: SizeType.ArgArr,
+  max: SizeType.ArgArr,
+  array: readonly unknown[],
+): boolean => array.length >= min && array.length <= max;

package/src/array/impl/array-utils-length-bounded-tuple-guard.test.mts

@@ -0,0 +1,441 @@
+import {
+  type BoundedLengthTuple,
+  type FixedLengthTuple,
+  type MaxLengthTuple,
+  type MinLengthTuple,
+} from 'ts-type-forge';
+import { expectType } from '../../expect-type.mjs';
+import {
+  isBoundedLengthTuple,
+  isEmptyTuple,
+  isFixedLengthTuple,
+  isMaxLengthTuple,
+  isMinLengthTuple,
+  isNonEmptyTuple,
+} from './array-utils-length-bounded-tuple-guard.mjs';
+
+describe('Arr structural tuple length guards', () => {
+  describe(isFixedLengthTuple, () => {
+    test('should return true if array has specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isFixedLengthTuple(3, arr));
+
+      if (isFixedLengthTuple(3, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+    });
+
+    test('should return false if array does not have specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isFixedLengthTuple(2, arr));
+    });
+
+    test('should return true for empty array and length 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isFixedLengthTuple(0, arr));
+
+      if (isFixedLengthTuple(0, arr)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should return false for non-empty array and length 0', () => {
+      const arr = [1] as const;
+
+      assert.isFalse(isFixedLengthTuple(0, arr));
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isFixedLengthTuple(2, mut_arr));
+
+      if (isFixedLengthTuple(2, mut_arr)) {
+        // transformer-ignore-next-line
+        expectType<typeof mut_arr, number[] & FixedLengthTuple<2, number>>('=');
+      }
+
+      assert.isFalse(isFixedLengthTuple(3, mut_arr));
+    });
+
+    test('should work with unknown readonly array type', () => {
+      const arr: readonly number[] = [1, 2] as const;
+
+      assert.isTrue(isFixedLengthTuple(2, arr));
+
+      if (isFixedLengthTuple(2, arr)) {
+        expectType<typeof arr, FixedLengthTuple<2, number>>('=');
+      }
+
+      assert.isFalse(isFixedLengthTuple(3, arr));
+    });
+
+    test('should return true for arrays of exact length (additional)', () => {
+      assert.isTrue(isFixedLengthTuple(3, [1, 2, 3]));
+
+      assert.isTrue(isFixedLengthTuple(0, []));
+
+      assert.isTrue(isFixedLengthTuple(1, ['a']));
+    });
+
+    test('should return false for arrays of different length (additional)', () => {
+      assert.isFalse(isFixedLengthTuple(2, [1, 2, 3]));
+
+      assert.isFalse(isFixedLengthTuple(4, [1, 2, 3]));
+
+      assert.isFalse(isFixedLengthTuple(1, []));
+    });
+
+    test('should work as type guard with exact length (additional)', () => {
+      const array: readonly number[] = [1, 2, 3] as const;
+
+      if (isFixedLengthTuple(3, array)) {
+        expectType<typeof array, FixedLengthTuple<3, number>>('=');
+
+        expect(array).toHaveLength(3);
+      }
+    });
+  });
+
+  describe(isMinLengthTuple, () => {
+    test('should return true if array length is greater than or equal to specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isMinLengthTuple(3, arr));
+
+      if (isMinLengthTuple(3, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+
+      assert.isTrue(isMinLengthTuple(2, arr));
+
+      if (isMinLengthTuple(2, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+    });
+
+    test('should return false if array length is less than specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isMinLengthTuple(4, arr));
+    });
+
+    test('should return true for empty array and length 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isMinLengthTuple(0, arr));
+
+      if (isMinLengthTuple(0, arr)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should return false for empty array and positive length', () => {
+      const arr = [] as const;
+
+      assert.isFalse(isMinLengthTuple(1, arr));
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isMinLengthTuple(2, mut_arr));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & MinLengthTuple<2, number>>('=');
+
+      assert.isFalse(isMinLengthTuple(3, mut_arr));
+    });
+
+    test('should work with unknown array type 2', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isMinLengthTuple(1, mut_arr));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & MinLengthTuple<1, number>>('=');
+
+      assert.isFalse(isMinLengthTuple(3, mut_arr));
+    });
+
+    test('should return true for arrays of at least specified length (additional)', () => {
+      assert.isTrue(isMinLengthTuple(3, [1, 2, 3]));
+
+      assert.isTrue(isMinLengthTuple(2, [1, 2, 3]));
+
+      assert.isTrue(isMinLengthTuple(1, [1, 2, 3]));
+
+      assert.isTrue(isMinLengthTuple(0, [1, 2, 3]));
+    });
+
+    test('should return false for arrays shorter than specified length (additional)', () => {
+      assert.isFalse(isMinLengthTuple(4, [1, 2, 3]));
+
+      assert.isFalse(isMinLengthTuple(1, []));
+    });
+
+    test('should work as type guard for at least length (additional)', () => {
+      const array: readonly number[] = [1, 2, 3] as const;
+
+      if (isMinLengthTuple(2, array)) {
+        expectType<typeof array, MinLengthTuple<2, number>>('=');
+
+        expect(array.length).toBeGreaterThanOrEqual(2);
+      }
+    });
+  });
+
+  describe(isMaxLengthTuple, () => {
+    test('should return true if array length is less than or equal to specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isMaxLengthTuple(3, arr));
+
+      if (isMaxLengthTuple(3, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+
+      assert.isTrue(isMaxLengthTuple(4, arr));
+
+      if (isMaxLengthTuple(4, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+    });
+
+    test('should return false if array length is greater than specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isMaxLengthTuple(2, arr));
+    });
+
+    test('should return true for empty array and length 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isMaxLengthTuple(0, arr));
+
+      if (isMaxLengthTuple(0, arr)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should return false for non-empty array and length 0', () => {
+      const arr = [1] as const;
+
+      assert.isFalse(isMaxLengthTuple(0, arr));
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isMaxLengthTuple(2, mut_arr));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & MaxLengthTuple<2, number>>('=');
+
+      assert.isFalse(isMaxLengthTuple(1, mut_arr));
+    });
+
+    test('should return true for arrays of at most specified length (additional)', () => {
+      assert.isTrue(isMaxLengthTuple(3, [1, 2, 3]));
+
+      assert.isTrue(isMaxLengthTuple(4, [1, 2, 3]));
+
+      assert.isTrue(isMaxLengthTuple(0, []));
+    });
+
+    test('should return false for arrays longer than specified length (additional)', () => {
+      assert.isFalse(isMaxLengthTuple(2, [1, 2, 3]));
+
+      assert.isFalse(isMaxLengthTuple(0, [1, 2, 3]));
+    });
+
+    test('should work as type guard for at most length (additional)', () => {
+      const array: readonly number[] = [1, 2] as const;
+
+      if (isMaxLengthTuple(3, array)) {
+        expectType<typeof array, MaxLengthTuple<3, number>>('=');
+
+        expect(array.length).toBeLessThanOrEqual(3);
+      }
+    });
+  });
+
+  describe(isBoundedLengthTuple, () => {
+    test('should return true if array length is within the specified range', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isBoundedLengthTuple(1, 3, arr));
+
+      if (isBoundedLengthTuple(1, 3, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+
+      assert.isTrue(isBoundedLengthTuple(3, 5, arr));
+
+      if (isBoundedLengthTuple(3, 5, arr)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+    });
+
+    test('should return false if array length is below the specified range', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isBoundedLengthTuple(4, 5, arr));
+    });
+
+    test('should return false if array length is above the specified range', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isBoundedLengthTuple(0, 2, arr));
+    });
+
+    test('should return true for empty array and range including 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isBoundedLengthTuple(0, 2, arr));
+
+      if (isBoundedLengthTuple(0, 2, arr)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isBoundedLengthTuple(1, 3, mut_arr));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & BoundedLengthTuple<1, 3, number>>(
+        '=',
+      );
+
+      assert.isFalse(isBoundedLengthTuple(3, 5, mut_arr));
+    });
+
+    test('should return true for arrays within specified range (additional)', () => {
+      assert.isTrue(isBoundedLengthTuple(1, 3, [1, 2, 3]));
+
+      assert.isTrue(isBoundedLengthTuple(3, 3, [1, 2, 3]));
+
+      assert.isTrue(isBoundedLengthTuple(0, 0, []));
+    });
+
+    test('should return false for arrays outside specified range (additional)', () => {
+      assert.isFalse(isBoundedLengthTuple(4, 5, [1, 2, 3]));
+
+      assert.isFalse(isBoundedLengthTuple(0, 2, [1, 2, 3]));
+    });
+
+    test('should work as type guard for bounded length (additional)', () => {
+      const array: readonly number[] = [1, 2] as const;
+
+      if (isBoundedLengthTuple(1, 3, array)) {
+        expectType<typeof array, BoundedLengthTuple<1, 3, number>>('=');
+
+        expect(array.length).toBeGreaterThanOrEqual(1);
+
+        expect(array.length).toBeLessThanOrEqual(3);
+      }
+    });
+  });
+
+  describe(isEmptyTuple, () => {
+    test('narrows an empty array to the empty tuple', () => {
+      const values: readonly number[] = [] as const;
+
+      assert.isTrue(isEmptyTuple(values));
+
+      if (isEmptyTuple(values)) {
+        expectType<typeof values, readonly []>('=');
+      }
+    });
+
+    test('rejects a non-empty array', () => {
+      assert.isFalse(isEmptyTuple([1] as const));
+    });
+  });
+
+  describe(isNonEmptyTuple, () => {
+    test('narrows to the structural non-empty tuple', () => {
+      const values: readonly number[] = [1, 2] as const;
+
+      assert.isTrue(isNonEmptyTuple(values));
+
+      if (isNonEmptyTuple(values)) {
+        expectType<typeof values, MinLengthTuple<1, number>>('=');
+
+        // The structural prefix makes the first element defined.
+        const first: number = values[0];
+
+        assert.deepStrictEqual(first, 1);
+      }
+    });
+
+    test('rejects an empty array', () => {
+      assert.isFalse(isNonEmptyTuple([] as const));
+    });
+  });
+});
+
+describe('curried tuple length guards', () => {
+  test('isFixedLengthTuple narrows when applied later', () => {
+    const isPair = isFixedLengthTuple(2);
+
+    assert.isTrue(isPair([1, 2]));
+
+    assert.isFalse(isPair([1, 2, 3]));
+
+    const value: readonly number[] = [1, 2] as const;
+
+    if (isPair(value)) {
+      expectType<typeof value, FixedLengthTuple<2, number>>('=');
+    }
+  });
+
+  test('isMinLengthTuple narrows when applied later', () => {
+    const hasOne = isMinLengthTuple(1);
+
+    assert.isTrue(hasOne(['task-1']));
+
+    assert.isFalse(hasOne([]));
+
+    const value: readonly string[] = ['task-1'] as const;
+
+    if (hasOne(value)) {
+      expectType<typeof value, MinLengthTuple<1, string>>('=');
+    }
+  });
+
+  test('isMaxLengthTuple narrows when applied later', () => {
+    const fitsInTwo = isMaxLengthTuple(2);
+
+    assert.isTrue(fitsInTwo([1, 2]));
+
+    assert.isFalse(fitsInTwo([1, 2, 3]));
+
+    const value: readonly number[] = [1, 2] as const;
+
+    if (fitsInTwo(value)) {
+      expectType<typeof value, MaxLengthTuple<2, number>>('=');
+    }
+  });
+
+  test('isBoundedLengthTuple narrows when applied later', () => {
+    const isSmall = isBoundedLengthTuple(1, 3);
+
+    assert.isTrue(isSmall([1, 2]));
+
+    assert.isFalse(isSmall([]));
+
+    assert.isFalse(isSmall([1, 2, 3, 4]));
+
+    const value: readonly number[] = [1, 2] as const;
+
+    if (isSmall(value)) {
+      expectType<typeof value, BoundedLengthTuple<1, 3, number>>('=');
+    }
+  });
+});