ts-data-forge 3.3.0 → 3.3.1

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

@@ -31,7 +31,9 @@ const {
 } as const);
 
 /**
- * Checks if a number is a PositiveUint32 (32-bit positive unsigned integer in the range [1, 2^32)).
+ * Checks if a number is a PositiveUint32 (32-bit positive unsigned integer in
+ * the range [1, 2^32)).
+ *
  * @param value The value to check.
  * @returns `true` if the value is a PositiveUint32, `false` otherwise.
  */
@@ -39,70 +41,49 @@ export const isPositiveUint32 = is;
 
 /**
  * Casts a number to a PositiveUint32 type.
+ *
  * @param value The value to cast.
  * @returns The value as a PositiveUint32 type.
  * @throws {TypeError} If the value is not a positive integer in [1, 2^32).
- * @example
- * ```typescript
- * const x = asPositiveUint32(1000); // PositiveUint32
- * const y = asPositiveUint32(4294967295); // PositiveUint32
- * // asPositiveUint32(0); // throws TypeError
- * // asPositiveUint32(-1); // throws TypeError
- * // asPositiveUint32(4294967296); // throws TypeError
- * ```
  */
 export const asPositiveUint32 = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for 32-bit positive unsigned integers.
- *
- * All operations automatically clamp results to the valid PositiveUint32 range [1, 4294967295].
- * This ensures that all arithmetic maintains the 32-bit positive unsigned integer constraint,
- * with results below 1 clamped to MIN_VALUE and overflow results clamped to MAX_VALUE.
- *
- * @example
- * ```typescript
- * const a = asPositiveUint32(4000000000);
- * const b = asPositiveUint32(1000000000);
- *
- * // Arithmetic operations with automatic clamping and positive constraint
- * const sum = PositiveUint32.add(a, b);       // PositiveUint32 (4294967295 - clamped to MAX_VALUE)
- * const diff = PositiveUint32.sub(a, b);      // PositiveUint32 (3000000000)
- * const reverseDiff = PositiveUint32.sub(b, a); // PositiveUint32 (1 - clamped to MIN_VALUE)
- * const product = PositiveUint32.mul(a, b);   // PositiveUint32 (4294967295 - clamped due to overflow)
- *
- * // Range operations (maintaining positive constraint)
- * const clamped = PositiveUint32.clamp(-100);     // PositiveUint32 (1)
- * const minimum = PositiveUint32.min(a, b);       // PositiveUint32 (1000000000)
- * const maximum = PositiveUint32.max(a, b);       // PositiveUint32 (4000000000)
+ * Namespace providing type-safe arithmetic operations for 32-bit positive
+ * unsigned integers.
  *
- * // Utility operations
- * const random = PositiveUint32.random();         // PositiveUint32 (random value in [1, 4294967295])
- * const power = PositiveUint32.pow(asPositiveUint32(2), asPositiveUint32(20)); // PositiveUint32 (1048576)
- * ```
+ * All operations automatically clamp results to the valid PositiveUint32 range
+ * [1, 4294967295]. This ensures that all arithmetic maintains the 32-bit
+ * positive unsigned integer constraint, with results below 1 clamped to
+ * MIN_VALUE and overflow results clamped to MAX_VALUE.
  */
 export const PositiveUint32 = {
   /**
    * Type guard to check if a value is a PositiveUint32.
+   *
    * @param value The value to check.
-   * @returns `true` if the value is a 32-bit positive unsigned integer, `false` otherwise.
+   * @returns `true` if the value is a 32-bit positive unsigned integer, `false`
+   *   otherwise.
    */
   is,
 
   /**
    * The minimum value for a 32-bit positive unsigned integer.
+   *
    * @readonly
    */
   MIN_VALUE,
 
   /**
    * The maximum value for a 32-bit positive unsigned integer.
+   *
    * @readonly
    */
   MAX_VALUE,
 
   /**
    * Returns the smaller of two PositiveUint32 values.
+   *
    * @param a The first PositiveUint32.
    * @param b The second PositiveUint32.
    * @returns The minimum value as a PositiveUint32.
@@ -111,6 +92,7 @@ export const PositiveUint32 = {
 
   /**
    * Returns the larger of two PositiveUint32 values.
+   *
    * @param a The first PositiveUint32.
    * @param b The second PositiveUint32.
    * @returns The maximum value as a PositiveUint32.
@@ -119,6 +101,7 @@ export const PositiveUint32 = {
 
   /**
    * Clamps a number to the PositiveUint32 range.
+   *
    * @param value The number to clamp.
    * @returns The value clamped to [1, 4294967295] as a PositiveUint32.
    */
@@ -126,12 +109,14 @@ export const PositiveUint32 = {
 
   /**
    * Generates a random PositiveUint32 value within the valid range.
+   *
    * @returns A random PositiveUint32 between 1 and 4294967295.
    */
   random,
 
   /**
    * Raises a PositiveUint32 to the power of another PositiveUint32.
+   *
    * @param a The base PositiveUint32.
    * @param b The exponent PositiveUint32.
    * @returns `a ** b` clamped to [1, 4294967295] as a PositiveUint32.
@@ -140,6 +125,7 @@ export const PositiveUint32 = {
 
   /**
    * Adds two PositiveUint32 values.
+   *
    * @param a The first PositiveUint32.
    * @param b The second PositiveUint32.
    * @returns `a + b` clamped to [1, 4294967295] as a PositiveUint32.
@@ -148,14 +134,17 @@ export const PositiveUint32 = {
 
   /**
    * Subtracts one PositiveUint32 from another.
+   *
    * @param a The minuend PositiveUint32.
    * @param b The subtrahend PositiveUint32.
-   * @returns `a - b` clamped to [1, 4294967295] as a PositiveUint32 (minimum 1).
+   * @returns `a - b` clamped to [1, 4294967295] as a PositiveUint32 (minimum
+   *   1).
    */
   sub,
 
   /**
    * Multiplies two PositiveUint32 values.
+   *
    * @param a The first PositiveUint32.
    * @param b The second PositiveUint32.
    * @returns `a * b` clamped to [1, 4294967295] as a PositiveUint32.
@@ -164,6 +153,7 @@ export const PositiveUint32 = {
 
   /**
    * Divides one PositiveUint32 by another using floor division.
+   *
    * @param a The dividend PositiveUint32.
    * @param b The divisor PositiveUint32.
    * @returns `⌊a / b⌋` clamped to [1, 4294967295] as a PositiveUint32.

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

@@ -11,8 +11,8 @@ describe('PositiveUint32', () => {
     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
+      expect(() => asPositiveUint32(4_294_967_295)).not.toThrow(); // 2^32 - 1
+      expect(() => asPositiveUint32(2_147_483_648)).not.toThrow(); // 2^31
     });
 
     test('rejects zero', () => {
@@ -20,8 +20,8 @@ describe('PositiveUint32', () => {
     });
 
     test('rejects values outside uint32 range', () => {
-      expect(() => asPositiveUint32(4294967296)).toThrow(TypeError); // 2^32
-      expect(() => asPositiveUint32(10000000000)).toThrow(TypeError);
+      expect(() => asPositiveUint32(4_294_967_296)).toThrow(TypeError); // 2^32
+      expect(() => asPositiveUint32(10_000_000_000)).toThrow(TypeError);
     });
 
     test('rejects negative integers', () => {
@@ -44,7 +44,7 @@ describe('PositiveUint32', () => {
     test('returns the same value for valid inputs', () => {
       expect(asPositiveUint32(5)).toBe(5);
       expect(asPositiveUint32(1)).toBe(1);
-      expect(asPositiveUint32(4294967295)).toBe(4294967295);
+      expect(asPositiveUint32(4_294_967_295)).toBe(4_294_967_295);
     });
 
     test.each([
@@ -55,7 +55,7 @@ describe('PositiveUint32', () => {
       { name: '-3.4', value: -3.4 },
       { name: '0', value: 0 },
       { name: '-1', value: -1 },
-      { name: '4294967296', value: 4294967296 },
+      { name: '4294967296', value: 4_294_967_296 },
     ] as const)(
       `asPositiveUint32($name) should throw a TypeError`,
       ({ value }) => {
@@ -72,8 +72,8 @@ describe('PositiveUint32', () => {
     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);
+      expect(isPositiveUint32(4_294_967_295)).toBe(true);
+      expect(isPositiveUint32(2_147_483_648)).toBe(true);
     });
 
     test('correctly identifies zero', () => {
@@ -81,8 +81,8 @@ describe('PositiveUint32', () => {
     });
 
     test('correctly identifies values outside uint32 range', () => {
-      expect(isPositiveUint32(4294967296)).toBe(false);
-      expect(isPositiveUint32(10000000000)).toBe(false);
+      expect(isPositiveUint32(4_294_967_296)).toBe(false);
+      expect(isPositiveUint32(10_000_000_000)).toBe(false);
     });
 
     test('correctly identifies negative integers', () => {
@@ -110,60 +110,63 @@ describe('PositiveUint32', () => {
   describe('constants', () => {
     test('MIN_VALUE and MAX_VALUE', () => {
       expect(PositiveUint32.MIN_VALUE).toBe(1);
-      expect(PositiveUint32.MAX_VALUE).toBe(4294967295);
+      expect(PositiveUint32.MAX_VALUE).toBe(4_294_967_295);
     });
   });
 
   describe('mathematical operations', () => {
-    const a = asPositiveUint32(1000000);
-    const b = asPositiveUint32(500000);
+    const a = asPositiveUint32(1_000_000);
+    const b = asPositiveUint32(500_000);
 
     test('min and max', () => {
-      expect(PositiveUint32.min(a, b)).toBe(500000);
-      expect(PositiveUint32.max(a, b)).toBe(1000000);
+      expect(PositiveUint32.min(a, b)).toBe(500_000);
+      expect(PositiveUint32.max(a, b)).toBe(1_000_000);
     });
 
     test('add (with clamping to positive uint32 range)', () => {
       const result = PositiveUint32.add(
-        asPositiveUint32(4294967000),
+        asPositiveUint32(4_294_967_000),
         asPositiveUint32(1000),
       );
-      expect(result).toBe(4294967295); // clamped to max
-      expect(PositiveUint32.add(a, b)).toBe(1500000);
+      expect(result).toBe(4_294_967_295); // clamped to max
+      expect(PositiveUint32.add(a, b)).toBe(1_500_000);
     });
 
     test('sub (never goes below 1)', () => {
-      expect(PositiveUint32.sub(a, b)).toBe(500000);
+      expect(PositiveUint32.sub(a, b)).toBe(500_000);
       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),
+        asPositiveUint32(100_000),
+        asPositiveUint32(100_000),
       );
-      expect(result).toBe(4294967295); // clamped to max
+      expect(result).toBe(4_294_967_295); // 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(a, asPositiveUint32(500_000))).toBe(2);
       expect(PositiveUint32.div(asPositiveUint32(7), asPositiveUint32(3))).toBe(
         2,
       );
       expect(
-        PositiveUint32.div(asPositiveUint32(500000), asPositiveUint32(1000000)),
+        PositiveUint32.div(
+          asPositiveUint32(500_000),
+          asPositiveUint32(1_000_000),
+        ),
       ).toBe(1); // floor(500000/1000000) = 0, clamped to 1
     });
 
     test('pow (with clamping to positive uint32 range)', () => {
       const result = PositiveUint32.pow(
-        asPositiveUint32(10000),
+        asPositiveUint32(10_000),
         asPositiveUint32(3),
       );
-      expect(result).toBe(4294967295); // clamped to max
+      expect(result).toBe(4_294_967_295); // clamped to max
       expect(PositiveUint32.pow(asPositiveUint32(2), asPositiveUint32(3))).toBe(
         8,
       );
@@ -189,7 +192,7 @@ describe('PositiveUint32', () => {
       for (const _ of range(10)) {
         const result = PositiveUint32.random(1, 30);
         expect(result).toBeGreaterThanOrEqual(1);
-        expect(result).toBeLessThanOrEqual(4294967295);
+        expect(result).toBeLessThanOrEqual(4_294_967_295);
       }
     });
   });
@@ -198,7 +201,7 @@ describe('PositiveUint32', () => {
     test('type relationships', () => {
       expectType<PositiveUint32, number>('<=');
 
-      expectTypeOf(asPositiveUint32(1000000)).toExtend<PositiveUint32>();
+      expectTypeOf(asPositiveUint32(1_000_000)).toExtend<PositiveUint32>();
     });
   });
 });

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

@@ -26,9 +26,9 @@ const {
   SafeUint
 >({
   integerOrSafeInteger: 'SafeInteger',
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   MIN_VALUE: Number.MIN_SAFE_INTEGER as SafeInt,
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);
@@ -39,17 +39,16 @@ const {
  * 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
+ *
+ * ```ts
+ * assert.ok(isSafeInt(Number.MAX_SAFE_INTEGER));
+ * assert.notOk(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
+ * assert.ok(SafeInt.is(Number.MIN_SAFE_INTEGER));
  * ```
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a safe integer, `false` otherwise
  */
 export const isSafeInt = is;
 
@@ -57,24 +56,21 @@ 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
+ * and returns it with the SafeInt brand. This ensures type safety for
+ * operations that require precise integer arithmetic.
  *
  * @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
+ * ```ts
+ * const branded = asSafeInt(123);
+ *
+ * assert(branded === 123);
+ * assert.ok(SafeInt.is(branded));
  * ```
+ *
+ * @param value - The value to cast
+ * @returns The value as a SafeInt branded type
+ * @throws {TypeError} If the value is not a safe integer
  */
 export const asSafeInt = castType;
 
@@ -86,58 +82,42 @@ export const asSafeInt = castType;
  * 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:
+ * 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.
    *
+   * @example
+   *
+   * ```ts
+   * assert.ok(isSafeInt(Number.MAX_SAFE_INTEGER));
+   * assert.notOk(isSafeInt(Number.MAX_SAFE_INTEGER + 0.5));
+   * assert.ok(SafeInt.is(Number.MIN_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,
@@ -145,81 +125,114 @@ export const SafeInt = {
   /**
    * 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
+   * Note: `Math.abs(MIN_SAFE_INTEGER)` would exceed `MAX_SAFE_INTEGER`, so this
+   * function clamps the result to maintain the safe integer guarantee.
    *
    * @example
-   * ```typescript
-   * SafeInt.abs(asSafeInt(-42));    // SafeInt (42)
-   * SafeInt.abs(asSafeInt(42));     // SafeInt (42)
-   * SafeInt.abs(SafeInt.MIN_VALUE); // SafeInt (MAX_SAFE_INTEGER)
+   *
+   * ```ts
+   * const negative = asSafeInt(-900);
+   * const absolute = SafeInt.abs(negative);
+   *
+   * assert(absolute === 900);
+   * assert.ok(SafeInt.is(absolute));
    * ```
+   *
+   * @param a - The safe integer value
+   * @returns The absolute value as a SafeInt, clamped if necessary
    */
   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)
+   *
+   * ```ts
+   * const smallest = SafeInt.min(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
+   *
+   * assert(smallest === -14);
    * ```
+   *
+   * @param values - The safe integers to compare (at least one required)
+   * @returns The smallest value as a SafeInt
    */
   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)
