the-sett / elm-serverless / Serverless

Use httpApi to define a Program that responds to HTTP requests. Take a look at the demos for usage examples.

Table of Contents

Defining a Program

Use httpApi to define a headless Elm program.

httpApi : HttpApi config model route msg -> Program config model route msg

Create a program from the given HTTP api.


type alias HttpApi config model route msg =
{ configDecoder : Json.Decode.Decoder config
, initialModel : model
, parseRoute : Url -> Maybe route
, endpoint : Conn config model route msg -> ( Conn config model route msg
, Platform.Cmd.Cmd msg )
, update : msg -> Conn config model route msg -> ( Conn config model route msg
, Platform.Cmd.Cmd msg )
, requestPort : RequestPort (Msg msg)
, responsePort : ResponsePort (Msg msg)
, interopPorts : List (InteropResponsePort (Msg msg)) 
}

Program for an HTTP API.

A Serverless.Program is parameterized by your 5 custom types

You must provide the following:

Notices that update and endpoint operate on Conn config model route msg and not just on model.


type alias Program config model route msg =
Platform.Program Flags (Model config model route msg) (Msg msg)

Serverless program type.

This maps to a headless elm Platform.Program.

Port Types

Since a library cannot expose ports, your application must define two ports with the following signatures. See the Hello World Demo for a usage example.


type alias IO =
( String, Json.Encode.Value )

Describes input and output events over ports as a connection id paired with a data value.


type alias RequestPort msg =
(IO -> msg) -> Platform.Sub.Sub msg

Type of port through which the request is received. Set your request port to this type.

port requestPort : RequestPort msg


type alias ResponsePort msg =
IO -> Platform.Cmd.Cmd msg

Type of port through which the request is sent. Set your response port to this type.

port responsePort : ResponsePort msg

Initialization Helpers

Various aspects of Program may not be needed. These functions are provided as a convenient way to opt-out.

noConfig : Json.Decode.Decoder ()

Opt-out of configuration decoding.

main : Serverless.Program () model route msg
main =
    Serverless.httpApi
        { configDecoder = noConfig

        -- ...
        }

noRoutes : Url -> Maybe ()

Opt-out of route parsing.

main : Serverless.Program config model () msg
main =
    Serverless.httpApi
        { parseRoute = noRoutes

        -- ...
        }

noSideEffects : () -> Conn config model route msg -> ( Conn config model route msg, Platform.Cmd.Cmd () )

Opt-out of side-effects.

main : Serverless.Program config model route ()
main =
    Serverless.httpApi
        { update = noSideEffects

        -- ...
        }

noPorts : List (InteropResponsePort (Msg msg))

Opt-out of interop ports.

main : Serverless.Program config model route ()
main =
    Serverless.httpApi
        { ports = noPorts

        -- ...
        }

Interop ports and helpers.


type alias InteropRequestPort a msg =
( String
, Basics.Int
, a ) -> Platform.Cmd.Cmd ms
)

The type of all outgoing interop ports.


type alias InteropResponsePort msg =
(( String
, Basics.Int
, Json.Encode.Value ) -> msg) -> Platform.Sub.Sub ms
)

The type of all incoming interop ports.

interop : InteropRequestPort a msg -> a -> (Json.Encode.Value -> msg) -> Conn config model route msg -> ( Conn config model route msg, Platform.Cmd.Cmd msg )

Interop helper that invokes a port that follows the InteropRequestPort model. This helper function automatically passes the connection id to the port with the data. The connection id is needed if the port generates a response, in order to send the response to the correct connection.

Note that it is possible to invoke any port, this is just a helper function for a default way of doing it.