A monad for succinctly expressing model transitions in the update function.

Effect is a RWS, where the State allows modification to model. It's also a Writer Monad, where the accumulator is a list of scheduled IO actions. Multiple actions can be scheduled using tell from the mtl library and a single asynchronous action can be scheduled using io_.

An Effect represents the results of an update action.

It consists of the updated model and a list of subscriptions. Each Sub is run in a new thread so there is no risk of accidentally blocking the application.

Tip: use the Effect monad in combination with the stateful Miso.Lens operators (all operators ending in "="). The following example assumes the lenses field1, counter and field2 are in scope and that the LambdaCase language extension is enabled:

myComponent = Component
  { update = \case
      MyAction1 -> do
        field1 .= value1
        counter += 1
      MyAction2 -> do
        field2 %= f
        io_ $ do
          consoleLog "Hello"
          consoleLog "World!"
  , ...
  }

Type synonym for constructing subscriptions.

For example usage see Miso.Subscription

The Sink function is used to write to the global event queue.

Function to write to the global event queue for processing by the scheduler.

Type to represent a DOM reference

This is the 'Reader r' in Effect. Accessible via ask. It holds a phantom type for context (the app-global React-style context, which is write-only from within update). It gives access to Component metadata such as the DOMRef the Component was mounted on and the ComponentId associated with it.

ComponentId of the current Component

Smart constructor for ComponentInfo

Represents a scheduled Effect that is executed either synchronously or asynchronously.

All IO is by default asynchronous, use the sync function for synchronous execution. Beware sync can block the render thread for a specific Component.

N.B. During Component unmounting, all effects are evaluated synchronously.

The ContextModify constructor carries a pending mutation to the app-global React-style context. It is emitted by modifyContext / putContext and applied to the global context during the scheduler's commit phase, triggering a re-render of every Component with useContext enabled.

Since: 1.9.0.0

Type to indicate if effects should be handled asynchronously or synchronously.

Smart constructor for an Effect with exactly one action.

Effect smart constructor, flipped

Smart constructor for an Effect with multiple IO actions.

Since: 1.9.0.0

Like batch but actions are discarded

Since: 1.9.0.0

Schedule a single IO action for later execution.

Note that multiple IO action can be scheduled using tell from the mtl library.

Since: 1.9.0.0

Like io but doesn't cause an action to be dispatched to the update function.

This is handy for scheduling IO computations where you don't care about their results or when they complete.

Note: The result of IO a is discarded.

Since: 1.9.0.0

Schedule a single IO action, executed synchronously. For asynchronous execution, see io.

Please use this with caution because it will block the render thread.

Since: 1.9.0.0

Like sync, except discards the result.

Since: 1.9.0.0

Like io but generalized to any instance of Foldable

This is handy for scheduling IO computations that return a Maybe value

Since: 1.9.0.0

Issue a new action to be processed by update.

data Action = HelloWorld
type Model  = Int

update :: Action -> Effect context props Model Action
update = \case
  Click -> issue HelloWorld

Since: 1.9.0.0

withSink allows users to write to the global event queue. This is useful for introducing IO into the system. A synonym for tell, specialized to Effect.

A use-case is scheduling an IO computation which creates a 3rd-party JS widget which has an associated callback. The callback can then call the sink to turn events into actions.

update FetchJSON = withSink $ \sink -> getJSON (sink . ReceivedJSON) (sink . HandleError)

Since: 1.9.0.0

Mutate the app-global React-style context from within update.

The supplied function is scheduled as a ContextModify and folded over the current global context during the scheduler's commit phase. If the context value changes (per its Eq instance), every Component with useContext enabled is re-rendered.

Note that context is write-only inside update; to read it, use the context argument threaded into the view function.

update Toggle = modifyContext (\theme -> if theme == Light then Dark else Light)

Since: 1.13.0.0

Mutate the app-global React-style context using a State computation.

A convenience wrapper around modifyContext that runs the supplied State context action over the current global context (via execState), scheduling the resulting context -> context transformation as a ContextModify. This lets you use put / modify and the lens operators from Miso.Lens to update context, mirroring how model is updated.

update Toggle = modifyContext_ $ theme .= Dark

Since: 1.13.0.0

Replace the app-global React-style context with a new value.

A convenience wrapper around modifyContext. See modifyContext for details of when re-renders are triggered.

Since: 1.13.0.0

Turn a Sub that consumes actions of type a into a Sub that consumes actions of type b using the supplied function of type a -> b.

Helper for Component construction, when you want to ignore the update function temporarily, or permanently.

Since: 1.9.0.0

Performs the given IO action before all IO actions collected by the given effect.

-- delays connecting a websocket by 100000 microseconds
beforeAll (liftIO $ threadDelay 100000) $ websocketConnectJSON OnConnect OnClose OnOpen OnError

Since: 1.9.0.0

Performs the given IO action after all IO actions collected by the given effect.

Example usage:

-- log that running the a websocket Effect completed
afterAll (consoleLog "Done running websocket effect") $ websocketConnectJSON OnConnect OnClose OnOpen OnError

Modifies all IO collected by the given Effect.

All IO expressions collected by Effect can be evaluated either synchronously or asynchronously (the default).

This function can be used to adjoin additional actions to all IO expressions in an Effect. For examples see beforeAll and afterAll.

Lens for accessing the underlying Component DOMRef.

  update = case
    SomeAction -> do
      domRef <- view componentDOMRef
      someAction domRef

Since: 1.9.0.0

Lens for accessing the parents's ComponentId from ComponentInfo.

update = case
  SomeAction -> do
    compParentId <- view componentParentId
    someAction compParentId

Since: 1.9.0.0

Lens for accessing the ComponentId from ComponentInfo.

  update = case
    SomeAction -> do
      compId <- view componentInfoId
      someAction compId

Since: 1.9.0.0

Internal function used to unwrap an Effect

Lens for accessing the underlying Component props.

  update = case
    SomeAction -> do
      props <- view componentInfoProps
      someAction props

Since: 1.9.0.0

Lens for accessing the underlying Component props.

This is a shorter convenience lens that is a synonynm for componentInfoProps. See getProps for usage in the Effect monad.

  update = case
    SomeAction ->
      someAction =<< view props

props retrieval from within the Effect monad.

  update = case
    SomeAction -> do
      props <- getProps
      someAction props

Lens for accessing the underlying Component context.

  update = case
    SomeAction -> do
      ctx <- view componentInfoContext
      someAction ctx

Since: 1.13.0.0

Lens for accessing the underlying Component context.

This is a shorter convenience lens that is a synonynm for componentInfoContext. See getContext for usage in the Effect monad.

  update = case
    SomeAction ->
      someAction =<< view context

Note: this lens is read-only within Effect. It targets the ComponentInfo reader environment, so setting through it (e.g. with set / .=) has no observable effect. To change the global context from update, use modifyContext, putContext, or modifyContext_ (the State-monad variant, which supports lens operators like .=) instead.

Since: 1.13.0.0

Read-only context retrieval from within the Effect monad.

  update = case
    SomeAction -> do
      ctx <- getContext
      someAction ctx

Since: 1.13.0.0