ts-data-forge 9.0.0 → 10.0.0

package/src/guard/as-length-bounded-array.test.mts

@@ -0,0 +1,118 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type MaxLengthArray,
+  type MinLengthArray,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import {
+  asBoundedLengthArray,
+  asFixedLengthArray,
+  asMaxLengthArray,
+  asMinLengthArray,
+} from './as-length-bounded-array.mjs';
+
+describe(asFixedLengthArray, () => {
+  test('should return the input when the length matches exactly', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asFixedLengthArray(xs, 4);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, FixedLengthArray<4, number>>('<=');
+
+    // in-range indexed access does not include `undefined`
+    const _first = casted[0];
+
+    expectType<typeof _first, number>('=');
+  });
+
+  test('should throw when the length does not match', () => {
+    expect(() => asFixedLengthArray([0, 1, 2], 4)).toThrow(TypeError);
+
+    expect(() => asFixedLengthArray([0, 1, 2], 4)).toThrow(
+      'Expected an array of length 4, got an array of length 3',
+    );
+  });
+
+  test('should preserve the original array type', () => {
+    const tuple = [1, 2, 3] as const;
+
+    const casted = asFixedLengthArray(tuple, 3);
+
+    expect(casted).toBe(tuple);
+
+    expectType<typeof casted, readonly [1, 2, 3]>('<=');
+
+    expectType<typeof casted, FixedLengthArray<3, 1 | 2 | 3>>('<=');
+  });
+});
+
+describe(asMinLengthArray, () => {
+  test('should return the input when the array is long enough', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asMinLengthArray(xs, 3);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MinLengthArray<3, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<='); // 3 >= 1
+  });
+
+  test('should throw when the array is too short', () => {
+    expect(() => asMinLengthArray([0], 3)).toThrow(TypeError);
+
+    expect(() => asMinLengthArray([0], 3)).toThrow(
+      'Expected an array of length >= 3, got an array of length 1',
+    );
+  });
+});
+
+describe(asMaxLengthArray, () => {
+  test('should return the input when the array is short enough', () => {
+    const xs: readonly number[] = [0, 1, 2] as const;
+
+    const casted = asMaxLengthArray(xs, 8);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MaxLengthArray<8, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<16, number>>('<='); // 8 <= 16
+  });
+
+  test('should throw when the array is too long', () => {
+    expect(() => asMaxLengthArray([0, 1, 2], 2)).toThrow(TypeError);
+
+    expect(() => asMaxLengthArray([0, 1, 2], 2)).toThrow(
+      'Expected an array of length <= 2, got an array of length 3',
+    );
+  });
+});
+
+describe(asBoundedLengthArray, () => {
+  test('should return the input when the length is within the range', () => {
+    const xs: readonly number[] = [1, 2, 3] as const;
+
+    const casted = asBoundedLengthArray(xs, 1, 5);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, BoundedLengthArray<1, 5, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<5, number>>('<=');
+  });
+
+  test('should throw when the length is out of the range', () => {
+    expect(() => asBoundedLengthArray([], 1, 5)).toThrow(TypeError);
+
+    expect(() => asBoundedLengthArray([1, 2, 3, 4, 5, 6], 1, 5)).toThrow(
+      'Expected an array of length in [1, 5], got an array of length 6',
+    );
+  });
+});

package/src/guard/index.mts

@@ -1,4 +1,6 @@
+export * from './as-length-bounded-array.mjs';
 export * from './has-key.mjs';
+export * from './is-length-bounded-array.mjs';
 export * from './is-length-bounded-string.mjs';
 export * from './is-non-empty-string.mjs';
 export * from './is-non-null-object.mjs';

package/src/guard/is-length-bounded-array.mts

