General purpose memoization tool

package.json

@@ -116,6 +116,7 @@
     "expo-av": "~13.10.4",
     "expo-image": "1.11.0",
     "expo-image-manipulator": "11.8.0",
+    "fast-equals": "^5.0.1",
     "focus-trap-react": "^10.2.3",
     "htmlparser2": "^7.2.0",
     "idb-keyval": "^6.2.1",

src/libs/memoize/cache/arrayCacheBuilder.ts

@@ -0,0 +1,74 @@
+import type {Cache, CacheOpts} from '@libs/memoize/types';
+import {getEqualityComparator} from '@libs/memoize/utils';
+
+/**
+ * Builder of the cache using `Array` primitive under the hood.
+ * @param opts - Cache options, check `CacheOpts` type for more details.
+ * @returns
+ */
+function buildArrayCache<K extends unknown[], V>(opts: CacheOpts): Cache<K, V> {
+    const cache: Array<[K, V]> = [];
+
+    const keyComparator = getEqualityComparator(opts);
+
+    function getKeyIndex(key: K) {
+        for (let i = cache.length - 1; i >= 0; i--) {
+            if (keyComparator(cache[i][0], key)) {
+                return i;
+            }
+        }
+        return -1;
+    }
+
+    return {
+        get(key) {
+            const index = getKeyIndex(key);
+
+            if (index !== -1) {
+                const [entry] = cache.splice(index, 1);
+                cache.push(entry);
+                return {value: entry[1]};
+            }
+        },
+        set(key, value) {
+            const index = getKeyIndex(key);
+
+            if (index !== -1) {
+                cache.splice(index, 1);
+            }
+
+            cache.push([key, value]);
+
+            if (cache.length > opts.maxSize) {
+                cache.shift();
+            }
+        },
+        delete(key) {
+            const index = getKeyIndex(key);
+            const has = index !== -1;
+
+            if (has) {
+                cache.splice(index, 1);
+            }
+
+            return has;
+        },
+        clear() {
+            cache.length = 0;
+        },
+        snapshot: {
+            keys() {
+                return cache.map((entry) => entry[0]);
+            },
+            values() {
+                return cache.map((entry) => entry[1]);
+            },
+            cache() {
+                return [...cache];
+            },
+            size: cache.length,
+        },
+    };
+}
+
+export default buildArrayCache;

src/libs/memoize/const.ts

@@ -0,0 +1,11 @@
+import type {Options} from './types';
+
+const DEFAULT_OPTIONS = {
+    maxSize: Infinity,
+    equality: 'shallow',
+    monitor: false,
+    cache: 'array',
+} satisfies Options;
+
+// eslint-disable-next-line import/prefer-default-export
+export {DEFAULT_OPTIONS};

src/libs/memoize/index.ts

@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import buildArrayCache from './cache/arrayCacheBuilder';
+import {MemoizeStats} from './stats';
+import type {ClientOptions, MemoizeFnPredicate} from './types';
+import {mergeOptions} from './utils';
+
+/**
+ * Wraps a function with a memoization layer. Useful for caching expensive calculations.
+ * @param fn - Function to memoize
+ * @param options - Options for the memoization layer, for more details see `ClientOptions` type.
+ * @returns Memoized function with a cache API attached to it.
+ */
+function memoize<Fn extends MemoizeFnPredicate>(fn: Fn, opts?: ClientOptions) {
+    const options = mergeOptions(opts);
+
+    const cache = buildArrayCache<Parameters<Fn>, ReturnType<Fn>>(options);
+
+    const stats = new MemoizeStats(options.monitor);
+
+    const memoized = function memoized(...key: Parameters<Fn>): ReturnType<Fn> {
+        const statsEntry = stats.createEntry();
+        statsEntry.track('keyLength', key.length);
+
+        const retrievalTimeStart = performance.now();
+        let cached = cache.get(key);
+        statsEntry.track('cacheRetrievalTime', performance.now() - retrievalTimeStart);
+        statsEntry.track('didHit', !!cached);
+
+        if (!cached) {
+            const fnTimeStart = performance.now();
+            const result = fn(...key);
+            statsEntry.track('fnTime', performance.now() - fnTimeStart);
+
+            cached = {value: result};
+            cache.set(key, result as ReturnType<Fn>);
+        }
+
+        statsEntry.track('cacheSize', cache.snapshot.size);
+        statsEntry.save();
+
+        return cached.value;
+    };
+
+    memoized.cache = cache;
+
+    memoized.stats = {
+        startMonitoring: () => stats.startMonitoring(),
+        stopMonitoring: () => stats.stopMonitoring(),
+    };
+
+    return memoized;
+}
+
+export default memoize;

src/libs/memoize/stats.ts

