feat: add defer and flowFromSuspend

api/FlowExt.api

@@ -30,6 +30,10 @@ public final class com/hoc081098/flowext/ConcatKt {
 	public static final fun startWith (Lkotlinx/coroutines/flow/Flow;Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
 }
 
+public final class com/hoc081098/flowext/DeferKt {
+	public static final fun defer (Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
+}
+
 public abstract interface class com/hoc081098/flowext/DelayStrategy {
 	public abstract fun nextDelay-3nIYWDw (Ljava/lang/Throwable;J)J
 }
@@ -97,6 +101,10 @@ public final class com/hoc081098/flowext/FlatMapFirstKt {
 	public static final fun flattenFirst (Lkotlinx/coroutines/flow/Flow;)Lkotlinx/coroutines/flow/Flow;
 }
 
+public final class com/hoc081098/flowext/FlowFromSuspendKt {
+	public static final fun flowFromSuspend (Lkotlin/jvm/functions/Function1;)Lkotlinx/coroutines/flow/Flow;
+}
+
 public final class com/hoc081098/flowext/IntervalKt {
 	public static final fun interval (JJ)Lkotlinx/coroutines/flow/Flow;
 	public static final fun interval-QTBD994 (JJ)Lkotlinx/coroutines/flow/Flow;

build.gradle.kts

@@ -10,7 +10,7 @@ plugins {
   id("com.diffplug.spotless") version "6.6.1"
   id("maven-publish")
   id("com.vanniktech.maven.publish") version "0.19.0"
-  id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.9.0"
+  id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.10.0"
   id("org.jetbrains.dokka") version "1.6.21"
   id("org.jetbrains.kotlinx.kover") version "0.5.1"
 }

src/commonMain/kotlin/com/hoc081098/flowext/defer.kt

@@ -0,0 +1,38 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2021-2022 Petrus Nguyễn Thái Học
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.hoc081098.flowext
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.FlowCollector
+import kotlinx.coroutines.flow.emitAll
+import kotlinx.coroutines.flow.flow
+
+/**
+ * Creates a [Flow] that, on collection, calls a [Flow] factory to make a [Flow] for each new [FlowCollector].
+ *
+ * In some circumstances, waiting until the last minute (that is, until collection time)
+ * to generate the [Flow] can ensure that collectors receive the freshest data.
+ */
+public fun <T> defer(flowFactory: suspend () -> Flow<T>): Flow<T> = flow { emitAll(flowFactory()) }

src/commonMain/kotlin/com/hoc081098/flowext/flowFromSuspend.kt

@@ -0,0 +1,40 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2021-2022 Petrus Nguyễn Thái Học
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.hoc081098.flowext
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flow
+
+/**
+ * Creates a _cold_ flow that produces a single value from the given [function].
+ *
+ * Example of usage:
+ *
+ * ```
+ * suspend fun remoteCall(): R = ...
+ * fun remoteCallFlow(): Flow<R> = flowFromSuspend(::remoteCall)
+ * ```
+ */
+public fun <T> flowFromSuspend(function: suspend () -> T): Flow<T> = flow { emit(function()) }

src/commonTest/kotlin/com/hoc081098/flowext/DeferTest.kt

@@ -0,0 +1,70 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2021-2022 Petrus Nguyễn Thái Học
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.hoc081098.flowext
+
+import com.hoc081098.flowext.utils.BaseTest
+import com.hoc081098.flowext.utils.TestException
+import com.hoc081098.flowext.utils.test
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.flow
+import kotlinx.coroutines.flow.flowOf
+import kotlin.test.Test
+
+@ExperimentalCoroutinesApi
+class DeferTest : BaseTest() {
+  @Test
+  fun deferredEmitsValues() = runTest {
+    var count = 0L
+    val flow = defer {
+      delay(count)
+      flowOf(count)
+    }
+
+    flow.test(listOf(Event.Value(0L), Event.Complete))
+
+    ++count
+    flow.test(listOf(Event.Value(1L), Event.Complete))
+
+    ++count
+    flow.test(listOf(Event.Value(2L), Event.Complete))
+  }
+
+  @Test
+  fun deferFailureUpStream() = runTest {
+    val testException = TestException()
+
+    defer<Int> {
+      flow { throw testException }
+    }.test(listOf(Event.Error(testException)))
+  }
+
+  @Test
+  fun deferFactoryThrows() = runTest {
+    val testException = TestException()
+
+    defer<Int> { throw testException }.test(listOf(Event.Error(testException)))
+  }
+}

src/commonTest/kotlin/com/hoc081098/flowext/FlowFromSuspendTest.kt

@@ -0,0 +1,59 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2021-2022 Petrus Nguyễn Thái Học
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.hoc081098.flowext
+
+import com.hoc081098.flowext.utils.BaseTest
+import com.hoc081098.flowext.utils.TestException
+import com.hoc081098.flowext.utils.test
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.delay
+import kotlin.test.Test
+
+@ExperimentalCoroutinesApi
+class FlowFromSuspendTest : BaseTest() {
+  @Test
+  fun flowFromSuspendEmitsValues() = runTest {
+    var count = 0L
+    val flow = flowFromSuspend {
+      delay(count)
+      count
+    }
+
+    flow.test(listOf(Event.Value(0L), Event.Complete))
+
+    ++count
+    flow.test(listOf(Event.Value(1L), Event.Complete))
+
+    ++count
+    flow.test(listOf(Event.Value(2L), Event.Complete))
+  }
+
+  @Test
+  fun deferFactoryThrows() = runTest {
+    val testException = TestException()
+
+    flowFromSuspend<Int> { throw testException }.test(listOf(Event.Error(testException)))
+  }
+}