@fimbul-works/vec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Claus Nuoskanen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @fimbul-works/vec
+
+A high-performance TypeScript vector math library providing 2D, 3D, and 4D vector operations with a focus on performance and type safety.
+
+[![npm version](https://badge.fury.io/js/%40fimbul-works%2Fvec.svg)](https://www.npmjs.com/package/@fimbul-works/vec)
+[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)
+
+## Features
+
+- 🚀 **Optimized Performance**: Uses `Float64Array` with magnitude caching and private fields
+- 🛡️ **Type Safety**: Full TypeScript support with strict typing and readonly options
+- 📏 **Multiple Distance Metrics**: Euclidean, Manhattan, Chebyshev, and Minkowski
+- 🔒 **Immutability Support**: Both mutable and immutable operation modes
+- 🎨 **Color Operations**: Built-in RGBA and RGB color handling
+- 🎮 **Graphics Ready**: Homogeneous coordinates and transformation support
+- 🧮 **Math Features**: Comprehensive geometric and arithmetic operations
+- ⚡ **Memory Efficient**: Zero-allocation options for performance-critical code
+
+## Installation
+
+```bash
+npm install @fimbul-works/vec
+```
+
+## Quick Start
+
+```typescript
+import { Vec2, Vec3, Vec4 } from "@fimbul-works/vec";
+
+// Create and manipulate vectors
+const position = new Vec2(100, 200);
+const direction = new Vec2(1, 0).rotate(Math.PI / 4);
+const movement = Vec2.scale(direction, 5);
+
+position.add(movement);
+
+// 3D graphics with homogeneous coordinates
+const point = new Vec4(x, y, z, 1);    // Point in 3D space
+const vector = new Vec4(dx, dy, dz, 0); // Direction in 3D space
+
+// Color manipulation
+const color = new Vec4(1, 0, 0, 0.5);  // Semi-transparent red
+```
+
+## Zero-Allocation Usage
+
+```typescript
+// Reuse vectors to avoid garbage collection
+const result = new Vec2();
+const temp = new Vec2();
+
+// Chain operations without creating intermediates
+position
+  .add(velocity.scale(deltaTime, temp))
+  .clamp(0, 100);
+```
+
+## Core Operations
+
+```typescript
+// Static operations (immutable)
+const sum = Vec2.add(v1, v2);
+const dot = Vec3.dot(v1, v2);
+const cross = Vec3.cross(v1, v2);
+
+// Method chaining (mutable)
+const result = new Vec3(1, 0, 0)
+  .rotate(angle)
+  .scale(2)
+  .normalize();
+
+// Distance calculations
+const dist = v1.distance(v2);
+const manhattan = v1.distanceManhattan(v2);
+```
+
+## Complete API Documentation
+
+- [Vec2 API Documentation](./VEC2.md)
+- [Vec3 API Documentation](./VEC3.md)
+- [Vec4 API Documentation](./VEC4.md)
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.
+
+---
+
+Built with ⚡ by [FimbulWorks](https://github.com/fimbul-works)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./vec2.js";
+export * from "./vec3.js";
+export * from "./vec4.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./vec2.js";
+export * from "./vec3.js";
+export * from "./vec4.js";

package/dist/vec2.d.ts

@@ -0,0 +1,531 @@
+/**
+ * Represents a 2D vector with various operations.
+ */
+export declare class Vec2 {
+    #private;
+    /**
+     * Creates a new Vec2 instance.
+     * @param x - The x-coordinate of the vector.
+     * @param y - The y-coordinate of the vector.
+     */
+    constructor(x?: number, y?: number);
+    /**
+     * Adds two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns A new Vec2 instance representing the sum.
+     */
+    static add(v: Vec2, w: Vec2): Vec2;
+    /**
+     * 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.
+     */
+    static subtract(v: Vec2, w: Vec2): Vec2;
+    /**
+     * Multiplies one vector with another.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns A new Vec2 instance representing the multiplied value.
+     */
+    static multiply(v: Vec2, w: Vec2): Vec2;
+    /**
+     * Divides one vector with another.
+     * @param v - Divident.
+     * @param w - Divisor.
+     * @returns A new Vec2 instance representing the divided value.
+     */
+    static divide(v: Vec2, w: Vec2): Vec2;
+    /**
+     * Calculates the angle between two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The angle between the vectors in radians.
+     */
+    static angleBetween(v: Vec2, w: Vec2): number;
+    /**
+     * Calculates the Euclidean distance between two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The distance between the vectors.
+     */
+    static distance(v: Vec2, w: Vec2): number;
+    /**
+     * Calculates the Chebyshev distance between two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The Chebyshev distance between the vectors.
+     */
+    static distanceChebyshev(v: Vec2, w: Vec2): number;
+    /**
+     * Calculates the Manhattan distance between two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The Manhattan distance between the vectors.
+     */
+    static distanceManhattan(v: Vec2, w: Vec2): number;
+    /**
+     * 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.
+     */
+    static distanceMinkowski(v: Vec2, w: Vec2, p: number): number;
+    /**
+     * 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.
+     */
+    static distanceSq(v: Vec2, w: Vec2): number;
+    /**
+     * Calculates the dot product of two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The dot product of the vectors.
+     */
+    static dot(v: Vec2, w: Vec2): number;
+    /**
+     * Calculates the cross product of two vectors.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @returns The cross product scalar value.
+     */
+    static cross(v: Vec2, w: Vec2): number;
+    /**
+     * Reflects the vector across a normal vector.
+     * @param v - The vector to reflect.
+     * @param normal - The normal vector to reflect across (must be normalized).
+     * @returns A new Vec2 instance representing the reflected vector.
+     */
+    static reflect(v: Vec2, normal: Vec2): Vec2;
+    /**
+     * Creates a Vec2 instance from polar coordinates.
+     * @param r - The radius.
+     * @param theta - The angle in radians.
+     * @returns A new Vec2 instance.
+     */
+    static fromPolarCoords(r: number, theta: number): Vec2;
+    /**
+     * Creates an immutable Vec2-like object.
+     * @param x - The x-coordinate of the vector.
+     * @param y - The y-coordinate of the vector.
+     * @returns An immutable object with Vec2-like properties.
+     */
+    static immutable(x?: number, y?: number): Readonly<{
+        angleX: number;
+        angleY: number;
+        isInfinite: boolean;
+        isNaN: boolean;
+        isZero: boolean;
+        magnitude: number;
+        magnitudeSq: number;
+        x: number;
+        xy: readonly number[];
+        y: number;
+    }>;
+    /**
+     * Checks if a vector has infinite components.
+     * @param v - The vector to check.
+     * @returns True if the vector has infinite components, false otherwise.
+     */
+    static isInfinite(v: Vec2): boolean;
+    /**
+     * Checks if a vector has NaN components.
+     * @param v - The vector to check.
+     * @returns True if the vector has NaN components, false otherwise.
+     */
+    static isNaN(v: Vec2): boolean;
+    /**
+     * Checks if a vector is zero.
+     * @param v - The vector to check.
+     * @returns True if the vector is zero, false otherwise.
+     */
+    static isZero(v: Vec2): boolean;
+    /**
+     * 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.
+     */
+    static lerp(v: Vec2, w: Vec2, t: number): Vec2;
+    /**
+     * Negates a vector.
+     * @param v - The vector to negate.
+     * @returns A new Vec2 instance representing the negated vector.
+     */
+    static negate(v: Vec2): Vec2;
+    /**
+     * Normalizes a vector.
+     * @param v - The vector to normalize.
+     * @returns A new Vec2 instance representing the normalized vector.
+     */
+    static normalize(v: Vec2): Vec2;
+    /**
+     * 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.
+     */
+    static project(v: Vec2, w: Vec2): Vec2;
+    /**
+     * Creates a random unit vector.
+     * @param random - A function that returns a random number between 0 and 1.
+     * @returns A new Vec2 instance representing a random unit vector.
+     */
+    static random(random?: () => number): Vec2;
+    /**
+     * 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.
+     */
+    static satisfyEquality(v: Vec2, w: Vec2): boolean;
+    /**
+     * 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.
+     */
+    static satisfyOpposition(v: Vec2, w: Vec2): boolean;
+    /**
+     * Compares a vector with another vector using an epsilon value for floating-point comparison.
+     * @param v - The first vector.
+     * @param w - The second vector.
+     * @param epsilon - The maximum difference between components to consider them equal.
+     * @returns True if the vectors are equal within epsilon, false otherwise.
+     */
+    static equals(v: Vec2, w: Vec2, epsilon?: number): boolean;
+    /**
+     * 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.
+     */
+    static scale(v: Vec2, c: number): Vec2;
+    /**
+     * Creates a zero vector.
+     * @returns A new Vec2 instance representing a zero vector.
+     */
+    static zero(): Vec2;
+    /**
+     * Creates a vector with all components set to 1.0.
+     * @returns A new Vec2 instance representing a vector with all components set to 1.0.
+     */
+    static one(): Vec2;
+    /**
+     * Creates a Vec2 from an array.
+     * @returns A new Vec2 instance.
+     */
+    static fromArray(arr: [number, number] | number[]): Vec2;
+    /**
+     * Creates a Vec2 from an object with x and y properties.
+     * @returns A new Vec2 instance.
+     */
+    static fromObject(obj: {
+        x: number;
+        y: number;
+    }): Vec2;
+    /**
+     * Creates a Vec2 instance from a JSON-parsed object.
+     * @param json - The JSON-parsed object containing x and y properties.
+     * @returns A new Vec2 instance.
+     */
+    static fromJSON(json: {
+        x: number;
+        y: number;
+    }): Vec2;
+    /**
+     * Gets the x-component of the vector.
+     * @returns The x-component.
+     */
+    get x(): number;
+    /**
+     * Sets the x-component of the vector.
+     * @param x - The new x-component.
+     */
+    set x(x: number);
+    /**
+     * Gets the y-component of the vector.
+     * @returns The y-component.
+     */
+    get y(): number;
+    /**
+     * Sets the y-component of the vector.
+     * @param y - The new y-component.
+     */
+    set y(y: number);
+    /**
+     * Gets a copy of the vector's components as an array.
+     * @returns An array containing the x and y components of the vector.
+     */
+    get xy(): [number, number];
+    /**
+     * Sets both components of the vector at once.
+     * @param xy - An array containing the new x and y components.
+     */
+    set xy(xy: [number, number] | number[]);
+    /**
+     * Gets the angle between the vector and the positive x-axis in radians.
+     * @returns The angle in radians, always in the range [0, 2π).
+     */
+    get angleX(): number;
+    /**
+     * Sets the angle between the vector and the positive x-axis, maintaining the vector's magnitude.
+     * @param phi - The new angle in radians.
+     */
+    set angleX(phi: number);
+    /**
+     * Gets the angle between the vector and the positive y-axis in radians.
+     * @returns The angle in radians, always in the range [0, 2π).
+     */
+    get angleY(): number;
+    /**
+     * Sets the angle between the vector and the positive y-axis, maintaining the vector's magnitude.
+     * @param phi - The new angle in radians.
+     */
+    set angleY(phi: number);
+    /**
+     * Gets the magnitude (length) of the vector.
+     * @returns The magnitude of the vector.
+     */
+    get magnitude(): number;
+    /**
+     * Sets the magnitude (length) of the vector, maintaining its direction.
+     * @param m - The new magnitude.
+     */
+    set magnitude(m: number);
+    /**
+     * Gets the squared magnitude of the vector.
+     * This is faster to compute than the actual magnitude and is useful for comparisons.
+     * @returns The squared magnitude of the vector.
+     */
+    get magnitudeSq(): number;
+    /**
+     * Adds another vector to this vector.
+     * @param v - The vector to add.
+     * @returns This Vec2 instance for method chaining.
+     */
+    add(v: Vec2): this;
+    /**
+     * Subtracts another vector from this vector.
+     * @param v - The vector to subtract.
+     * @returns This Vec2 instance for method chaining.
+     */
+    subtract(v: Vec2): this;
+    /**
+     * Multiplies this vector with another vector.
+     * @param v - The vector to multiply with.
+     * @returns This Vec2 instance for method chaining.
+     */
+    multiply(v: Vec2): this;
+    /**
+     * Divides this vector with another vector.
+     * @param v - The vector to divide with.
+     * @returns This Vec2 instance for method chaining.
+     */
+    divide(v: Vec2): this;
+    /**
+     * Calculates the angle between this vector and another vector.
+     * @param v - The other vector.
+     * @returns The angle between the vectors in radians.
+     */
+    angleBetween(v: Vec2): number;
+    /**
+     * Clamps the magnitude of this vector between a minimum and maximum value.
+     * @param min - The minimum magnitude.
+     * @param max - The maximum magnitude.
+     * @returns This Vec2 instance for method chaining.
+     */
+    clamp(min: number, max: number): this;
+    /**
+     * Creates a copy of this vector.
+     * @returns A new Vec2 instance with the same components.
+     */
+    clone(): Vec2;
+    /**
+     * Copies the components of another vector to this vector.
+     * @param v - The vector to copy from.
+     * @returns This Vec2 instance for method chaining.
+     */
+    copy(v: Vec2): this;
+    /**
+     * Calculates the distance between this vector and another vector.
+     * @param v - The other vector.
+     * @returns The distance between the vectors.
+     */
+    distance(v: Vec2): number;
+    /**
+     * Calculates the Chebyshev distance between this vector and another vector.
+     * @param v - The other vector.
+     * @returns The Chebyshev distance between the vectors.
+     */
+    distanceChebyshev(v: Vec2): number;
+    /**
+     * Calculates the Manhattan distance between this vector and another vector.
+     * @param v - The other vector.
+     * @returns The Manhattan distance between the vectors.
+     */
+    distanceManhattan(v: Vec2): number;
+    /**
+     * Calculates the Minkowski distance between this vector and another vector.
+     * @param v - The other vector.
+     * @param p - The order of the Minkowski distance.
+     * @returns The Minkowski distance between the vectors.
+     */
+    distanceMinkowski(v: Vec2, p: number): number;
+    /**
+     * Calculates the squared distance between this vector and another vector.
+     * @param v - The other vector.
+     * @returns The squared distance between the vectors.
+     */
+    distanceSq(v: Vec2): number;
+    /**
+     * Calculates the dot product of this vector with another vector.
+     * @param v - The other vector.
+     * @returns The dot product of the vectors.
+     */
+    dot(v: Vec2): number;
+    /**
+     * Calculates the cross product of this vector with another vector.
+     * @param v - The other vector.
+     * @returns The cross product of the vectors.
+     */
+    cross(v: Vec2): number;
+    /**
+     * Reflects this vector across a normal vector.
+     * @param normal - The normal vector to reflect across (must be normalized).
+     * @returns A new Vec2 instance representing the reflected vector.
+     */
+    reflect(normal: Vec2): Vec2;
+    /**
+     * Checks if this vector has infinite components.
+     * @returns True if the vector has infinite components, false otherwise.
+     */
+    isInfinite(): boolean;
+    /**
+     * Checks if this vector has NaN components.
+     * @returns True if the vector has NaN components, false otherwise.
+     */
+    isNaN(): boolean;
+    /**
+     * Checks if this vector is zero.
+     * @returns True if the vector is zero, false otherwise.
+     */
+    isZero(): boolean;
+    /**
+     * Limits the maximum magnitude of this vector.
+     * @param max - The maximum magnitude.
+     * @returns This Vec2 instance for method chaining.
+     */
+    limitMax(max: number): this;
+    /**
+     * Limits the minimum magnitude of this vector.
+     * @param min - The minimum magnitude.
+     * @returns This Vec2 instance for method chaining.
+     */
+    limitMin(min: number): this;
+    /**
+     * Sets this vector to point towards another vector.
+     * @param v - The vector to look at.
+     * @returns This Vec2 instance for method chaining.
+     */
+    lookAt(v: Vec2): this;
+    /**
+     * Negates this vector.
+     * @returns This Vec2 instance for method chaining.
+     */
+    negate(): this;
+    /**
+     * Normalizes this vector.
+     * @returns This Vec2 instance for method chaining.
+     */
+    normalize(): this;
+    /**
+     * Projects this vector onto another vector.
+     * @param v - The vector to project onto.
+     * @returns This Vec2 instance for method chaining.
+     */
+    project(v: Vec2): this;
+    /**
+     * Sets this vector to a random direction with the same magnitude.
+     * @param random - A function that returns a random number between 0 and 1.
+     * @returns This Vec2 instance for method chaining.
+     */
+    random(random?: () => number): this;
+    /**
+     * Rotates this vector around the Z-axis.
+     * @param phi - The angle of rotation in radians.
+     * @returns This Vec2 instance for method chaining.
+     */
+    rotateZ(phi: number): this;
+    /**
+     * Checks if this vector is equal to another vector.
+     * @param v - The other vector.
+     * @returns True if the vectors are equal, false otherwise.
+     */
+    satisfyEquality(v: Vec2): boolean;
+    /**
+     * Checks if this vector is opposite to another vector.
+     * @param v - The other vector.
+     * @returns True if the vectors are opposite, false otherwise.
+     */
+    satisfyOpposition(v: Vec2): boolean;
+    /**
+     * Compares this vector with another vector using an epsilon value for floating-point comparison.
+     * @param v - The vector to compare with.
+     * @param epsilon - The maximum difference between components to consider them equal.
+     * @returns True if the vectors are equal within epsilon, false otherwise.
+     */
+    equals(v: Vec2, epsilon?: number): boolean;
+    /**
+     * Scales this vector by a scalar value.
+     * @param c - The scalar value.
+     * @returns This Vec2 instance for method chaining.
+     */
+    scale(c: number): this;
+    /**
+     * Rotates this vector 90 degrees to the left.
+     * @returns This Vec2 instance for method chaining.
+     */
+    turnLeft(): this;
+    /**
+     * Rotates this vector 90 degrees to the right.
+     * @returns This Vec2 instance for method chaining.
+     */
+    turnRight(): this;
+    /**
+     * Sets this vector to zero.
+     * @returns This Vec2 instance for method chaining.
+     */
+    zero(): this;
+    /**
+     * Makes the Vec2 instance iterable.
+     * @yields The x and y components of the vector.
+     */
+    [Symbol.iterator](): IterableIterator<number>;
+    /**
+     * Returns a string representation of the vector.
+     * @returns A string in the format "Vec2(x, y)".
+     */
+    toString(): string;
+    /**
+     * Converts the vector to a plain object.
+     * @returns An object with x and y properties.
+     */
+    toObject(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Serializes the vector to a JSON-friendly format.
+     * @returns A JSON-friendly object representation of the vector.
+     */
+    toJSON(): {
+        x: number;
+        y: number;
+    };
+}