(DOCSP-29167): Kotlin Flow docs (#49)

# Pull Request Info

Kotlin Flow docs

[PR Reviewing
Guidelines](https://github.com/mongodb/docs-java/blob/master/REVIEWING.md)

JIRA - https://jira.mongodb.org/browse/DOCSP-29167
Staging -
https://docs-mongodbcom-staging.corp.mongodb.com/kotlin/docsworker-xlarge/DOCSP-29167/fundamentals/crud/read-operations/flow

## Self-Review Checklist

- [ ] Is this free of any warnings or errors in the RST?
- [ ] Did you run a spell-check?
- [ ] Did you run a grammar-check?
- [ ] Are all the links working?

---------

Co-authored-by: cbullinger <[email protected]>

Author: mongodben

examples/src/test/kotlin/FlowTest.kt

@@ -0,0 +1,120 @@
+
+
+import com.mongodb.ExplainVerbosity
+import com.mongodb.kotlin.client.coroutine.MongoClient
+import config.getConfig
+import kotlinx.coroutines.flow.*
+import kotlinx.coroutines.runBlocking
+import org.bson.Document
+import org.junit.jupiter.api.AfterAll
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.BeforeAll
+import org.junit.jupiter.api.TestInstance
+import java.util.*
+import kotlin.test.*
+
+
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+internal class FlowTest {
+
+    data class PaintOrder(
+        val id: Int,
+        val color: String,
+        val qty: Int
+    )
+    companion object {
+        val config = getConfig()
+        val client = MongoClient.create(config.connectionUri)
+        val database = client.getDatabase("paint_store")
+        val collection = database.getCollection<PaintOrder>("paint_order")
+
+        @BeforeAll
+        @JvmStatic
+        fun beforeAll() {
+            runBlocking {
+                collection.insertMany(listOf(
+                    PaintOrder(1, "red", 5),
+                    PaintOrder(2, "purple", 8),
+                    PaintOrder(3, "yellow", 0),
+                    PaintOrder(4, "green", 6),
+                    PaintOrder(5, "pink", 0)
+                ))
+            }
+        }
+
+        @AfterAll
+        @JvmStatic
+        fun afterAll() {
+            runBlocking {
+                collection.drop()
+                client.close()
+            }
+        }
+    }
+
+    @Test
+    fun firstOrNullTest() = runBlocking {
+        // :snippet-start: firstOrNull
+        val resultsFlow = collection.find()
+        val firstResultOrNull = resultsFlow.firstOrNull()
+        // :snippet-end:
+        assertNotNull(firstResultOrNull)
+    }
+    @Test
+    fun firstTest() = runBlocking {
+        var isReached = false
+        // :snippet-start: first
+        try {
+            val resultsFlow = collection.find()
+            val firstResult = resultsFlow.first()
+            isReached = true // :remove:
+        } catch (e: NoSuchElementException) {
+            println("No results found")
+        }
+        // :snippet-end:
+        assert(isReached)
+    }
+
+    @Test
+    fun countTest() = runBlocking {
+        // :snippet-start: count
+        val resultsFlow = collection.find()
+        val count = resultsFlow.count()
+        // :snippet-end:
+        assertEquals(5, count)
+    }
+
+    @Test
+    fun toListTest() = runBlocking {
+        // :snippet-start: toList
+        val resultsFlow = collection.find()
+        val results = resultsFlow.toList()
+        // :snippet-end:
+        assertEquals(5, results.size)
+    }
+
+    @Test
+    fun iterateTest() = runBlocking {
+        // :snippet-start: iterate
+        val resultsFlow = collection.find()
+        resultsFlow.collect { println(it) }
+        // :snippet-end:
+        assertEquals(5, resultsFlow.count())
+    }
+
+    @Test
+    fun explainTest() = runBlocking {
+        // :snippet-start: explain
+        val explanation = collection.find().explain(ExplainVerbosity.EXECUTION_STATS)
+        val jsonSummary = explanation.getEmbedded(
+            listOf("queryPlanner", "winningPlan"),
+            Document::class.java
+        ).toJson()
+        println(jsonSummary)
+        // :snippet-end:
+        val expected = """{"stage": "COLLSCAN", "direction": "forward"}
+        """.trimIndent()
+        assertEquals(expected, jsonSummary)
+    }
+}
+

examples/src/test/kotlin/TimeSeriesTest.kt

@@ -5,7 +5,7 @@ import com.mongodb.client.model.Filters.*
 import com.mongodb.client.model.Projections.*
 import com.mongodb.client.model.TimeSeriesOptions
 import com.mongodb.kotlin.client.coroutine.MongoClient
-import io.github.cdimascio.dotenv.dotenv
+import config.getConfig
 import kotlinx.coroutines.flow.toList
 import kotlinx.coroutines.runBlocking
 import org.bson.json.JsonWriterSettings
@@ -20,8 +20,8 @@ import kotlin.test.*
 internal class TimeSeriesTest {
 
     companion object {
-        val dotenv = dotenv()
-        val mongoClient = MongoClient.create(dotenv["MONGODB_CONNECTION_URI"])
+        val config = getConfig()
+        val mongoClient = MongoClient.create(config.connectionUri)
 
         @AfterAll
         @JvmStatic

source/examples/generated/FlowTest.snippet.count.kt

@@ -0,0 +1,2 @@
+val resultsFlow = collection.find()
+val count = resultsFlow.count()

source/examples/generated/FlowTest.snippet.explain.kt

@@ -0,0 +1,6 @@
+val explanation = collection.find().explain(ExplainVerbosity.EXECUTION_STATS)
+val jsonSummary = explanation.getEmbedded(
+    listOf("queryPlanner", "winningPlan"),
+    Document::class.java
+).toJson()
+println(jsonSummary)

source/examples/generated/FlowTest.snippet.first.kt

@@ -0,0 +1,6 @@
+try {
+    val resultsFlow = collection.find()
+    val firstResult = resultsFlow.first()
+} catch (e: NoSuchElementException) {
+    println("No results found")
+}

source/examples/generated/FlowTest.snippet.firstOrNull.kt

@@ -0,0 +1,2 @@
+val resultsFlow = collection.find()
+val firstResultOrNull = resultsFlow.firstOrNull()

source/examples/generated/FlowTest.snippet.iterate.kt

@@ -0,0 +1,2 @@
+val resultsFlow = collection.find()
+resultsFlow.collect { println(it) }

source/examples/generated/FlowTest.snippet.toList.kt

@@ -0,0 +1,2 @@
+val resultsFlow = collection.find()
+val results = resultsFlow.toList()

source/fundamentals/crud/read-operations.txt

@@ -5,6 +5,7 @@ Read Operations
 .. default-domain:: mongodb
 
 - :doc:`/fundamentals/crud/read-operations/retrieve`
+- :doc:`/fundamentals/crud/read-operations/flow`
 - :doc:`/fundamentals/crud/read-operations/change-streams`
 - :doc:`/fundamentals/crud/read-operations/sort`
 - :doc:`/fundamentals/crud/read-operations/skip`
@@ -13,20 +14,15 @@ Read Operations
 - :doc:`/fundamentals/crud/read-operations/geo`
 - :doc:`/fundamentals/crud/read-operations/text`
 
-.. TODO:(DOCSP-29167) add back when refactor cursor page to flow page
-.. - :doc:`/fundamentals/crud/read-operations/cursor`
-
 .. toctree::
    :caption: Read Operations
 
    /fundamentals/crud/read-operations/retrieve
+   /fundamentals/crud/read-operations/flow
    /fundamentals/crud/read-operations/change-streams
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
    /fundamentals/crud/read-operations/limit
    /fundamentals/crud/read-operations/project
    /fundamentals/crud/read-operations/geo
    /fundamentals/crud/read-operations/text
-
-.. TODO:(DOCSP-29167) add back when refactor cursor page to flow page
-.. /fundamentals/crud/read-operations/cursor