API for purging all entries about store

[DanielAsher]

I ran into this requirement today. I couldn't figure out whether there was any way to iterate over all keys in a store.

[ychescale9]

@digitalbuddha is this something we want to support? I can send a PR if it is 😃

New Store API might look like this:

interface Store<Key : Any, Output : Any> {

    /**
     * Return a flow for the given key
     * @param request - see [StoreRequest] for configurations
     */
    fun stream(request: StoreRequest<Key>): Flow<StoreResponse<Output>>

    /**
     * Purge a particular entry from memory and disk cache.
     * Persistent storage will only be cleared if a delete function was passed to
     * [StoreBuilder.persister] or [StoreBuilder.nonFlowingPersister] when creating the [Store].
     */
    suspend fun clear(key: Key)

    /**
     * Purge all entries from memory and disk cache.
     * Persistent storage will only be cleared if a deleteAll function was passed to
     * [StoreBuilder.persister] or [StoreBuilder.nonFlowingPersister] when creating the [Store].
     */
    suspend fun clearAll()
}

New persister APIs for deleting disk cache:

    /**
     * Connects a ([kotlinx.coroutines.flow.Flow]) source of truth that is accessed via [reader], [writer] and [delete].
     *
     * For maximal flexibility, [writer]'s record type ([Output]] and [reader]'s record type
     * ([NewOutput]) are not identical. This allows us to read one type of objects from network and
     * transform them to another type when placing them in local storage.
     *
     * A source of truth is usually backed by local storage. It's purpose is to eliminate the need
     * for waiting on network update before local modifications are available (via [Store.stream]).
     *
     * @param reader reads records from the source of truth
     * @param writer writes records **coming in from the fetcher (network)** to the source of truth.
     * Writing local user updates to the source of truth via [Store] is currently not supported.
     * @param delete deletes records in the source of truth for the give key
     * @param deleteAll deletes all records in the source of truth
     *
     */
    fun <NewOutput : Any> persister(
        reader: (Key) -> Flow<NewOutput?>,
        writer: suspend (Key, Output) -> Unit,
        delete: (suspend (Key) -> Unit)? = null,
        deleteAll: (suspend () -> Unit)? = null
    ): StoreBuilder<Key, NewOutput>

    /**
     * Connects a (non-[Flow]) source of truth that is accessible via [reader], [writer],
     * [delete], and [deleteAll].
     *
     * @see persister
     */
    fun <NewOutput : Any> nonFlowingPersister(
        reader: suspend (Key) -> NewOutput?,
        writer: suspend (Key, Output) -> Unit,
        delete: (suspend (Key) -> Unit)? = null,
        deleteAll: (suspend () -> Unit)? = null
    ): StoreBuilder<Key, NewOutput>

[digitalbuddha]

Off the top of my head I can't think of any reason not to have this. Let's give it a go and create a @experimental annotation allowing consumers to know that this is less hardened than other apis.

[ychescale9]

Cool. Will give it a go next week.