#incr.mbt

#Install

moon add bobzhang/incr

#Interactive example: delivery dispatch

python3 examples/dispatch/build.py
# Open _build/dispatch/index.html in your browser.

#Start with cells and thunks

///|
test "readme incremental total" {
  let engine = @incr.Engine()
  let price = engine.cell(20)
  let quantity = engine.cell(3)
  let total = engine.thunk(() => price.force() * quantity.force())
  assert_eq(total.force(), 60)
  assert_eq(total.force(), 60)
  assert_eq(engine.stats().evaluations, 1)
  quantity.set(4)
  assert_eq(engine.stats().evaluations, 1)
  assert_eq(total.force(), 80)
  assert_eq(engine.stats().evaluations, 2)
}

#Reuse computations by argument or name

///|
test "readme memoization" {
  let engine = @incr.Engine()
  let fib = @incr.Memo::recursive(engine, (memo, n : Int32) => {
    if n < 2 {
      n
    } else {
      memo.call(n - 1) + memo.call(n - 2)
    }
  })
  assert_eq(fib.call(10), 55)
  assert_eq(engine.stats().evaluations, 11)
  let double = @incr.Memo(engine, x => x * 2)
  let name = @incr.name_of_string("answer")
  let answer = double.named(name, 21)
  assert_eq(answer.force(), 42)
  assert_true(answer == double.named(name, 30))
  assert_eq(answer.force(), 60)
}

#Observe just the part you need

///|
test "readme projection" {
  let engine = @incr.Engine()
  let record = engine.cell(("Ada", 20))
  let greeting = engine.thunk(() => "Hello, " + record.force_map(x => x.0))
  assert_eq(greeting.force(), "Hello, Ada")
  record.set(("Ada", 21))
  assert_eq(greeting.force(), "Hello, Ada")
  assert_eq(engine.stats().evaluations, 1)
}

#Collections and inspection

#Computation contract

• A computation uses one engine. Cross-engine observations are rejected.
• Thunk bodies are synchronous, deterministic, and non-raising. Represent expected failures as result values. set is allowed only between computations.
• Store immutable snapshots. Do not mutate an array, map, or mutable record that is already a cached value or memo key. Copy it and write the new value to a cell. Unlike Rust's Clone, MoonBit does not automatically deep-copy stored values.
• Capture changing values as cells. Other captured closure state must remain fixed for the lifetime of a thunk or memo table. Equality and hashing must be consistent. A force_map callback must neither observe nor allocate graph nodes.
• Names must be unique within each typed family and namespace for allocations that need independent identities. Use name_fork or nested namespaces to split them deterministically.
• force_cycle(Some(fallback)) cuts a recursive demand with a supplied value; it is not a fixed-point solver. An unexpected cycle panics. Discard a computation after a panic; panic recovery is not a supported evaluation mechanism.
• Engines retain their graph and memo tables retain their entries. There is no eviction or graph garbage collection API. Use bounded workloads and call engine.dispose() when their lifetime ends. Disposal clears edges, values, closures, and typed caches, and invalidates existing handles. It is especially important on native backends, where reference cycles are not collected. Very deep demand chains and recursive collection transformations are limited by the backend call stack.

#Build and test

moon check --target all --warn-list +unnecessary_annotation
moon test
moon test --target js
moon test --target native
moon run cmd/demo
moon fmt
moon info

#Benchmarks