magic-utils-yonava 1.0.0

package/src/deepDelta/delta.test.ts

@@ -0,0 +1,129 @@
+import { expect, test } from 'vitest';
+
+import { delta } from '.';
+
+test('deepDelta standard', () => {
+  const yona = {
+    name: 'yona',
+    sex: 'm',
+    residence: 'amherst',
+    school: {
+      name: 'umass',
+      year: 'senior',
+      info: {
+        major: ['cs'],
+        minor: [],
+        start: '2023',
+      },
+    },
+    test: {
+      hello: 'world',
+      removeMe: {
+        removeMe: 'removeMe',
+        removeMe2: {},
+      },
+      test2: {
+        test3: 'secret',
+      },
+    },
+  };
+
+  const dila = {
+    name: 'dila',
+    sex: 'f',
+    residence: 'amherst',
+    school: {
+      name: 'umass',
+      year: 'junior',
+      info: {
+        major: ['cs', 'japanese'],
+        minor: [],
+        start: '2022',
+      },
+    },
+    test: {
+      hello: 'world',
+      removeMe: {
+        removeMe: 'removeMe',
+        removeMe2: {},
+      },
+      test2: {
+        test3: 'secret changed',
+      },
+    },
+  };
+
+  const expected = {
+    name: 'dila',
+    sex: 'f',
+    school: {
+      year: 'junior',
+      info: {
+        major: ['cs', 'japanese'],
+        start: '2022',
+      },
+    },
+    test: {
+      test2: {
+        test3: 'secret changed',
+      },
+    },
+  };
+
+  const result = delta(yona, dila);
+  expect(result).toEqual(expected);
+});
+
+test('deepDelta works if new object has more keys', () => {
+  const yona = {
+    name: 'yona',
+  };
+
+  const dila = {
+    name: 'dila',
+    favoriteColor: 'blue',
+    anime: {
+      naruto: 'meh',
+      bleach: 'good',
+    },
+  };
+
+  const expected = {
+    name: 'dila',
+    favoriteColor: 'blue',
+    anime: {
+      naruto: 'meh',
+      bleach: 'good',
+    },
+  };
+
+  const result = delta(yona, dila);
+
+  expect(result).toEqual(expected);
+});
+
+test('deepDelta works on fields that are null or undefined', () => {
+  const colorGetter = () => 'blue';
+
+  const yona = {
+    name: 'yona',
+    favoriteColor: {
+      color: colorGetter,
+    },
+    sbahn: 's1',
+  };
+
+  const dila = {
+    name: 'dila',
+    favoriteColor: null,
+    sbahn: undefined,
+  };
+
+  const expected = {
+    name: 'dila',
+    sbahn: undefined,
+  };
+
+  const result = delta(yona, dila);
+  expect(result).toEqual(expected);
+});

package/src/deepDelta/index.ts

@@ -0,0 +1,48 @@
+// recursively compare two objects and return the delta
+
+// -----------------
+
+const isObj = (obj: any) =>
+  Object.prototype.toString.call(obj) === '[object Object]';
+
+/**
+ * gets the delta between two objects
+ *
+ * @param oldObject
+ * @param newObject
+ * @returns an object with only the changes, the values are the new values
+ */
+export const delta = (
+  oldObject: Record<any, any>,
+  newObject: Record<any, any>,
+) => {
+  const output: Record<any, any> = {};
+
+  if (!oldObject) return newObject;
+  if (!newObject) return null;
+
+  const oldObjectKeys = Object.keys(oldObject);
+  const newObjectKeys = Object.keys(newObject);
+
+  for (const key of newObjectKeys) {
+    if (!oldObjectKeys.includes(key)) {
+      output[key] = newObject[key];
+    }
+  }
+
+  for (const key of oldObjectKeys) {
+    if (isObj(oldObject[key])) {
+      const diffObj = delta(oldObject[key], newObject[key]);
+      if (diffObj) output[key] = diffObj;
+      continue;
+    }
+
+    if (Array.isArray(oldObject[key])) {
+      if (JSON.stringify(oldObject[key]) !== JSON.stringify(newObject[key]))
+        output[key] = newObject[key];
+      continue;
+    } else if (oldObject[key] !== newObject[key]) output[key] = newObject[key];
+  }
+
+  return Object.keys(output).length ? output : null;
+};

