feat(core): add Velocity type and functions to calculate velocities

Implemented the Velocity type as a Vector2 to represent 2D velocities in the swiperia-core package. Added functions to compute both the velocity vector and scalar velocity between two points, ensuring robust handling with unit tests that cover various scenarios including edge cases like zero time delta.

packages/swiperia-core/src/lib/velocity/Velocity.type.ts

@@ -0,0 +1,6 @@
+import type { Vector2 } from "../vector2/Vector2.type";
+
+/**
+ * Represents the velocity of an object as a 2D vector.
+ */
+export type Velocity = Vector2;

packages/swiperia-core/src/lib/velocity/index.ts

@@ -0,0 +1,2 @@
+export type { Velocity } from './Velocity.type';
+export { velocity, vxvy } from './velocity';

packages/swiperia-core/src/lib/velocity/velocity.spec.ts

@@ -0,0 +1,100 @@
+import { Point } from '../point/Point.type';
+import { Velocity } from './Velocity.type';
+import { velocity, vxvy } from './velocity';
+
+describe('vxvy', () => {
+  it('should calculate velocity correctly for positive coordinates', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = 2;
+    const expectedVelocity: Velocity = [1.5, 2];
+    expect(vxvy(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should calculate velocity correctly for negative coordinates', () => {
+    const a: Point = [-2, 3];
+    const b: Point = [1, -1];
+    const dt = 1;
+    const expectedVelocity: Velocity = [3, -4];
+    expect(vxvy(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should return [0, 0] when points are the same', () => {
+    const a: Point = [5, 5];
+    const b: Point = [5, 5];
+    const dt = 1;
+    const expectedVelocity: Velocity = [0, 0];
+    expect(vxvy(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should handle zero time delta', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = 0;
+    expect(() => vxvy(a, b, dt)).toThrow();
+  });
+});
+describe('vxvy', () => {
+  it('should calculate velocity correctly when time delta is negative', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = -2;
+    expect(() => vxvy(a, b, dt)).toThrow();
+  });
+
+  it('should calculate velocity correctly when points have large coordinates', () => {
+    const a: Point = [1000, -2000];
+    const b: Point = [2000, 3000];
+    const dt = 5;
+    const expectedVelocity: Velocity = [200, 1000];
+    expect(vxvy(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should calculate velocity correctly when points have decimal coordinates', () => {
+    const a: Point = [1.5, 2.7];
+    const b: Point = [4.2, -1.8];
+    const dt = 3;
+    const expectedVelocity: Velocity = [0.9, -1.5];
+    expect(vxvy(a, b, dt)).toEqual(expectedVelocity);
+  });
+});
+
+describe('velocity', () => {
+  it('should calculate velocity correctly for positive coordinates using the velocity function', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = 2;
+    const expectedVelocity = 2.5;
+    expect(velocity(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should calculate velocity correctly for negative coordinates using the velocity function', () => {
+    const a: Point = [-2, 3];
+    const b: Point = [1, -1];
+    const dt = 1;
+    const expectedVelocity = 5;
+    expect(velocity(a, b, dt)).toEqual(expectedVelocity);
+  });
+
+  it('should return NaN when points are the same using the velocity function', () => {
+    const a: Point = [5, 5];
+    const b: Point = [5, 5];
+    const dt = 1;
+    expect(velocity(a, b, dt)).toEqual(0);
+  });
+
+  it('should handle zero time delta using the velocity function', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = 0;
+    expect(() => velocity(a, b, dt)).toThrow();
+  });
+
+  it('should calculate velocity correctly when time delta is negative using the velocity function', () => {
+    const a: Point = [0, 0];
+    const b: Point = [3, 4];
+    const dt = -2;
+    expect(() => velocity(a, b, dt)).toThrow();
+  });
+
+});

packages/swiperia-core/src/lib/velocity/velocity.ts

@@ -0,0 +1,34 @@
+import type { Point } from '../point/Point.type';
+import type { Velocity } from './Velocity.type';
+import { distance } from '../point/distance';
+
+/**
+ * Calculates the velocity vector (vx, vy) between two points over a given time delta.
+ *
+ * @param a - The starting point.
+ * @param b - The ending point.
+ * @param dt - The time delta in seconds.
+ * @returns The velocity vector (vx, vy) in units per second.
+ */
+export const vxvy = (a: Point, b: Point, dt: number): Velocity => {
+  if (dt <= 0) throw new Error('Time delta must be non-zero and positive.');
+  const [ax, ay] = a;
+  const [bx, by] = b;
+  const dx = bx - ax;
+  const dy = by - ay;
+  return [dx / dt, dy / dt];
+};
+
+/**
+ * Calculates the velocity between two points over a given time delta.
+ *
+ * @param a - The starting point.
+ * @param b - The ending point.
+ * @param dt - The time delta in seconds.
+ * @returns The velocity in units per second.
+ */
+export const velocity = (a: Point, b: Point, dt: number): number => {
+  if (dt <= 0) throw new Error('Time delta must be non-zero and positive.');
+  const _distance = distance(a, b);
+  return _distance / dt;
+};