@lakuna/umath 3.0.0 → 4.0.0

package/src/linalg/Quaternion.ts

@@ -1,7 +1,4 @@
-import type AxisAngle from "../types/AxisAngle.js";
-
 import radiansToDegrees from "../algorithms/radiansToDegrees.js";
-import createAxisAngleLike from "../utility/createAxisAngleLike.js";
 import epsilon from "../utility/epsilon.js";
 import {
 	createMatrix3Like,
@@ -89,8 +86,8 @@ export const fromValues: <T extends QuaternionLike>(
  * @public
  */
 export const add: <T extends QuaternionLike>(
-	a: QuaternionLike,
-	b: QuaternionLike,
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>,
 	out: T
 ) => T = vector4Add;
 
@@ -102,7 +99,7 @@ export const add: <T extends QuaternionLike>(
  * @public
  */
 export const copy: <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ) => T = vector4Copy;
 
@@ -113,7 +110,10 @@ export const copy: <T extends QuaternionLike>(
  * @returns The dot product.
  * @public
  */
-export const dot: (a: QuaternionLike, b: QuaternionLike) => number = vector4Dot;
+export const dot: (
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>
+) => number = vector4Dot;
 
 /**
  * Determine whether or not two unit quaternions point in roughly the same direction.
@@ -122,8 +122,10 @@ export const dot: (a: QuaternionLike, b: QuaternionLike) => number = vector4Dot;
  * @returns Whether or not the unit quaternions point in the same direction.
  * @public
  */
-export const equals = (a: QuaternionLike, b: QuaternionLike): boolean =>
-	Math.abs(dot(a, b)) >= 1 - epsilon;
+export const equals = (
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>
+): boolean => Math.abs(dot(a, b)) >= 1 - epsilon;
 
 /**
  * Determine whether or not two quaternions are exactly equivalent.
@@ -132,8 +134,10 @@ export const equals = (a: QuaternionLike, b: QuaternionLike): boolean =>
  * @returns Whether or not the quaternions are equivalent.
  * @public
  */
-export const exactEquals: (a: QuaternionLike, b: QuaternionLike) => boolean =
-	vector4ExactEquals;
+export const exactEquals: (
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>
+) => boolean = vector4ExactEquals;
 
 /**
  * Calculate the magnitude (length) of a quaternion.
@@ -141,7 +145,7 @@ export const exactEquals: (a: QuaternionLike, b: QuaternionLike) => boolean =
  * @returns The magnitude.
  * @public
  */
-export const getMagnitude: (quaternion: QuaternionLike) => number =
+export const getMagnitude: (quaternion: Readonly<QuaternionLike>) => number =
 	vector4GetMagnitude;
 
 /**
@@ -150,8 +154,9 @@ export const getMagnitude: (quaternion: QuaternionLike) => number =
  * @returns The squared magnitude.
  * @public
  */
-export const getSquaredMagnitude: (quaternion: QuaternionLike) => number =
-	vector4GetSquaredMagnitude;
+export const getSquaredMagnitude: (
+	quaternion: Readonly<QuaternionLike>
+) => number = vector4GetSquaredMagnitude;
 
 /**
  * Perform a linear interpolation between two quaternions.
@@ -164,8 +169,8 @@ export const getSquaredMagnitude: (quaternion: QuaternionLike) => number =
  * @public
  */
 export const lerp: <T extends QuaternionLike>(
-	a: QuaternionLike,
-	b: QuaternionLike,
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>,
 	t: number,
 	out: T
 ) => T = vector4Lerp;
@@ -178,7 +183,7 @@ export const lerp: <T extends QuaternionLike>(
  * @public
  */
 export const normalize: <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ) => T = vector4Normalize;
 
@@ -191,7 +196,7 @@ export const normalize: <T extends QuaternionLike>(
  * @public
  */
 export const scale: <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	scalar: number,
 	out: T
 ) => T = vector4Scale;
@@ -206,7 +211,7 @@ export const scale: <T extends QuaternionLike>(
  * @public
  */
 export const fromMatrix3 = <T extends QuaternionLike>(
-	matrix: Matrix3Like,
+	matrix: Readonly<Matrix3Like>,
 	out: T
 ): T => {
 	const m0 = matrix[0];
@@ -540,7 +545,7 @@ const doubleRatio = 360 / Math.PI;
  * @public
  */
 export const toEuler = <T extends Vector3Like>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const x = quaternion[0];
@@ -585,9 +590,9 @@ const im3 = createMatrix3Like();
  * @public
  */
 export const fromAxes = <T extends QuaternionLike>(
-	view: Vector3Like,
-	right: Vector3Like,
-	up: Vector3Like,
+	view: Readonly<Vector3Like>,
+	right: Readonly<Vector3Like>,
+	up: Readonly<Vector3Like>,
 	out: T
 ): T =>
 	normalize(
@@ -621,14 +626,14 @@ export const identity = <T extends QuaternionLike>(out: T): T =>
 /**
  * Calculate the axis and angle that represent a quaternion.
  * @param quaternion - The quaternion.
- * @param out - The axis and angle to store the result in.
+ * @param out - The axis to store the result in.
  * @returns The axis and angle.
  * @public
  */
-export const getAxisAngle = <T extends AxisAngle>(
-	quaternion: QuaternionLike,
+export const getAxisAngle = <T extends Vector3Like>(
+	quaternion: Readonly<QuaternionLike>,
 	out: T
-): T => {
+): [T, number] => {
 	const r = Math.acos(quaternion[3]) * 2;
 	const s = Math.sin(r / 2);
 
@@ -637,25 +642,26 @@ export const getAxisAngle = <T extends AxisAngle>(
 			quaternion[0] / s,
 			quaternion[1] / s,
 			quaternion[2] / s,
-			out.axis
+			out
 		);
 	} else {
-		vector3FromValues(1, 0, 0, out.axis);
+		vector3FromValues(1, 0, 0, out);
 	}
 
-	out.angle = r;
-	return out;
+	return [out, r];
 };
 
 /**
  * Set the axis and angle that represent a quaternion.
- * @param axisAngle - The axis and angle.
+ * @param axis - The axis.
+ * @param angle - The angle.
  * @param out - The quaternion to store the result in.
  * @returns The quaternion.
  * @public
  */
 export const setAxisAngle = <T extends QuaternionLike>(
-	{ angle, axis }: AxisAngle,
+	axis: Readonly<Vector3Like>,
+	angle: number,
 	out: T
 ): T => {
 	const r = angle / 2;
@@ -671,7 +677,10 @@ export const setAxisAngle = <T extends QuaternionLike>(
  * @returns The angular distance in radians.
  * @public
  */
-export const getAngle = (a: QuaternionLike, b: QuaternionLike): number => {
+export const getAngle = (
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>
+): number => {
 	const dp = dot(a, b);
 	return Math.acos(2 * dp * dp - 1);
 };
@@ -685,8 +694,8 @@ export const getAngle = (a: QuaternionLike, b: QuaternionLike): number => {
  * @public
  */
 export const multiply = <T extends QuaternionLike>(
-	a: QuaternionLike,
-	b: QuaternionLike,
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const ax = a[0];
@@ -717,7 +726,7 @@ export const multiply = <T extends QuaternionLike>(
  * @public
  */
 export const rotateX = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	radians: number,
 	out: T
 ): T => {
@@ -748,7 +757,7 @@ export const rotateX = <T extends QuaternionLike>(
  * @public
  */
 export const rotateY = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	radians: number,
 	out: T
 ): T => {
@@ -779,7 +788,7 @@ export const rotateY = <T extends QuaternionLike>(
  * @public
  */
 export const rotateZ = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	radians: number,
 	out: T
 ): T => {
@@ -809,7 +818,7 @@ export const rotateZ = <T extends QuaternionLike>(
  * @public
  */
 export const calculateW = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const x = quaternion[0];
@@ -834,7 +843,7 @@ export const calculateW = <T extends QuaternionLike>(
  * @public
  */
 export const exp = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const x = quaternion[0];
@@ -856,7 +865,7 @@ export const exp = <T extends QuaternionLike>(
  * @public
  */
 export const ln = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const x = quaternion[0];
@@ -880,7 +889,7 @@ export const ln = <T extends QuaternionLike>(
  * @public
  */
 export const pow = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	scalar: number,
 	out: T
 ): T => exp(scale(ln(quaternion, out), scalar, out), out);
@@ -896,8 +905,8 @@ export const pow = <T extends QuaternionLike>(
  * @public
  */
 export const slerp = <T extends QuaternionLike>(
-	a: QuaternionLike,
-	b: QuaternionLike,
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>,
 	t: number,
 	out: T
 ): T => {
@@ -976,7 +985,7 @@ export const random = <T extends QuaternionLike>(out: T): T => {
  * @public
  */
 export const invert = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T => {
 	const a0 = quaternion[0];
@@ -1000,7 +1009,7 @@ export const invert = <T extends QuaternionLike>(
  * @public
  */
 export const conjugate = <T extends QuaternionLike>(
-	quaternion: QuaternionLike,
+	quaternion: Readonly<QuaternionLike>,
 	out: T
 ): T =>
 	fromValues(
@@ -1028,10 +1037,10 @@ const controlPointTwo = createQuaternionLike();
  * @public
  */
 export const sqlerp = <T extends QuaternionLike>(
-	a: QuaternionLike,
-	b: QuaternionLike,
-	c: QuaternionLike,
-	d: QuaternionLike,
+	a: Readonly<QuaternionLike>,
+	b: Readonly<QuaternionLike>,
+	c: Readonly<QuaternionLike>,
+	d: Readonly<QuaternionLike>,
 	t: number,
 	out: T
 ): T =>
@@ -1060,8 +1069,8 @@ const iv3 = createVector3Like();
  * @public
  */
 export const fromRotationTo = <T extends QuaternionLike>(
-	a: Vector3Like,
-	b: Vector3Like,
+	a: Readonly<Vector3Like>,
+	b: Readonly<Vector3Like>,
 	out: T
 ): T => {
 	const dp = vector3Dot(a, b);
@@ -1072,7 +1081,7 @@ export const fromRotationTo = <T extends QuaternionLike>(
 			vector3Cross(yAxis, a, iv3);
 		}
 		vector3Normalize(iv3, iv3);
-		return setAxisAngle({ angle: Math.PI, axis: iv3 }, out);
+		return setAxisAngle(iv3, Math.PI, out);
 	}
 
 	if (dp > 1 - epsilon) {
@@ -1106,12 +1115,15 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	public 3: number;
 
 	/** The axis and angle that represent this quaternion. */
-	public get axisAngle(): ReturnType<typeof createAxisAngleLike> {
-		return getAxisAngle(this, createAxisAngleLike());
+	public get axisAngle(): readonly [Readonly<Vector3Like>, number] {
+		return getAxisAngle(this, createVector3Like());
 	}
 
-	public set axisAngle(value: AxisAngle) {
-		setAxisAngle(value, this);
+	public set axisAngle([axis, angle]: readonly [
+		Readonly<Vector3Like>,
+		number
+	]) {
+		setAxisAngle(axis, angle, this);
 	}
 
 	/** Get the magnitude (length) of this quaternion. */
@@ -1141,9 +1153,9 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @returns The quaternion.
 	 */
 	public static fromAxes(
-		view: Vector3Like,
-		right: Vector3Like,
-		up: Vector3Like
+		view: Readonly<Vector3Like>,
+		right: Readonly<Vector3Like>,
+		up: Readonly<Vector3Like>
 	): Quaternion {
 		return fromAxes(view, right, up, new Quaternion());
 	}
@@ -1166,7 +1178,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @returns The quaternion.
 	 * @see {@link https://en.wikipedia.org/wiki/Rotation_matrix | Rotation matrix}
 	 */
-	public static fromMatrix3(matrix: Matrix3Like): Quaternion {
+	public static fromMatrix3(matrix: Readonly<Matrix3Like>): Quaternion {
 		return fromMatrix3(matrix, new Quaternion());
 	}
 
@@ -1176,7 +1188,10 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param b - The second unit vector.
 	 * @returns The unit quaternion.
 	 */
-	public static fromRotationTo(a: Vector3Like, b: Vector3Like): Quaternion {
+	public static fromRotationTo(
+		a: Readonly<Vector3Like>,
+		b: Readonly<Vector3Like>
+	): Quaternion {
 		return fromRotationTo(a, b, new Quaternion());
 	}
 
@@ -1202,7 +1217,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other quaternion.
 	 * @returns The sum of the quaternions.
 	 */
-	public add(quaternion: QuaternionLike): Quaternion {
+	public add(quaternion: Readonly<QuaternionLike>): Quaternion {
 		return add(this, quaternion, new Quaternion());
 	}
 
@@ -1235,7 +1250,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The quaternion to copy.
 	 * @returns This quaternion.
 	 */
-	public copy(quaternion: QuaternionLike): this {
+	public copy(quaternion: Readonly<QuaternionLike>): this {
 		return copy(quaternion, this);
 	}
 
@@ -1244,7 +1259,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other quaternion.
 	 * @returns The dot product.
 	 */
-	public dot(quaternion: QuaternionLike): number {
+	public dot(quaternion: Readonly<QuaternionLike>): number {
 		return dot(this, quaternion);
 	}
 
@@ -1253,7 +1268,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other quaternion.
 	 * @returns Whether or not the quaternions are equivalent.
 	 */
-	public equals(quaternion: QuaternionLike): boolean {
+	public equals(quaternion: Readonly<QuaternionLike>): boolean {
 		return equals(this, quaternion);
 	}
 
@@ -1262,7 +1277,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other quaternion.
 	 * @returns Whether or not the quaternions are equivalent.
 	 */
-	public exactEquals(quaternion: QuaternionLike): boolean {
+	public exactEquals(quaternion: Readonly<QuaternionLike>): boolean {
 		return exactEquals(this, quaternion);
 	}
 
@@ -1279,7 +1294,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other unit quaternion.
 	 * @returns The angular distance in radians.
 	 */
-	public getAngle(quaternion: QuaternionLike): number {
+	public getAngle(quaternion: Readonly<QuaternionLike>): number {
 		return getAngle(this, quaternion);
 	}
 
@@ -1305,7 +1320,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param t - The interpolation amount (in `[0,1]`).
 	 * @returns The interpolated quaternion.
 	 */
-	public lerp(quaternion: QuaternionLike, t: number): Quaternion {
+	public lerp(quaternion: Readonly<QuaternionLike>, t: number): Quaternion {
 		return lerp(this, quaternion, t, new Quaternion());
 	}
 
@@ -1322,7 +1337,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @param quaternion - The other quaternion.
 	 * @returns The product.
 	 */
-	public multiply(quaternion: QuaternionLike): Quaternion {
+	public multiply(quaternion: Readonly<QuaternionLike>): Quaternion {
 		return multiply(this, quaternion, new Quaternion());
 	}
 
@@ -1394,7 +1409,7 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @returns The interpolated quaternion.
 	 * @see {@link https://en.wikipedia.org/wiki/Slerp | Slerp}
 	 */
-	public slerp(quaternion: QuaternionLike, t: number): Quaternion {
+	public slerp(quaternion: Readonly<QuaternionLike>, t: number): Quaternion {
 		return slerp(this, quaternion, t, new Quaternion());
 	}
 
@@ -1408,9 +1423,9 @@ export default class Quaternion extends Float32Array implements QuaternionLike {
 	 * @see {@link https://en.wikipedia.org/wiki/Slerp | Slerp}
 	 */
 	public sqlerp(
-		a: QuaternionLike,
-		b: QuaternionLike,
-		quaternion: QuaternionLike,
+		a: Readonly<QuaternionLike>,
+		b: Readonly<QuaternionLike>,
+		quaternion: Readonly<QuaternionLike>,
 		t: number
 	): Quaternion {
 		return sqlerp(this, a, b, quaternion, t, new Quaternion());

package/src/linalg/SlowMatrix.ts

@@ -20,7 +20,7 @@ interface SizedMatrixLike extends MatrixLike {
  * Determine whether the given `MatrixLike` has size information.
  * @internal
  */
-const isSized = (matrix: MatrixLike): matrix is SizedMatrixLike =>
+const isSized = (matrix: Readonly<MatrixLike>): matrix is SizedMatrixLike =>
 	"width" in matrix &&
 	typeof matrix.width === "number" &&
 	"height" in matrix &&
@@ -50,7 +50,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * Create a variable-size matrix from the given columns.
 	 * @param cols - The columns in the matrix.
 	 */
-	public constructor(...cols: number[][]) {
+	public constructor(...cols: readonly (readonly number[])[]) {
 		super(cols.flat());
 
 		this.width = cols.length;
@@ -70,7 +70,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @returns The sum of the matrices.
 	 * @see {@link https://en.wikipedia.org/wiki/Matrix_addition | Matrix addition}
 	 */
-	public add(matrix: MatrixLike): SlowMatrix {
+	public add(matrix: Readonly<MatrixLike>): SlowMatrix {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||
@@ -110,7 +110,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @param matrix - The matrix to copy.
 	 * @returns This matrix.
 	 */
-	public copy(matrix: MatrixLike): this {
+	public copy(matrix: Readonly<MatrixLike>): this {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||
@@ -131,7 +131,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @param matrix - The other matrix.
 	 * @returns Whether or not the matrices are equivalent.
 	 */
-	public equals(matrix: MatrixLike): boolean {
+	public equals(matrix: Readonly<MatrixLike>): boolean {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||
@@ -154,7 +154,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @param matrix - The other matrix.
 	 * @returns Whether the matrices are equivalent.
 	 */
-	public exactEquals(matrix: MatrixLike): boolean {
+	public exactEquals(matrix: Readonly<MatrixLike>): boolean {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||
@@ -178,7 +178,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @returns The product of the matrices.
 	 * @see {@link https://en.wikipedia.org/wiki/Matrix_multiplication | Matrix multiplication}
 	 */
-	public multiply(matrix: MatrixLike): SlowMatrix {
+	public multiply(matrix: Readonly<MatrixLike>): SlowMatrix {
 		if (!isSized(matrix) || this.width !== matrix.height) {
 			throw new MatrixSizeError();
 		}
@@ -227,7 +227,10 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @see {@link https://en.wikipedia.org/wiki/Matrix_addition | Matrix addition}
 	 * @see {@link https://en.wikipedia.org/wiki/Matrix_multiplication | Matrix multiplication}
 	 */
-	public multiplyScalarAndAdd(matrix: MatrixLike, scalar: number): SlowMatrix {
+	public multiplyScalarAndAdd(
+		matrix: Readonly<MatrixLike>,
+		scalar: number
+	): SlowMatrix {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||
@@ -253,7 +256,7 @@ export default class SlowMatrix extends Float32Array implements Matrix {
 	 * @returns The difference between the matrices.
 	 * @see {@link https://en.wikipedia.org/wiki/Matrix_addition | Matrix addition}
 	 */
-	public subtract(matrix: MatrixLike): SlowMatrix {
+	public subtract(matrix: Readonly<MatrixLike>): SlowMatrix {
 		if (
 			!isSized(matrix) ||
 			this.width !== matrix.width ||

package/src/linalg/SlowSquareMatrix.ts

@@ -43,7 +43,7 @@ export default class SlowSquareMatrix
 	 * @param cols - The columns in the matrix.
 	 * @see {@link https://en.wikipedia.org/wiki/Square_matrix | Square matrix}
 	 */
-	public constructor(...cols: number[][]) {
+	public constructor(...cols: readonly (readonly number[])[]) {
 		super(...cols);
 
 		// Ensure that every column is the same height and that the height is equal to the width.