Merge pull request #51 from cashapp/jw/flow/2021-11-10

Re-add flow factory

Author: JakeWharton

README.md

@@ -1,6 +1,6 @@
 # Molecule
 
-Build a `StateFlow` stream using Jetpack Compose[^1].
+Build a `StateFlow` or `Flow` stream using Jetpack Compose[^1].
 
 ```kotlin
 fun CoroutineScope.launchCounter(): StateFlow<Int> = launchMolecule {
@@ -108,7 +108,7 @@ This model-producing composable function can be run with `launchMolecule`.
 ```kotlin
 val userFlow = db.users()
 val balanceFlow = db.balances()
-val models = scope.launchMolecule {
+val models: StateFlow<ProfileModel> = scope.launchMolecule {
   ProfilePresenter(userFlow, balanceFlow)
 }
 ```
@@ -126,6 +126,40 @@ fun Profile(models: StateFlow<ProfileModel>) {
 }
 ```
 
+For more information see [the `launchMolecule` documentation](https://cashapp.github.io/molecule/docs/latest/molecule-runtime/molecule-runtime/app.cash.molecule/launch-molecule.html).
+
+### Flow
+
+In addition to `StateFlow`s, Molecule can create regular `Flow`s.
+The flow-returning function does not require a `CoroutineScope` as it will be inherited from the collector.
+
+Here is the presenter example updated to use a regular `Flow`:
+```kotlin
+val userFlow = db.users()
+val balanceFlow = db.balances()
+val models: Flow<ProfileModel> = moleculeFlow {
+  ProfilePresenter(userFlow, balanceFlow)
+}
+```
+
+And the counter example:
+```kotlin
+fun counter(): Flow<Int> = moleculeFlow {
+  val count by remember { mutableStateOf(0) }
+
+  LaunchedEffect(Unit) {
+    while (true) {
+      delay(1_000)
+      count++
+    }
+  }
+
+  count
+}
+```
+
+For more information see [the `moleculeFlow` documentation](https://cashapp.github.io/molecule/docs/latest/molecule-runtime/molecule-runtime/app.cash.molecule/molecule-flow.html).
+
 ## Usage
 
 Add the buildscript dependency and apply the plugin to every module which wants to call `launchMolecule` or define `@Composable` functions for use with Molecule.
@@ -168,15 +202,16 @@ apply plugin: 'app.cash.molecule'
 
 ### Frame Clock
 
-The entrypoint to the library is [the `launchMolecule` function](https://cashapp.github.io/molecule/docs/latest/molecule-runtime/molecule-runtime/app.cash.molecule/launch-molecule.html) which is an extension on `CoroutineScope`.
-That scope must contain a `MonotonicFrameClock` key which is used to determine when recomposition occurs and a new value is produced.
+Molecule requires a `MonotonicFrameClock` key in your `CoroutineScope`.
+This applies to [the `launchMolecule` extension's](https://cashapp.github.io/molecule/docs/latest/molecule-runtime/molecule-runtime/app.cash.molecule/launch-molecule.html) receiver and the scope in which you collect [the `moleculeFlow` function]()-returned flow.
+The clock is used to determine when recomposition occurs and a new value is produced.
 
 On Android, [`AndroidUiDispatcher.Main`](https://cashapp.github.io/molecule/docs/latest/molecule-runtime/molecule-runtime/app.cash.molecule/-android-ui-dispatcher/-companion/-main.html) can be used for running your composables on the main thread with recomposition synchronized to the frame rate.
 For any other rate or to recompose on a background thread, create a [`BroadcastFrameClock`](https://developer.android.com/reference/kotlin/androidx/compose/runtime/BroadcastFrameClock) and a timer to invoke its `sendFrame` function at your desired rate.
 
 ### Testing
 
-While the created `StateFlow` can be tested normally, the use of the frame clock to control recomposition makes it harder than it should be.
+While the created `StateFlow`s and `Flow`s can be tested normally, the use of the frame clock to control recomposition makes it harder than it should be.
 The 'molecule-testing' dependency provides a `testMolecule` function which simplifies your test code by managing the threading, coroutine scope, and frame clock for you.
 
 ```kotlin

molecule/molecule-runtime/build.gradle

@@ -1,4 +1,5 @@
 import org.jetbrains.kotlin.gradle.plugin.KotlinPluginKt
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 apply plugin: 'com.android.library'
 apply plugin: 'org.jetbrains.kotlin.android'
@@ -43,6 +44,12 @@ android {
   }
 }
 
+tasks.withType(KotlinCompile).configureEach {
+  kotlinOptions {
+    freeCompilerArgs += '-Xopt-in=kotlin.RequiresOptIn'
+  }
+}
+
 spotless {
   kotlin {
     targetExclude(

molecule/molecule-runtime/src/main/java/app/cash/molecule/molecule.kt

@@ -22,11 +22,26 @@ import androidx.compose.runtime.Recomposer
 import androidx.compose.runtime.snapshots.Snapshot
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.CoroutineStart.UNDISPATCHED
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.channelFlow
 import kotlinx.coroutines.job
 import kotlinx.coroutines.launch
 
+@OptIn(ExperimentalCoroutinesApi::class) // Marked as stable in kotlinx.coroutines 1.6.
+fun <T> moleculeFlow(body: @Composable () -> T): Flow<T> {
+  return channelFlow {
+    launchMolecule(
+      emitter = {
+        trySend(it).getOrThrow()
+      },
+      body = body,
+    )
+  }
+}
+
 fun <T> CoroutineScope.launchMolecule(
   body: @Composable () -> T,
 ): StateFlow<T> {