package bonsai

  1. Overview
  2. Docs
package bonsai
Legend:
Library
Module
Module type
Parameter
Class
Class type

Many modules have the same shape, they declare the model, action, and result of the component, and then define apply_action and view over those types.

This is intended to be used with the of_module function.

module Input : sig ... end

A component receives read-only input, either as output from other components or from an external system (e.g. data from a server). The input is frequently dynamic, but may also be constant.

A component's model is a state-machine that the component can read, but also write to. Because both the input and model are readable, it can be hard to decide whether to request some data from the input or the model. It is highly recommended to put just the data that needs mutation in Model.t, and the rest in Input.t.

Components can change their own Model.t by issuing "actions" that perform the state transition. If you think of the state machine as having state-nodes of type Model.t, then the arrows between those nodes would be of type Action.t.

module Result : sig ... end

While UI components stereotypically produce some kind of "view", with Bonsai, components are small and easy enough to compose that Bonsai components frequently produce intermediate results which are then wired into other components.

val apply_action : inject:(Action.t -> Event.t) -> schedule_event:(Event.t -> unit) -> Input.t -> Model.t -> Action.t -> Model.t

When an action is raised by this component (via an Event.t), Bonsai will eventually pass that action back to that component's apply_action function. This function is responsible for looking at the model and the incoming action and producing a new model.

apply_action is a transformation from a model and an action into a new model. During the transformation, the component can also emit more actions via schedule_event or use Async to arrange for schedule_event to be called later.

val compute : inject:(Action.t -> Event.t) -> Input.t -> Model.t -> Result.t

compute is a function from input and model to the component's result. In a component that produces a view, this function could be thought of as the "view computation function".

This function is also given an "inject" function which converts this component's Action.t to a global Event.t which can be given to Bonsai to schedule. Frequently, this Event.t is embedded within the result as a handler for some kind of user input.

val name : string

The name of the component. This is used to identify the component while debugging, and to annotate error messages. If you can't think of a good name, a reasonable fallback is Source_code_position.to_string [%here].