ts-data-forge 1.0.0 → 1.0.1

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

@@ -0,0 +1,243 @@
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+/**
+ * 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 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
+ *
+ * @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 declare const asSafeInt: <N extends number>(x: N) => number & {
+    readonly NaNValue: false;
+    readonly Finite: true;
+    readonly Int: true;
+    readonly SafeInt: true;
+} & Readonly<{
+    'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+}> & N;
+/**
+ * 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 declare 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
+     */
+    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
+     *
+     * @example
+     * ```typescript
+     * SafeInt.abs(asSafeInt(-42));    // SafeInt (42)
+     * SafeInt.abs(asSafeInt(42));     // SafeInt (42)
+     * SafeInt.abs(SafeInt.MIN_VALUE); // SafeInt (MAX_SAFE_INTEGER)
+     * ```
+     */
+    readonly abs: (x: WithSmallInt<SafeInt, 40>) => TsVerifiedInternals.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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    readonly max: (...values: readonly WithSmallInt<SafeInt, 40>[]) => SafeInt;
+    /**
+     * 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.
+     */
+    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]
+     *
+     * @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);
+     * ```
+     */
+    readonly random: (min: WithSmallInt<SafeInt, 40>, max: WithSmallInt<SafeInt, 40>) => SafeInt;
+    /**
+     * 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.
+     */
+    readonly pow: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => SafeInt;
+    /**
+     * 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.
+     */
+    readonly add: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => SafeInt;
+    /**
+     * 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.
+     */
+    readonly sub: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => SafeInt;
+    /**
+     * 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.
+     */
+    readonly mul: (x: WithSmallInt<SafeInt, 40>, y: WithSmallInt<SafeInt, 40>) => 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).
+     *
+     * @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;
+        readonly "!=0": true;
+        readonly Finite: true;
+        readonly Int: true;
+        readonly SafeInt: true;
+    } & Readonly<{
+        'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+    }>>) => SafeInt;
+};
+//# sourceMappingURL=safe-int.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safe-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/safe-int.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAkClE;;;;;;;;;;;;;;;;;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"}

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

@@ -0,0 +1,240 @@
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+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({
+    integerOrSafeInteger: 'SafeInteger',
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    MIN_VALUE: Number.MIN_SAFE_INTEGER,
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    MAX_VALUE: Number.MAX_SAFE_INTEGER,
+    typeNameInMessage,
+});
+/**
+ * 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
+ * ```
+ */
+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
+ * ```
+ */
+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
+ * ```
+ */
+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,
+};
+
+export { SafeInt, asSafeInt, isSafeInt };
+//# sourceMappingURL=safe-int.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safe-int.mjs","sources":["../../../src/number/branded-types/safe-int.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,gBAAgB;AAE1C,MAAM,EACJ,SAAS,EACT,SAAS,EACT,GAAG,EACH,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,mBAAmB,CAAC,kBAAkB,CAAC,mBAAmB,CAI5D;AACA,IAAA,oBAAoB,EAAE,aAAa;;IAEnC,SAAS,EAAE,MAAM,CAAC,gBAA2B;;IAE7C,SAAS,EAAE,MAAM,CAAC,gBAA4B;IAC9C,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;;;;;;;;;;AAiBG;AACI,MAAM,SAAS,GAAG;AAEzB;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACI,MAAM,SAAS,GAAG;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCG;AACI,MAAM,OAAO,GAAG;AACrB;;;;;;;AAOG;IACH,EAAE;AAEF;;;AAGG;IACH,SAAS;AAET;;;AAGG;IACH,SAAS;AAET;;;;;;;;;;;;;;;AAeG;IACH,GAAG;AAEH;;;;;;;;;;;AAWG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;;;;;;AAWG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;AAIG;IACH,KAAK;AAEL;;;;;;;;;;;;;;;;;;;;AAoBG;IACH,MAAM;AAEN;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;AAKG;IACH,GAAG;AAEH;;;;;;;;;;;;;;;;;;;;AAoBG;IACH,GAAG;;;;;"}

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

