From 57fe3abef047c239dd7c13fdace8bf7f45136445 Mon Sep 17 00:00:00 2001 From: Mario Rogic Date: Sun, 8 Oct 2023 16:30:08 +0100 Subject: [PATCH 1/2] Add findOrCreateHandle --- docs.json | 2 +- endpoint.json | 2 +- src/Websocket.elm | 25 ++++++++++++++++++++++--- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/docs.json b/docs.json index e3edfbe..b40bf04 100644 --- a/docs.json +++ b/docs.json @@ -1 +1 @@ -[{"name":"Websocket","comment":"\n\n@docs Connection, SendError, close, createHandle, listen, sendString\n\n","unions":[{"name":"Connection","comment":" A websocket connection\n","args":[],"cases":[]},{"name":"SendError","comment":" Errors that might happen when sending data.\n","args":[],"cases":[["ConnectionClosed",[]]]}],"aliases":[],"values":[{"name":"close","comment":" Close the websocket connection\n","type":"Websocket.Connection -> Task.Task Basics.Never ()"},{"name":"createHandle","comment":" Create a websocket handle that you can then open by calling listen or sendString.\n","type":"String.String -> Task.Task Basics.Never Websocket.Connection"},{"name":"listen","comment":" Listen for incoming messages through a websocket connection. You'll also get notified if the connection closes.\n","type":"Websocket.Connection -> (String.String -> msg) -> msg -> Platform.Sub.Sub msg"},{"name":"sendString","comment":" Send a string\n","type":"Websocket.Connection -> String.String -> Task.Task Websocket.SendError ()"}],"binops":[]}] \ No newline at end of file +[{"name":"Websocket","comment":"\n\n@docs Connection, SendError, close, createHandle, findOrCreateHandle, listen, sendString, CloseEventCode\n\n","unions":[{"name":"CloseEventCode","comment":" Here are some possible reasons that your websocket connection closed.\n","args":[],"cases":[["NormalClosure",[]],["GoingAway",[]],["ProtocolError",[]],["UnsupportedData",[]],["NoStatusReceived",[]],["AbnormalClosure",[]],["InvalidFramePayloadData",[]],["PolicyViolation",[]],["MessageTooBig",[]],["MissingExtension",[]],["InternalError",[]],["ServiceRestart",[]],["TryAgainLater",[]],["BadGateway",[]],["TlsHandshake",[]],["UnknownCode",["Basics.Int"]]]},{"name":"Connection","comment":" A websocket connection\n","args":[],"cases":[]},{"name":"SendError","comment":" Errors that might happen when sending data.\n","args":[],"cases":[["ConnectionClosed",[]]]}],"aliases":[],"values":[{"name":"close","comment":" Close the websocket connection\n","type":"Websocket.Connection -> Task.Task Basics.Never ()"},{"name":"createHandle","comment":" Create a websocket handle that you can then open by calling `listen` or `sendString`.\n\nEach handle is unique, so you can have multiple open connections at once to the same URL by using `createHandle` multiple times.\n\nIt is your responsibility to hold onto the `Connection` value, if you lose it you will not be able to explicitly close the connection.\n\nIf you know you will only need a discrete number of connections, you can use `findOrCreateHandle`.\n\n","type":"String.String -> Task.Task Basics.Never Websocket.Connection"},{"name":"findOrCreateHandle","comment":" Find or create a websocket handle with a given namespace that you can then open by calling `listen` or `sendString`.\n\nEach handle is unique by its namespace, so calling `findOrCreateHandle` multiple times with the same namespace and URL will return the same `Connection` handle.\n\nIf you want an automatic unique namespace per `Connection`, use `createHandle` instead.\n\n","type":"String.String -> String.String -> Task.Task Basics.Never Websocket.Connection"},{"name":"listen","comment":" Listen for incoming messages through a websocket connection. You'll also get notified if the connection closes.\n","type":"Websocket.Connection -> (String.String -> msg) -> ({ code : Websocket.CloseEventCode, reason : String.String } -> msg) -> Platform.Sub.Sub msg"},{"name":"sendString","comment":" Send a string\n","type":"Websocket.Connection -> String.String -> Task.Task Websocket.SendError ()"}],"binops":[]}] \ No newline at end of file diff --git a/endpoint.json b/endpoint.json index 21da40b..56326f2 100644 --- a/endpoint.json +++ b/endpoint.json @@ -1 +1 @@ -{"url":"https://static.lamdera.com/r/lamdera/websocket/pack.zip","hash":"f1b5836ae33508e05356c7b8c408459e91e120bf"} +{"url":"https://static.lamdera.com/r/lamdera/websocket/pack.zip","hash":"60a78fa49c619dc009c9f946a070fda9d5a357f1"} diff --git a/src/Websocket.elm b/src/Websocket.elm index b0651ed..c83c8a9 100644 --- a/src/Websocket.elm +++ b/src/Websocket.elm @@ -1,8 +1,8 @@ -effect module Websocket where { command = MyCmd, subscription = MySub } exposing (Connection, SendError(..), close, createHandle, listen, sendString, CloseEventCode(..)) +effect module Websocket where { command = MyCmd, subscription = MySub } exposing (Connection, SendError(..), close, createHandle, findOrCreateHandle, listen, sendString, CloseEventCode(..)) {-| -@docs Connection, SendError, close, createHandle, listen, sendString, CloseEventCode +@docs Connection, SendError, close, createHandle, findOrCreateHandle, listen, sendString, CloseEventCode -} @@ -18,13 +18,32 @@ type Connection = Connection String String -{-| Create a websocket handle that you can then open by calling listen or sendString. +{-| Create a websocket handle that you can then open by calling `listen` or `sendString`. + +Each handle is unique, so you can have multiple open connections at once to the same URL by using `createHandle` multiple times. + +It is your responsibility to hold onto the `Connection` value, if you lose it you will not be able to explicitly close the connection. + +If you know you will only need a discrete number of connections, you can use `findOrCreateHandle`. + -} createHandle : String -> Task Never Connection createHandle url = Elm.Kernel.LamderaWebsocket.createHandle () url +{-| Find or create a websocket handle with a given namespace that you can then open by calling `listen` or `sendString`. + +Each handle is unique by its namespace, so calling `findOrCreateHandle` multiple times with the same namespace and URL will return the same `Connection` handle. + +If you want an automatic unique namespace per `Connection`, use `createHandle` instead. + +-} +findOrCreateHandle : String -> String -> Task Never Connection +findOrCreateHandle namespace url = + Elm.Kernel.LamderaWebsocket.createHandle namespace url + + {-| Errors that might happen when sending data. -} type SendError From 1b33ee5a7652337dbcf13c71ca9ca45739f9a3a1 Mon Sep 17 00:00:00 2001 From: Mario Rogic Date: Wed, 1 May 2024 15:15:51 +1000 Subject: [PATCH 2/2] Refine findOrCreateHandle docs --- src/Websocket.elm | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/Websocket.elm b/src/Websocket.elm index c83c8a9..0a39732 100644 --- a/src/Websocket.elm +++ b/src/Websocket.elm @@ -38,6 +38,8 @@ Each handle is unique by its namespace, so calling `findOrCreateHandle` multiple If you want an automatic unique namespace per `Connection`, use `createHandle` instead. +This is useful in the scenario where you need a specific connection, but don't really care about keeping track of it in your application, so you can use `findOrCreateHandle` to retrieve the `Connection` value again anytime you need to send something. + -} findOrCreateHandle : String -> String -> Task Never Connection findOrCreateHandle namespace url =