lamdera/program-test/3.0.0

NOTE: the latest version is 4.0.0

A Lamdera package. It is not on package.elm-lang.org: the Lamdera compiler provides it, from static.lamdera.com, so lamdera install works and elm install does not.

Effect.Subscription

Note: Elm has managed effects, meaning that things like HTTP requests or writing to disk are all treated as data in Elm. When this data is given to the Elm runtime system, it can do some “query optimization” before actually performing the effect. Perhaps unexpectedly, this managed effects idea is the heart of why Elm is so nice for testing, reuse, reproducibility, etc.

Elm has two kinds of managed effects: commands and subscriptions.

Subscriptions

type alias Subscription restriction msg =
Subscription restriction msg

A subscription is a way of telling Elm, “Hey, let me know if anything interesting happens over there!” So if you want to listen for messages on a web socket, you would tell Elm to create a subscription. If you want to get clock ticks, you would tell Elm to subscribe to that. The cool thing here is that this means Elm manages all the details of subscriptions instead of you. So if a web socket goes down, you do not need to manually reconnect with an exponential backoff strategy, Elm does this all for you behind the scenes!

Every Sub specifies (1) which effects you need access to and (2) the type of messages that will come back into your application.

Note: Do not worry if this seems confusing at first! As with every Elm user ever, subscriptions will make more sense as you work through the Elm Architecture Tutorial and see how they fit into a real application!

none : Subscription restriction msg

Tell the runtime that there are no subscriptions.

List (Subscription restriction msg)
-> Subscription restriction msg

When you need to subscribe to multiple things, you can create a batch of subscriptions.

Note: Sub.none and Sub.batch [ Sub.none, Sub.none ] and Sub.batch [] all do the same thing.

String
-> ((Value -> msg) -> Sub msg)
-> (Value -> msg)
-> Subscription FrontendOnly msg

This function listens for data from JS land. Below is an example of how to use it.

import Subscription exposing (Subscription)
import Command exposing (FrontendOnly)
import Json.Decode


port scrollEventPort : (Json.Decode.value -> msg) -> Sub msg


copyToClipboard : (Json.Decode.value -> msg) -> Subscription FrontendOnly msg
copyToClipboard msg =
    Subscription.fromJs "scrollEventPort" scrollEventPort msg
String
-> ((Bytes -> msg) -> Sub msg)
-> (Bytes -> msg)
-> Subscription FrontendOnly msg

Same as fromJs but for ports that receive Bytes instead of JSON.

import Bytes exposing (Bytes)
import Command exposing (FrontendOnly)
import Subscription exposing (Subscription)


port bytesEventPort : (Bytes -> msg) -> Sub msg


bytesEvent : (Bytes -> msg) -> Subscription FrontendOnly msg
bytesEvent msg =
    Subscription.fromJsBytes "bytesEventPort" bytesEventPort msg

Fancy Stuff

map : (a -> b) -> Subscription restriction a -> Subscription restriction b

Transform the messages produced by a subscription. Very similar to Html.map.

This is very rarely useful in well-structured Elm code, so definitely read the section on structure in the guide before reaching for this!