/* * Copyright (c) 2026, OpenSavvy and contributors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package opensavvy.ktmongo.sync.api /** * Streaming-capable iterable cursor to read data from the database. * * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/core/cursors/) */ interface MongoIterable { /** * Returns the first document found by this query, or throws an exception. * * @throws NoSuchElementException If this query returned no results. * @see firstOrNull Return `null` instead of throwing an exception. */ fun first(): Document /** * Returns the first document found by this query, or returns `null`. * * @see first Throw an exception instead of returning `null`. */ fun firstOrNull(): Document? /** * Performs a client-side streaming mapping on the results. */ fun map(transform: (Document) -> Out): MongoIterable /** * Executes [action] for each document returned by this query. * * This method streams all returned documents into the [action] function. * The entire response set is not loaded at once into memory. * * MongoDB cursors are batched: a batch is queried, processed, then another batch is requested, etc. * The batch size can be configured in the operation creating this iterable. * * If the operation contains a sort without an index, MongoDB will load all results * into memory. The driver will still stream the results. * * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ fun forEach(action: (Document) -> Unit) /** * Reads the entirety of this iterable into a [List]. * * Since lists are in-memory, this method loads the entirety of the results into memory. * * @see forEach Execute an action for each result. * @see toSet Store all results in a [Set]. */ fun toList(): List { val list = ArrayList() forEach { list.add(it) } return list } /** * Reads the entirety of this iterable into a [Set]. * * Since sets are in-memory, this method loads the entirety of the results into memory. * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. */ fun toSet(): Set { val set = HashSet() forEach { set.add(it) } return set } /** * This method always throws an exception. * * Streaming a [MongoIterable] into a [Sequence] is not supported, because iterables * must be closed, and sequences cannot detect when iteration finishes. * * If you want to use a [Sequence] data structure for convenience, and the volume of data * is low, use [toList] followed by [asSequence][List.asSequence]. * All data will be loaded in memory at once. * * If streaming is important, either use [forEach], `stream` (Java-only). * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ @Deprecated("Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow", ReplaceWith("this.toList().asSequence()"), level = DeprecationLevel.ERROR) fun asSequence(): Sequence = throw UnsupportedOperationException("Sequences are not supported because they create memory lists. Use lists, streams, or simply forEach instead.") /** * This method always throws an exception. * * Streaming a [MongoIterable] into a [Sequence] is not supported, because iterables * must be closed, and sequences cannot detect when iteration finishes. * * If you want to use a [Sequence] data structure for convenience, and the volume of data * is low, use [toList] followed by [asSequence][List.asSequence]. * All data will be loaded in memory at once. * * If streaming is important, either use [forEach], `stream` (Java-only). * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ @Deprecated("Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow", ReplaceWith("this.toList().asSequence()"), level = DeprecationLevel.ERROR) fun toSequence(): Sequence = throw UnsupportedOperationException("Sequences are not supported because they create memory lists. Use lists, streams, or simply forEach instead.") }