ts-data-forge 1.0.0

package/src/number/branded-types/non-zero-uint32.mts

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

package/src/number/branded-types/non-zero-uint32.test.mts

@@ -0,0 +1,199 @@
+import { expectType } from '../../expect-type.mjs';
+import {
+  asNonZeroUint32,
+  isNonZeroUint32,
+  NonZeroUint32,
+} from './non-zero-uint32.mjs';
+
+describe('NonZeroUint32', () => {
+  describe('asNonZeroUint32', () => {
+    test('accepts valid non-zero uint32 values', () => {
+      expect(() => asNonZeroUint32(1)).not.toThrow();
+      expect(() => asNonZeroUint32(1000)).not.toThrow();
+      expect(() => asNonZeroUint32(4294967295)).not.toThrow(); // 2^32 - 1
+      expect(() => asNonZeroUint32(2147483648)).not.toThrow(); // 2^31
+    });
+
+    test('rejects zero', () => {
+      expect(() => asNonZeroUint32(0)).toThrow(TypeError);
+    });
+
+    test('rejects values outside uint32 range', () => {
+      expect(() => asNonZeroUint32(4294967296)).toThrow(TypeError); // 2^32
+      expect(() => asNonZeroUint32(10000000000)).toThrow(TypeError);
+    });
+
+    test('rejects negative integers', () => {
+      expect(() => asNonZeroUint32(-1)).toThrow(TypeError);
+      expect(() => asNonZeroUint32(-42)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asNonZeroUint32(Number.NaN)).toThrow(TypeError);
+      expect(() => asNonZeroUint32(Number.POSITIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asNonZeroUint32(Number.NEGATIVE_INFINITY)).toThrow(
+        TypeError,
+      );
+      expect(() => asNonZeroUint32(1.2)).toThrow(TypeError);
+      expect(() => asNonZeroUint32(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asNonZeroUint32(5)).toBe(5);
+      expect(asNonZeroUint32(1)).toBe(1);
+      expect(asNonZeroUint32(4294967295)).toBe(4294967295);
+    });
+
+    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 },
+      { name: '-3.4', value: -3.4 },
+      { name: '0', value: 0 },
+      { name: '-1', value: -1 },
+      { name: '4294967296', value: 4294967296 },
+    ] as const)(
+      `asNonZeroUint32($name) should throw a TypeError`,
+      ({ value }) => {
+        expect(() => asNonZeroUint32(value)).toThrow(
+          new TypeError(
+            `Expected a non-zero integer in [1, 2^32), got: ${value}`,
+          ),
+        );
+      },
+    );
+  });
+
+  describe('isNonZeroUint32', () => {
+    test('correctly identifies non-zero uint32 values', () => {
+      expect(isNonZeroUint32(1)).toBe(true);
+      expect(isNonZeroUint32(1000)).toBe(true);
+      expect(isNonZeroUint32(4294967295)).toBe(true);
+      expect(isNonZeroUint32(2147483648)).toBe(true);
+    });
+
+    test('correctly identifies zero', () => {
+      expect(isNonZeroUint32(0)).toBe(false);
+    });
+
+    test('correctly identifies values outside uint32 range', () => {
+      expect(isNonZeroUint32(4294967296)).toBe(false);
+      expect(isNonZeroUint32(10000000000)).toBe(false);
+    });
+
+    test('correctly identifies negative integers', () => {
+      expect(isNonZeroUint32(-1)).toBe(false);
+      expect(isNonZeroUint32(-42)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isNonZeroUint32(Number.NaN)).toBe(false);
+      expect(isNonZeroUint32(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isNonZeroUint32(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isNonZeroUint32(1.2)).toBe(false);
+      expect(isNonZeroUint32(-3.4)).toBe(false);
+    });
+  });
+
+  describe('NonZeroUint32.is', () => {
+    test('same as isNonZeroUint32 function', () => {
+      expect(NonZeroUint32.is(5)).toBe(isNonZeroUint32(5));
+      expect(NonZeroUint32.is(0)).toBe(isNonZeroUint32(0));
+      expect(NonZeroUint32.is(-1)).toBe(isNonZeroUint32(-1));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(NonZeroUint32.MIN_VALUE).toBe(1);
+      expect(NonZeroUint32.MAX_VALUE).toBe(4294967295);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asNonZeroUint32(1000000);
+    const b = asNonZeroUint32(500000);
+
+    test('min and max', () => {
+      expect(NonZeroUint32.min(a, b)).toBe(500000);
+      expect(NonZeroUint32.max(a, b)).toBe(1000000);
+    });
+
+    test('add (with clamping to non-zero uint32 range)', () => {
+      const result = NonZeroUint32.add(
+        asNonZeroUint32(4294967000),
+        asNonZeroUint32(1000),
+      );
+      expect(result).toBe(4294967295); // clamped to max
+      expect(NonZeroUint32.add(a, b)).toBe(1500000);
+    });
+
+    test('sub (never goes below 1)', () => {
+      expect(NonZeroUint32.sub(a, b)).toBe(500000);
+      expect(NonZeroUint32.sub(b, a)).toBe(1); // clamped to 1
+    });
+
+    test('mul (with clamping to non-zero uint32 range)', () => {
+      const result = NonZeroUint32.mul(
+        asNonZeroUint32(100000),
+        asNonZeroUint32(100000),
+      );
+      expect(result).toBe(4294967295); // clamped to max
+      expect(NonZeroUint32.mul(asNonZeroUint32(1000), asNonZeroUint32(5))).toBe(
+        5000,
+      );
+    });
+
+    test('div (floor division, never goes below 1)', () => {
+      expect(NonZeroUint32.div(a, asNonZeroUint32(500000))).toBe(2);
+      expect(NonZeroUint32.div(asNonZeroUint32(7), asNonZeroUint32(3))).toBe(2);
+      expect(
+        NonZeroUint32.div(asNonZeroUint32(500000), asNonZeroUint32(1000000)),
+      ).toBe(1); // floor(500000/1000000) = 0, clamped to 1
+    });
+
+    test('pow (with clamping to non-zero uint32 range)', () => {
+      const result = NonZeroUint32.pow(
+        asNonZeroUint32(10000),
+        asNonZeroUint32(3),
+      );
+      expect(result).toBe(4294967295); // clamped to max
+      expect(NonZeroUint32.pow(asNonZeroUint32(2), asNonZeroUint32(3))).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates non-zero uint32 values within specified range', () => {
+      const min = 1;
+      const max = 20;
+
+      for (let i = 0; i < 10; i++) {
+        const result = NonZeroUint32.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(NonZeroUint32.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).not.toBe(0);
+      }
+    });
+
+    test('generates values within NonZeroUint32 range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = NonZeroUint32.random(1, 30);
+        expect(result).toBeGreaterThanOrEqual(1);
+        expect(result).toBeLessThanOrEqual(4294967295);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<NonZeroUint32, number>('<=');
+
+      expectTypeOf(asNonZeroUint32(1000000)).toExtend<NonZeroUint32>();
+    });
+  });
+});

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

@@ -0,0 +1,241 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = PositiveFiniteNumber;
+
+const typeNameInMessage = 'a positive finite number';
+
+const {
+  MIN_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForFloat<
+  ElementType,
+  number,
+  undefined
+>({
+  MIN_VALUE: Number.MIN_VALUE,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+const floor = (
+  x: ElementType,
+): TsVerifiedInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+  TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>
+> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.floor(x) as TsVerifiedInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    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.RemoveNonZeroBrandKey<
+  TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>
+> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  Math.round(x) as TsVerifiedInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>
+  >;
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>,
+  PositiveInt
+>('=');
+
+expectType<
+  TsVerifiedInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<
+    TsVerifiedInternals.RefinedNumberUtils.ToInt<ElementType>
+  >,
+  Uint
+>('=');
+
+/**
+ * Checks if a number is a PositiveFiniteNumber (a finite number > 0).
+ * @param value The value to check.
+ * @returns `true` if the value is a PositiveFiniteNumber, `false` otherwise.
+ */
+export const isPositiveFiniteNumber = is;
+
+/**
+ * Casts a number to a PositiveFiniteNumber type.
+ * @param value The value to cast.
+ * @returns The value as a PositiveFiniteNumber type.
+ * @throws {TypeError} If the value is not a positive finite number.
+ * @example
+ * ```typescript
+ * const x = asPositiveFiniteNumber(5.5); // PositiveFiniteNumber
+ * const y = asPositiveFiniteNumber(0.001); // PositiveFiniteNumber
+ * // asPositiveFiniteNumber(0); // throws TypeError
+ * // asPositiveFiniteNumber(-1); // throws TypeError
+ * ```
+ */
+export const asPositiveFiniteNumber = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for positive finite numbers.
+ *
+ * All operations maintain the positive constraint by clamping non-positive results to MIN_VALUE,
+ * while ensuring results remain finite (excluding NaN and Infinity). This type is useful
+ * for representing quantities that must always be positive, such as probabilities, magnitudes,
+ * and physical measurements.
+ *
+ * @example
+ * ```typescript
+ * const probability = asPositiveFiniteNumber(0.75);
+ * const rate = asPositiveFiniteNumber(1.25);
+ *
+ * // Arithmetic operations with positive clamping
+ * const combined = PositiveFiniteNumber.add(probability, rate);        // PositiveFiniteNumber (2.0)
+ * const difference = PositiveFiniteNumber.sub(rate, probability);      // PositiveFiniteNumber (0.5)
+ * const scaled = PositiveFiniteNumber.mul(probability, rate);          // PositiveFiniteNumber (0.9375)
+ * const ratio = PositiveFiniteNumber.div(rate, probability);           // PositiveFiniteNumber (1.666...)
+ *
+ * // Range operations
+ * const clamped = PositiveFiniteNumber.clamp(-10.5);                  // PositiveFiniteNumber (MIN_VALUE)
+ * const minimum = PositiveFiniteNumber.min(probability, rate);         // PositiveFiniteNumber (0.75)
+ * const maximum = PositiveFiniteNumber.max(probability, rate);         // PositiveFiniteNumber (1.25)
+ *
+ * // Rounding operations (different return types based on operation)
+ * const ceiled = PositiveFiniteNumber.ceil(probability);              // PositiveInt (1)
+ * const floored = PositiveFiniteNumber.floor(rate);                   // Uint (1)
+ * const rounded = PositiveFiniteNumber.round(rate);                   // Uint (1)
+ *
+ * // Utility operations
+ * const random = PositiveFiniteNumber.random();                       // PositiveFiniteNumber (random positive value)
+ * const power = PositiveFiniteNumber.pow(rate, probability);          // PositiveFiniteNumber (1.18...)
+ * ```
+ */
+export const PositiveFiniteNumber = {
+  /**
+   * Type guard to check if a value is a PositiveFiniteNumber.
+   * @param value The value to check.
+   * @returns `true` if the value is a positive finite number, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a positive finite number.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * Returns the smaller of two PositiveFiniteNumber values.
+   * @param a The first PositiveFiniteNumber.
+   * @param b The second PositiveFiniteNumber.
+   * @returns The minimum value as a PositiveFiniteNumber.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two PositiveFiniteNumber values.
+   * @param a The first PositiveFiniteNumber.
+   * @param b The second PositiveFiniteNumber.
+   * @returns The maximum value as a PositiveFiniteNumber.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the positive finite range.
+   * @param value The number to clamp.
+   * @returns The value clamped to (0, +∞) as a PositiveFiniteNumber.
+   */
+  clamp,
+
+  /**
+   * Rounds down a PositiveFiniteNumber to the nearest integer.
+   * @param x The PositiveFiniteNumber to round down.
+   * @returns The floor value as a Uint (can be 0).
+   */
+  floor,
+
+  /**
+   * Rounds up a PositiveFiniteNumber to the nearest integer.
+   * @param x The PositiveFiniteNumber to round up.
+   * @returns The ceiling value as a PositiveInt (always >= 1).
+   */
+  ceil,
+
+  /**
+   * Rounds a PositiveFiniteNumber to the nearest integer.
+   * @param x The PositiveFiniteNumber to round.
+   * @returns The rounded value as a Uint (can be 0 if x < 0.5).
+   */
+  round,
+
+  /**
+   * Generates a random PositiveFiniteNumber value.
+   * @returns A random positive finite number.
+   */
+  random,
+
+  /**
+   * Raises a PositiveFiniteNumber to the power of another PositiveFiniteNumber.
+   * @param a The base PositiveFiniteNumber.
+   * @param b The exponent PositiveFiniteNumber.
+   * @returns `a ** b` clamped to (0, +∞) as a PositiveFiniteNumber.
+   */
+  pow,
+
+  /**
+   * Adds two PositiveFiniteNumber values.
+   * @param a The first PositiveFiniteNumber.
+   * @param b The second PositiveFiniteNumber.
+   * @returns `a + b` clamped to (0, +∞) as a PositiveFiniteNumber.
+   */
+  add,
+
+  /**
+   * Subtracts one PositiveFiniteNumber from another.
+   * @param a The minuend PositiveFiniteNumber.
+   * @param b The subtrahend PositiveFiniteNumber.
+   * @returns `a - b` clamped to (0, +∞) as a PositiveFiniteNumber (minimum MIN_VALUE).
+   */
+  sub,
+
+  /**
+   * Multiplies two PositiveFiniteNumber values.
+   * @param a The first PositiveFiniteNumber.
+   * @param b The second PositiveFiniteNumber.
+   * @returns `a * b` clamped to (0, +∞) as a PositiveFiniteNumber.
+   */
+  mul,
+
+  /**
+   * Divides one PositiveFiniteNumber by another.
+   * @param a The dividend PositiveFiniteNumber.
+   * @param b The divisor PositiveFiniteNumber.
+   * @returns `a / b` clamped to (0, +∞) as a PositiveFiniteNumber.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof PositiveFiniteNumber,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'positive'
+  >
+>('=');
+
+expectType<
+  typeof PositiveFiniteNumber,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<ElementType, 'positive'>
+>('<=');