ts-data-forge 11.0.0 → 12.0.0

package/src/number/branded-types/non-zero-int32.mts

@@ -13,7 +13,7 @@ const {
   MIN_VALUE,
   abs,
   castType,
-  clamp,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -33,118 +33,122 @@ const {
 } as const);
 
 /**
- * Checks if a number is a NonZeroInt32 (32-bit non-zero signed integer in the
- * range [-2^31, 2^31) excluding 0).
+ * Type guard that checks if a value is a non-zero integer in [-2^31, 2^31).
  *
- * @param value The value to check.
- * @returns `true` if the value is a NonZeroInt32, `false` otherwise.
+ * Returns `true` for a non-zero integer in [-2^31, 2^31) — a value with no
+ * fractional component.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a non-zero integer in [-2^31, 2^31), `false` otherwise
  */
 export const isNonZeroInt32 = is;
 
 /**
- * Casts a number to a NonZeroInt32 type.
+ * Casts a `number` to the `NonZeroInt32` branded type.
+ *
+ * Validates that the value is a non-zero integer in [-2^31, 2^31) and returns
+ * it with the `NonZeroInt32` brand. Throws a `TypeError` otherwise.
  *
- * @param value The value to cast.
- * @returns The value as a NonZeroInt32 type.
- * @throws {TypeError} If the value is not a non-zero integer in [-2^31, 2^31).
+ * @param value - The value to cast
+ * @returns The value as a `NonZeroInt32`
+ * @throws {TypeError} If the value is not a non-zero integer in [-2^31, 2^31)
  */
 export const asNonZeroInt32 = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for 32-bit non-zero
- * signed integers.
+ * Namespace providing type-safe operations for the `NonZeroInt32` branded type.
  *
