feat: add vector2 type (#110)

* Fixed documentation and param names on Vector3 function.

* Improved documentation and param names

* Barebones implementation of Vector2

* Updated api.md

* lint-fix pass

etc/ecs-math.api.md

@@ -234,13 +234,34 @@ export const ToGammaSpace: number;
 // @public
 export const ToLinearSpace = 2.2;
 
+// @public
+export type Vector2 = Vector2.ReadonlyVector2;
+
+// @public
+export namespace Vector2 {
+    export function create(
+    x?: number,
+    y?: number): MutableVector2;
+    export type Mutable = MutableVector2;
+    export type MutableVector2 = {
+        x: number;
+        y: number;
+    };
+    export function One(): MutableVector2;
+    export type ReadonlyVector2 = {
+        readonly x: number;
+        readonly y: number;
+    };
+    export function Zero(): MutableVector2;
+}
+
 // @public
 export type Vector3 = Vector3.ReadonlyVector3;
 
 // @public
 export namespace Vector3 {
     export function add(vector1: ReadonlyVector3, vector2: ReadonlyVector3): MutableVector3;
-    export function addToRef(vector1: ReadonlyVector3, vector2: ReadonlyVector3, result: MutableVector3): void;
+    export function addToRef(vectorA: ReadonlyVector3, vectorB: ReadonlyVector3, result: MutableVector3): void;
     export function applyMatrix4(vector: ReadonlyVector3, matrix: Matrix.ReadonlyMatrix): MutableVector3;
     export function applyMatrix4ToRef(vector: ReadonlyVector3, matrix: Matrix.ReadonlyMatrix, result: MutableVector3): void;
     export function Backward(): MutableVector3;
@@ -318,7 +339,7 @@ export namespace Vector3 {
     export function scaleToRef(vector: ReadonlyVector3, scale: number, result: MutableVector3): void;
     export function subtract(vector1: ReadonlyVector3, vector2: ReadonlyVector3): MutableVector3;
     export function subtractFromFloatsToRef(vector1: ReadonlyVector3, x: number, y: number, z: number, result: MutableVector3): void;
-    export function subtractToRef(vector1: ReadonlyVector3, vector2: ReadonlyVector3, result: MutableVector3): void;
+    export function subtractToRef(vectorA: ReadonlyVector3, vectorB: ReadonlyVector3, result: MutableVector3): void;
     export function toString(vector: ReadonlyVector3): string;
     export function transformCoordinates(vector: ReadonlyVector3, transformation: Matrix.ReadonlyMatrix): MutableVector3;
     export function transformCoordinatesFromFloatsToRef(x: number, y: number, z: number, transformation: Matrix.ReadonlyMatrix, result: MutableVector3): void;

src/Vector2.ts

@@ -0,0 +1,98 @@
+/**
+ * @public
+ * Vector2 is a type and a namespace.
+ * - The namespace contains all types and functions to operates with Vector2
+ * - The type Vector2 is an alias to Vector2.ReadonlyVector2
+ * ```
+ *
+ * // Namespace usage example
+ * const next = Vector2.add(pointA, velocityA) // add function not implemented yet
+ *
+ * // Type usage example
+ * const readonlyPosition: Vector2 = Vector2.Zero()
+ * readonlyPosition.x = 0.1 // this FAILS
+ *
+ * // For mutable usage, use `Vector2.Mutable`
+ * const position: Vector2.Mutable = Vector2.One()
+ * position.x = 3.0 // this WORKS
+ * ```
+ */
+export type Vector2 = Vector2.ReadonlyVector2
+
+/**
+ * @public
+ * Vector2 is a type and a namespace.
+ * ```
+ * // The namespace contains all types and functions to operates with Vector2
+ * const next = Vector2.add(pointA, velocityA) // add function not implemented yet
+ * // The type Vector2 is an alias to Vector2.ReadonlyVector2
+ * const readonlyPosition: Vector2 = Vector2.Zero()
+ * readonlyPosition.x = 0.1 // this FAILS
+ *
+ * // For mutable usage, use `Vector2.Mutable`
+ * const position: Vector2.Mutable = Vector2.One()
+ * position.x = 3.0 // this WORKS
+ * ```
+ */
+export namespace Vector2 {
+  /**
+   * @public
+   * For external use, type with `Vector2`, e.g. `const zeroPosition: Vector2 = Vector2.Zero()`.
+   * For mutable typing, use `Vector2.Mutable`, e.g. `const oneVector: Vector2.Mutable = Vector2.One()`.
+   */
+  export type ReadonlyVector2 = {
+    readonly x: number
+    readonly y: number
+  }
+
+  /**
+   * @public
+   * For external usage, type with `Vector2`, e.g. `const zeroPosition: Vector2 = Vector2.Zero()`.
+   * For mutable typing, use `Vector2.Mutable`, e.g. `const oneVector: Vector2.Mutable = Vector2.One()`.
+   */
+  export type MutableVector2 = {
+    x: number
+    y: number
+  }
+
+  /**
+   * @public
+   * Type with `Vector2` for readonly usage, e.g. `const zeroPosition: Vector2 = Vector2.Zero()`.
+   * For mutable, use `Vector2.Mutable`, e.g. `const oneVector: Vector2.Mutable = Vector2.One()`.
+   */
+  export type Mutable = MutableVector2
+
+  /**
+   * Creates a new Vector2 object from the given x, y (floats) coordinates.
+   * @param x - defines the first coordinates (on X axis)
+   * @param y - defines the second coordinates (on Y axis)
+   */
+  export function create(
+    /**
+     * Defines the first coordinates (on X axis)
+     */
+    x: number = 0,
+    /**
+     * Defines the second coordinates (on Y axis)
+     */
+    y: number = 0
+  ): MutableVector2 {
+    return { x, y }
+  }
+
+  /**
+   * Returns a new Vector2 set to (0.0, 0.0)
+   * @returns a new empty Vector2
+   */
+  export function Zero(): MutableVector2 {
+    return create(0.0, 0.0)
+  }
+
+  /**
+   * Returns a new Vector2 set to (1.0, 1.0)
+   * @returns a new unit Vector2
+   */
+  export function One(): MutableVector2 {
+    return create(1.0, 1.0)
+  }
+}

src/Vector3.ts

@@ -129,18 +129,19 @@ export namespace Vector3 {
   }
 
   /**
-   * Add component by component the vector2 into dest
-   * @param dest - the first vector and destination of addition
-   * @param vector2 - the second vector
+   * Performs addition between vectorA and vectorB and stores the result into result
+   * @param vectorA - the first vector for the addition operation
+   * @param vectorB - the second vector for the addition operation
+   * @param result - the vector where the result of the addition is stored
    */
   export function addToRef(
-    vector1: ReadonlyVector3,
-    vector2: ReadonlyVector3,
+    vectorA: ReadonlyVector3,
+    vectorB: ReadonlyVector3,
     result: MutableVector3
   ): void {
-    result.x = vector1.x + vector2.x
-    result.y = vector1.y + vector2.y
-    result.z = vector1.z + vector2.z
+    result.x = vectorA.x + vectorB.x
+    result.y = vectorA.y + vectorB.y
+    result.z = vectorA.z + vectorB.z
   }
 
   /**
@@ -159,17 +160,19 @@ export namespace Vector3 {
   }
 
   /**
-   * Returns a new Vector3 as the result of the substraction of the two given vectors.
-   * @returns the resulting vector
+   * Performs substraction between vectorA and vectorB and stores the result into result
+   * @param vectorA - the first vector for the substraction operation
+   * @param vectorB - the second vector for the substraction operation
+   * @param result - the vector where the result of the substraction is stored
    */
   export function subtractToRef(
-    vector1: ReadonlyVector3,
-    vector2: ReadonlyVector3,
+    vectorA: ReadonlyVector3,
+    vectorB: ReadonlyVector3,
     result: MutableVector3
   ): void {
-    result.x = vector1.x - vector2.x
-    result.y = vector1.y - vector2.y
-    result.z = vector1.z - vector2.z
+    result.x = vectorA.x - vectorB.x
+    result.y = vectorA.y - vectorB.y
+    result.z = vectorA.z - vectorB.z
   }
 
   /**

src/index.ts

@@ -1,8 +1,8 @@
 export * from './Quaternion'
+export * from './Vector2'
 export * from './Vector3'
 export * from './Color3'
 export * from './Color4'
-export * from './Vector3'
 export * from './Scalar'
 export * from './types'
 export * from './index'

test/vector2.spec.ts

@@ -0,0 +1,25 @@
+import { Vector2 } from '../src/Vector2'
+
+const results = {
+  zeros: '(0.0, 0.0)',
+  ones: '(1.0, 1.0)'
+}
+
+const normalize = (v: string) => (v === '-0.0' ? '0.0' : v)
+
+function vector2ToString(vec: Vector2.MutableVector2) {
+  const x = normalize(vec.x.toFixed(1).slice(0, 6))
+  const y = normalize(vec.y.toFixed(1).slice(0, 6))
+
+  return `(${x}, ${y})`
+}
+
+describe('ECS Vector2 - Next tests', () => {
+  it('Vector2.create One', () => {
+    expect(vector2ToString(Vector2.One())).toEqual(results.ones)
+  })
+
+  it('Vector3.create zeros', () => {
+    expect(vector2ToString(Vector2.Zero())).toEqual(results.zeros)
+  })
+})

test/vector3.spec.ts

@@ -26,7 +26,6 @@ function vector3ToString(vec: Vector3.MutableVector3) {
 describe('ECS Vector3 - Next tests', () => {
   it('Vector3.create One', () => {
     expect(vector3ToString(Vector3.One())).toEqual(results.ones)
-    Vector3.Random()
   })
 
   it('Vector3.create zeros', () => {