ts-data-forge 3.3.0 → 3.3.1

package/src/number/branded-types/positive-safe-int.mts

@@ -26,13 +26,24 @@ const {
 >({
   integerOrSafeInteger: 'SafeInteger',
   MIN_VALUE: 1,
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
   MAX_VALUE: Number.MAX_SAFE_INTEGER as SafeUint,
   typeNameInMessage,
 } as const);
 
 /**
- * Checks if a number is a PositiveSafeInt (a positive safe integer in the range [1, MAX_SAFE_INTEGER]).
+ * Checks if a number is a PositiveSafeInt (a positive safe integer in the range
+ * [1, MAX_SAFE_INTEGER]).
+ *
+ * @example
+ *
+ * ```ts
+ * assert.ok(isPositiveSafeInt(1));
+ * assert.ok(isPositiveSafeInt(Number.MAX_SAFE_INTEGER));
+ * assert.notOk(isPositiveSafeInt(0));
+ * assert.ok(PositiveSafeInt.is(42));
+ * ```
+ *
  * @param value The value to check.
  * @returns `true` if the value is a PositiveSafeInt, `false` otherwise.
  */
@@ -40,68 +51,78 @@ export const isPositiveSafeInt = is;
 
 /**
  * Casts a number to a PositiveSafeInt type.
+ *
+ * @example
+ *
+ * ```ts
+ * const branded = asPositiveSafeInt(128);
+ *
+ * assert(branded === 128);
+ * assert.ok(PositiveSafeInt.is(branded));
+ * ```
+ *
  * @param value The value to cast.
  * @returns The value as a PositiveSafeInt type.
  * @throws {TypeError} If the value is not a positive safe integer.
- * @example
- * ```typescript
- * const x = asPositiveSafeInt(5); // PositiveSafeInt
- * const y = asPositiveSafeInt(1000); // PositiveSafeInt
- * // asPositiveSafeInt(0); // throws TypeError
- * // asPositiveSafeInt(-1); // throws TypeError
- * ```
  */
 export const asPositiveSafeInt = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for positive safe integers.
+ * Namespace providing type-safe arithmetic operations for positive safe
+ * integers.
  *
- * All operations automatically clamp results to the positive safe integer range [1, MAX_SAFE_INTEGER].
- * This ensures that all arithmetic maintains both the positive constraint and IEEE 754 precision guarantees,
- * preventing precision loss and ensuring results are always positive.
- *
- * @example
- * ```typescript
- * const a = asPositiveSafeInt(1000000);
- * const b = asPositiveSafeInt(2000000);
- *
- * // Arithmetic operations with positive safe range clamping
- * const sum = PositiveSafeInt.add(a, b);          // PositiveSafeInt (3000000)
- * const diff = PositiveSafeInt.sub(a, b);         // PositiveSafeInt (1 - clamped to MIN_VALUE)
- * const product = PositiveSafeInt.mul(a, b);      // PositiveSafeInt (2000000000000)
- *
- * // Range operations
- * const clamped = PositiveSafeInt.clamp(0);           // PositiveSafeInt (1)
- * const minimum = PositiveSafeInt.min(a, b);          // PositiveSafeInt (1000000)
- * const maximum = PositiveSafeInt.max(a, b);          // PositiveSafeInt (2000000)
- *
- * // Utility operations
- * const random = PositiveSafeInt.random();            // PositiveSafeInt (random positive safe integer)
- * const power = PositiveSafeInt.pow(asPositiveSafeInt(2), asPositiveSafeInt(10)); // PositiveSafeInt (1024)
- * ```
+ * All operations automatically clamp results to the positive safe integer range
+ * [1, MAX_SAFE_INTEGER]. This ensures that all arithmetic maintains both the
+ * positive constraint and IEEE 754 precision guarantees, preventing precision
+ * loss and ensuring results are always positive.
  */
 export const PositiveSafeInt = {
   /**
    * Type guard to check if a value is a PositiveSafeInt.
+   *
+   * @example
+   *
+   * ```ts
+   * assert.ok(isPositiveSafeInt(1));
+   * assert.ok(isPositiveSafeInt(Number.MAX_SAFE_INTEGER));
+   * assert.notOk(isPositiveSafeInt(0));
+   * assert.ok(PositiveSafeInt.is(42));
+   * ```
+   *
    * @param value The value to check.
    * @returns `true` if the value is a positive safe integer, `false` otherwise.
+   * @see {@link isPositiveSafeInt} for usage examples
    */
   is,
 
   /**
    * The minimum value for a positive safe integer.
+   *
    * @readonly
    */
   MIN_VALUE,
 
   /**
    * The maximum safe integer value (2^53 - 1).
+   *
    * @readonly
    */
   MAX_VALUE,
 
   /**
    * Returns the smaller of two PositiveSafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const smallest = PositiveSafeInt.min(
+   *   asPositiveSafeInt(10),
+   *   asPositiveSafeInt(5),
+   * );
+   *
+   * assert(smallest === 5);
+   * ```
+   *
    * @param a The first PositiveSafeInt.
    * @param b The second PositiveSafeInt.
    * @returns The minimum value as a PositiveSafeInt.
@@ -110,6 +131,18 @@ export const PositiveSafeInt = {
 
   /**
    * Returns the larger of two PositiveSafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const largest = PositiveSafeInt.max(
+   *   asPositiveSafeInt(10),
+   *   asPositiveSafeInt(5),
+   * );
+   *
+   * assert(largest === 10);
+   * ```
+   *
    * @param a The first PositiveSafeInt.
    * @param b The second PositiveSafeInt.
    * @returns The maximum value as a PositiveSafeInt.
@@ -118,6 +151,19 @@ export const PositiveSafeInt = {
 
   /**
    * Clamps a number to the positive safe integer range.
+   *
+   * @example
+   *
+   * ```ts
+   * const belowRange = PositiveSafeInt.clamp(0);
+   * const withinRange = PositiveSafeInt.clamp(123);
+   * const aboveRange = PositiveSafeInt.clamp(Number.MAX_SAFE_INTEGER + 10);
+   *
+   * assert(belowRange === 1);
+   * assert(withinRange === 123);
+   * assert(aboveRange === Number.MAX_SAFE_INTEGER);
+   * ```
+   *
    * @param value The number to clamp.
    * @returns The value clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
    */
@@ -125,12 +171,35 @@ export const PositiveSafeInt = {
 
   /**
    * Generates a random PositiveSafeInt value within the valid range.
+   *
+   * @example
+   *
+   * ```ts
+   * const min = asPositiveSafeInt(1);
+   * const max = asPositiveSafeInt(6);
+   * const randomValue = PositiveSafeInt.random(min, max);
+   *
+   * assert.ok(PositiveSafeInt.is(randomValue));
+   * assert.ok(randomValue >= 1 && randomValue <= 6);
+   * ```
+   *
    * @returns A random PositiveSafeInt between 1 and MAX_SAFE_INTEGER.
    */
   random,
 
   /**
    * Raises a PositiveSafeInt to the power of another PositiveSafeInt.
+   *
+   * @example
+   *
+   * ```ts
+   * const base = asPositiveSafeInt(3);
+   * const exponent = asPositiveSafeInt(3);
+   * const power = PositiveSafeInt.pow(base, exponent);
+   *
+   * assert(power === 27);
+   * ```
+   *
    * @param a The base PositiveSafeInt.
    * @param b The exponent PositiveSafeInt.
    * @returns `a ** b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
@@ -139,6 +208,19 @@ export const PositiveSafeInt = {
 
   /**
    * Adds two PositiveSafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const sum = PositiveSafeInt.add(
+   *   asPositiveSafeInt(1000),
+   *   asPositiveSafeInt(2048),
+   * );
+   *
+   * assert(sum === 3048);
+   * assert.ok(PositiveSafeInt.is(sum));
+   * ```
+   *
    * @param a The first PositiveSafeInt.
    * @param b The second PositiveSafeInt.
    * @returns `a + b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
@@ -147,14 +229,41 @@ export const PositiveSafeInt = {
 
   /**
    * Subtracts one PositiveSafeInt from another.
+   *
+   * @example
+   *
+   * ```ts
+   * const difference = PositiveSafeInt.sub(
+   *   asPositiveSafeInt(10),
+   *   asPositiveSafeInt(20),
+   * );
+   *
+   * assert(difference === 1);
+   * assert.ok(PositiveSafeInt.is(difference));
+   * ```
+   *
    * @param a The minuend PositiveSafeInt.
    * @param b The subtrahend PositiveSafeInt.
-   * @returns `a - b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt (minimum 1).
+   * @returns `a - b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt
+   *   (minimum 1).
    */
   sub,
 
   /**
    * Multiplies two PositiveSafeInt values.
+   *
+   * @example
+   *
+   * ```ts
+   * const product = PositiveSafeInt.mul(
+   *   asPositiveSafeInt(50),
+   *   asPositiveSafeInt(20),
+   * );
+   *
+   * assert(product === 1000);
+   * assert.ok(PositiveSafeInt.is(product));
+   * ```
+   *
    * @param a The first PositiveSafeInt.
    * @param b The second PositiveSafeInt.
    * @returns `a * b` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.
@@ -163,6 +272,23 @@ export const PositiveSafeInt = {
 
   /**
    * Divides one PositiveSafeInt by another using floor division.
+   *
+   * @example
+   *
+   * ```ts
+   * const quotient = PositiveSafeInt.div(
+   *   asPositiveSafeInt(25),
+   *   asPositiveSafeInt(4),
+   * );
+   * const clamped = PositiveSafeInt.div(
+   *   asPositiveSafeInt(5),
+   *   asPositiveSafeInt(50),
+   * );
+   *
+   * assert(quotient === 6);
+   * assert(clamped === 1);
+   * ```
+   *
    * @param a The dividend PositiveSafeInt.
    * @param b The divisor PositiveSafeInt.
    * @returns `⌊a / b⌋` clamped to [1, MAX_SAFE_INTEGER] as a PositiveSafeInt.

package/src/number/branded-types/positive-uint16.mts

@@ -31,7 +31,9 @@ const {
 } as const);
 
 /**
- * Checks if a number is a PositiveUint16 (16-bit positive unsigned integer in the range [1, 2^16)).
+ * Checks if a number is a PositiveUint16 (16-bit positive unsigned integer in
+ * the range [1, 2^16)).
+ *
  * @param value The value to check.
  * @returns `true` if the value is a PositiveUint16, `false` otherwise.
  */
@@ -39,70 +41,49 @@ export const isPositiveUint16 = is;
 
 /**
  * Casts a number to a PositiveUint16 type.
+ *
  * @param value The value to cast.
  * @returns The value as a PositiveUint16 type.
  * @throws {TypeError} If the value is not a positive integer in [1, 2^16).
- * @example
- * ```typescript
- * const x = asPositiveUint16(1000); // PositiveUint16
- * const y = asPositiveUint16(65535); // PositiveUint16
- * // asPositiveUint16(0); // throws TypeError
- * // asPositiveUint16(-1); // throws TypeError
- * // asPositiveUint16(65536); // throws TypeError
- * ```
  */
 export const asPositiveUint16 = castType;
 
 /**
- * Namespace providing type-safe arithmetic operations for 16-bit positive unsigned integers.
- *
- * All operations automatically clamp results to the valid PositiveUint16 range [1, 65535].
- * This ensures that all arithmetic maintains the 16-bit positive unsigned integer constraint,
- * with results below 1 clamped to MIN_VALUE and overflow results clamped to MAX_VALUE.
- *
- * @example
- * ```typescript
- * const a = asPositiveUint16(60000);
- * const b = asPositiveUint16(10000);
- *
- * // Arithmetic operations with automatic clamping and positive constraint
- * const sum = PositiveUint16.add(a, b);       // PositiveUint16 (65535 - clamped to MAX_VALUE)
- * const diff = PositiveUint16.sub(a, b);      // PositiveUint16 (50000)
- * const reverseDiff = PositiveUint16.sub(b, a); // PositiveUint16 (1 - clamped to MIN_VALUE)
- * const product = PositiveUint16.mul(a, b);   // PositiveUint16 (65535 - clamped due to overflow)
- *
- * // Range operations (maintaining positive constraint)
- * const clamped = PositiveUint16.clamp(-100);     // PositiveUint16 (1)
- * const minimum = PositiveUint16.min(a, b);       // PositiveUint16 (10000)
- * const maximum = PositiveUint16.max(a, b);       // PositiveUint16 (60000)
+ * Namespace providing type-safe arithmetic operations for 16-bit positive
+ * unsigned integers.
  *
- * // Utility operations
- * const random = PositiveUint16.random();         // PositiveUint16 (random value in [1, 65535])
- * const power = PositiveUint16.pow(asPositiveUint16(2), asPositiveUint16(10)); // PositiveUint16 (1024)
- * ```
+ * All operations automatically clamp results to the valid PositiveUint16 range
+ * [1, 65535]. This ensures that all arithmetic maintains the 16-bit positive
+ * unsigned integer constraint, with results below 1 clamped to MIN_VALUE and
+ * overflow results clamped to MAX_VALUE.
  */
 export const PositiveUint16 = {
   /**
    * Type guard to check if a value is a PositiveUint16.
+   *
    * @param value The value to check.
-   * @returns `true` if the value is a 16-bit positive unsigned integer, `false` otherwise.
+   * @returns `true` if the value is a 16-bit positive unsigned integer, `false`
+   *   otherwise.
    */
   is,
 
   /**
    * The minimum value for a 16-bit positive unsigned integer.
+   *
    * @readonly
    */
   MIN_VALUE,
 
   /**
    * The maximum value for a 16-bit positive unsigned integer.
+   *
    * @readonly
    */
   MAX_VALUE,
 
   /**
    * Returns the smaller of two PositiveUint16 values.
+   *
    * @param a The first PositiveUint16.
    * @param b The second PositiveUint16.
    * @returns The minimum value as a PositiveUint16.
@@ -111,6 +92,7 @@ export const PositiveUint16 = {
 
   /**
    * Returns the larger of two PositiveUint16 values.
+   *
    * @param a The first PositiveUint16.
    * @param b The second PositiveUint16.
    * @returns The maximum value as a PositiveUint16.
@@ -119,6 +101,7 @@ export const PositiveUint16 = {
 
   /**
    * Clamps a number to the PositiveUint16 range.
+   *
    * @param value The number to clamp.
    * @returns The value clamped to [1, 65535] as a PositiveUint16.
    */
@@ -126,12 +109,14 @@ export const PositiveUint16 = {
 
   /**
    * Generates a random PositiveUint16 value within the valid range.
+   *
    * @returns A random PositiveUint16 between 1 and 65535.
    */
   random,
 
   /**
    * Raises a PositiveUint16 to the power of another PositiveUint16.
+   *
    * @param a The base PositiveUint16.
    * @param b The exponent PositiveUint16.
    * @returns `a ** b` clamped to [1, 65535] as a PositiveUint16.
@@ -140,6 +125,7 @@ export const PositiveUint16 = {
 
   /**
    * Adds two PositiveUint16 values.
+   *
    * @param a The first PositiveUint16.
    * @param b The second PositiveUint16.
    * @returns `a + b` clamped to [1, 65535] as a PositiveUint16.
@@ -148,6 +134,7 @@ export const PositiveUint16 = {
 
   /**
    * Subtracts one PositiveUint16 from another.
+   *
    * @param a The minuend PositiveUint16.
    * @param b The subtrahend PositiveUint16.
    * @returns `a - b` clamped to [1, 65535] as a PositiveUint16 (minimum 1).
@@ -156,6 +143,7 @@ export const PositiveUint16 = {
 
   /**
    * Multiplies two PositiveUint16 values.
+   *
    * @param a The first PositiveUint16.
    * @param b The second PositiveUint16.
    * @returns `a * b` clamped to [1, 65535] as a PositiveUint16.
@@ -164,6 +152,7 @@ export const PositiveUint16 = {
 
   /**
    * Divides one PositiveUint16 by another using floor division.
+   *
    * @param a The dividend PositiveUint16.
    * @param b The divisor PositiveUint16.
    * @returns `⌊a / b⌋` clamped to [1, 65535] as a PositiveUint16.

package/src/number/branded-types/positive-uint16.test.mts

@@ -11,8 +11,8 @@ describe('PositiveUint16', () => {
     test('accepts valid positive uint16 values', () => {
       expect(() => asPositiveUint16(1)).not.toThrow();
       expect(() => asPositiveUint16(1000)).not.toThrow();
-      expect(() => asPositiveUint16(65535)).not.toThrow(); // 2^16 - 1
-      expect(() => asPositiveUint16(32768)).not.toThrow(); // 2^15
+      expect(() => asPositiveUint16(65_535)).not.toThrow(); // 2^16 - 1
+      expect(() => asPositiveUint16(32_768)).not.toThrow(); // 2^15
     });
 
     test('rejects zero', () => {
@@ -20,8 +20,8 @@ describe('PositiveUint16', () => {
     });
 
     test('rejects values outside uint16 range', () => {
-      expect(() => asPositiveUint16(65536)).toThrow(TypeError); // 2^16
-      expect(() => asPositiveUint16(100000)).toThrow(TypeError);
+      expect(() => asPositiveUint16(65_536)).toThrow(TypeError); // 2^16
+      expect(() => asPositiveUint16(100_000)).toThrow(TypeError);
     });
 
     test('rejects negative integers', () => {
@@ -44,7 +44,7 @@ describe('PositiveUint16', () => {
     test('returns the same value for valid inputs', () => {
       expect(asPositiveUint16(5)).toBe(5);
       expect(asPositiveUint16(1)).toBe(1);
-      expect(asPositiveUint16(65535)).toBe(65535);
+      expect(asPositiveUint16(65_535)).toBe(65_535);
     });
 
     test.each([
@@ -55,7 +55,7 @@ describe('PositiveUint16', () => {
       { name: '-3.4', value: -3.4 },
       { name: '0', value: 0 },
       { name: '-1', value: -1 },
-      { name: '65536', value: 65536 },
+      { name: '65536', value: 65_536 },
     ] as const)(
       `asPositiveUint16($name) should throw a TypeError`,
       ({ value }) => {
@@ -72,8 +72,8 @@ describe('PositiveUint16', () => {
     test('correctly identifies positive uint16 values', () => {
       expect(isPositiveUint16(1)).toBe(true);
       expect(isPositiveUint16(1000)).toBe(true);
-      expect(isPositiveUint16(65535)).toBe(true);
-      expect(isPositiveUint16(32768)).toBe(true);
+      expect(isPositiveUint16(65_535)).toBe(true);
+      expect(isPositiveUint16(32_768)).toBe(true);
     });
 
     test('correctly identifies zero', () => {
@@ -81,8 +81,8 @@ describe('PositiveUint16', () => {
     });
 
     test('correctly identifies values outside uint16 range', () => {
-      expect(isPositiveUint16(65536)).toBe(false);
-      expect(isPositiveUint16(100000)).toBe(false);
+      expect(isPositiveUint16(65_536)).toBe(false);
+      expect(isPositiveUint16(100_000)).toBe(false);
     });
 
     test('correctly identifies negative integers', () => {
@@ -110,7 +110,7 @@ describe('PositiveUint16', () => {
   describe('constants', () => {
     test('MIN_VALUE and MAX_VALUE', () => {
       expect(PositiveUint16.MIN_VALUE).toBe(1);
-      expect(PositiveUint16.MAX_VALUE).toBe(65535);
+      expect(PositiveUint16.MAX_VALUE).toBe(65_535);
     });
   });
 
@@ -125,10 +125,10 @@ describe('PositiveUint16', () => {
 
     test('add (with clamping to positive uint16 range)', () => {
       const result = PositiveUint16.add(
-        asPositiveUint16(65000),
+        asPositiveUint16(65_000),
         asPositiveUint16(1000),
       );
-      expect(result).toBe(65535); // clamped to max
+      expect(result).toBe(65_535); // clamped to max
       expect(PositiveUint16.add(a, b)).toBe(150);
     });
 
@@ -142,7 +142,7 @@ describe('PositiveUint16', () => {
         asPositiveUint16(1000),
         asPositiveUint16(100),
       );
-      expect(result).toBe(65535); // clamped to max
+      expect(result).toBe(65_535); // clamped to max
       expect(
         PositiveUint16.mul(asPositiveUint16(10), asPositiveUint16(5)),
       ).toBe(50);
@@ -163,7 +163,7 @@ describe('PositiveUint16', () => {
         asPositiveUint16(256),
         asPositiveUint16(3),
       );
-      expect(result).toBe(65535); // clamped to max
+      expect(result).toBe(65_535); // clamped to max
       expect(PositiveUint16.pow(asPositiveUint16(2), asPositiveUint16(3))).toBe(
         8,
       );
@@ -189,7 +189,7 @@ describe('PositiveUint16', () => {
       for (const _ of range(10)) {
         const result = PositiveUint16.random(1, 30);
         expect(result).toBeGreaterThanOrEqual(1);
-        expect(result).toBeLessThanOrEqual(65535);
+        expect(result).toBeLessThanOrEqual(65_535);
       }
     });
   });