ts-data-forge 3.3.0 → 4.0.0

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

@@ -6,42 +6,37 @@ import { TsDataForgeInternals } from '../refined-number-utils.mjs';
  * with no fractional component. This includes values outside the safe integer
  * range, unlike SafeInt.
  *
- * @param value - The value to check
- * @returns `true` if the value is an integer, `false` otherwise
- *
  * @example
- * ```typescript
- * isInt(5);        // true
- * isInt(-10);      // true
- * isInt(0);        // true
- * isInt(5.5);      // false
- * isInt(NaN);      // false
- * isInt(Infinity); // false
+ *
+ * ```ts
+ * assert.ok(isInt(5));
+ * assert.notOk(isInt(5.25));
+ * assert.ok(Int.is(-10));
  * ```
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is an integer, `false` otherwise
  */
 export declare const isInt: (a: number) => a is Int;
 /**
  * Casts a number to an Int branded type.
  *
- * This function validates that the input is an integer and returns it with
- * the Int brand. Throws a TypeError if the value has a fractional component
- * or is not a finite number.
- *
- * @param value - The value to cast
- * @returns The value as an Int branded type
- * @throws {TypeError} If the value is not an integer
+ * This function validates that the input is an integer and returns it with the
+ * Int brand. Throws a TypeError if the value has a fractional component or is
+ * not a finite number.
  *
  * @example
- * ```typescript
- * const x = asInt(5);    // Int
- * const y = asInt(-10);  // Int
- * const z = asInt(0);    // Int
  *
- * // These throw TypeError:
- * // asInt(5.5);         // Not an integer
- * // asInt(NaN);         // Not a number
- * // asInt(Infinity);    // Not finite
+ * ```ts
+ * const branded = asInt(42);
+ *
+ * assert(branded === 42);
+ * assert.ok(Int.is(branded));
  * ```
