@woosh/meep-engine 2.165.6 → 2.166.0

package/src/core/cache/Cache.d.ts

@@ -1,56 +1,226 @@
-import Signal from "../events/signal/Signal";
-
-interface Hashable {
-    hash(): number
-    equals(other: any): boolean
-}
-
-export class Cache<K extends Hashable, V> extends Map<K,V>{
-    constructor({
-                    maxWeight,
-                    keyWeigher,
-                    valueWeigher,
-                    keyHashFunction,
-                    keyEqualityFunction,
-                    capacity
-                }?: {
-        maxWeight?: number,
-        keyWeigher?: (key: K) => number,
-        valueWeigher?: (value: V) => number,
-        keyHashFunction?: (key: K) => number,
-        keyEqualityFunction?: (a: K, b: K) => boolean,
-        capacity?: number
-    })
-
-    readonly onEvicted: Signal<K, V>
-    readonly onRemoved: Signal<K, V>
-    readonly onSet: Signal<K, V>
-
-    readonly weight: number
-
-    maxWeight: number
-
-    size(): number
-
-    put(k: K, v: V): void
-
-    get(k: K): V | null
-
-    contains(k: K): boolean
-
-    remove(k: K): boolean
-
-    silentRemove(k: K): boolean
-
-    evictOne(): boolean
-
-    clear(): void
-
-    drop(): void
-
-    getOrCompute(key: K, compute: (key: K) => V, compute_context?: any): V
-
-    recomputeWeight(): void
-
-    updateElementWeight(key: K): boolean
-}
+/**
+ * Hash-based cache, uses LRU (Least-Recently Used) eviction policy.
+ * Make sure that keys being used are truly immutable when it comes to hash and equality calculation; otherwise cache corruption is inevitable.
+ *
+ * @template Key
+ * @template Value
+ * @extends {Map<Key,Value>}
+ *
+ * @example
+ *  const cache = new Cache({maxWeight:2});
+ *
+ *  cache.put(key0, "a");
+ *  cache.put(key1, "b");
+ *  cache.put(key2, "c"); // cache has only enough space for 2 elements, key0 will be evicted
+ *
+ *  cache.get(key0); // null, was evicted
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Cache<Key, Value> {
+    /**
+     * Note: setting {@link maxWeight} to 0 is pointless, as the cache will not be able to hold even a single element.
+     *
+     * @param {number} [maxWeight=Number.POSITIVE_INFINITY] capacity of the cache, measure in "weight"; The weight is computed by summing key and value weights.
+     * @param {function(key:Key):number} [keyWeigher= key=>0] function to compute weight of a key
+     * @param {function(value:Value):number} [valueWeigher= value=>1] function to compute weight of a value
+     * @param {function(Key):number} [keyHashFunction]
+     * @param {function(Key, Key):boolean} [keyEqualityFunction]
+     * @param {number} [capacity] initial capacity for the cache, helps prevent early resizing
+     * @constructor
+     */
+    constructor({ maxWeight, keyWeigher, valueWeigher, keyHashFunction, keyEqualityFunction, capacity }?: number);
+    /**
+     *
+     * @type {function(Key): number}
+     * @private
+     */
+    private keyWeigher;
+    /**
+     *
+     * @type {function(Value): number}
+     * @private
+     */
+    private valueWeigher;
+    /**
+     *
+     * @type {CacheElement<Key,Value>|null}
+     * @private
+     */
+    private __first;
+    /**
+     *
+     * @type {CacheElement<Key,Value>|null}
+     * @private
+     */
+    private __last;
+    /**
+     *
+     * @type {HashMap<Key, CacheElement<Key,Value>>}
+     * @private
+     */
+    private data;
+    /**
+     * Dispatched when an element is evicted from the cache due to capacity constraints.
+     * Note that standard removal of an element will trigger as well, so {@link onRemoved} will still be dispatched as well, prior to this.
+     * @type {Signal<Key,Value>}
+     */
+    onEvicted: any;
+    /**
+     * Dispatched when an element is removed from the cache, either manually or due to eviction.
+     * @type {Signal<Key,Value>}
+     */
+    onRemoved: any;
+    /**
+     * Dispatched when an element is added to the cache.
+     * @type {Signal<Key,Value>}
+     */
+    onSet: any;
+    /**
+     * Marks the element as recently used.
+     * Moves the element to the end of the eviction queue
+     * @param {CacheElement<Key,Value>} element
+     * @private
+     */
+    private __promote;
+    /**
+     * Number of elements stored in cache
+     * @returns {number}
+     */
+    size(): number;
+    /**
+     * @deprecated use {@link maxWeight} directly instead
+     */
+    setMaxWeight(value: any): void;
+    /**
+     * Total weight of all elements currently in the cache.
+     * This is guaranteed to be less than or equal to {@link maxWeight}
+     *
+     * @returns {number}
+     */
+    get weight(): number;
+    /**
+     * Will cause evictions if the current weight is greater than what we're setting
+     * @param {number} weight
+     */
+    set maxWeight(arg: number);
+    get maxWeight(): number;
+    /**
+     * Forces weight to be recomputed for all elements stored in the cache
+     * Useful when values are mutated without re-insertion.
+     * In general - prefer to treat values as immutable
+     */
+    recomputeWeight(): void;
+    /**
+     * Useful when working with wrapped value types, where contents can change and affect overall weight
+     * Instead of re-inserting the element, we can just update weights
+     * NOTE: this method may trigger eviction
+     * @param {Key} key
+     * @returns {boolean} true when weight successfully updated, false if element was not found in cache
+     */
+    updateElementWeight(key: Key): boolean;
+    /**
+     * @private
+     * @param {Key} key
+     * @param {Value} value
+     * @returns {number}
+     */
+    private computeElementWeight;
+    /**
+     *
+     * @returns {CacheElement<Key,Value>|null}
+     */
+    findEvictionVictim(): CacheElement<Key, Value> | null;
+    /**
+     * Evicts a single element from the cache
+     * @returns {boolean} true if an element was evicted, false otherwise
+     */
+    evictOne(): boolean;
+    /**
+     * Drop data until the weight reduces to lower or equal to the requested weight
+     * @param {number} target_weight
+     */
+    evictUntilWeight(target_weight: number): void;
+    /**
+     *
+     * @param {Key} key
+     * @param {Value} value
+     */
+    put(key: Key, value: Value): void;
+    /**
+     *
+     * @param {Key} key
+     * @returns {boolean}
+     */
+    contains(key: Key): boolean;
+    /**
+     *
+     * @param {Key} key
+     * @returns {Value|null} value, or null if element was not found
+     */
+    get(key: Key): Value | null;
+    /**
+     * Please note that the key will be stored inside the cache, so it must be treated as immutable
+     * @param {Key} key
+     * @param {function(Key):Value} compute
+     * @param {*} [compute_context]
+     * @return {Value}
+     */
+    getOrCompute(key: Key, compute: (arg0: Key) => Value, compute_context?: any): Value;
+    /**
+     *
+     * @param {CacheElement<Key,Value>} element
+     * @private
+     */
+    private __removeElement;
+    /**
+     *
+     * @param {Key} key
+     * @returns {boolean} true if element was removed, false otherwise
+     */
+    remove(key: Key): boolean;
+    /**
+     * Remove without triggering {@link #onRemoved}
+     * NOTE: please be sure you understand what you're doing when you use this method
+     * @param {Key} key
+     * @returns {boolean} true if the element was removed, false otherwise
+     */
+    silentRemove(key: Key): boolean;
+    /**
+     * Remove all elements from the cache.
+     * Triggers {@link #onRemoved} for each removed element.
+     *
+     */
+    clear(): void;
+    /**
+     * Removed all data from cache
+     * NOTE: Does NOT signal via {@link removeListener}
+     */
+    drop(): void;
+    /**
+     *
+     * @param {function(message:string, key:Key, value:Value)} callback
+     * @param {*} [thisArg]
+     * @returns {boolean}
+     */
+    validate(callback: any, thisArg?: any): boolean;
+    /**
+     * Shortcut for "Map" class spec compliance
+     * @readonly
+     */
+    readonly set: (key: any, value: any) => void;
+    /**
+     * Shortcut for "Map" class spec compliance
+     * @readonly
+     */
+    readonly delete: (key: any) => boolean;
+    /**
+     * Shortcut for "Map" class spec compliance
+     * @readonly
+     */
+    readonly has: (key: any) => boolean;
+    #private;
+}
+import { CacheElement } from "./CacheElement.js";
+//# sourceMappingURL=Cache.d.ts.map

