ts-data-forge 1.0.0

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

@@ -0,0 +1,354 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = FiniteNumber;
+
+const typeNameInMessage = 'a finite number';
+
+const {
+  abs,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  undefined,
+  undefined
+>({
+  MIN_VALUE: undefined,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+const floor = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.floor(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+const ceil = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.ceil(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+const round = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.round(x) as TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>;
+
+expectType<TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>, Int>('=');
+
+/**
+ * Type guard that checks if a value is a finite number.
+ *
+ * Returns `true` if the value is a finite number (not NaN, Infinity, or -Infinity).
+ * This is stricter than the standard number type, which includes these special values.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is finite, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isFiniteNumber(42);          // true
+ * isFiniteNumber(3.14);        // true
+ * isFiniteNumber(-0);          // true
+ * isFiniteNumber(Infinity);    // false
+ * isFiniteNumber(-Infinity);   // false
+ * isFiniteNumber(NaN);         // false
+ * isFiniteNumber(1/0);         // false (Infinity)
+ * ```
+ */
+export const isFiniteNumber = is;
+
+/**
+ * Casts a number to a FiniteNumber branded type.
+ *
+ * This function validates that the input is finite (not NaN, Infinity, or -Infinity)
+ * and returns it with the FiniteNumber brand. This ensures type safety for operations
+ * that require finite numeric values.
+ *
+ * @param value - The value to cast
+ * @returns The value as a FiniteNumber branded type
+ * @throws {TypeError} If the value is NaN, Infinity, or -Infinity
+ *
+ * @example
+ * ```typescript
+ * const x = asFiniteNumber(5.5);   // FiniteNumber
+ * const y = asFiniteNumber(-10);   // FiniteNumber
+ * const z = asFiniteNumber(0);     // FiniteNumber
+ *
+ * // These throw TypeError:
+ * // asFiniteNumber(Infinity);     // Not finite
+ * // asFiniteNumber(-Infinity);    // Not finite
+ * // asFiniteNumber(NaN);          // Not a number
+ * // asFiniteNumber(Math.sqrt(-1)); // Results in NaN
+ * ```
+ */
+export const asFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe operations for FiniteNumber branded types.
+ *
+ * The FiniteNumber type represents any finite numeric value, excluding the
+ * special values NaN, Infinity, and -Infinity. All operations are guaranteed
+ * to maintain the finite constraint when given finite inputs.
+ *
+ * This type is essential for:
+ * - Mathematical operations that require real numbers
+ * - Preventing NaN/Infinity propagation in calculations
+ * - Ensuring numeric stability in algorithms
+ *
+ * @example
+ * ```typescript
+ * // Type validation
+ * FiniteNumber.is(3.14);       // true
+ * FiniteNumber.is(Infinity);   // false
+ * FiniteNumber.is(0/0);        // false (NaN)
+ *
+ * // Arithmetic with guaranteed finite results
+ * const a = asFiniteNumber(10.5);
+ * const b = asFiniteNumber(3.2);
+ *
+ * const sum = FiniteNumber.add(a, b);      // FiniteNumber (13.7)
+ * const diff = FiniteNumber.sub(a, b);     // FiniteNumber (7.3)
+ * const product = FiniteNumber.mul(a, b);  // FiniteNumber (33.6)
+ * const quotient = FiniteNumber.div(a, b); // FiniteNumber (3.28125)
+ * const power = FiniteNumber.pow(a, asFiniteNumber(2)); // FiniteNumber (110.25)
+ *
+ * // Rounding to integers
+ * const value = asFiniteNumber(5.7);
+ * const floored = FiniteNumber.floor(value);  // Int (5)
+ * const ceiled = FiniteNumber.ceil(value);    // Int (6)
+ * const rounded = FiniteNumber.round(value);  // Int (6)
+ *
+ * // Utility operations
+ * const absolute = FiniteNumber.abs(asFiniteNumber(-42.5)); // FiniteNumber (42.5)
+ * const minimum = FiniteNumber.min(a, b, asFiniteNumber(5)); // FiniteNumber (3.2)
+ * const maximum = FiniteNumber.max(a, b, asFiniteNumber(5)); // FiniteNumber (10.5)
+ *
+ * // Random generation
+ * const rand = FiniteNumber.random(asFiniteNumber(0), asFiniteNumber(1)); // Random in [0, 1]
+ * ```
+ */
+export const FiniteNumber = {
+  /**
+   * Type guard that checks if a value is a finite number.
+   *
+   * @param value - The value to check
+   * @returns `true` if the value is finite, `false` otherwise
+   *
+   * @see {@link isFiniteNumber} for usage examples
+   */
+  is,
+
+  /**
+   * Returns the absolute value of a finite number.
+   * @param x - The finite number to get the absolute value of
+   * @returns The absolute value as a FiniteNumber
+   * @example
+   * ```typescript
+   * FiniteNumber.abs(asFiniteNumber(-5.5)); // FiniteNumber (5.5)
+   * FiniteNumber.abs(asFiniteNumber(3.2)); // FiniteNumber (3.2)
+   * ```
+   */
+  abs,
+
+  /**
+   * Returns the minimum value from a list of finite numbers.
+   *
+   * @param values - The finite numbers to compare (at least one required)
+   * @returns The smallest value as a FiniteNumber
+   *
+   * @example
+   * ```typescript
+   * const a = asFiniteNumber(5.5);
+   * const b = asFiniteNumber(3.2);
+   * const c = asFiniteNumber(7.8);
+   *
+   * FiniteNumber.min(a, b);      // FiniteNumber (3.2)
+   * FiniteNumber.min(a, b, c);   // FiniteNumber (3.2)
+   * ```
+   */
+  min: min_,
+
+  /**
+   * Returns the maximum value from a list of finite numbers.
+   *
+   * @param values - The finite numbers to compare (at least one required)
+   * @returns The largest value as a FiniteNumber
+   *
+   * @example
+   * ```typescript
+   * const a = asFiniteNumber(5.5);
+   * const b = asFiniteNumber(3.2);
+   * const c = asFiniteNumber(7.8);
+   *
+   * FiniteNumber.max(a, b);      // FiniteNumber (7.8)
+   * FiniteNumber.max(a, b, c);   // FiniteNumber (7.8)
+   * ```
+   */
+  max: max_,
+
+  /**
+   * Returns the largest integer less than or equal to the given finite number.
+   * @param x - The finite number to floor
+   * @returns The floor value as an Int
+   * @example
+   * ```typescript
+   * FiniteNumber.floor(asFiniteNumber(5.8)); // Int (5)
+   * FiniteNumber.floor(asFiniteNumber(-5.2)); // Int (-6)
+   * ```
+   */
+  floor,
+
+  /**
+   * Returns the smallest integer greater than or equal to the given finite number.
+   * @param x - The finite number to ceil
+   * @returns The ceiling value as an Int
+   * @example
+   * ```typescript
+   * FiniteNumber.ceil(asFiniteNumber(5.2)); // Int (6)
+   * FiniteNumber.ceil(asFiniteNumber(-5.8)); // Int (-5)
+   * ```
+   */
+  ceil,
+
+  /**
+   * Rounds a finite number to the nearest integer.
+   * @param x - The finite number to round
+   * @returns The rounded value as an Int
+   * @example
+   * ```typescript
+   * FiniteNumber.round(asFiniteNumber(5.4)); // Int (5)
+   * FiniteNumber.round(asFiniteNumber(5.6)); // Int (6)
+   * FiniteNumber.round(asFiniteNumber(5.5)); // Int (6)
+   * ```
+   */
+  round,
+
+  /**
+   * Generates a random finite number within the specified range.
+   *
+   * The generated value is uniformly distributed in the range [min, max].
+   * Both bounds are inclusive.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random FiniteNumber in the range [min, max]
+   *
+   * @example
+   * ```typescript
+   * // Random percentage (0-100)
+   * const pct = FiniteNumber.random(
+   *   asFiniteNumber(0),
+   *   asFiniteNumber(100)
+   * );
+   *
+   * // Random coordinate (-1 to 1)
+   * const coord = FiniteNumber.random(
+   *   asFiniteNumber(-1),
+   *   asFiniteNumber(1)
+   * );
+   * ```
+   */
+  random,
+
+  /**
+   * Raises a finite number to a power.
+   * @param a - The base finite number
+   * @param b - The exponent finite number
+   * @returns `a ** b` as a FiniteNumber
+   * @example
+   * ```typescript
+   * FiniteNumber.pow(asFiniteNumber(2.5), asFiniteNumber(3)); // FiniteNumber (15.625)
+   * ```
+   */
+  pow,
+
+  /**
+   * Adds two finite numbers.
+   * @param a - First finite number
+   * @param b - Second finite number
+   * @returns `a + b` as a FiniteNumber
+   * @example
+   * ```typescript
+   * FiniteNumber.add(asFiniteNumber(5.5), asFiniteNumber(3.2)); // FiniteNumber (8.7)
+   * ```
+   */
+  add,
+
+  /**
+   * Subtracts two finite numbers.
+   * @param a - First finite number
+   * @param b - Second finite number
+   * @returns `a - b` as a FiniteNumber
+   * @example
+   * ```typescript
+   * FiniteNumber.sub(asFiniteNumber(8.7), asFiniteNumber(3.2)); // FiniteNumber (5.5)
+   * ```
+   */
+  sub,
+
+  /**
+   * Multiplies two finite numbers.
+   * @param a - First finite number
+   * @param b - Second finite number
+   * @returns `a * b` as a FiniteNumber
+   * @example
+   * ```typescript
+   * FiniteNumber.mul(asFiniteNumber(5.5), asFiniteNumber(2)); // FiniteNumber (11)
+   * ```
+   */
+  mul,
+
+  /**
+   * Divides two finite numbers.
+   *
+   * The divisor must be non-zero (enforced by type constraints).
+   * The result is guaranteed to be finite when both inputs are finite
+   * and the divisor is non-zero.
+   *
+   * @param a - The dividend
+   * @param b - The divisor (must be non-zero)
+   * @returns The quotient `a / b` as a FiniteNumber
+   *
+   * @example
+   * ```typescript
+   * const a = asFiniteNumber(11);
+   * const b = asFiniteNumber(2);
+   *
+   * FiniteNumber.div(a, b); // FiniteNumber (5.5)
+   *
+   * // With non-zero type guard
+   * const divisor = asFiniteNumber(userInput);
+   * if (Num.isNonZero(divisor)) {
+   *   const result = FiniteNumber.div(a, divisor);
+   * }
+   * ```
+   */
+  div,
+} as const;
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.ToNonNegative<ElementType>,
+  NonNegativeFiniteNumber
+>('=');
+
+expectType<
+  keyof typeof FiniteNumber,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+>('=');
+
+expectType<
+  typeof FiniteNumber,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, never>
+>('<=');

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

@@ -0,0 +1,135 @@
+import { expectType } from '../../expect-type.mjs';
+import { asFiniteNumber, FiniteNumber } from './finite-number.mjs';
+import { asNonZeroFiniteNumber } from './non-zero-finite-number.mjs';
+
+describe('FiniteNumber', () => {
+  describe('asFiniteNumber', () => {
+    test('accepts valid finite numbers', () => {
+      expect(() => asFiniteNumber(0)).not.toThrow();
+      expect(() => asFiniteNumber(1)).not.toThrow();
+      expect(() => asFiniteNumber(-1)).not.toThrow();
+      expect(() => asFiniteNumber(3.14)).not.toThrow();
+      expect(() => asFiniteNumber(-2.5)).not.toThrow();
+      expect(() => asFiniteNumber(Number.MAX_VALUE)).not.toThrow();
+      expect(() => asFiniteNumber(-Number.MAX_VALUE)).not.toThrow();
+    });
+
+    test('rejects non-finite numbers', () => {
+      expect(() => asFiniteNumber(Number.NaN)).toThrow(TypeError);
+      expect(() => asFiniteNumber(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asFiniteNumber(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asFiniteNumber(5.5)).toBe(5.5);
+      expect(asFiniteNumber(-10)).toBe(-10);
+      expect(asFiniteNumber(0)).toBe(0);
+    });
+
+    test.each([
+      { name: 'Number.NaN', value: Number.NaN },
+      { name: 'Number.POSITIVE_INFINITY', value: Number.POSITIVE_INFINITY },
+      { name: 'Number.NEGATIVE_INFINITY', value: Number.NEGATIVE_INFINITY },
+    ] as const)(
+      `asFiniteNumber($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asFiniteNumber(value)).toThrow(
+          new TypeError(`Expected a finite number, got: ${value}`),
+        );
+      },
+    );
+  });
+
+  describe('FiniteNumber.is', () => {
+    test('correctly identifies finite numbers', () => {
+      expect(FiniteNumber.is(0)).toBe(true);
+      expect(FiniteNumber.is(1)).toBe(true);
+      expect(FiniteNumber.is(-1)).toBe(true);
+      expect(FiniteNumber.is(3.14)).toBe(true);
+      expect(FiniteNumber.is(-2.5)).toBe(true);
+      expect(FiniteNumber.is(Number.MAX_VALUE)).toBe(true);
+      expect(FiniteNumber.is(-Number.MAX_VALUE)).toBe(true);
+    });
+
+    test('correctly identifies non-finite numbers', () => {
+      expect(FiniteNumber.is(Number.NaN)).toBe(false);
+      expect(FiniteNumber.is(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(FiniteNumber.is(Number.NEGATIVE_INFINITY)).toBe(false);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asFiniteNumber(5.5);
+    const b = asFiniteNumber(2.5);
+    const c = asFiniteNumber(-3.5);
+
+    test('abs', () => {
+      expect(FiniteNumber.abs(a)).toBe(5.5);
+      expect(FiniteNumber.abs(c)).toBe(3.5);
+      expect(FiniteNumber.abs(asFiniteNumber(0))).toBe(0);
+    });
+
+    test('min and max', () => {
+      expect(FiniteNumber.min(a, b)).toBe(2.5);
+      expect(FiniteNumber.max(a, b)).toBe(5.5);
+      expect(FiniteNumber.min(a, c)).toBe(-3.5);
+      expect(FiniteNumber.max(a, c)).toBe(5.5);
+    });
+
+    test('floor, ceil, round', () => {
+      expect(FiniteNumber.floor(a)).toBe(5);
+      expect(FiniteNumber.ceil(a)).toBe(6);
+      expect(FiniteNumber.round(a)).toBe(6);
+      expect(FiniteNumber.floor(c)).toBe(-4);
+      expect(FiniteNumber.ceil(c)).toBe(-3);
+      expect(FiniteNumber.round(c)).toBe(-3);
+    });
+
+    test('add', () => {
+      expect(FiniteNumber.add(a, b)).toBe(8);
+      expect(FiniteNumber.add(a, c)).toBe(2);
+    });
+
+    test('sub', () => {
+      expect(FiniteNumber.sub(a, b)).toBe(3);
+      expect(FiniteNumber.sub(a, c)).toBe(9);
+    });
+
+    test('mul', () => {
+      expect(FiniteNumber.mul(a, b)).toBe(13.75);
+      expect(FiniteNumber.mul(a, c)).toBe(-19.25);
+    });
+
+    test('div', () => {
+      expect(FiniteNumber.div(a, asNonZeroFiniteNumber(2.5))).toBe(2.2);
+      expect(FiniteNumber.div(a, asNonZeroFiniteNumber(2))).toBe(2.75);
+    });
+
+    test('pow', () => {
+      expect(FiniteNumber.pow(asFiniteNumber(2), asFiniteNumber(3))).toBe(8);
+      expect(FiniteNumber.pow(asFiniteNumber(3), asFiniteNumber(2))).toBe(9);
+    });
+  });
+
+  describe('random', () => {
+    test('generates numbers within specified range', () => {
+      const min = asFiniteNumber(-5.5);
+      const max = asFiniteNumber(10.3);
+
+      for (let i = 0; i < 10; i++) {
+        const result = FiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(FiniteNumber.is(result)).toBe(true);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<FiniteNumber, number>('<=');
+
+      expectTypeOf(asFiniteNumber(5.5)).toExtend<FiniteNumber>();
+    });
+  });
+});

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

@@ -0,0 +1,26 @@
+export * from './finite-number.mjs';
+export * from './int.mjs';
+export * from './int16.mjs';
+export * from './int32.mjs';
+export * from './non-negative-finite-number.mjs';
+export * from './non-negative-int16.mjs';
+export * from './non-negative-int32.mjs';
+export * from './non-zero-finite-number.mjs';
+export * from './non-zero-int.mjs';
+export * from './non-zero-int16.mjs';
+export * from './non-zero-int32.mjs';
+export * from './non-zero-safe-int.mjs';
+export * from './non-zero-uint16.mjs';
+export * from './non-zero-uint32.mjs';
+export * from './positive-finite-number.mjs';
+export * from './positive-int.mjs';
+export * from './positive-int16.mjs';
+export * from './positive-int32.mjs';
+export * from './positive-safe-int.mjs';
+export * from './positive-uint16.mjs';
+export * from './positive-uint32.mjs';
+export * from './safe-int.mjs';
+export * from './safe-uint.mjs';
+export * from './uint.mjs';
+export * from './uint16.mjs';
+export * from './uint32.mjs';