+ *
+ * @param value - The value to cast
+ * @returns The value as an Int branded type
+ * @throws {TypeError} If the value is not an integer
  */
 export declare const asInt: <N extends number>(x: N) => number & {
     readonly NaNValue: false;
@@ -57,178 +52,185 @@ export declare const asInt: <N extends number>(x: N) => number & {
  * range restrictions. All operations preserve the integer constraint, using
  * floor division for division operations.
  *
- * Unlike SafeInt, Int allows values outside the safe integer range
- * (±2^53 - 1), but be aware that very large integers may lose precision
- * in JavaScript's number type.
- *
- * @example
- * ```typescript
- * // Type validation
- * Int.is(42);      // true
- * Int.is(3.14);    // false
- * Int.is(-0);      // true (negative zero is an integer)
- *
- * // Basic arithmetic
- * const a = asInt(10);
- * const b = asInt(3);
- *
- * const sum = Int.add(a, b);      // Int (13)
- * const diff = Int.sub(a, b);     // Int (7)
- * const product = Int.mul(a, b);  // Int (30)
- * const quotient = Int.div(a, b); // Int (3) - floor division
- * const power = Int.pow(a, b);    // Int (1000)
- *
- * // Utility operations
- * const absolute = Int.abs(asInt(-42));    // Int (42)
- * const minimum = Int.min(a, b, asInt(5)); // Int (3)
- * const maximum = Int.max(a, b, asInt(5)); // Int (10)
- *
- * // Random generation
- * const die = Int.random(asInt(1), asInt(6)); // Random Int in [1, 6]
- * ```
+ * Unlike SafeInt, Int allows values outside the safe integer range (±2^53 - 1),
+ * but be aware that very large integers may lose precision in JavaScript's
+ * number type.
  */
 export declare const Int: {
     /**
      * Type guard that checks if a value is an integer.
      *
+     * @example
+     *
+     * ```ts
+     * assert.ok(isInt(5));
+     * assert.notOk(isInt(5.25));
+     * assert.ok(Int.is(-10));
+     * ```
+     *
      * @param value - The value to check
      * @returns `true` if the value is an integer, `false` otherwise
-     *
      * @see {@link isInt} for usage examples
      */
     readonly is: (a: number) => a is Int;
     /**
      * Returns the absolute value of an integer.
      *
-     * The result is always non-negative and maintains the Int brand.
-     * Note that Math.abs(Number.MIN_SAFE_INTEGER) exceeds Number.MAX_SAFE_INTEGER,
-     * so use SafeInt for guaranteed precision.
-     *
-     * @param a - The integer value
-     * @returns The absolute value as a non-negative Int
+     * The result is always non-negative and maintains the Int brand. Note that
+     * Math.abs(Number.MIN_SAFE_INTEGER) exceeds Number.MAX_SAFE_INTEGER, so use
+     * SafeInt for guaranteed precision.
      *
      * @example
-     * ```typescript
-     * Int.abs(asInt(-5));  // Int (5)
-     * Int.abs(asInt(3));   // Int (3)
-     * Int.abs(asInt(-0));  // Int (0)
+     *
+     * ```ts
+     * const negative = asInt(-12);
+     * const absolute = Int.abs(negative);
+     *
+     * assert(absolute === 12);
+     * assert.ok(Int.is(absolute));
      * ```
+     *
+     * @param a - The integer value
+     * @returns The absolute value as a non-negative Int
      */
     readonly abs: (x: WithSmallInt<Int, 40>) => TsDataForgeInternals.RefinedNumberUtils.ToNonNegative<Int>;
     /**
      * Returns the minimum value from a list of integers.
      *
-     * @param values - The integers to compare (at least one required)
-     * @returns The smallest value as an Int
-     *
      * @example
-     * ```typescript
-     * Int.min(asInt(5), asInt(3));           // Int (3)
-     * Int.min(asInt(-10), asInt(0), asInt(10)); // Int (-10)
+     *
+     * ```ts
+     * const smallest = Int.min(asInt(7), asInt(-3), asInt(2));
+     *
+     * assert(smallest === -3);
      * ```
+     *
+     * @param values - The integers to compare (at least one required)
+     * @returns The smallest value as an Int
      */
     readonly min: (...values: readonly WithSmallInt<Int, 40>[]) => Int;
     /**
      * Returns the maximum value from a list of integers.
      *
-     * @param values - The integers to compare (at least one required)
-     * @returns The largest value as an Int
-     *
      * @example
-     * ```typescript
-     * Int.max(asInt(5), asInt(3));           // Int (5)
-     * Int.max(asInt(-10), asInt(0), asInt(10)); // Int (10)
+     *
+     * ```ts
+     * const largest = Int.max(asInt(7), asInt(-3), asInt(2));
+     *
+     * assert(largest === 7);
      * ```
+     *
+     * @param values - The integers to compare (at least one required)
+     * @returns The largest value as an Int
      */
     readonly max: (...values: readonly WithSmallInt<Int, 40>[]) => Int;
     /**
      * Generates a random integer within the specified range (inclusive).
      *
-     * The range is inclusive on both ends, so random(1, 6) can return
-     * any of: 1, 2, 3, 4, 5, or 6.
-     *
-     * @param min - The minimum value (inclusive)
-     * @param max - The maximum value (inclusive)
-     * @returns A random Int in the range [min, max]
+     * The range is inclusive on both ends, so random(1, 6) can return any of: 1,
+     * 2, 3, 4, 5, or 6.
      *
      * @example
-     * ```typescript
-     * // Dice roll
-     * const d6 = Int.random(asInt(1), asInt(6));
      *
-     * // Random array index
-     * const index = Int.random(asInt(0), asInt(array.length - 1));
+     * ```ts
+     * const min = asInt(1);
+     * const max = asInt(6);
+     * const randomValue = Int.random(min, max);
      *
-     * // Can generate negative values
-     * const temp = Int.random(asInt(-10), asInt(10));
+     * assert.ok(Int.is(randomValue));
+     * assert.ok(randomValue >= 1 && randomValue <= 6);
      * ```
+     *
+     * @param min - The minimum value (inclusive)
+     * @param max - The maximum value (inclusive)
+     * @returns A random Int in the range [min, max]
      */
     readonly random: (min?: WithSmallInt<Int, 40> | undefined, max?: WithSmallInt<Int, 40> | undefined) => Int;
     /**
      * Raises an integer to a power.
+     *
+     * @example
+     *
+     * ```ts
+     * const base = asInt(2);
+     * const exponent = asInt(5);
+     * const power = Int.pow(base, exponent);
+     *
+     * assert(power === 32);
+     * ```
+     *
      * @param a - The base integer
      * @param b - The exponent integer
      * @returns `a ** b` as an Int
-     * @example
-     * ```typescript
-     * Int.pow(asInt(2), asInt(3)); // Int (8)
-     * ```
      */
     readonly pow: (x: WithSmallInt<Int, 40>, y: WithSmallInt<Int, 40>) => Int;
     /**
      * Adds two integers.
+     *
+     * @example
+     *
+     * ```ts
+     * const sum = Int.add(asInt(12), asInt(8));
+     *
+     * assert(sum === 20);
+     * ```
+     *
      * @param a - First integer
      * @param b - Second integer
      * @returns `a + b` as an Int
-     * @example
-     * ```typescript
-     * Int.add(asInt(5), asInt(3)); // Int (8)
-     * ```
      */
     readonly add: (x: WithSmallInt<Int, 40>, y: WithSmallInt<Int, 40>) => Int;
     /**
      * Subtracts two integers.
+     *
+     * @example
+     *
+     * ```ts
+     * const difference = Int.sub(asInt(12), asInt(8));
+     *
+     * assert(difference === 4);
+     * ```
+     *
      * @param a - First integer
      * @param b - Second integer
      * @returns `a - b` as an Int
-     * @example
-     * ```typescript
-     * Int.sub(asInt(8), asInt(3)); // Int (5)
-     * ```
      */
     readonly sub: (x: WithSmallInt<Int, 40>, y: WithSmallInt<Int, 40>) => Int;
     /**
      * Multiplies two integers.
+     *
+     * @example
+     *
+     * ```ts
+     * const product = Int.mul(asInt(-4), asInt(6));
+     *
+     * assert(product === -24);
+     * ```
+     *
      * @param a - First integer
      * @param b - Second integer
      * @returns `a * b` as an Int
-     * @example
-     * ```typescript
-     * Int.mul(asInt(4), asInt(3)); // Int (12)
-     * ```
      */
     readonly mul: (x: WithSmallInt<Int, 40>, y: WithSmallInt<Int, 40>) => Int;
     /**
      * Divides two integers using floor division.
      *
-     * Performs mathematical floor division: `⌊a / b⌋`.
-     * The result is always an integer, rounding toward negative infinity.
+     * Performs mathematical floor division: `⌊a / b⌋`. The result is always an
+     * integer, rounding toward negative infinity.
+     *
+     * @example
+     *
+     * ```ts
+     * const dividend = asInt(17);
+     * const divisor = asInt(5);
+     * const quotient = Int.div(dividend, divisor);
+     *
+     * assert(quotient === 3);
+     * ```
      *
      * @param a - The dividend
      * @param b - The divisor (must be non-zero)
      * @returns The integer quotient as an Int
-     *
-     * @example
-     * ```typescript
-     * // Positive division
-     * Int.div(asInt(10), asInt(3));   // Int (3)
-     * Int.div(asInt(9), asInt(3));    // Int (3)
-     *
-     * // Negative division (rounds toward -∞)
-     * Int.div(asInt(-10), asInt(3));  // Int (-4)
-     * Int.div(asInt(10), asInt(-3));  // Int (-4)
-     * Int.div(asInt(-10), asInt(-3)); // Int (3)
-     * ```
      */
     readonly div: (x: WithSmallInt<Int, 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/int.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AA6BnE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,KAAK,yBAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,KAAK;;;;;;MAAW,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,GAAG;IACd;;;;;;;OAOG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AA6BnE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,yBAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,KAAK;;;;;;MAAW,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG;IACd;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;;;;;OAmBG;;IAGH;;;;;;;;;;;;;OAaG;;IAGH;;;;;;;;;;;;;OAaG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;;;;;OAmBG;;;;;;;;;CAEK,CAAC"}