Meet Store

Purpose of the Fetcher

Data Retrieval: The Fetcher abstracts the logic of fetching data from remote sources, allowing the Store to request data without needing to know the details of how and where the data is obtained.
Error Handling: It provides a consistent way to handle errors that may occur during data retrieval.
Multiple Responses: The Fetcher supports both single and multiple responses per request, accommodating various network protocols like HTTP and WebSockets.
Fallback Mechanisms: It allows specifying fallback Fetchers to use alternative data sources if the primary fetch fails.

APIs

Fetcher

Fetcher has the following structure:

interface Fetcher<Key : Any, Network : Any> {
    val name: String?
    val fallback: Fetcher<Key, Network>?
    operator fun invoke(key: Key): Flow<FetcherResult<Network>>
}

Key

Any

required

The type representing the key used to identify the data to fetch. For example, if fetching a list of posts, this could be an Int representing the post ID.

Network

Any

required

The type representing the data fetched from the remote source. For example, if fetching a list of posts, this could be List<Post> representing the list of posts.

name

String?

An optional unique name for the Fetcher, useful when differentiating between multiple fetchers, particularly when using fallbacks.

fallback

Fetcher<Key, Network>?

An optional Fetcher to be used if the parent Fetcher fails.

invoke(key: Key)

Flow<FetcherResult<Network>>

A function that takes a key and returns a Flow<FetcherResult<Network>>, representing the asynchronous stream of fetched data or errors.

FetcherResult

When the Fetcher retrieves data, it wraps the result in a FetcherResult, which can represent either a successful data retrieval or an error.

sealed class FetcherResult<out Network : Any>

FetcherResult.Data

Represents a successful fetch.

sealed class FetcherResult<out Network : Any> {
    data class Data<Network : Any>(val value: Network, val origin: String? = null) : FetcherResult<Network>()
}

value

Network

required

The fetched data.

origin

String?

An optional string to identify the source of the data.

FetcherResult.Error

Represents an error that occurred during fetching.

sealed class FetcherResult<out Network : Any> {
    data class Data<Network : Any>(val value: Network, val origin: String? = null) : FetcherResult<Network>()

    sealed class Error : FetcherResult<Nothing>()
}

FetcherResult.Error.Exception

Used to represent an exception that occurred.

sealed class FetcherResult<out Network : Any> {
    data class Data<Network : Any>(val value: Network, val origin: String? = null) : FetcherResult<Network>()

    sealed class Error : FetcherResult<Nothing>() {
        data class Exception(val error: Throwable) : Error()
    }
}

error

Throwable

required

The exception that occurred.

FetcherResult.Error.Message

Used to represent an error that occurred without an exception being thrown.

sealed class FetcherResult<out Network : Any> {
    data class Data<Network : Any>(val value: Network, val origin: String? = null) : FetcherResult<Network>()

    sealed class Error : FetcherResult<Nothing>() {
        data class Exception(val error: Throwable) : Error()

        data class Message(val message: String) : Error()
    }
}

message

String

required

The error message.

FetcherResult.Error.Custom

Used to represent a custom error. This is useful when the network returns an error object that is not an exception. For example, a union type returned from a gRPC call.

sealed class FetcherResult<out Network : Any> {
    data class Data<Network : Any>(val value: Network, val origin: String? = null) : FetcherResult<Network>()

    sealed class Error : FetcherResult<Nothing>() {
        data class Exception(val error: Throwable) : Error()

        data class Message(val message: String) : Error()

        data class Custom<E : Any>(val error: E) : Error()
    }
}

Any

required

The type representing the custom error. For example, if fetching a list of posts, this could be PostNetworkError.

error

required

The custom error.

Data Flow

Data RequestApplication code requests data from the Store.

Extension for Making a Cached Data Request:

suspend fun <Key : Any, Output : Any> Store<Key, Output>.get(key: Key) =
    stream(StoreReadRequest.cached(key, refresh = false))
        .filterNot { it is StoreReadResponse.Loading || it is StoreReadResponse.NoNewData }
        .first()
        .requireData()

Extension for Making a Fresh Data Request:

suspend fun <Key : Any, Output : Any> Store<Key, Output>.fresh(key: Key) =
  stream(StoreReadRequest.fresh(key))
      .filterNot { it is StoreReadResponse.Loading || it is StoreReadResponse.NoNewData }
      .first()
      .requireData()

Data Fetching

The Fetcher retrieves data from the remote source, emitting FetcherResult objects.

Error Handling

If an error occurs, the Fetcher emits a FetcherResult.Error, which the Store can handle appropriately.

Data Storage

Successful data is written to the Source Of Truth and Memory Cache.

Data Delivery

The Store provides the data to the application in the form of a StoreReadResponse.

Get started

Learn about Store

Build with Store

Fetcher

Purpose of the Fetcher

APIs

Fetcher

FetcherResult

FetcherResult.Data

FetcherResult.Error

FetcherResult.Error.Exception

FetcherResult.Error.Message

FetcherResult.Error.Custom

Data Flow

​Purpose of the Fetcher

​APIs

​Fetcher

​FetcherResult

​FetcherResult.Data

​FetcherResult.Error

FetcherResult.Error.Exception

FetcherResult.Error.Message

FetcherResult.Error.Custom

​Data Flow

Purpose of the Fetcher

APIs

Fetcher

FetcherResult

FetcherResult.Data

FetcherResult.Error

Data Flow