ts-data-forge 1.0.0

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

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

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

@@ -0,0 +1,170 @@
+import { expectType } from '../../expect-type.mjs';
+import { asNonZeroUint16 } from './non-zero-uint16.mjs';
+import { asUint16, isUint16, Uint16 } from './uint16.mjs';
+
+describe('Uint16', () => {
+  describe('asUint16', () => {
+    test('accepts valid uint16 values', () => {
+      expect(() => asUint16(0)).not.toThrow();
+      expect(() => asUint16(1)).not.toThrow();
+      expect(() => asUint16(65535)).not.toThrow(); // 2^16 - 1
+      expect(() => asUint16(32768)).not.toThrow(); // 2^15
+    });
+
+    test('rejects values outside uint16 range', () => {
+      expect(() => asUint16(65536)).toThrow(TypeError); // 2^16
+      expect(() => asUint16(100000)).toThrow(TypeError);
+    });
+
+    test('rejects negative integers', () => {
+      expect(() => asUint16(-1)).toThrow(TypeError);
+      expect(() => asUint16(-42)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asUint16(Number.NaN)).toThrow(TypeError);
+      expect(() => asUint16(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asUint16(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asUint16(1.2)).toThrow(TypeError);
+      expect(() => asUint16(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asUint16(5)).toBe(5);
+      expect(asUint16(0)).toBe(0);
+      expect(asUint16(65535)).toBe(65535);
+    });
+
+    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: '-1', value: -1 },
+    ] as const)(`asUint16($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asUint16(value)).toThrow(
+        new TypeError(
+          `Expected a non-negative integer less than 2^16, got: ${value}`,
+        ),
+      );
+    });
+  });
+
+  describe('isUint16', () => {
+    test('correctly identifies uint16 values', () => {
+      expect(isUint16(0)).toBe(true);
+      expect(isUint16(1)).toBe(true);
+      expect(isUint16(65535)).toBe(true);
+      expect(isUint16(32768)).toBe(true);
+    });
+
+    test('correctly identifies values outside uint16 range', () => {
+      expect(isUint16(65536)).toBe(false);
+      expect(isUint16(100000)).toBe(false);
+    });
+
+    test('correctly identifies negative integers', () => {
+      expect(isUint16(-1)).toBe(false);
+      expect(isUint16(-42)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isUint16(Number.NaN)).toBe(false);
+      expect(isUint16(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isUint16(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isUint16(1.2)).toBe(false);
+      expect(isUint16(-3.4)).toBe(false);
+    });
+  });
+
+  describe('Uint16.is', () => {
+    test('same as isUint16 function', () => {
+      expect(Uint16.is(5)).toBe(isUint16(5));
+      expect(Uint16.is(65536)).toBe(isUint16(65536));
+      expect(Uint16.is(-1)).toBe(isUint16(-1));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(Uint16.MIN_VALUE).toBe(0);
+      expect(Uint16.MAX_VALUE).toBe(65535);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asUint16(100);
+    const b = asUint16(50);
+    const c = asUint16(0);
+
+    test('min and max', () => {
+      expect(Uint16.min(a, b)).toBe(50);
+      expect(Uint16.max(a, b)).toBe(100);
+      expect(Uint16.min(a, c)).toBe(0);
+      expect(Uint16.max(a, c)).toBe(100);
+    });
+
+    test('add (with clamping to uint16 range)', () => {
+      const result = Uint16.add(asUint16(65000), asUint16(1000));
+      expect(result).toBe(65535); // clamped to max
+      expect(Uint16.add(a, b)).toBe(150);
+    });
+
+    test('sub (never goes below 0)', () => {
+      expect(Uint16.sub(a, b)).toBe(50);
+      expect(Uint16.sub(b, a)).toBe(0); // clamped to 0
+      expect(Uint16.sub(c, a)).toBe(0); // clamped to 0
+    });
+
+    test('mul (with clamping to uint16 range)', () => {
+      const result = Uint16.mul(asUint16(1000), asUint16(100));
+      expect(result).toBe(65535); // clamped to max
+      expect(Uint16.mul(asUint16(10), asUint16(5))).toBe(50);
+    });
+
+    test('div (floor division, never goes below 0)', () => {
+      expect(Uint16.div(a, asNonZeroUint16(50))).toBe(2);
+      expect(Uint16.div(asUint16(7), asNonZeroUint16(3))).toBe(2);
+      expect(Uint16.div(asUint16(50), asNonZeroUint16(100))).toBe(0); // floor(50/100) = 0
+    });
+
+    test('pow (with clamping to uint16 range)', () => {
+      const result = Uint16.pow(asUint16(256), asUint16(3));
+      expect(result).toBe(65535); // clamped to max
+      expect(Uint16.pow(asUint16(2), asUint16(3))).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates uint16 values within specified range', () => {
+      const min = 0;
+      const max = 20;
+
+      for (let i = 0; i < 10; i++) {
+        const result = Uint16.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(Uint16.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).toBeGreaterThanOrEqual(0);
+      }
+    });
+
+    test('generates values within Uint16 range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = Uint16.random(0, 30);
+        expect(result).toBeGreaterThanOrEqual(0);
+        expect(result).toBeLessThanOrEqual(65535);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<Uint16, number>('<=');
+
+      expectTypeOf(asUint16(100)).toExtend<Uint16>();
+    });
+  });
+});

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

@@ -0,0 +1,218 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = Uint32;
+
+const typeNameInMessage = 'a non-negative integer less than 2^32';
+
+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 ** 32 - 1,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a Uint32 (32-bit unsigned integer in the range [0, 2^32)).
+ * @param value The value to check.
+ * @returns `true` if the value is a Uint32, `false` otherwise.
+ */
+export const isUint32 = is;
+
+/**
+ * Casts a number to a Uint32 type.
+ * @param value The value to cast.
+ * @returns The value as a Uint32 type.
+ * @throws {TypeError} If the value is not a non-negative integer less than 2^32.
+ * @example
+ * ```typescript
+ * const x = asUint32(1000000); // Uint32
+ * const y = asUint32(0); // Uint32
+ * // asUint32(-1); // throws TypeError
+ * // asUint32(5000000000); // throws TypeError
+ * ```
+ */
+export const asUint32 = castType;
+
+/**
+ * Utility functions for working with Uint32 (32-bit unsigned integer) branded types.
+ * Provides type-safe operations that ensure results remain within the valid range [0, 2^32).
+ * All arithmetic operations are clamped to maintain the Uint32 constraint.
+ *
+ * @example
+ * ```typescript
+ * // Type checking
+ * Uint32.is(1000000); // true
+ * Uint32.is(-1); // false
+ * Uint32.is(5000000000); // false (exceeds 2^32)
+ *
+ * // Constants
+ * console.log(Uint32.MIN_VALUE); // 0
+ * console.log(Uint32.MAX_VALUE); // 4294967295 (2^32 - 1)
+ *
+ * // Arithmetic operations (all results clamped to [0, 2^32))
+ * const a = asUint32(1000000);
+ * const b = asUint32(500000);
+ *
+ * Uint32.add(a, b); // Uint32 (1500000)
+ * Uint32.sub(a, b); // Uint32 (500000)
+ * Uint32.mul(a, b); // Uint32 (clamped if overflow)
+ * Uint32.div(a, b); // Uint32 (2)
+ * Uint32.pow(asUint32(2), asUint32(10)); // Uint32 (1024)
+ *
+ * // Utility functions
+ * Uint32.min(a, b); // Uint32 (500000)
+ * Uint32.max(a, b); // Uint32 (1000000)
+ * Uint32.clamp(asUint32(5000000000), Uint32.MIN_VALUE, Uint32.MAX_VALUE); // Uint32 (MAX_VALUE)
+ * Uint32.random(); // Random Uint32
+ * ```
+ */
+export const Uint32 = {
+  /**
+   * Type guard that checks if a value is a 32-bit unsigned integer.
+   * @param value - The value to check
+   * @returns `true` if the value is within the range [0, 2^32), `false` otherwise
+   */
+  is,
+
+  /**
+   * The minimum value for a Uint32.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum value for a Uint32.
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the minimum of multiple Uint32 values.
+   * @param values - The Uint32 values to compare
+   * @returns The smallest value as a Uint32
+   */
+  min: min_,
+
+  /**
+   * Returns the maximum of multiple Uint32 values.
+   * @param values - The Uint32 values to compare
+   * @returns The largest value as a Uint32
+   */
+  max: max_,
+
+  /**
+   * Clamps a Uint32 to be within the specified range.
+   * @param value - The value to clamp
+   * @param min - The minimum value
+   * @param max - The maximum value
+   * @returns The clamped value as a Uint32
+   * @example
+   * ```typescript
+   * Uint32.clamp(asUint32(5000000000), Uint32.MIN_VALUE, asUint32(1000)); // Uint32 (1000)
+   * ```
+   */
+  clamp,
+
+  /**
+   * Generates a random Uint32 value.
+   * @returns A random Uint32 value within [0, 2^32)
+   */
+  random,
+
+  /**
+   * Raises a Uint32 to a power, with result clamped to [0, 2^32).
+   * @param a - The base Uint32
+   * @param b - The exponent Uint32
+   * @returns `a ** b` as a Uint32, clamped to valid range
+   * @example
+   * ```typescript
+   * Uint32.pow(asUint32(2), asUint32(10)); // Uint32 (1024)
+   * ```
+   */
+  pow,
+
+  /**
+   * Adds two Uint32 values, with result clamped to [0, 2^32).
+   * @param a - First Uint32
+   * @param b - Second Uint32
+   * @returns `a + b` as a Uint32, clamped to valid range
+   * @example
+   * ```typescript
+   * Uint32.add(asUint32(1000000), asUint32(500000)); // Uint32 (1500000)
+   * ```
+   */
+  add,
+
+  /**
+   * Subtracts two Uint32 values, with result clamped to [0, 2^32).
+   * @param a - First Uint32
+   * @param b - Second Uint32
+   * @returns `a - b` as a Uint32, clamped to valid range (minimum 0)
+   * @example
+   * ```typescript
+   * Uint32.sub(asUint32(1000000), asUint32(500000)); // Uint32 (500000)
+   * Uint32.sub(asUint32(100), asUint32(500)); // Uint32 (0) - clamped
+   * ```
+   */
+  sub,
+
+  /**
+   * Multiplies two Uint32 values, with result clamped to [0, 2^32).
+   * @param a - First Uint32
+   * @param b - Second Uint32
+   * @returns `a * b` as a Uint32, clamped to valid range
+   * @example
+   * ```typescript
+   * Uint32.mul(asUint32(1000), asUint32(500)); // Uint32 (500000)
+   * ```
+   */
+  mul,
+
+  /**
+   * Divides two Uint32 values using floor division, with result clamped to [0, 2^32).
+   * @param a - The dividend Uint32
+   * @param b - The divisor Uint32
+   * @returns `⌊a / b⌋` as a Uint32, clamped to valid range
+   * @example
+   * ```typescript
+   * Uint32.div(asUint32(1000000), asUint32(500000)); // Uint32 (2)
+   * Uint32.div(asUint32(7), asUint32(3)); // Uint32 (2) - floor division
+   * ```
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof Uint32,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof Uint32,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('<=');