ts-data-forge 1.0.0

package/src/number/branded-types/safe-uint.mts

@@ -0,0 +1,187 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = SafeUint;
+
+const typeNameInMessage = 'a non-negative safe integer';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  0,
+  SafeUint
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  MIN_VALUE: 0,
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a SafeUint.
+ * @param value The value to check.
+ * @returns `true` if the value is a SafeUint, `false` otherwise.
+ */
+export const isSafeUint = is;
+
+/**
+ * Casts a number to a SafeUint type.
+ * @param value The value to cast.
+ * @returns The value as a SafeUint type.
+ * @throws {TypeError} If the value is not a non-negative safe integer.
+ * @example
+ * ```typescript
+ * const x = asSafeUint(5); // SafeUint
+ * const y = asSafeUint(0); // SafeUint
+ * // asSafeUint(-1); // throws TypeError
+ * // asSafeUint(1.5); // throws TypeError
+ * ```
+ */
+export const asSafeUint = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for safe unsigned integers.
+ *
+ * All operations automatically clamp results to the safe unsigned integer range [0, MAX_SAFE_INTEGER].
+ * This ensures that all arithmetic maintains both the non-negative constraint and IEEE 754 precision guarantees,
+ * preventing precision loss while ensuring results are never negative.
+ *
+ * @example
+ * ```typescript
+ * const a = asSafeUint(9007199254740000);  // Near MAX_SAFE_INTEGER
+ * const b = asSafeUint(1000);
+ *
+ * // Arithmetic operations with safe unsigned range clamping
+ * const sum = SafeUint.add(a, b);          // SafeUint (clamped to MAX_SAFE_INTEGER)
+ * const diff = SafeUint.sub(b, a);         // SafeUint (0 - clamped to MIN_VALUE)
+ * const product = SafeUint.mul(a, b);      // SafeUint (clamped to MAX_SAFE_INTEGER)
+ *
+ * // Range operations
+ * const clamped = SafeUint.clamp(-100);        // SafeUint (0)
+ * const minimum = SafeUint.min(a, b);          // SafeUint (1000)
+ * const maximum = SafeUint.max(a, b);          // SafeUint (a)
+ *
+ * // Utility operations
+ * const random = SafeUint.random();            // SafeUint (random safe unsigned integer)
+ * const power = SafeUint.pow(asSafeUint(2), asSafeUint(20)); // SafeUint (1048576)
+ * ```
+ */
+export const SafeUint = {
+  /**
+   * Type guard to check if a value is a SafeUint.
+   * @param value The value to check.
+   * @returns `true` if the value is a non-negative safe integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for a safe unsigned integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum safe integer value (2^53 - 1).
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the smaller of two SafeUint values.
+   * @param a The first SafeUint.
+   * @param b The second SafeUint.
+   * @returns The minimum value as a SafeUint.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two SafeUint values.
+   * @param a The first SafeUint.
+   * @param b The second SafeUint.
+   * @returns The maximum value as a SafeUint.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the safe unsigned integer range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [0, MAX_SAFE_INTEGER] as a SafeUint.
+   */
+  clamp,
+
+  /**
+   * Generates a random SafeUint value within the valid range.
+   * @returns A random SafeUint between 0 and MAX_SAFE_INTEGER.
+   */
+  random,
+
+  /**
+   * Raises a SafeUint to the power of another SafeUint.
+   * @param a The base SafeUint.
+   * @param b The exponent SafeUint.
+   * @returns `a ** b` clamped to [0, MAX_SAFE_INTEGER] as a SafeUint.
+   */
+  pow,
+
+  /**
+   * Adds two SafeUint values.
+   * @param a The first SafeUint.
+   * @param b The second SafeUint.
+   * @returns `a + b` clamped to [0, MAX_SAFE_INTEGER] as a SafeUint.
+   */
+  add,
+
+  /**
+   * Subtracts one SafeUint from another.
+   * @param a The minuend SafeUint.
+   * @param b The subtrahend SafeUint.
+   * @returns `a - b` clamped to [0, MAX_SAFE_INTEGER] as a SafeUint (minimum 0).
+   */
+  sub,
+
+  /**
+   * Multiplies two SafeUint values.
+   * @param a The first SafeUint.
+   * @param b The second SafeUint.
+   * @returns `a * b` clamped to [0, MAX_SAFE_INTEGER] as a SafeUint.
+   */
+  mul,
+
+  /**
+   * Divides one SafeUint by another using floor division.
+   * @param a The dividend SafeUint.
+   * @param b The divisor SafeUint.
+   * @returns `⌊a / b⌋` clamped to [0, MAX_SAFE_INTEGER] as a SafeUint.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof SafeUint,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof SafeUint,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative' | 'range'
+  >
+>('<=');

package/src/number/branded-types/safe-uint.test.mts

@@ -0,0 +1,176 @@
+import { expectType } from '../../expect-type.mjs';
+import { asSafeUint, isSafeUint, SafeUint } from './safe-uint.mjs';
+
+describe('SafeUint', () => {
+  describe('asSafeUint', () => {
+    test('accepts valid safe unsigned integers', () => {
+      expect(() => asSafeUint(0)).not.toThrow();
+      expect(() => asSafeUint(1)).not.toThrow();
+      expect(() => asSafeUint(42)).not.toThrow();
+      expect(() => asSafeUint(100)).not.toThrow();
+      expect(() => asSafeUint(Number.MAX_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects negative numbers', () => {
+      expect(() => asSafeUint(-1)).toThrow(TypeError);
+      expect(() => asSafeUint(-42)).toThrow(TypeError);
+      expect(() => asSafeUint(Number.MIN_SAFE_INTEGER)).toThrow(TypeError);
+    });
+
+    test('rejects values outside safe integer range', () => {
+      expect(() => asSafeUint(Number.MAX_SAFE_INTEGER + 1)).toThrow(TypeError);
+      expect(() => asSafeUint(Number.MAX_VALUE)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asSafeUint(Number.NaN)).toThrow(TypeError);
+      expect(() => asSafeUint(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asSafeUint(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asSafeUint(1.2)).toThrow(TypeError);
+      expect(() => asSafeUint(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asSafeUint(5)).toBe(5);
+      expect(asSafeUint(0)).toBe(0);
+      expect(asSafeUint(10)).toBe(10);
+      expect(asSafeUint(Number.MAX_SAFE_INTEGER)).toBe(Number.MAX_SAFE_INTEGER);
+    });
+
+    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)(`asSafeUint($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asSafeUint(value)).toThrow(
+        new TypeError(`Expected a non-negative safe integer, got: ${value}`),
+      );
+    });
+  });
+
+  describe('isSafeUint', () => {
+    test('correctly identifies safe unsigned integers', () => {
+      expect(isSafeUint(0)).toBe(true);
+      expect(isSafeUint(1)).toBe(true);
+      expect(isSafeUint(42)).toBe(true);
+      expect(isSafeUint(100)).toBe(true);
+      expect(isSafeUint(Number.MAX_SAFE_INTEGER)).toBe(true);
+    });
+
+    test('correctly identifies negative numbers', () => {
+      expect(isSafeUint(-1)).toBe(false);
+      expect(isSafeUint(-42)).toBe(false);
+      expect(isSafeUint(Number.MIN_SAFE_INTEGER)).toBe(false);
+    });
+
+    test('correctly identifies values outside safe integer range', () => {
+      expect(isSafeUint(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
+      expect(isSafeUint(Number.MAX_VALUE)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isSafeUint(Number.NaN)).toBe(false);
+      expect(isSafeUint(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isSafeUint(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isSafeUint(1.2)).toBe(false);
+      expect(isSafeUint(-3.4)).toBe(false);
+    });
+  });
+
+  describe('SafeUint.is', () => {
+    test('same as isSafeUint function', () => {
+      expect(SafeUint.is(5)).toBe(isSafeUint(5));
+      expect(SafeUint.is(-1)).toBe(isSafeUint(-1));
+      expect(SafeUint.is(0)).toBe(isSafeUint(0));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE and MAX_VALUE', () => {
+      expect(SafeUint.MIN_VALUE).toBe(0);
+      expect(SafeUint.MAX_VALUE).toBe(Number.MAX_SAFE_INTEGER);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asSafeUint(5);
+    const b = asSafeUint(2);
+    const c = asSafeUint(0);
+
+    test('min and max', () => {
+      expect(SafeUint.min(a, b)).toBe(2);
+      expect(SafeUint.max(a, b)).toBe(5);
+      expect(SafeUint.min(a, c)).toBe(0);
+      expect(SafeUint.max(a, c)).toBe(5);
+    });
+
+    test('add (clamped to safe uint range)', () => {
+      const largeValue = asSafeUint(Number.MAX_SAFE_INTEGER - 1);
+      const result = SafeUint.add(largeValue, asSafeUint(10));
+      expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+      expect(SafeUint.add(a, b)).toBe(7);
+    });
+
+    test('sub (never goes below 0)', () => {
+      expect(SafeUint.sub(a, b)).toBe(3);
+      expect(SafeUint.sub(b, a)).toBe(0); // clamped to 0
+      expect(SafeUint.sub(c, a)).toBe(0); // clamped to 0
+    });
+
+    test('mul (clamped to safe uint range)', () => {
+      const largeValue = asSafeUint(
+        Math.floor(Math.sqrt(Number.MAX_SAFE_INTEGER)),
+      );
+      const result = SafeUint.mul(largeValue, largeValue);
+      expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+      expect(SafeUint.mul(asSafeUint(10), asSafeUint(5))).toBe(50);
+    });
+
+    test('div (floor division, never goes below 0)', () => {
+      expect(SafeUint.div(a, b)).toBe(2);
+      expect(SafeUint.div(asSafeUint(7), asSafeUint(3))).toBe(2);
+      expect(SafeUint.div(b, a)).toBe(0); // floor(2/5) = 0
+    });
+
+    test('pow (clamped to safe uint range)', () => {
+      const result = SafeUint.pow(asSafeUint(1000), asSafeUint(10));
+      expect(result).toBe(Number.MAX_SAFE_INTEGER); // clamped to max
+      expect(SafeUint.pow(asSafeUint(2), asSafeUint(3))).toBe(8);
+    });
+  });
+
+  describe('random', () => {
+    test('generates safe unsigned integers within specified range', () => {
+      const min = 0;
+      const max = 20;
+
+      for (let i = 0; i < 10; i++) {
+        const result = SafeUint.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(SafeUint.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).toBeGreaterThanOrEqual(0);
+      }
+    });
+
+    test('generates values within safe uint range', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = SafeUint.random(0, 30);
+        expect(result).toBeGreaterThanOrEqual(0);
+        expect(result).toBeLessThanOrEqual(Number.MAX_SAFE_INTEGER);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<SafeUint, number>('<=');
+
+      expectTypeOf(asSafeUint(5)).toExtend<SafeUint>();
+    });
+  });
+});

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

@@ -0,0 +1,179 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = Uint;
+
+const typeNameInMessage = 'a non-negative integer';
+
+const {
+  MIN_VALUE,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  0,
+  undefined
+>({
+  integerOrSafeInteger: 'Integer',
+  MIN_VALUE: 0,
+  MAX_VALUE: undefined,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Checks if a number is a Uint.
+ * @param value The value to check.
+ * @returns `true` if the value is a Uint, `false` otherwise.
+ */
+export const isUint = is;
+
+/**
+ * Casts a number to a Uint type.
+ * @param value The value to cast.
+ * @returns The value as a Uint type.
+ * @throws {TypeError} If the value is not a non-negative integer.
+ * @example
+ * ```typescript
+ * const x = asUint(5); // Uint
+ * const y = asUint(0); // Uint
+ * // asUint(-1); // throws TypeError
+ * // asUint(1.5); // throws TypeError
+ * ```
+ */
+export const asUint = castType;
+
+/**
+ * Namespace providing type-safe arithmetic operations for unsigned integers.
+ *
+ * All operations maintain the non-negative constraint by clamping negative results to 0.
+ * This ensures that all arithmetic preserves the unsigned integer property.
+ *
+ * @example
+ * ```typescript
+ * const a = asUint(100);
+ * const b = asUint(150);
+ *
+ * // Arithmetic operations with non-negative clamping
+ * const sum = Uint.add(a, b);       // Uint (250)
+ * const diff = Uint.sub(a, b);      // Uint (0 - clamped to MIN_VALUE)
+ * const product = Uint.mul(a, b);   // Uint (15000)
+ * const quotient = Uint.div(b, a);  // Uint (1)
+ *
+ * // Range operations
+ * const clamped = Uint.clamp(-50);      // Uint (0)
+ * const minimum = Uint.min(a, b);       // Uint (100)
+ * const maximum = Uint.max(a, b);       // Uint (150)
+ *
+ * // Utility operations
+ * const random = Uint.random();         // Uint (random non-negative integer)
+ * const power = Uint.pow(asUint(2), asUint(8)); // Uint (256)
+ * ```
+ */
+export const Uint = {
+  /**
+   * Type guard to check if a value is a Uint.
+   * @param value The value to check.
+   * @returns `true` if the value is a non-negative integer, `false` otherwise.
+   */
+  is,
+
+  /**
+   * The minimum value for an unsigned integer.
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * Returns the smaller of two Uint values.
+   * @param a The first Uint.
+   * @param b The second Uint.
+   * @returns The minimum value as a Uint.
+   */
+  min: min_,
+
+  /**
+   * Returns the larger of two Uint values.
+   * @param a The first Uint.
+   * @param b The second Uint.
+   * @returns The maximum value as a Uint.
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the Uint range (non-negative).
+   * @param value The number to clamp.
+   * @returns The value clamped to [0, +∞) as a Uint.
+   */
+  clamp,
+
+  /**
+   * Generates a random Uint value.
+   * @returns A random non-negative integer as a Uint.
+   */
+  random,
+
+  /**
+   * Raises a Uint to the power of another Uint.
+   * @param a The base Uint.
+   * @param b The exponent Uint.
+   * @returns `a ** b` clamped to [0, +∞) as a Uint.
+   */
+  pow,
+
+  /**
+   * Adds two Uint values.
+   * @param a The first Uint.
+   * @param b The second Uint.
+   * @returns `a + b` clamped to [0, +∞) as a Uint.
+   */
+  add,
+
+  /**
+   * Subtracts one Uint from another.
+   * @param a The minuend Uint.
+   * @param b The subtrahend Uint.
+   * @returns `a - b` clamped to [0, +∞) as a Uint (minimum 0).
+   */
+  sub,
+
+  /**
+   * Multiplies two Uint values.
+   * @param a The first Uint.
+   * @param b The second Uint.
+   * @returns `a * b` clamped to [0, +∞) as a Uint.
+   */
+  mul,
+
+  /**
+   * Divides one Uint by another using floor division.
+   * @param a The dividend Uint.
+   * @param b The divisor Uint.
+   * @returns `⌊a / b⌋` clamped to [0, +∞) as a Uint.
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof Uint,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative'
+  >
+>('=');
+
+expectType<
+  typeof Uint,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'non-negative'
+  >
+>('<=');

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

@@ -0,0 +1,158 @@
+import { expectType } from '../../expect-type.mjs';
+import { asUint, isUint, Uint } from './uint.mjs';
+
+describe('Uint', () => {
+  describe('asUint', () => {
+    test('accepts valid unsigned integers', () => {
+      expect(() => asUint(0)).not.toThrow();
+      expect(() => asUint(1)).not.toThrow();
+      expect(() => asUint(42)).not.toThrow();
+      expect(() => asUint(100)).not.toThrow();
+      expect(() => asUint(Number.MAX_SAFE_INTEGER)).not.toThrow();
+    });
+
+    test('rejects negative integers', () => {
+      expect(() => asUint(-1)).toThrow(TypeError);
+      expect(() => asUint(-42)).toThrow(TypeError);
+      expect(() => asUint(Number.MIN_SAFE_INTEGER)).toThrow(TypeError);
+    });
+
+    test('rejects non-integers', () => {
+      expect(() => asUint(Number.NaN)).toThrow(TypeError);
+      expect(() => asUint(Number.POSITIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asUint(Number.NEGATIVE_INFINITY)).toThrow(TypeError);
+      expect(() => asUint(1.2)).toThrow(TypeError);
+      expect(() => asUint(-3.4)).toThrow(TypeError);
+    });
+
+    test('returns the same value for valid inputs', () => {
+      expect(asUint(5)).toBe(5);
+      expect(asUint(0)).toBe(0);
+      expect(asUint(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 },
+      { name: '-3.4', value: -3.4 },
+      { name: '-1', value: -1 },
+    ] as const)(`asUint($name) should throw a TypeError`, ({ value }) => {
+      expect(() => asUint(value)).toThrow(
+        new TypeError(`Expected a non-negative integer, got: ${value}`),
+      );
+    });
+  });
+
+  describe('isUint', () => {
+    test('correctly identifies unsigned integers', () => {
+      expect(isUint(0)).toBe(true);
+      expect(isUint(1)).toBe(true);
+      expect(isUint(42)).toBe(true);
+      expect(isUint(100)).toBe(true);
+      expect(isUint(Number.MAX_SAFE_INTEGER)).toBe(true);
+    });
+
+    test('correctly identifies negative integers', () => {
+      expect(isUint(-1)).toBe(false);
+      expect(isUint(-42)).toBe(false);
+      expect(isUint(Number.MIN_SAFE_INTEGER)).toBe(false);
+    });
+
+    test('correctly identifies non-integers', () => {
+      expect(isUint(Number.NaN)).toBe(false);
+      expect(isUint(Number.POSITIVE_INFINITY)).toBe(false);
+      expect(isUint(Number.NEGATIVE_INFINITY)).toBe(false);
+      expect(isUint(1.2)).toBe(false);
+      expect(isUint(-3.4)).toBe(false);
+    });
+  });
+
+  describe('Uint.is', () => {
+    test('same as isUint function', () => {
+      expect(Uint.is(5)).toBe(isUint(5));
+      expect(Uint.is(-1)).toBe(isUint(-1));
+      expect(Uint.is(0)).toBe(isUint(0));
+    });
+  });
+
+  describe('constants', () => {
+    test('MIN_VALUE', () => {
+      expect(Uint.MIN_VALUE).toBe(0);
+    });
+  });
+
+  describe('mathematical operations', () => {
+    const a = asUint(5);
+    const b = asUint(2);
+    const c = asUint(0);
+
+    test('min and max', () => {
+      expect(Uint.min(a, b)).toBe(2);
+      expect(Uint.max(a, b)).toBe(5);
+      expect(Uint.min(a, c)).toBe(0);
+      expect(Uint.max(a, c)).toBe(5);
+    });
+
+    test('add (never goes below 0)', () => {
+      expect(Uint.add(a, b)).toBe(7);
+      expect(Uint.add(a, c)).toBe(5);
+    });
+
+    test('sub (never goes below 0)', () => {
+      expect(Uint.sub(a, b)).toBe(3);
+      expect(Uint.sub(b, a)).toBe(0); // clamped to 0
+      expect(Uint.sub(c, a)).toBe(0); // clamped to 0
+    });
+
+    test('mul (never goes below 0)', () => {
+      expect(Uint.mul(a, b)).toBe(10);
+      expect(Uint.mul(a, c)).toBe(0);
+    });
+
+    test('div (floor division, never goes below 0)', () => {
+      expect(Uint.div(a, b)).toBe(2);
+      expect(Uint.div(asUint(7), asUint(3))).toBe(2);
+      expect(Uint.div(b, a)).toBe(0); // floor(2/5) = 0
+    });
+
+    test('pow (never goes below 0)', () => {
+      expect(Uint.pow(asUint(2), asUint(3))).toBe(8);
+      expect(Uint.pow(asUint(3), asUint(2))).toBe(9);
+      expect(Uint.pow(asUint(5), asUint(0))).toBe(1);
+    });
+  });
+
+  describe('random', () => {
+    test('generates unsigned integers within specified range', () => {
+      const min = 0;
+      const max = 20;
+
+      for (let i = 0; i < 10; i++) {
+        const result = Uint.random(min, max);
+        expect(result).toBeGreaterThanOrEqual(min);
+        expect(result).toBeLessThanOrEqual(max);
+        expect(Uint.is(result)).toBe(true);
+        expect(Number.isInteger(result)).toBe(true);
+        expect(result).toBeGreaterThanOrEqual(0);
+      }
+    });
+
+    test('generates values starting from 0', () => {
+      for (let i = 0; i < 10; i++) {
+        const result = Uint.random(0, 30);
+        expect(result).toBeGreaterThanOrEqual(0);
+        expect(result).toBeLessThanOrEqual(30);
+      }
+    });
+  });
+
+  describe('type assertions', () => {
+    test('type relationships', () => {
+      expectType<Uint, number>('<=');
+
+      expectTypeOf(asUint(5)).toExtend<Uint>();
+    });
+  });
+});