@vived/core 1.0.1 → 1.2.0

package/src/Utilities/LerpNumber.ts

@@ -0,0 +1,109 @@
+import { EaseFn } from "../Types";
+import { quintInOut } from "./easeFunctions";
+
+/**
+ * Configuration object for performing a linear interpolation (lerp) operation.
+ * @interface LerpNumberDTO
+ */
+export interface LerpNumberDTO {
+  /** Starting value of the lerp */
+  start: number;
+  /** Target/ending value of the lerp */
+  end: number;
+  /** Callback function that receives the interpolated value on each update */
+  update: (value: number) => void;
+  /** Duration of the lerp in milliseconds. Defaults to LerpNumber.defaultDurationMS */
+  durationMS?: number;
+  /** Easing function to modify the interpolation curve. Defaults to LerpNumber.defaultEase */
+  ease?: EaseFn;
+  /** Optional callback function called when lerp completes naturally */
+  onComplete?: () => void;
+  /** Optional callback function called when lerp is cancelled */
+  onCancel?: () => void;
+}
+
+/**
+ * Utility class for smoothly interpolating between two numbers over time.
+ * Uses requestAnimationFrame for smooth animation and supports custom easing functions.
+ *
+ * @example
+ * const lerper = new LerpNumber();
+ * // Animate from 0 to 100 over 2 seconds
+ * await lerper.lerp({
+ *   start: 0,
+ *   end: 100,
+ *   durationMS: 2000,
+ *   update: (value) => console.log(value)
+ * });
+ */
+export class LerpNumber {
+  public defaultDurationMS = 1000;
+  public defaultEase: EaseFn = quintInOut;
+
+  public get isLerping() {
+    return this._isLerping;
+  }
+  private _isLerping = false;
+
+  /**
+   * Cancels the current lerp operation if one is in progress.
+   * Triggers the onCancel callback if provided in the original lerp configuration.
+   */
+  public cancel() {
+    if (!this._isLerping) return;
+
+    this._cancelLerp = true;
+  }
+
+  private _cancelLerp = false;
+
+  /**
+   * Initiates a lerp (linear interpolation) operation.
+   * If a lerp is already in progress, it will be cancelled before starting the new one.
+   *
+   * @param data - Configuration object for the lerp operation
+   * @returns Promise that resolves when the lerp completes or is cancelled
+   * @throws Never throws, but may reject if the update function throws
+   */
+  lerp = (data: LerpNumberDTO): Promise<void> => {
+    if (this._isLerping) {
+      this.cancel();
+    }
+    const { start, end, durationMS, ease, onComplete, update, onCancel } = data;
+
+    const durationToUse = durationMS ?? this.defaultDurationMS;
+    const easeToUse = ease ?? this.defaultEase;
+
+    return new Promise((resolve) => {
+      const startTime = performance.now();
+      this._isLerping = true;
+
+      update(start);
+
+      const interval = setInterval(() => {
+        if (this._cancelLerp) {
+          clearInterval(interval);
+          this._isLerping = false;
+          this._cancelLerp = false;
+          if (onCancel) onCancel();
+          return resolve();
+        }
+
+        const currentTime = performance.now();
+        const elapsedTime = currentTime - startTime;
+        const progress = Math.min(elapsedTime / durationToUse, 1);
+        const easedProgress = easeToUse(progress);
+        const value = start + (end - start) * easedProgress;
+        update(value);
+
+        if (progress >= 1) {
+          clearInterval(interval);
+          this._isLerping = false;
+          update(end);
+          if (onComplete) onComplete();
+          resolve();
+        }
+      }, 10);
+    });
+  };
+}

package/src/Utilities/degreesToRadians.test.ts

@@ -0,0 +1,8 @@
+import { degreesToRadians } from "./degreesToRadians"
+
+test("Converting degrees to radians", ()=>{
+  expect(degreesToRadians(0)).toEqual(0);
+  expect(degreesToRadians(180)).toBeCloseTo(Math.PI);
+  expect(degreesToRadians(-90)).toBeCloseTo(-Math.PI/2);
+})
+

