@fimbul-works/vec/README.md

A comprehensive TypeScript vector math library providing 2D, 3D, and 4D vector operations with a focus on performance and type safety.

# @fimbul-works/vec

A high-performance TypeScript vector math library providing both **functional** and **object-oriented** APIs for 2D, 3D, and 4D vector operations with a focus on performance, type safety, and immutability.

[![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)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@fimbul-works/vec)](https://bundlephobia.com/package/@fimbul-works/vec)

## ✨ Highlights

- **🎯 Two API Styles**: Choose between modern functional API (arrays) or classic OOP API (classes)
- **🛡️ Type Safe**: Full TypeScript support with strict typing and array tuple types
- **📏 Multiple Distance Metrics**: Euclidean, Manhattan, Chebyshev, and Minkowski
- **🎮 Graphics Ready**: Homogeneous coordinates and RGB/RGBA color support
- **🧮 Comprehensive**: Complete set of vector operations for game dev, graphics, and physics
- **🌳 Tree-Shakeable**: Import only what you need with the functional API

## 📦 Installation

```bash
npm install @fimbul-works/vec
```

## 🚀 Quick Start

### Functional API (Recommended)

The **functional API** uses array tuples and is recommended for new projects:

```typescript
// Import the functional API
import { add2D, magnitude2D, dot2D, normalize2D } from "@fimbul-works/vec/2d";
import { add3D, cross3D } from "@fimbul-works/vec/3d";

// Type: ArrayVector2D = [number, number]
const position: ArrayVector2D = [100, 200];
const velocity: ArrayVector2D = [5, 10];

// Immutable operations return new arrays
const newPosition = add2D(position, velocity); // [105, 210]
const speed = magnitude2D(velocity); // 11.18...

// 3D operations
const v1: ArrayVector3D = [1, 2, 3];
const v2: ArrayVector3D = [4, 5, 6];
const sum = add3D(v1, v2); // [5, 7, 9]
const cross = cross3D(v1, v2); // [-3, 6, -3]

// Chain operations functionally
const result = normalize2D(add2D(position, velocity));
```

**Benefits of the Functional API:**
- ✅ Immutable - data never changes unexpectedly
- ✅ Tree-shakeable - smaller bundles
- ✅ Simple - just functions and arrays
- ✅ Pattern-matching ready - works with destructuring

### OOP API (Legacy)

The **OOP API** uses mutable classes and is maintained for backward compatibility:

```typescript
import { Vec2, Vec3, Vec4 } from "@fimbul-works/vec";

// Create and manipulate vectors
const position = new Vec2(100, 200);
const velocity = new Vec2(5, 10);

position.add(velocity); // Mutates position

// Method chaining
const result = new Vec3(1, 0, 0)
  .rotateY(Math.PI / 4)
  .scale(2)
  .normalize();

// 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 with RGB accessors
const color = new Vec3(0.8, 0.2, 0.4);
color.r = 1.0; // Set red component
```

## 📖 API Documentation

Complete API documentation generated by TypeDoc:

### Functional API
- **[2D Vector Functions](./docs/ArrayVector2D.md)** - Complete 2D functional API reference
- **[3D Vector Functions](./docs/ArrayVector3D.md)** - Complete 3D functional API reference
- **[4D Vector Functions](./docs/ArrayVector4D.md)** - Complete 4D functional API reference
- **[Spherical Interpolation Functions](./docs/Slerp.md)** - Spherical Interpolation API reference

### OOP API (Legacy)
- **[Vec2 Class](./docs/Vec2.md)** - Complete Vec2 class documentation
- **[Vec3 Class](./docs/Vec3.md)** - Complete Vec3 class documentation
- **[Vec4 Class](./docs/Vec4.md)** - Complete Vec4 class documentation

## 🎯 Common Operations

### Functional API Examples

```typescript
import {
  add2D, subtract2D, multiply2D, divide2D,
  dot2D, cross2D,
  magnitude2D, normalize2D, negate2D,
  distance2D, distanceManhattan2D, distanceChebyshev2D,
  lerp2D, clamp2D, limitMax2D, limitMin2D,
  rotate2D, reflect2D, project2D,
  angleBetween2D, angleX2D, angleY2D
} from "@fimbul-works/vec/2d";

// Vector arithmetic
const v1: ArrayVector2D = [3, 4];
const v2: ArrayVector2D = [1, 2];

add2D(v1, v2);        // [4, 6]  - Addition
subtract2D(v1, v2);   // [2, 2]  - Subtraction
multiply2D(v1, v2);   // [3, 8]  - Component-wise multiplication
divide2D(v1, v2);     // [3, 2]  - Component-wise division

// Products
dot2D(v1, v2);        // 11      - Dot product
cross2D(v1, v2);      // 2       - 2D cross product (returns scalar)

// Magnitude & normalization
magnitude2D(v1);      // 5       - Vector length
normalize2D(v1);     // [0.6, 0.8] - Unit vector
negate2D(v1);        // [-3, -4] - Opposite direction

// Distance metrics
distance2D(v1, v2);           // 3.606  - Euclidean distance
distanceManhattan2D(v1, v2);   // 4      - Manhattan distance
distanceChebyshev2D(v1, v2);   // 2      - Chebyshev distance

// Interpolation & clamping
lerp2D(v1, v2, 0.5);  // [2, 3]  - Linear interpolation
clamp2D(v1, 2, 8);     // Keeps magnitude between 2 and 8
limitMax2D(v1, 3);     // Limits magnitude to maximum of 3
limitMin2D(v1, 6);     // Ensures magnitude is at least 6

// Rotation & reflection
rotate2D(v1, Math.PI / 2);  // [-4, 3] - Rotate 90°
reflect2D(v1, v2);          // Reflection

// Angles
angleBetween2D(v1, v2);  // Angle between vectors in radians
angleX2D(v1);            // Angle with x-axis
```

### Homogeneous Coordinates (4D)

```typescript
// 3D point: w = 1
const point: ArrayVector4D = [x, y, z, 1];

// 3D direction: w = 0
const direction: ArrayVector4D = [dx, dy, dz, 0];
```

## 🔄 Migration from OOP to Functional

Migrating from the OOP API to the functional API is straightforward:

| OOP (Vec2) | Functional (2D) |
|-----------|-----------------|
| `new Vec2(x, y)` | `[x, y]` as `ArrayVector2D` |
| `Vec2.add(v1, v2)` | `add2D(v1, v2)` |
| `v1.add(v2)` | `add2D(v1, v2)` |
| `v.x` | `v[0]` |
| `v.y` | `v[1]` |
| `v.magnitude` | `magnitude2D(v)` |
| `v.normalize()` | `normalize2D(v)` |

**Key differences:**
- Functional API is **immutable** - returns new arrays instead of mutating
- Uses **array indexing** `[0], [1]` instead of properties `.x, .y`
- Functions are **standalone** instead of class methods

## 📦 Import Paths

```typescript
// Functional API (Recommended)
import { add2D } from "@fimbul-works/vec/2d";
import { add3D } from "@fimbul-works/vec/3d";
import { add4D } from "@fimbul-works/vec/4d";

// OOP API (Legacy)
import { Vec2 } from "@fimbul-works/vec/vec2";
import { Vec3 } from "@fimbul-works/vec/vec3";
import { Vec4 } from "@fimbul-works/vec/vec4";

// Types
import type { ArrayVector2D } from "@fimbul-works/vec/2d";
import type { ArrayVector3D } from "@fimbul-works/vec/3d";
import type { ArrayVector4D } from "@fimbul-works/vec/4d";
```

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details.

---

Built with ⚡ by [FimbulWorks](https://github.com/fimbul-works)