@vived/core 2.0.0 → 2.0.2

package/src/ValueObjects/README.md

@@ -0,0 +1,552 @@
+# ValueObjects
+
+The ValueObjects folder provides immutable, mathematical primitives for 3D graphics, geometry, and data representation. These classes follow the Value Object pattern - they are immutable, comparable by value, and provide rich static methods for common operations.
+
+## Overview
+
+Value objects are designed to be:
+- **Immutable** - Once created, their values cannot change
+- **Comparable** - Equality is based on values, not identity
+- **Self-contained** - Include all operations relevant to their domain
+- **Framework-agnostic** - Pure TypeScript with no external dependencies
+
+## Mathematical Types
+
+### Vector3
+
+3D vector with comprehensive linear algebra operations.
+
+```typescript
+import { Vector3 } from "@vived/core";
+
+// Factory methods
+const zero = Vector3.Zero(); // [0,0,0]
+const one = Vector3.One(); // [1,1,1]
+const up = Vector3.Up(); // [0,1,0]
+const down = Vector3.Down(); // [0,-1,0]
+const right = Vector3.Right(); // [1,0,0]
+const left = Vector3.Left(); // [-1,0,0]
+const forward = Vector3.Forward(); // [0,0,1]
+const backward = Vector3.Backward(); // [0,0,-1]
+
+// Create from components
+const position = new Vector3(10, 20, 30);
+
+// Vector operations
+const a = new Vector3(1, 2, 3);
+const b = new Vector3(4, 5, 6);
+
+const sum = Vector3.Add(a, b);
+const difference = Vector3.Subtract(a, b);
+const dot = Vector3.Dot(a, b);
+const cross = Vector3.Cross(a, b);
+
+// Vector properties
+console.log(a.magnitude); // Length of vector
+console.log(a.unit); // Normalized vector
+console.log(a.array); // [1, 2, 3]
+console.log(a.dto); // { x: 1, y: 2, z: 3 }
+
+// Comparison
+const equal = Vector3.Equal(a, b);
+const close = Vector3.Close(a, b, 0.01); // Within tolerance
+
+// Transformations
+const scaled = Vector3.NewVectorOfLength(a, 10);
+const lerped = Vector3.Lerp(a, b, 0.5); // 50% between a and b
+const transformed = Vector3.Transform(a, matrix);
+
+// Serialization
+const fromArray = Vector3.FromArray([1, 2, 3]);
+const fromDTO = Vector3.FromDTO({ x: 1, y: 2, z: 3 });
+```
+
+### Vector2
+
+2D vector with rotation and geometric operations.
+
+```typescript
+import { Vector2, Angle } from "@vived/core";
+
+// Factory methods
+const zero = Vector2.Zero(); // [0,0]
+const one = Vector2.One(); // [1,1]
+
+// Create and manipulate
+const a = new Vector2(3, 4);
+const b = new Vector2(1, 1);
+
+const sum = Vector2.Add(a, b);
+const difference = Vector2.Subtract(a, b);
+const dot = Vector2.Dot(a, b);
+const cross = Vector2.Cross(a, b); // Returns scalar
+
+// Properties
+console.log(a.magnitude); // 5
+console.log(a.unit); // Normalized vector
+
+// Rotation
+const rotated = Vector2.Rotate(a, Angle.FromDegrees(45));
+
+// Scaling
+const scaled = Vector2.Scale(a, 2);
+const resized = Vector2.NewVectorOfLength(a, 10);
+
+// Angles
+const angleBetween = Vector2.AngleBetween(a, b);
+
+// Comparison
+const equal = Vector2.Equal(a, b);
+const close = Vector2.Close(a, b, 0.01);
+```
+
+### Quaternion
+
+Rotation representation with comprehensive conversion methods.
+
+```typescript
+import { Quaternion, Angle, Vector3 } from "@vived/core";
+
+// Factory methods
+const identity = Quaternion.Identity();
+
+// From angle-axis
+const q1 = Quaternion.FromAngleAxis(
+	Vector3.Up(),
+	Angle.FromDegrees(90)
+);
+
+// From Euler angles
+const q2 = Quaternion.FromEuler(
+	Angle.FromDegrees(0),
+	Angle.FromDegrees(90),
+	Angle.FromDegrees(0)
+);
+
+// From Yaw-Pitch-Roll
+const q3 = Quaternion.FromYawPitchRoll(
+	Angle.FromDegrees(45), // Yaw
+	Angle.FromDegrees(0), // Pitch
+	Angle.FromDegrees(0) // Roll
+);
+
+// From direction vector
+const q4 = Quaternion.FromDirectionVector(Vector3.Forward());
+
+// Operations
+const multiplied = Quaternion.Multiply(q1, q2);
+const inverted = Quaternion.Inverse(q1);
+const angleBetween = Quaternion.AngleBetween(q1, q2);
+
+// Comparison
+const equal = Quaternion.Equal(q1, q2);
+const close = Quaternion.Close(q1, q2, 0.001);
+
+// Conversion to Euler
+const eulerAngles = q1.toEuler(); // { pitch, yaw, roll }
+
+// Serialization
+const array = q1.toArray(); // [x, y, z, w]
+const dto = q1.toDTO(); // { x, y, z, w }
+const fromDTO = Quaternion.FromDTO({ x: 0, y: 0, z: 0, w: 1 });
+```
+
+### Matrix
+
+4x4 transformation matrix for 3D graphics.
+
+```typescript
+import { Matrix, Vector3, Quaternion, Angle } from "@vived/core";
+
+// Factory methods
+const identity = Matrix.Identity();
+const zero = Matrix.Zero();
+
+// Transformation matrices
+const translation = Matrix.Translation(new Vector3(10, 20, 30));
+const scale = Matrix.Scaling(new Vector3(2, 2, 2));
+const rotation = Matrix.RotationYawPitchRoll(
+	Angle.FromDegrees(0),
+	Angle.FromDegrees(90),
+	Angle.FromDegrees(0)
+);
+
+// From quaternion
+const rotationQ = Matrix.FromQuaternion(quaternion);
+
+// Matrix operations
+const product = Matrix.Multiply(translation, rotation);
+const inverted = Matrix.Invert(matrix);
+const transposed = Matrix.Transpose(matrix);
+
+// Decomposition
+const decomposed = matrix.decompose(); // { translation, rotation, scale }
+
+// Comparison
+const equal = Matrix.Equal(m1, m2);
+const close = Matrix.Close(m1, m2, 0.001);
+
+// Access raw data
+const array = matrix.m; // Float32Array of 16 elements
+```
+
+### Angle
+
+Type-safe angle representation with automatic conversion between degrees and radians.
+
+```typescript
+import { Angle } from "@vived/core";
+
+// Create from degrees or radians
+const angle1 = Angle.FromDegrees(90);
+const angle2 = Angle.FromRadians(Math.PI / 2);
+
+// Access both representations
+console.log(angle1.degrees); // 90
+console.log(angle1.radians); // ~1.5708
+
+// Comparison
+const equal = angle1.degrees === angle2.degrees;
+const close = Angle.Close(angle1, angle2, 0.001);
+```
+
+## Geometric Types
+
+### LineSegment2D
+
+2D line segment with intersection and projection operations.
+
+```typescript
+import { LineSegment2D, Vector2 } from "@vived/core";
+
+const line = new LineSegment2D(
+	new Vector2(0, 0),
+	new Vector2(10, 10)
+);
+
+// Properties
+console.log(line.length); // Length of segment
+console.log(line.direction); // Unit direction vector
+
+// Position along line
+const midpoint = LineSegment2D.GetPositionAtPercent(line, 0.5);
+
+// Intersection
+const line2 = new LineSegment2D(
+	new Vector2(0, 10),
+	new Vector2(10, 0)
+);
+const intersection = LineSegment2D.Intersect(line, line2);
+
+// Closest point
+const point = new Vector2(5, 0);
+const closest = LineSegment2D.ClosestPointOnLine(line, point);
+```
+
+### ParametricLine
+
+3D parametric line representation.
+
+```typescript
+import { ParametricLine, Vector3 } from "@vived/core";
+
+// Factory methods
+const forward = ParametricLine.Forward();
+const up = ParametricLine.Up();
+const right = ParametricLine.Right();
+
+// From two points
+const line1 = ParametricLine.FromTwoPoint(
+	new Vector3(0, 0, 0),
+	new Vector3(1, 1, 1)
+);
+
+// From point and direction
+const line2 = ParametricLine.FromPointDirection(
+	Vector3.Zero(),
+	Vector3.Up()
+);
+
+// Get point at distance
+const point = ParametricLine.GetPointAtDistance(line1, 5);
+
+// Properties
+console.log(line1.origin); // Starting point
+console.log(line1.direction); // Direction vector
+```
+
+### ParametricPlane
+
+3D plane representation with intersection calculations.
+
+```typescript
+import { ParametricPlane, Vector3, ParametricLine } from "@vived/core";
+
+// Factory methods
+const xy = ParametricPlane.XY(); // Z = 0
+const zx = ParametricPlane.ZX(); // Y = 0
+const yz = ParametricPlane.YZ(); // X = 0
+
+// From point and normal
+const plane1 = ParametricPlane.FromPointNormal(
+	new Vector3(0, 0, 0),
+	Vector3.Up()
+);
+
+// From three points
+const plane2 = ParametricPlane.FromThreePoints(
+	new Vector3(0, 0, 0),
+	new Vector3(1, 0, 0),
+	new Vector3(0, 1, 0)
+);
+
+// Get plane equation (ax + by + cz + d = 0)
+const params = plane1.GetParameters(); // { a, b, c, d }
+
+// Intersection with line
+const line = ParametricLine.Forward();
+const intersection = plane1.intersectLine(line); // Vector3 or undefined
+```
+
+### Rectangle
+
+2D rectangular bounds.
+
+```typescript
+import { Rectangle } from "@vived/core";
+
+const rect = new Rectangle(
+	0, // top
+	100, // right
+	100, // bottom
+	0 // left
+);
+
+// Properties
+console.log(rect.top);
+console.log(rect.right);
+console.log(rect.bottom);
+console.log(rect.left);
+
+// Serialization
+const dto = rect.dto;
+const fromDTO = Rectangle.FromDTO(dto);
+```
+
+## Color Types
+
+### Color
+
+Immutable color with multiple creation methods and conversions.
+
+```typescript
+import { Color } from "@vived/core";
+
+// Factory methods
+const rgb = Color.RGB(255, 0, 0); // Red
+const rgba = Color.RGBA(255, 0, 0, 128); // Semi-transparent red
+const hex = Color.Hex("#FF0000");
+const x11 = Color.X11("Red"); // X11 color names
+
+// Color properties
+console.log(rgb.r); // 0-255
+console.log(rgb.g);
+console.log(rgb.b);
+console.log(rgb.a);
+
+// As percentages
+console.log(rgb.rPercent); // 0-1
+console.log(rgb.gPercent);
+console.log(rgb.bPercent);
+console.log(rgb.aPercent);
+
+// Conversions
+console.log(rgb.hex); // "#ff0000"
+console.log(rgb.array); // [255, 0, 0, 255]
+console.log(rgb.dto); // { r: 255, g: 0, b: 0, a: 255 }
+
+// Comparison
+const equal = Color.Equal(color1, color2);
+
+// Serialization
+const fromDTO = Color.FromDTO({ r: 255, g: 0, b: 0, a: 255 });
+
+// X11 colors
+// Supports 140+ named colors like:
+// "Red", "Blue", "Green", "White", "Black", "Gray"
+// "LightBlue", "DarkRed", "MediumSeaGreen", etc.
+const blue = Color.X11("Blue");
+```
+
+## Versioning
+
+### Version
+
+Semantic version comparison and management.
+
+```typescript
+import { Version, VersionStage } from "@vived/core";
+
+// Parse version strings
+const v1 = Version.FromString("1.2.3");
+const v2 = Version.FromString("2.0.0-beta");
+
+// Access components
+console.log(v1.major); // 1
+console.log(v1.minor); // 2
+console.log(v1.patch); // 3
+console.log(v2.stage); // VersionStage.BETA
+
+// Find latest version
+const versions = [
+	Version.FromString("1.0.0"),
+	Version.FromString("1.2.0"),
+	Version.FromString("2.0.0")
+];
+const latest = Version.GetLatest(versions); // 2.0.0
+
+// Find latest with specific major
+const latestV1 = Version.GetLatestWithMajor(versions, 1); // 1.2.0
+
+// Find latest with specific major.minor
+const latestV1_2 = Version.GetLatestWithMajorMinor(versions, 1, 2); // 1.2.0
+
+// Version stages
+VersionStage.RELEASED
+VersionStage.BETA
+VersionStage.ALPHA
+```
+
+## Design Principles
+
+### Immutability
+
+All value objects are immutable. Operations return new instances:
+
+```typescript
+const v1 = new Vector3(1, 2, 3);
+const v2 = Vector3.Add(v1, Vector3.One()); // Returns new Vector3
+// v1 remains unchanged
+```
+
+### Static Factory Methods
+
+Use static methods for common operations to avoid creating intermediate objects:
+
+```typescript
+// Good - single object creation
+const result = Vector3.Add(a, b);
+
+// Avoid - creates temporary objects
+const result = a.add(b); // If this existed
+```
+
+### Equality by Value
+
+Value objects are compared by their values, not by reference:
+
+```typescript
+const a = new Vector3(1, 2, 3);
+const b = new Vector3(1, 2, 3);
+
+console.log(a === b); // false (different objects)
+console.log(Vector3.Equal(a, b)); // true (same values)
+```
+
+### DTO Pattern
+
+All complex value objects support Data Transfer Objects for serialization:
+
+```typescript
+// To DTO
+const dto = vector.dto; // { x: 1, y: 2, z: 3 }
+const json = JSON.stringify(dto);
+
+// From DTO
+const parsed = JSON.parse(json);
+const vector = Vector3.FromDTO(parsed);
+```
+
+## Common Patterns
+
+### Transformations
+
+Chain transformations using matrix multiplication:
+
+```typescript
+const translation = Matrix.Translation(new Vector3(10, 0, 0));
+const rotation = Matrix.RotationYawPitchRoll(
+	Angle.FromDegrees(45),
+	Angle.FromDegrees(0),
+	Angle.FromDegrees(0)
+);
+const scale = Matrix.Scaling(new Vector3(2, 2, 2));
+
+// Order matters: Scale -> Rotate -> Translate
+const transform = Matrix.Multiply(
+	translation,
+	Matrix.Multiply(rotation, scale)
+);
+
+const transformed = Vector3.Transform(position, transform);
+```
+
+### Rotations
+
+Use quaternions for smooth rotations:
+
+```typescript
+// Create rotation
+const rotation = Quaternion.FromAngleAxis(
+	Vector3.Up(),
+	Angle.FromDegrees(90)
+);
+
+// Convert to matrix for transformations
+const matrix = Matrix.FromQuaternion(rotation);
+
+// Apply to vector
+const rotated = Vector3.Transform(vector, matrix);
+```
+
+### Interpolation
+
+Lerp between values for smooth animations:
+
+```typescript
+const start = new Vector3(0, 0, 0);
+const end = new Vector3(10, 10, 10);
+
+// Animate from 0% to 100%
+for (let t = 0; t <= 1; t += 0.1)
+{
+	const position = Vector3.Lerp(start, end, t);
+}
+```
+
+## Use Cases
+
+- **3D Graphics** - Position, rotation, scale transformations
+- **Game Development** - Entity positions, camera math, physics
+- **Geometric Calculations** - Ray casting, collision detection, intersection tests
+- **Animation** - Interpolation, rotation, smooth transitions
+- **UI Layout** - 2D positioning, rectangular bounds
+- **Data Serialization** - JSON-safe DTOs for network/storage
+- **Version Management** - Semantic versioning for assets or APIs
+
+## Performance Considerations
+
+- **Immutability overhead** - Creating new objects for each operation has a cost
+- **Use static methods** - Avoid unnecessary object creation
+- **Reuse common values** - Cache frequently used vectors (Zero, One, Up, etc.)
+- **Matrix operations** - Matrix multiplication is computationally expensive
+- **Normalize wisely** - Computing unit vectors involves square roots
+
+## Testing
+
+All value objects include comprehensive test coverage demonstrating:
+- Factory method creation
+- Mathematical operations
+- Equality and comparison
+- Edge cases (zero vectors, identity matrices, etc.)
+- Serialization and deserialization