package/src/deepMerge.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+
+import { deepMerge } from './deepMerge';
+
+describe('deepMerge', () => {
+  it('merges flat objects with rightmost priority', () => {
+    const result = deepMerge({ a: 1 }, { a: 2, b: 3 });
+    expect(result).toEqual({ a: 2, b: 3 });
+  });
+
+  it('merges nested objects deeply', () => {
+    const result = deepMerge({ a: { b: 1, c: 2 } }, { a: { b: 3, d: 4 } });
+    expect(result).toEqual({ a: { b: 3, c: 2, d: 4 } });
+  });
+
+  it('overwrites arrays instead of merging them', () => {
+    const result = deepMerge(
+      { a: [1, 2], b: { c: [3, 4] } },
+      { a: [5], b: { c: [6] } },
+    );
+    expect(result).toEqual({ a: [5], b: { c: [6] } });
+  });
+
+  it('handles primitive overwrites correctly', () => {
+    const result = deepMerge({ a: { b: 1 } }, { a: 5 });
+    expect(result).toEqual({ a: 5 });
+  });
+
+  it('returns non-object when passed a primitive last', () => {
+    const result = deepMerge({ a: 1 }, 5);
+    expect(result).toBe(5);
+  });
+
+  it('handles merging with undefined and null safely', () => {
+    const result = deepMerge({ a: { b: 1 } }, undefined, null, { a: { c: 2 } });
+    expect(result).toEqual({ a: { b: 1, c: 2 } });
+  });
+
+  it('handles empty inputs', () => {
+    const result = deepMerge();
+    expect(result).toEqual({});
+  });
+});
+
+describe('deepMerge - special cases', () => {
+  it('overwrites Date objects', () => {
+    const date1 = new Date('2020-01-01');
+    const date2 = new Date('2021-01-01');
+
+    const result = deepMerge({ date: date1 }, { date: date2 });
+    expect(result.date).toBe(date2);
+  });
+
+  it('overwrites Map objects', () => {
+    const map1 = new Map([['a', 1]]);
+    const map2 = new Map([['b', 2]]);
+
+    const result = deepMerge({ map: map1 }, { map: map2 });
+    expect(result.map).toBe(map2);
+  });
+
+  it('overwrites Set objects', () => {
+    const set1 = new Set([1, 2]);
+    const set2 = new Set([3, 4]);
+
+    const result = deepMerge({ set: set1 }, { set: set2 });
+    expect(result.set).toBe(set2);
+  });
+
+  it('overwrites functions', () => {
+    const fn1 = () => 1;
+    const fn2 = () => 2;
+
+    const result = deepMerge({ fn: fn1 }, { fn: fn2 });
+    expect(result.fn).toBe(fn2);
+    expect(result.fn()).toBe(2);
+  });
+
+  it('overwrites class instances', () => {
+    class Example {
+      x = 1;
+    }
+    const obj1 = { instance: new Example() };
+    const obj2 = { instance: { y: 2 } };
+
+    const result = deepMerge(obj1, obj2);
+    expect(result.instance).toEqual({ y: 2 });
+  });
+});

package/src/deepMerge.ts

@@ -0,0 +1,37 @@
+export const isPlainObject = (
+  obj: any,
+): obj is Record<string | number | symbol, unknown> =>
+  !!obj &&
+  typeof obj === 'object' &&
+  Object.getPrototypeOf(obj) === Object.prototype;
+
+/**
+ * Deeply merges multiple objects. Properties from later objects overwrite those from earlier ones.
+ * Non-object values (including arrays) are replaced, not merged.
+ *
+ * @param {...any[]} objects - Objects to merge. The rightmost object's properties take precedence.
+ * @returns {any} - A new deeply merged object.
+ *
+ * @example
+ * const result = deepMerge(
+ *   { a: 1, b: { c: 2 } },
+ *   { b: { d: 3 }, e: 4 }
+ * );
+ * // result: { a: 1, b: { c: 2, d: 3 }, e: 4 }
+ */
+export const deepMerge = (...objects: any[]): any =>
+  objects.reduce((acc, obj) => {
+    if (obj === undefined || obj === null) return acc;
+
+    if (!isPlainObject(obj)) return obj;
+
+    Object.keys(obj).forEach((key) => {
+      if (isPlainObject(obj[key]) && isPlainObject(acc[key])) {
+        acc[key] = deepMerge(acc[key], obj[key]);
+      } else {
+        acc[key] = obj[key];
+      }
+    });
+
+    return acc;
+  }, {});

