@pawells/math-extended 1.1.1 → 3.0.0

package/build/quaternions/predefined.js

@@ -10,7 +10,9 @@ import { QuaternionFromAxisAngle } from './core.js';
  * @returns Quaternion representing rotation around X-axis
  *
  * @example
+ * ```typescript
  * const q = QuaternionRotationX(Math.PI / 2); // 90° rotation around X-axis
+ * ```
  */
 export function QuaternionRotationX(angle) {
     return QuaternionFromAxisAngle([1, 0, 0], angle);
@@ -22,7 +24,9 @@ export function QuaternionRotationX(angle) {
  * @returns Quaternion representing rotation around Y-axis
  *
  * @example
+ * ```typescript
  * const q = QuaternionRotationY(Math.PI / 4); // 45° rotation around Y-axis
+ * ```
  */
 export function QuaternionRotationY(angle) {
     return QuaternionFromAxisAngle([0, 1, 0], angle);
@@ -34,7 +38,9 @@ export function QuaternionRotationY(angle) {
  * @returns Quaternion representing rotation around Z-axis
  *
  * @example
+ * ```typescript
  * const q = QuaternionRotationZ(Math.PI); // 180° rotation around Z-axis
+ * ```
  */
 export function QuaternionRotationZ(angle) {
     return QuaternionFromAxisAngle([0, 0, 1], angle);

package/build/quaternions/predefined.js.map

@@ -1 +1 @@
-{"version":3,"file":"predefined.js","sourceRoot":"","sources":["../../src/quaternions/predefined.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"predefined.js","sourceRoot":"","sources":["../../src/quaternions/predefined.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAChD,OAAO,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/build/quaternions/types.d.ts

@@ -3,8 +3,7 @@
  * Quaternions provide a mathematically robust way to represent rotations in 3D space,
  * avoiding gimbal lock and providing smooth interpolation capabilities.
  */
-import { TVector3, TVector4 } from '../vectors/types.js';
-import { IMatrix3 } from '../matrices/types.js';
+import z from 'zod';
 /**
  * Quaternion type representing a rotation in 3D space as [x, y, z, w].
  * The first three components (x, y, z) represent the vector part (rotation axis scaled by sin(θ/2)),
@@ -13,40 +12,52 @@ import { IMatrix3 } from '../matrices/types.js';
  * Quaternions extend IVector4 to leverage vector operations while maintaining semantic meaning.
  *
  * @example
- * const identity: IQuaternion = [0, 0, 0, 1];     // No rotation
- * const rotationX: IQuaternion = [1, 0, 0, 0];    // 180° rotation around X-axis
- * const rotation90Y: IQuaternion = [0, 0.707, 0, 0.707]; // 90° rotation around Y-axis
+ * ```typescript
+ * const identity: TQuaternion = [0, 0, 0, 1];     // No rotation
+ * const rotationX: TQuaternion = [1, 0, 0, 0];    // 180° rotation around X-axis
+ * const rotation90Y: TQuaternion = [0, 0.707, 0, 0.707]; // 90° rotation around Y-axis
+ * ```
  */
-export type TQuaternion = TVector4;
+export declare const QUATERNION_SCHEMA: z.ZodArray<z.ZodUnknown>;
+export type TQuaternion = [number, number, number, number];
 /**
  * Euler angles representation as [x, y, z] rotations in radians.
  * Order of rotation is typically Z-Y-X (yaw-pitch-roll) unless specified otherwise.
  *
  * @example
- * const euler: IEulerAngles = [0, Math.PI/4, 0]; // 45° pitch rotation
+ * ```typescript
+ * const euler: TEulerAngles = [0, Math.PI/4, 0]; // 45° pitch rotation
+ * ```
  */
-export type TEulerAngles = TVector3;
+export declare const EULER_ANGLES_SCHEMA: z.ZodArray<z.ZodUnknown>;
+export type TEulerAngles = [number, number, number];
 /**
  * Axis-angle representation as [axis_x, axis_y, axis_z, angle].
  * The first three components define a normalized rotation axis,
  * and the fourth component is the rotation angle in radians.
  *
  * @example
- * const axisAngle: IAxisAngle = [0, 1, 0, Math.PI/2]; // 90° rotation around Y-axis
+ * ```typescript
+ * const axisAngle: TAxisAngle = [0, 1, 0, Math.PI/2]; // 90° rotation around Y-axis
+ * ```
  */
-export type TAxisAngle = TVector4;
+export declare const AXIS_ANGLE_SCHEMA: z.ZodArray<z.ZodUnknown>;
+export type TAxisAngle = [number, number, number, number];
 /**
  * Rotation matrix representation as a 3x3 matrix.
- * Uses the standard IMatrix3 type for better integration with matrix operations.
+ * Uses the standard TMatrix3 type for better integration with matrix operations.
  *
  * @example
- * const identity: IRotationMatrix = [
+ * ```typescript
+ * const identity: TRotationMatrix = [
  *   [1, 0, 0],  // First row
  *   [0, 1, 0],  // Second row
  *   [0, 0, 1]   // Third row
  * ];
+ * ```
  */
-export type TRotationMatrix = IMatrix3;
+export declare const ROTATION_MATRIX_SCHEMA: z.ZodArray<z.ZodArray<z.ZodUnknown>>;
+export type TRotationMatrix = [[number, number, number], [number, number, number], [number, number, number]];
 /**
  * Union type representing any supported rotation representation.
  * Useful for functions that can accept multiple rotation formats.

package/build/quaternions/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/quaternions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;AAElC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,eAAe,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/quaternions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,0BAQ7B,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,0BAQ/B,CAAC;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,0BAQ7B,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,sCAUlC,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7G;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,eAAe,CAAC"}

package/build/quaternions/types.js

@@ -3,5 +3,55 @@
  * Quaternions provide a mathematically robust way to represent rotations in 3D space,
  * avoiding gimbal lock and providing smooth interpolation capabilities.
  */
-export {};
+import z from 'zod';
+/**
+ * Quaternion type representing a rotation in 3D space as [x, y, z, w].
+ * The first three components (x, y, z) represent the vector part (rotation axis scaled by sin(θ/2)),
+ * and the fourth component (w) represents the scalar part (cos(θ/2)).
+ *
+ * Quaternions extend IVector4 to leverage vector operations while maintaining semantic meaning.
+ *
+ * @example
+ * ```typescript
+ * const identity: TQuaternion = [0, 0, 0, 1];     // No rotation
+ * const rotationX: TQuaternion = [1, 0, 0, 0];    // 180° rotation around X-axis
+ * const rotation90Y: TQuaternion = [0, 0.707, 0, 0.707]; // 90° rotation around Y-axis
+ * ```
+ */
+export const QUATERNION_SCHEMA = z.array(z.unknown().refine(val => typeof val === 'number' && !Number.isNaN(val), { message: 'Component must be a number' })).refine(arr => arr.length === 4, { message: 'Quaternion must have exactly 4 components' });
+/**
+ * Euler angles representation as [x, y, z] rotations in radians.
+ * Order of rotation is typically Z-Y-X (yaw-pitch-roll) unless specified otherwise.
+ *
+ * @example
+ * ```typescript
+ * const euler: TEulerAngles = [0, Math.PI/4, 0]; // 45° pitch rotation
+ * ```
+ */
+export const EULER_ANGLES_SCHEMA = z.array(z.unknown().refine(val => typeof val === 'number' && !Number.isNaN(val), { message: 'Component must be a number' })).refine(arr => arr.length === 3, { message: 'Euler angles must have exactly 3 components' });
+/**
+ * Axis-angle representation as [axis_x, axis_y, axis_z, angle].
+ * The first three components define a normalized rotation axis,
+ * and the fourth component is the rotation angle in radians.
+ *
+ * @example
+ * ```typescript
+ * const axisAngle: TAxisAngle = [0, 1, 0, Math.PI/2]; // 90° rotation around Y-axis
+ * ```
+ */
+export const AXIS_ANGLE_SCHEMA = z.array(z.unknown().refine(val => typeof val === 'number' && !Number.isNaN(val), { message: 'Component must be a number' })).refine(arr => arr.length === 4, { message: 'Axis-angle must have exactly 4 components' });
+/**
+ * Rotation matrix representation as a 3x3 matrix.
+ * Uses the standard TMatrix3 type for better integration with matrix operations.
+ *
+ * @example
+ * ```typescript
+ * const identity: TRotationMatrix = [
+ *   [1, 0, 0],  // First row
+ *   [0, 1, 0],  // Second row
+ *   [0, 0, 1]   // Third row
+ * ];
+ * ```
+ */
+export const ROTATION_MATRIX_SCHEMA = z.array(z.array(z.unknown().refine(val => typeof val === 'number' && !Number.isNaN(val), { message: 'Component must be a number' }))).refine(arr => arr.length === 3 && arr.every(row => row.length === 3), { message: 'Rotation matrix must be 3x3' });
 //# sourceMappingURL=types.js.map

package/build/quaternions/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/quaternions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/quaternions/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CACvC,CAAC,CAAC,OAAO,EAAE,CAAC,MAAM,CACjB,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACpD,EAAE,OAAO,EAAE,4BAA4B,EAAE,CACzC,CACD,CAAC,MAAM,CACP,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EACvB,EAAE,OAAO,EAAE,2CAA2C,EAAE,CACxD,CAAC;AAGF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CACzC,CAAC,CAAC,OAAO,EAAE,CAAC,MAAM,CACjB,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACpD,EAAE,OAAO,EAAE,4BAA4B,EAAE,CACzC,CACD,CAAC,MAAM,CACP,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EACvB,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAC1D,CAAC;AAGF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CACvC,CAAC,CAAC,OAAO,EAAE,CAAC,MAAM,CACjB,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACpD,EAAE,OAAO,EAAE,4BAA4B,EAAE,CACzC,CACD,CAAC,MAAM,CACP,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EACvB,EAAE,OAAO,EAAE,2CAA2C,EAAE,CACxD,CAAC;AAGF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC5C,CAAC,CAAC,KAAK,CACN,CAAC,CAAC,OAAO,EAAE,CAAC,MAAM,CACjB,GAAG,CAAC,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACpD,EAAE,OAAO,EAAE,4BAA4B,EAAE,CACzC,CACD,CACD,CAAC,MAAM,CACP,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,EAC7D,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAC1C,CAAC"}

package/build/random.d.ts

@@ -2,11 +2,19 @@
  * Generates a random integer within the specified range (inclusive).
  * @param min - Minimum value (inclusive)
  * @param max - Maximum value (inclusive)
- * @returns Random integer between min and max, or NaN if min > max
- * @throws Returns `Number.NaN` when `min > max`
- * @example RandomInt(1, 6) // Returns 1, 2, 3, 4, 5, or 6 (dice roll)
- * @example RandomInt(-5, 5) // Returns any integer from -5 to 5
- * @example RandomInt(10, 5) // Returns Number.NaN (invalid range)
+ * @returns Random integer between min and max. Returns Number.NaN when min > max.
+ * @example
+ * ```typescript
+ * RandomInt(1, 6) // Returns 1, 2, 3, 4, 5, or 6 (dice roll)
+ * ```
+ * @example
+ * ```typescript
+ * RandomInt(-5, 5) // Returns any integer from -5 to 5
+ * ```
+ * @example
+ * ```typescript
+ * RandomInt(10, 5) // Returns Number.NaN (invalid range)
+ * ```
  */
 export declare function RandomInt(min: number, max: number): number;
 /**
@@ -14,11 +22,19 @@ export declare function RandomInt(min: number, max: number): number;
  * Note: Asymmetry with RandomInt — this function returns NaN when min >= max (not just min > max).
  * @param min - Minimum value (inclusive)
  * @param max - Maximum value (exclusive)
- * @returns Random float between min (inclusive) and max (exclusive), or NaN if min >= max
- * @throws Returns `Number.NaN` when `min >= max`
- * @example RandomFloat(0, 1) // Returns 0.0 to 0.999...
- * @example RandomFloat(-1.5, 1.5) // Returns any float from -1.5 to 1.499...
- * @example RandomFloat(5, 5) // Returns Number.NaN (min equals max)
+ * @returns Random float between min (inclusive) and max (exclusive). Returns Number.NaN when min >= max.
+ * @example
+ * ```typescript
+ * RandomFloat(0, 1) // Returns 0.0 to 0.999...
+ * ```
+ * @example
+ * ```typescript
+ * RandomFloat(-1.5, 1.5) // Returns any float from -1.5 to 1.499...
+ * ```
+ * @example
+ * ```typescript
+ * RandomFloat(5, 5) // Returns Number.NaN (min equals max)
+ * ```
  */
 export declare function RandomFloat(min: number, max: number): number;
 /**
@@ -26,8 +42,14 @@ export declare function RandomFloat(min: number, max: number): number;
  * @template T - The type of elements in the array
  * @param array - Array to choose from
  * @returns Random element from the array, or undefined if array is empty
- * @example RandomChoice([1, 2, 3, 4, 5]) // Returns one of the numbers
- * @example RandomChoice(['red', 'green', 'blue']) // Returns one of the colors
+ * @example
+ * ```typescript
+ * RandomChoice([1, 2, 3, 4, 5]) // Returns one of the numbers
+ * ```
+ * @example
+ * ```typescript
+ * RandomChoice(['red', 'green', 'blue']) // Returns one of the colors
+ * ```
  */
 export declare function RandomChoice<T>(array: T[]): T | undefined;
 /**
@@ -37,8 +59,14 @@ export declare function RandomChoice<T>(array: T[]): T | undefined;
  * @param array - Array to choose from
  * @param count - Number of elements to select
  * @returns Array of `count` unique randomly selected elements, or empty array if inputs are invalid
- * @example RandomSample([1, 2, 3, 4, 5], 3) // Returns 3 unique numbers
- * @example RandomSample(['a', 'b', 'c'], 2) // Returns 2 unique letters
+ * @example
+ * ```typescript
+ * RandomSample([1, 2, 3, 4, 5], 3) // Returns 3 unique numbers
+ * ```
+ * @example
+ * ```typescript
+ * RandomSample(['a', 'b', 'c'], 2) // Returns 2 unique letters
+ * ```
  */
 export declare function RandomSample<T>(array: T[], count: number): T[];
 /**
@@ -47,8 +75,14 @@ export declare function RandomSample<T>(array: T[], count: number): T[];
  * @param array - Array to shuffle
  * @param clone - If true, returns a shuffled copy; if false/undefined, modifies original array
  * @returns Shuffled array (original reference if clone=false, new array if clone=true)
- * @example RandomShuffle([1, 2, 3, 4, 5]) // Modifies and returns original array
- * @example RandomShuffle([1, 2, 3, 4, 5], true) // Returns new shuffled array, original unchanged
+ * @example
+ * ```typescript
+ * RandomShuffle([1, 2, 3, 4, 5]) // Modifies and returns original array
+ * ```
+ * @example
+ * ```typescript
+ * RandomShuffle([1, 2, 3, 4, 5], true) // Returns new shuffled array, original unchanged
+ * ```
  */
 export declare function RandomShuffle<T>(array: T[], clone?: boolean): T[];
 /**
@@ -56,8 +90,14 @@ export declare function RandomShuffle<T>(array: T[], clone?: boolean): T[];
  * @param probability - Probability of returning true (0.0 to 1.0, default: 0.5)
  * @returns Random boolean based on probability
  * @throws {RangeError} If probability is outside the range [0, 1]
- * @example RandomBool() // 50% chance of true
- * @example RandomBool(0.8) // 80% chance of true
+ * @example
+ * ```typescript
+ * RandomBool() // 50% chance of true
+ * ```
+ * @example
+ * ```typescript
+ * RandomBool(0.8) // 80% chance of true
+ * ```
  */
 export declare function RandomBool(probability?: number): boolean;
 /**
@@ -67,8 +107,14 @@ export declare function RandomBool(probability?: number): boolean;
  * @param mean - Mean of the distribution (default: 0)
  * @param standardDeviation - Standard deviation of the distribution (default: 1)
  * @returns Random number from normal distribution
- * @example RandomNormal() // Standard normal distribution (mean=0, std=1)
- * @example RandomNormal(100, 15) // IQ-like distribution (mean=100, std=15)
+ * @example
+ * ```typescript
+ * RandomNormal() // Standard normal distribution (mean=0, std=1)
+ * ```
+ * @example
+ * ```typescript
+ * RandomNormal(100, 15) // IQ-like distribution (mean=100, std=15)
+ * ```
  */
 export declare function RandomNormal(mean?: number, standardDeviation?: number): number;
 //# sourceMappingURL=random.d.ts.map

package/build/random.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAKzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAc9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,CAWjE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,WAAW,GAAE,MAAY,GAAG,OAAO,CAI7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,MAAU,EAAE,iBAAiB,GAAE,MAAU,GAAG,MAAM,CAUpF"}
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAKzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAc9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,CAWjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,WAAW,GAAE,MAAY,GAAG,OAAO,CAI7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,MAAU,EAAE,iBAAiB,GAAE,MAAU,GAAG,MAAM,CAiBpF"}

package/build/random.js

@@ -4,11 +4,19 @@ const BOX_MULLER_MIN_U1 = Number.EPSILON; // Avoid log(0) = -Infinity in Box-Mul
  * Generates a random integer within the specified range (inclusive).
  * @param min - Minimum value (inclusive)
  * @param max - Maximum value (inclusive)
- * @returns Random integer between min and max, or NaN if min > max
- * @throws Returns `Number.NaN` when `min > max`
- * @example RandomInt(1, 6) // Returns 1, 2, 3, 4, 5, or 6 (dice roll)
- * @example RandomInt(-5, 5) // Returns any integer from -5 to 5
- * @example RandomInt(10, 5) // Returns Number.NaN (invalid range)
+ * @returns Random integer between min and max. Returns Number.NaN when min > max.
+ * @example
+ * ```typescript
+ * RandomInt(1, 6) // Returns 1, 2, 3, 4, 5, or 6 (dice roll)
+ * ```
+ * @example
+ * ```typescript
+ * RandomInt(-5, 5) // Returns any integer from -5 to 5
+ * ```
+ * @example
+ * ```typescript
+ * RandomInt(10, 5) // Returns Number.NaN (invalid range)
+ * ```
  */
 export function RandomInt(min, max) {
     if (min > max)
@@ -20,11 +28,19 @@ export function RandomInt(min, max) {
  * Note: Asymmetry with RandomInt — this function returns NaN when min >= max (not just min > max).
  * @param min - Minimum value (inclusive)
  * @param max - Maximum value (exclusive)
- * @returns Random float between min (inclusive) and max (exclusive), or NaN if min >= max
- * @throws Returns `Number.NaN` when `min >= max`
- * @example RandomFloat(0, 1) // Returns 0.0 to 0.999...
- * @example RandomFloat(-1.5, 1.5) // Returns any float from -1.5 to 1.499...
- * @example RandomFloat(5, 5) // Returns Number.NaN (min equals max)
+ * @returns Random float between min (inclusive) and max (exclusive). Returns Number.NaN when min >= max.
+ * @example
+ * ```typescript
+ * RandomFloat(0, 1) // Returns 0.0 to 0.999...
+ * ```
+ * @example
+ * ```typescript
+ * RandomFloat(-1.5, 1.5) // Returns any float from -1.5 to 1.499...
+ * ```
+ * @example
+ * ```typescript
+ * RandomFloat(5, 5) // Returns Number.NaN (min equals max)
+ * ```
  */
 export function RandomFloat(min, max) {
     if (min >= max)
@@ -36,8 +52,14 @@ export function RandomFloat(min, max) {
  * @template T - The type of elements in the array
  * @param array - Array to choose from
  * @returns Random element from the array, or undefined if array is empty
- * @example RandomChoice([1, 2, 3, 4, 5]) // Returns one of the numbers
- * @example RandomChoice(['red', 'green', 'blue']) // Returns one of the colors
+ * @example
+ * ```typescript
+ * RandomChoice([1, 2, 3, 4, 5]) // Returns one of the numbers
+ * ```
+ * @example
+ * ```typescript
+ * RandomChoice(['red', 'green', 'blue']) // Returns one of the colors
+ * ```
  */
 export function RandomChoice(array) {
     if (array.length === 0)
@@ -52,8 +74,14 @@ export function RandomChoice(array) {
  * @param array - Array to choose from
  * @param count - Number of elements to select
  * @returns Array of `count` unique randomly selected elements, or empty array if inputs are invalid
- * @example RandomSample([1, 2, 3, 4, 5], 3) // Returns 3 unique numbers
- * @example RandomSample(['a', 'b', 'c'], 2) // Returns 2 unique letters
+ * @example
+ * ```typescript
+ * RandomSample([1, 2, 3, 4, 5], 3) // Returns 3 unique numbers
+ * ```
+ * @example
+ * ```typescript
+ * RandomSample(['a', 'b', 'c'], 2) // Returns 2 unique letters
+ * ```
  */
 export function RandomSample(array, count) {
     if (array.length === 0 || count <= 0 || count > array.length)
@@ -74,8 +102,14 @@ export function RandomSample(array, count) {
  * @param array - Array to shuffle
  * @param clone - If true, returns a shuffled copy; if false/undefined, modifies original array
  * @returns Shuffled array (original reference if clone=false, new array if clone=true)
- * @example RandomShuffle([1, 2, 3, 4, 5]) // Modifies and returns original array
- * @example RandomShuffle([1, 2, 3, 4, 5], true) // Returns new shuffled array, original unchanged
+ * @example
+ * ```typescript
+ * RandomShuffle([1, 2, 3, 4, 5]) // Modifies and returns original array
+ * ```
+ * @example
+ * ```typescript
+ * RandomShuffle([1, 2, 3, 4, 5], true) // Returns new shuffled array, original unchanged
+ * ```
  */
 export function RandomShuffle(array, clone) {
     const targetArray = clone ? [...array] : array;
@@ -92,8 +126,14 @@ export function RandomShuffle(array, clone) {
  * @param probability - Probability of returning true (0.0 to 1.0, default: 0.5)
  * @returns Random boolean based on probability
  * @throws {RangeError} If probability is outside the range [0, 1]
- * @example RandomBool() // 50% chance of true
- * @example RandomBool(0.8) // 80% chance of true
+ * @example
+ * ```typescript
+ * RandomBool() // 50% chance of true
+ * ```
+ * @example
+ * ```typescript
+ * RandomBool(0.8) // 80% chance of true
+ * ```
  */
 export function RandomBool(probability = 0.5) {
     if (probability < 0 || probability > 1)
@@ -107,12 +147,25 @@ export function RandomBool(probability = 0.5) {
  * @param mean - Mean of the distribution (default: 0)
  * @param standardDeviation - Standard deviation of the distribution (default: 1)
  * @returns Random number from normal distribution
- * @example RandomNormal() // Standard normal distribution (mean=0, std=1)
- * @example RandomNormal(100, 15) // IQ-like distribution (mean=100, std=15)
+ * @example
+ * ```typescript
+ * RandomNormal() // Standard normal distribution (mean=0, std=1)
+ * ```
+ * @example
+ * ```typescript
+ * RandomNormal(100, 15) // IQ-like distribution (mean=100, std=15)
+ * ```
  */
 export function RandomNormal(mean = 0, standardDeviation = 1) {
     // Box-Muller transform — u1 must be > 0 to avoid log(0) = -Infinity
     let u1 = Math.random();
+    /**
+     * Avoid log(0) → -Infinity by rejecting u1 too close to 0.
+     * BOX_MULLER_MIN_U1 = Number.EPSILON ≈ 2.22e-16.
+     * Expected retry probability per call: ~2.22e-16 (effectively never executed).
+     * Box-Muller with u1 >= Number.EPSILON is statistically sound and produces
+     * valid normal-distributed values.
+     */
     while (u1 < BOX_MULLER_MIN_U1) {
         u1 = Math.random();
     }

package/build/random.js.map

@@ -1 +1 @@
-{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"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"}