Add findOrCreateHandle

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":[]}]
+[{"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":[]}]

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"}

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,34 @@ 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.
+
+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 =
+    Elm.Kernel.LamderaWebsocket.createHandle namespace url
+
+
 {-| Errors that might happen when sending data.
 -}
 type SendError