- * All operations automatically clamp results to the valid NonZeroInt32 range
- * [-2147483648, 2147483647] excluding 0. This ensures that all arithmetic
- * maintains the 32-bit non-zero signed integer constraint, preventing zero
- * results and overflow.
+ * The `NonZeroInt32` type represents a non-zero integer in [-2^31, 2^31).
+ * Division (`div`) uses floor division.
  */
 export const NonZeroInt32 = {
   /**
-   * Type guard to check if a value is a NonZeroInt32.
+   * Type guard that checks if a value is a non-zero integer in [-2^31, 2^31).
    *
-   * @param value The value to check.
-   * @returns `true` if the value is a 32-bit non-zero signed integer, `false`
-   *   otherwise.
+   * @param value - The value to check
+   * @returns `true` if the value is a non-zero integer in [-2^31, 2^31), `false` otherwise
+   * @see {@link isNonZeroInt32} for usage examples
    */
   is,
 
   /**
-   * The minimum value for a 32-bit non-zero signed integer.
-   *
-   * @readonly
+   * The smallest value representable as `NonZeroInt32` (the lower saturation
+   * target of `fromNumber`).
    */
   MIN_VALUE,
 
   /**
-   * The maximum value for a 32-bit non-zero signed integer.
-   *
-   * @readonly
+   * The largest value representable as `NonZeroInt32` (the upper saturation
+   * target of `fromNumber`).
    */
   MAX_VALUE,
 
   /**
-   * Returns the absolute value of a 32-bit non-zero signed integer.
+   * Returns the absolute value of a non-zero integer in [-2^31, 2^31).
    *
-   * @param a The NonZeroInt32 value.
-   * @returns The absolute value as a NonZeroInt32, clamped to valid range.
+   * The result is non-negative and keeps the `NonZeroInt32` brand.
+   *
+   * @param a - The non-zero integer value
+   * @returns The absolute value as a non-negative `NonZeroInt32`
    */
   abs,
 
   /**
-   * Returns the smaller of two NonZeroInt32 values.
+   * Returns the smallest of the given non-zero integers.
    *
-   * @param a The first NonZeroInt32.
-   * @param b The second NonZeroInt32.
-   * @returns The minimum value as a NonZeroInt32.
+   * @param values - The non-zero integers to compare (at least one required)
+   * @returns The smallest value as a `NonZeroInt32`
    */
   min: min_,
 
   /**
-   * Returns the larger of two NonZeroInt32 values.
+   * Returns the largest of the given non-zero integers.
    *
-   * @param a The first NonZeroInt32.
-   * @param b The second NonZeroInt32.
-   * @returns The maximum value as a NonZeroInt32.
+   * @param values - The non-zero integers to compare (at least one required)
+   * @returns The largest value as a `NonZeroInt32`
    */
   max: max_,
 
   /**
-   * Clamps a number to the NonZeroInt32 range (avoiding zero).
+   * Converts an arbitrary `number` into a `NonZeroInt32`, rounding to the
+   * nearest integer and saturating the result into the range `[MIN_VALUE,
+   * MAX_VALUE]`.
+   *
+   * Unlike `asNonZeroInt32`, this is total: out-of-range inputs are clamped to
+   * the nearest representable `NonZeroInt32` instead of throwing.
    *
-   * @param value The number to clamp.
-   * @returns The value clamped to [-2147483648, 2147483647] \ {0} as a
-   *   NonZeroInt32.
+   * @param value - The value to convert
+   * @returns The value as a `NonZeroInt32`
    */
-  clamp,
+  fromNumber,
 
   /**
-   * Generates a random NonZeroInt32 value within the valid range.
+   * Generates a random `NonZeroInt32` within the given range.
    *
-   * @returns A random NonZeroInt32 between MIN_VALUE and MAX_VALUE (excluding
-   *   0).
+   * The range is inclusive on both ends.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random `NonZeroInt32` in `[min, max]`
    */
   random,
 
   /**
-   * Raises a NonZeroInt32 to the power of another NonZeroInt32.
+   * Raises `a` to the power `b`, returning `a ** b` as a `NonZeroInt32`
+   * (floored to an integer).
    *
-   * @param a The base NonZeroInt32.
-   * @param b The exponent NonZeroInt32.
-   * @returns `a ** b` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
+   * @param a - The base non-zero integer
+   * @param b - The exponent non-zero integer
+   * @returns `a ** b` as a `NonZeroInt32`
    */
   pow,
 
   /**
-   * Multiplies two NonZeroInt32 values.
-   *
-   * The product of two non-zero integers is always non-zero, so this stays
-   * closed; for the non-closed operations (`add`/`sub`/`div`, whose result may
-   * be `0`) use {@link Num.add}/{@link Num.sub}/{@link Num.divInt}.
+   * Multiplies two non-zero integers, returning `a * b` as a `NonZeroInt32`.
    *
-   * @param a The first NonZeroInt32.
-   * @param b The second NonZeroInt32.
-   * @returns `a * b` clamped to [-2147483648, 2147483647] as a NonZeroInt32.
+   * @param a - The first non-zero integer
+   * @param b - The second non-zero integer
+   * @returns The product of `a` and `b` as a `NonZeroInt32`
    */
   mul,
 } as const;

package/src/number/branded-types/non-zero-safe-int.mts

@@ -17,7 +17,7 @@ const {
   MIN_VALUE,
   abs,
   castType,
-  clamp,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -39,119 +39,124 @@ const {
 } as const);
 
 /**
- * Checks if a number is a NonZeroSafeInt (a non-zero safe integer in the range
- * [MIN_SAFE_INTEGER, MAX_SAFE_INTEGER] excluding 0).
+ * Type guard that checks if a value is a non-zero safe integer.
  *
- * @param value The value to check.
- * @returns `true` if the value is a NonZeroSafeInt, `false` otherwise.
+ * Returns `true` for a non-zero safe integer — a value with no fractional
+ * component.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a non-zero safe integer, `false` otherwise
  */
 export const isNonZeroSafeInt = is;
 
 /**
- * Casts a number to a NonZeroSafeInt type.
+ * Casts a `number` to the `NonZeroSafeInt` branded type.
+ *
+ * Validates that the value is a non-zero safe integer and returns it with the
+ * `NonZeroSafeInt` brand. Throws a `TypeError` otherwise.
  *
- * @param value The value to cast.
- * @returns The value as a NonZeroSafeInt type.
- * @throws {TypeError} If the value is not a non-zero safe integer.
+ * @param value - The value to cast
+ * @returns The value as a `NonZeroSafeInt`
+ * @throws {TypeError} If the value is not a non-zero safe integer
  */
 export const asNonZeroSafeInt = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for non-zero safe