package/src/fps.ts

@@ -0,0 +1,64 @@
+import { onMounted, onUnmounted, ref } from "vue";
+
+export function useFPS() {
+  const fps = ref(0);
+  const frameTime = ref(0);
+  const slowFrameCount = ref(0);
+  const slowFrameRatio = ref(0);
+
+  let frameId: number;
+  let intervalId: NodeJS.Timeout;
+
+  let lastMeasure = performance.now();
+  let lastFrame = performance.now();
+  let frames = 0;
+  let slowFrames = 0;
+
+  const SLOW_FRAME_THRESHOLD = 33.3; // ms
+
+  const update = () => {
+    const now = performance.now();
+    const delta = now - lastFrame;
+    frameTime.value = delta;
+    lastFrame = now;
+
+    if (delta > SLOW_FRAME_THRESHOLD) {
+      slowFrames++;
+    }
+
+    frames++;
+    frameId = requestAnimationFrame(update);
+  };
+
+  const measure = () => {
+    const now = performance.now();
+    const delta = now - lastMeasure;
+
+    fps.value = Math.round((frames * 1000) / delta);
+    slowFrameCount.value = slowFrames;
+    slowFrameRatio.value = frames > 0 ? slowFrames / frames : 0;
+
+    frames = 0;
+    slowFrames = 0;
+    lastMeasure = now;
+  };
+
+  onMounted(() => {
+    lastFrame = performance.now();
+    lastMeasure = performance.now();
+    frameId = requestAnimationFrame(update);
+    intervalId = setInterval(measure, 500);
+  });
+
+  onUnmounted(() => {
+    cancelAnimationFrame(frameId);
+    clearInterval(intervalId);
+  });
+
+  return {
+    fps,
+    frameTime,
+    slowFrameCount,
+    slowFrameRatio,
+  };
+}

package/src/fracDecConverter/index.ts

@@ -0,0 +1,36 @@
+
+export const gcd = (a: number, b: number): number => (b ? gcd(b, a % b) : a);
+
+export const isNullOrUnd = (input: any) =>
+  input === null || input === undefined;
+
+export const isFraction = (input: string) => {
+  const fraction = input.trim().split('/').filter(Boolean);
+  if (fraction.length !== 2) return false;
+  const [numerator, denominator] = fraction.map(Number);
+  if (isNullOrUnd(numerator) || isNullOrUnd(denominator)) return false;
+  return true;
+};
+
+export const decimalToFraction = (decimalInput: number) => {
+  const decimal = Math.round(decimalInput * 1e10) / 1e10;
+  const len = decimal.toString().length - 2;
+  let denominator = 10 ** len;
+  let numerator = decimal * denominator;
+  const divisor = gcd(numerator, denominator);
+  numerator /= divisor;
+  denominator /= divisor;
+  if (denominator === 1) return numerator.toString();
+  return `${numerator}/${denominator}`;
+};
+
+/**
+ * @param fractionInput  a string representing a fraction
+ * @returns the decimal representation of the fraction or undefined if the input is not a fraction
+ */
+export const fractionToDecimal = (fractionInput: string) => {
+  if (!isFraction(fractionInput)) return;
+  const fraction = fractionInput.split('/');
+  const [numerator, denominator] = fraction.map(Number);
+  return numerator / denominator;
+};

package/src/hashing.ts

@@ -0,0 +1,9 @@
+export const djb2Hasher = (str: string) => {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) + hash + str.charCodeAt(i);
+  }
+  return hash >>> 0;
+};
+
+export type DJB2Hash = ReturnType<typeof djb2Hasher>;

package/src/id.ts

@@ -0,0 +1,5 @@
+/**
+ * generates a new, random, id
+ * @example generateId() // 'abc123'
+ */
+export const generateId = () => Math.random().toString(36).substring(2, 9);

package/src/localStorage.ts

