Migrating from Elmish

Keep your Elmish init and update, and move views to Ranvier one at a time.

Mvu holds the model in a signal. Each view reads the parts it needs through selectors: memos that trigger their readers only when the selected value changes. The rest of the application can keep its Elmish loop.

Setup

Mvu ships in its own package, Ranvier.Elmish, which depends on Ranvier:

dotnet add package Ranvier.Elmish --prerelease

A model and its update

Create an app with Mvu.create init update. Read a field with app.Select, and send messages with app.Dispatch.

open Ranvier
open Ranvier.Elmish

type Model = { Count: int; Name: string; Address: Address }
and Address = { City: string; Zip: string }

type Msg =
    | Increment
    | Rename of string
    | Move of string

let init = { Count = 0; Name = "Ada"; Address = { City = "Bergen"; Zip = "5003" } }

let update msg model =
    match msg with
    | Increment -> { model with Count = model.Count + 1 }
    | Rename name -> { model with Name = name }
    | Move city -> { model with Model.Address.City = city }

let graph = new Graph ()

graph.Run (fun () ->
    let app = Mvu.create init update
    let count = app.Select _.Count
    createEffect (fun () -> printfn "count = %d" count.Value)

    app.Dispatch Increment      // count = 1
    app.Dispatch (Rename "Grace") // the count effect stays asleep
)

This map isolates selector behaviour: incrementing changes the count, while renaming changes the model but leaves the count effect alone.

Dispatch msg applies update msg model and writes the resulting model to the signal.

• app.Model tracks the whole model. An effect reading it runs on every model change, like an Elmish view.
• app.Select f tracks the selected value. The selector recomputes on model writes while observed, but triggers its readers only when its result changes.

Commands

Use Mvu.withCmd when init and update return a model and a command list, as with Elmish's Program.mkProgram:

let update msg model =
    match msg with
    | Load -> { model with Loading = true }, [ fun dispatch -> fetch (fun items -> dispatch (Loaded items)) ]
    | Loaded items -> { model with Loading = false; Items = items }, []

let app = Mvu.withCmd (initial, [ fun dispatch -> dispatch Load ]) update

Each command receives Dispatch and runs in list order after the accompanying model write. Initial commands run before withCmd returns.

Dispatch and threads

Under the default affinity, Dispatch runs inline on the graph's thread. Calls from other threads are queued and applied on that thread, through Graph.Dispatch.

Selectors and their cost

Each model write recomputes every observed selector directly over the model. Unobserved selectors do not run. A selector compares its result; it does not diff a view.

Nest selectors to reduce this work. A memo over another selector runs only when that selector's result changes:

let address = app.Select _.Address
let city = createMemo (fun _ -> address.Value.City)

An adoption path

1. Keep the whole-model view. Keep init and update, replace Program.mkProgram with Mvu.withCmd, and run the existing view from an effect reading app.Model. Pass it app.Dispatch.
2. Migrate one view. Read app.Select memos in that view's effects instead of app.Model.
3. Repeat. Move the next view, nesting selectors when it displays part of a sub-model.

Owners instead of hooks

Selectors and effects belong to the scope active when they are created. Create a view inside createRoot or an owning memo to dispose its nodes, including selectors, with that scope.