@woosh/meep-engine 2.165.6 → 2.166.0

package/src/core/cache/wtinylfu/benchmark/CacheWTinylfu.bench.md

@@ -0,0 +1,243 @@
+# W-TinyLFU benchmarks
+
+Benchmarks comparing `CacheWTinylfu` against the LRU `Cache` sibling. They split into **two axes**
+that answer different questions:
+
+| Axis | Question | Answered by |
+|------|----------|-------------|
+| **Effectiveness** (hit rate) | What fraction of accesses hit? Determined by the **policy**. | `hitRate.spec.js` |
+| **Performance** (throughput / latency / space) | What does each operation **cost**? Determined by the **implementation**. | everything else |
+
+You need both to judge the trade: the policy benchmark tells you what W-TinyLFU *saves you in misses*;
+the performance benchmarks tell you what it *costs per op and in RAM*. The exchange rate between them is
+the cost of a miss in your system (a disk/network miss dwarfs a few hundred ns; a cheap recompute does not).
+
+> ⚠️ **About the numbers below.** They're from one dev machine (Node v20.14.0, Windows 11) and microbenchmarks
+> are noisy — absolute nanoseconds wander run-to-run by tens of percent. **Trust the ratios and the shape, not
+> the exact ns.** The ratios are measured *interleaved* (LRU and W-TinyLFU timed back-to-back each round, then
+> the per-round ratios medianed), so they stay stable even as the absolutes drift. Re-run on your own hardware
+> for absolutes.
+
+---
+
+## Running
+
+Each benchmark is a **self-executing spec**: a single `<name>.spec.js` that is *both* a runnable Node
+benchmark and a Jest spec. The measurement **only ever runs under plain `node`** — never in-process under
+Jest, because Jest's babel transform badly distorts the timings (see *Why not measure under Jest* below).
+The files are stripped from the published npm package by the `*.spec.js` rule.
+
+**To get numbers — run it directly with `node`, from the repo root:**
+
+```bash
+node src/core/cache/wtinylfu/benchmark/<name>.spec.js
+```
+
+where `<name>` is one of: `hitRate`, `fillDrain`, `readAll`, `continuousPut`, `mixed`, `latency`, `scaling`,
+`memory`.
+
+**Under Jest** each file is a `describe.skip`, so `npx jest` collects but skips them (zero CI cost). Un-skip
+one (flip `describe.skip` → `describe`) and Jest will **spawn a clean `node` child on the file** and check the
+output is sane — you get the same pristine numbers, never the transformed ones.
+
+Two flags (for the `node` invocation):
+
+- **`--expose-gc`** (a Node flag, goes *before* the script path): lets a benchmark force GC between trials for
+  cleaner numbers. Optional for most; **required** for `memory` (it refuses to run without it). *(When run via
+  Jest, the child is always spawned with `--expose-gc`.)*
+  ```bash
+  node --expose-gc src/core/cache/wtinylfu/benchmark/fillDrain.spec.js
+  ```
+- **`HASH=int`** (an env var): the **isolated-hash toggle** — use integer keys + an identity hash instead of
+  string keys + `computeStringHash`, to strip string-hashing cost and see pure-policy overhead. Works on
+  **every** benchmark.
+  ```bash
+  HASH=int node --expose-gc src/core/cache/wtinylfu/benchmark/readAll.spec.js
+  ```
+
+All workloads are **seeded**, so runs are reproducible. Both caches are always built at **matched capacity**
+(N weight-1 entries) so the comparison is fair.
+
+### Layout & file structure
+
+Each benchmark lives in its own self-contained file in this `benchmark/` folder as `<name>.spec.js`.
+There is **no shared harness** — each file inlines the scaffolding it needs, so it stands alone (copy it,
+run it, read it without chasing imports). Every file follows the same skeleton:
+
+```
+1. HEADER       what it measures · how to run · how to read it
+2. CONFIG       the knobs: CAPACITY / WARMUP / TRIALS / SEED
+3. SCAFFOLDING  inlined: clock, rng, matched-capacity factories, measureInterleaved, any workload
+                (top-level — pure definitions, safe when Jest imports the file)
+   if (under Jest) → spawn a clean `node` on this file + assert the output is sane
+   else            → the actual benchmark:
+4. WORKLOAD       the setup + the timed body                       (the "arrange")
+5. MEASURE        measureInterleaved([LRU, W-TinyLFU], {...})      (the "act")
+6. REPORT         formatting + console.log                         (the "assert" analog — reports, no pass/fail)
+```
+
+The `if (typeof describe === "function")` split is what keeps the measurement out of Jest's transform: under
+Jest only the spawn-branch runs; under `node` only the `else` (measurement) branch runs.
+
+A benchmark **reports** numbers; it does not **assert** pass/fail. That's why the measurement always runs
+under plain `node` — the Jest side only launches it and checks the output isn't empty.
+
+### Why not measure under Jest
+
+Jest runs every file through **babel-jest** before V8 sees it (transpiled to CommonJS, wrapped in Jest's
+module registry). That transformed code JITs differently from the native ES module `node` runs — and the
+overhead is **not uniform**: a cheap op (LRU) takes a bigger proportional hit than a heavier one (W-TinyLFU).
+Measured in-process under Jest, absolutes inflated ~2–12× **and several ratios inverted** — `fill` read
+1.76x → 0.91x, `mixed` 1.48x → 0.90x, `latency p50` 3.0x → 0.86x — i.e. Jest would tell you W-TinyLFU is
+*faster* than LRU on inserts, which is false. It was also ~4× slower wall-clock. So the benchmark body never
+runs under Jest; the spec spawns a clean `node` child and only checks the output is well-formed.
+
+---
+
+## Effectiveness — `hitRate.spec.js`
+
+Replays seeded access traces as a read-through cache and reports **hit ratio** (capacity N = 500). This is
+where W-TinyLFU earns its keep.
+
+```
+                                       LRU      W-TinyLFU    Δ
+uniform random (no skew)              10.0%      10.0%      0.0   ← control: no harm
+zipfian skew 0.7 / 0.9 / 1.1        22.7/45.4/70.7  ~equal  ±1    ← realistic skew: roughly even
+scan (hot set + one-shot scans)       31.6%      47.0%     +15.4  ← scan resistance: the big win
+cyclic loop (size > capacity)         LRU pathological case  win  ← incumbent-favoring ties
+```
+
+**Takeaway:** roughly even with LRU on plain skew, *no worse* on uniform, and a large win on **scan-heavy**
+and **cyclic** workloads (where LRU is catastrophic). That scan resistance is the reason to pay the costs below.
+
+---
+
+## Performance
+
+Realistic (string-key) mode, `--expose-gc`, interleaved, median of 100 trials. **Capacities:** the read / fill /
+space and `continuousPut` benchmarks use **N = 65,536**; `mixed` uses a quarter of that (**N = 16,384**,
+keyspace 10×N) so its keyspace can dwarf the cache for realistic misses. All are powers of two — safe under
+churn because the shared HashMap grows headroom at its load factor.
+
+### `fillDrain` — insert + teardown
+
+```
+fill (put)       | LRU ~197 ns/op  | W-TinyLFU ~378 ns/op  | ~2.1x
+drain (clear)    | LRU ~21 ms/call | W-TinyLFU ~11 ms/call  | ~0.52x
+drain (remove)   | LRU ~259 ns/op  | W-TinyLFU ~317 ns/op   | ~1.2x
+```
+`fill` is the policy's insert cost (sketch + region routing). The `drain` rows reflect each class's *teardown
+implementation*, not the policy — LRU's `clear()` removes element-by-element while W-TinyLFU bulk-resets, so the
+drain difference is an implementation artifact.
+
+### `readAll` — read path (cold vs warm)
+
+```
+read cold        | LRU ~370 ns/op | W-TinyLFU ~710 ns/op | ~1.9x
+read warm        | LRU ~290 ns/op | W-TinyLFU ~490 ns/op | ~1.7x
+```
+Every get is a hit. `cold` = first read-pass (W-TinyLFU's promotion activity); `warm` = settled steady state.
+The premium is modest and one-time, not a recurring spike.
+
+### `continuousPut` — sustained load (churn vs update)
+
+```
+put churn        | LRU ~660 ns/op | W-TinyLFU ~656 ns/op | ~1.0x   (new keys → evict + admission duel)
+put update       | LRU ~220 ns/op | W-TinyLFU ~447 ns/op | ~2.0x   (re-put existing keys → in-place)
+```
+**The key reframe.** W-TinyLFU's extra policy work is roughly **additive (~150–200 ns/op)**, not a multiplier —
+on the cheap `update` baseline it shows as ~2.1×. On `churn` it doesn't show at all: **element pooling** makes
+W-TinyLFU's inserts allocation-free, while LRU still allocates an element per insert, so that saving *offsets*
+the policy overhead and W-TinyLFU draws level with LRU (~1.0×).
+
+### `mixed` — realistic blended throughput
+
+```
+mixed get/put    | LRU ~157 ns/op | W-TinyLFU ~224 ns/op | ~1.4x
+```
+Zipfian read-through (get; on miss, put) over a keyspace 10× the cache — the most representative single number.
+
+### `latency` — the tail (percentiles)
+
+```
+              p50    p99    p999     max
+LRU           200   ~700   ~2400    multi-ms (GC)
+W-TinyLFU     300   ~1300  ~7400    multi-ms (GC)
+```
+Per-op timing during a fill. W-TinyLFU's whole distribution shifts up ~2× — its heavier insert, paid broadly
+rather than in a rare spike. The **max is a multi-ms GC pause on both**, not a policy event — read the policy
+tail in p99/p999, not max.
+
+### `memory` — bytes per entry (space) · requires `--expose-gc`
+
+```
+                       fresh fill                 after churn (steady state)
+LRU          | ~144 (heap ~136 + ext ~8)  | ~224 (heap ~208 + ext ~16)  bytes/entry
+W-TinyLFU    | ~164 (heap ~152 + ext ~12) | ~245 (heap ~225 + ext ~20)  bytes/entry
+→ fresh, W-TinyLFU vs LRU: +~20 B/entry  (+~16 heap = per-element `region` + `keyHash`; +~4 sketch)
+→ churn cost (both caches): +~80 B/entry  (the shared HashMap doubling its slab at the load factor)
+```
+~14% more RAM per entry for the **policy** (fresh) — the **W-vs-LRU difference of ~4 B ≈ the sketch**. The
+**churn cost** is the same +~80 for both because it's the *shared HashMap*, not the policy: once the cache is
+full and evicting, the entries slab (and its bins) hits the 0.75 load factor and **doubles** to keep amortised
+O(1) inserts, so a churning cache carries ~2× the entry headroom of a fresh fill.
+
+### `scaling` — O(1) check + locality across N
+
+```
+     N        LRU      W-TinyLFU   ratio
+    2,048     62.3       175.6      2.88x
+   16,384    102.8       230.0      2.25x
+  131,072    379.2       556.8      1.47x
+1,048,576    667.7       911.8      1.37x        (warm random read, ns/op)
+```
+Per-op cost rises only ~11× from 2k→1M (not ~500×) → **O(1) confirmed**; the rise is **CPU-cache locality**.
+The ratio **compresses as N grows** — both caches increasingly bottlenecked on RAM latency at large N.
+
+### `HASH=int` — pure-policy overhead (cross-cutting)
+
+Run any benchmark with `HASH=int` to strip string hashing. Example (read warm):
+
+```
+                realistic        isolated (HASH=int)
+LRU              ~290 ns/op        ~151 ns/op
+W-TinyLFU        ~490 ns/op        ~338 ns/op
+ratio             ~1.7x             ~2.3x
+```
+Reveals that **string hashing is a large *shared* cost** (~140 ns of LRU's warm read was just `Map` string
+hashing, paid by both caches). Removing it shrinks the baseline, so the *same* fixed policy overhead becomes a
+bigger multiple.
+
+---
+
+## Headline findings
+
+1. **Cost is a roughly fixed additive overhead, not a multiplier** — ~100–300 ns/op of extra work (sketch
+   increment + region bookkeeping), so the "Nx" you see depends mostly on how cheap the underlying op already was.
+2. **O(1) and predictable** — confirmed across 3 orders of magnitude; the only growth is shared CPU-cache locality.
+3. **No tail surprises** — the overhead is spread across the whole distribution (median through p999), not a rare
+   spike; the worst-case `max` is a GC pause both caches share.
+4. **~14% more memory per entry** — the per-element `region` + `keyHash` fields plus the O(N) frequency sketch
+   (plus a shared ~+80 B/entry once any cache is full and churning — the HashMap doubling its slab, not policy-specific).
+5. **Bought against scan resistance** — the effectiveness axis shows large hit-rate wins on scan/cyclic workloads,
+   while staying roughly even with LRU on plain skew and doing no harm on uniform.
+
+**The trade in one line:** ~150–200 ns/op and ~14% RAM, predictable and O(1), in exchange for scan-resistant,
+frequency-aware retention — worth it exactly when your misses are expensive and your traffic isn't purely uniform.
+
+## Methodology notes (why the numbers are trustworthy)
+
+- **Pre-generated keys** outside the timed region (else you measure string allocation, not the cache).
+- **Warmup** discarded so the JIT has compiled the hot path (we measure optimized machine code, not the cold
+  interpreter).
+- **Interleaved trials** — every round times LRU and W-TinyLFU back-to-back, and the ratio is the **median of
+  the per-round ratios** (paired). So machine drift within a round hits both equally and cancels in the ratio.
+- **Median of trials** (not mean) to shrug off the occasional GC pause.
+- **Selective `forceGc`** — forced for low-allocation bodies (reads, teardown) where a stray pause is pure noise;
+  *not* for allocation-heavy bodies (fill, churn) where GC is part of the real cost.
+- **Result sinks** so pure-read loops aren't deleted by dead-code elimination.
+- **Matched capacity & shared seeded workloads** so LRU and W-TinyLFU face identical conditions.
+- **Measured under `node`, never in-process under a test runner** — a transform (babel/esbuild) distorts both
+  the absolute ns *and* the ratio (a cheap op suffers proportionally more overhead). Measured under Jest
+  in-process, several ratios *inverted* (e.g. `fill` read 1.76x → 0.91x). That's why the self-executing spec
+  spawns a clean `node` child instead of measuring inside Jest — see *Why not measure under Jest*.

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

@@ -0,0 +1,80 @@
+/**
+ * Pure decision predicates for the W-TinyLFU policy.
+ *
+ * No state: weights and frequencies in, verdicts out. This is the policy's "functional core" —
+ * what makes the cache W-TinyLFU rather than a generic cache — extracted so each decision can be
+ * unit-tested directly with plain numbers, without observing element placement.
+ */
+/**
+ * Total weight Main (Trial + Protected) is allowed to hold.
+ * @param {number} maxWeight total cache weight budget
+ * @param {number} windowMaxWeight Window region's weight cap
+ * @returns {number}
+ */
+export function mainCapacity(maxWeight: number, windowMaxWeight: number): number;
+/**
+ * Does Main exceed its budget once `extraWeight` is added? Counts current Trial occupancy.
+ * @param {number} trialWeight
+ * @param {number} protectedWeight
+ * @param {number} extraWeight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function exceedsMainWeight(trialWeight: number, protectedWeight: number, extraWeight: number, mainCap: number): boolean;
+/**
+ * Could `weight` never fit in Main, even with Trial fully evicted? Only Protected's live weight is
+ * the immovable floor (Trial is fully evictable). Distinct from {@link exceedsMainWeight}, which
+ * counts current Trial occupancy.
+ * @param {number} protectedWeight
+ * @param {number} weight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function cannotFitMain(protectedWeight: number, weight: number, mainCap: number): boolean;
+/**
+ * Is `weight` too big to ever fit in Window, even when empty? (ceiling test, ignores occupancy)
+ * @param {number} weight
+ * @param {number} windowMaxWeight
+ * @returns {boolean}
+ */
+export function tooBigForWindow(weight: number, windowMaxWeight: number): boolean;
+/**
+ * Decide where a new element of `weight` goes on admission:
+ *  - REJECT: can never fit Main, even with Trial fully evicted;
+ *  - TRIAL:  fits Main but too big for Window, so goes straight to the admission duel;
+ *  - WINDOW: normal case.
+ * @param {number} weight
+ * @param {number} protectedWeight  live Protected occupancy (the immovable floor)
+ * @param {number} windowMaxWeight  Window's weight cap
+ * @param {number} mainCap          Main's weight budget
+ * @returns {number} one of {@link AdmissionRoute}
+ */
+export function classifyAdmission(weight: number, protectedWeight: number, windowMaxWeight: number, mainCap: number): number;
+/**
+ * Does the admission candidate beat the victim on frequency? Ties favour the incumbent (strict >).
+ * @param {number} candidateFrequency
+ * @param {number} victimFrequency
+ * @returns {boolean}
+ */
+export function winsAdmissionDuel(candidateFrequency: number, victimFrequency: number): boolean;
+/**
+ * Should a Trial element be promoted to Protected? It must be hot enough AND fit Protected — an
+ * element with weight > protectedMaxWeight is a valid Trial resident that stays pinned (never
+ * promotable). So this is the full Trial→Protected transition gate.
+ * @param {number} frequency
+ * @param {number} promotionThreshold
+ * @param {number} weight
+ * @param {number} protectedMaxWeight
+ * @returns {boolean}
+ */
+export function shouldPromoteToProtected(frequency: number, promotionThreshold: number, weight: number, protectedMaxWeight: number): boolean;
+/**
+ * Where a newly-admitted element should be routed.
+ */
+export type AdmissionRoute = number;
+export namespace AdmissionRoute {
+    let REJECT: number;
+    let WINDOW: number;
+    let TRIAL: number;
+}
+//# sourceMappingURL=wtinylfuDecisions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wtinylfuDecisions.d.ts","sourceRoot":"","sources":["../../../../../src/core/cache/wtinylfu/wtinylfuDecisions.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,wCAJW,MAAM,mBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,+CANW,MAAM,mBACN,MAAM,eACN,MAAM,WACN,MAAM,GACJ,OAAO,CAKnB;AAED;;;;;;;;GAQG;AACH,+CALW,MAAM,UACN,MAAM,WACN,MAAM,GACJ,OAAO,CAKnB;AAED;;;;;GAKG;AACH,wCAJW,MAAM,mBACN,MAAM,GACJ,OAAO,CAInB;AAQD;;;;;;;;;;GAUG;AACH,0CANW,MAAM,mBACN,MAAM,mBACN,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;GAKG;AACH,sDAJW,MAAM,mBACN,MAAM,GACJ,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,oDANW,MAAM,sBACN,MAAM,UACN,MAAM,sBACN,MAAM,GACJ,OAAO,CAKnB;;;;6BA5CS,MAAM"}

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

@@ -0,0 +1,102 @@
+/**
+ * Pure decision predicates for the W-TinyLFU policy.
+ *
+ * No state: weights and frequencies in, verdicts out. This is the policy's "functional core" —
+ * what makes the cache W-TinyLFU rather than a generic cache — extracted so each decision can be
+ * unit-tested directly with plain numbers, without observing element placement.
+ */
+
+/**
+ * Total weight Main (Trial + Protected) is allowed to hold.
+ * @param {number} maxWeight total cache weight budget
+ * @param {number} windowMaxWeight Window region's weight cap
+ * @returns {number}
+ */
+export function mainCapacity(maxWeight, windowMaxWeight) {
+    return maxWeight - windowMaxWeight;
+}
+
+/**
+ * Does Main exceed its budget once `extraWeight` is added? Counts current Trial occupancy.
+ * @param {number} trialWeight
+ * @param {number} protectedWeight
+ * @param {number} extraWeight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function exceedsMainWeight(trialWeight, protectedWeight, extraWeight, mainCap) {
+    const projectedMainWeight = trialWeight + protectedWeight + extraWeight
+    return projectedMainWeight > mainCap;
+}
+
+/**
+ * Could `weight` never fit in Main, even with Trial fully evicted? Only Protected's live weight is
+ * the immovable floor (Trial is fully evictable). Distinct from {@link exceedsMainWeight}, which
+ * counts current Trial occupancy.
+ * @param {number} protectedWeight
+ * @param {number} weight
+ * @param {number} mainCap
+ * @returns {boolean}
+ */
+export function cannotFitMain(protectedWeight, weight, mainCap) {
+    const requiredMainWeight = protectedWeight + weight;
+    return requiredMainWeight > mainCap;
+}
+
+/**
+ * Is `weight` too big to ever fit in Window, even when empty? (ceiling test, ignores occupancy)
+ * @param {number} weight
+ * @param {number} windowMaxWeight
+ * @returns {boolean}
+ */
+export function tooBigForWindow(weight, windowMaxWeight) {
+    return weight > windowMaxWeight;
+}
+
+/**
+ * Where a newly-admitted element should be routed.
+ * @enum {number}
+ */
+export const AdmissionRoute = { REJECT: 0, WINDOW: 1, TRIAL: 2 };
+
+/**
+ * Decide where a new element of `weight` goes on admission:
+ *  - REJECT: can never fit Main, even with Trial fully evicted;
+ *  - TRIAL:  fits Main but too big for Window, so goes straight to the admission duel;
+ *  - WINDOW: normal case.
+ * @param {number} weight
+ * @param {number} protectedWeight  live Protected occupancy (the immovable floor)
+ * @param {number} windowMaxWeight  Window's weight cap
+ * @param {number} mainCap          Main's weight budget
+ * @returns {number} one of {@link AdmissionRoute}
+ */
+export function classifyAdmission(weight, protectedWeight, windowMaxWeight, mainCap) {
+    if (cannotFitMain(protectedWeight, weight, mainCap)) return AdmissionRoute.REJECT;
+    if (tooBigForWindow(weight, windowMaxWeight))        return AdmissionRoute.TRIAL;
+    return AdmissionRoute.WINDOW;
+}
+
+/**
+ * Does the admission candidate beat the victim on frequency? Ties favour the incumbent (strict >).
+ * @param {number} candidateFrequency
+ * @param {number} victimFrequency
+ * @returns {boolean}
+ */
+export function winsAdmissionDuel(candidateFrequency, victimFrequency) {
+    return candidateFrequency > victimFrequency;
+}
+
+/**
+ * Should a Trial element be promoted to Protected? It must be hot enough AND fit Protected — an
+ * element with weight > protectedMaxWeight is a valid Trial resident that stays pinned (never
+ * promotable). So this is the full Trial→Protected transition gate.
+ * @param {number} frequency
+ * @param {number} promotionThreshold
+ * @param {number} weight
+ * @param {number} protectedMaxWeight
+ * @returns {boolean}
+ */
+export function shouldPromoteToProtected(frequency, promotionThreshold, weight, protectedMaxWeight) {
+    return (frequency > promotionThreshold)
+        && (weight <= protectedMaxWeight);
+}

package/src/core/collection/RingBuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RingBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/RingBuffer.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IACI;;OAEG;IACH,kBAFW,MAAM,EAoChB;IA7BG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,OAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,MAFU,CAAC,EAAE,CAEc;IAG/B;;;OAGG;IACH,iBAFW,MAAM,QAwBhB;IAED;;;OAGG;IACH,WAFY,CAAC,CAIZ;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,CAAC,CAYb;IAED,cAIC;IAED;;;OAGG;IACH,cAFW,CAAC,QAuBX;IAED;;;OAGG;IACH,SAFa,CAAC,GAAC,SAAS,CAcvB;IAED;;;OAGG;IACH,4BAFW,MAAM,QA8BhB;IAED;;;;;OAKG;IACH,2BAJoB,CAAC,KAAE,OAAO,kBAEjB,CAAC,GAAC,SAAS,CAsBvB;IAED;;;;OAIG;IACH,wBAHoB,CAAC,+BAmBpB;IAED;;;;OAIG;IACH,gBAHW,CAAC,GACC,OAAO,CAKnB;CACJ"}
+{"version":3,"file":"RingBuffer.d.ts","sourceRoot":"","sources":["../../../../src/core/collection/RingBuffer.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IACI;;OAEG;IACH,kBAFW,MAAM,EAoChB;IA7BG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,MAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,OAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,MAFU,CAAC,EAAE,CAEc;IAG/B;;;OAGG;IACH,iBAFW,MAAM,QAwBhB;IAED;;;OAGG;IACH,WAFY,CAAC,CAKZ;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACJ,CAAC,CAYb;IAED,cAIC;IAED;;;OAGG;IACH,cAFW,CAAC,QAuBX;IAED;;;OAGG;IACH,SAFa,CAAC,GAAC,SAAS,CAcvB;IAED;;;OAGG;IACH,4BAFW,MAAM,QA8BhB;IAED;;;;;OAKG;IACH,2BAJoB,CAAC,KAAE,OAAO,kBAEjB,CAAC,GAAC,SAAS,CAsBvB;IAED;;;;OAIG;IACH,wBAHoB,CAAC,+BAmBpB;IAED;;;;OAIG;IACH,gBAHW,CAAC,GACC,OAAO,CAgBnB;CACJ"}

package/src/core/collection/RingBuffer.js

@@ -80,7 +80,8 @@ export class RingBuffer {
      * @return {V}
      */
     getHead() {
-        return this.data[this.head - 1];
+        // delegate so the head-1 index wraps correctly when the write cursor sits at slot 0
+        return this.getFromHead(0);
     }
 
     /**
@@ -242,7 +243,18 @@ export class RingBuffer {
      * @returns {boolean}
      */
     contains(value) {
-        // TODO do a bounds check
-        return this.data.indexOf(value) !== -1;
+        // scan only live slots — a shift()-ed element is still physically present in the backing array
+        const count = this.count;
+        const size = this.size;
+        const tail = this.tail;
+        const data = this.data;
+
+        for (let i = 0; i < count; i++) {
+            if (data[(tail + i) % size] === value) {
+                return true;
+            }
+        }
+
+        return false;
     }
 }

package/src/core/collection/Stack.d.ts

@@ -12,8 +12,8 @@ export class Stack<T> {
      * @readonly
      */
     readonly on: {
-        removed: Signal<any, any, any, any, any, any, any, any>;
-        added: Signal<any, any, any, any, any, any, any, any>;
+        removed: Signal;
+        added: Signal;
     };
     /**
      * @returns {T[]}

package/src/core/collection/array/array_copy.d.ts

@@ -1,7 +1,12 @@
-export declare function array_copy<T>(
-    source: ArrayLike<T>,
-    source_position: number,
-    destination: ArrayLike<T>,
-    destination_position: number,
-    length: number
-): void;
+/**
+ * Copy data from one array to another
+ * Follows Java System.arraycopy interface
+ * @template T
+ * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Int32Array|Float32Array|Float64Array} source The source array
+ * @param {number} source_position Starting position where to copy from inside the source array
+ * @param {T[]|ArrayLike<T>|TypedArray|Uint8ClampedArray|Uint8Array|Uint32Array|Int32Array|Float32Array|Float64Array} destination The destination array
+ * @param {number} destination_position Starting position where to copy to inside the destination array
+ * @param {number} length How many elements should be copied
+ */
+export function array_copy<T>(source: any, source_position: number, destination: any, destination_position: number, length: number): void;
+//# sourceMappingURL=array_copy.d.ts.map

package/src/core/collection/array/computeHashArray.d.ts

@@ -1 +1,9 @@
-export function computeHashArray<T>(array: T[], hash: (T) => number): number
+/**
+ * @template T
+ * @param {T[]} array
+ * @param {function(T):number} elementHashFunction
+ * @param {*} [thisArg]
+ * @returns {number}
+ */
+export function computeHashArray<T>(array: T[], elementHashFunction: (arg0: T) => number, thisArg?: any): number;
+//# sourceMappingURL=computeHashArray.d.ts.map

package/src/core/collection/array/isArrayEqualStrict.d.ts

@@ -1 +1,8 @@
-export function isArrayEqualStrict<T>(a: ArrayLike<T>, b: ArrayLike<T>): boolean
+/**
+ *
+ * @param {Array|Uint8Array|Float32Array} a
+ * @param {Array|Uint8Array|Float32Array} b
+ * @returns {boolean}
+ */
+export function isArrayEqualStrict(a: any[] | Uint8Array | Float32Array, b: any[] | Uint8Array | Float32Array): boolean;
+//# sourceMappingURL=isArrayEqualStrict.d.ts.map

package/src/core/collection/array/isArraysEqualWithComparator.d.ts

@@ -1 +1,10 @@
-export function isArraysEqualWithComparator<T>(a:ArrayLike<T>, b:ArrayLike<T>, equals:(a:T,b:T)=>boolean):boolean
+/**
+ * @template T
+ * @param {T[]} a
+ * @param {T[]} b
+ * @param {function(T,T):boolean} elements_equal
+ * @param {*} [element_equal_context]
+ * @returns {boolean}
+ */
+export function isArraysEqualWithComparator<T>(a: T[], b: T[], elements_equal: (arg0: T, arg1: T) => boolean, element_equal_context?: any): boolean;
+//# sourceMappingURL=isArraysEqualWithComparator.d.ts.map

package/src/core/collection/array/iterator/ArrayIteratorRandom.d.ts

@@ -2,7 +2,9 @@ export class ArrayIteratorRandom extends AbstractArrayIterator<any> {
     constructor();
     __i: number;
     __sequence: any[];
-    __random: () => number;
+    __random: (() => number) | {
+        setCurrentSeed: (arg0: v) => number;
+    };
     /**
      *
      * @param {number} v

package/src/core/collection/array/iterator/ArrayIteratorRandom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ArrayIteratorRandom.d.ts","sourceRoot":"","sources":["../../../../../../src/core/collection/array/iterator/ArrayIteratorRandom.js"],"names":[],"mappings":"AAIA;IACI,cAOC;IAJG,YAAY;IACZ,kBAAoB;IAEpB,uBAA+B;IAGnC;;;OAGG;IACH,WAFW,MAAM,QAIhB;IAED,4BAYC;IAED,wBAgBC;CACJ;sCAnDqC,4BAA4B"}
+{"version":3,"file":"ArrayIteratorRandom.d.ts","sourceRoot":"","sources":["../../../../../../src/core/collection/array/iterator/ArrayIteratorRandom.js"],"names":[],"mappings":"AAIA;IACI,cAOC;IAJG,YAAY;IACZ,kBAAoB;IAEpB;;MAA+B;IAGnC;;;OAGG;IACH,WAFW,MAAM,QAIhB;IAED,4BAYC;IAED,wBAgBC;CACJ;sCAnDqC,4BAA4B"}