- * integers.
+ * Namespace providing type-safe operations for the `NonZeroSafeInt` branded
+ * type.
  *
- * All operations automatically clamp results to the non-zero safe integer
- * range, excluding zero. This ensures that all arithmetic maintains both the
- * non-zero constraint and IEEE 754 precision guarantees, preventing precision
- * loss while ensuring results are never zero.
+ * The `NonZeroSafeInt` type represents a non-zero safe integer. Division
+ * (`div`) uses floor division.
  */
 export const NonZeroSafeInt = {
   /**
-   * Type guard to check if a value is a NonZeroSafeInt.
+   * Type guard that checks if a value is a non-zero safe integer.
    *
-   * @param value The value to check.
-   * @returns `true` if the value is a non-zero safe integer, `false` otherwise.
+   * @param value - The value to check
+   * @returns `true` if the value is a non-zero safe integer, `false` otherwise
+   * @see {@link isNonZeroSafeInt} for usage examples
    */
   is,
 
   /**
-   * The minimum safe integer value (-(2^53 - 1)).
-   *
-   * @readonly
+   * The smallest value representable as `NonZeroSafeInt` (the lower saturation
+   * target of `fromNumber`).
    */
   MIN_VALUE,
 
   /**
-   * The maximum safe integer value (2^53 - 1).
-   *
-   * @readonly
+   * The largest value representable as `NonZeroSafeInt` (the upper saturation
+   * target of `fromNumber`).
    */
   MAX_VALUE,
 
   /**
    * Returns the absolute value of a non-zero safe integer.
    *
-   * @param a The NonZeroSafeInt value.
-   * @returns The absolute value as a NonZeroSafeInt, clamped to safe range.
+   * The result is non-negative and keeps the `NonZeroSafeInt` brand.
+   *
+   * @param a - The non-zero safe integer value
+   * @returns The absolute value as a non-negative `NonZeroSafeInt`
    */
   abs,
 
   /**
-   * Returns the smaller of two NonZeroSafeInt values.
+   * Returns the smallest of the given non-zero safe integers.
    *
-   * @param a The first NonZeroSafeInt.
-   * @param b The second NonZeroSafeInt.
-   * @returns The minimum value as a NonZeroSafeInt.
+   * @param values - The non-zero safe integers to compare (at least one required)
+   * @returns The smallest value as a `NonZeroSafeInt`
    */
   min: min_,
 
   /**
-   * Returns the larger of two NonZeroSafeInt values.
+   * Returns the largest of the given non-zero safe integers.
    *
-   * @param a The first NonZeroSafeInt.
-   * @param b The second NonZeroSafeInt.
-   * @returns The maximum value as a NonZeroSafeInt.
+   * @param values - The non-zero safe integers to compare (at least one required)
+   * @returns The largest value as a `NonZeroSafeInt`
    */
   max: max_,
 
   /**
-   * Clamps a number to the non-zero safe integer range.
+   * Converts an arbitrary `number` into a `NonZeroSafeInt`, rounding to the
+   * nearest integer and saturating the result into the range `[MIN_VALUE,
+   * MAX_VALUE]`.
+   *
+   * Unlike `asNonZeroSafeInt`, this is total: out-of-range inputs are clamped
+   * to the nearest representable `NonZeroSafeInt` instead of throwing.
    *
-   * @param value The number to clamp.
-   * @returns The value clamped to [MIN_SAFE_INTEGER, MAX_SAFE_INTEGER] \ {0} as
-   *   a NonZeroSafeInt.
+   * @param value - The value to convert
+   * @returns The value as a `NonZeroSafeInt`
    */
-  clamp,
+  fromNumber,
 
   /**
-   * Generates a random NonZeroSafeInt value within the valid range.
+   * Generates a random `NonZeroSafeInt` within the given range.
    *
-   * @returns A random non-zero safe integer between MIN_SAFE_INTEGER and
-   *   MAX_SAFE_INTEGER.
+   * The range is inclusive on both ends.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random `NonZeroSafeInt` in `[min, max]`
    */
   random,
 
   /**
-   * Raises a NonZeroSafeInt to the power of another NonZeroSafeInt.
+   * Raises `a` to the power `b`, returning `a ** b` as a `NonZeroSafeInt`
+   * (floored to an integer).
    *
-   * @param a The base NonZeroSafeInt.
-   * @param b The exponent NonZeroSafeInt.
-   * @returns `a ** b` clamped to non-zero safe integer range as a
-   *   NonZeroSafeInt.
+   * @param a - The base non-zero safe integer
+   * @param b - The exponent non-zero safe integer
+   * @returns `a ** b` as a `NonZeroSafeInt`
    */
   pow,
 
   /**
-   * Multiplies two NonZeroSafeInt values.
-   *
-   * The product of two non-zero safe integers is always non-zero, so this stays
-   * closed; for the non-closed operations (`add`/`sub`/`div`, whose result may
-   * be `0`) use {@link Num.add}/{@link Num.sub}/{@link Num.divInt}.
+   * Multiplies two non-zero safe integers, returning `a * b` as a
+   * `NonZeroSafeInt`.
    *
-   * @param a The first NonZeroSafeInt.
-   * @param b The second NonZeroSafeInt.
-   * @returns `a * b` clamped to non-zero safe integer range as a
-   *   NonZeroSafeInt.
+   * @param a - The first non-zero safe integer
+   * @param b - The second non-zero safe integer
+   * @returns The product of `a` and `b` as a `NonZeroSafeInt`
    */
   mul,
 } as const;