@@ -0,0 +1,151 @@
+/**
+ * Checks if a number is a SafeUint.
+ * @param value The value to check.
+ * @returns `true` if the value is a SafeUint, `false` otherwise.
+ */
+export declare const isSafeUint: (a: number) => a is SafeUint;
+/**
+ * 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
+ * ```
+ */
+export declare const asSafeUint: <N extends number>(x: N) => number & {
+    readonly NaNValue: false;
+    readonly "> -2^16": true;
+    readonly "> -2^32": true;
+    readonly ">= -2^15": true;
+    readonly ">= -2^31": true;
+    readonly ">=0": true;
+    readonly Finite: true;
+    readonly Int: true;
+    readonly SafeInt: true;
+} & Readonly<{
+    'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+}> & N;
+/**
+ * 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)
+ *
+ * // Utility operations
+ * const random = SafeUint.random();            // SafeUint (random safe unsigned integer)
+ * const power = SafeUint.pow(asSafeUint(2), asSafeUint(20)); // SafeUint (1048576)
+ * ```
+ */
+export declare 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.
+     */
+    readonly is: (a: number) => a is SafeUint;
+    /**
+     * The minimum value for a safe unsigned integer.
+     * @readonly
+     */
+    readonly MIN_VALUE: 0;
+    /**
+     * The maximum safe integer value (2^53 - 1).
+     * @readonly
+     */
+    readonly MAX_VALUE: SafeUint;
+    /**
+     * Returns the smaller of two SafeUint values.
+     * @param a The first SafeUint.
+     * @param b The second SafeUint.
+     * @returns The minimum value as a SafeUint.
+     */
+    readonly min: (...values: readonly WithSmallInt<SafeUint, 40>[]) => SafeUint;
+    /**
+     * Returns the larger of two SafeUint values.
+     * @param a The first SafeUint.
+     * @param b The second SafeUint.
+     * @returns The maximum value as a SafeUint.
+     */
+    readonly max: (...values: readonly WithSmallInt<SafeUint, 40>[]) => SafeUint;
+    /**
+     * 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.
+     */
+    readonly clamp: (x: number) => SafeUint;
+    /**
+     * Generates a random SafeUint value within the valid range.
+     * @returns A random SafeUint between 0 and MAX_SAFE_INTEGER.
+     */
+    readonly random: (min: WithSmallInt<SafeUint, 40>, max: WithSmallInt<SafeUint, 40>) => SafeUint;
+    /**
+     * 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.
+     */
+    readonly pow: (x: WithSmallInt<SafeUint, 40>, y: WithSmallInt<SafeUint, 40>) => SafeUint;
+    /**
+     * 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.
+     */
+    readonly add: (x: WithSmallInt<SafeUint, 40>, y: WithSmallInt<SafeUint, 40>) => SafeUint;
+    /**
+     * 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).
+     */
+    readonly sub: (x: WithSmallInt<SafeUint, 40>, y: WithSmallInt<SafeUint, 40>) => SafeUint;
+    /**
+     * 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.
+     */
+    readonly mul: (x: WithSmallInt<SafeUint, 40>, y: WithSmallInt<SafeUint, 40>) => SafeUint;
+    /**
+     * 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.
+     */
+    readonly div: (x: WithSmallInt<SafeUint, 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 | NormalizeBrandUnion<number & {
+        readonly NaNValue: false;
+        readonly "!=0": true;
+        readonly "> -2^16": true;
+        readonly "> -2^32": true;
+        readonly ">= -2^15": true;
+        readonly ">= -2^31": true;
+        readonly ">=0": true;
+        readonly Finite: true;
+        readonly Int: true;
+        readonly SafeInt: true;
+    } & Readonly<{
+        'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+    }>>) => SafeUint;
+};
+//# sourceMappingURL=safe-uint.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"safe-uint.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/safe-uint.mts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,eAAO,MAAM,UAAU,8BAAK,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;MAAW,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ;IACnB;;;;OAIG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;;;;;;;;;;;;;;CAEK,CAAC"}