@@ -0,0 +1,195 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type MaxLengthArray,
+  type MinLengthArray,
+  type SupportedLength,
+} from 'ts-type-forge';
+
+/**
+ * Type guard that checks if an array has at least `minLength` elements.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `MinLengthArray<MinLength, E>` while preserving the
+ *   original array type (e.g. tuple types) via intersection.
+ * - The length constraint lives only in the brand, so this stays cheap for the
+ *   type checker even when the element type is large — unlike
+ *   `isMinLengthTuple`, which narrows to a structural tuple type.
+ * - The result participates in the length-constraint subtyping relation: for
+ *   example, a value narrowed to `MinLengthArray<3, E>` is assignable to
+ *   `MinLengthArray<1, E>`.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: readonly number[] = [0, 1, 2, 3];
+ *
+ * assert.isTrue(isMinLengthArray(input, 3));
+ *
+ * assert.isFalse(isMinLengthArray([0], 3));
+ *
+ * if (isMinLengthArray(input, 3)) {
+ *   const history: MinLengthArray<3, number> = input;
+ *
+ *   const nonEmpty: MinLengthArray<1, number> = input; // OK (3 >= 1)
+ * }
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template MinLength - The minimum number of elements (inclusive).
+ * @param xs - The array to check.
+ * @param minLength - The minimum number of elements (inclusive).
+ * @returns `true` if `xs.length >= minLength`, `false` otherwise. When `true`,
+ *   TypeScript narrows `xs` to `MinLengthArray<MinLength, Xs[number]> & Xs`.
+ */
+export const isMinLengthArray = <
+  Xs extends readonly unknown[],
+  MinLength extends SupportedLength,
+>(
+  xs: Xs,
+  minLength: MinLength,
+): xs is MinLengthArray<MinLength, Xs[number]> & Xs => xs.length >= minLength;
+
+/**
+ * Type guard that checks if an array has at most `maxLength` elements.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `MaxLengthArray<MaxLength, E>` while preserving the
+ *   original array type (e.g. tuple types) via intersection.
+ * - The length constraint lives only in the brand, so this stays cheap for the
+ *   type checker even when the element type is large — unlike
+ *   `isMaxLengthTuple`, which narrows to a union of tuple types.
+ * - The result participates in the length-constraint subtyping relation: for
+ *   example, a value narrowed to `MaxLengthArray<8, E>` is assignable to
+ *   `MaxLengthArray<16, E>`.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: readonly string[] = ['a', 'b', 'c'];
+ *
+ * assert.isTrue(isMaxLengthArray(input, 8));
+ *
+ * assert.isFalse(isMaxLengthArray(input, 2));
+ *
+ * if (isMaxLengthArray(input, 8)) {
+ *   const tags: MaxLengthArray<8, string> = input;
+ *
+ *   const relaxed: MaxLengthArray<16, string> = input; // OK (8 <= 16)
+ * }
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template MaxLength - The maximum number of elements (inclusive).
+ * @param xs - The array to check.
+ * @param maxLength - The maximum number of elements (inclusive).
+ * @returns `true` if `xs.length <= maxLength`, `false` otherwise. When `true`,
+ *   TypeScript narrows `xs` to `MaxLengthArray<MaxLength, Xs[number]> & Xs`.
+ */
+export const isMaxLengthArray = <
+  Xs extends readonly unknown[],
+  MaxLength extends SupportedLength,
+>(
+  xs: Xs,
+  maxLength: MaxLength,
+): xs is MaxLengthArray<MaxLength, Xs[number]> & Xs => xs.length <= maxLength;
+
+/**
+ * Type guard that checks if an array's length is within the inclusive range
+ * `[minLength, maxLength]`.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `BoundedLengthArray<MinLength, MaxLength, E>` while
+ *   preserving the original array type (e.g. tuple types) via intersection.
+ * - Since `BoundedLengthArray` is the intersection of `MinLengthArray` and
+ *   `MaxLengthArray`, the narrowed value is assignable to both, and both
+ *   bounds can be weakened independently.
+ * - The length constraint lives only in the brand, so this stays cheap for the
+ *   type checker even when the element type is large — unlike
+ *   `isBoundedLengthTuple`, which narrows to a union of tuple types.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: readonly number[] = [1, 2, 3];
+ *
+ * assert.isTrue(isBoundedLengthArray(input, 1, 5));
+ *
+ * assert.isFalse(isBoundedLengthArray([], 1, 5));
+ *
+ * if (isBoundedLengthArray(input, 1, 5)) {
+ *   const selection: BoundedLengthArray<1, 5, number> = input;
+ *
+ *   const relaxed: BoundedLengthArray<0, 100, number> = input; // OK ([1, 5] ⊆ [0, 100])
+ * }
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template MinLength - The minimum number of elements (inclusive).
+ * @template MaxLength - The maximum number of elements (inclusive).
+ * @param xs - The array to check.
+ * @param minLength - The minimum number of elements (inclusive).
+ * @param maxLength - The maximum number of elements (inclusive).
+ * @returns `true` if `minLength <= xs.length && xs.length <= maxLength`,
+ *   `false` otherwise. When `true`, TypeScript narrows `xs` to
+ *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.
+ */
+export const isBoundedLengthArray = <
+  Xs extends readonly unknown[],
+  MinLength extends SupportedLength,
+  MaxLength extends SupportedLength,
+>(
+  xs: Xs,
+  minLength: MinLength,
+  maxLength: MaxLength,
+): xs is BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs =>
+  xs.length >= minLength && xs.length <= maxLength;
+
+/**
+ * Type guard that checks if an array has exactly `length` elements.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `FixedLengthArray<Length, E>` while preserving the
+ *   original array type (e.g. tuple types) via intersection.
+ * - Since `FixedLengthArray<Length, E>` is defined as
+ *   `BoundedLengthArray<Length, Length, E>`, the narrowed value is assignable
+ *   to any `MinLengthArray<N, E>` with `N <= Length` and any
+ *   `MaxLengthArray<N, E>` with `N >= Length`.
+ * - The length constraint lives only in the brand, so this stays cheap for the
+ *   type checker even when the element type is large — unlike
+ *   `isFixedLengthTuple`, which narrows to a structural tuple type.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: readonly number[] = [255, 128, 0];
+ *
+ * assert.isTrue(isFixedLengthArray(input, 3));
+ *
+ * assert.isFalse(isFixedLengthArray(input, 4));
+ *
+ * if (isFixedLengthArray(input, 3)) {
+ *   const rgb: FixedLengthArray<3, number> = input;
+ *
+ *   const atMost5: MaxLengthArray<5, number> = input; // OK (3 <= 5)
+ * }
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template Length - The exact number of elements.
+ * @param xs - The array to check.
+ * @param length - The exact number of elements.
+ * @returns `true` if `xs.length === length`, `false` otherwise. When `true`,
+ *   TypeScript narrows `xs` to `FixedLengthArray<Length, Xs[number]> & Xs`.
+ */
+export const isFixedLengthArray = <
+  Xs extends readonly unknown[],
+  Length extends SupportedLength,
+>(
+  xs: Xs,
+  length: Length,
+): xs is FixedLengthArray<Length, Xs[number]> & Xs => xs.length === length;

