Bonsai

Bonsai is a UI library for building performant, reactive web applications in OCaml. It is inspired by Elm and is designed around the concept of components implemented as purely functional state machines.

Key characteristics include:

• Incrementality: Values (including the view) are only recomputed when necessary, preventing unnecessary work.
• Composable State: Unlike frameworks that tie state to a UI component hierarchy, Bonsai allows you to compose state and incrementality primitives independently. This makes it easier to manage state lifecycles, such as embedding stateful components within tabbed interfaces without manual state hoisting.
• Full-stack OCaml: Enables sharing types and business logic between the backend and frontend.

module Dice = struct
  let faces =
    [ "⚀"; "⚁"; "⚂"; "⚃"; "⚄"; "⚅" ]
  ;;

  let component (graph @ local) =
    (* Components are implemented as purely functional state machines. *)
    let face, set_face = Bonsai.state (List.hd_exn faces) graph in
    (* Components are incrementally rendered, only when the relevant parts of the state change. *)
    let%arr face and set_face in
    {%html|
      <div>
        You rolled a #{face}
        <button
          style=""
          on_click=%{fun _ ->
            let index = Random.int (List.length faces) in
            set_face (List.nth_exn faces index)}
        >
          Roll the dice
        </button>
      </div>
    |}
  ";;

Because js_of_ocaml (JSOO) lacks tail call optimization, deeply recursive functions can cause stack overflow errors. Trampoline is a monad designed to mitigate this by managing the execution flow to avoid deep recursion on the call stack.

To use Trampoline, you must:

1. Use the let%bind.Trampoline syntax (provided by the library's effect handlers/monadic syntax) for recursive calls.
2. Wrap the final result of your computation in Trampoline.return.
3. Execute the computation using Trampoline.run.

(* Standard recursive function that might stack overflow in JSOO *)
let some_function x =
  let rec f x =
    let a = f (x - 1) in
    let b = f (x - 2) in
    some_reduce a b
  in
  f x

(* Re-written version using Trampoline to prevent stack overflow *)
let some_function_safe x =
  let rec f x =
    let%bind.Trampoline a = f (x - 1) in
    let%bind.Trampoline b = f (x - 2) in
    Trampoline.return (some_reduce a b)
  in
  Trampoline.run (f x)

By default, Bonsai's switch function traverses all branches in a match%sub when constructing the graph. For large or complex graphs, this can be expensive. To prevent unnecessary computation of branches that might never be used, use the [%lazy] modifier.

To use [%lazy], you must have a graph variable in scope. If your graph variable is not named graph, you must specify its name inside the [%lazy ...] block.

Example with default graph name:

let f (either_value : (_, _) Either.t Value.t) page1 page2 graph =
  let open Bonsai.Let_syntax in
  match%sub [%lazy] either_value with
  | First (a, b) -> page1 a b
  | Second x -> page2 x

Example with custom graph name my_graph_7:

let f (either_value : (_, _) Either.t Value.t) page1 page2 my_graph_7 =
  let open Bonsai.Let_syntax in
  match%sub [%lazy my_graph_7] either_value with
  | First (a, b) -> page1 a b
  | Second x -> page2 x