Add the SharedFlow.asFlow operator (#4541)

See its documentation for the explanation and rationale.

Fixes #4530

Author: g000sha256

CONTRIBUTING.md

@@ -47,7 +47,7 @@ so do familiarize yourself with the following guidelines.
     PRs that add new API without a corresponding issue with positive feedback about the proposed implementation are
     unlikely to be approved or reviewed.
   * All new APIs must come with documentation and tests.
-  * All new APIs are initially released with the `@ExperimentalCoroutineApi` annotation and graduate later.
+  * All new APIs are initially released with the `@ExperimentalCoroutinesApi` annotation and graduate later.
   * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 
     It will not pass the tests otherwise.
   * If you plan large API additions, then please start by submitting an issue with the proposed API design

kotlinx-coroutines-core/api/kotlinx-coroutines-core.api

@@ -1012,6 +1012,7 @@ public final class kotlinx/coroutines/flow/FlowKt {
 	public static final fun asFlow (Lkotlin/ranges/IntRange;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun asFlow (Lkotlin/ranges/LongRange;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun asFlow (Lkotlin/sequences/Sequence;)Lkotlinx/coroutines/flow/Flow;
+	public static final fun asFlow (Lkotlinx/coroutines/flow/SharedFlow;)Lkotlinx/coroutines/flow/Flow;
 	public static final fun asFlow ([I)Lkotlinx/coroutines/flow/Flow;
 	public static final fun asFlow ([J)Lkotlinx/coroutines/flow/Flow;
 	public static final fun asFlow ([Ljava/lang/Object;)Lkotlinx/coroutines/flow/Flow;

kotlinx-coroutines-core/api/kotlinx-coroutines-core.klib.api

@@ -1003,6 +1003,7 @@ final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/Flow<kotlinx.coroutines.flo
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/Flow<kotlinx.coroutines.flow/Flow<#A>>).kotlinx.coroutines.flow/merge(): kotlinx.coroutines.flow/Flow<#A> // kotlinx.coroutines.flow/merge|merge@kotlinx.coroutines.flow.Flow<kotlinx.coroutines.flow.Flow<0:0>>(){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/MutableSharedFlow<#A>).kotlinx.coroutines.flow/asSharedFlow(): kotlinx.coroutines.flow/SharedFlow<#A> // kotlinx.coroutines.flow/asSharedFlow|asSharedFlow@kotlinx.coroutines.flow.MutableSharedFlow<0:0>(){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/MutableStateFlow<#A>).kotlinx.coroutines.flow/asStateFlow(): kotlinx.coroutines.flow/StateFlow<#A> // kotlinx.coroutines.flow/asStateFlow|asStateFlow@kotlinx.coroutines.flow.MutableStateFlow<0:0>(){0§<kotlin.Any?>}[0]
+final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/SharedFlow<#A>).kotlinx.coroutines.flow/asFlow(): kotlinx.coroutines.flow/Flow<#A> // kotlinx.coroutines.flow/asFlow|asFlow@kotlinx.coroutines.flow.SharedFlow<0:0>(){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/SharedFlow<#A>).kotlinx.coroutines.flow/cancellable(): kotlinx.coroutines.flow/Flow<#A> // kotlinx.coroutines.flow/cancellable|cancellable@kotlinx.coroutines.flow.SharedFlow<0:0>(){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/SharedFlow<#A>).kotlinx.coroutines.flow/flowOn(kotlin.coroutines/CoroutineContext): kotlinx.coroutines.flow/Flow<#A> // kotlinx.coroutines.flow/flowOn|flowOn@kotlinx.coroutines.flow.SharedFlow<0:0>(kotlin.coroutines.CoroutineContext){0§<kotlin.Any?>}[0]
 final fun <#A: kotlin/Any?> (kotlinx.coroutines.flow/SharedFlow<#A>).kotlinx.coroutines.flow/onSubscription(kotlin.coroutines/SuspendFunction1<kotlinx.coroutines.flow/FlowCollector<#A>, kotlin/Unit>): kotlinx.coroutines.flow/SharedFlow<#A> // kotlinx.coroutines.flow/onSubscription|onSubscription@kotlinx.coroutines.flow.SharedFlow<0:0>(kotlin.coroutines.SuspendFunction1<kotlinx.coroutines.flow.FlowCollector<0:0>,kotlin.Unit>){0§<kotlin.Any?>}[0]

kotlinx-coroutines-core/common/src/flow/operators/Share.kt

@@ -353,6 +353,34 @@ private fun <T> CoroutineScope.launchSharingDeferred(
     }
 }
 
+// -------------------------------- asFlow --------------------------------
+
+/**
+ * Represents this shared flow and its subtypes as a plain flow,
+ * hiding its hot flow characteristics.
+ *
+ * Unlike simple upcasting, the returned flow prevents casting back to the original
+ * hot flow type, ensuring that implementation details remain encapsulated.
+ *
+ * Example:
+ * ```
+ * class Repository {
+ *     private val _updates = MutableStateFlow("initial")
+ *
+ *     // Exposes Flow interface without leaking MutableStateFlow implementation
+ *     val updates: Flow<String> = _updates.asFlow()
+ * }
+ *
+ * // Usage
+ * val flow = repository.updates
+ * val mutableStateFlow = flow as? MutableStateFlow // null - cast prevented
+ * val stateFlow = flow as? StateFlow // null - cast prevented
+ * ```
+ */
+@ExperimentalCoroutinesApi
+public fun <T> SharedFlow<T>.asFlow(): Flow<T> =
+    transform { value -> emit(value) }
+
 // -------------------------------- asSharedFlow/asStateFlow --------------------------------
 
 /**

kotlinx-coroutines-core/common/test/flow/operators/AsFlowTest.kt

@@ -0,0 +1,34 @@
+@file:Suppress("PackageDirectoryMismatch")
+
+package kotlinx.coroutines.flow
+
+import kotlinx.coroutines.testing.*
+import kotlin.test.*
+
+class AsFlowTest : TestBase() {
+    @Test
+    fun testAsFlow() = runTest {
+        val mutableSharedFlow = MutableSharedFlow<Int>(replay = 3)
+        mutableSharedFlow.emit(value = 1)
+        mutableSharedFlow.emit(value = 2)
+        mutableSharedFlow.emit(value = 3)
+
+        val flow = mutableSharedFlow.asFlow()
+
+        assertEquals(
+            expected = listOf(1, 2, 3),
+            actual = flow
+                .take(count = 3)
+                .toList(),
+        )
+    }
+
+    @Test
+    fun testAsFlowIsNotSharedFlow() {
+        val mutableSharedFlow = MutableSharedFlow<Int>()
+
+        val flow = mutableSharedFlow.asFlow()
+
+        assertIsNot<SharedFlow<Int>>(flow)
+    }
+}