+   *
+   * ```ts
+   * const largest = SafeInt.max(asSafeInt(25), asSafeInt(-14), asSafeInt(99));
+   *
+   * assert(largest === 99);
    * ```
+   *
+   * @param values - The safe integers to compare (at least one required)
+   * @returns The largest value as a SafeInt
    */
   max: max_,
 
   /**
    * Clamps a number to the safe integer range.
+   *
+   * @example
+   *
+   * ```ts
+   * const aboveRange = SafeInt.clamp(1e20);
+   * const withinRange = SafeInt.clamp(123);
+   * const belowRange = SafeInt.clamp(-1e20);
+   *
+   * assert(aboveRange === Number.MAX_SAFE_INTEGER);
+   * assert(withinRange === 123);
+   * assert(belowRange === Number.MIN_SAFE_INTEGER);
+   * ```
+   *
    * @param value The number to clamp.
-   * @returns The value clamped to [MIN_SAFE_INTEGER, MAX_SAFE_INTEGER] as a SafeInt.
+   * @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]
+   * The range is inclusive on both ends. If min > max, they are automatically
+   * swapped.
    *
    * @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));
+   * ```ts
+   * const min = asSafeInt(-10);
+   * const max = asSafeInt(10);
+   * const randomValue = SafeInt.random(min, max);
    *
-   * // Can use full safe range
-   * const any = SafeInt.random(SafeInt.MIN_VALUE, SafeInt.MAX_VALUE);
+   * assert.ok(SafeInt.is(randomValue));
+   * assert.ok(randomValue >= -10 && randomValue <= 10);
    * ```
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random SafeInt in the range [min, max]
    */
   random,
 
   /**
    * Raises a SafeInt to the power of another SafeInt.
+   *
+   * @example
+   *
+   * ```ts
+   * const base = asSafeInt(3);
+   * const exponent = asSafeInt(5);
+   * const power = SafeInt.pow(base, exponent);
+   *
+   * assert(power === 243);
+   * assert.ok(SafeInt.is(power));
+   * ```
+   *
    * @param a The base SafeInt.
    * @param b The exponent SafeInt.
    * @returns `a ** b` clamped to safe integer range as a SafeInt.
@@ -228,6 +241,16 @@ export const SafeInt = {
 
   /**
    * Adds two SafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const sum = SafeInt.add(asSafeInt(9), asSafeInt(4));
+   *
+   * assert(sum === 13);
+   * assert.ok(SafeInt.is(sum));
+   * ```
+   *
    * @param a The first SafeInt.
    * @param b The second SafeInt.
    * @returns `a + b` clamped to safe integer range as a SafeInt.
@@ -236,6 +259,16 @@ export const SafeInt = {
 
   /**
    * Subtracts one SafeInt from another.
+   *
+   * @example
+   *
+   * ```ts
+   * const difference = SafeInt.sub(asSafeInt(9), asSafeInt(14));
+   *
+   * assert(difference === -5);
+   * assert.ok(SafeInt.is(difference));
+   * ```
+   *
    * @param a The minuend SafeInt.
    * @param b The subtrahend SafeInt.
    * @returns `a - b` clamped to safe integer range as a SafeInt.
@@ -244,6 +277,16 @@ export const SafeInt = {
 
   /**
    * Multiplies two SafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const product = SafeInt.mul(asSafeInt(-8), asSafeInt(7));
+   *
+   * assert(product === -56);
+   * assert.ok(SafeInt.is(product));
+   * ```
+   *
    * @param a The first SafeInt.
    * @param b The second SafeInt.
    * @returns `a * b` clamped to safe integer range as a SafeInt.
@@ -253,23 +296,21 @@ export const SafeInt = {
   /**
    * Divides one SafeInt by another using floor division.
    *
-   * Performs mathematical floor division: `⌊a / b⌋`.
-   * The divisor must be non-zero (enforced by type constraints).
+   * Performs mathematical floor division: `⌊a / b⌋`. The divisor must be
+   * non-zero (enforced by type constraints).
+   *
+   * @example
+   *
+   * ```ts
+   * const quotient = SafeInt.div(asSafeInt(-17), asSafeInt(5));
+   *
+   * assert(quotient === -4);
+   * assert.ok(SafeInt.is(quotient));
+   * ```
    *
    * @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;