package/src/number/branded-types/non-zero-uint16.mts

@@ -13,7 +13,7 @@ const {
   MIN_VALUE,
   add,
   castType,
-  clamp,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -33,117 +33,122 @@ const {
 } as const);
 
 /**
- * Checks if a number is a NonZeroUint16 (16-bit non-zero unsigned integer in
- * the range [1, 2^16)).
+ * Type guard that checks if a value is a non-zero integer in [1, 2^16).
  *
- * @param value The value to check.
- * @returns `true` if the value is a NonZeroUint16, `false` otherwise.
+ * Returns `true` for a non-zero integer in [1, 2^16) — a value with no
+ * fractional component.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a non-zero integer in [1, 2^16), `false` otherwise
  */
 export const isNonZeroUint16 = is;
 
 /**
- * Casts a number to a NonZeroUint16 type.
+ * Casts a `number` to the `NonZeroUint16` branded type.
+ *
+ * Validates that the value is a non-zero integer in [1, 2^16) and returns it
+ * with the `NonZeroUint16` brand. Throws a `TypeError` otherwise.
  *
- * @param value The value to cast.
- * @returns The value as a NonZeroUint16 type.
- * @throws {TypeError} If the value is not a non-zero integer in [1, 2^16).
+ * @param value - The value to cast
+ * @returns The value as a `NonZeroUint16`
+ * @throws {TypeError} If the value is not a non-zero integer in [1, 2^16)
  */
 export const asNonZeroUint16 = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for 16-bit non-zero
- * unsigned integers.
+ * Namespace providing type-safe operations for the `NonZeroUint16` branded
+ * type.
  *
