ts-data-forge 1.0.0 → 1.0.2

package/dist/number/branded-types/positive-finite-number.mjs

@@ -0,0 +1,165 @@
+import { TsVerifiedInternals } from '../refined-number-utils.mjs';
+
+const typeNameInMessage = 'a positive finite number';
+const { MIN_VALUE, min: min_, max: max_, pow, add, sub, mul, div, random, is, castType, clamp, } = TsVerifiedInternals.RefinedNumberUtils.operatorsForFloat({
+    MIN_VALUE: Number.MIN_VALUE,
+    MAX_VALUE: undefined,
+    typeNameInMessage,
+});
+const floor = (x) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+Math.floor(x);
+const ceil = (x) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+Math.ceil(x);
+const round = (x) => 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+Math.round(x);
+/**
+ * Checks if a number is a PositiveFiniteNumber (a finite number > 0).
+ * @param value The value to check.
+ * @returns `true` if the value is a PositiveFiniteNumber, `false` otherwise.
+ */
+const isPositiveFiniteNumber = is;
+/**
+ * Casts a number to a PositiveFiniteNumber type.
+ * @param value The value to cast.
+ * @returns The value as a PositiveFiniteNumber type.
+ * @throws {TypeError} If the value is not a positive finite number.
+ * @example
+ * ```typescript
+ * const x = asPositiveFiniteNumber(5.5); // PositiveFiniteNumber
+ * const y = asPositiveFiniteNumber(0.001); // PositiveFiniteNumber
+ * // asPositiveFiniteNumber(0); // throws TypeError
+ * // asPositiveFiniteNumber(-1); // throws TypeError
+ * ```
+ */
+const asPositiveFiniteNumber = castType;
+/**
+ * Namespace providing type-safe arithmetic operations for positive finite numbers.
+ *
+ * All operations maintain the positive constraint by clamping non-positive results to MIN_VALUE,
+ * while ensuring results remain finite (excluding NaN and Infinity). This type is useful
+ * for representing quantities that must always be positive, such as probabilities, magnitudes,
+ * and physical measurements.
+ *
+ * @example
+ * ```typescript
+ * const probability = asPositiveFiniteNumber(0.75);
+ * const rate = asPositiveFiniteNumber(1.25);
+ *
+ * // Arithmetic operations with positive clamping
+ * const combined = PositiveFiniteNumber.add(probability, rate);        // PositiveFiniteNumber (2.0)
+ * const difference = PositiveFiniteNumber.sub(rate, probability);      // PositiveFiniteNumber (0.5)
+ * const scaled = PositiveFiniteNumber.mul(probability, rate);          // PositiveFiniteNumber (0.9375)
+ * const ratio = PositiveFiniteNumber.div(rate, probability);           // PositiveFiniteNumber (1.666...)
+ *
+ * // Range operations
+ * const clamped = PositiveFiniteNumber.clamp(-10.5);                  // PositiveFiniteNumber (MIN_VALUE)
+ * const minimum = PositiveFiniteNumber.min(probability, rate);         // PositiveFiniteNumber (0.75)
+ * const maximum = PositiveFiniteNumber.max(probability, rate);         // PositiveFiniteNumber (1.25)
+ *
+ * // Rounding operations (different return types based on operation)
+ * const ceiled = PositiveFiniteNumber.ceil(probability);              // PositiveInt (1)
+ * const floored = PositiveFiniteNumber.floor(rate);                   // Uint (1)
+ * const rounded = PositiveFiniteNumber.round(rate);                   // Uint (1)
+ *
+ * // Utility operations
+ * const random = PositiveFiniteNumber.random();                       // PositiveFiniteNumber (random positive value)
+ * const power = PositiveFiniteNumber.pow(rate, probability);          // PositiveFiniteNumber (1.18...)
+ * ```
+ */
+const PositiveFiniteNumber = {
+    /**
+     * Type guard to check if a value is a PositiveFiniteNumber.
+     * @param value The value to check.
+     * @returns `true` if the value is a positive finite number, `false` otherwise.
+     */
+    is,
+    /**
+     * The minimum value for a positive finite number.
+     * @readonly
+     */
+    MIN_VALUE,
+    /**
+     * Returns the smaller of two PositiveFiniteNumber values.
+     * @param a The first PositiveFiniteNumber.
+     * @param b The second PositiveFiniteNumber.
+     * @returns The minimum value as a PositiveFiniteNumber.
+     */
+    min: min_,
+    /**
+     * Returns the larger of two PositiveFiniteNumber values.
+     * @param a The first PositiveFiniteNumber.
+     * @param b The second PositiveFiniteNumber.
+     * @returns The maximum value as a PositiveFiniteNumber.
+     */
+    max: max_,
+    /**
+     * Clamps a number to the positive finite range.
+     * @param value The number to clamp.
+     * @returns The value clamped to (0, +∞) as a PositiveFiniteNumber.
+     */
+    clamp,
+    /**
+     * Rounds down a PositiveFiniteNumber to the nearest integer.
+     * @param x The PositiveFiniteNumber to round down.
+     * @returns The floor value as a Uint (can be 0).
+     */
+    floor,
+    /**
+     * Rounds up a PositiveFiniteNumber to the nearest integer.
+     * @param x The PositiveFiniteNumber to round up.
+     * @returns The ceiling value as a PositiveInt (always >= 1).
+     */
+    ceil,
+    /**
+     * Rounds a PositiveFiniteNumber to the nearest integer.
+     * @param x The PositiveFiniteNumber to round.
+     * @returns The rounded value as a Uint (can be 0 if x < 0.5).
+     */
+    round,
+    /**
+     * Generates a random PositiveFiniteNumber value.
+     * @returns A random positive finite number.
+     */
+    random,
+    /**
+     * Raises a PositiveFiniteNumber to the power of another PositiveFiniteNumber.
+     * @param a The base PositiveFiniteNumber.
+     * @param b The exponent PositiveFiniteNumber.
+     * @returns `a ** b` clamped to (0, +∞) as a PositiveFiniteNumber.
+     */
+    pow,
+    /**
+     * Adds two PositiveFiniteNumber values.
+     * @param a The first PositiveFiniteNumber.
+     * @param b The second PositiveFiniteNumber.
+     * @returns `a + b` clamped to (0, +∞) as a PositiveFiniteNumber.
+     */
+    add,
+    /**
+     * Subtracts one PositiveFiniteNumber from another.
+     * @param a The minuend PositiveFiniteNumber.
+     * @param b The subtrahend PositiveFiniteNumber.
+     * @returns `a - b` clamped to (0, +∞) as a PositiveFiniteNumber (minimum MIN_VALUE).
+     */
+    sub,
+    /**
+     * Multiplies two PositiveFiniteNumber values.
+     * @param a The first PositiveFiniteNumber.
+     * @param b The second PositiveFiniteNumber.
+     * @returns `a * b` clamped to (0, +∞) as a PositiveFiniteNumber.
+     */
+    mul,
+    /**
+     * Divides one PositiveFiniteNumber by another.
+     * @param a The dividend PositiveFiniteNumber.
+     * @param b The divisor PositiveFiniteNumber.
+     * @returns `a / b` clamped to (0, +∞) as a PositiveFiniteNumber.
+     */
+    div,
+};
+
+export { PositiveFiniteNumber, asPositiveFiniteNumber, isPositiveFiniteNumber };
+//# sourceMappingURL=positive-finite-number.mjs.map

