@fimbul-works/vec 1.1.0 → 2.0.0

package/dist/esm/vec4.js

@@ -1,4 +1,8 @@
-const { cos, acos, atan2, sqrt, abs } = Math;
+/**
+ * Documentation for 4D Vector class.
+ * @module Vec4
+ */
+const { sin, cos, acos, atan2, sqrt, abs, log, PI } = Math;
 /**
  * Represents a 4D vector with various operations.
  */
@@ -9,10 +13,11 @@ export class Vec4 {
     /**
      * Computes and updates the magnitude of the vector.
      * @private
-     * @param x - The x-component of the vector.
-     * @param y - The y-component of the vector.
-     * @param z - The z-component of the vector.
-     * @param w - The w-component of the vector.
+     * @param {number} x - The x-component of the vector.
+     * @param {number} y - The y-component of the vector.
+     * @param {number} z - The z-component of the vector.
+     * @param {number} w - The w-component of the vector.
+     * @returns {void}
      */
     #computeMagnitude(x = this.#xyzw[0], y = this.#xyzw[1], z = this.#xyzw[2], w = this.#xyzw[3]) {
         if (x !== this.#prevXYZW[0] || y !== this.#prevXYZW[1] || z !== this.#prevXYZW[2] || w !== this.#prevXYZW[3]) {
@@ -25,10 +30,10 @@ export class Vec4 {
     }
     /**
      * Creates a new Vec4 instance.
-     * @param x - The x-coordinate of the vector.
-     * @param y - The y-coordinate of the vector.
-     * @param z - The z-coordinate of the vector.
-     * @param w - The w-coordinate of the vector.
+     * @param {number} x - The x-coordinate of the vector.
+     * @param {number} y - The y-coordinate of the vector.
+     * @param {number} z - The z-coordinate of the vector.
+     * @param {number} w - The w-coordinate of the vector.
      */
     constructor(x = 0, y = 0, z = 0, w = 0) {
         this.#xyzw[0] = x;
@@ -39,18 +44,18 @@ export class Vec4 {
     }
     /**
      * Adds two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns A new Vec3 instance representing the sum.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {Vec4} A new Vec4 instance representing the sum.
      */
     static add(v, w) {
         return new Vec4(v.#xyzw[0] + w.#xyzw[0], v.#xyzw[1] + w.#xyzw[1], v.#xyzw[2] + w.#xyzw[2], v.#xyzw[3] + w.#xyzw[3]);
     }
     /**
      * Subtracts one vector from another.
-     * @param v - The vector to subtract from.
-     * @param w - The vector to subtract.
-     * @returns A new Vec2 instance representing the difference.
+     * @param {Vec4} v - The vector to subtract from.
+     * @param {Vec4} w - The vector to subtract.
+     * @returns {Vec4} A new Vec4 instance representing the difference.
      */
     static subtract(v, w) {
         return new Vec4(v.#xyzw[0] - w.#xyzw[0], v.#xyzw[1] - w.#xyzw[1], v.#xyzw[2] - w.#xyzw[2], v.#xyzw[3] - w.#xyzw[3]);
@@ -75,9 +80,9 @@ export class Vec4 {
     }
     /**
      * Calculates the angle between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The angle between the vectors in radians.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The angle between the vectors in radians.
      */
     static angleBetween(v, w) {
         return acos((v.#xyzw[0] * w.#xyzw[0] + v.#xyzw[1] * w.#xyzw[1] + v.#xyzw[2] * w.#xyzw[2] + v.#xyzw[3] * w.#xyzw[3]) /
@@ -85,9 +90,9 @@ export class Vec4 {
     }
     /**
      * Calculates the Euclidean distance between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The distance between the vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The distance between the vectors.
      */
     static distance(v, w) {
         return sqrt((v.#xyzw[0] - w.#xyzw[0]) ** 2 +
@@ -97,9 +102,9 @@ export class Vec4 {
     }
     /**
      * Calculates the Chebyshev distance between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The Chebyshev distance between the vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The Chebyshev distance between the vectors.
      */
     static distanceChebyshev(v, w) {
         const absX = abs(v.#xyzw[0] - w.#xyzw[0]);
@@ -116,9 +121,9 @@ export class Vec4 {
     }
     /**
      * Calculates the Manhattan distance between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The Manhattan distance between the vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The Manhattan distance between the vectors.
      */
     static distanceManhattan(v, w) {
         return (abs(v.#xyzw[0] - w.#xyzw[0]) +
@@ -128,10 +133,10 @@ export class Vec4 {
     }
     /**
      * Calculates the Minkowski distance between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @param p - The order of the Minkowski distance.
-     * @returns The Minkowski distance between the vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @param {number} p - The order of the Minkowski distance.
+     * @returns {number} The Minkowski distance between the vectors.
      */
     static distanceMinkowski(v, w, p) {
         return ((abs(v.#xyzw[0] - w.#xyzw[0]) ** p +
@@ -142,9 +147,9 @@ export class Vec4 {
     }
     /**
      * Calculates the squared Euclidean distance between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The squared distance between the vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The squared distance between the vectors.
      */
     static distanceSq(v, w) {
         return ((v.#xyzw[0] - w.#xyzw[0]) ** 2 +
@@ -154,9 +159,9 @@ export class Vec4 {
     }
     /**
      * Calculates the dot product of two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns The dot product of the two vectors.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {number} The dot product of the two vectors.
      */
     static dot(v, w) {
         return v.#xyzw[0] * w.#xyzw[0] + v.#xyzw[1] * w.#xyzw[1] + v.#xyzw[2] * w.#xyzw[2] + v.#xyzw[3] * w.#xyzw[3];
@@ -178,9 +183,11 @@ export class Vec4 {
     }
     /**
      * Creates an immutable Vec4-like object.
-     * @param x - The x-coordinate of the vector.
-     * @param y - The y-coordinate of the vector.
-     * @returns An immutable object with Vec4-like properties.
+     * @param {number} x - The x-coordinate of the vector.
+     * @param {number} y - The y-coordinate of the vector.
+     * @param {number} z - The z-coordinate of the vector.
+     * @param {number} w - The w-coordinate of the vector.
+     * @returns {Readonly<{ x: number; y: number; z: number; w: number; xyzw: readonly number[]; r: number; g: number; b: number; a: number; rgba: readonly number[]; magnitude: number; magnitudeSq: number; angleW: number; angleX: number; angleY: number; angleZ: number; isInfinite: boolean; isNaN: boolean; isZero: boolean }>} An immutable object with Vec4-like properties.
      */
     static immutable(x = 0, y = 0, z = 0, w = 0) {
         const data = new Float64Array(10);
@@ -269,8 +276,8 @@ export class Vec4 {
     }
     /**
      * Checks if a vector has infinite components.
-     * @param v - The vector to check.
-     * @returns True if the vector has infinite components, false otherwise.
+     * @param {Vec4} v - The vector to check.
+     * @returns {boolean} True if the vector has infinite components, false otherwise.
      */
     static isInfinite(v) {
         const x = v.#xyzw[0];
@@ -288,26 +295,26 @@ export class Vec4 {
     }
     /**
      * Checks if a vector has NaN components.
-     * @param v - The vector to check.
-     * @returns True if the vector has NaN components, false otherwise.
+     * @param {Vec4} v - The vector to check.
+     * @returns {boolean} True if the vector has NaN components, false otherwise.
      */
     static isNaN(v) {
         return Number.isNaN(v.#xyzw[0]) || Number.isNaN(v.#xyzw[1]) || Number.isNaN(v.#xyzw[2]) || Number.isNaN(v.#xyzw[3]);
     }
     /**
      * Checks if a vector is zero.
-     * @param v - The vector to check.
-     * @returns True if the vector is zero, false otherwise.
+     * @param {Vec4} v - The vector to check.
+     * @returns {boolean} True if the vector is zero, false otherwise.
      */
     static isZero(v) {
         return v.#xyzw[0] === 0 && v.#xyzw[1] === 0 && v.#xyzw[2] === 0 && v.#xyzw[3] === 0;
     }
     /**
      * Performs linear interpolation between two vectors.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @param t - The interpolation parameter (0 to 1).
-     * @returns A new Vec2 instance representing the interpolated vector.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @param {number} t - The interpolation parameter (0 to 1).
+     * @returns {Vec4} A new Vec4 instance representing the interpolated vector.
      */
     static lerp(v, w, t) {
         if (t > 1)
@@ -322,16 +329,16 @@ export class Vec4 {
     }
     /**
      * Negates a vector.
-     * @param v - The vector to negate.
-     * @returns A new Vec2 instance representing the negated vector.
+     * @param {Vec4} v - The vector to negate.
+     * @returns {Vec4} A new Vec4 instance representing the negated vector.
      */
     static negate(v) {
         return new Vec4(-v.#xyzw[0], -v.#xyzw[1], -v.#xyzw[2], -v.#xyzw[3]);
     }
     /**
      * Normalizes a vector.
-     * @param v - The vector to normalize.
-     * @returns A new Vec2 instance representing the normalized vector.
+     * @param {Vec4} v - The vector to normalize.
+     * @returns {Vec4} A new Vec4 instance representing the normalized vector.
      */
     static normalize(v) {
         const m = v.#magnitude;
@@ -339,9 +346,9 @@ export class Vec4 {
     }
     /**
      * Projects one vector onto another.
-     * @param v - The vector to project.
-     * @param w - The vector to project onto.
-     * @returns A new Vec2 instance representing the projected vector.
+     * @param {Vec4} v - The vector to project.
+     * @param {Vec4} w - The vector to project onto.
+     * @returns {Vec4} A new Vec4 instance representing the projected vector.
      */
     static project(v, w) {
         const vM = v.#magnitude;
@@ -355,37 +362,34 @@ export class Vec4 {
     }
     /**
      * Creates a random unit vector.
-     * @param random - A function that returns a random number between 0 and 1.
-     * @returns A new Vec4 instance representing a random unit vector.
+     * @param {() => number} random - A function that returns a random number between 0 and 1.
+     * @returns {Vec4} A new Vec4 instance representing a random unit vector.
      */
     static random(random = Math.random) {
-        let x1;
-        let x2;
-        let x3;
-        let x4;
-        do {
-            x1 = random() * 2 - 1;
-            x2 = random() * 2 - 1;
-            x3 = random() * 2 - 1;
-            x4 = random() * 2 - 1;
-        } while (x1 ** 2 + x2 ** 2 >= 1 || x3 ** 2 + x4 ** 2 >= 1);
-        const f = sqrt((1 - x1 ** 2 - x2 ** 2) / (x3 ** 2 + x4 ** 2));
-        return new Vec4(x1, x2, x3 * f, x4 * f);
+        // 1. Generate four numbers from a Normal Distribution (Box-Muller transform)
+        const x = sqrt(-2 * log(random())) * cos(2 * PI * random());
+        const y = sqrt(-2 * log(random())) * sin(2 * PI * random());
+        const z = sqrt(-2 * log(random())) * cos(2 * PI * random());
+        const w = sqrt(-2 * log(random())) * sin(2 * PI * random());
+        // 2. Calculate the current length
+        const length = sqrt(x * x + y * y + z * z + w * w);
+        // 3. Divide by length to make it a unit vector
+        return new Vec4(x / length, y / length, z / length, w / length);
     }
     /**
      * Checks if two vectors are equal.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns True if the vectors are equal, false otherwise.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {boolean} True if the vectors are equal, false otherwise.
      */
     static satisfyEquality(v, w) {
         return (v.#xyzw[0] === w.#xyzw[0] && v.#xyzw[1] === w.#xyzw[1] && v.#xyzw[2] === w.#xyzw[2] && v.#xyzw[3] === w.#xyzw[3]);
     }
     /**
      * Checks if two vectors are opposite.
-     * @param v - The first vector.
-     * @param w - The second vector.
-     * @returns True if the vectors are opposite, false otherwise.
+     * @param {Vec4} v - The first vector.
+     * @param {Vec4} w - The second vector.
+     * @returns {boolean} True if the vectors are opposite, false otherwise.
      */
     static satisfyOpposition(v, w) {
         return (v.#xyzw[0] === -w.#xyzw[0] &&
@@ -408,16 +412,16 @@ export class Vec4 {
     }
     /**
      * Scales a vector by a scalar value.
-     * @param v - The vector to scale.
-     * @param c - The scalar value.
-     * @returns A new Vec2 instance representing the scaled vector.
+     * @param {Vec4} v - The vector to scale.
+     * @param {number} c - The scalar value.
+     * @returns {Vec4} A new Vec4 instance representing the scaled vector.
      */
     static scale(v, c) {
         return new Vec4(v.#xyzw[0] * c, v.#xyzw[1] * c, v.#xyzw[2] * c, v.#xyzw[3] * c);
     }
     /**
      * Creates a zero vector.
-     * @returns A new Vec4 instance representing a zero vector.
+     * @returns {Vec4} A new Vec4 instance representing a zero vector.
      */
     static zero() {
         return new Vec4();
@@ -431,14 +435,16 @@ export class Vec4 {
     }
     /**
      * Creates a Vec4 from an array.
-     * @returns A new Vec4 instance.
+     * @param {[number, number, number, number] | number[]} arr - An array containing the x, y, z, and w coordinates.
+     * @returns {Vec4} A new Vec4 instance.
      */
     static fromArray(arr) {
         return new Vec4(arr[0] ?? 0, arr[1] ?? 0, arr[2] ?? 0, arr[3] ?? 0);
     }
     /**
      * Creates a Vec4 from an object with x, y, z and w properties.
-     * @returns A new Vec4 instance.
+     * @param {{ x: number; y: number; z: number; w: number }} obj - An object with x, y, z, and w properties.
+     * @returns {Vec4} A new Vec4 instance.
      */
     static fromObject(obj) {
         return new Vec4(obj.x, obj.y, obj.z, obj.w);
@@ -453,14 +459,15 @@ export class Vec4 {
     }
     /**
      * Gets the x-component of the vector.
-     * @returns The x-component.
+     * @returns {number} The x-component.
      */
     get x() {
         return this.#xyzw[0];
     }
     /**
      * Sets the x-component of the vector.
-     * @param x - The new x-component.
+     * @param {number} x - The new x-component.
+     * @returns {void}
      */
     set x(x) {
         this.#xyzw[0] = x;
@@ -468,14 +475,15 @@ export class Vec4 {
     }
     /**
      * Gets the y-component of the vector.
-     * @returns The y-component.
+     * @returns {number} The y-component.
      */
     get y() {
         return this.#xyzw[1];
     }
     /**
      * Sets the z-component of the vector.
-     * @param y - The new z-component.
+     * @param {number} y - The new z-component.
+     * @returns {void}
      */
     set y(y) {
         this.#xyzw[1] = y;
@@ -483,14 +491,15 @@ export class Vec4 {
     }
     /**
      * Gets the z-component of the vector.
-     * @returns The z-component.
+     * @returns {number} The z-component.
      */
     get z() {
         return this.#xyzw[2];
     }
     /**
      * Sets the z-component of the vector.
-     * @param z - The new z-component.
+     * @param {number} z - The new z-component.
+     * @returns {void}
      */
     set z(z) {
         this.#xyzw[2] = z;
@@ -498,14 +507,15 @@ export class Vec4 {
     }
     /**
      * Gets the w-component of the vector.
-     * @returns The w-component.
+     * @returns {number} The w-component.
      */
     get w() {
         return this.#xyzw[3];
     }
     /**
      * Sets the w-component of the vector.
-     * @param w - The new w-component.
+     * @param {number} w - The new w-component.
+     * @returns {void}
      */
     set w(w) {
         this.#xyzw[3] = w;
@@ -513,14 +523,15 @@ export class Vec4 {
     }
     /**
      * Gets a copy of the vector's components as an array.
-     * @returns An array containing the x, y, z and w components of the vector.
+     * @returns {[number, number, number, number]} An array containing the x, y, z and w components of the vector.
      */
     get xyzw() {
         return Array.from(this.#xyzw.slice());
     }
     /**
      * Sets both components of the vector at once.
-     * @param xyzw - An array containing the new x, y and z components.
+     * @param {[number, number, number, number]} xyzw - An array containing the new x, y, z and w components.
+     * @returns {void}
      */
     set xyzw(xyzw) {
         this.#xyzw[0] = xyzw[0];
@@ -531,70 +542,75 @@ export class Vec4 {
     }
     /**
      * Gets the Red-component of a Color.
-     * @returns The Red-component.
+     * @returns {number} The Red-component.
      */
     get r() {
         return this.x;
     }
     /**
      * Sets the Red-component of a Color.
-     * @param r - The new Red-component.
+     * @param {number} r - The new Red-component.
+     * @returns {void}
      */
     set r(r) {
         this.x = r;
     }
     /**
      * Gets the Green-component of a Color.
-     * @returns The Green-component.
+     * @returns {number} The Green-component.
      */
     get g() {
         return this.y;
     }
     /**
      * Sets the Green-component of the Color.
-     * @param g - The new Green-component.
+     * @param {number} g - The new Green-component.
+     * @returns {void}
      */
     set g(g) {
         this.y = g;
     }
     /**
      * Gets the Blue-component of the color.
-     * @returns The Blue-component.
+     * @returns {number} The Blue-component.
      */
     get b() {
         return this.z;
     }
     /**
      * Sets the Blue-component of the Color.
-     * @param b - The new Blue-component.
+     * @param {number} b - The new Blue-component.
+     * @returns {void}
      */
     set b(b) {
         this.z = b;
     }
     /**
      * Gets the Alpha-component of the color.
-     * @returns The Alpha-component.
+     * @returns {number} The Alpha-component.
      */
     get a() {
         return this.w;
     }
     /**
      * Sets the Alpha-component of the Color.
-     * @param b - The new Alpha-component.
+     * @param {number} a - The new Alpha-component.
+     * @returns {void}
      */
     set a(a) {
         this.w = a;
     }
     /**
      * Gets a copy of the vector's components as an array.
-     * @returns An array containing the Red, Green, Blue and Alpha components of the Color.
+     * @returns {[number, number, number, number]} An array containing the Red, Green, Blue and Alpha components of the Color.
      */
     get rgba() {
         return this.xyzw;
     }
     /**
      * Sets all components of the Color at once.
-     * @param rgba - An array containing the new Red, Green and Blue components.
+     * @param {[number, number, number, number]} rgba - An array containing the new Red, Green, Blue and Alpha components.
+     * @returns {void}
      */
     set rgba(rgba) {
         this.xyzw = rgba;
@@ -656,8 +672,8 @@ export class Vec4 {
     }
     /**
      * Adds another vector to this vector.
-     * @param v - The vector to add.
-     * @returns This Vec4 instance for method chaining.
+     * @param {Vec4} v - The vector to add.
+     * @returns {this} This Vec4 instance for method chaining.
      */
     add(v) {
         this.#xyzw[0] += v.#xyzw[0];
@@ -719,9 +735,9 @@ export class Vec4 {
     }
     /**
      * Clamps the magnitude of this vector between a minimum and maximum value.
-     * @param min - The minimum magnitude.
-     * @param max - The maximum magnitude.
-     * @returns This Vec4 instance for method chaining.
+     * @param {number} min - The minimum magnitude.
+     * @param {number} max - The maximum magnitude.
+     * @returns {this} This Vec4 instance for method chaining.
      */
     clamp(min, max) {
         const m = this.#magnitude;
@@ -743,7 +759,7 @@ export class Vec4 {
     }
     /**
      * Creates a copy of this vector.
-     * @returns A new Vec4 instance with the same components.
+     * @returns {Vec4} A new Vec4 instance with the same components.
      */
     clone() {
         return new Vec4(this.#xyzw[0], this.#xyzw[1], this.#xyzw[2], this.#xyzw[3]);
@@ -774,8 +790,8 @@ export class Vec4 {
     }
     /**
      * Calculates the Chebyshev distance between this vector and another vector.
-     * @param v - The first vector.
-     * @returns The Chebyshev distance between the vectors.
+     * @param {Vec4} v - The other vector.
+     * @returns {number} The Chebyshev distance between the vectors.
      */
     distanceChebyshev(v) {
         const absX = abs(this.#xyzw[0] - v.#xyzw[0]);
@@ -792,8 +808,8 @@ export class Vec4 {
     }
     /**
      * Calculates the Manhattan distance between this vector and another vector.
-     * @param v - The other vector.
-     * @returns The Manhattan distance between the vectors.
+     * @param {Vec4} v - The other vector.
+     * @returns {number} The Manhattan distance between the vectors.
      */
     distanceManhattan(v) {
         return (abs(this.#xyzw[0] - v.#xyzw[0]) +
@@ -802,10 +818,10 @@ export class Vec4 {
             abs(this.#xyzw[3] - v.#xyzw[3]));
     }
     /**
-     * Calculates the Minkowski distance between  thisvector and another vector.
-     * @param v - The other vector.
-     * @param p - The order of the Minkowski distance.
-     * @returns The Minkowski distance between the vectors.
+     * Calculates the Minkowski distance between this vector and another vector.
+     * @param {Vec4} v - The other vector.
+     * @param {number} p - The order of the Minkowski distance.
+     * @returns {number} The Minkowski distance between the vectors.
      */
     distanceMinkowski(v, p) {
         return ((abs(this.#xyzw[0] - v.#xyzw[0]) ** p +
@@ -984,23 +1000,7 @@ export class Vec4 {
      * @returns This Vec4 instance for method chaining.
      */
     random(random = Math.random) {
-        let x1;
-        let x2;
-        let x3;
-        let x4;
-        do {
-            x1 = random() * 2 - 1;
-            x2 = random() * 2 - 1;
-            x3 = random() * 2 - 1;
-            x4 = random() * 2 - 1;
-        } while (x1 ** 2 + x2 ** 2 >= 1 || x3 ** 2 + x4 ** 2 >= 1);
-        const f = sqrt((1 - x1 ** 2 - x2 ** 2) / (x3 ** 2 + x4 ** 2));
-        const m = this.#magnitude;
-        this.#xyzw[0] = m * x1;
-        this.#xyzw[1] = m * x2;
-        this.#xyzw[2] = m * x3 * f;
-        this.#xyzw[3] = m * x4 * f;
-        this.#computeMagnitude();
+        this.copy(Vec4.random(random));
         return this;
     }
     /**