@woosh/meep-engine 2.165.6 → 2.166.0

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

@@ -0,0 +1,10 @@
+/**
+ * *
+ */
+export type CacheRegionType = number;
+export namespace CacheRegionType {
+    let Window: number;
+    let Trial: number;
+    let Protected: number;
+}
+//# sourceMappingURL=CacheRegionType.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheRegionType.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/CacheRegionType.js"],"names":[],"mappings":";;;8BAEU,MAAM"}

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

@@ -0,0 +1,10 @@
+/**
+ *
+ * @enum {number}
+ * @private
+ */
+export const CacheRegionType = {
+    Window: 0,
+    Trial: 1,
+    Protected: 2
+};

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

@@ -0,0 +1,66 @@
+export class CacheRegionWTinylfu {
+    /**
+     *
+     * @param {number} maxWeight
+     */
+    constructor({ maxWeight }?: number);
+    /**
+     * Add new element to this region
+     * @param {CacheElementWTinylfu} element
+     * @param {number} [weight=element.weight]
+     */
+    add(element: CacheElementWTinylfu, weight?: number): void;
+    /**
+     * Update to MRU
+     * @param {CacheElementWTinylfu} element
+     */
+    touch(element: CacheElementWTinylfu): void;
+    /**
+     *
+     * @returns {CacheElementWTinylfu<Key,Value>|null}
+     */
+    findEvictionVictim(): CacheElementWTinylfu<Key, Value> | null;
+    /**
+     *
+     * @param {CacheElementWTinylfu<Key,Value>} element
+     * @param {number} [weight=element.weight]
+     * @private
+     */
+    private __removeElement;
+    /**
+     *
+     * @param {CacheElementWTinylfu<Key,Value>} element
+     * @param {number} [weight=element.weight]
+     */
+    remove(element: any, weight?: number): void;
+    /**
+     * Total weight of all elements in this region.
+     *
+     * @returns {number}
+     */
+    get weight(): number;
+    /**
+     *
+     * @param {number} delta
+     */
+    adjustWeight(delta: number): void;
+    /**
+     *
+     * @returns {number}
+     */
+    get maxWeight(): number;
+    /**
+     * Would the region exceed its capacity if `extraWeight` were added?
+     * Pass 0 (default) to test the current state.
+     * @param {number} [extraWeight=0]
+     * @returns {boolean}
+     */
+    wouldExceedCapacity(extraWeight?: number): boolean;
+    /**
+     * Empty the region. Elements are abandoned (the cache drops them from its lookup map).
+     */
+    clear(): void;
+    #private;
+}
+import { CacheElementWTinylfu } from "./CacheElementWTinylfu.js";
+//# sourceMappingURL=CacheRegionWTinylfu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheRegionWTinylfu.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/CacheRegionWTinylfu.js"],"names":[],"mappings":"AAIA;IA8BI;;;OAGG;IACH,4BAFW,MAAM,EAWhB;IAED;;;;OAIG;IACH,aAHW,oBAAoB,WACpB,MAAM,QAmBhB;IAED;;;OAGG;IACH,eAFW,oBAAoB,QAoB9B;IAED;;;OAGG;IACH,sBAFa,gCAA+B,GAAC,IAAI,CAIhD;IAED;;;;;OAKG;IACH,wBAcC;IAED;;;;OAIG;IACH,8BAFW,MAAM,QAMhB;IAED;;;;OAIG;IACH,qBAEC;IAED;;;OAGG;IACH,oBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,wBAEC;IAED;;;;;OAKG;IACH,kCAHW,MAAM,GACJ,OAAO,CAInB;IAED;;OAEG;IACH,cAIC;;CAEJ;qCArLkC,2BAA2B"}

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

