ts-data-forge 7.0.0 → 7.1.0

package/src/array/impl/array-utils-reducing-value.mts

@@ -265,7 +265,7 @@ export function count<E>(
  * ```ts
  * const words = ['Ada', 'Grace', 'Alan', 'Barbara'] as const;
  *
- * const counts = Arr.countBy(words, (word) => word[0]);
+ * const counts = Arr.countBy(words, (word) => word.at(0));
  *
  * assert.deepStrictEqual(counts.get('A'), Optional.some(2));
  *
@@ -503,7 +503,6 @@ export function sum(array: readonly Int[]): Int;
 export function sum(array: readonly number[]): number;
 
 export function sum(array: readonly number[]): number {
-  // eslint-disable-next-line ts-data-forge/prefer-arr-sum
   return array.reduce((prev, curr) => prev + curr, 0);
 }
 

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

@@ -196,7 +196,6 @@ export function findLast<E>(
  *
  * const indexOfB = Arr.findIndex(letters, (letter) => letter === 'b');
  *
- * // eslint-disable-next-line unicorn/prefer-array-index-of
  * const indexOfMissing = Arr.findIndex<string>((letter) => letter === 'z')(
  *   letters,
  * );
@@ -263,7 +262,6 @@ export function findIndex<E>(
  *
  * const lastIndexOfB = Arr.findLastIndex(letters, (letter) => letter === 'b');
  *
- * // eslint-disable-next-line unicorn/prefer-array-index-of
  * const notFound = Arr.findLastIndex<string>((letter) => letter === 'z')(
  *   letters,
  * );

package/src/array/impl/array-utils-set-op.mts

@@ -105,7 +105,6 @@ export const setIntersection = <
   array1: readonly E1[],
   array2: readonly E2[],
 ): readonly (E1 & E2)[] =>
-  // transformer-ignore-next-line
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   (array1 as readonly (E1 & E2)[]).filter((e) => array2.includes(e));
 

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

@@ -540,13 +540,15 @@ export function flat<E, D extends SafeUintWithSmallInt = 1>(
         const depth = arrayOrDepth as SafeUintWithSmallInt | undefined;
 
         return (array) => flat(array, depth);
-      } else if (arrayOrDepth === undefined) {
-        return (array) => flat(array, 1);
-      } else {
-        expectType<typeof arrayOrDepth, readonly E[]>('=');
+      }
 
-        return arrayOrDepth.flat();
+      if (arrayOrDepth === undefined) {
+        return (array) => flat(array, 1);
       }
+
+      expectType<typeof arrayOrDepth, readonly E[]>('=');
+
+      return arrayOrDepth.flat();
     }
 
     case 0:
@@ -709,7 +711,7 @@ export const concat = <
  *
  * const groupedByLength = Arr.groupBy(animals, (animal) => animal.length);
  *
- * const groupedByFirstLetter = Arr.groupBy((animal: string) => animal[0])(
+ * const groupedByFirstLetter = Arr.groupBy((animal: string) => animal.at(0))(
  *   animals,
  * );
  *

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

@@ -1,5 +1,7 @@
 import {
   type ArrayAtLeastLen,
+  type ArrayAtMostLen,
+  type ArrayBoundedLen,
   type ArrayOfLength,
   type BoolOr,
   type NonEmptyArray,
@@ -28,7 +30,6 @@ import { type ArrayIndex, type SizeType } from '../../types.mjs';
  * ```
  */
 export const isArray = <E,>(value: E): value is FilterArray<E> =>
-  // eslint-disable-next-line ts-data-forge/prefer-arr-is-array
   Array.isArray(value);
 
 type FilterArray<T> = T extends T
@@ -64,7 +65,6 @@ type Cast<A, B> = A extends B ? A : never;
  * ```
  */
 export const isEmpty = <E,>(array: readonly E[]): array is readonly [] =>
-  // eslint-disable-next-line ts-data-forge/prefer-arr-is-array-of-length
   array.length === 0;
 
 /**
@@ -88,9 +88,7 @@ export const isEmpty = <E,>(array: readonly E[]): array is readonly [] =>
  */
 export const isNonEmpty = <E,>(
   array: readonly E[],
-): array is NonEmptyArray<E> =>
-  // eslint-disable-next-line ts-data-forge/prefer-arr-is-non-empty
-  array.length > 0;
+): array is NonEmptyArray<E> => array.length > 0;
 
 /**
  * Checks if an array has a specific length.
@@ -140,6 +138,60 @@ export const isArrayAtLeastLength = <E, N extends SizeType.ArgArr>(
   len: N,
 ): array is ArrayAtLeastLen<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.isArrayAtMostLength(pair, 2));
+ *
+ * assert.isFalse(Arr.isArrayAtMostLength(triple, 2));
+ *
+ * if (Arr.isArrayAtMostLength(pair, 2)) {
+ *   assert.isTrue(pair.length <= 2);
+ * }
+ * ```
+ */
+export const isArrayAtMostLength = <E, N extends SizeType.ArgArr>(
+  array: readonly E[],
+  len: N,
+): array is ArrayAtMostLen<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.isArrayBoundedLength(pair, 1, 3));
+ *
+ * assert.isFalse(Arr.isArrayBoundedLength(quad, 1, 3));
+ *
+ * if (Arr.isArrayBoundedLength(pair, 1, 3)) {
+ *   assert.isTrue(pair.length >= 1 && pair.length <= 3);
+ * }
+ * ```
+ */
+export const isArrayBoundedLength = <
+  E,
+  Min extends SizeType.ArgArr,
+  Max extends SizeType.ArgArr,
+>(
+  array: readonly E[],
+  min: Min,
+  max: Max,
+): array is ArrayBoundedLen<Min, Max, E> =>
+  array.length >= min && array.length <= max;
+
 /**
  * Tests whether all elements in an array pass a test implemented by a predicate.
  *

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

@@ -1,10 +1,17 @@
-import { type ArrayAtLeastLen, type ArrayOfLength } from 'ts-type-forge';
+import {
+  type ArrayAtLeastLen,
+  type ArrayAtMostLen,
+  type ArrayBoundedLen,
+  type ArrayOfLength,
+} from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import {
   every,
   indexIsInRange,
   isArray,
   isArrayAtLeastLength,
+  isArrayAtMostLength,
+  isArrayBoundedLength,
   isArrayOfLength,
   isEmpty,
   isNonEmpty,
@@ -584,6 +591,158 @@ describe('Arr validations', () => {
     });
   });
 
+  describe(isArrayAtMostLength, () => {
+    test('should return true if array length is less than or equal to specified length', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isArrayAtMostLength(arr, 3));
+
+      if (isArrayAtMostLength(arr, 3)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+
+      assert.isTrue(isArrayAtMostLength(arr, 4));
+
+      if (isArrayAtMostLength(arr, 4)) {
+        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(isArrayAtMostLength(arr, 2));
+    });
+
+    test('should return true for empty array and length 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isArrayAtMostLength(arr, 0));
+
+      if (isArrayAtMostLength(arr, 0)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should return false for non-empty array and length 0', () => {
+      const arr = [1] as const;
+
+      assert.isFalse(isArrayAtMostLength(arr, 0));
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isArrayAtMostLength(mut_arr, 2));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & ArrayAtMostLen<2, number>>('=');
+
+      assert.isFalse(isArrayAtMostLength(mut_arr, 1));
+    });
+
+    test('should return true for arrays of at most specified length (additional)', () => {
+      assert.isTrue(isArrayAtMostLength([1, 2, 3], 3));
+
+      assert.isTrue(isArrayAtMostLength([1, 2, 3], 4));
+
+      assert.isTrue(isArrayAtMostLength([], 0));
+    });
+
+    test('should return false for arrays longer than specified length (additional)', () => {
+      assert.isFalse(isArrayAtMostLength([1, 2, 3], 2));
+
+      assert.isFalse(isArrayAtMostLength([1, 2, 3], 0));
+    });
+
+    test('should work as type guard for at most length (additional)', () => {
+      const array: readonly number[] = [1, 2] as const;
+
+      if (isArrayAtMostLength(array, 3)) {
+        expectType<typeof array, ArrayAtMostLen<3, number>>('=');
+
+        expect(array.length).toBeLessThanOrEqual(3);
+      }
+    });
+  });
+
+  describe(isArrayBoundedLength, () => {
+    test('should return true if array length is within the specified range', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isTrue(isArrayBoundedLength(arr, 1, 3));
+
+      if (isArrayBoundedLength(arr, 1, 3)) {
+        expectType<typeof arr, readonly [1, 2, 3]>('=');
+      }
+
+      assert.isTrue(isArrayBoundedLength(arr, 3, 5));
+
+      if (isArrayBoundedLength(arr, 3, 5)) {
+        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(isArrayBoundedLength(arr, 4, 5));
+    });
+
+    test('should return false if array length is above the specified range', () => {
+      const arr = [1, 2, 3] as const;
+
+      assert.isFalse(isArrayBoundedLength(arr, 0, 2));
+    });
+
+    test('should return true for empty array and range including 0', () => {
+      const arr = [] as const;
+
+      assert.isTrue(isArrayBoundedLength(arr, 0, 2));
+
+      if (isArrayBoundedLength(arr, 0, 2)) {
+        expectType<typeof arr, readonly []>('=');
+      }
+    });
+
+    test('should work with unknown array type', () => {
+      const mut_arr: number[] = [1, 2];
+
+      assert.isTrue(isArrayBoundedLength(mut_arr, 1, 3));
+
+      // transformer-ignore-next-line
+      expectType<typeof mut_arr, number[] & ArrayBoundedLen<1, 3, number>>('=');
+
+      assert.isFalse(isArrayBoundedLength(mut_arr, 3, 5));
+    });
+
+    test('should return true for arrays within specified range (additional)', () => {
+      assert.isTrue(isArrayBoundedLength([1, 2, 3], 1, 3));
+
+      assert.isTrue(isArrayBoundedLength([1, 2, 3], 3, 3));
+
+      assert.isTrue(isArrayBoundedLength([], 0, 0));
+    });
+
+    test('should return false for arrays outside specified range (additional)', () => {
+      assert.isFalse(isArrayBoundedLength([1, 2, 3], 4, 5));
+
+      assert.isFalse(isArrayBoundedLength([1, 2, 3], 0, 2));
+    });
+
+    test('should work as type guard for bounded length (additional)', () => {
+      const array: readonly number[] = [1, 2] as const;
+
+      if (isArrayBoundedLength(array, 1, 3)) {
+        expectType<typeof array, ArrayBoundedLen<1, 3, number>>('=');
+
+        expect(array.length).toBeGreaterThanOrEqual(1);
+
+        expect(array.length).toBeLessThanOrEqual(3);
+      }
+    });
+  });
+
   describe(every, () => {
     test('should return true when all elements satisfy predicate', () => {
       const evens = [2, 4, 6, 8] as const;