#incr

#Quick Start

• Input[T] — a value you set directly (a spreadsheet cell you type into)
• Derived[T] — a value computed from other cells (a formula cell); it caches its result and notices which cells it read, automatically

let rt = Runtime()

// Create inputs
let x = rt.input(10, label="x")
let y = rt.input(20, label="y")

// Combine inputs and chain further derived stages
let sum = x.derived2(y, (a, b) => a + b, label="sum")
let doubled = sum.map(v => v * 2, label="doubled")

// Outside the graph, read with `read_or_abort()` or `read()`.
// (`.get()` is only legal inside another derived computation —
// use `Derived(rt, () => ...)` when a stage reads several cells.)
inspect(sum.read_or_abort(), content="30")
inspect(doubled.read_or_abort(), content="60")

// Update an input — downstream derived values recompute on the next read
x.set(5)
inspect(doubled.read_or_abort(), content="50")

Note on the example above: It is nocheck because the snippet omits imports and a test wrapper. The same construction is checked in docs/target_api_examples.mbt.md and exercised end-to-end by tests/quickstart_test.mbt — if you edit the example, update those in lockstep.

#Installation

{
  "import": ["dowdiness/incr"]
}

#How It Works, in Plain Words

1. Writes are cheap. x.set(5) records "something changed" (a counter ticks up) and returns. Nothing recomputes yet.
2. Reads check before they work. When you later read doubled, the runtime walks back through what doubled read last time and asks: did any of it actually change? Untouched branches are skipped without running any of your code.
3. "Same answer" stops the ripple. If a recomputed value comes out equal to its previous value, everything downstream of it is also skipped. (The docs call this backdating — the value's "last changed" timestamp is kept in the past.)
4. Dependencies can change between runs. If a formula reads different cells this time (say, an if took the other branch), the recorded dependencies are simply replaced. Nothing is declared up front.

• Failed computations and cycle errors never corrupt the cache: the last successful result and its recorded dependencies stay authoritative.
• Reads that can fail return Result (read() / get()); a dependency cycle or a disposed cell comes back as an Err you can handle, not a crash. The _or_abort variants abort instead, for when failure is a bug.
• Caching is in-memory and per-process. Nothing persists across runs.

#Beyond Input and Derived

#Which type should I use?

#Learn More

• New to incr? Start with Getting Started, then Core Concepts.
• Looking for a specific pattern? Backdating, durability, keyed queries, batched updates with rollback, cycle-safe reads, and more are covered in the Cookbook.
• Looking up a type or method? See the API Reference.
• Exploring the practical demo? Try the live typed spreadsheet, run the CLI demo for the fixed trace, or build the editable Rabbita Web demo locally.
• Working on incr itself? docs/architecture.md (package map) and docs/design/internals.md (algorithms).

#Background and Theory

• A Derived compute closure is the task; the runtime records the dependencies read by the last successful compute.
• Input::set(...) bumps a revision; it does not eagerly recompute the pull graph.
• A later read verifies the recorded trace on demand: no dependency changed → the closure does not run (green path); a dependency changed → the closure reruns and records a new trace (red path); an equal result on the red path preserves changed_at (backdating, the paper's early cutoff).

#Development

moon check    # Type-check the workspace
moon build    # Build the workspace
moon test     # Run all workspace tests
moon bench    # Run benchmarks (always pass --release for representative numbers)

#Supported targets

#License