package/dist/number/branded-types/positive-finite-number.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"positive-finite-number.mjs","sources":["../../../src/number/branded-types/positive-finite-number.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAKA,MAAM,iBAAiB,GAAG,0BAA0B;AAEpD,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,mBAAmB,CAAC,kBAAkB,CAAC,iBAAiB,CAI1D;IACA,SAAS,EAAE,MAAM,CAAC,SAAS;AAC3B,IAAA,SAAS,EAAE,SAAS;IACpB,iBAAiB;AACT,CAAA,CAAC;AAEX,MAAM,KAAK,GAAG,CACZ,CAAc;AAId;AACA,IAAI,CAAC,KAAK,CAAC,CAAC,CAEX;AAEH,MAAM,IAAI,GAAG,CACX,CAAc;AAEd;AACA,IAAI,CAAC,IAAI,CAAC,CAAC,CAA8D;AAE3E,MAAM,KAAK,GAAG,CACZ,CAAc;AAId;AACA,IAAI,CAAC,KAAK,CAAC,CAAC,CAEX;AAcH;;;;AAIG;AACI,MAAM,sBAAsB,GAAG;AAEtC;;;;;;;;;;;;AAYG;AACI,MAAM,sBAAsB,GAAG;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCG;AACI,MAAM,oBAAoB,GAAG;AAClC;;;;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;;;;AAIG;IACH,KAAK;AAEL;;;;AAIG;IACH,IAAI;AAEJ;;;;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;;;;;"}

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

@@ -0,0 +1,270 @@
+/**
+ * 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
+ *
+ * @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
+ * ```
+ */
+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
+ *
+ * @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
+ * ```
+ */
+export declare const asPositiveInt: <N extends number>(x: N) => 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<{
+    'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+}> & N;
+/**
+ * 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.
+ *
+ * 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.
+     *
+     * @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;
+    /**
+     * Returns the minimum value from a list of positive integers.
+     *
+     * 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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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
+     *
+     * @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)
+     * ```
+     */
+    readonly clamp: (x: number) => PositiveInt;
+    /**
+     * Generates a random positive integer within the specified range (inclusive).
+     *
+     * Both bounds are inclusive, and both min and max must be positive integers.
+     * If min > max, they are automatically swapped.
+     *
+     * @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]
+     *
+     * @example
+     * ```typescript
+     * // Dice roll
+     * const d6 = PositiveInt.random(asPositiveInt(1), asPositiveInt(6));
+     *
+     * // Random user ID
+     * const userId = PositiveInt.random(asPositiveInt(1000), asPositiveInt(9999));
+     *
+     * // Random page count
+     * const pages = PositiveInt.random(asPositiveInt(50), asPositiveInt(500));
+     * ```
+     */
+    readonly random: (min: WithSmallInt<PositiveInt, 40>, max: WithSmallInt<PositiveInt, 40>) => 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.
+     * @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;
+    /**
+     * Subtracts two positive integers, clamping the result to remain positive.
+     *
+     * If the mathematical result would be <= 0, it is clamped to 1 to maintain
+     * the positive integer constraint.
+     *
+     * @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.
+     * @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.
+     *
+     * 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.
+     *
+     * @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;
+        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<{
+        'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+    }>>) => PositiveInt;
+};
+//# sourceMappingURL=positive-int.d.mts.map

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

@@ -0,0 +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"}