package/src/core/cache/Cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/Cache.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAgBI;;;;;;;;;;OAUG;IACH,sGARW,MAAM,EA2FhB;IAzDG;;;;OAIG;IACH,mBAA4B;IAE5B;;;;OAIG;IACH,qBAAgC;IAEhC;;;;OAIG;IACH,gBAAmB;IACnB;;;;OAIG;IACH,eAAkB;IAGlB;;;;OAIG;IACH,aAIE;IAEF;;;;OAIG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,WAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEE;IAE7B;;;OAGG;IACH,OAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEF;IAG7B;;;;;OAKG;IACH,kBAyBC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;OAGG;IACH,2BAeC;IAED,wBAEC;IAED;;;;OAIG;IACH,wBAaC;IAED;;;;;;OAMG;IACH,yBAHW,GAAG,GACD,OAAO,CAgCnB;IAED;;;;;OAKG;IACH,6BAUC;IAED;;;OAGG;IACH,sBAFa,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAIxC;IAED;;;OAGG;IACH,YAFa,OAAO,CAkBnB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAWhB;IAED;;;;OAIG;IACH,SAHW,GAAG,SACH,KAAK,QA+Ef;IAED;;;;OAIG;IACH,cAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,KAAK,GAAC,IAAI,CAYtB;IAGD;;;;;;OAMG;IACH,kBALW,GAAG,kBACM,GAAG,KAAE,KAAK,0BAElB,KAAK,CAchB;IAED;;;;OAIG;IACH,wBAqBC;IAED;;;;OAIG;IACH,YAHW,GAAG,GACD,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,kBAHW,GAAG,GACD,OAAO,CAanB;IAED;;;;OAIG;IACH,cAcC;IAED;;;OAGG;IACH,aAOC;IAED;;;;;OAKG;IACH,wCAFa,OAAO,CAMnB;IAGL;;;OAGG;IACH,6CAAmB;IAEnB;;;OAGG;IACH,+BA9FiB,OAAO,CA8FF;IAEtB;;;OAGG;IACH,4BAhLiB,OAAO,CAgLL;;CAlBlB;mBA7kBkB,4BAA4B;6BAKlB,mBAAmB"}
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/Cache.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAgBI;;;;;;;;;;OAUG;IACH,sGARW,MAAM,EA2FhB;IAzDG;;;;OAIG;IACH,mBAA4B;IAE5B;;;;OAIG;IACH,qBAAgC;IAEhC;;;;OAIG;IACH,gBAAmB;IACnB;;;;OAIG;IACH,eAAkB;IAGlB;;;;OAIG;IACH,aAIE;IAEF;;;;OAIG;IACH,eAA6B;IAE7B;;;OAGG;IACH,eAA6B;IAE7B;;;OAGG;IACH,WAAyB;IAG7B;;;;;OAKG;IACH,kBAqBC;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;OAEG;IACH,+BAEC;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;OAGG;IACH,2BAeC;IAED,wBAEC;IAED;;;;OAIG;IACH,wBAaC;IAED;;;;;;OAMG;IACH,yBAHW,GAAG,GACD,OAAO,CAgCnB;IAED;;;;;OAKG;IACH,6BAUC;IAED;;;OAGG;IACH,sBAFa,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAIxC;IAED;;;OAGG;IACH,YAFa,OAAO,CAkBnB;IAED;;;OAGG;IACH,gCAFW,MAAM,QAWhB;IAED;;;;OAIG;IACH,SAHW,GAAG,SACH,KAAK,QA+Ef;IAED;;;;OAIG;IACH,cAHW,GAAG,GACD,OAAO,CAInB;IAED;;;;OAIG;IACH,SAHW,GAAG,GACD,KAAK,GAAC,IAAI,CAYtB;IAGD;;;;;;OAMG;IACH,kBALW,GAAG,kBACM,GAAG,KAAE,KAAK,0BAElB,KAAK,CAchB;IAED;;;;OAIG;IACH,wBAqBC;IAED;;;;OAIG;IACH,YAHW,GAAG,GACD,OAAO,CAgBnB;IAED;;;;;OAKG;IACH,kBAHW,GAAG,GACD,OAAO,CAanB;IAED;;;;OAIG;IACH,cAcC;IAED;;;OAGG;IACH,aAOC;IAED;;;;;OAKG;IACH,wCAFa,OAAO,CAMnB;IAGL;;;OAGG;IACH,6CAAmB;IAEnB;;;OAGG;IACH,+BA9FiB,OAAO,CA8FF;IAEtB;;;OAGG;IACH,4BAhLiB,OAAO,CAgLL;;CAlBlB;6BApkB4B,mBAAmB"}