package/src/guard/is-length-bounded-array.test.mts

@@ -0,0 +1,169 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type MaxLengthArray,
+  type MinLengthArray,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import {
+  isBoundedLengthArray,
+  isFixedLengthArray,
+  isMaxLengthArray,
+  isMinLengthArray,
+} from './is-length-bounded-array.mjs';
+
+describe(isMinLengthArray, () => {
+  test('should return true when the array is long enough', () => {
+    assert.isTrue(isMinLengthArray([1, 2, 3], 3));
+
+    assert.isTrue(isMinLengthArray([1, 2, 3], 2));
+
+    assert.isTrue(isMinLengthArray([], 0));
+  });
+
+  test('should return false when the array is too short', () => {
+    assert.isFalse(isMinLengthArray([1, 2], 3));
+
+    assert.isFalse(isMinLengthArray([], 1));
+  });
+
+  test('should act as a type guard', () => {
+    const value: readonly number[] = [0, 1, 2, 3] as const;
+
+    if (isMinLengthArray(value, 3)) {
+      expectType<typeof value, MinLengthArray<3, number>>('<=');
+
+      expectType<typeof value, MinLengthArray<1, number>>('<='); // 3 >= 1
+
+      expectType<typeof value, MinLengthArray<5, number>>('!<=');
+
+      // indexed access below the minimum length does not include `undefined`
+      // (even under `noUncheckedIndexedAccess`)
+      const _first = value[0];
+
+      expectType<typeof _first, number>('=');
+
+      const _third = value[2];
+
+      expectType<typeof _third, number>('=');
+
+      const _fourth = value[3];
+
+      expectType<typeof _fourth, number | undefined>('=');
+
+      expect(value.length).toBeGreaterThanOrEqual(3);
+    }
+  });
+
+  test('should preserve the original array type', () => {
+    const tuple = [1, 2, 3] as const;
+
+    if (isMinLengthArray(tuple, 2)) {
+      expectType<typeof tuple, readonly [1, 2, 3]>('<=');
+
+      expectType<typeof tuple, MinLengthArray<2, 1 | 2 | 3>>('<=');
+    }
+  });
+});
+
+describe(isMaxLengthArray, () => {
+  test('should return true when the array is short enough', () => {
+    assert.isTrue(isMaxLengthArray([1, 2, 3], 3));
+
+    assert.isTrue(isMaxLengthArray([1, 2, 3], 4));
+
+    assert.isTrue(isMaxLengthArray([], 0));
+  });
+
+  test('should return false when the array is too long', () => {
+    assert.isFalse(isMaxLengthArray([1, 2, 3], 2));
+
+    assert.isFalse(isMaxLengthArray([1], 0));
+  });
+
+  test('should act as a type guard', () => {
+    const value: readonly number[] = [0, 1, 2] as const;
+
+    if (isMaxLengthArray(value, 8)) {
+      expectType<typeof value, MaxLengthArray<8, number>>('<=');
+
+      expectType<typeof value, MaxLengthArray<16, number>>('<='); // 8 <= 16
+
+      expectType<typeof value, MaxLengthArray<2, number>>('!<=');
+
+      expect(value.length).toBeLessThanOrEqual(8);
+    }
+  });
+});
+
+describe(isBoundedLengthArray, () => {
+  test('should return true when the length is within the range', () => {
+    assert.isTrue(isBoundedLengthArray([1, 2, 3], 1, 5));
+
+    assert.isTrue(isBoundedLengthArray([1], 1, 5));
+
+    assert.isTrue(isBoundedLengthArray([1, 2, 3, 4, 5], 1, 5));
+  });
+
+  test('should return false when the length is out of the range', () => {
+    assert.isFalse(isBoundedLengthArray([], 1, 5));
+
+    assert.isFalse(isBoundedLengthArray([1, 2, 3, 4, 5, 6], 1, 5));
+  });
+
+  test('should act as a type guard', () => {
+    const value: readonly number[] = [1, 2, 3] as const;
+
+    if (isBoundedLengthArray(value, 1, 5)) {
+      expectType<typeof value, BoundedLengthArray<1, 5, number>>('<=');
+
+      expectType<typeof value, BoundedLengthArray<0, 100, number>>('<=');
+
+      expectType<typeof value, MinLengthArray<1, number>>('<=');
+
+      expectType<typeof value, MaxLengthArray<5, number>>('<=');
+
+      expectType<typeof value, BoundedLengthArray<2, 5, number>>('!<=');
+    }
+  });
+});
+
+describe(isFixedLengthArray, () => {
+  test('should return true when the length matches exactly', () => {
+    assert.isTrue(isFixedLengthArray([1, 2, 3], 3));
+
+    assert.isTrue(isFixedLengthArray([], 0));
+  });
+
+  test('should return false when the length does not match', () => {
+    assert.isFalse(isFixedLengthArray([1, 2, 3], 2));
+
+    assert.isFalse(isFixedLengthArray([1, 2, 3], 4));
+  });
+
+  test('should act as a type guard', () => {
+    const value: readonly number[] = [255, 128, 0] as const;
+
+    if (isFixedLengthArray(value, 3)) {
+      expectType<typeof value, FixedLengthArray<3, number>>('<=');
+
+      expectType<typeof value, MaxLengthArray<5, number>>('<='); // 3 <= 5
+
+      expectType<typeof value, MinLengthArray<1, number>>('<='); // 3 >= 1
+
+      expectType<typeof value, FixedLengthArray<4, number>>('!<=');
+
+      // `length` is narrowed to the literal and in-range indexed access does
+      // not include `undefined` (even under `noUncheckedIndexedAccess`)
+      const _len = value.length;
+
+      expectType<typeof _len, 3>('=');
+
+      const _second = value[1];
+
+      expectType<typeof _second, number>('=');
+
+      expect(value).toHaveLength(3);
+    }
+  });
+});

