#moonlarder

#Install

moon add jhshuai/moonlarder

#Try it

moon run cmd/main --target wasm-gc

#Why

#Usage

let cache : Larder[String, Int] = Larder::new(capacity=100, default_ttl_ms=60_000L)

cache.set("answer", 42, now_ms=0L)
cache.get("answer", now_ms=1_000L) // Some(42)

// Memoize an expensive computation: recomputed only on a miss or expiry.
let value = cache.get_or_insert_with("expensive", now_ms=0L, fn() {
  compute_expensive_thing()
})

cache.set("short-lived", "value", now_ms=0L, ttl_ms=5_000L)

cache.set_many([("a", 1), ("b", 2), ("c", 3)], now_ms=0L)
let found = cache.get_many(["a", "missing", "c"], now_ms=0L)
// found == [("a", 1), ("c", 3)] - only the hits, in the order asked

let by_size : Larder[String, Bytes] = Larder::new(
  capacity=10 * 1024 * 1024, // 10 MiB total, not 10 MiB per entry
  weigher=fn(_key, value) { value.length() },
)

let cache : Larder[String, Int] = Larder::new(capacity=100, policy=Lfu)

let cache : Larder[String, Int] = Larder::new(capacity=100, policy=Arc)

#Frequency estimation

let sketch : FrequencySketch[String] = FrequencySketch::new(capacity=10_000)
sketch.increment("popular-key")
sketch.increment("popular-key")
sketch.estimate("popular-key") // 2 - never lower than the true count,
                                // possibly higher from hash collisions

let cache : Larder[String, Int] = Larder::new(capacity=100, admission_filter=true)

let cache : Larder[String, Int] = Larder::new(capacity=100, policy=WindowTinyLfu)

let snapshot : Json = ToJson::to_json(cache)
let restored : Larder[String, Int] = @json.from_json(snapshot)

let cache : Larder[String, Handle] = Larder::new(
  capacity=1000,
  on_remove=fn(_key, handle, _cause) { handle.close() },
)

#API

• Larder::new(capacity~, default_ttl_ms?, weigher?, policy?, admission_filter?, on_remove?) — create a cache
• Larder::from_array(entries, capacity~, default_ttl_ms?, weigher?, policy?, admission_filter?, on_remove?, now_ms~) — build a cache from an array in one call, as if set had been called for each entry in order
• get(key, now_ms~) — look up a value, refreshing its recency on a hit
• get_many(keys, now_ms~) — look up several keys in one call, returning only the hits, in order
• peek(key, now_ms~) — read a value without affecting recency or stats
• set(key, value, now_ms~, ttl_ms?) — insert or update, evicting least-recently-used entries if the cache is now over capacity
• set_many(entries, now_ms~, ttl_ms?) — insert or update several entries under one ttl in one call
• get_or_insert_with(key, now_ms~, ttl_ms?, compute) — memoize
• try_get_or_insert_with(key, now_ms~, ttl_ms?, compute) — memoize a loader that can fail; the error propagates and nothing is stored
• touch_ttl(key, now_ms~, ttl_ms?) — refresh an entry's expiry in place (sliding expiration) without needing its value
• contains(key, now_ms~) — check presence without affecting recency
• remove(key) / clear() / retain(predicate)
• purge_expired(now_ms~) — proactively sweep expired entries
• keys() / values() / to_array(now_ms~) — inspect current contents
• iter() / iter2() — support for entry in larder { .. } and for key, value in larder { .. } directly
• is_empty() / size() / capacity() / weight() / resize(capacity)
• policy() — the eviction policy this cache was created with
• admission_rejections() — how many newcomers admission_filter has turned away; always 0 when it isn't enabled
• stats() — hit/miss/eviction/expiration counters
• on_remove — notified synchronously whenever an entry leaves, with why (Explicit, Replaced, Expired, or Evicted); see below
• ToJson/FromJson — snapshot to and rehydrate from JSON (see above)

• FrequencySketch::new(capacity~) — create an empty sketch
• increment(key) — record one occurrence of key
• estimate(key) — an approximate count, never below the true count while under the per-counter cap (15)
• clear() — reset every counter to zero

#Testing

• the whole point of the window - a candidate that built up real frequency while still sitting there beating an untouched incumbent it would have lost to immediately under a plain admission_filter.

#Benchmarks

moon bench --target wasm-gc

#Does the Map-based design actually pay for itself?

#Real-world usage

#Notes

• Not thread-safe; use one Larder per thread or add your own synchronization if you need to share one.
• Keys must implement Hash + Eq.
• Expiry is lazy: an expired entry is only removed when it's looked up (get/contains) or via an explicit purge_expired, so a write-heavy, rarely-read workload can hold expired entries until one of those runs.
• A negative ttl_ms/default_ttl_ms is honored, not rejected: the entry is already expired the moment it's looked up. A ttl_ms large enough to overflow Int64 saturates to "practically never expires" rather than wrapping around to a deadline in the past. A weigher returning zero or a negative weight is clamped to at least 1, so it can never silently defeat capacity enforcement.

#License