ts-data-forge 11.0.1 → 12.1.0

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

@@ -3,6 +3,7 @@ import {
   type FixedLengthArray,
   type MaxLengthArray,
   type MinLengthArray,
+  type NonEmptyArray,
   type SupportedLength,
 } from 'ts-type-forge';
 import {
@@ -22,6 +23,9 @@ import {
  * structural tuple prefix (in-range indexed access without `undefined` under
  * `noUncheckedIndexedAccess`).
  *
+ * Supports a curried overload: calling it with only `length` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -30,6 +34,10 @@ import {
  * const atMost5: MaxLengthArray<5, number> = rgb; // OK (3 <= 5)
  * const red: number = rgb[0]; // OK — no `undefined`
  *
+ * // curried version
+ * const asRgb = Arr.asFixedLengthArray(3);
+ * const green = asRgb([0, 255, 0]);
+ *
  * // Arr.asFixedLengthArray([255, 128], 3); // throws TypeError
  * ```
  *
@@ -40,21 +48,43 @@ import {
  * @returns `xs` typed as `FixedLengthArray<Length, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length !== length`.
  */
-export const asFixedLengthArray = <
+export function asFixedLengthArray<
   Xs extends readonly unknown[],
   Length extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, length: Length): FixedLengthArray<Length, Xs[number]> & Xs;
+
+// Curried version
+export function asFixedLengthArray<Length extends SupportedLength>(
   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}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => FixedLengthArray<Length, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asFixedLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], length: SupportedLength]
+    | readonly [length: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, length] = args;
+
+      if (!isFixedLengthArray(xs, length)) {
+        throw new TypeError(
+          `Expected an array of length ${length}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [length] = args;
+
+      return (xs) => asFixedLengthArray(xs, length);
+    }
+  }
+}
 
 /**
  * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has
@@ -66,6 +96,9 @@ export const asFixedLengthArray = <
  * structural tuple prefix (indexed access below `min(N, 10)` without
  * `undefined` under `noUncheckedIndexedAccess`).
  *
+ * Supports a curried overload: calling it with only `minLength` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -74,6 +107,10 @@ export const asFixedLengthArray = <
  * const nonEmpty: MinLengthArray<1, number> = history; // OK (3 >= 1)
  * const first: number = history[0]; // OK — no `undefined`
  *
+ * // curried version
+ * const asHistory = Arr.asMinLengthArray(3);
+ * const next = asHistory([4, 5, 6, 7]);
+ *
  * // Arr.asMinLengthArray([0], 3); // throws TypeError
  * ```
  *
@@ -84,21 +121,43 @@ export const asFixedLengthArray = <
  * @returns `xs` typed as `MinLengthArray<MinLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength`.
  */
-export const asMinLengthArray = <
+export function asMinLengthArray<
   Xs extends readonly unknown[],
   MinLength extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, minLength: MinLength): MinLengthArray<MinLength, Xs[number]> & Xs;
+
+// Curried version
+export function asMinLengthArray<MinLength extends SupportedLength>(
   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}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => MinLengthArray<MinLength, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asMinLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], minLength: SupportedLength]
+    | readonly [minLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, minLength] = args;
+
+      if (!isMinLengthArray(xs, minLength)) {
+        throw new TypeError(
+          `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [minLength] = args;
+
+      return (xs) => asMinLengthArray(xs, minLength);
+    }
+  }
+}
 
 /**
  * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has
@@ -108,6 +167,9 @@ export const asMinLengthArray = <
  * length is verified at runtime, and the original array type (e.g. tuple
  * types) is preserved via intersection.
  *
+ * Supports a curried overload: calling it with only `maxLength` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -115,6 +177,10 @@ export const asMinLengthArray = <
  *
  * const relaxed: MaxLengthArray<16, string> = tags; // OK (8 <= 16)
  *
+ * // curried version
+ * const asTags = Arr.asMaxLengthArray(8);
+ * const more = asTags(['d', 'e']);
+ *
  * // Arr.asMaxLengthArray(['a', 'b', 'c'], 2); // throws TypeError
  * ```
  *
@@ -125,21 +191,43 @@ export const asMinLengthArray = <
  * @returns `xs` typed as `MaxLengthArray<MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length > maxLength`.
  */
-export const asMaxLengthArray = <
+export function asMaxLengthArray<
   Xs extends readonly unknown[],
   MaxLength extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, maxLength: MaxLength): MaxLengthArray<MaxLength, Xs[number]> & Xs;
+
+// Curried version
+export function asMaxLengthArray<MaxLength extends SupportedLength>(
   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}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => MaxLengthArray<MaxLength, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asMaxLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], maxLength: SupportedLength]
