magic-utils-yonava 1.0.2 → 1.0.3

package/{src/debounce.ts → dist/debounce.js}

@@ -6,10 +6,10 @@
  * @param ms time in milliseconds
  * @returns a debounced function
  */
-export const debounce = <T extends () => void>(fn: T, ms: number) => {
-  let timeout: NodeJS.Timeout;
-  return () => {
-    clearTimeout(timeout);
-    timeout = setTimeout(fn, ms);
-  };
+export const debounce = (fn, ms) => {
+    let timeout;
+    return () => {
+        clearTimeout(timeout);
+        timeout = setTimeout(fn, ms);
+    };
 };

package/dist/debugging.d.ts

@@ -0,0 +1,2 @@
+export declare const useLogReport: <T = string>(frequencyMs?: number, resetReportAfterLogging?: boolean) => Set<T>;
+export declare const useCooldownLog: (frequencyMs?: number) => (...data: any[]) => void;

package/dist/debugging.js

@@ -0,0 +1,21 @@
+export const useLogReport = (frequencyMs = 1000, resetReportAfterLogging = true) => {
+    const report = new Set();
+    const logReport = () => {
+        console.log(Array.from(report));
+        if (resetReportAfterLogging)
+            report.clear();
+    };
+    setInterval(logReport, frequencyMs);
+    return report;
+};
+export const useCooldownLog = (frequencyMs = 1000) => {
+    let cooldown = false;
+    const log = (...data) => {
+        if (cooldown)
+            return;
+        console.log(...data);
+        cooldown = true;
+    };
+    setInterval(() => (cooldown = false), frequencyMs);
+    return log;
+};

package/dist/deepDelta/delta.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deepDelta/delta.test.js

@@ -0,0 +1,114 @@
+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/dist/deepDelta/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * gets the delta between two objects
+ *
+ * @param oldObject
+ * @param newObject
+ * @returns an object with only the changes, the values are the new values
+ */
+export declare const delta: (oldObject: Record<any, any>, newObject: Record<any, any>) => Record<any, any> | null;

package/dist/deepDelta/index.js

@@ -0,0 +1,40 @@
+// recursively compare two objects and return the delta
+// -----------------
+const isObj = (obj) => 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, newObject) => {
+    const output = {};
+    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/dist/deepMerge.d.ts

@@ -0,0 +1,16 @@
+export declare const isPlainObject: (obj: any) => obj is Record<string | number | symbol, unknown>;
+/**
+ * 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 declare const deepMerge: (...objects: any[]) => any;

package/dist/deepMerge.js

@@ -0,0 +1,32 @@
+export const isPlainObject = (obj) => !!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) => 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/dist/deepMerge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deepMerge.test.js

@@ -0,0 +1,68 @@
+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/dist/fps.d.ts

@@ -0,0 +1,6 @@
+export declare function useFPS(): {
+    fps: import("vue").Ref<number, number>;
+    frameTime: import("vue").Ref<number, number>;
+    slowFrameCount: import("vue").Ref<number, number>;
+    slowFrameRatio: import("vue").Ref<number, number>;
+};

package/dist/fps.js

@@ -0,0 +1,51 @@
+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;
+    let intervalId;
+    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/dist/fracDecConverter/index.d.ts

@@ -0,0 +1,9 @@
+export declare const gcd: (a: number, b: number) => number;
+export declare const isNullOrUnd: (input: any) => boolean;
+export declare const isFraction: (input: string) => boolean;
+export declare const decimalToFraction: (decimalInput: number) => string;
+/**
+ * @param fractionInput  a string representing a fraction
+ * @returns the decimal representation of the fraction or undefined if the input is not a fraction
+ */
+export declare const fractionToDecimal: (fractionInput: string) => number | undefined;

package/dist/fracDecConverter/index.js

@@ -0,0 +1,34 @@
+export const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+export const isNullOrUnd = (input) => input === null || input === undefined;
+export const isFraction = (input) => {
+    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) => {
+    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) => {
+    if (!isFraction(fractionInput))
+        return;
+    const fraction = fractionInput.split('/');
+    const [numerator, denominator] = fraction.map(Number);
+    return numerator / denominator;
+};

package/dist/hashing.d.ts

@@ -0,0 +1,2 @@
+export declare const djb2Hasher: (str: string) => number;
+export type DJB2Hash = ReturnType<typeof djb2Hasher>;

package/dist/hashing.js

@@ -0,0 +1,7 @@
+export const djb2Hasher = (str) => {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash << 5) + hash + str.charCodeAt(i);
+    }
+    return hash >>> 0;
+};

package/dist/id.d.ts

@@ -0,0 +1,5 @@
+/**
+ * generates a new, random, id
+ * @example generateId() // 'abc123'
+ */
+export declare const generateId: () => string;

package/dist/localStorage.d.ts

@@ -0,0 +1,37 @@
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export declare const localKeys: {
+    /** nodes in graph product */
+    readonly nodes: (key: string) => `nodes-${string}`;
+    /** edges in graph product */
+    readonly edges: (key: string) => `edges-${string}`;
+    /** graph product simulation speed */
+    readonly simulationPlaybackSpeed: "simulation-playback-speed";
+    /** graph theme set by user - {@link Graph.preferredTheme} */
+    readonly preferredTheme: "preferred-theme";
+};
+/**
+ * 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 declare const local: {
+    get: <T extends LocalKeys>(key: T) => string | null;
+    set: <T extends LocalKeys, K extends LocalType<T>>(key: T, value: K) => void;
+    remove: <T extends LocalKeys>(key: T) => void;
+    clear: () => void;
+};
+export {};

package/dist/localStorage.js

@@ -0,0 +1,22 @@
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export const localKeys = {
+    /** nodes in graph product */
+    nodes: (key) => `nodes-${key}`,
+    /** edges in graph product */
+    edges: (key) => `edges-${key}`,
+    /** graph product simulation speed */
+    simulationPlaybackSpeed: 'simulation-playback-speed',
+    /** graph theme set by user - {@link Graph.preferredTheme} */
+    preferredTheme: 'preferred-theme',
+};
+/**
+ * perform **type safe** localStorage actions
+ */
+export const local = {
+    get: (key) => localStorage.getItem(key),
+    set: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+    clear: localStorage.clear,
+};

package/dist/math.d.ts

@@ -0,0 +1,60 @@
+/**
+ * the golden ratio constant.
+ * {@link} https://en.wikipedia.org/wiki/Golden_ratio
+ */
+export declare 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 declare const roundToNearestN: (nearest: number) => (n: number) => number;
+/**
+ * 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 declare const getPrimeFactors: (num: number) => number[];
+/**
+ * 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 declare const lowestPrimeFactor: (num: number) => number;
+/**
+ * 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 declare const gcd: (a: number, b: number) => number;
+/**
+ * check if two numbers are within a certain tolerance of each other
+ */
+export declare const within: (tolerance: number) => (a: number, b: number) => boolean;
+/**
+ * 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 declare const average: (arr: number[]) => number;