@@ -0,0 +1,183 @@
+import {assert} from "../../assert.js";
+import {CacheElementWTinylfu} from "./CacheElementWTinylfu.js";
+
+
+export class CacheRegionWTinylfu {
+
+    /**
+     * How much "weight" the region can hold before it starts evicting elements
+     * @type {number}
+     * @private
+     */
+    #allowedMaxWeight = Number.POSITIVE_INFINITY;
+
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    #currentWeight = 0;
+
+    /**
+     * Head (next is LRU direction, previous is MRU direction)
+     * @type {CacheElementWTinylfu|null}
+     * @private
+     */
+    #first = null;
+
+    /**
+     * Tail (next is LRU direction, previous is MRU direction)
+     * @type {CacheElementWTinylfu|null}
+     * @private
+     */
+    #last = null;
+
+    /**
+     *
+     * @param {number} maxWeight
+     */
+    constructor({
+                    maxWeight = Number.POSITIVE_INFINITY
+                } = {}) {
+
+        assert.isNumber(maxWeight, 'maxWeight');
+        assert.notNaN(maxWeight, 'maxWeight');
+        assert.greaterThanOrEqual(maxWeight, 0, 'maxWeight < 0');
+
+        this.#allowedMaxWeight = maxWeight;
+    }
+
+    /**
+     * Add new element to this region
+     * @param {CacheElementWTinylfu} element
+     * @param {number} [weight=element.weight]
+     */
+    add(element, weight = element.weight){
+        assert.ok(element instanceof CacheElementWTinylfu);
+
+        // patch the element in
+        element.next = this.#first;
+
+        if (this.#first !== null) {
+            this.#first.previous = element;
+        }
+        this.#first = element;
+
+        if (this.#last === null) {
+            this.#last = element;
+        }
+
+        //update weight
+        this.#currentWeight += weight;
+    }
+
+    /**
+     * Update to MRU
+     * @param {CacheElementWTinylfu} element
+     */
+    touch(element) {
+        if (element === this.#first) {
+            // already at the front
+            return;
+        }
+
+        // update end-pointers
+        if (element === this.#last) {
+            this.#last = element.previous;
+        }
+
+        element.unlink(); //detach from the list
+
+        if (this.#first !== null) {
+            element.next = this.#first;
+            this.#first.previous = element;
+        }
+        this.#first = element;
+    }
+
+    /**
+     *
+     * @returns {CacheElementWTinylfu<Key,Value>|null}
+     */
+    findEvictionVictim() {
+        return this.#last;
+    }
+
+    /**
+     *
+     * @param {CacheElementWTinylfu<Key,Value>} element
+     * @param {number} [weight=element.weight]
+     * @private
+     */
+    __removeElement(element, weight = element.weight) {
+        // remove from the queue
+        if (element === this.#first) {
+            this.#first = element.next;
+        }
+
+        if (element === this.#last) {
+            this.#last = element.previous;
+        }
+
+        element.unlink();
+
+        //update weight
+        this.#currentWeight -= weight;
+    }
+
+    /**
+     *
+     * @param {CacheElementWTinylfu<Key,Value>} element
+     * @param {number} [weight=element.weight]
+     */
+    remove(element, weight = element.weight) {
+        assert.ok(element != null, "Attempted to remove undefined element");
+
+        this.__removeElement(element, weight);
+    }
+
+    /**
+     * Total weight of all elements in this region.
+     *
+     * @returns {number}
+     */
+    get weight() {
+        return this.#currentWeight;
+    }
+
+    /**
+     *
+     * @param {number} delta
+     */
+    adjustWeight(delta) {
+        this.#currentWeight += delta;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get maxWeight() {
+        return this.#allowedMaxWeight;
+    }
+
+    /**
+     * Would the region exceed its capacity if `extraWeight` were added?
+     * Pass 0 (default) to test the current state.
+     * @param {number} [extraWeight=0]
+     * @returns {boolean}
+     */
+    wouldExceedCapacity(extraWeight = 0) {
+        return this.#currentWeight + extraWeight > this.#allowedMaxWeight;
+    }
+
+    /**
+     * Empty the region. Elements are abandoned (the cache drops them from its lookup map).
+     */
+    clear() {
+        this.#first = null;
+        this.#last = null;
+        this.#currentWeight = 0;
+    }
+
+}

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