- * All operations automatically clamp results to the valid NonZeroUint16 range
- * [1, 65535]. This ensures that all arithmetic maintains the 16-bit non-zero
- * unsigned integer constraint, with results below 1 clamped to MIN_VALUE and
- * overflow results clamped to MAX_VALUE.
+ * The `NonZeroUint16` type represents a non-zero integer in [1, 2^16). Division
+ * (`div`) uses floor division.
  */
 export const NonZeroUint16 = {
   /**
-   * Type guard to check if a value is a NonZeroUint16.
+   * Type guard that checks if a value is a non-zero integer in [1, 2^16).
    *
-   * @param value The value to check.
-   * @returns `true` if the value is a 16-bit non-zero unsigned integer, `false`
-   *   otherwise.
+   * @param value - The value to check
+   * @returns `true` if the value is a non-zero integer in [1, 2^16), `false` otherwise
+   * @see {@link isNonZeroUint16} for usage examples
    */
   is,
 
   /**
-   * The minimum value for a 16-bit non-zero unsigned integer.
-   *
-   * @readonly
+   * The smallest value representable as `NonZeroUint16` (the lower saturation
+   * target of `fromNumber`).
    */
   MIN_VALUE,
 
   /**
-   * The maximum value for a 16-bit non-zero unsigned integer.
-   *
-   * @readonly
+   * The largest value representable as `NonZeroUint16` (the upper saturation
+   * target of `fromNumber`).
    */
   MAX_VALUE,
 
   /**
-   * Returns the smaller of two NonZeroUint16 values.
+   * Returns the smallest of the given non-zero integers.
    *
-   * @param a The first NonZeroUint16.
-   * @param b The second NonZeroUint16.
-   * @returns The minimum value as a NonZeroUint16.
+   * @param values - The non-zero integers to compare (at least one required)
+   * @returns The smallest value as a `NonZeroUint16`
    */
   min: min_,
 
   /**
-   * Returns the larger of two NonZeroUint16 values.
+   * Returns the largest of the given non-zero integers.
    *
-   * @param a The first NonZeroUint16.
-   * @param b The second NonZeroUint16.
-   * @returns The maximum value as a NonZeroUint16.
+   * @param values - The non-zero integers to compare (at least one required)
+   * @returns The largest value as a `NonZeroUint16`
    */
   max: max_,
 
   /**
-   * Clamps a number to the NonZeroUint16 range.
+   * Converts an arbitrary `number` into a `NonZeroUint16`, rounding to the
+   * nearest integer and saturating the result into the range `[MIN_VALUE,
+   * MAX_VALUE]`.
    *
-   * @param value The number to clamp.
-   * @returns The value clamped to [1, 65535] as a NonZeroUint16.
+   * Unlike `asNonZeroUint16`, this is total: out-of-range inputs are clamped to
+   * the nearest representable `NonZeroUint16` instead of throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as a `NonZeroUint16`
    */
-  clamp,
+  fromNumber,
 
   /**
-   * Generates a random NonZeroUint16 value within the valid range.
+   * Generates a random `NonZeroUint16` within the given range.
+   *
+   * The range is inclusive on both ends.
    *
-   * @returns A random NonZeroUint16 between 1 and 65535.
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive)
+   * @returns A random `NonZeroUint16` in `[min, max]`
    */
   random,
 
   /**
-   * Raises a NonZeroUint16 to the power of another NonZeroUint16.
+   * Raises `a` to the power `b`, returning `a ** b` as a `NonZeroUint16`
+   * (floored to an integer).
    *
-   * @param a The base NonZeroUint16.
-   * @param b The exponent NonZeroUint16.
-   * @returns `a ** b` clamped to [1, 65535] as a NonZeroUint16.
+   * @param a - The base non-zero integer
+   * @param b - The exponent non-zero integer
+   * @returns `a ** b` as a `NonZeroUint16`
    */
   pow,
 
   /**
-   * Adds two NonZeroUint16 values.
+   * Adds two non-zero integers, returning `a + b` as a `NonZeroUint16`.
    *
-   * @param a The first NonZeroUint16.
-   * @param b The second NonZeroUint16.
-   * @returns `a + b` clamped to [1, 65535] as a NonZeroUint16.
+   * @param a - The first non-zero integer
+   * @param b - The second non-zero integer
+   * @returns The sum of `a` and `b` as a `NonZeroUint16`
    */
   add,
 
   /**
-   * Multiplies two NonZeroUint16 values.
-   *
-   * Both `add` and `mul` stay within `[1, 65535]`. For the non-closed
-   * operations (`sub`/`div`, whose result may be `0`) use {@link Num.sub} /
-   * {@link Num.divInt}.
+   * Multiplies two non-zero integers, returning `a * b` as a `NonZeroUint16`.
    *
-   * @param a The first NonZeroUint16.
-   * @param b The second NonZeroUint16.
-   * @returns `a * b` clamped to [1, 65535] as a NonZeroUint16.
+   * @param a - The first non-zero integer
+   * @param b - The second non-zero integer
+   * @returns The product of `a` and `b` as a `NonZeroUint16`
    */
   mul,
 } as const;