ts-data-forge 3.3.0 → 4.0.0

package/dist/number/branded-types/safe-uint.mjs

@@ -1,79 +1,61 @@
 import { TsDataForgeInternals } from '../refined-number-utils.mjs';
 
 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, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
+const { MAX_VALUE, MIN_VALUE, add, castType, clamp, div, is, max: max_, min: min_, mul, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
     integerOrSafeInteger: 'SafeInteger',
     MIN_VALUE: 0,
-    // 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,
     typeNameInMessage,
 });
 /**
  * Checks if a number is a SafeUint.
+ *
  * @param value The value to check.
  * @returns `true` if the value is a SafeUint, `false` otherwise.
  */
 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
- * ```
  */
 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)
+ * Namespace providing type-safe arithmetic operations for safe unsigned
+ * integers.
  *
- * // Utility operations
- * const random = SafeUint.random();            // SafeUint (random safe unsigned integer)
- * const power = SafeUint.pow(asSafeUint(2), asSafeUint(20)); // SafeUint (1048576)
- * ```
+ * 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.
  */
 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.
+     * @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.
@@ -81,6 +63,7 @@ const 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.
@@ -88,17 +71,20 @@ const 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.
@@ -106,6 +92,7 @@ const 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.
@@ -113,13 +100,16 @@ const 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).
+     * @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.
@@ -127,6 +117,7 @@ const 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.

