OutMessage

**Note: ** This library is opinionated. The usage of an OutMsg is a technique to extend The Elm Architecture (TEA) to support child-parent communication. The README covers the design.

The OutMsg pattern has two components:

OutMsg, a user-defined type (just like Model or Msg) with the specific purpose of notifying a parent component.
interpretOutMsg, a function that converts OutMsg values into side-effects (commands and changes to the model)

OutMsg values can be captured in the parent's update function, and handled there by interpretOutMsg. The basic pattern can be extended to return multiple OutMsg using List or to optionally return no OutMsg using Maybe.

#Evaluators

evaluate :

(outMsg -> model -> ( model, Cmd msg ))

-> ( model, Cmd msg, outMsg )

-> ( model, Cmd msg )

Turn an OutMsg value into commands and model changes.

The arguments are:

interpretOutMsg, a user-defined function that turns OutMsg values into model changes and effects.
a tuple containing the model (updated with the child component), commands (of the parent's Msg type) and an OutMsg. This package exposes helpers to construct this tuple from the value that a child update function returns.

Example usage:

-- in update : Msg -> Model -> (Model, Cmd Msg)
-- assuming interpretOutMsg : OutMsg -> Model -> (Model, Cmd Msg)
-- ChildComponentModule.update
--       : ChildMsg
--       -> ChildModel -> (ChildModel, Cmd ChildMsg, OutMsg)
ChildComponentMessageWrapper childMsg ->
    ChildComponentModule.update childMsg model.child
        -- update the model with the new child component
        |> OutMessage.mapComponent
            (\newChild -> { model | child = newChild }
        -- convert child cmd to parent cmd
        |> OutMessage.mapCmd ChildComponentMessageWrapper
        -- apply outmsg changes
        |> OutMessage.evaluate interpretOutMsg

evaluateMaybe :

(outMsg -> model -> ( model, Cmd msg ))

-> Cmd msg

-> ( model, Cmd msg, Maybe outMsg )

-> ( model, Cmd msg )

Turn a Maybe OutMsg into effects and model changes.

Has a third argument for a default command that is used when OutMsg is Nothing.

evaluateList :

(outMsg -> model -> ( model, Cmd msg ))

-> ( model, Cmd msg, List outMsg )

-> ( model, Cmd msg )

Turn a List OutMsg into effects and model changes.

Takes care of threading the state. When interpreting an OutMsg changes the model, the updated model will be used for subsequent interpretations of OutMsgs. Cmds are accumulated and batched.

evaluateResult :

(outMsg -> model -> ( model, Cmd msg ))

-> (error -> Cmd msg)

-> ( model, Cmd msg, Result error outMsg )

-> ( model, Cmd msg )

Turn a Result error OutMsg into effects and model changes

Has a third argument for a function that turns errors into a command that is used when OutMsg is Err error.

#Mapping

mapComponent : (childComponent -> a) -> ( childComponent, b, c ) -> ( a, b, c )

Apply a function over the updated child component.

mapCmd :

(childmsg -> parentmsg)

-> ( a, Cmd childmsg, c )

-> ( a, Cmd parentmsg, c )

Apply a function over the Msg from the child.

mapOutMsg : (outMsg -> c) -> ( a, b, outMsg ) -> ( a, b, c )

Apply a function over the child's OutMsg.

#Helpers

addOutMsg : outMsg -> ( model, Cmd msg ) -> ( model, Cmd msg, outMsg )

Add an outmessage to the normal type that update has. Handy to use in a pipe:

( { model | a = 1 }, Cmd.none )
    |> addOutMsg Nothing

toNested : ( a, b, c ) -> ( ( a, b ), c )

Helper to split the OutMsg from the normal type that update has.

The functions fst and snd can now be used, which can be handy.

fromNested : ( ( a, b ), c ) -> ( a, b, c )

Join the component, command and outmessage into a flat tuple.

#Internals

Internal functions that can be used to create custom evaluators.

An evaluator has three basic components:

A state creator, often using OutMessage.wrap.
A state modifier, any function from the State package (see the use of State.traverse in evaluateList).
A state evaluator that runs the state and creates a 'vanilla' elm value.

This package uses the State package for threading the model through a series of updates and accumulating commands.

wrap :

(outmsg -> model -> ( model, Cmd msg ))

-> outmsg

-> State model (Cmd msg)

Embed a function into State

run : Cmd msg -> model -> State model (Cmd msg) -> ( model, Cmd msg )

Evaluate a State model (Cmd msg) given a model, and commands to prepend.

wrap interpretOutMsg myOutMsg
    |> run Cmd.none myModel

Modules

OutMessage

abinayasudhir/outmessage/1.0.0

OutMessage

Modules