📦 Vector3D

A robust and type-safe 3D vector math library for JavaScript and TypeScript projects.

🎯 Why Choose Vector3D?

Vector3D provides a comprehensive and intuitive API for performing common 3D vector operations. Built with TypeScript, it offers strong type safety, enhancing code reliability and developer experience. This library is designed for performance and ease of integration into any project requiring efficient 3D mathematical computations, from game development to graphics applications.

✨ Features

• Vector Initialization: Easily create 3D vectors from components or other vectors.
• Basic Arithmetic: Perform addition, subtraction, multiplication, and division of vectors and scalars.
• Scalar Operations: Scale, negate, and clamp vector components.
• Geometric Calculations: Compute dot products, cross products, magnitudes (lengths), distances, and normalize vectors.
• Comparison: Check for vector equality with optional tolerance.
• Utility Methods: Clone vectors, set components, and provide immutable operations for safer state management.
• Type-Safe API: Fully written in TypeScript for robust development and compile-time error checking.

🚀 Installation

To use Vector3D in your project, install it via npm:

npm install @lzimul/vector3d

📖 Quick Start

Import the @lzimul/vector3d class and start performing 3D operations.

import { Vector3D } from '@lzimul/vector3d'; // Assuming main export

// Create vectors
const vecA = new Vector3D(1, 2, 3);
const vecB = new Vector3D(4, 5, 6);

// Perform addition
const sum = vecA.add(vecB); // Returns a new Vector3D (5, 7, 9)

// Calculate dot product
const dotProduct = vecA.dot(vecB); // Returns a number (1*4 + 2*5 + 3*6 = 32)

// Normalize a vector
const normalizedVecA = vecA.normalize();

// Get magnitude (length)
const magnitude = vecA.magnitude();

// Chain operations
const result = new Vector3D(10, 20, 30)
    .subtract(vecA)
    .scale(0.5)
    .add(normalizedVecA);

console.log('Vector A:', vecA.toString());
console.log('Vector B:', vecB.toString());
console.log('Sum:', sum.toString());
console.log('Dot Product:', dotProduct);
console.log('Normalized A:', normalizedVecA.toString());
console.log('Magnitude A:', magnitude);
console.log('Chained Result:', result.toString());

📚 API Documentation

Detailed API documentation, including all methods, parameters, and examples, can be generated using TypeDoc.

To generate the documentation locally:

1. Clone the repository.
2. Install development dependencies: npm install
3. Run the docs script: npm run docs

The generated documentation will be available in the docs directory.

📁 Project Structure

Vector3D/
├── .github/                 # GitHub specific configurations (e.g., workflows, issue templates)
├── .idea/                   # IDE (IntelliJ/WebStorm) project configuration
├── src/                     # Source code directory for the Vector3D library
│   └── (vector-related files) # e.g., index.ts, Vector3D.ts, operations.ts
├── .gitignore               # Specifies intentionally untracked files to ignore
├── .prettierrc              # Prettier configuration for code formatting
├── LICENSE                  # MIT License file
├── README.md                # Project README file
├── SECURITY.md              # Security policy documentation
├── eslint.config.js         # ESLint configuration for code linting
├── package-lock.json        # npm lock file, detailing dependency tree
├── package.json             # Project metadata, scripts, and dependencies
├── tsconfig.json            # TypeScript compiler configuration
└── typedoc.json             # TypeDoc configuration for API documentation generation

🛠️ Tech Stack

• Language:
• Package Manager:
• Build Tool:
• Testing:
• Linting:
• Formatting:
• Documentation:

🔧 Development

Prerequisites

• Node.js (LTS recommended)
• npm (comes with Node.js)

Installation for Development

1. Clone the repository

   git clone https://github.com/lZiMUl/Vector3D.git
   cd Vector3D

2. Install dependencies

   npm install

Available Scripts

| Command | Description |

| :-------------- | :---------------------------------------------- |

| npm run build | Compiles the TypeScript source code to JavaScript. |

| npm run test | Runs the test suite using Jest. |

| npm run lint | Lints the codebase using ESLint. |

| npm run format| Formats the code using Prettier. |

| npm run docs | Generates API documentation using TypeDoc. |

Building the Library

To compile the TypeScript source files into JavaScript, run:

npm run build

This will output the compiled files to the dist directory.

🧪 Testing

The project uses Jest for testing. To run the tests:

npm run test

🤝 Contributing to Vector3D

We welcome contributions! If you have suggestions for improvements, new features, or bug fixes, please open an issue or submit a pull request.

Please ensure your code adheres to the project's coding style and passes all tests and linting checks.

Contribution Guidelines:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Make your changes.
4. Run tests (npm run test) and linting (npm run lint).
5. Commit your changes (git commit -am 'feat: Add new feature').
6. Push to the branch (git push origin feature/your-feature).
7. Open a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by various vector math libraries in game development and graphics.
• Built with modern TypeScript tooling for a robust development experience.

📞 Support & Contact

• 🐛 Issues: GitHub Issues

⭐ Star this repo if you find it helpful!

Made with ❤️ by lZiMUl