@fimbul-works/vec 1.0.1 → 1.0.3

package/VEC2.md

@@ -0,0 +1,147 @@
+# Vec2
+
+A 2D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec2
+
+- `constructor(x: number = 0, y: number = x)`: Creates a new vector with the given x and y coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number] | number[])`: Creates a Vec2 from an array
+- `fromObject(obj: { x: number; y: number })`: Creates a Vec2 from an object with x and y properties
+- `fromJSON(json: { x: number; y: number })`: Creates a Vec2 from a JSON object
+- `fromPolarCoords(r: number, theta: number)`: Creates a Vec2 from polar coordinates
+- `immutable(x: number = 0, y: number = 0)`: Creates an immutable Vec2-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec2, w: Vec2)`: Adds two vectors
+- `subtract(v: Vec2, w: Vec2)`: Subtracts one vector from another
+- `multiply(v: Vec2, w: Vec2)`: Multiplies two vectors component-wise
+- `divide(v: Vec2, w: Vec2)`: Divides two vectors component-wise
+- `dot(v: Vec2, w: Vec2)`: Calculates the dot product
+- `cross(v: Vec2, w: Vec2)`: Calculates the cross product
+- `scale(v: Vec2, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec2)`: Negates a vector
+- `normalize(v: Vec2)`: Normalizes a vector
+- `project(v: Vec2, w: Vec2)`: Projects one vector onto another
+- `reflect(v: Vec2, normal: Vec2)`: Reflects a vector across a normal vector
+- `lerp(v: Vec2, w: Vec2, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec2, w: Vec2)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec2, w: Vec2)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec2, w: Vec2)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec2, w: Vec2)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec2, w: Vec2, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec2, w: Vec2)`: Calculates angle between vectors
+- `equals(v: Vec2, w: Vec2, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec2)`: Checks if vector has infinite components
+- `isNaN(v: Vec2)`: Checks if vector has NaN components
+- `isZero(v: Vec2)`: Checks if vector is zero
+- `satisfyEquality(v: Vec2, w: Vec2)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec2, w: Vec2)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `xy`: Gets or sets both components as an array
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets or sets the angle with positive x-axis
+- `angleY`: Gets or sets the angle with positive y-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec2)`: Adds another vector
+- `subtract(v: Vec2)`: Subtracts another vector
+- `multiply(v: Vec2)`: Multiplies with another vector
+- `divide(v: Vec2)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec2)`: Projects onto another vector
+- `reflect(normal: Vec2)`: Reflects across a normal vector
+- `rotateZ(phi: number)`: Rotates around Z-axis
+- `turnLeft()`: Rotates 90 degrees left
+- `turnRight()`: Rotates 90 degrees right
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec2)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec2)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec2)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec2)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec2, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec2)`: Calculates angle to another vector
+- `equals(v: Vec2, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec2)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec2)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec2)`: Copies components from another vector
+- `lookAt(v: Vec2)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec2 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x and y components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec2(3, 4);
+const v2 = new Vec2(1, 2);
+
+// Basic operations
+const sum = Vec2.add(v1, v2);
+const dot = Vec2.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .rotate(Math.PI / 4);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y] = v1;
+```

package/VEC3.md

@@ -0,0 +1,159 @@
+# Vec3
+
+A 3D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec3
+
+- `constructor(x: number = 0, y: number = 0, z: number = 0)`: Creates a new vector with the given x, y and z coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number, number] | number[])`: Creates a Vec3 from an array
+- `fromObject(obj: { x: number; y: number; z: number })`: Creates a Vec3 from an object with x, y and z properties
+- `fromJSON(json: { x: number; y: number; z: number })`: Creates a Vec3 from a JSON object
+- `fromCylindricalCoords(r: number, phi: number, z: number)`: Creates a Vec3 from cylindrical coordinates
+- `fromSphericalCoords(r: number, theta: number, phi: number)`: Creates a Vec3 from spherical coordinates
+- `immutable(x: number = 0, y: number = 0, z: number = 0)`: Creates an immutable Vec3-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec3, w: Vec3)`: Adds two vectors
+- `subtract(v: Vec3, w: Vec3)`: Subtracts one vector from another
+- `multiply(v: Vec3, w: Vec3)`: Multiplies two vectors component-wise
+- `divide(v: Vec3, w: Vec3)`: Divides two vectors component-wise
+- `dot(v: Vec3, w: Vec3)`: Calculates the dot product
+- `cross(v: Vec3, w: Vec3)`: Calculates the cross product
+- `scale(v: Vec3, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec3)`: Negates a vector
+- `normalize(v: Vec3)`: Normalizes a vector
+- `project(v: Vec3, w: Vec3)`: Projects one vector onto another
+- `reflect(v: Vec3, normal: Vec3)`: Reflects a vector across a normal vector
+- `lerp(v: Vec3, w: Vec3, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec3, w: Vec3)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec3, w: Vec3)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec3, w: Vec3)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec3, w: Vec3)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec3, w: Vec3, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec3, w: Vec3)`: Calculates angle between vectors
+- `equals(v: Vec3, w: Vec3, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec3)`: Checks if vector has infinite components
+- `isNaN(v: Vec3)`: Checks if vector has NaN components
+- `isZero(v: Vec3)`: Checks if vector is zero
+- `satisfyEquality(v: Vec3, w: Vec3)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec3, w: Vec3)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `z`: Gets or sets the z-component
+- `xyz`: Gets or sets all components as an array
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets the angle with positive x-axis
+- `angleY`: Gets the angle with positive y-axis
+- `angleZ`: Gets the angle with positive z-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec3)`: Adds another vector
+- `subtract(v: Vec3)`: Subtracts another vector
+- `multiply(v: Vec3)`: Multiplies with another vector
+- `divide(v: Vec3)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec3)`: Projects onto another vector
+- `reflect(normal: Vec3)`: Reflects across a normal vector
+- `rotateX(phi: number)`: Rotates around X-axis
+- `rotateY(phi: number)`: Rotates around Y-axis
+- `rotateZ(phi: number)`: Rotates around Z-axis
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec3)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec3)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec3)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec3)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec3, p: number)`: Calculates Minkowski distance
+
+### Cross Product
+
+- `cross(v: Vec3)`: Calculates the cross product with another vector
+
+### Comparison and State
+
+- `angleBetween(v: Vec3)`: Calculates angle to another vector
+- `equals(v: Vec3, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec3)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec3)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec3)`: Copies components from another vector
+- `lookAt(v: Vec3)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec3 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x, y, and z components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec3(3, 4, 5);
+const v2 = new Vec3(1, 2, 3);
+
+// Basic operations
+const sum = Vec3.add(v1, v2);
+const crossProduct = Vec3.cross(v1, v2);
+const dot = Vec3.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .rotateX(Math.PI / 4);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y, z] = v1;
+
+// Create from special coordinates
+const cylindrical = Vec3.fromCylindricalCoords(2, Math.PI/4, 5);
+const spherical = Vec3.fromSphericalCoords(2, Math.PI/3, Math.PI/4);
+```

