Improve behavior for realtime channel creation and improve docs

Realtime/src/commonMain/kotlin/io/github/jan/supabase/realtime/Realtime.kt

@@ -54,7 +54,7 @@ sealed interface Realtime : MainPlugin<Realtime.Config>, CustomSerializationPlug
     val status: StateFlow<Status>
 
     /**
-     * A map of all active the subscriptions
+     * A list of all active the subscriptions
      */
     val subscriptions: Map<String, RealtimeChannel>
 
@@ -103,6 +103,17 @@ sealed interface Realtime : MainPlugin<Realtime.Config>, CustomSerializationPlug
      */
     suspend fun setAuth(token: String? = null)
 
+    /**
+     * Creates a new [RealtimeChannel] and adds it to the [subscriptions]
+     *
+     * - This method does not subscribe to the channel. You have to call [RealtimeChannel.subscribe] to do so.
+     * - If the channel already exists, it will be returned
+     *
+     * @param channelId The id of the channel
+     * @param builder The builder for the channel
+     */
+    fun channel(channelId: String, builder: RealtimeChannelBuilder): RealtimeChannel
+
     /**
      * @property websocketConfig Custom configuration for the Ktor Websocket Client. This only applies if [Realtime.Config.websocketFactory] is null.
      * @property secure Whether to use wss or ws. Defaults to [SupabaseClient.useHTTPS] when null
@@ -187,11 +198,15 @@ sealed interface Realtime : MainPlugin<Realtime.Config>, CustomSerializationPlug
 }
 
 /**
- * Creates a new [RealtimeChannel]
+ * Creates a new [RealtimeChannel] and adds it to the [Realtime.subscriptions]
+ *
+ * - This method does not subscribe to the channel. You have to call [RealtimeChannel.subscribe] to do so.
+ * - If the channel already exists, it will be returned
+ *
+ * @param channelId The id of the channel
+ * @param builder The builder for the channel
  */
-inline fun Realtime.channel(channelId: String, builder: RealtimeChannelBuilder.() -> Unit = {}): RealtimeChannel {
-    return RealtimeChannelBuilder("realtime:$channelId", this as RealtimeImpl).apply(builder).build()
-}
+inline fun Realtime.channel(channelId: String, builder: RealtimeChannelBuilder.() -> Unit = {}): RealtimeChannel = channel(channelId, RealtimeChannelBuilder("realtime:$channelId", this as RealtimeImpl).apply(builder))
 
 /**
  * Supabase Realtime is a way to listen to changes in the PostgreSQL database via websockets

Realtime/src/commonMain/kotlin/io/github/jan/supabase/realtime/RealtimeImpl.kt

@@ -162,6 +162,13 @@ import kotlin.io.encoding.ExperimentalEncodingApi
         _status.value = Realtime.Status.DISCONNECTED
     }
 
+    override fun channel(channelId: String, builder: RealtimeChannelBuilder): RealtimeChannel {
+        if(subscriptions.containsKey(channelId)) return subscriptions[channelId]!!
+        val channel = builder.build()
+        _subscriptions[channelId] = channel
+        return channel
+    }
+
     private suspend fun onMessage(message: RealtimeMessage) {
         Realtime.logger.d { "Received message $message" }
         val channel = subscriptions[message.topic] as? RealtimeChannelImpl

Realtime/src/commonTest/kotlin/RealtimeTest.kt

@@ -1,6 +1,7 @@
 import io.github.jan.supabase.realtime.Realtime
 import io.github.jan.supabase.realtime.RealtimeImpl
 import io.github.jan.supabase.realtime.RealtimeMessage
+import io.github.jan.supabase.realtime.channel
 import io.github.jan.supabase.realtime.realtime
 import io.ktor.util.encodeBase64
 import kotlinx.coroutines.test.runTest
@@ -31,6 +32,22 @@ class RealtimeTest {
         }
     }
 
+    @Test
+    fun testExistingChannelShouldBeReturned() {
+        runTest {
+            createTestClient(
+                wsHandler = { _, _ ->
+                    //Does not matter for this test
+                },
+                supabaseHandler = {
+                    val channel = it.realtime.channel("channelId")
+                    val channel2 = it.realtime.channel("channelId")
+                    assertEquals(channel, channel2)
+                }
+            )
+        }
+    }
+
     @Test
     fun testSendingRealtimeMessages() {
         val expectedMessage = RealtimeMessage(