Fetcher

Responsible for retrieving data from remote sources, such as web services or APIs. It defines how fresh data is fetched when the the Store doesn’t have the required information or when the data needs to be refreshed.

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:

kotlin

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

Parameter: Key
Type: Any
Required: Required
Description: 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.
Parameter: Network
Type: Any
Required: Required
Description: 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.
Parameter: name
Type: String?
Required: Optional
Description: An optional unique name for the Fetcher, useful when differentiating between multiple fetchers, particularly when using fallbacks.
Parameter: fallback
Type: Fetcher<Key, Network>?
Required: Optional
Description: An optional Fetcher to be used if the parent Fetcher fails.
Parameter: invoke(key: Key)
Type: Flow<FetcherResult<Network>>
Required: Optional
Description: 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.

kotlin

sealed class FetcherResult<out Network : Any>

FetcherResult.Data

Represents a successful fetch.

kotlin

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

Parameter: value
Type: Network
Required: Required
Description: The fetched data.
Parameter: origin
Type: String?
Required: Optional
Description: An optional string to identify the source of the data.

FetcherResult.Error

Represents an error that occurred during fetching.

kotlin

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.

kotlin

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()
    }
}

Parameter: error
Type: Throwable
Required: Required
Description: The exception that occurred.

FetcherResult.Error.Message

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

kotlin

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()
    }
}

Parameter: message
Type: String
Required: Required
Description: 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.

kotlin

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()
    }
}

Parameter: E
Type: Any
Required: Required
Description: The type representing the custom error. For example, if fetching a list of posts, this could be PostNetworkError.
Parameter: error
Type: E
Required: Required
Description: The custom error.

Data Flow

Data Request

Application code requests data from the Store.

Extension for Making a Cached Data Request:

kotlin

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:

kotlin

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()

Client-Side Checks Conditional On Request Type
2
Client-Side Checks Conditional On Request Type
Note
Fresh Data Requests Bypass Client-Side Checks:
If the request is for fresh data, the Store bypasses the Memory Cache, Source Of Truth, and Validator and invokes the Fetcher immediately.
1. Cache Check
  A
  Cache Check
  If the request is for cached data, the Store checks the Memory Cache for the requested data. If the Memory Cache does not contain the data, the Store checks the Source Of Truth, if the Store is configured with a Source Of Truth.
2. Validation
  B
  Validation
  If the data is missing or determined invalid by the Validator, the Store invokes the Fetcher.
Data Fetching
3
Data Fetching
The Fetcher retrieves data from the remote source, emitting FetcherResult objects.
Error Handling
4
Error Handling
If an error occurs, the Fetcher emits a FetcherResult.Error, which the Store can handle appropriately.
Data Storage
5
Data Storage
Successful data is written to the Source Of Truth and Memory Cache.
Data Delivery
6
Data Delivery
The Store provides the data to the application in the form of a StoreReadResponse.