Reflex FRP

Reflex functions often operate in a monadic context m a. The specific monad m is determined by your FRP host (e.g., reflex-dom). To help developers understand what capabilities a function requires, the documentation uses specific annotations:

• [ ] (Pure): Operates on Events, Behaviors, or Dynamics without regard to "current time".
• [S] (MonadSample): Requires a monad supporting MonadSample. Used for functions that produce a result "as of now".
• [H] (MonadHold): Requires a monad supporting MonadHold. Since MonadHold depends on MonadSample, any [S] function also runs in an [H] context.
• [B] (PostBuild): Requires PostBuild to fire an event when the network is set up.
• [A] (Adjustable): Requires Adjustable to add or remove pieces of the network via Events.
• [T] (TriggerEvent): Requires TriggerEvent to create new externally-fired Events.
• [P] (PerformEvent): Requires PerformEvent to trigger IO actions via Events.

Reflex provides several functions to transform a Dynamic collection (like a Map or a List) into a collection of dynamically-changing widgets or values. These functions handle the lifecycle of the elements as the underlying collection changes.

• listWithKey: Turns a Dynamic (Map k v) into a Dynamic (Map k a) by applying a constructor function to each key and its corresponding Dynamic v.
• list: Similar to listWithKey, but the constructor function does not receive the key.
• simpleList: A simplified version for Dynamic [v], where elements are processed without keys.
• listViewWithKey: Specialized for widgets that return an Event a. It returns an Event (Map k a).
• selectViewListWithKey_: Creates a set of widgets where one is selected based on a Dynamic k. It returns an Event k representing the current selection.
• listWithKeyShallowDiff: Uses an initial Map and an Event (Map k (Maybe v)) to perform shallow updates rather than full re-renders.

-- Turn a Dynamic key/value map into a set of dynamically-changing widgets.
listWithKey :: Ord k => Dynamic (Map k v) -> (k -> Dynamic v -> m a) -> m (Dynamic (Map k a))

-- Even simpler version where there are no keys and we just use a list.
simpleList :: Dynamic [v] -> (Dynamic v -> m a) -> m (Dynamic [a])

To connect your FRP network to the real world, use the performEvent family of functions. These allow you to execute side-effecting actions in response to events.

• performEvent: Runs side-effecting actions in an Event. The returned Event contains the results of those actions. Requires a PerformEvent t m constraint.
• performEvent_: Runs side-effects but does not return an Event containing results.
• performEventAsync: Used for asynchronous actions. You provide a callback to the action, which the action uses to send its return value back into the network.

-- Run side-effecting actions in Event when it occurs; returned Event contains results.
performEvent :: Event (Performable m a) -> m (Event a)

-- Just run side-effects; no return Event
performEvent_ :: Event (Performable m ()) -> m ()

-- Actions run asynchronously; actions are given a callback to send return values
performEventAsync :: Event ((a -> IO ()) -> Performable m ()) -> m (Event a)

When building complex applications, you may need to create, destroy, or switch between entire sub-networks dynamically.

• runWithReplace: Takes an initial value and an Event of replacement actions. It returns the current value and an Event of the new values.
• networkView: Given a Dynamic of network-creating actions, it creates a network that is recreated whenever the Dynamic updates. This is useful for switching between different UI views or logic sets.
• networkHold: Given an initial network and an Event of new network-creating actions, it returns a Dynamic representing the current network. The network is recreated whenever the Event fires.
• untilReady: Renders a placeholder network (m a) to be shown while a primary network (m b) is being built. It returns the placeholder result and an Event indicating when the primary network is ready.

-- Given a Dynamic of network-creating actions, create a network that is recreated whenever the Dynamic updates.
networkView :: Dynamic (m a) -> m (Event a)

-- Given an initial network and an Event of network-creating actions, create a network that is recreated whenever the Event fires.
networkHold :: m a -> Event (m a) -> m (Dynamic a)

-- Render a placeholder network to be shown while another network is not yet done building
untilReady :: m a -> m b -> m (a, Event b)

Events represent discrete occurrences in time. You can transform them using standard functional patterns or combine them with other Events and Behaviors.

Transformation

• fmap, ffor, <$: Standard mapping functions.
• fmapMaybe, fforMaybe: Map and filter out Nothing values.
• ffilter: Filter events based on a predicate.
• updated: Extract an Event from a Dynamic (fires whenever the Dynamic changes).

Sampling Behaviors and Dynamics

Use these to capture the state of a Behavior or Dynamic at the moment an Event fires:

• gate: Only allows an Event to pass if a Behavior Bool is True.
• tag: Attach the current value of a Behavior to an Event.
• attach: Combine an Event with the current value of a Behavior into a tuple (a, b).
• attachPromptlyDyn: Similar to attach, but uses a Dynamic and uses the most recent value immediately.

Combining Multiple Events

• leftmost: Returns the first event from a list that fires.
• mergeWith: Combines multiple events of the same type using a combining function.
• align: Combines two events into a These a b structure (handling simultaneous firings).
• difference: Returns an event that fires when the first event fires, but only if the second does not.

-- Example: Tagging an event with a behavior value
-- [ ] tag :: Behavior a -> Event b -> Event a

-- Example: Filtering an event
-- [ ] ffilter :: (a -> Bool) -> Event a -> Event a