ts-data-forge 3.2.0 → 3.3.1

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

@@ -1,46 +1,40 @@
 /**
  * Type guard that checks if a value is a positive integer.
  *
- * A positive integer is any integer greater than zero (>= 1).
- * This excludes zero, negative numbers, and non-integers.
- *
- * @param value - The value to check
- * @returns `true` if the value is a positive integer, `false` otherwise
+ * A positive integer is any integer greater than zero (>= 1). This excludes
+ * zero, negative numbers, and non-integers.
  *
  * @example
- * ```typescript
- * isPositiveInt(5);    // true
- * isPositiveInt(1);    // true
- * isPositiveInt(0);    // false (zero is not positive)
- * isPositiveInt(-1);   // false (negative)
- * isPositiveInt(5.5);  // false (not an integer)
- * isPositiveInt(NaN);  // false
+ *
+ * ```ts
+ * assert.ok(isPositiveInt(5));
+ * assert.notOk(isPositiveInt(0));
+ * assert.ok(PositiveInt.is(10));
  * ```
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a positive integer, `false` otherwise
  */
 export declare const isPositiveInt: (a: number) => a is PositiveInt;
 /**
  * Casts a number to a PositiveInt branded type.
  *
- * This function validates that the input is a positive integer (>= 1)
- * and returns it with the PositiveInt brand. This ensures type safety
- * for operations that require strictly positive integer values.
- *
- * @param value - The value to cast
- * @returns The value as a PositiveInt branded type
- * @throws {TypeError} If the value is not a positive integer
+ * This function validates that the input is a positive integer (>= 1) and
+ * returns it with the PositiveInt brand. This ensures type safety for
+ * operations that require strictly positive integer values.
  *
  * @example
- * ```typescript
- * const count = asPositiveInt(5);      // PositiveInt
- * const length = asPositiveInt(100);   // PositiveInt
- * const one = asPositiveInt(1);        // PositiveInt (minimum valid)
  *
- * // These throw TypeError:
- * // asPositiveInt(0);                 // Zero is not positive
- * // asPositiveInt(-1);                // Negative numbers not allowed
- * // asPositiveInt(5.5);               // Not an integer
- * // asPositiveInt(Infinity);          // Not finite
+ * ```ts
+ * const branded = asPositiveInt(7);
+ *
+ * assert(branded === 7);
+ * assert.ok(PositiveInt.is(branded));
  * ```
+ *
+ * @param value - The value to cast
+ * @returns The value as a PositiveInt branded type
+ * @throws {TypeError} If the value is not a positive integer
  */
 export declare const asPositiveInt: <N extends number>(x: N) => number & {
     readonly NaNValue: false;
@@ -59,58 +53,38 @@ export declare const asPositiveInt: <N extends number>(x: N) => number & {
  * Namespace providing type-safe operations for PositiveInt branded types.
  *
  * PositiveInt represents integers that are strictly greater than zero (>= 1).
- * All operations automatically clamp results to maintain the positive constraint,
- * ensuring that arithmetic operations never produce zero or negative values.
+ * All operations automatically clamp results to maintain the positive
+ * constraint, ensuring that arithmetic operations never produce zero or
+ * negative values.
  *
  * This type is essential for:
+ *
  * - Array lengths and sizes (length >= 1)
  * - Counts and quantities that must be positive
  * - Denominators in division operations
  * - Loop counters and iteration counts
  * - Database primary keys and IDs
- *
- * @example
- * ```typescript
- * // Type validation
- * PositiveInt.is(5);    // true
- * PositiveInt.is(1);    // true (minimum value)
- * PositiveInt.is(0);    // false
- * PositiveInt.is(-1);   // false
- *
- * // Automatic clamping in operations
- * const a = asPositiveInt(10);
- * const b = asPositiveInt(3);
- *
- * const sum = PositiveInt.add(a, b);          // PositiveInt (13)
- * const diff1 = PositiveInt.sub(a, b);        // PositiveInt (7)
- * const diff2 = PositiveInt.sub(b, a);        // PositiveInt (1) - clamped!
- * const product = PositiveInt.mul(a, b);      // PositiveInt (30)
- * const quotient = PositiveInt.div(a, b);     // PositiveInt (3)
- *
- * // Edge case: division that would be < 1
- * const small = PositiveInt.div(asPositiveInt(2), asPositiveInt(3)); // PositiveInt (1)
- *
- * // Range operations
- * const minimum = PositiveInt.min(a, b);      // PositiveInt (3)
- * const maximum = PositiveInt.max(a, b);      // PositiveInt (10)
- *
- * // Random generation
- * const dice = PositiveInt.random(asPositiveInt(1), asPositiveInt(6)); // 1-6
- * const id = PositiveInt.random(asPositiveInt(1000), asPositiveInt(9999)); // 4-digit ID
- * ```
  */
 export declare const PositiveInt: {
     /**
      * Type guard that checks if a value is a positive integer.
      *
+     * @example
+     *
+     * ```ts
+     * assert.ok(isPositiveInt(5));
+     * assert.notOk(isPositiveInt(0));
+     * assert.ok(PositiveInt.is(10));
+     * ```
+     *
      * @param value - The value to check
      * @returns `true` if the value is a positive integer, `false` otherwise
-     *
      * @see {@link isPositiveInt} for usage examples
      */
     readonly is: (a: number) => a is PositiveInt;
     /**
      * The minimum value for a PositiveInt.
+     *
      * @readonly
      */
     readonly MIN_VALUE: 1;
@@ -120,45 +94,59 @@ export declare const PositiveInt: {
      * Since all inputs are guaranteed to be >= 1, the result is also guaranteed
      * to be a positive integer.
      *
-     * @param values - The positive integers to compare (at least one required)
-     * @returns The smallest value as a PositiveInt
-     *
      * @example
-     * ```typescript
-     * PositiveInt.min(asPositiveInt(5), asPositiveInt(3));    // PositiveInt (3)
-     * PositiveInt.min(asPositiveInt(10), asPositiveInt(1), asPositiveInt(7)); // PositiveInt (1)
+     *
+     * ```ts
+     * const smallest = PositiveInt.min(
+     *   asPositiveInt(9),
+     *   asPositiveInt(3),
+     *   asPositiveInt(12),
+     * );
+     *
+     * assert(smallest === 3);
      * ```
+     *
+     * @param values - The positive integers to compare (at least one required)
+     * @returns The smallest value as a PositiveInt
      */
     readonly min: (...values: readonly WithSmallInt<PositiveInt, 40>[]) => PositiveInt;
     /**
      * Returns the maximum value from a list of positive integers.
      *
-     * @param values - The positive integers to compare (at least one required)
-     * @returns The largest value as a PositiveInt
-     *
      * @example
-     * ```typescript
-     * PositiveInt.max(asPositiveInt(5), asPositiveInt(3));    // PositiveInt (5)
-     * PositiveInt.max(asPositiveInt(10), asPositiveInt(1), asPositiveInt(7)); // PositiveInt (10)
+     *
+     * ```ts
+     * const largest = PositiveInt.max(
+     *   asPositiveInt(9),
+     *   asPositiveInt(3),
+     *   asPositiveInt(12),
+     * );
+     *
+     * assert(largest === 12);
      * ```
+     *
+     * @param values - The positive integers to compare (at least one required)
+     * @returns The largest value as a PositiveInt
      */
     readonly max: (...values: readonly WithSmallInt<PositiveInt, 40>[]) => PositiveInt;
     /**
      * Clamps a number to the positive integer range.
      *
-     * Since PositiveInt has a minimum value of 1, this function ensures
-     * that any input less than 1 is clamped to 1.
-     *
-     * @param value - The number to clamp
-     * @returns The value clamped to >= 1 as a PositiveInt
+     * Since PositiveInt has a minimum value of 1, this function ensures that any
+     * input less than 1 is clamped to 1.
      *
      * @example
-     * ```typescript
-     * PositiveInt.clamp(5);    // PositiveInt (5)
-     * PositiveInt.clamp(0);    // PositiveInt (1) - clamped to minimum
-     * PositiveInt.clamp(-10);  // PositiveInt (1) - clamped to minimum
-     * PositiveInt.clamp(100);  // PositiveInt (100)
+     *
+     * ```ts
+     * const belowRange = PositiveInt.clamp(0);
+     * const withinRange = PositiveInt.clamp(10);
+     *
+     * assert(belowRange === 1);
+     * assert(withinRange === 10);
      * ```
+     *
+     * @param value - The number to clamp
+     * @returns The value clamped to >= 1 as a PositiveInt
      */
     readonly clamp: (x: number) => PositiveInt;
     /**
@@ -167,43 +155,55 @@ export declare const PositiveInt: {
      * Both bounds are inclusive, and both min and max must be positive integers.
      * If min > max, they are automatically swapped.
      *
+     * @example
+     *
+     * ```ts
+     * const min = asPositiveInt(3);
+     * const max = asPositiveInt(6);
+     * const randomValue = PositiveInt.random(min, max);
+     *
+     * assert.ok(PositiveInt.is(randomValue));
+     * assert.ok(randomValue >= 3 && randomValue <= 6);
+     * ```
+     *
      * @param min - The minimum value (inclusive, must be >= 1)
      * @param max - The maximum value (inclusive, must be >= min)
      * @returns A random PositiveInt in the range [min, max]
+     */
+    readonly random: (min?: WithSmallInt<PositiveInt, 40> | undefined, max?: WithSmallInt<PositiveInt, 40> | undefined) => PositiveInt;
+    /**
+     * Raises a positive integer to a power, ensuring the result is never less
+     * than 1.
      *
      * @example
-     * ```typescript
-     * // Dice roll
-     * const d6 = PositiveInt.random(asPositiveInt(1), asPositiveInt(6));
      *
-     * // Random user ID
-     * const userId = PositiveInt.random(asPositiveInt(1000), asPositiveInt(9999));
+     * ```ts
+     * const base = asPositiveInt(2);
+     * const exponent = asPositiveInt(4);
+     * const power = PositiveInt.pow(base, exponent);
      *
-     * // Random page count
-     * const pages = PositiveInt.random(asPositiveInt(50), asPositiveInt(500));
+     * assert(power === 16);
      * ```
-     */
-    readonly random: (min?: WithSmallInt<PositiveInt, 40> | undefined, max?: WithSmallInt<PositiveInt, 40> | undefined) => PositiveInt;
-    /**
-     * Raises a positive integer to a power, ensuring the result is never less than 1.
+     *
      * @param a - The base positive integer
      * @param b - The exponent positive integer
      * @returns `a ** b` as a PositiveInt, but never less than 1
-     * @example
-     * ```typescript
-     * PositiveInt.pow(asPositiveInt(2), asPositiveInt(3)); // PositiveInt (8)
-     * ```
      */
     readonly pow: (x: WithSmallInt<PositiveInt, 40>, y: WithSmallInt<PositiveInt, 40>) => PositiveInt;
     /**
      * Adds two positive integers, ensuring the result is never less than 1.
+     *
+     * @example
+     *
+     * ```ts
+     * const sum = PositiveInt.add(asPositiveInt(4), asPositiveInt(5));
+     *
+     * assert(sum === 9);
+     * ```
+     *
      * @param a - First positive integer
      * @param b - Second positive integer
      * @returns `a + b` as a PositiveInt, but never less than 1
-     * @example
-     * ```typescript
-     * PositiveInt.add(asPositiveInt(5), asPositiveInt(3)); // PositiveInt (8)
-     * ```
      */
     readonly add: (x: WithSmallInt<PositiveInt, 40>, y: WithSmallInt<PositiveInt, 40>) => PositiveInt;
     /**
@@ -212,46 +212,56 @@ export declare const PositiveInt: {
      * If the mathematical result would be <= 0, it is clamped to 1 to maintain
      * the positive integer constraint.
      *
+     * @example
+     *
+     * ```ts
+     * const difference = PositiveInt.sub(asPositiveInt(5), asPositiveInt(7));
+     *
+     * assert(difference === 1);
+     * ```
+     *
      * @param a - The minuend (positive integer)
      * @param b - The subtrahend (positive integer)
      * @returns `max(1, a - b)` as a PositiveInt
-     *
-     * @example
-     * ```typescript
-     * PositiveInt.sub(asPositiveInt(8), asPositiveInt(3));  // PositiveInt (5)
-     * PositiveInt.sub(asPositiveInt(3), asPositiveInt(8));  // PositiveInt (1) - clamped
-     * PositiveInt.sub(asPositiveInt(5), asPositiveInt(5));  // PositiveInt (1) - clamped
-     * ```
      */
     readonly sub: (x: WithSmallInt<PositiveInt, 40>, y: WithSmallInt<PositiveInt, 40>) => PositiveInt;
     /**
      * Multiplies two positive integers, ensuring the result is never less than 1.
+     *
+     * @example
+     *
+     * ```ts
+     * const product = PositiveInt.mul(asPositiveInt(3), asPositiveInt(7));
+     *
+     * assert(product === 21);
+     * ```
+     *
      * @param a - First positive integer
      * @param b - Second positive integer
      * @returns `a * b` as a PositiveInt, but never less than 1
-     * @example
-     * ```typescript
-     * PositiveInt.mul(asPositiveInt(4), asPositiveInt(3)); // PositiveInt (12)
-     * ```
      */
     readonly mul: (x: WithSmallInt<PositiveInt, 40>, y: WithSmallInt<PositiveInt, 40>) => PositiveInt;
     /**
-     * Divides two positive integers using floor division, clamping to remain positive.
+     * Divides two positive integers using floor division, clamping to remain
+     * positive.
      *
      * Performs mathematical floor division: `⌊a / b⌋`. If the result would be 0
-     * (when a < b), it is clamped to 1 to maintain the positive integer constraint.
+     * (when a < b), it is clamped to 1 to maintain the positive integer
+     * constraint.
+     *
+     * @example
+     *
+     * ```ts
+     * const quotient = PositiveInt.div(asPositiveInt(9), asPositiveInt(2));
+     * const clamped = PositiveInt.div(asPositiveInt(3), asPositiveInt(10));
+     *
+     * assert(quotient === 4);
+     * assert(clamped === 1);
+     * ```
      *
      * @param a - The dividend (positive integer)
      * @param b - The divisor (positive integer, guaranteed non-zero)
      * @returns `max(1, ⌊a / b⌋)` as a PositiveInt
-     *
-     * @example
-     * ```typescript
-     * PositiveInt.div(asPositiveInt(10), asPositiveInt(3)); // PositiveInt (3)
-     * PositiveInt.div(asPositiveInt(9), asPositiveInt(3));  // PositiveInt (3)
-     * PositiveInt.div(asPositiveInt(2), asPositiveInt(3));  // PositiveInt (1) - clamped
-     * PositiveInt.div(asPositiveInt(1), asPositiveInt(5));  // PositiveInt (1) - clamped
-     * ```
      */
     readonly div: (x: WithSmallInt<PositiveInt, 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;

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

@@ -1 +1 @@
-{"version":3,"file":"positive-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/positive-int.mts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,iCAAK,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;MAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;;OAOG;;IAGH;;;OAGG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;OAWG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;;;;;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"positive-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/positive-int.mts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,iCAAK,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;MAAW,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;;;;;;;;;OAcG;;IAGH;;;;OAIG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;;;;OAkBG;;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;;;;;;;OAqBG;;;;;;;;;;;;;;CAEK,CAAC"}