ts-data-forge 1.0.0

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

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

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

@@ -0,0 +1,291 @@
+import { expectType } from '../../expect-type.mjs';
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+type ElementType = SafeInt;
+
+const typeNameInMessage = 'a safe integer';
+
+const {
+  MIN_VALUE,
+  MAX_VALUE,
+  abs,
+  min: min_,
+  max: max_,
+  pow,
+  add,
+  sub,
+  mul,
+  div,
+  random,
+  is,
+  castType,
+  clamp,
+} = TsVerifiedInternals.RefinedNumberUtils.operatorsForInteger<
+  ElementType,
+  SafeInt,
+  SafeUint
+>({
+  integerOrSafeInteger: 'SafeInteger',
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  MIN_VALUE: Number.MIN_SAFE_INTEGER as SafeInt,
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
+  typeNameInMessage,
+} as const);
+
+/**
+ * Type guard that checks if a value is a safe integer.
+ *
+ * A safe integer is an integer that can be exactly represented in JavaScript
+ * without precision loss. The range is [±(2^53 - 1)].
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a safe integer, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isSafeInt(42);                    // true
+ * isSafeInt(Number.MAX_SAFE_INTEGER); // true
+ * isSafeInt(Number.MAX_SAFE_INTEGER + 1); // false
+ * isSafeInt(3.14);                  // false
+ * isSafeInt(NaN);                   // false
+ * ```
+ */
+export const isSafeInt = is;
+
+/**
+ * Casts a number to a SafeInt branded type.
+ *
+ * This function validates that the input is a safe integer (within ±(2^53 - 1))
+ * and returns it with the SafeInt brand. This ensures type safety for operations
+ * that require precise integer arithmetic.
+ *
+ * @param value - The value to cast
+ * @returns The value as a SafeInt branded type
+ * @throws {TypeError} If the value is not a safe integer
+ *
+ * @example
+ * ```typescript
+ * const x = asSafeInt(5);          // SafeInt
+ * const y = asSafeInt(-1000);      // SafeInt
+ * const z = asSafeInt(2**50);      // SafeInt (within range)
+ *
+ * // These throw TypeError:
+ * // asSafeInt(1.5);                      // Not an integer
+ * // asSafeInt(Number.MAX_SAFE_INTEGER + 1); // Exceeds safe range
+ * // asSafeInt(2**53);                    // Loss of precision
+ * ```
+ */
+export const asSafeInt = castType;
+
+/**
+ * Namespace providing type-safe operations for SafeInt branded types.
+ *
+ * SafeInt represents integers that can be exactly represented in JavaScript's
+ * number type without precision loss. The range is [±(2^53 - 1)], which covers
+ * approximately ±9 quadrillion.
+ *
+ * All operations automatically clamp results to stay within the safe range,
+ * preventing precision loss that occurs with larger integers. This makes SafeInt
+ * ideal for:
+ * - Financial calculations requiring exact cents
+ * - Database IDs and counters
+ * - Array indices and sizes
+ * - Any integer arithmetic requiring precision guarantees
+ *
+ * @example
+ * ```typescript
+ * // Near the boundary
+ * const nearMax = asSafeInt(9007199254740990);
+ * const increment = asSafeInt(10);
+ *
+ * // Automatic clamping prevents precision loss
+ * const sum = SafeInt.add(nearMax, increment);    // Clamped to MAX_SAFE_INTEGER
+ * const product = SafeInt.mul(nearMax, increment); // Clamped to MAX_SAFE_INTEGER
+ *
+ * // Safe operations
+ * const a = asSafeInt(1000000);
+ * const b = asSafeInt(500);
+ *
+ * const diff = SafeInt.sub(a, b);        // SafeInt (999500)
+ * const quotient = SafeInt.div(a, b);    // SafeInt (2000)
+ * const power = SafeInt.pow(b, asSafeInt(2)); // SafeInt (250000)
+ *
+ * // Utility operations
+ * const absolute = SafeInt.abs(asSafeInt(-42)); // SafeInt (42)
+ * const clamped = SafeInt.clamp(2**60);         // SafeInt (MAX_SAFE_INTEGER)
+ *
+ * // Random generation
+ * const die = SafeInt.random(asSafeInt(1), asSafeInt(6)); // Random 1-6
+ * ```
+ */
+export const SafeInt = {
+  /**
+   * Type guard that checks if a value is a safe integer.
+   *
+   * @param value - The value to check
+   * @returns `true` if the value is a safe integer, `false` otherwise
+   *
+   * @see {@link isSafeInt} for usage examples
+   */
+  is,
+
+  /**
+   * The minimum safe integer value (-(2^53 - 1)).
+   * @readonly
+   */
+  MIN_VALUE,
+
+  /**
+   * The maximum safe integer value (2^53 - 1).
+   * @readonly
+   */
+  MAX_VALUE,
+
+  /**
+   * Returns the absolute value of a safe integer.
+   *
+   * Note: `Math.abs(MIN_SAFE_INTEGER)` would exceed `MAX_SAFE_INTEGER`,
+   * so this function clamps the result to maintain the safe integer guarantee.
+   *
+   * @param a - The safe integer value
+   * @returns The absolute value as a SafeInt, clamped if necessary
+   *
+   * @example
+   * ```typescript
+   * SafeInt.abs(asSafeInt(-42));    // SafeInt (42)
+   * SafeInt.abs(asSafeInt(42));     // SafeInt (42)
+   * SafeInt.abs(SafeInt.MIN_VALUE); // SafeInt (MAX_SAFE_INTEGER)
+   * ```
+   */
+  abs,
+
+  /**
+   * Returns the minimum value from a list of safe integers.
+   *
+   * @param values - The safe integers to compare (at least one required)
+   * @returns The smallest value as a SafeInt
+   *
+   * @example
+   * ```typescript
+   * SafeInt.min(asSafeInt(5), asSafeInt(3));        // SafeInt (3)
+   * SafeInt.min(asSafeInt(-10), asSafeInt(0), asSafeInt(10)); // SafeInt (-10)
+   * ```
+   */
+  min: min_,
+
+  /**
+   * Returns the maximum value from a list of safe integers.
+   *
+   * @param values - The safe integers to compare (at least one required)
+   * @returns The largest value as a SafeInt
+   *
+   * @example
+   * ```typescript
+   * SafeInt.max(asSafeInt(5), asSafeInt(3));        // SafeInt (5)
+   * SafeInt.max(asSafeInt(-10), asSafeInt(0), asSafeInt(10)); // SafeInt (10)
+   * ```
+   */
+  max: max_,
+
+  /**
+   * Clamps a number to the safe integer range.
+   * @param value The number to clamp.
+   * @returns The value clamped to [MIN_SAFE_INTEGER, MAX_SAFE_INTEGER] as a SafeInt.
+   */
+  clamp,
+
+  /**
+   * Generates a random safe integer within the specified range (inclusive).
+   *
+   * The range is inclusive on both ends. If min > max, they are automatically swapped.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random SafeInt in the range [min, max]
+   *
+   * @example
+   * ```typescript
+   * // Dice roll
+   * const d20 = SafeInt.random(asSafeInt(1), asSafeInt(20));
+   *
+   * // Random index for large array
+   * const index = SafeInt.random(asSafeInt(0), asSafeInt(1000000));
+   *
+   * // Can use full safe range
+   * const any = SafeInt.random(SafeInt.MIN_VALUE, SafeInt.MAX_VALUE);
+   * ```
+   */
+  random,
+
+  /**
+   * Raises a SafeInt to the power of another SafeInt.
+   * @param a The base SafeInt.
+   * @param b The exponent SafeInt.
+   * @returns `a ** b` clamped to safe integer range as a SafeInt.
+   */
+  pow,
+
+  /**
+   * Adds two SafeInt values.
+   * @param a The first SafeInt.
+   * @param b The second SafeInt.
+   * @returns `a + b` clamped to safe integer range as a SafeInt.
+   */
+  add,
+
+  /**
+   * Subtracts one SafeInt from another.
+   * @param a The minuend SafeInt.
+   * @param b The subtrahend SafeInt.
+   * @returns `a - b` clamped to safe integer range as a SafeInt.
+   */
+  sub,
+
+  /**
+   * Multiplies two SafeInt values.
+   * @param a The first SafeInt.
+   * @param b The second SafeInt.
+   * @returns `a * b` clamped to safe integer range as a SafeInt.
+   */
+  mul,
+
+  /**
+   * Divides one SafeInt by another using floor division.
+   *
+   * Performs mathematical floor division: `⌊a / b⌋`.
+   * The divisor must be non-zero (enforced by type constraints).
+   *
+   * @param a - The dividend
+   * @param b - The divisor (must be non-zero)
+   * @returns The integer quotient as a SafeInt
+   *
+   * @example
+   * ```typescript
+   * SafeInt.div(asSafeInt(10), asSafeInt(3));   // SafeInt (3)
+   * SafeInt.div(asSafeInt(-10), asSafeInt(3));  // SafeInt (-4)
+   *
+   * // Large number division
+   * const large = asSafeInt(1000000000000);
+   * const divisor = asSafeInt(1000000);
+   * SafeInt.div(large, divisor); // SafeInt (1000000)
+   * ```
+   */
+  div,
+} as const;
+
+expectType<
+  keyof typeof SafeInt,
+  keyof TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'range'
+  >
+>('=');
+
+expectType<
+  typeof SafeInt,
+  TsVerifiedInternals.RefinedNumberUtils.NumberClass<
+    ElementType,
+    'int' | 'range'
+  >
+>('<=');

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

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