A small, typed WebSocket client for Elm with a compact, auditable JavaScript runtime. It supports multiple connections, lifecycle events, and text, binary, or JSON messages.

Installation

Install the Elm package:

elm install mbr/elm-wss

Elm packages cannot declare ports. Make Main.elm a port module, or use another application-owned port module, then add these declarations:

import WebsocketSimple exposing (CommandPort, EventPort)


port wsCmd : CommandPort msg


port wsMsg : EventPort msg

The JavaScript runtime expects the exact port names wsCmd and wsMsg.

Copy js/elm-websockets.js into the browser assets. Load the runtime and compiled Elm application, initialize Elm, and then initialize the runtime:

<script src="elm-websockets.js"></script>
<script src="app.js"></script>
<script>
var app = Elm.Main.init({
  node: document.getElementById("elm")
});
ElmWebsockets.initApp(app);
</script>

The JavaScript initialization is a no-op when the application does not contain the command port, so it can remain in the bootstrap while WebSocket code is temporarily unused.

Ports

Pass the application-owned ports described by these aliases to commands and subscriptions.

Basic usage

Subscribe to events before opening a connection, and wait for Connected before transmitting:

import WebsocketPorts as Ports
import WebsocketSimple as WebSocket


type Msg
    = WebSocketEvent WebSocket.RawMsg


init : () -> ( List String, Cmd Msg )
init _ =
    ( [], WebSocket.open Ports.wsCmd "ws://127.0.0.1:8765" )


update : Msg -> List String -> ( List String, Cmd Msg )
update msg model =
    case msg of
        WebSocketEvent (WebSocket.Connected _) ->
            ( model, WebSocket.send Ports.wsCmd (WebSocket.Transmit "hello") )


        WebSocketEvent (WebSocket.Text value) ->
            ( value :: model, WebSocket.close Ports.wsCmd )


        WebSocketEvent (WebSocket.Binary _) ->
            ( model, WebSocket.close Ports.wsCmd )


        WebSocketEvent (WebSocket.Disconnected _) ->
            ( model, Cmd.none )


        WebSocketEvent (WebSocket.TransportError error) ->
            ( WebSocket.errorToString error :: model, Cmd.none )


subscriptions : List String -> Sub Msg
subscriptions _ =
    Sub.map WebSocketEvent (WebSocket.subscribe Ports.wsMsg)

Commands

send and its convenience functions use an implicit "default" handle. Use sendWithHandle for multiple connections.

Handles

Each connection is identified by an opaque handle encoded as a string at the port boundary.

chat : WebSocket.Handle
chat =
    WebSocket.handle "chat"


alerts : WebSocket.Handle
alerts =
    WebSocket.handle "alerts"


openConnections : Cmd msg
openConnections =
    Cmd.batch
        [ WebSocket.sendWithHandle Ports.wsCmd chat (WebSocket.Open chatUrl [])
        , WebSocket.sendWithHandle Ports.wsCmd alerts (WebSocket.Open alertsUrl [])
        ]

Events

subscribe discards handle information. Use subscribeWithHandle to distinguish events from multiple connections.

type Msg
    = WebSocketEvent ( WebSocket.Handle, WebSocket.RawMsg )


subscriptions : model -> Sub Msg
subscriptions _ =
    Sub.map WebSocketEvent (WebSocket.subscribeWithHandle Ports.wsMsg)

JSON

Regular subscriptions expose incoming text and binary frames as Text String and Binary Bytes. Typed subscriptions decode text frames while keeping transport errors separate from payload decoding failures. A binary frame received through a typed JSON subscription produces an UnsupportedData transport failure.

import Json.Decode as Decode


type alias Payload =
    { message : String }


payloadDecoder : Decode.Decoder Payload
payloadDecoder =
    Decode.map Payload (Decode.field "message" Decode.string)


type Msg
    = WebSocketMessage (WebSocket.Msg Payload)


subscriptions : model -> Sub Msg
subscriptions _ =
    WebSocket.subscribeMsg Ports.wsMsg payloadDecoder WebSocketMessage