@woosh/meep-engine 2.165.7 → 2.167.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"}