#comemoon

#Why comemoon?

#Features

• Fine-grained invalidation — only actually-read tracked data invalidates a cache entry
• Mutable tracked calls (TrackedMut) — side effects recorded and replayed on cache hit, with downgrade / reborrow / track_mut views
• Trait tracking — #comemo.track on a trait generates a generic surface (WorldTracked[T] with fn[T : World] bounds)
• Multi-parameter memoization — memoize2 … memoize6 for up to 6 tracked parameters
• Validation accelerator — per-instance call→return-hash map, O(1) revalidation
• Age-based eviction — evict(max_age) with age reset on hit
• Recursion — recursive memoized functions share the same per-function cache
• No proc macros — #comemo.track is expanded by a build-time generator (gen/gen.py) via MoonBit's official rule / dev_build hooks; generated code is committed, so downstream users never run it

#Installation

moon add starAndHonor/comemoon

#Quick start

#comemotrack
pub struct Files {
  map : Map[String, String]
}

///|
pub fn Files::read(self : Files, path : String) -> String {
  self.map.get(path).unwrap_or("")
}

///|
pub fn Files::write(self : Files, path : String, text : String) -> Unit {
  self.map[path] = text
}

fn eval(script : String, files : FilesTracked) -> Int {
  let cache : Cache[FilesCall, Int] = Cache::new()
  memoize(cache, input, true, fn() {
    // the computation; reads through `files` are tracked
  })
}

#Demo

moon run cmd/main

#API overview

#How it works

memoized fn call
      │
      ▼
per-fn Cache (CallTree)      key = murmur3-128(receiver + plain args)
      │
      ▼
CallTree lookup: walk trie; at each inner node replay the recorded call on the
live tracked value; continue only if the replayed return-hash == edge label
      │
      ├─ leaf → HIT:  replay recorded mutable calls (side effects),
      │               clone output, reset age
      └─ miss → attach a Constraint sink to tracked args, run fn,
                insert (immutable calls → trie path, mutable calls → entry)

#Differences from Rust comemo

• No proc macros — instead of #[memoize] / #[track], you annotate types and traits with #comemo.track and a build-time generator emits the boilerplate.
• Generic trait tracking — tracked traits produce a generic surface (WorldTracked[T]) instead of dyn Track trait objects, so tracked APIs stay statically typed.
• Single-threaded — no locks or cross-thread sharing; one cache belongs to one thread.

#Testing

moon test                    # wasm
moon test --target native    # native

#Roadmap

• Multi-target codegen polish (native performance tuning)
• Extended arity beyond 6 tracked parameters
• Benchmark suite against the Rust reference (speed + memory)
• More examples: incremental build tool, reactive data pipeline

#Contributing

#License

#Acknowledgements

• comemo — the original implementation and behavioral contract
• typst — the project comemo was built for
• MoonBit — the language and toolchain