@@ -0,0 +1,49 @@
+
+
+type LocalStorageGetter = (...args: any[]) => string;
+type LocalStorageRecord = Record<string, string | LocalStorageGetter>;
+
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export const localKeys = {
+  /** nodes in graph product */
+  nodes: (key: string) => `nodes-${key}` as const,
+  /** edges in graph product */
+  edges: (key: string) => `edges-${key}` as const,
+  /** graph product simulation speed */
+  simulationPlaybackSpeed: 'simulation-playback-speed',
+  /** graph theme set by user - {@link Graph.preferredTheme} */
+  preferredTheme: 'preferred-theme',
+} as const satisfies LocalStorageRecord;
+
+/**
+ * all return values of localStorage are, by default, string.
+ * this type allows string to be narrowed to types such as 'true' | 'false'
+ */
+type TypeOverride = {};
+
+type LocalObj = typeof localKeys;
+
+/**
+ * @example
+ * type T = TypeOrReturnType<number> // number
+ * type TFunc = TypeOrReturnType<() => number> // number
+ */
+type TypeOrReturnType<T> = T extends (...args: any[]) => infer U ? U : T;
+
+type LocalKeys = TypeOrReturnType<LocalObj[keyof LocalObj]>;
+type LocalType<T extends LocalKeys> = T extends keyof TypeOverride
+  ? TypeOverride[T]
+  : string;
+
+/**
+ * perform **type safe** localStorage actions
+ */
+export const local = {
+  get: <T extends LocalKeys>(key: T) => localStorage.getItem(key),
+  set: <T extends LocalKeys, K extends LocalType<T>>(key: T, value: K) =>
+    localStorage.setItem(key, value),
+  remove: <T extends LocalKeys>(key: T) => localStorage.removeItem(key),
+  clear: localStorage.clear,
+};

package/src/math.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+  average,
+  gcd,
+  getPrimeFactors,
+  lowestPrimeFactor,
+  roundToNearestN,
+} from './math';
+
+describe('roundToNearestN', () => {
+  test('rounds a number to the nearest multiple of n', () => {
+    const roundToNearest5 = roundToNearestN(5);
+    expect(roundToNearest5(13)).toBe(15);
+    expect(roundToNearest5(12)).toBe(10);
+  });
+});
+
+describe('getPrimeFactors', () => {
+  test('returns the prime factors of a number', () => {
+    expect(getPrimeFactors(12)).toEqual([2, 2, 3]);
+    expect(getPrimeFactors(15)).toEqual([3, 5]);
+  });
+
+  test('edge case: 1', () => {
+    expect(getPrimeFactors(1)).toEqual([]);
+  });
+});
+
+describe('lowestPrimeFactor', () => {
+  test('returns the lowest prime factor of a number', () => {
+    expect(lowestPrimeFactor(12)).toBe(2);
+    expect(lowestPrimeFactor(15)).toBe(3);
+  });
+
+  test('edge case: 1', () => {
+    expect(lowestPrimeFactor(1)).toBe(1);
+  });
+});
+
+describe('gcd', () => {
+  test('returns the greatest common divisor of two numbers', () => {
+    expect(gcd(12, 15)).toBe(3);
+    expect(gcd(12, 18)).toBe(6);
+  });
+});
+
+describe('average', () => {
+  test('returns the average of a list of numbers', () => {
+    expect(average([1, 2, 3, 4, 5])).toBe(3);
+    expect(average([1, 2, 3, 4, 5, 6])).toBe(3.5);
+  });
+
+  test('edge case: empty list', () => {
+    expect(average([])).toBe(0);
+  });
+});

package/src/math.ts