@@ -0,0 +1,279 @@
+export class CacheWTinylfu {
+    /**
+     *
+     * @param {number} [maxWeight=Number.POSITIVE_INFINITY] total weight budget of the cache; an element's weight is keyWeigher(key) + valueWeigher(value)
+     * @param {number} [promotionThreshold=1] frequency an item must exceed to be promoted out of Trial (Probation)
+     * @param {number} [capacityWindow=1] weight cap of the Window region (burst buffer)
+     * @param {number} [capacityProtected=1] weight cap of the Protected region (VIP segment of Main)
+     * @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]
+     */
+    constructor({ maxWeight, promotionThreshold, capacityWindow, capacityProtected, keyWeigher, valueWeigher, keyHashFunction, keyEqualityFunction }?: number);
+    /**
+     * Dispatched when an element is added or its value replaced. send2(key, value)
+     * @type {Signal}
+     */
+    onSet: Signal;
+    /**
+     * Dispatched when an element leaves the cache, by eviction or explicit remove. send2(key, value)
+     * @type {Signal}
+     */
+    onRemoved: Signal;
+    /**
+     * Dispatched when an element leaves due to capacity, immediately after onRemoved. send2(key, value)
+     * @type {Signal}
+     */
+    onEvicted: Signal;
+    /**
+     * Dispatched when admission control turns an element away (reject-guard or lost duel) — it was
+     * never stored. Unique to W-TinyLFU. send2(key, value)
+     * @type {Signal}
+     */
+    onRejected: Signal;
+    /**
+     * Update the recency & frequency of the cache element
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    private __touch;
+    /**
+     * Recency + promotion side of an access (no frequency increment).
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    private __onAccess;
+    /**
+     * Access of a Trial element: promote to Protected if hot enough and it fits, else bump recency.
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    private __onTrialAccess;
+    /**
+     * Record an access to `element` in the frequency sketch (using its cached key hash).
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    private __incrementSketch;
+    /**
+     * Estimated access frequency of `element` from the sketch (using its cached key hash).
+     * @param {CacheElementWTinylfu} element
+     * @returns {number}
+     * @private
+     */
+    private __frequency;
+    /**
+     * Is `element` hot enough and small enough to be promoted from Trial to Protected?
+     * (frequency above threshold AND fits Protected — contract in {@link shouldPromoteToProtected})
+     * @param {CacheElementWTinylfu} element
+     * @returns {boolean}
+     * @private
+     */
+    private __shouldPromoteToProtected;
+    /**
+     * The admission duel: does the candidate beat the victim on frequency?
+     * (contract in {@link winsAdmissionDuel})
+     * @param {CacheElementWTinylfu} candidate
+     * @param {CacheElementWTinylfu} victim
+     * @returns {boolean}
+     * @private
+     */
+    private __admissionDuel;
+    /**
+     * Explicitly remove (invalidate) a key. Fires onRemoved, but not onEvicted (not capacity-driven).
+     * @param {Key} key
+     * @returns {boolean} true if the key was present and removed
+     */
+    remove(key: Key): boolean;
+    /**
+     * Remove all entries. Fires onRemoved for each (explicit removal, so not onEvicted).
+     * The frequency sketch is left intact (history decays on its own).
+     */
+    clear(): void;
+    /**
+     * An element's weight: keyWeigher(key) + valueWeigher(value). Asserts each is a non-negative number.
+     * @param {Key} key
+     * @param {Value} value
+     * @returns {number}
+     * @private
+     */
+    private __computeElementWeight;
+    /**
+     * Total weight Main (Trial + Protected) is allowed to hold.
+     * @returns {number}
+     * @private
+     */
+    private __mainCapacity;
+    /**
+     * Would Main exceed its budget once `extraWeight` is added, counting current occupancy?
+     * (contract in {@link exceedsMainWeight})
+     * @param {number} [extraWeight=0]
+     * @returns {boolean}
+     * @private
+     */
+    private __exceedsMainWeight;
+    /**
+     * Could `weight` never fit Main, even with Trial fully evicted? (Protected's live weight is the
+     * immovable floor — contract in {@link cannotFitMain}.)
+     * @param {number} weight
+     * @returns {boolean}
+     * @private
+     */
+    private __cannotFitMain;
+    /**
+     * Decide where an element of `weight` is routed on admission: Reject, Window, or Trial.
+     * (contract in {@link classifyAdmission})
+     * @param {number} weight
+     * @returns {number} one of AdmissionRoute
+     * @private
+     */
+    private __classifyAdmission;
+    /**
+     * Demote a Protected element to Trial. Pure relocation — the caller restores Main's budget.
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    private __demoteToTrial;
+    /**
+     * Refit a grown Protected element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    private __refitGrownProtected;
+    /**
+     * Refit a grown Trial element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    private __refitGrownTrial;
+    /**
+     * Refit a grown Window element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    private __refitGrownWindow;
+    /**
+     * Route an update to an existing key: shrink/same-weight applies in place, a growth dispatches to the
+     * region's refit handler. On survival, commits the new value and counts the access.
+     * @param {CacheElementWTinylfu} element
+     * @param {Value} newValue
+     * @private
+     */
+    private __routeUpdate;
+    /**
+     * Relocate a resident into Trial (already removed from its prior region by the caller).
+     * @param {CacheElementWTinylfu} movedElement
+     * @private
+     */
+    private __moveToTrial;
+    /**
+     * First-time admission: place a new element in `region`, register it in the lookup map,
+     * and record its frequency.
+     * @param {CacheElementWTinylfu} element
+     * @param {CacheRegionType} region
+     * @private
+     */
+    private __admit;
+    /**
+     * Remove an element from its region's list and the lookup map. Always fires onRemoved; also fires
+     * onEvicted when capacity-driven (`evicted`, the default), but not for manual removal.
+     * @param {CacheElementWTinylfu} element
+     * @param {number} [weight=element.weight]
+     * @param {boolean} [evicted=true] true for capacity eviction, false for explicit removal
+     * @private
+     */
+    private __evict;
+    /**
+     * @param {CacheElementWTinylfu} element
+     * @returns {CacheRegionWTinylfu}
+     * @private
+     */
+    private __regionOf;
+    /**
+     * Earn `element` a place in Trial: if Main is over budget, duel it against the Trial LRU victim and,
+     * on a win, evict Trial victims until it fits. Verdict only — the caller owns the element's data entry.
+     * @param {CacheElementWTinylfu} element
+     * @returns {boolean} true if `element` is admitted and space was made for it;
+     *  false if it lost the admission duel.
+     * @private
+     */
+    private __prepareTrialSpaceFor;
+    /**
+     * @returns {CacheElementWTinylfu} Trial's LRU eviction victim
+     * @throws
+     * if Trial is empty while Main is over capacity (invariant: callers guarantee Trial holds enough evictable weight)
+     * @private
+     */
+    private __trialEvictionVictim;
+    /**
+     * Move a Window resident toward Trial through the admission duel; on a loss it is evicted
+     * (onRemoved + onEvicted).
+     * @param {CacheElementWTinylfu} candidate
+     * @param {number} [weight=candidate.weight] weight to reclaim from Window (override when it has changed)
+     * @returns {boolean} whether the candidate survived into Trial
+     * @private
+     */
+    private __nominateWindowToTrial;
+    /**
+     * Evict Window's LRU residents (nominating each to Trial) until `incomingWeight` fits.
+     * @param {number} incomingWeight
+     * @private
+     */
+    private __makeRoomInWindow;
+    /**
+     * Admit a new element that is too big for Window straight into the Trial duel; on a loss it is
+     * rejected (onRejected) — it was never stored.
+     * @param {CacheElementWTinylfu} newElement
+     * @private
+     */
+    private __nominateDirectToTrial;
+    /**
+     * Route a brand-new element per classifyAdmission: reject outright, insert into Window, or send it to
+     * the Trial duel.
+     * @param {CacheElementWTinylfu} newElement
+     * @private
+     */
+    private __routeAdmission;
+    /**
+     * Insert a new entry, or update the value of an existing key. The main write entry point.
+     * @param {Key} key
+     * @param {Value} value
+     */
+    put(key: Key, value: Value): void;
+    /**
+     * Look up a key. A hit counts as an access (recency + frequency, and may trigger promotion).
+     * @param {Key} key
+     * @returns {Value|null} the cached value, or null if not found
+     */
+    get(key: Key): Value | null;
+    /**
+     * @internal Diagnostic for tests/monitoring: which region currently holds `key`, or null if absent.
+     * Returns the immutable {@link CacheRegionType} — it does NOT expose the element itself.
+     * @param {Key} key
+     * @returns {CacheRegionType|null}
+     */
+    inspectRegion(key: Key): CacheRegionType | null;
+    /**
+     * @internal Diagnostic for tests/monitoring: the live weight currently held by each region.
+     * @returns {{window: number, trial: number, protected: number}}
+     */
+    inspectWeights(): {
+        window: number;
+        trial: number;
+        protected: number;
+    };
+    #private;
+}
+import { Signal } from "../../events/signal/Signal.js";
+import { CacheRegionType } from "./CacheRegionType.js";
+//# sourceMappingURL=CacheWTinylfu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheWTinylfu.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/CacheWTinylfu.js"],"names":[],"mappings":"AAiDA;IA0FI;;;;;;;;;;OAUG;IACH,mJATW,MAAM,EA+DhB;IA1FD;;;OAGG;IACH,OAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,WAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,WAFU,MAAM,CAES;IAEzB;;;;OAIG;IACH,YAFU,MAAM,CAEU;IAqE1B;;;;OAIG;IACH,gBAGC;IAED;;;;OAIG;IACH,mBAcC;IACD;;;;OAIG;IACH,wBAsBC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;OAKG;IACH,oBAEC;IAED;;;;;;OAMG;IACH,mCAEC;IAED;;;;;;;OAOG;IACH,wBAEC;IAED;;;;OAIG;IACH,kBAFa,OAAO,CAUnB;IAED;;;OAGG;IACH,cASC;IAED;;;;;;OAMG;IACH,+BAUC;IAED;;;;OAIG;IACH,uBAEC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,wBAEC;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;OAIG;IACH,wBAIC;IAED;;;;;;;OAOG;IACH,8BAmBC;IAED;;;;;;;OAOG;IACH,0BAeC;IAED;;;;;;;OAOG;IACH,2BAwBC;IAED;;;;;;OAMG;IACH,sBAkCC;IAED;;;;OAIG;IACH,sBAGC;IAED;;;;;;OAMG;IACH,gBAQC;IAED;;;;;;;OAOG;IACH,gBASC;IAoBD;;;;OAIG;IACH,mBAOC;IAED;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;OAKG;IACH,8BAMC;IAED;;;;;;;OAOG;IACH,gCAcC;IAED;;;;OAIG;IACH,2BASC;IAED;;;;;OAKG;IACH,gCAQC;IAED;;;;;OAKG;IACH,yBAmBC;IAED;;;;OAIG;IACH,kCAkBC;IAED;;;;OAIG;IACH,eAFa,QAAM,IAAI,CAWtB;IAID;;;;;OAKG;IACH,yBAFa,eAAe,GAAC,IAAI,CAKhC;IAED;;;OAGG;IACH,kBAFa;QAAC,QAAQ,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,CAQ9D;;CACJ;uBA9vBoB,+BAA+B;gCARtB,sBAAsB"}