ts-data-forge 1.0.0

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

@@ -0,0 +1,223 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = NonNegativeFiniteNumber;
+
+const typeNameInMessage = 'a non-negative finite number';
+
+const {
+  MIN_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  0,
+  undefined
+>({
+  MIN_VALUE: 0,
+  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>, Uint>(
+  '=',
+);
+
+/**
+ * Checks if a number is a NonNegativeFiniteNumber (a finite number >= 0).
+ * @param value The value to check.
+ * @returns `true` if the value is a NonNegativeFiniteNumber, `false` otherwise.
+ */
+export const isNonNegativeFiniteNumber = is;
+
+/**
+ * Casts a number to a NonNegativeFiniteNumber type.
+ * @param value The value to cast.
+ * @returns The value as a NonNegativeFiniteNumber type.
+ * @throws {TypeError} If the value is not a non-negative finite number.
+ * @example
+ * ```typescript
+ * const x = asNonNegativeFiniteNumber(5.5); // NonNegativeFiniteNumber
+ * const y = asNonNegativeFiniteNumber(0); // NonNegativeFiniteNumber
+ * // asNonNegativeFiniteNumber(-1); // throws TypeError
+ * // asNonNegativeFiniteNumber(Infinity); // throws TypeError
+ * ```
+ */
+export const asNonNegativeFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for non-negative finite numbers.
+ *
+ * All operations maintain the non-negative constraint by clamping negative results to 0,
+ * while ensuring results remain finite (excluding NaN and Infinity). This type is useful
+ * for representing measurements, distances, weights, and other inherently non-negative values.
+ *
+ * @example
+ * ```typescript
+ * const distance = asNonNegativeFiniteNumber(5.5);
+ * const speed = asNonNegativeFiniteNumber(2.2);
+ *
+ * // Arithmetic operations with non-negative clamping
+ * const total = NonNegativeFiniteNumber.add(distance, speed);        // NonNegativeFiniteNumber (7.7)
+ * const diff = NonNegativeFiniteNumber.sub(speed, distance);        // NonNegativeFiniteNumber (0 - clamped)
+ * const area = NonNegativeFiniteNumber.mul(distance, speed);        // NonNegativeFiniteNumber (12.1)
+ * const ratio = NonNegativeFiniteNumber.div(distance, speed);       // NonNegativeFiniteNumber (2.5)
+ *
+ * // Range operations
+ * const clamped = NonNegativeFiniteNumber.clamp(-10.5);             // NonNegativeFiniteNumber (0)
+ * const minimum = NonNegativeFiniteNumber.min(distance, speed);     // NonNegativeFiniteNumber (2.2)
+ * const maximum = NonNegativeFiniteNumber.max(distance, speed);     // NonNegativeFiniteNumber (5.5)
+ *
+ * // Rounding operations (return Uint)
+ * const pixels = NonNegativeFiniteNumber.round(distance);           // Uint (6)
+ * const floorValue = NonNegativeFiniteNumber.floor(distance);       // Uint (5)
+ * const ceilValue = NonNegativeFiniteNumber.ceil(distance);         // Uint (6)
+ * ```
+ */
+export const NonNegativeFiniteNumber = {
+  /**
+   * Type guard to check if a value is a NonNegativeFiniteNumber.
+   * @param value The value to check.
+   * @returns `true` if the value is a non-negative finite number, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a non-negative finite number.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * Returns the smaller of two NonNegativeFiniteNumber values.
+   * @param a The first NonNegativeFiniteNumber.
+   * @param b The second NonNegativeFiniteNumber.
+   * @returns The minimum value as a NonNegativeFiniteNumber.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NonNegativeFiniteNumber values.
+   * @param a The first NonNegativeFiniteNumber.
+   * @param b The second NonNegativeFiniteNumber.
+   * @returns The maximum value as a NonNegativeFiniteNumber.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the non-negative finite range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [0, +∞) as a NonNegativeFiniteNumber.
+   */
+  clamp,
+
+  /**
+   * Rounds down a NonNegativeFiniteNumber to the nearest integer.
+   * @param x The NonNegativeFiniteNumber to round down.
+   * @returns The floor value as a Uint.
+   */
+  floor,
+
+  /**
+   * Rounds up a NonNegativeFiniteNumber to the nearest integer.
+   * @param x The NonNegativeFiniteNumber to round up.
+   * @returns The ceiling value as a Uint.
+   */
+  ceil,
+
+  /**
+   * Rounds a NonNegativeFiniteNumber to the nearest integer.
+   * @param x The NonNegativeFiniteNumber to round.
+   * @returns The rounded value as a Uint.
+   */
+  round,
+
+  /**
+   * Generates a random NonNegativeFiniteNumber value.
+   * @returns A random non-negative finite number.
+   */
+  random,
+
+  /**
+   * Raises a NonNegativeFiniteNumber to the power of another NonNegativeFiniteNumber.
+   * @param a The base NonNegativeFiniteNumber.
+   * @param b The exponent NonNegativeFiniteNumber.
+   * @returns `a ** b` clamped to [0, +∞) as a NonNegativeFiniteNumber.
+   */
+  pow,
+
+  /**
+   * Adds two NonNegativeFiniteNumber values.
+   * @param a The first NonNegativeFiniteNumber.
+   * @param b The second NonNegativeFiniteNumber.
+   * @returns `a + b` clamped to [0, +∞) as a NonNegativeFiniteNumber.
+   */
+  add,
+
+  /**
+   * Subtracts one NonNegativeFiniteNumber from another.
+   * @param a The minuend NonNegativeFiniteNumber.
+   * @param b The subtrahend NonNegativeFiniteNumber.
+   * @returns `a - b` clamped to [0, +∞) as a NonNegativeFiniteNumber (minimum 0).
+   */
+  sub,
+
+  /**
+   * Multiplies two NonNegativeFiniteNumber values.
+   * @param a The first NonNegativeFiniteNumber.
+   * @param b The second NonNegativeFiniteNumber.
+   * @returns `a * b` clamped to [0, +∞) as a NonNegativeFiniteNumber.
+   */
+  mul,
+
+  /**
+   * Divides one NonNegativeFiniteNumber by another.
+   * @param a The dividend NonNegativeFiniteNumber.
+   * @param b The divisor NonNegativeFiniteNumber.
+   * @returns `a / b` clamped to [0, +∞) as a NonNegativeFiniteNumber.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof NonNegativeFiniteNumber,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'non-negative'
+  >
+>('=');
+
+expectType<
+  typeof NonNegativeFiniteNumber,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'non-negative'
+  >
+>('<=');

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

@@ -0,0 +1,188 @@
+import { expectType } from '../../expect-type.mjs';
+import {
+  asNonNegativeFiniteNumber,
+  isNonNegativeFiniteNumber,
+  NonNegativeFiniteNumber,
+} from './non-negative-finite-number.mjs';
+
+describe('NonNegativeFiniteNumber', () => {
+  describe('asNonNegativeFiniteNumber', () => {
+    test('accepts valid non-negative finite numbers', () => {
+      expect(() => asNonNegativeFiniteNumber(0)).not.toThrow();
+      expect(() => asNonNegativeFiniteNumber(1)).not.toThrow();
+      expect(() => asNonNegativeFiniteNumber(3.14)).not.toThrow();
+      expect(() => asNonNegativeFiniteNumber(0.5)).not.toThrow();
+      expect(() => asNonNegativeFiniteNumber(Number.MAX_VALUE)).not.toThrow();
+    });
+
+    test('rejects negative numbers', () => {
+      expect(() => asNonNegativeFiniteNumber(-1)).toThrow(TypeError);
+      expect(() => asNonNegativeFiniteNumber(-0.1)).toThrow(TypeError);
+      expect(() => asNonNegativeFiniteNumber(-Number.MAX_VALUE)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('rejects non-finite numbers', () => {
+      expect(() => asNonNegativeFiniteNumber(Number.NaN)).toThrow(TypeError);
+      expect(() => asNonNegativeFiniteNumber(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asNonNegativeFiniteNumber(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNonNegativeFiniteNumber(5.5)).toBe(5.5);
+      expect(asNonNegativeFiniteNumber(0)).toBe(0);
+      expect(asNonNegativeFiniteNumber(10)).toBe(10);
+    });
+
+    test.each([
+      { name: 'Number.NaN', value: Number.NaN },
+      { name: 'Number.POSITIVE_INFINITY', value: Number.POSITIVE_INFINITY },
+      { name: 'Number.NEGATIVE_INFINITY', value: Number.NEGATIVE_INFINITY },
+      { name: '-1.2', value: -1.2 },
+    ] as const)(
+      `asNonNegativeFiniteNumber($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asNonNegativeFiniteNumber(value)).toThrow(
+          new TypeError(`Expected a non-negative finite number, got: ${value}`),
+        );
+      },
+    );
+  });
+
+  describe('isNonNegativeFiniteNumber', () => {
+    test('correctly identifies non-negative finite numbers', () => {
+      expect(isNonNegativeFiniteNumber(0)).toBe(true);
+      expect(isNonNegativeFiniteNumber(1)).toBe(true);
+      expect(isNonNegativeFiniteNumber(3.14)).toBe(true);
+      expect(isNonNegativeFiniteNumber(0.5)).toBe(true);
+      expect(isNonNegativeFiniteNumber(Number.MAX_VALUE)).toBe(true);
+    });
+
+    test('correctly identifies negative numbers', () => {
+      expect(isNonNegativeFiniteNumber(-1)).toBe(false);
+      expect(isNonNegativeFiniteNumber(-0.1)).toBe(false);
+      expect(isNonNegativeFiniteNumber(-Number.MAX_VALUE)).toBe(false);
+    });
+
+    test('correctly identifies non-finite numbers', () => {
+      expect(isNonNegativeFiniteNumber(Number.NaN)).toBe(false);
+      expect(isNonNegativeFiniteNumber(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isNonNegativeFiniteNumber(Number.NEGATIVE_INFINITY)).toBe(false);
+    });
+  });
+
+  describe('NonNegativeFiniteNumber.is', () => {
+    test('same as isNonNegativeFiniteNumber function', () => {
+      expect(NonNegativeFiniteNumber.is(5)).toBe(isNonNegativeFiniteNumber(5));
+      expect(NonNegativeFiniteNumber.is(-1)).toBe(
+        isNonNegativeFiniteNumber(-1),
+      );
+      expect(NonNegativeFiniteNumber.is(0)).toBe(isNonNegativeFiniteNumber(0));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE', () => {
+      expect(NonNegativeFiniteNumber.MIN_VALUE).toBe(0);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asNonNegativeFiniteNumber(5.5);
+    const b = asNonNegativeFiniteNumber(2.5);
+    const c = asNonNegativeFiniteNumber(0);
+
+    test('min and max', () => {
+      expect(NonNegativeFiniteNumber.min(a, b)).toBe(2.5);
+      expect(NonNegativeFiniteNumber.max(a, b)).toBe(5.5);
+      expect(NonNegativeFiniteNumber.min(a, c)).toBe(0);
+      expect(NonNegativeFiniteNumber.max(a, c)).toBe(5.5);
+    });
+
+    test('floor, ceil, round', () => {
+      expect(NonNegativeFiniteNumber.floor(a)).toBe(5);
+      expect(NonNegativeFiniteNumber.ceil(a)).toBe(6);
+      expect(NonNegativeFiniteNumber.round(a)).toBe(6);
+      expect(NonNegativeFiniteNumber.floor(b)).toBe(2);
+      expect(NonNegativeFiniteNumber.ceil(b)).toBe(3);
+      expect(NonNegativeFiniteNumber.round(b)).toBe(3);
+    });
+
+    test('add (never goes below 0)', () => {
+      expect(NonNegativeFiniteNumber.add(a, b)).toBe(8);
+      expect(NonNegativeFiniteNumber.add(a, c)).toBe(5.5);
+    });
+
+    test('sub (never goes below 0)', () => {
+      expect(NonNegativeFiniteNumber.sub(a, b)).toBe(3);
+      expect(NonNegativeFiniteNumber.sub(b, a)).toBe(0); // clamped to 0
+    });
+
+    test('mul (never goes below 0)', () => {
+      expect(NonNegativeFiniteNumber.mul(a, b)).toBe(13.75);
+      expect(NonNegativeFiniteNumber.mul(a, c)).toBe(0);
+    });
+
+    test('div method exists', () => {
+      // Test that the div function exists and is of the right type
+      expect(typeof NonNegativeFiniteNumber.div).toBe('function');
+      // Note: Cannot test division without type assertions due to strict type requirements
+    });
+
+    test('pow (never goes below 0)', () => {
+      expect(
+        NonNegativeFiniteNumber.pow(
+          asNonNegativeFiniteNumber(2),
+          asNonNegativeFiniteNumber(3),
+        ),
+      ).toBe(8);
+      expect(
+        NonNegativeFiniteNumber.pow(
+          asNonNegativeFiniteNumber(3),
+          asNonNegativeFiniteNumber(2),
+        ),
+      ).toBe(9);
+    });
+  });
+
+  describe('random', () => {
+    test('generates non-negative numbers within specified range', () => {
+      const min = asNonNegativeFiniteNumber(1.5);
+      const max = asNonNegativeFiniteNumber(10.3);
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonNegativeFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(NonNegativeFiniteNumber.is(result)).toBe(true);
+        expect(result).toBeGreaterThanOrEqual(0);
+      }
+    });
+
+    test('generates numbers starting from 0', () => {
+      const min = asNonNegativeFiniteNumber(0);
+      const max = asNonNegativeFiniteNumber(5);
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonNegativeFiniteNumber.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(0);
+        expect(result).toBeLessThanOrEqual(5);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<NonNegativeFiniteNumber, number>('<=');
+
+      expectTypeOf(
+        asNonNegativeFiniteNumber(5.5),
+      ).toExtend<NonNegativeFiniteNumber>();
+    });
+  });
+});

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

@@ -0,0 +1,187 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = NonNegativeInt16;
+
+const typeNameInMessage = 'a non-negative integer in [0, 2^15)';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  0,
+  number
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: 0,
+  MAX_VALUE: 2 ** 15 - 1,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a NonNegativeInt16 (16-bit non-negative signed integer in the range [0, 2^15)).
+ * @param value The value to check.
+ * @returns `true` if the value is a NonNegativeInt16, `false` otherwise.
+ */
+export const isNonNegativeInt16 = is;
+
+/**
+ * Casts a number to a NonNegativeInt16 type.
+ * @param value The value to cast.
+ * @returns The value as a NonNegativeInt16 type.
+ * @throws {TypeError} If the value is not a non-negative integer in [0, 2^15).
+ * @example
+ * ```typescript
+ * const x = asNonNegativeInt16(1000); // NonNegativeInt16
+ * const y = asNonNegativeInt16(0); // NonNegativeInt16
+ * // asNonNegativeInt16(-1); // throws TypeError
+ * // asNonNegativeInt16(32768); // throws TypeError
+ * ```
+ */
+export const asNonNegativeInt16 = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for 16-bit non-negative integers.
+ *
+ * All operations automatically clamp results to the valid NonNegativeInt16 range [0, 32767].
+ * This ensures that all arithmetic maintains the 16-bit non-negative integer constraint,
+ * with negative results clamped to 0 and overflow results clamped to MAX_VALUE.
+ *
+ * @example
+ * ```typescript
+ * const a = asNonNegativeInt16(30000);
+ * const b = asNonNegativeInt16(5000);
+ *
+ * // Arithmetic operations with automatic clamping
+ * const sum = NonNegativeInt16.add(a, b);       // NonNegativeInt16 (32767 - clamped to MAX_VALUE)
+ * const diff = NonNegativeInt16.sub(a, b);      // NonNegativeInt16 (25000)
+ * const reverseDiff = NonNegativeInt16.sub(b, a); // NonNegativeInt16 (0 - clamped to MIN_VALUE)
+ * const product = NonNegativeInt16.mul(a, b);   // NonNegativeInt16 (32767 - clamped due to overflow)
+ *
+ * // Range operations
+ * const clamped = NonNegativeInt16.clamp(-100);     // NonNegativeInt16 (0)
+ * const minimum = NonNegativeInt16.min(a, b);       // NonNegativeInt16 (5000)
+ * const maximum = NonNegativeInt16.max(a, b);       // NonNegativeInt16 (30000)
+ *
+ * // Utility operations
+ * const random = NonNegativeInt16.random();         // NonNegativeInt16 (random value in [0, 32767])
+ * const power = NonNegativeInt16.pow(asNonNegativeInt16(2), asNonNegativeInt16(10)); // NonNegativeInt16 (1024)
+ * ```
+ */
+export const NonNegativeInt16 = {
+  /**
+   * Type guard to check if a value is a NonNegativeInt16.
+   * @param value The value to check.
+   * @returns `true` if the value is a 16-bit non-negative integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a 16-bit non-negative integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for a 16-bit non-negative integer.
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the smaller of two NonNegativeInt16 values.
+   * @param a The first NonNegativeInt16.
+   * @param b The second NonNegativeInt16.
+   * @returns The minimum value as a NonNegativeInt16.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two NonNegativeInt16 values.
+   * @param a The first NonNegativeInt16.
+   * @param b The second NonNegativeInt16.
+   * @returns The maximum value as a NonNegativeInt16.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the NonNegativeInt16 range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [0, 32767] as a NonNegativeInt16.
+   */
+  clamp,
+
+  /**
+   * Generates a random NonNegativeInt16 value within the valid range.
+   * @returns A random NonNegativeInt16 between 0 and 32767.
+   */
+  random,
+
+  /**
+   * Raises a NonNegativeInt16 to the power of another NonNegativeInt16.
+   * @param a The base NonNegativeInt16.
+   * @param b The exponent NonNegativeInt16.
+   * @returns `a ** b` clamped to [0, 32767] as a NonNegativeInt16.
+   */
+  pow,
+
+  /**
+   * Adds two NonNegativeInt16 values.
+   * @param a The first NonNegativeInt16.
+   * @param b The second NonNegativeInt16.
+   * @returns `a + b` clamped to [0, 32767] as a NonNegativeInt16.
+   */
+  add,
+
+  /**
+   * Subtracts one NonNegativeInt16 from another.
+   * @param a The minuend NonNegativeInt16.
+   * @param b The subtrahend NonNegativeInt16.
+   * @returns `a - b` clamped to [0, 32767] as a NonNegativeInt16 (minimum 0).
+   */
+  sub,
+
+  /**
+   * Multiplies two NonNegativeInt16 values.
+   * @param a The first NonNegativeInt16.
+   * @param b The second NonNegativeInt16.
+   * @returns `a * b` clamped to [0, 32767] as a NonNegativeInt16.
+   */
+  mul,
+
+  /**
+   * Divides one NonNegativeInt16 by another using floor division.
+   * @param a The dividend NonNegativeInt16.
+   * @param b The divisor NonNegativeInt16.
+   * @returns `⌊a / b⌋` clamped to [0, 32767] as a NonNegativeInt16.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof NonNegativeInt16,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof NonNegativeInt16,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('<=');