package/VEC4.md

@@ -0,0 +1,146 @@
+# Vec4
+
+A 4D vector implementation with comprehensive mathematical operations and utility methods.
+
+## Constructor
+
+### Vec4
+
+- `constructor(x: number = 0, y: number = 0, z: number = 0, w: number = 0)`: Creates a new vector with the given x, y, z, and w coordinates
+
+## Static Methods
+
+### Creation and Conversion
+
+- `fromArray(arr: [number, number, number, number] | number[])`: Creates a Vec4 from an array
+- `fromObject(obj: { x: number; y: number; z: number; w: number })`: Creates a Vec4 from an object with x, y, z, and w properties
+- `fromJSON(json: { x: number; y: number; z: number; w: number })`: Creates a Vec4 from a JSON object
+- `immutable(x: number = 0, y: number = 0, z: number = 0, w: number = 0)`: Creates an immutable Vec4-like object
+- `one()`: Creates a vector with all components set to 1.0
+- `random(random: () => number = Math.random)`: Creates a random unit vector
+- `zero()`: Creates a zero vector
+
+### Vector Operations
+
+- `add(v: Vec4, w: Vec4)`: Adds two vectors
+- `subtract(v: Vec4, w: Vec4)`: Subtracts one vector from another
+- `multiply(v: Vec4, w: Vec4)`: Multiplies two vectors component-wise
+- `divide(v: Vec4, w: Vec4)`: Divides two vectors component-wise
+- `dot(v: Vec4, w: Vec4)`: Calculates the dot product
+- `scale(v: Vec4, c: number)`: Scales a vector by a scalar value
+- `negate(v: Vec4)`: Negates a vector
+- `normalize(v: Vec4)`: Normalizes a vector
+- `project(v: Vec4, w: Vec4)`: Projects one vector onto another
+- `reflect(v: Vec4, normal: Vec4)`: Reflects a vector across a normal vector
+- `lerp(v: Vec4, w: Vec4, t: number)`: Performs linear interpolation between vectors
+
+### Distance Calculations
+
+- `distance(v: Vec4, w: Vec4)`: Calculates Euclidean distance between vectors
+- `distanceSq(v: Vec4, w: Vec4)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec4, w: Vec4)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec4, w: Vec4)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec4, w: Vec4, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec4, w: Vec4)`: Calculates angle between vectors
+- `equals(v: Vec4, w: Vec4, epsilon?: number)`: Compares vectors with optional epsilon
+- `isInfinite(v: Vec4)`: Checks if vector has infinite components
+- `isNaN(v: Vec4)`: Checks if vector has NaN components
+- `isZero(v: Vec4)`: Checks if vector is zero
+- `satisfyEquality(v: Vec4, w: Vec4)`: Checks if vectors are equal
+- `satisfyOpposition(v: Vec4, w: Vec4)`: Checks if vectors are opposite
+
+## Instance Properties
+
+### Getters and Setters
+
+- `x`: Gets or sets the x-component
+- `y`: Gets or sets the y-component
+- `z`: Gets or sets the z-component
+- `w`: Gets or sets the w-component
+- `xyzw`: Gets or sets all components as an array
+- `magnitude`: Gets or sets the vector's magnitude
+- `magnitudeSq`: Gets the squared magnitude (read-only)
+- `angleX`: Gets the angle with positive x-axis
+- `angleY`: Gets the angle with positive y-axis
+- `angleZ`: Gets the angle with positive z-axis
+- `angleW`: Gets the angle with positive w-axis
+
+## Instance Methods
+
+### Vector Operations
+
+- `add(v: Vec4)`: Adds another vector
+- `subtract(v: Vec4)`: Subtracts another vector
+- `multiply(v: Vec4)`: Multiplies with another vector
+- `divide(v: Vec4)`: Divides by another vector
+- `scale(c: number)`: Scales by a scalar value
+- `normalize()`: Normalizes the vector
+- `negate()`: Negates the vector
+- `project(v: Vec4)`: Projects onto another vector
+- `reflect(normal: Vec4)`: Reflects across a normal vector
+- `zero()`: Sets to zero vector
+- `random(random?: () => number)`: Sets to random direction
+
+### Distance Calculations
+
+- `distance(v: Vec4)`: Calculates Euclidean distance to another vector
+- `distanceSq(v: Vec4)`: Calculates squared Euclidean distance
+- `distanceChebyshev(v: Vec4)`: Calculates Chebyshev distance
+- `distanceManhattan(v: Vec4)`: Calculates Manhattan distance
+- `distanceMinkowski(v: Vec4, p: number)`: Calculates Minkowski distance
+
+### Comparison and State
+
+- `angleBetween(v: Vec4)`: Calculates angle to another vector
+- `equals(v: Vec4, epsilon?: number)`: Compares with another vector
+- `isInfinite()`: Checks for infinite components
+- `isNaN()`: Checks for NaN components
+- `isZero()`: Checks if zero vector
+- `satisfyEquality(v: Vec4)`: Checks equality with another vector
+- `satisfyOpposition(v: Vec4)`: Checks opposition with another vector
+
+### Magnitude Operations
+
+- `clamp(min: number, max: number)`: Clamps magnitude between values
+- `limitMax(max: number)`: Limits maximum magnitude
+- `limitMin(min: number)`: Limits minimum magnitude
+
+### Utility Methods
+
+- `clone()`: Creates a copy of the vector
+- `copy(v: Vec4)`: Copies components from another vector
+- `lookAt(v: Vec4)`: Points towards another vector
+- `toString()`: Returns string representation
+- `toObject()`: Converts to plain object
+- `toJSON()`: Converts to JSON format
+
+## Iteration
+
+Vec4 implements the iterator protocol, allowing it to be used with for...of loops and spread operators. The iterator yields the x, y, z, and w components in order.
+
+## Example Usage
+
+```typescript
+// Create vectors
+const v1 = new Vec4(1, 2, 3, 1);  // Homogeneous coordinates
+const v2 = new Vec4(0, 1, 0, 0);  // Direction vector
+
+// Basic operations
+const sum = Vec4.add(v1, v2);
+const dot = Vec4.dot(v1, v2);
+
+// Method chaining
+v1.normalize()
+  .scale(2)
+  .limitMax(5);
+
+// Get properties
+console.log(v1.magnitude);
+console.log(v1.angleX);
+
+// Convert to array
+const [x, y, z, w] = v1;
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fimbul-works/vec",
-  "version": "1.0.1",
-  "description": "A high-performance vector math library for TypeScript",
+  "version": "1.0.3",
+  "description": "A comprehensive TypeScript vector math library providing 2D, 3D, and 4D vector operations with a focus on performance and type safety.",
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -31,7 +31,7 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": ["dist", "README.md", "VEC2.md", "VEC3.md", "VEC4.md", "LICENSE"],
   "sideEffects": false,
   "scripts": {
     "dev": "tsc --watch",