@@ -0,0 +1,93 @@
+/**
+ * the golden ratio constant.
+ * {@link} https://en.wikipedia.org/wiki/Golden_ratio
+ */
+export const GOLDEN_RATIO = 1.618;
+
+/**
+ * rounds a number to the nearest multiple of another number
+ *
+ * @param n the number to round
+ * @param nearest the number to round to
+ * @returns the rounded number
+ * @example const roundToNearest5 = roundToNearestN(5);
+ * roundToNearest5(13) // 15
+ * roundToNearest5(12) // 10
+ */
+export const roundToNearestN = (nearest: number) => (n: number) => {
+  return Math.round(n / nearest) * nearest;
+};
+
+/**
+ * get the prime factors of a number
+ *
+ * @param num the number to get the prime factors of
+ * @returns the prime factors of the number
+ * @example getPrimeFactors(12) // [2, 2, 3]
+ * getPrimeFactors(15) // [3, 5]
+ */
+export const getPrimeFactors = (num: number) => {
+  const factors: number[] = [];
+  let divisor = 2;
+
+  while (num >= 2) {
+    if (num % divisor === 0) {
+      factors.push(divisor);
+      num = num / divisor;
+    } else {
+      divisor++;
+    }
+  }
+
+  return factors;
+};
+
+/**
+ * get the lowest prime factor of a number
+ *
+ * @param num the number to get the lowest prime factor of
+ * @returns the lowest prime factor of the number
+ * @example
+ * lowestPrimeFactor(12) // 12 = 2 * 2 * 3, min(2, 2, 3) = 2
+ * lowestPrimeFactor(15) // 15 = 3 * 5, min(3, 5) = 3
+ */
+export const lowestPrimeFactor = (num: number) => {
+  if (num === 1) return 1; // 1 has no prime factors
+  return Math.min(...getPrimeFactors(num));
+};
+
+/**
+ * get the greatest common divisor of two numbers.
+ * {@link} https://en.wikipedia.org/wiki/Euclidean_algorithm
+ * {@link} https://en.wikipedia.org/wiki/Greatest_common_divisor
+ *
+ * @param a the first number
+ * @param b the second number
+ * @returns the greatest common divisor of the two numbers
+ * @example gcd(12, 15) // 3
+ * gcd(12, 18) // 6
+ */
+export const gcd = (a: number, b: number): number => {
+  if (b === 0) return a;
+  return gcd(b, a % b);
+};
+
+/**
+ * check if two numbers are within a certain tolerance of each other
+ */
+export const within = (tolerance: number) => (a: number, b: number) => {
+  return Math.abs(a - b) <= tolerance;
+};
+
+/**
+ * get the average of an array of numbers
+ *
+ * @param arr the array of numbers to average
+ * @returns the average of the array
+ * @example average([1, 2, 3]) // 2
+ * average([1, 2, 3, 4]) // 2.5
+ */
+export const average = (arr: number[]) => {
+  if (arr.length === 0) return 0;
+  return arr.reduce((acc, val) => acc + val, 0) / arr.length;
+};

package/src/maybeGetter/index.ts

@@ -0,0 +1,41 @@
+import type { RemoveAnyArray } from '../types';
+
+/**
+ * taking some data that may be a plain value or a function that returns that value
+ *
+ * @template T - the type of the value
+ * @template K - the type of the arguments necessary in order to resolve the value
+ */
+export type MaybeGetter<T, K extends any[] = []> = T | ((...arg: K) => T);
+
+/**
+ * the value of a MaybeGetter
+ */
+export type UnwrapMaybeGetter<T> =
+  T extends MaybeGetter<infer U, infer _> ? U : T;
+
+/**
+ * the parameters of a MaybeGetter
+ */
+export type MaybeGetterParams<T> = RemoveAnyArray<
+  T extends MaybeGetter<infer _, infer K> ? K : []
+>;
+
+/**
+ * unwraps a MaybeGetter into a value of type T.
+ *
+ * @param value - the value to unwrap
+ * @param args - the arguments to pass to the getter if the value is a getter
+ * @returns T, which is UnwrapMaybeGetter<MaybeGetter<T, K>>
+ * @example getValue(5) // 5
+ * getValue(() => 5) // 5
+ */
+export const getValue = <T, K extends any[]>(
+  value: MaybeGetter<T, K>,
+  ...args: K
+) => {
+  if (typeof value === 'function') {
+    return (value as (...args: K) => T)(...args);
+  }
+  return value;
+};

package/src/mouse.ts

@@ -0,0 +1,8 @@
+/**
+ * https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
+ */
+export const MOUSE_BUTTONS = {
+  left: 0,
+  middle: 1,
+  right: 2,
+} as const;

package/src/random.ts

@@ -0,0 +1,27 @@
+/**
+ * given two numbers, this function returns a random number between them (inclusive)
+ *
+ * @param min - the lowest number
+ * @param max - the highest number
+ * @returns a random number between min and max
+ */
+export const getRandomInRange = (min: number, max: number) =>
+  Math.round(Math.random() * (max - min) + min);
+
+export const getRandomPointOnCanvas = (
+  canvas: HTMLCanvasElement,
+  buffer = 50,
+) => ({
+  x: getRandomInRange(buffer, canvas.width - buffer),
+  y: getRandomInRange(buffer, canvas.height - buffer),
+});
+
+/**
+ * get a random element from an array
+ *
+ * @param array
+ * @returns random element from given array
+ */
+export const getRandomElement = <T>(array: ArrayLike<T>) => {
+  return array[Math.floor(Math.random() * array.length)];
+};