ts-data-forge 3.3.0 → 3.3.1

package/dist/number/branded-types/safe-int.d.mts

@@ -5,41 +5,37 @@ import { TsDataForgeInternals } from '../refined-number-utils.mjs';
  * 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 declare const isSafeInt: (a: number) => a is SafeInt;
 /**
  * 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 declare const asSafeInt: <N extends number>(x: N) => number & {
     readonly NaNValue: false;
@@ -57,132 +53,149 @@ export declare const asSafeInt: <N extends number>(x: N) => number & {
  * 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 declare 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
      */
     readonly is: (a: number) => a is SafeInt;
     /**
      * The minimum safe integer value (-(2^53 - 1)).
+     *
      * @readonly
      */
     readonly MIN_VALUE: SafeInt;
     /**
      * The maximum safe integer value (2^53 - 1).
+     *
      * @readonly
      */
     readonly MAX_VALUE: SafeUint;
     /**
      * 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
      */
     readonly abs: (x: WithSmallInt<SafeInt, 40>) => TsDataForgeInternals.RefinedNumberUtils.ToNonNegative<SafeInt>;
     /**
      * 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
      */
     readonly min: (...values: readonly WithSmallInt<SafeInt, 40>[]) => SafeInt;
     /**
      * 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
      */
     readonly max: (...values: readonly WithSmallInt<SafeInt, 40>[]) => SafeInt;
     /**
      * 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.
      */
     readonly clamp: (x: number) => SafeInt;
     /**
      * 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]
      */
     readonly random: (min?: WithSmallInt<SafeInt, 40> | undefined, max?: WithSmallInt<SafeInt, 40> | undefined) => SafeInt;
     /**
      * 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.
@@ -190,6 +203,16 @@ export declare const SafeInt: {
     readonly pow: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => 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.
@@ -197,6 +220,16 @@ export declare const SafeInt: {
     readonly add: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => 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.
@@ -204,6 +237,16 @@ export declare const SafeInt: {
     readonly sub: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => 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.
@@ -212,23 +255,21 @@ export declare 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)
-     * ```
      */
     readonly div: (x: WithSmallInt<SafeInt, 40>, y: 1 | 2 | 3 | 32 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 10 | 24 | 14 | 34 | 12 | 13 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 33 | 35 | 36 | 37 | 38 | 39 | -1 | -2 | -3 | -32 | -4 | -5 | -6 | -7 | -8 | -9 | -11 | -10 | -24 | -14 | -34 | -12 | -13 | -15 | -16 | -17 | -18 | -19 | -20 | -21 | -22 | -23 | -25 | -26 | -27 | -28 | -29 | -30 | -31 | -33 | -35 | -36 | -37 | -38 | -39 | -40 | NormalizeBrandUnion<number & {
         readonly NaNValue: false;

package/dist/number/branded-types/safe-int.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/safe-int.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAkCnE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,6BAAK,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,SAAS;;;;;;;MAAW,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,OAAO;IAClB;;;;;;;OAOG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;OAIG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"safe-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/safe-int.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAkCnE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,6BAAK,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS;;;;;;;MAAW,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO;IAClB;;;;;;;;;;;;;;OAcG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;;;;;;;;;;;;;;;OAkBG;;IAGH;;;;;;;;;;;;;OAaG;;IAGH;;;;;;;;;;;;;OAaG;;IAGH;;;;;;;;;;;;;;;;;;OAkBG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;OAeG;;IAGH;;;;;;;;;;;;;;;;;;OAkBG;;;;;;;;;;CAEK,CAAC"}