package/src/guard/is-length-bounded-string.mts

@@ -3,8 +3,8 @@ import {
   type FixedLengthString,
   type MaxLengthString,
   type MinLengthString,
+  type SupportedLength,
 } from 'ts-type-forge';
-import { type SizeType } from '../types.mjs';
 
 /**
  * Type guard that checks if a string has at least `minLength` characters.
@@ -46,7 +46,7 @@ import { type SizeType } from '../types.mjs';
  */
 export const isMinLengthString = <
   S extends string,
-  MinLength extends SizeType.ArgStr,
+  MinLength extends SupportedLength,
 >(
   s: S,
   minLength: MinLength,
@@ -92,7 +92,7 @@ export const isMinLengthString = <
  */
 export const isMaxLengthString = <
   S extends string,
-  MaxLength extends SizeType.ArgStr,
+  MaxLength extends SupportedLength,
 >(
   s: S,
   maxLength: MaxLength,
@@ -142,8 +142,8 @@ export const isMaxLengthString = <
  */
 export const isBoundedLengthString = <
   S extends string,
-  MinLength extends SizeType.ArgStr,
-  MaxLength extends SizeType.ArgStr,
+  MinLength extends SupportedLength,
+  MaxLength extends SupportedLength,
 >(
   s: S,
   minLength: MinLength,
@@ -192,7 +192,7 @@ export const isBoundedLengthString = <
  */
 export const isFixedLengthString = <
   S extends string,
-  Length extends SizeType.ArgStr,
+  Length extends SupportedLength,
 >(
   s: S,
   length: Length,

package/src/object/object.test.mts

@@ -1,6 +1,6 @@
 import {
-  type ArrayOfLength,
   type DeepReadonly,
+  type FixedLengthTuple,
   type UnknownRecord,
 } from 'ts-type-forge';
 import { expectType } from '../expect-type.mjs';
@@ -407,7 +407,7 @@ describe('merge', () => {
   test('type: MergeAll with fixed length typed array', () => {
     type MyRecord = Readonly<{ x: number; y: string }>;
 
-    const records: ArrayOfLength<3, MyRecord> = [
+    const records: FixedLengthTuple<3, MyRecord> = [
       { x: 1, y: 'a' },
       { x: 2, y: 'b' },
       { x: 3, y: 'c' },
@@ -438,7 +438,7 @@ describe('merge', () => {
   test('type: MergeAll with fixed length typed array and optional properties', () => {
     type RecordWithOptional = Readonly<{ x: number; y?: string }>;
 
-    const records: ArrayOfLength<2, RecordWithOptional> = [
+    const records: FixedLengthTuple<2, RecordWithOptional> = [
       { x: 1, y: 'a' },
       { x: 2 },
     ] as const;