package/src/Utilities/degreesToRadians.ts

@@ -0,0 +1,3 @@
+export function degreesToRadians(deg: number):number{
+  return deg * Math.PI / 180;
+}

package/src/Utilities/easeFunctions.test.ts

@@ -0,0 +1,251 @@
+import {
+  easeLinear,
+  quadIn,
+  quadInOut,
+  quadOut,
+  cubicIn,
+  cubicInOut,
+  cubicOut,
+  expoIn,
+  expoInOut,
+  expoOut,
+  sinIn,
+  sinInOut,
+  sinOut,
+  quartIn,
+  quartInOut,
+  quartOut,
+  quintIn,
+  quintInOut,
+  quintOut,
+  circIn,
+  circInOut,
+  circOut,
+} from "./easeFunctions";
+
+it("Returns the proper values for ease linear", () => {
+  expect(easeLinear(-1)).toEqual(0);
+  expect(easeLinear(0)).toEqual(0);
+  expect(easeLinear(0.25)).toEqual(0.25);
+  expect(easeLinear(0.5)).toEqual(0.5);
+  expect(easeLinear(0.75)).toEqual(0.75);
+  expect(easeLinear(1)).toEqual(1);
+  expect(easeLinear(2)).toEqual(1);
+});
+
+// Quad
+it("Returns the proper val for quad in", () => {
+  expect(quadIn(-1)).toEqual(0);
+  expect(quadIn(0)).toEqual(0);
+  expect(quadIn(0.25)).toEqual(0.0625);
+  expect(quadIn(0.5)).toEqual(0.25);
+  expect(quadIn(0.75)).toEqual(0.5625);
+  expect(quadIn(1)).toEqual(1);
+  expect(quadIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for quad out", () => {
+  expect(quadOut(-1)).toEqual(0);
+  expect(quadOut(0)).toEqual(0);
+  expect(quadOut(0.25)).toEqual(0.4375);
+  expect(quadOut(0.5)).toEqual(0.75);
+  expect(quadOut(0.75)).toEqual(0.9375);
+  expect(quadOut(1)).toEqual(1);
+  expect(quadOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for quad in out", () => {
+  expect(quadInOut(-1)).toEqual(0);
+  expect(quadInOut(0)).toEqual(0);
+  expect(quadInOut(0.25)).toEqual(0.125);
+  expect(quadInOut(0.5)).toEqual(0.5);
+  expect(quadInOut(0.75)).toEqual(0.875);
+  expect(quadInOut(1)).toEqual(1);
+  expect(quadInOut(2)).toEqual(1);
+});
+
+// Cubic
+it("Returns the proper val for cubic in", () => {
+  expect(cubicIn(-1)).toEqual(0);
+  expect(cubicIn(0)).toEqual(0);
+  expect(cubicIn(0.25)).toEqual(0.015625);
+  expect(cubicIn(0.5)).toEqual(0.125);
+  expect(cubicIn(0.75)).toEqual(0.421875);
+  expect(cubicIn(1)).toEqual(1);
+  expect(cubicIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for cubic out", () => {
+  expect(cubicOut(-1)).toEqual(0);
+  expect(cubicOut(0)).toEqual(0);
+  expect(cubicOut(0.25)).toEqual(0.578125);
+  expect(cubicOut(0.5)).toEqual(0.875);
+  expect(cubicOut(0.75)).toEqual(0.984375);
+  expect(cubicOut(1)).toEqual(1);
+  expect(cubicOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for cubic in out", () => {
+  expect(cubicInOut(-1)).toEqual(0);
+  expect(cubicInOut(0)).toEqual(0);
+  expect(cubicInOut(0.25)).toEqual(0.0625);
+  expect(cubicInOut(0.5)).toEqual(0.5);
+  expect(cubicInOut(0.75)).toEqual(0.9375);
+  expect(cubicInOut(1)).toEqual(1);
+  expect(cubicInOut(2)).toEqual(1);
+});
+
+// Expo
+it("Returns the proper val for Expo in", () => {
+  expect(expoIn(-1)).toEqual(0);
+  expect(expoIn(0)).toEqual(0);
+  expect(expoIn(0.25)).toEqual(0.005524271728019902);
+  expect(expoIn(0.5)).toEqual(0.03125);
+  expect(expoIn(0.75)).toEqual(0.17677669529663687);
+  expect(expoIn(1)).toEqual(1);
+  expect(expoIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for Expo out", () => {
+  expect(expoOut(-1)).toEqual(0);
+  expect(expoOut(0)).toEqual(0);
+  expect(expoOut(0.25)).toEqual(0.8232233047033631);
+  expect(expoOut(0.5)).toEqual(0.96875);
+  expect(expoOut(0.75)).toEqual(0.99447572827198);
+  expect(expoOut(1)).toEqual(1);
+  expect(expoOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for Expo in out", () => {
+  expect(expoInOut(-1)).toEqual(0);
+  expect(expoInOut(0)).toEqual(0);
+  expect(expoInOut(0.25)).toEqual(0.015625);
+  expect(expoInOut(0.5)).toEqual(0.5);
+  expect(expoInOut(0.75)).toEqual(0.984375);
+  expect(expoInOut(1)).toEqual(1);
+  expect(expoInOut(2)).toEqual(1);
+});
+
+// Sin
+it("Returns the proper val for Sin in", () => {
+  expect(sinIn(-1)).toEqual(0);
+  expect(sinIn(0)).toEqual(0);
+  expect(sinIn(0.25)).toEqual(0.07612046748871326);
+  expect(sinIn(0.5)).toEqual(0.2928932188134524);
+  expect(sinIn(0.75)).toEqual(0.6173165676349102);
+  expect(sinIn(1)).toEqual(1);
+  expect(sinIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for Sin out", () => {
+  expect(sinOut(-1)).toEqual(0);
+  expect(sinOut(0)).toEqual(0);
+  expect(sinOut(0.25)).toEqual(0.3826834323650898);
+  expect(sinOut(0.5)).toEqual(0.7071067811865475);
+  expect(sinOut(0.75)).toEqual(0.9238795325112867);
+  expect(sinOut(1)).toEqual(1);
+  expect(sinOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for Sin in out", () => {
+  expect(sinInOut(-1)).toEqual(0);
+  expect(sinInOut(0)).toEqual(0);
+  expect(sinInOut(0.25)).toEqual(0.1464466094067262);
+  expect(sinInOut(0.5)).toBeCloseTo(0.5);
+  expect(sinInOut(0.75)).toEqual(0.8535533905932737);
+  expect(sinInOut(1)).toEqual(1);
+  expect(sinInOut(2)).toEqual(1);
+});
+
+// Quart
+it("Returns the proper val for Quart in", () => {
+  expect(quartIn(-1)).toEqual(0);
+  expect(quartIn(0)).toEqual(0);
+  expect(quartIn(0.25)).toEqual(0.00390625);
+  expect(quartIn(0.5)).toEqual(0.0625);
+  expect(quartIn(0.75)).toEqual(0.31640625);
+  expect(quartIn(1)).toEqual(1);
+  expect(quartIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for Quart out", () => {
+  expect(quartOut(-1)).toEqual(0);
+  expect(quartOut(0)).toEqual(0);
+  expect(quartOut(0.25)).toEqual(0.68359375);
+  expect(quartOut(0.5)).toEqual(0.9375);
+  expect(quartOut(0.75)).toEqual(0.99609375);
+  expect(quartOut(1)).toEqual(1);
+  expect(quartOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for Quart in out", () => {
+  expect(quartInOut(-1)).toEqual(0);
+  expect(quartInOut(0)).toEqual(0);
+  expect(quartInOut(0.25)).toEqual(0.03125);
+  expect(quartInOut(0.5)).toBeCloseTo(0.5);
+  expect(quartInOut(0.75)).toEqual(0.96875);
+  expect(quartInOut(1)).toEqual(1);
+  expect(quartInOut(2)).toEqual(1);
+});
+
+// Quint
+it("Returns the proper val for Quint in", () => {
+  expect(quintIn(-1)).toEqual(0);
+  expect(quintIn(0)).toEqual(0);
+  expect(quintIn(0.25)).toEqual(0.0009765625);
+  expect(quintIn(0.5)).toEqual(0.03125);
+  expect(quintIn(0.75)).toEqual(0.2373046875);
+  expect(quintIn(1)).toEqual(1);
+  expect(quintIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for Quint out", () => {
+  expect(quintOut(-1)).toEqual(0);
+  expect(quintOut(0)).toEqual(0);
+  expect(quintOut(0.25)).toEqual(0.7626953125);
+  expect(quintOut(0.5)).toEqual(0.96875);
+  expect(quintOut(0.75)).toEqual(0.9990234375);
+  expect(quintOut(1)).toEqual(1);
+  expect(quintOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for Quint in out", () => {
+  expect(quintInOut(-1)).toEqual(0);
+  expect(quintInOut(0)).toEqual(0);
+  expect(quintInOut(0.25)).toEqual(0.015625);
+  expect(quintInOut(0.5)).toBeCloseTo(0.5);
+  expect(quintInOut(0.75)).toEqual(0.984375);
+  expect(quintInOut(1)).toEqual(1);
+  expect(quintInOut(2)).toEqual(1);
+});
+
+// Circ
+it("Returns the proper val for Circ in", () => {
+  expect(circIn(-1)).toEqual(0);
+  expect(circIn(0)).toEqual(0);
+  expect(circIn(0.25)).toEqual(0.031754163448145745);
+  expect(circIn(0.5)).toEqual(0.1339745962155614);
+  expect(circIn(0.75)).toEqual(0.3385621722338523);
+  expect(circIn(1)).toEqual(1);
+  expect(circIn(2)).toEqual(1);
+});
+
+it("Returns the proper val for Circ out", () => {
+  expect(circOut(-1)).toEqual(0);
+  expect(circOut(0)).toEqual(0);
+  expect(circOut(0.25)).toEqual(0.6614378277661477);
+  expect(circOut(0.5)).toEqual(0.8660254037844386);
+  expect(circOut(0.75)).toEqual(0.9682458365518543);
+  expect(circOut(1)).toEqual(1);
+  expect(circOut(2)).toEqual(1);
+});
+
+it("Returns the proper val for Circ in out", () => {
+  expect(circInOut(-1)).toEqual(0);
+  expect(circInOut(0)).toEqual(0);
+  expect(circInOut(0.25)).toEqual(0.0669872981077807);
+  expect(circInOut(0.5)).toBeCloseTo(0.5);
+  expect(circInOut(0.75)).toEqual(0.9330127018922193);
+  expect(circInOut(1)).toEqual(1);
+  expect(circInOut(2)).toEqual(1);
+});

package/src/Utilities/easeFunctions.ts

@@ -0,0 +1,180 @@
+import { EaseFn } from "../Types";
+
+
+export const easeLinear: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x;
+};
+
+export const quadIn: EaseFn = (x: number) => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x * x;
+};
+
+export const quadOut: EaseFn = (x: number) => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x * (2 - x);
+};
+
+export const quadInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  if (x < 0.5) {
+    return 2 * x * x;
+  } else {
+    return 1 - Math.pow(-2 * x + 2, 2) / 2;
+  }
+};
+
+export const cubicIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x * x * x;
+};
+
+export const cubicOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return --x * x * x + 1;
+};
+
+export const cubicInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  x *= 2;
+
+  if (x <= 1) {
+    return (x * x * x) / 2;
+  } else {
+    return ((x -= 2) * x * x + 2) / 2;
+  }
+};
+
+export const expoIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return Math.pow(2, 10 * x - 10);
+};
+
+export const expoOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return 1 - Math.pow(2, -10 * x);
+};
+
+export const expoInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x < 0.5
+    ? Math.pow(2, 20 * x - 10) / 2
+    : (2 - Math.pow(2, -20 * x + 10)) / 2;
+};
+
+export const sinIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return 1 - Math.cos((x * Math.PI) / 2);
+};
+
+export const sinOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return Math.sin((x * Math.PI) / 2);
+};
+
+export const sinInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return -(Math.cos(Math.PI * x) - 1) / 2;
+};
+
+export const quartIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x * x * x * x;
+};
+
+export const quartOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return 1 - Math.pow(1 - x, 4);
+};
+
+export const quartInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  if (x < 0.5) {
+    return 8 * x * x * x * x;
+  } else {
+    return 1 - Math.pow(-2 * x + 2, 4) / 2;
+  }
+};
+
+export const quintIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return x * x * x * x * x;
+};
+
+export const quintOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return 1 - Math.pow(1 - x, 5);
+};
+
+export const quintInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  if (x < 0.5) {
+    return 16 * x * x * x * x * x;
+  } else {
+    return 1 - Math.pow(-2 * x + 2, 5) / 2;
+  }
+};
+
+export const circIn: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return 1 - Math.sqrt(1 - Math.pow(x, 2));
+};
+
+export const circOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  return Math.sqrt(1 - Math.pow(x - 1, 2));
+};
+
+export const circInOut: EaseFn = (x: number): number => {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+
+  if (x < 0.5) {
+    return (1 - Math.sqrt(1 - Math.pow(2 * x, 2))) / 2;
+  } else {
+    return (Math.sqrt(1 - Math.pow(-2 * x + 2, 2)) + 1) / 2;
+  }
+};