@@ -0,0 +1,104 @@
+type MemoizeStatsEntry = {
+    keyLength: number;
+    didHit: boolean;
+    cacheRetrievalTime: number;
+    fnTime?: number;
+    cacheSize: number;
+};
+
+class MemoizeStats {
+    private calls = 0;
+
+    private hits = 0;
+
+    private avgKeyLength = 0;
+
+    private avgCacheRetrievalTime = 0;
+
+    private avgFnTime = 0;
+
+    private cacheSize = 0;
+
+    enabled = false;
+
+    constructor(enabled: boolean) {
+        this.enabled = enabled;
+    }
+
+    // See https://en.wikipedia.org/wiki/Moving_average#Cumulative_average
+    private calculateCumulativeAvg(avg: number, length: number, value: number) {
+        return (avg * (length - 1) + value) / length;
+    }
+
+    private cumulateEntry(entry: MemoizeStatsEntry) {
+        this.calls++;
+        this.hits += entry.didHit ? 1 : 0;
+
+        this.cacheSize = entry.cacheSize;
+
+        this.avgKeyLength = this.calculateCumulativeAvg(this.avgKeyLength, this.calls, entry.keyLength);
+
+        this.avgCacheRetrievalTime = this.calculateCumulativeAvg(this.avgCacheRetrievalTime, this.hits, entry.cacheRetrievalTime);
+
+        if (entry.fnTime !== undefined) {
+            this.avgFnTime = this.calculateCumulativeAvg(this.avgFnTime, this.calls - this.hits, entry.fnTime);
+        }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static isMemoizeStatsEntry(entry: any): entry is MemoizeStatsEntry {
+        return entry.keyLength !== undefined && entry.didHit !== undefined && entry.cacheRetrievalTime !== undefined;
+    }
+
+    // eslint-disable-next-line rulesdir/prefer-early-return
+    private saveEntry(entry: Partial<MemoizeStatsEntry>) {
+        if (this.enabled && MemoizeStats.isMemoizeStatsEntry(entry)) {
+            this.cumulateEntry(entry);
+        }
+    }
+
+    createEntry() {
+        // If monitoring is disabled, return a dummy object that does nothing
+        if (!this.enabled) {
+            return {
+                track: () => {},
+                save: () => {},
+            };
+        }
+
+        const entry: Partial<MemoizeStatsEntry> = {};
+
+        return {
+            track: <P extends keyof MemoizeStatsEntry>(cacheProp: P, value: MemoizeStatsEntry[P]) => {
+                entry[cacheProp] = value;
+            },
+            save: () => this.saveEntry(entry),
+        };
+    }
+
+    startMonitoring() {
+        this.enabled = true;
+        this.calls = 0;
+        this.hits = 0;
+        this.avgKeyLength = 0;
+        this.avgCacheRetrievalTime = 0;
+        this.avgFnTime = 0;
+        this.cacheSize = 0;
+    }
+
+    stopMonitoring() {
+        this.enabled = false;
+
+        return {
+            calls: this.calls,
+            hits: this.hits,
+            avgKeyLength: this.avgKeyLength,
+            avgCacheRetrievalTime: this.avgCacheRetrievalTime,
+            avgFnTime: this.avgFnTime,
+            cacheSize: this.cacheSize,
+        };
+    }
+}
+
+export type {MemoizeStatsEntry};
+export {MemoizeStats};

src/libs/memoize/types.ts

@@ -0,0 +1,38 @@
+type KeyComparator = <K>(key1: K[], key2: K[]) => boolean;
+
+type Cache<K, V> = {
+    get: (key: K) => {value: V} | undefined;
+    set: (key: K, value: V) => void;
+    delete: (key: K) => boolean;
+    clear: () => void;
+    snapshot: {
+        keys: () => K[];
+        values: () => V[];
+        cache: () => Array<[K, V]>;
+        size: number;
+    };
+};
+
+type CacheOpts = {
+    maxSize: number;
+    equality: 'deep' | 'shallow' | KeyComparator;
+};
+
+type InternalOptions = {
+    cache: 'array';
+};
+
+type Options = {
+    maxSize: number;
+    equality: 'deep' | 'shallow' | KeyComparator;
+    monitor: boolean;
+} & InternalOptions;
+
+type ClientOptions = Partial<Omit<Options, keyof InternalOptions>>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MemoizeFnPredicate = (...args: any[]) => any;
+
+type MemoizedFn<Fn extends MemoizeFnPredicate> = Fn & {cache: Cache<Parameters<Fn>, ReturnType<Fn>>};
+
+export type {Cache, CacheOpts, Options, ClientOptions, MemoizedFn, KeyComparator, MemoizeFnPredicate};

src/libs/memoize/utils.ts

@@ -0,0 +1,23 @@
+import {deepEqual, shallowEqual} from 'fast-equals';
+import {DEFAULT_OPTIONS} from './const';
+import type {CacheOpts, ClientOptions, Options} from './types';
+
+function getEqualityComparator(opts: CacheOpts) {
+    switch (opts.equality) {
+        case 'deep':
+            return deepEqual;
+        case 'shallow':
+            return shallowEqual;
+        default:
+            return opts.equality;
+    }
+}
+
+function mergeOptions(options?: ClientOptions): Options {
+    if (!options) {
+        return DEFAULT_OPTIONS;
+    }
+    return {...DEFAULT_OPTIONS, ...options};
+}
+
+export {mergeOptions, getEqualityComparator};