(#130) Introduce EasingFunction interface (#304)

* (#130) Updated implementation

* (#130) Easing function refinement

Author: s1hofmann

index.ts

@@ -31,7 +31,7 @@ export {Button} from "./lib/button.enum";
 export {centerOf, randomPointIn} from "./lib/location.function";
 export {LocationParameters} from "./lib/locationparameters.class";
 export {OptionalSearchParameters} from "./lib/optionalsearchparameters.class";
-export {linear} from "./lib/movementtype.function";
+export {EasingFunction, linear} from "./lib/mouse-movement.function";
 export {Point} from "./lib/point.class";
 export {Region} from "./lib/region.class";
 export {Window} from "./lib/window.class";

lib/mouse-movement.function.spec.ts

@@ -0,0 +1,80 @@
+import {
+    calculateStepDuration,
+    linear,
+    calculateMovementTimesteps, EasingFunction
+} from "./mouse-movement.function";
+
+describe("MovementType", () => {
+    describe("baseStepDuration", () => {
+        it("should calculate the base step duration in nanoseconds", () => {
+            // GIVEN
+            const speedInPixelsPerSecond = 1000;
+            const expectedBaseStepDuration = 1_000_000;
+
+            // WHEN
+            const result = calculateStepDuration(speedInPixelsPerSecond);
+
+            // THEN
+            expect(result).toBe(expectedBaseStepDuration);
+        });
+    });
+
+    describe("stepDuration", () => {
+        it("should call easing function progress to calculate current step duration", () => {
+            // GIVEN
+            const amountOfSteps = 100;
+            const speedInPixelsPerSecond = 1000;
+            const easingFunction = jest.fn(() => 0);
+
+            // WHEN
+            calculateMovementTimesteps(amountOfSteps, speedInPixelsPerSecond, easingFunction);
+
+            // THEN
+            expect(easingFunction).toBeCalledTimes(amountOfSteps);
+        })
+    });
+
+    describe('linear', () => {
+        it("should return a set of linear timesteps, 1000000 nanosecond per step.", () => {
+            // GIVEN
+            const expected = [1000000, 1000000, 1000000, 1000000, 1000000, 1000000];
+
+            // WHEN
+            const result = calculateMovementTimesteps(6, 1000, linear);
+
+            // THEN
+            expect(result).toEqual(expected);
+        });
+
+        it("should should return a set of linear timesteps, 2000000 nanoseconds per step.", () => {
+            // GIVEN
+            const expected = [2000000, 2000000, 2000000, 2000000, 2000000, 2000000];
+
+            // WHEN
+            const result = calculateMovementTimesteps(6, 500, linear);
+
+            // THEN
+            expect(result).toEqual(expected);
+        });
+    });
+
+    describe('non-linear', () => {
+        it("should return progress slowly in the first half, 2000000 nanoseconds per step, then continue with normal speed, 1000000 nanoseconds per step", () => {
+            // GIVEN
+            const mouseSpeed = 1000;
+            const easingFunction: EasingFunction = (p: number) => {
+                if (p < 0.5) {
+                    return -0.5 * mouseSpeed;
+                }
+                return 0;
+            };
+            const expected = [2000000, 2000000, 2000000, 1000000, 1000000, 1000000];
+
+            // WHEN
+            const result = calculateMovementTimesteps(6, mouseSpeed, easingFunction);
+
+            // THEN
+            expect(result).toEqual(expected);
+        });
+    });
+});

lib/mouse-movement.function.ts

@@ -0,0 +1,31 @@
+/**
+ * {@link EasingFunction}s are used to modify movement behaviour.
+ *
+ * See https://easings.net/ for reference
+ */
+export interface EasingFunction {
+    (progressPercentage: number): number;
+}
+
+export const calculateStepDuration = (speedInPixelsPerSecond: number) => (1 / speedInPixelsPerSecond) * 1_000_000_000;
+
+export const calculateMovementTimesteps = (
+    amountOfSteps: number,
+    speedInPixelsPerSecond: number,
+    easingFunction: EasingFunction = linear
+): number[] => {
+    return Array(amountOfSteps)
+        .fill(speedInPixelsPerSecond)
+        .map((speed: number, idx: number) => {
+            let speedInPixels = speed;
+            if (typeof easingFunction === "function") {
+                speedInPixels += easingFunction(idx / amountOfSteps);
+            }
+            const stepDuration = calculateStepDuration(speedInPixels);
+            return (isFinite(stepDuration) && stepDuration > 0) ? stepDuration : 0;
+        });
+};
+
+export const linear: EasingFunction = (_: number): number => {
+    return 0;
+};