package/src/Utilities/generateUniqueID.ts

@@ -0,0 +1,5 @@
+import { v4 as uuidv4 } from "uuid";
+
+export function generateUniqueID(): string {
+  return uuidv4();
+}

package/src/Utilities/index.ts

@@ -0,0 +1,6 @@
+export * from "./degreesToRadians";
+export * from "./LengthConverters";
+export * from "./generateUniqueID";
+export * from "./easeFunctions";
+export * from "./interpolateNumber";
+

package/src/Utilities/interpolateNumber.test.ts

@@ -0,0 +1,28 @@
+import { interpolateNumber } from "./interpolateNumber";
+
+describe("Lerp number", () => {
+  it("Interpolate as expected", () => {
+    const lerpedVal = interpolateNumber(0, 10, 0.5);
+    expect(lerpedVal).toEqual(5);
+  });
+
+  it("Interpolate without clamping", () => {
+    const lerpedVal = interpolateNumber(0, 10, -0.5);
+    expect(lerpedVal).toEqual(-5);
+  });
+
+  it("Interpolate without clamping", () => {
+    const lerpedVal = interpolateNumber(0, 10, 1.5);
+    expect(lerpedVal).toEqual(15);
+  });
+
+  it("Interpolate with clamping", () => {
+    const lerpedVal = interpolateNumber(0, 10, -0.5, true);
+    expect(lerpedVal).toEqual(0);
+  });
+
+  it("Interpolate with clamping", () => {
+    const lerpedVal = interpolateNumber(0, 10, 1.5, true);
+    expect(lerpedVal).toEqual(10);
+  });
+});

package/src/Utilities/interpolateNumber.ts

@@ -0,0 +1,21 @@
+export function interpolateNumber(
+  start: number,
+  end: number,
+  percent: number,
+  clamp: boolean = false
+): number {
+  const range = end - start;
+
+  if (!clamp) {
+    return percent * range + start;
+  }
+
+  let clampedP = percent;
+  if (clampedP < 0) {
+    clampedP = 0;
+  } else if (clampedP > 1) {
+    clampedP = 1;
+  }
+
+  return clampedP * range + start;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./AppObject";
 export * from "./Entities";
 export * from "./Types";
+export * from "./Utilities";
 export * from "./ValueObjects";