package/src/core/cache/Cache.js

@@ -159,15 +159,11 @@ export class Cache {
 
         element.unlink();
 
-        element.previous = null;
-
         if (this.__first !== null) {
             // shift previous head element forward
             element.next = this.__first;
 
             this.__first.previous = element;
-        } else {
-            element.next = null;
         }
 
         this.__first = element;

package/src/core/cache/CacheElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheElement.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/CacheElement.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IAEI;;;OAGG;IACH,KAFU,GAAG,CAEF;IAEX;;;OAGG;IACH,OAFU,KAAK,CAEF;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAE1B;IAEZ;;;OAGG;IACH,UAFU,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAEtB;IAEhB,eAWC;IAED,mBAEC;CACJ"}
+{"version":3,"file":"CacheElement.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/CacheElement.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IAEI;;;OAGG;IACH,KAFU,GAAG,CAEF;IAEX;;;OAGG;IACH,OAFU,KAAK,CAEF;IAEb;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAE1B;IAEZ;;;OAGG;IACH,UAFU,aAAa,GAAG,EAAC,KAAK,CAAC,GAAC,IAAI,CAEtB;IAEhB,eAeC;IAED,mBAEC;CACJ"}

package/src/core/cache/CacheElement.js

@@ -47,6 +47,10 @@ export class CacheElement {
         if (next !== null) {
             next.previous = previous;
         }
+
+        // detach self fully, so the element is safe to re-add to another list
+        this.next = null;
+        this.previous = null;
     }
 
     toString() {

package/src/core/cache/FrequencySketch.d.ts

@@ -84,30 +84,9 @@ export class FrequencySketch<T> {
      * @param {number} input_hash the element to add
      */
     increment(input_hash: number): void;
-    /**
-     * Increments the specified counter by 1 if it is not already at the maximum value (15).
-     *
-     * @param {number} i the table index (8 counters)
-     * @param {number} j the counter to increment
-     * @returns {boolean} if incremented
-     */
-    incrementAt(i: number, j: number): boolean;
     /**
      * Reduces every counter by half of its original value.
      */
     reset(): void;
-    /**
-     * Returns the table index for the counter at the specified depth.
-     * @param {number} item the element's hash
-     * @param {number} i the counter depth
-     * @returns {number} the table index
-     */
-    indexOf(item: number, i: number): number;
-    /**
-     * Applies a supplemental hash function to a given hash code, which defends against poor quality
-     * @param {number} v
-     * @returns {number}
-     */
-    spread(v: number): number;
 }
 //# sourceMappingURL=FrequencySketch.d.ts.map

package/src/core/cache/FrequencySketch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrequencySketch.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/FrequencySketch.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAED;IACf;;;OAGG;IACH,WAFU,MAAM,CAEF;IACd;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IACb;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,4BAFW,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,oBAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;OAOG;IACH,sBAFW,MAAM,QAwBhB;IAED;;;;;;OAMG;IACH,eAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAgBnB;IAED;;OAEG;IACH,cAaC;IAED;;;;;OAKG;IACH,cAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,UAHW,MAAM,GACJ,MAAM,CASlB;CACJ"}
+{"version":3,"file":"FrequencySketch.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/FrequencySketch.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAED;IACf;;;OAGG;IACH,WAFU,MAAM,CAEF;IACd;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IACb;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,4BAFW,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,oBAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,MAAM,CAgBlB;IAED;;;;;;;OAOG;IACH,sBAFW,MAAM,QAwBhB;IAED;;OAEG;IACH,cAaC;CACJ"}

package/src/core/cache/FrequencySketch.js

@@ -19,6 +19,55 @@ const ONE_MASK = 0x11111111;
  */
 const MAX_INT_32 = 2147483647;
 
+/**
+ * Applies a supplemental hash function to a given hash code, which defends against poor quality hashes.
+ * @param {number} v
+ * @returns {number}
+ */
+function spread(v) {
+    let x = v;
+
+    x = ((x >>> 16) ^ x) * 0x45d9f3b;
+    x = ((x >>> 16) ^ x) * 0x45d9f3b;
+
+    return (x >>> 16) ^ x;
+}
+
+/**
+ * Returns the table index for the counter at the specified depth.
+ * @param {number} item the element's hash
+ * @param {number} i the counter depth
+ * @param {number} tableMask the table-size mask
+ * @returns {number} the table index
+ */
+function indexOf(item, i, tableMask) {
+    let hash = (item + SEED[i]) * SEED[i];
+    hash += (hash >>> 16);
+
+    return hash & tableMask;
+}
+
+/**
+ * Increments the specified counter by 1 if it is not already at the maximum value (15).
+ * @param {Uint32Array} table the counter table
+ * @param {number} i the table index (8 counters)
+ * @param {number} j the counter to increment
+ * @returns {boolean} if incremented
+ */
+function incrementAt(table, i, j) {
+    const offset = j << 2;
+    const mask = (0xF << offset);
+
+    const existing_table_value = table[i];
+
+    if ((existing_table_value & mask) !== mask) {
+        table[i] = existing_table_value + (1 << offset);
+        return true;
+    }
+
+    return false;
+}
+
 /**
  * A probabilistic multiset for estimating the popularity of an element within a time window. The
  * maximum frequency of an element is limited to 15 (4-bits) and an aging process periodically
@@ -121,13 +170,15 @@ export class FrequencySketch {
      * @returns {number} the estimated number of occurrences of the element; possibly zero but never negative
      */
     frequency(input_hash) {
-        const hash = this.spread(input_hash);
+        const table = this.table;
+        const tableMask = this.tableMask;
+        const hash = spread(input_hash);
         const start = (hash & 3) << 2;
         let frequency = MAX_INT_32;
 
         for (let i = 0; i < 4; i++) {
-            const index = this.indexOf(hash, i);
-            const count = (this.table[index] >>> ((start + i) << 2)) & 0xf;
+            const index = indexOf(hash, i, tableMask);
+            const count = (table[index] >>> ((start + i) << 2)) & 0xf;
             frequency = min2(frequency, count);
         }
 
@@ -143,21 +194,21 @@ export class FrequencySketch {
      * @param {number} input_hash the element to add
      */
     increment(input_hash) {
-        const hash = this.spread(input_hash);
+        const table = this.table;
+        const tableMask = this.tableMask;
+        const hash = spread(input_hash);
         const start = (hash & 3) << 2;
 
         // Loop unrolling improves throughput by 5m ops/s
-        const index0 = this.indexOf(hash, 0);
-        const index1 = this.indexOf(hash, 1);
-        const index2 = this.indexOf(hash, 2);
-        const index3 = this.indexOf(hash, 3);
-
-        // Evaluate all four counters unconditionally; `||` would short-circuit and skip the remaining
-        // increments as soon as the first one returned true, so only one of the four counters would ever advance.
-        const added0 = this.incrementAt(index0, start);
-        const added1 = this.incrementAt(index1, start + 1);
-        const added2 = this.incrementAt(index2, start + 2);
-        const added3 = this.incrementAt(index3, start + 3);
+        const index0 = indexOf(hash, 0, tableMask);
+        const index1 = indexOf(hash, 1, tableMask);
+        const index2 = indexOf(hash, 2, tableMask);
+        const index3 = indexOf(hash, 3, tableMask);
+
+        const added0 = incrementAt(table, index0, start);
+        const added1 = incrementAt(table, index1, start + 1);
+        const added2 = incrementAt(table, index2, start + 2);
+        const added3 = incrementAt(table, index3, start + 3);
 
         const added = added0 || added1 || added2 || added3;
 
@@ -166,29 +217,6 @@ export class FrequencySketch {
         }
     }
 
-    /**
-     * Increments the specified counter by 1 if it is not already at the maximum value (15).
-     *
-     * @param {number} i the table index (8 counters)
-     * @param {number} j the counter to increment
-     * @returns {boolean} if incremented
-     */
-    incrementAt(i, j) {
-        const offset = j << 2;
-        const mask = (0xF << offset);
-
-        const table = this.table;
-
-        const existing_table_value = table[i];
-
-        if ((existing_table_value & mask) !== mask) {
-            table[i] = existing_table_value + (1 << offset);
-            return true;
-        }
-
-        return false;
-    }
-
     /**
      * Reduces every counter by half of its original value.
      */
@@ -206,31 +234,4 @@ export class FrequencySketch {
 
         this.size = (this.size >>> 1) - (count >>> 2);
     }
-
-    /**
-     * Returns the table index for the counter at the specified depth.
-     * @param {number} item the element's hash
-     * @param {number} i the counter depth
-     * @returns {number} the table index
-     */
-    indexOf(item, i) {
-        let hash = (item + SEED[i]) * SEED[i];
-        hash += (hash >>> 16);
-
-        return hash & this.tableMask;
-    }
-
-    /**
-     * Applies a supplemental hash function to a given hash code, which defends against poor quality
-     * @param {number} v
-     * @returns {number}
-     */
-    spread(v) {
-        let x = v;
-
-        x = ((x >>> 16) ^ x) * 0x45d9f3b;
-        x = ((x >>> 16) ^ x) * 0x45d9f3b;
-
-        return (x >>> 16) ^ x;
-    }
 }

package/src/core/cache/LoadingCache.d.ts

@@ -1,23 +1,72 @@
-export declare class LoadingCache<K, V> {
-    constructor(options: {
-        maxWeight?: number,
-        keyWeigher?: (key: K) => number,
-        valueWeigher?: (value: V) => number,
-        keyHashFunction?: (key: K) => number,
-        keyEqualityFunction?: (a: K, b: K) => boolean,
-        capacity?: number,
-        timeToLive?: number,
-        load: (key: K) => Promise<V>,
-        retryFailed?: boolean
-    })
-
-    refresh(key: K): Promise<V>
-
-    invalidate(key: K): void
-
-    clear(): void
-
-    get(key: K): Promise<V>
-
-    put(key: K, value: V): void
-}
+/**
+ * Asynchronous cache capable of resolving its own values by keys
+ * Modelled on Guava's LoadingCache concept
+ * @template K
+ * @template V
+ * @class
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class LoadingCache<K, V> {
+    /**
+     * @see {@link Cache} for more details on what each parameter means
+     * @param [maxWeight]
+     * @param [keyWeigher]
+     * @param [valueWeigher]
+     * @param [keyHashFunction]
+     * @param [keyEqualityFunction]
+     * @param [capacity]
+     * @param {number} [timeToLive] in seconds, default is 10 seconds
+     * @param {function(key:K):Promise<V>} load
+     * @param {boolean} [retryFailed]
+     */
+    constructor({ maxWeight, keyWeigher, valueWeigher, keyHashFunction, keyEqualityFunction, capacity, timeToLive, load, retryFailed }?: {
+        maxWeight: any;
+        keyWeigher: any;
+        valueWeigher?: typeof returnZero;
+        keyHashFunction: any;
+        keyEqualityFunction: any;
+        capacity: any;
+        timeToLive?: number;
+        load: any;
+        retryFailed?: boolean;
+    });
+    /**
+     *
+     * @param {K} key
+     * @returns {boolean}
+     */
+    invalidate(key: K): boolean;
+    /**
+     *
+     */
+    clear(): void;
+    /**
+     * Load new value for the key (happens asynchronously)
+     * @param {K} key
+     * @returns {Promise<V>}
+     */
+    refresh(key: K): Promise<V>;
+    /**
+     * Directly insert value into the cache
+     * @param {K} key
+     * @param {V} value
+     */
+    put(key: K, value: V): void;
+    /**
+     *
+     * @param {K} key
+     * @returns {boolean}
+     */
+    contains(key: K): boolean;
+    /**
+     *
+     * @param {K} key
+     * @return {Promise<V>}
+     */
+    get(key: K): Promise<V>;
+    #private;
+}
+import { returnZero } from "../function/returnZero.js";
+//# sourceMappingURL=LoadingCache.d.ts.map

package/src/core/cache/wtinylfu/CacheElementWTinylfu.d.ts

@@ -0,0 +1,17 @@
+export class CacheElementWTinylfu extends CacheElement<any, any> {
+    constructor();
+    /**
+     *
+     * @type {CacheRegionType}
+     */
+    region: CacheRegionType;
+    /**
+     * Cached key hash (keyHashFunction(key)), computed once at admission so the frequency-sketch paths
+     * (increment / frequency / admission duel) never recompute it.
+     * @type {number}
+     */
+    keyHash: number;
+}
+import { CacheElement } from "../CacheElement.js";
+import { CacheRegionType } from "./CacheRegionType.js";
+//# sourceMappingURL=CacheElementWTinylfu.d.ts.map

package/src/core/cache/wtinylfu/CacheElementWTinylfu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheElementWTinylfu.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/CacheElementWTinylfu.js"],"names":[],"mappings":"AAGA;;IAEI;;;OAGG;IACH,QAFU,eAAe,CAEO;IAEhC;;;;OAIG;IACH,SAFU,MAAM,CAEJ;CACf;6BAjB0B,oBAAoB;gCACjB,sBAAsB"}

package/src/core/cache/wtinylfu/CacheElementWTinylfu.js

@@ -0,0 +1,18 @@
+import {CacheElement} from "../CacheElement.js";
+import {CacheRegionType} from "./CacheRegionType.js";
+
+export class CacheElementWTinylfu extends CacheElement {
+
+    /**
+     *
+     * @type {CacheRegionType}
+     */
+    region = CacheRegionType.Window;
+
+    /**
+     * Cached key hash (keyHashFunction(key)), computed once at admission so the frequency-sketch paths
+     * (increment / frequency / admission duel) never recompute it.
+     * @type {number}
+     */
+    keyHash = 0;
+}