ts-data-forge 9.0.1 → 11.0.0

package/src/array/impl/array-utils-length-bounded-array-cast.mts

@@ -0,0 +1,190 @@
+import {
+  type BoundedLengthArray,
+  type FixedLengthArray,
+  type MaxLengthArray,
+  type MinLengthArray,
+  type SupportedLength,
+} from 'ts-type-forge';
+import {
+  isBoundedLengthArray,
+  isFixedLengthArray,
+  isMaxLengthArray,
+  isMinLengthArray,
+} from './array-utils-length-bounded-array-guard.mjs';
+
+/**
+ * Casts an array to `FixedLengthArray<Length, E>` after checking that it has
+ * exactly `length` elements.
+ *
+ * Use this instead of writing `xs as unknown as FixedLengthArray<N, E>`: the
+ * length is verified at runtime, and the original array type (e.g. tuple
+ * types) is preserved via intersection, so the result also benefits from the
+ * structural tuple prefix (in-range indexed access without `undefined` under
+ * `noUncheckedIndexedAccess`).
+ *
+ * @example
+ *
+ * ```ts
+ * const rgb = Arr.asFixedLengthArray([255, 128, 0], 3);
+ *
+ * const atMost5: MaxLengthArray<5, number> = rgb; // OK (3 <= 5)
+ * const red: number = rgb[0]; // OK — no `undefined`
+ *
+ * // Arr.asFixedLengthArray([255, 128], 3); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template Length - The exact number of elements.
+ * @param xs - The array to cast.
+ * @param length - The exact number of elements.
+ * @returns `xs` typed as `FixedLengthArray<Length, Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs.length !== length`.
+ */
+export const asFixedLengthArray = <
+  Xs extends readonly unknown[],
+  Length extends SupportedLength,
+>(
+  xs: Xs,
+  length: Length,
+): FixedLengthArray<Length, Xs[number]> & Xs => {
+  if (!isFixedLengthArray(xs, length)) {
+    throw new TypeError(
+      `Expected an array of length ${length}, got an array of length ${xs.length}`,
+    );
+  }
+
+  return xs;
+};
+
+/**
+ * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has
+ * at least `minLength` elements.
+ *
+ * Use this instead of writing `xs as unknown as MinLengthArray<N, E>`: the
+ * length is verified at runtime, and the original array type (e.g. tuple
+ * types) is preserved via intersection, so the result also benefits from the
+ * structural tuple prefix (indexed access below `min(N, 10)` without
+ * `undefined` under `noUncheckedIndexedAccess`).
+ *
+ * @example
+ *
+ * ```ts
+ * const history = Arr.asMinLengthArray([0, 1, 2, 3], 3);
+ *
+ * const nonEmpty: MinLengthArray<1, number> = history; // OK (3 >= 1)
+ * const first: number = history[0]; // OK — no `undefined`
+ *
+ * // Arr.asMinLengthArray([0], 3); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template MinLength - The minimum number of elements (inclusive).
+ * @param xs - The array to cast.
+ * @param minLength - The minimum number of elements (inclusive).
+ * @returns `xs` typed as `MinLengthArray<MinLength, Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs.length < minLength`.
+ */
+export const asMinLengthArray = <
+  Xs extends readonly unknown[],
+  MinLength extends SupportedLength,
+>(
+  xs: Xs,
+  minLength: MinLength,
+): MinLengthArray<MinLength, Xs[number]> & Xs => {
+  if (!isMinLengthArray(xs, minLength)) {
+    throw new TypeError(
+      `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`,
+    );
+  }
+
+  return xs;
+};
+
+/**
+ * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has
+ * at most `maxLength` elements.
+ *
+ * Use this instead of writing `xs as unknown as MaxLengthArray<N, E>`: the
+ * length is verified at runtime, and the original array type (e.g. tuple
+ * types) is preserved via intersection.
+ *
+ * @example
+ *
+ * ```ts
+ * const tags = Arr.asMaxLengthArray(['a', 'b', 'c'], 8);
+ *
+ * const relaxed: MaxLengthArray<16, string> = tags; // OK (8 <= 16)
+ *
+ * // Arr.asMaxLengthArray(['a', 'b', 'c'], 2); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @template MaxLength - The maximum number of elements (inclusive).
+ * @param xs - The array to cast.
+ * @param maxLength - The maximum number of elements (inclusive).
+ * @returns `xs` typed as `MaxLengthArray<MaxLength, Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs.length > maxLength`.
+ */
+export const asMaxLengthArray = <
+  Xs extends readonly unknown[],
+  MaxLength extends SupportedLength,
+>(
+  xs: Xs,
+  maxLength: MaxLength,
+): MaxLengthArray<MaxLength, Xs[number]> & Xs => {
+  if (!isMaxLengthArray(xs, maxLength)) {
+    throw new TypeError(
+      `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`,
+    );
+  }
+
+  return xs;
+};
+
+/**
+ * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after
+ * checking that its length is within the inclusive range
+ * `[minLength, maxLength]`.
+ *
+ * Use this instead of writing
+ * `xs as unknown as BoundedLengthArray<Min, Max, E>`: the length is verified
+ * at runtime, and the original array type (e.g. tuple types) is preserved via
+ * intersection.
+ *
+ * @example
+ *
+ * ```ts
+ * const selection = Arr.asBoundedLengthArray([1, 2, 3], 1, 5);
+ *
+ * const relaxed: BoundedLengthArray<0, 100, number> = selection; // OK
+ *
+ * // Arr.asBoundedLengthArray([], 1, 5); // throws TypeError
+ * ```
+ *
+ * @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 cast.
+ * @param minLength - The minimum number of elements (inclusive).
+ * @param maxLength - The maximum number of elements (inclusive).
+ * @returns `xs` typed as
+ *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs.length < minLength || xs.length > maxLength`.
+ */
+export const asBoundedLengthArray = <
+  Xs extends readonly unknown[],
+  MinLength extends SupportedLength,
+  MaxLength extends SupportedLength,
+>(
+  xs: Xs,
+  minLength: MinLength,
+  maxLength: MaxLength,
+): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs => {
+  if (!isBoundedLengthArray(xs, minLength, maxLength)) {
+    throw new TypeError(
+      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${xs.length}`,
+    );
+  }
+
+  return xs;
+};

package/src/array/impl/array-utils-length-bounded-array-cast.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 './array-utils-length-bounded-array-cast.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/array/impl/array-utils-length-bounded-array-guard.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(Arr.isMinLengthArray(input, 3));
+ *
+ * assert.isFalse(Arr.isMinLengthArray([0], 3));
+ *
+ * if (Arr.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(Arr.isMaxLengthArray(input, 8));
+ *
+ * assert.isFalse(Arr.isMaxLengthArray(input, 2));
+ *
+ * if (Arr.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(Arr.isBoundedLengthArray(input, 1, 5));
+ *
+ * assert.isFalse(Arr.isBoundedLengthArray([], 1, 5));
+ *
+ * if (Arr.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(Arr.isFixedLengthArray(input, 3));
+ *
+ * assert.isFalse(Arr.isFixedLengthArray(input, 4));
+ *
+ * if (Arr.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/array/impl/array-utils-length-bounded-array-guard.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 './array-utils-length-bounded-array-guard.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);
+    }
+  });
+});