package/dist/number/branded-types/safe-uint.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"safe-uint.mjs","sources":["../../../src/number/branded-types/safe-uint.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,6BAA6B;AAEvD,MAAM,EACJ,SAAS,EACT,SAAS,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,MAAM,EACN,EAAE,EACF,QAAQ,EACR,KAAK,GACN,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,aAAa;AACnC,IAAA,SAAS,EAAE,CAAC;;IAEZ,SAAS,EAAE,MAAM,CAAC,gBAA4B;IAC9C,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;AAIG;AACI,MAAM,UAAU,GAAG;AAE1B;;;;;;;;;;;;AAYG;AACI,MAAM,UAAU,GAAG;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,QAAQ,GAAG;AACtB;;;;AAIG;IACH,EAAE;AAEF;;;AAGG;IACH,SAAS;AAET;;;AAGG;IACH,SAAS;AAET;;;;;AAKG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;AAKG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;AAIG;IACH,KAAK;AAEL;;;AAGG;IACH,MAAM;AAEN;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;;;;;"}
+{"version":3,"file":"safe-uint.mjs","sources":["../../../src/number/branded-types/safe-uint.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,6BAA6B;AAEvD,MAAM,EACJ,SAAS,EACT,SAAS,EACT,GAAG,EACH,QAAQ,EACR,KAAK,EACL,GAAG,EACH,EAAE,EACF,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,GAAG,EACH,MAAM,EACN,GAAG,GACJ,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,aAAa;AACnC,IAAA,SAAS,EAAE,CAAC;;IAEZ,SAAS,EAAE,MAAM,CAAC,gBAA4B;IAC9C,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;AAKG;AACI,MAAM,UAAU,GAAG;AAE1B;;;;;;AAMG;AACI,MAAM,UAAU,GAAG;AAE1B;;;;;;;;AAQG;AACI,MAAM,QAAQ,GAAG;AACtB;;;;;;AAMG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;AAIG;IACH,SAAS;AAET;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;AAKG;IACH,KAAK;AAEL;;;;AAIG;IACH,MAAM;AAEN;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;;AAOG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;;;;;"}

package/dist/number/branded-types/uint.d.mts

@@ -1,21 +1,33 @@
 /**
  * Checks if a number is a Uint.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.ok(isUint(4));
+ * assert.notOk(isUint(-1));
+ * assert.ok(Uint.is(0));
+ * ```
+ *
  * @param value The value to check.
  * @returns `true` if the value is a Uint, `false` otherwise.
  */
 export declare const isUint: (a: number) => a is NonNegativeInt;
 /**
  * Casts a number to a Uint type.
+ *
+ * @example
+ *
+ * ```ts
+ * const branded = asUint(12);
+ *
+ * assert(branded === 12);
+ * assert.ok(Uint.is(branded));
+ * ```
+ *
  * @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 declare const asUint: <N extends number>(x: N) => number & {
     readonly NaNValue: false;
@@ -32,44 +44,44 @@ export declare const asUint: <N extends number>(x: N) => number & {
 /**
  * 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)
- * ```
+ * All operations maintain the non-negative constraint by clamping negative
+ * results to 0. This ensures that all arithmetic preserves the unsigned integer
+ * property.
  */
 export declare const Uint: {
     /**
      * Type guard to check if a value is a Uint.
+     *
+     * @example
+     *
+     * ```ts
+     * assert.ok(isUint(4));
+     * assert.notOk(isUint(-1));
+     * assert.ok(Uint.is(0));
+     * ```
+     *
      * @param value The value to check.
      * @returns `true` if the value is a non-negative integer, `false` otherwise.
+     * @see {@link isUint} for usage examples
      */
     readonly is: (a: number) => a is NonNegativeInt;
     /**
      * The minimum value for an unsigned integer.
+     *
      * @readonly
      */
     readonly MIN_VALUE: 0;
     /**
      * Returns the smaller of two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const smallest = Uint.min(asUint(7), asUint(3));
+     *
+     * assert(smallest === 3);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns The minimum value as a Uint.
@@ -77,6 +89,15 @@ export declare const Uint: {
     readonly min: (...values: readonly WithSmallInt<NonNegativeInt, 40>[]) => NonNegativeInt;
     /**
      * Returns the larger of two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const largest = Uint.max(asUint(7), asUint(3));
+     *
+     * assert(largest === 7);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns The maximum value as a Uint.
@@ -84,17 +105,51 @@ export declare const Uint: {
     readonly max: (...values: readonly WithSmallInt<NonNegativeInt, 40>[]) => NonNegativeInt;
     /**
      * Clamps a number to the Uint range (non-negative).
+     *
+     * @example
+     *
+     * ```ts
+     * const clampedNegative = Uint.clamp(-5);
+     * const clampedPositive = Uint.clamp(42);
+     *
+     * assert(clampedNegative === 0);
+     * assert(clampedPositive === 42);
+     * ```
+     *
      * @param value The number to clamp.
      * @returns The value clamped to [0, +∞) as a Uint.
      */
     readonly clamp: (x: number) => NonNegativeInt;
     /**
      * Generates a random Uint value.
+     *
+     * @example
+     *
+     * ```ts
+     * const min = asUint(0);
+     * const max = asUint(3);
+     * const randomValue = Uint.random(min, max);
+     *
+     * assert.ok(Uint.is(randomValue));
+     * assert.ok(randomValue >= 0 && randomValue <= 3);
+     * ```
+     *
      * @returns A random non-negative integer as a Uint.
      */
     readonly random: (min?: WithSmallInt<NonNegativeInt, 40> | undefined, max?: WithSmallInt<NonNegativeInt, 40> | undefined) => NonNegativeInt;
     /**
      * Raises a Uint to the power of another Uint.
+     *
+     * @example
+     *
+     * ```ts
+     * const base = asUint(2);
+     * const exponent = asUint(5);
+     * const power = Uint.pow(base, exponent);
+     *
+     * assert(power === 32);
+     * ```
+     *
      * @param a The base Uint.
      * @param b The exponent Uint.
      * @returns `a ** b` clamped to [0, +∞) as a Uint.
@@ -102,6 +157,15 @@ export declare const Uint: {
     readonly pow: (x: WithSmallInt<NonNegativeInt, 40>, y: WithSmallInt<NonNegativeInt, 40>) => NonNegativeInt;
     /**
      * Adds two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const sum = Uint.add(asUint(5), asUint(8));
+     *
+     * assert(sum === 13);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns `a + b` clamped to [0, +∞) as a Uint.
@@ -109,6 +173,15 @@ export declare const Uint: {
     readonly add: (x: WithSmallInt<NonNegativeInt, 40>, y: WithSmallInt<NonNegativeInt, 40>) => NonNegativeInt;
     /**
      * Subtracts one Uint from another.
+     *
+     * @example
+     *
+     * ```ts
+     * const difference = Uint.sub(asUint(5), asUint(8));
+     *
+     * assert(difference === 0);
+     * ```
+     *
      * @param a The minuend Uint.
      * @param b The subtrahend Uint.
      * @returns `a - b` clamped to [0, +∞) as a Uint (minimum 0).
@@ -116,6 +189,15 @@ export declare const Uint: {
     readonly sub: (x: WithSmallInt<NonNegativeInt, 40>, y: WithSmallInt<NonNegativeInt, 40>) => NonNegativeInt;
     /**
      * Multiplies two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const product = Uint.mul(asUint(7), asUint(6));
+     *
+     * assert(product === 42);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns `a * b` clamped to [0, +∞) as a Uint.
@@ -123,6 +205,15 @@ export declare const Uint: {
     readonly mul: (x: WithSmallInt<NonNegativeInt, 40>, y: WithSmallInt<NonNegativeInt, 40>) => NonNegativeInt;
     /**
      * Divides one Uint by another using floor division.
+     *
+     * @example
+     *
+     * ```ts
+     * const quotient = Uint.div(asUint(10), asUint(4));
+     *
+     * assert(quotient === 2);
+     * ```
+     *
      * @param a The dividend Uint.
      * @param b The divisor Uint.
      * @returns `⌊a / b⌋` clamped to [0, +∞) as a Uint.

package/dist/number/branded-types/uint.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"uint.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/uint.mts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,eAAO,MAAM,MAAM,oCAAK,CAAC;AAEzB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;MAAW,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,IAAI;IACf;;;;OAIG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;;;;;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"uint.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/uint.mts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,oCAAK,CAAC;AAEzB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;MAAW,CAAC;AAE/B;;;;;;GAMG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;OAcG;;IAGH;;;;OAIG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;;;;;;;;;;;;;CAEK,CAAC"}

package/dist/number/branded-types/uint.mjs

@@ -1,7 +1,7 @@
 import { TsDataForgeInternals } from '../refined-number-utils.mjs';
 
 const typeNameInMessage = 'a non-negative integer';
-const { MIN_VALUE, min: min_, max: max_, pow, add, sub, mul, div, random, is, castType, clamp, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
+const { MIN_VALUE, add, castType, clamp, div, is, max: max_, min: min_, mul, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
     integerOrSafeInteger: 'Integer',
     MIN_VALUE: 0,
     MAX_VALUE: Number.MAX_VALUE,
@@ -9,65 +9,77 @@ const { MIN_VALUE, min: min_, max: max_, pow, add, sub, mul, div, random, is, ca
 });
 /**
  * Checks if a number is a Uint.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.ok(isUint(4));
+ * assert.notOk(isUint(-1));
+ * assert.ok(Uint.is(0));
+ * ```
+ *
  * @param value The value to check.
  * @returns `true` if the value is a Uint, `false` otherwise.
  */
 const isUint = is;
 /**
  * Casts a number to a Uint type.
+ *
+ * @example
+ *
+ * ```ts
+ * const branded = asUint(12);
+ *
+ * assert(branded === 12);
+ * assert.ok(Uint.is(branded));
+ * ```
+ *
  * @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
- * ```
  */
 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)
- * ```
+ * All operations maintain the non-negative constraint by clamping negative
+ * results to 0. This ensures that all arithmetic preserves the unsigned integer
+ * property.
  */
 const Uint = {
     /**
      * Type guard to check if a value is a Uint.
+     *
+     * @example
+     *
+     * ```ts
+     * assert.ok(isUint(4));
+     * assert.notOk(isUint(-1));
+     * assert.ok(Uint.is(0));
+     * ```
+     *
      * @param value The value to check.
      * @returns `true` if the value is a non-negative integer, `false` otherwise.
+     * @see {@link isUint} for usage examples
      */
     is,
     /**
      * The minimum value for an unsigned integer.
+     *
      * @readonly
      */
     MIN_VALUE,
     /**
      * Returns the smaller of two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const smallest = Uint.min(asUint(7), asUint(3));
+     *
+     * assert(smallest === 3);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns The minimum value as a Uint.
@@ -75,6 +87,15 @@ const Uint = {
     min: min_,
     /**
      * Returns the larger of two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const largest = Uint.max(asUint(7), asUint(3));
+     *
+     * assert(largest === 7);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns The maximum value as a Uint.
@@ -82,17 +103,51 @@ const Uint = {
     max: max_,
     /**
      * Clamps a number to the Uint range (non-negative).
+     *
+     * @example
+     *
+     * ```ts
+     * const clampedNegative = Uint.clamp(-5);
+     * const clampedPositive = Uint.clamp(42);
+     *
+     * assert(clampedNegative === 0);
+     * assert(clampedPositive === 42);
+     * ```
+     *
      * @param value The number to clamp.
      * @returns The value clamped to [0, +∞) as a Uint.
      */
     clamp,
     /**
      * Generates a random Uint value.
+     *
+     * @example
+     *
+     * ```ts
+     * const min = asUint(0);
+     * const max = asUint(3);
+     * const randomValue = Uint.random(min, max);
+     *
+     * assert.ok(Uint.is(randomValue));
+     * assert.ok(randomValue >= 0 && randomValue <= 3);
+     * ```
+     *
      * @returns A random non-negative integer as a Uint.
      */
     random,
     /**
      * Raises a Uint to the power of another Uint.
+     *
+     * @example
+     *
+     * ```ts
+     * const base = asUint(2);
+     * const exponent = asUint(5);
+     * const power = Uint.pow(base, exponent);
+     *
+     * assert(power === 32);
+     * ```
+     *
      * @param a The base Uint.
      * @param b The exponent Uint.
      * @returns `a ** b` clamped to [0, +∞) as a Uint.
@@ -100,6 +155,15 @@ const Uint = {
     pow,
     /**
      * Adds two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const sum = Uint.add(asUint(5), asUint(8));
+     *
+     * assert(sum === 13);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns `a + b` clamped to [0, +∞) as a Uint.
@@ -107,6 +171,15 @@ const Uint = {
     add,
     /**
      * Subtracts one Uint from another.
+     *
+     * @example
+     *
+     * ```ts
+     * const difference = Uint.sub(asUint(5), asUint(8));
+     *
+     * assert(difference === 0);
+     * ```
+     *
      * @param a The minuend Uint.
      * @param b The subtrahend Uint.
      * @returns `a - b` clamped to [0, +∞) as a Uint (minimum 0).
@@ -114,6 +187,15 @@ const Uint = {
     sub,
     /**
      * Multiplies two Uint values.
+     *
+     * @example
+     *
+     * ```ts
+     * const product = Uint.mul(asUint(7), asUint(6));
+     *
+     * assert(product === 42);
+     * ```
+     *
      * @param a The first Uint.
      * @param b The second Uint.
      * @returns `a * b` clamped to [0, +∞) as a Uint.
@@ -121,6 +203,15 @@ const Uint = {
     mul,
     /**
      * Divides one Uint by another using floor division.
+     *
+     * @example
+     *
+     * ```ts
+     * const quotient = Uint.div(asUint(10), asUint(4));
+     *
+     * assert(quotient === 2);
+     * ```
+     *
      * @param a The dividend Uint.
      * @param b The divisor Uint.
      * @returns `⌊a / b⌋` clamped to [0, +∞) as a Uint.

package/dist/number/branded-types/uint.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"uint.mjs","sources":["../../../src/number/branded-types/uint.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,wBAAwB;AAElD,MAAM,EACJ,SAAS,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,GAAG,EACH,MAAM,EACN,EAAE,EACF,QAAQ,EACR,KAAK,GACN,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,SAAS;AAC/B,IAAA,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;AAIG;AACI,MAAM,MAAM,GAAG;AAEtB;;;;;;;;;;;;AAYG;AACI,MAAM,MAAM,GAAG;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;AACI,MAAM,IAAI,GAAG;AAClB;;;;AAIG;IACH,EAAE;AAEF;;;AAGG;IACH,SAAS;AAET;;;;;AAKG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;AAKG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;AAIG;IACH,KAAK;AAEL;;;AAGG;IACH,MAAM;AAEN;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;;;;;"}
+{"version":3,"file":"uint.mjs","sources":["../../../src/number/branded-types/uint.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,wBAAwB;AAElD,MAAM,EACJ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,KAAK,EACL,GAAG,EACH,EAAE,EACF,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,GAAG,EACH,MAAM,EACN,GAAG,GACJ,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,SAAS;AAC/B,IAAA,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;;;;;;AAaG;AACI,MAAM,MAAM,GAAG;AAEtB;;;;;;;;;;;;;;;AAeG;AACI,MAAM,MAAM,GAAG;AAEtB;;;;;;AAMG;AACI,MAAM,IAAI,GAAG;AAClB;;;;;;;;;;;;;;AAcG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;;;;;;;;;;;AAcG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;;;;;;;;;AAcG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;;;;;;;;;;AAeG;IACH,KAAK;AAEL;;;;;;;;;;;;;;;AAeG;IACH,MAAM;AAEN;;;;;;;;;;;;;;;;AAgBG;IACH,GAAG;AAEH;;;;;;;;;;;;;;AAcG;IACH,GAAG;AAEH;;;;;;;;;;;;;;AAcG;IACH,GAAG;AAEH;;;;;;;;;;;;;;AAcG;IACH,GAAG;AAEH;;;;;;;;;;;;;;AAcG;IACH,GAAG;;;;;"}