+    | readonly [maxLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, maxLength] = args;
+
+      if (!isMaxLengthArray(xs, maxLength)) {
+        throw new TypeError(
+          `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [maxLength] = args;
+
+      return (xs) => asMaxLengthArray(xs, maxLength);
+    }
+  }
+}
 
 /**
  * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after
@@ -151,6 +239,10 @@ export const asMaxLengthArray = <
  * at runtime, and the original array type (e.g. tuple types) is preserved via
  * intersection.
  *
+ * Supports a curried overload: calling it with only `minLength` and
+ * `maxLength` returns a function that casts an array, which is convenient for
+ * `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -158,6 +250,10 @@ export const asMaxLengthArray = <
  *
  * const relaxed: BoundedLengthArray<0, 100, number> = selection; // OK
  *
+ * // curried version
+ * const asSelection = Arr.asBoundedLengthArray(1, 5);
+ * const next = asSelection([4, 5]);
+ *
  * // Arr.asBoundedLengthArray([], 1, 5); // throws TypeError
  * ```
  *
@@ -171,7 +267,7 @@ export const asMaxLengthArray = <
  *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength || xs.length > maxLength`.
  */
-export const asBoundedLengthArray = <
+export function asBoundedLengthArray<
   Xs extends readonly unknown[],
   MinLength extends SupportedLength,
   MaxLength extends SupportedLength,
@@ -179,11 +275,80 @@ export const asBoundedLengthArray = <
   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}`,
-    );
+): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+
+// Curried version
+export function asBoundedLengthArray<
+  MinLength extends SupportedLength,
+  MaxLength extends SupportedLength,
+>(
+  minLength: MinLength,
+  maxLength: MaxLength,
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+
+export function asBoundedLengthArray<E>(
+  ...args:
+    | readonly [
+        xs: readonly E[],
+        minLength: SupportedLength,
+        maxLength: SupportedLength,
+      ]
+    | readonly [minLength: SupportedLength, maxLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 3: {
+      const [xs, minLength, maxLength] = args;
+
+      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;
+    }
+
+    case 2: {
+      const [minLength, maxLength] = args;
+
+      return (xs) => asBoundedLengthArray(xs, minLength, maxLength);
+    }
+  }
+}
+
+/**
+ * Casts an array to `NonEmptyArray<E>` after checking that it has at least one
+ * element.
+ *
+ * `NonEmptyArray<E>` is an alias of `MinLengthArray<1, E>`, so this is the
+ * length-1 specialization of {@link asMinLengthArray}. Use this instead of
+ * writing `xs as unknown as NonEmptyArray<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
+ * (`xs[0]` without `undefined` under `noUncheckedIndexedAccess`).
+ *
+ * @example
+ *
+ * ```ts
+ * const history = Arr.asNonEmptyArray([0, 1, 2, 3]);
+ *
+ * const first: number = history[0]; // OK — no `undefined`
+ *
+ * // Arr.asNonEmptyArray([]); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @param xs - The array to cast.
+ * @returns `xs` typed as `NonEmptyArray<Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs` is empty.
+ */
+export const asNonEmptyArray = <Xs extends readonly unknown[]>(
+  xs: Xs,
+): NonEmptyArray<Xs[number]> & Xs => {
+  if (!isMinLengthArray(xs, 1)) {
+    throw new TypeError('Expected a non-empty array, got an empty array');
   }
 
   return xs;

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

@@ -3,6 +3,7 @@ import {
   type FixedLengthArray,
   type MaxLengthArray,
   type MinLengthArray,
+  type NonEmptyArray,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import {
@@ -10,6 +11,7 @@ import {
   asFixedLengthArray,
   asMaxLengthArray,
   asMinLengthArray,
+  asNonEmptyArray,
 } from './array-utils-length-bounded-array-cast.mjs';
 
 describe(asFixedLengthArray, () => {
@@ -47,6 +49,29 @@ describe(asFixedLengthArray, () => {
 
     expectType<typeof casted, FixedLengthArray<3, 1 | 2 | 3>>('<=');
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asFixedLengthArray(4)(xs);
+
+    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('curried version throws when the length does not match', () => {
+    expect(() => asFixedLengthArray(4)([0, 1, 2])).toThrow(TypeError);
+
+    expect(() => asFixedLengthArray(4)([0, 1, 2])).toThrow(
+      'Expected an array of length 4, got an array of length 3',
+    );
+  });
 });
 
 describe(asMinLengthArray, () => {
@@ -69,6 +94,26 @@ describe(asMinLengthArray, () => {
       'Expected an array of length >= 3, got an array of length 1',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asMinLengthArray(3)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MinLengthArray<3, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<='); // 3 >= 1
+  });
+
+  test('curried version throws when the array is too short', () => {
+    expect(() => asMinLengthArray(3)([0])).toThrow(TypeError);
+
+    expect(() => asMinLengthArray(3)([0])).toThrow(
+      'Expected an array of length >= 3, got an array of length 1',
+    );
+  });
 });
 
 describe(asMaxLengthArray, () => {
@@ -91,6 +136,26 @@ describe(asMaxLengthArray, () => {
       'Expected an array of length <= 2, got an array of length 3',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2] as const;
+
+    const casted = asMaxLengthArray(8)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MaxLengthArray<8, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<16, number>>('<='); // 8 <= 16
+  });
+
+  test('curried version throws when the array is too long', () => {
+    expect(() => asMaxLengthArray(2)([0, 1, 2])).toThrow(TypeError);
+
+    expect(() => asMaxLengthArray(2)([0, 1, 2])).toThrow(
+      'Expected an array of length <= 2, got an array of length 3',
+    );
+  });
 });
 
 describe(asBoundedLengthArray, () => {
@@ -115,4 +180,65 @@ describe(asBoundedLengthArray, () => {
       'Expected an array of length in [1, 5], got an array of length 6',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [1, 2, 3] as const;
+
+    const casted = asBoundedLengthArray(1, 5)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, BoundedLengthArray<1, 5, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<5, number>>('<=');
+  });
+
+  test('curried version throws when the length is out of the range', () => {
+    expect(() => asBoundedLengthArray(1, 5)([])).toThrow(TypeError);
+
+    expect(() => asBoundedLengthArray(1, 5)([1, 2, 3, 4, 5, 6])).toThrow(
+      'Expected an array of length in [1, 5], got an array of length 6',
+    );
+  });
+});
+
+describe(asNonEmptyArray, () => {
+  test('should return the input when the array is non-empty', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asNonEmptyArray(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, NonEmptyArray<number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<=');
+
+    // in-range indexed access does not include `undefined`
+    const _first = casted[0];
+
+    expectType<typeof _first, number>('=');
+  });
+
+  test('should throw when the array is empty', () => {
+    expect(() => asNonEmptyArray([])).toThrow(TypeError);
+
+    expect(() => asNonEmptyArray([])).toThrow(
+      'Expected a non-empty array, got an empty array',
+    );
+  });
+
+  test('should preserve the original array type', () => {
+    const tuple = [1, 2, 3] as const;
+
+    const casted = asNonEmptyArray(tuple);
+
+    expect(casted).toBe(tuple);
+
+    expectType<typeof casted, readonly [1, 2, 3]>('<=');
+
+    expectType<typeof casted, NonEmptyArray<1 | 2 | 3>>('<=');
+  });
 });

package/src/number/branded-types/int16.mts

@@ -14,8 +14,8 @@ const {
   abs,
   add,
   castType,
-  clamp,
   div,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -74,12 +74,14 @@ export const Int16 = {
   is,
 
   /**
-   * The smallest value representable as `Int16`.
+   * The smallest value representable as `Int16` (the lower saturation target of
+   * `fromNumber`).
    */
   MIN_VALUE,
 
   /**
-   * The largest value representable as `Int16`.
+   * The largest value representable as `Int16` (the upper saturation target of
+   * `fromNumber`).
    */
   MAX_VALUE,
 
@@ -110,13 +112,16 @@ export const Int16 = {
   max: max_,
 
   /**
-   * Clamps a `number` into the `Int16` range, rounding to the nearest integer
-   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+   * Converts an arbitrary `number` into an `Int16`, rounding to the nearest
+   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
    *
-   * @param value - The value to clamp
-   * @returns The clamped value as an `Int16`
+   * Unlike `asInt16`, this is total: out-of-range inputs are clamped to the
+   * nearest representable `Int16` instead of throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as an `Int16`
    */
-  clamp,
+  fromNumber,
 
   /**
    * Generates a random `Int16` within the given range.

package/src/number/branded-types/int32.mts

@@ -14,8 +14,8 @@ const {
   abs,
   add,
   castType,
-  clamp,
   div,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -74,12 +74,14 @@ export const Int32 = {
   is,
 
   /**
-   * The smallest value representable as `Int32`.
+   * The smallest value representable as `Int32` (the lower saturation target of
+   * `fromNumber`).
    */
   MIN_VALUE,
 
   /**
-   * The largest value representable as `Int32`.
+   * The largest value representable as `Int32` (the upper saturation target of
+   * `fromNumber`).
    */
   MAX_VALUE,
 
@@ -110,13 +112,16 @@ export const Int32 = {
   max: max_,
 
   /**
-   * Clamps a `number` into the `Int32` range, rounding to the nearest integer
-   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+   * Converts an arbitrary `number` into an `Int32`, rounding to the nearest
+   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
    *
-   * @param value - The value to clamp
-   * @returns The clamped value as an `Int32`
+   * Unlike `asInt32`, this is total: out-of-range inputs are clamped to the
+   * nearest representable `Int32` instead of throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as an `Int32`
    */
-  clamp,
+  fromNumber,
 
   /**
    * Generates a random `Int32` within the given range.

package/src/number/branded-types/negative-finite-number.mts

@@ -12,7 +12,7 @@ const {
   MAX_VALUE,
   add,
   castType,
-  clamp,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -31,7 +31,7 @@ const {
 } as const);
 
 const abs = (x: ElementType): PositiveFiniteNumber =>
-  PositiveFiniteNumber.clamp(Math.abs(x));
+  PositiveFiniteNumber.fromNumber(Math.abs(x));
 
 const floor = (
   x: ElementType,
@@ -101,7 +101,10 @@ export const NegativeFiniteNumber = {
   is,
 
   /**
-   * The largest value representable as `NegativeFiniteNumber`.
+   * The largest value representable as `NegativeFiniteNumber` (the upper
+   * saturation target of `fromNumber`). The domain is open at `0` (excluded),
+   * so this is `-Number.MIN_VALUE` — the negative double closest to `0` —
+   * rather than `0`.
    */
   MAX_VALUE,
 
@@ -132,13 +135,17 @@ export const NegativeFiniteNumber = {
   max: max_,
 
   /**
-   * Clamps a `number` into the `NegativeFiniteNumber` range `[MIN_VALUE,
-   * MAX_VALUE]`.
+   * Converts an arbitrary `number` into a `NegativeFiniteNumber`, saturating it
+   * into the range `[MIN_VALUE, MAX_VALUE]`.
    *
-   * @param value - The value to clamp
-   * @returns The clamped value as a `NegativeFiniteNumber`
+   * Unlike `asNegativeFiniteNumber`, this is total: out-of-range inputs are
+   * clamped to the nearest representable `NegativeFiniteNumber` instead of
+   * throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as a `NegativeFiniteNumber`
    */
-  clamp,
+  fromNumber,
 
   /**
    * Returns the greatest integer less than or equal to a negative finite

package/src/number/branded-types/negative-finite-number.test.mts

@@ -93,13 +93,13 @@ describe('NegativeFiniteNumber test', () => {
     });
   });
 
-  describe('NegativeFiniteNumber.clamp', () => {
+  describe('NegativeFiniteNumber.fromNumber', () => {
     test('clamps non-negative values into range', () => {
-      expect(NegativeFiniteNumber.clamp(-5.5)).toBeCloseTo(-5.5, 5);
+      expect(NegativeFiniteNumber.fromNumber(-5.5)).toBeCloseTo(-5.5, 5);
 
-      expect(NegativeFiniteNumber.clamp(0)).toBeLessThan(0);
+      expect(NegativeFiniteNumber.fromNumber(0)).toBeLessThan(0);
 
-      expect(NegativeFiniteNumber.clamp(5)).toBeLessThan(0);
+      expect(NegativeFiniteNumber.fromNumber(5)).toBeLessThan(0);
     });
   });