Store

https://store.mobilenativefoundation.org/docs
Admin
Store is designed to simplify data management in modern applications, providing an architecture for...
Tokens:24,165
Snippets:284
Trust Score:7.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Fetcher Network Fetch Example

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

Demonstrates fetching data from the network using a Fetcher.

```kotlin
val networkData = fetcher.fetch(key)
```

--------------------------------

### Real Implementation of Post Operations

Source: https://store.mobilenativefoundation.org/docs/quickstart

Provides the concrete implementation for the PostOperations interface using Ktor's HttpClient. Handles making GET and PUT requests to the API.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.rest.impl

import io.ktor.client.* 
import io.ktor.client.call.* 
import io.ktor.client.request.* 
import org.mobilenativefoundation.trails.backend.models.PostNetworkModel

@Inject
class RealPostOperations(
    private val httpClient: HttpClient = httpClient()
) : PostOperations {

    override suspend fun getPost(id: Int): PostNetworkModel {
        val url = TrailsEndpoints.getPost(id)
        val response = httpClient.get(url)
        return response.body()
    }

    override suspend fun updatePost(post: PostNetworkModel): Boolean {
        val url = TrailsEndpoints.updatePost(post.id)
        val response = httpClient.put(url) {
            setBody(post)
        }
        return response.body()
    }
}
```

--------------------------------

### Setup PostSourceOfTruthFactory

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

The Source of Truth Factory sets up the reader and writer components for handling data operations. It defines how reads, writes, deletes, and deleteAll operations are managed.

```kotlin
class PostSourceOfTruthFactory(
    private val reader: PostSourceOfTruthReader,
    private val writer: PostSourceOfTruthWriter,
) {
    fun create(): SourceOfTruth<PostOperation, Output, Output> = SourceOfTruth.of(
        reader = { operation ->
            val mutableSharedFlow = MutableSharedFlow<Output?>(
                replay = 8,
                extraBufferCapacity = 20,
                onBufferOverflow = BufferOverflow.DROP_OLDEST,
            )

            reader.handleRead(operation) { mutableSharedFlow.emit(it) }

            mutableSharedFlow.asSharedFlow()
        },
        writer = { operation, output -> writer.handleWrite(operation, output) },
        delete = { operation -> writer.handleWrite(operation) },
        deleteAll = { writer.handleWrite(Operation.Mutation.Delete.DeleteAll) },
    )
}
```

--------------------------------

### Generated SQLDelight Entity

Source: https://store.mobilenativefoundation.org/docs/quickstart

An example of a Kotlin data class generated by SQLDelight from the SQL schema. This class represents a row in the 'postEntity' table.

```kotlin
data class PostEntity(
    val id: Long,
    val creator_id: Long,
    val caption: String?,
    val created_at: String,
    val likes_count: Long,
    val comments_count: Long,
    val shares_count: Long,
    val views_count: Long,
    val is_sponsored: Long,
    val cover_url: String,
    val platform: Platform,
    val location_name: String?,
    val is_favorited_by_current_user: Long
)
```

--------------------------------

### Bookkeeper Implementation with Database Storage

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/bookkeeper

Example of creating a Bookkeeper that uses a local database (trailsDatabase) to store and manage failed sync records for posts. It includes error handling for database operations.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createBookkeeper(): Bookkeeper<Int> =
  Bookkeeper.by(
      getLastFailedSync = { id ->
          trailsDatabase.postBookkeepingQueries
              .selectMostRecentFailedSync(id).executeAsOneOrNull()?.let {
                  timestampToEpochMilliseconds(timestamp = failedSync.timestamp)
              }
      },
      setLastFailedSync = { id, timestamp ->
          try {
              trailsDatabase.postBookkeepingQueries.insertFailedSync(
                  PostFailedSync(
                      post_id = id,
                      timestamp = epochMillisecondsToTimestamp(timestamp)
                  )
              )
              true
          } catch (e: SQLException) {
              // Handle the exception
              false
          }
      },
      clear = { id ->
          try {
              trailsDatabase.postBookkeepingQueries.clearByPostId(id)
              true
          } catch (e: SQLException) {
              // Handle the exception
              false
          }
      },
      clearAll = {
          try {
              trailsDatabase.postBookkeepingQueries.clearAll()
              true
          } catch (e: SQLException) {
              // Handle the exception
              false
          }
      }
  )
```

--------------------------------

### API Interface for Post Operations

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the contract for interacting with post-related API endpoints. Includes suspend functions for getting and updating posts.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.rest.api

interface PostOperations {
    suspend fun getPost(id: Int): PostNetworkModel
    suspend fun updatePost(post: PostNetworkModel): Boolean
}

interface TrailsApi: PostOperations
```

--------------------------------

### Get Cached Data from Store5

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/fetcher

Extension function to retrieve cached data from a Store. It bypasses loading and no-new-data states, returning the first available data.

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

--------------------------------

### Set Up Store Factory

Source: https://store.mobilenativefoundation.org/docs/quickstart

Provides a placeholder for setting up a factory to create a `PostStore` instance. Implementations for `TODO()` will be provided in subsequent steps.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

```

--------------------------------

### Invoke Source of Truth Reader

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

The Store invokes the reader method of the Source of Truth to get a Flow of local data.

```kotlin
val localDataFlow = sourceOfTruth.reader(key)
```

--------------------------------

### Observing Database Changes

Source: https://store.mobilenativefoundation.org/docs/quickstart

Demonstrates how to observe changes in the database using `asFlow()` and `mapToOneOrNull()` for real-time updates.

```kotlin
trailsDatabase
    .postQueries
    .selectPostById(id.toLong())
    .asFlow()
    .mapToOneOrNull()
```

--------------------------------

### Implement the Converter

Source: https://store.mobilenativefoundation.org/docs/quickstart

Sets up a Converter to handle transformations between network, local database, and domain models using extension functions.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createConverter(): Converter<PostNetworkModel, PostEntity, Post> =
  Converter.Builder<PostNetworkModel, PostEntity, Post>()
      .fromOutputToLocal { post -> post.asPostEntity() }
      .fromNetworkToLocal { postNetworkModel -> postNetworkModel.asPost() }
      .build()
```

--------------------------------

### Post Detail Screen Presenter Implementation

Source: https://store.mobilenativefoundation.org/docs/quickstart

Implements the PostDetailScreen Presenter using the PostRepository to fetch post data and manage UI state. It uses LaunchedEffect to load data when the screen is composed.

```kotlin
package org.mobilenativefoundation.trails.xplat.feat.postDetailScreen.impl

@Inject
class PostDetailScreenPresenter(
    private val postRepository: PostRepository,
    @Assisted private val postId: Int
) : PostDetailScreen.Presenter {

    @Composable
    override fun present(): PostDetailScreen.State {
        var post: Post? by remember { mutableStateOf(null) }

        LaunchedEffect(postId) {

```

--------------------------------

### Initiate Store Read Request

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

Initiates a data read request from the Store, specifying the key and whether to refresh.

```kotlin
val request = StoreReadRequest.cached(key, refresh)
val flow = store.stream(request)
```

--------------------------------

### Implement the Fetcher

Source: https://store.mobilenativefoundation.org/docs/quickstart

Creates a Fetcher to retrieve post data from the network using the PostOperations client. Handles cases where a post is not found.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createFetcher(): Fetcher<Int, PostNetworkModel> =
  Fetcher.of { id ->
      // Fetch post from the network
      client.getPost(id) ?: throw IllegalArgumentException("Post with ID $id not found.")
  }
```

--------------------------------

### Time-Based Data Validation

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/validator

Implement a validator to ensure data is refreshed after a specific period, such as 24 hours. This example checks if the current time is before the item's expiration time.

```kotlin
val validator = Validator.by { item ->
    Clock.System.now() < item.expiresAt
}
```

--------------------------------

### Queue Local Write Request

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/updater

Add a write request to the per-key write request queue within RealMutableStore.

```kotlin
addWriteRequestToQueue(writeRequest)
```

--------------------------------

### Real Post Repository Implementation

Source: https://store.mobilenativefoundation.org/docs/quickstart

Implements the PostRepository using PostStore for data fetching and caching. Handles writing updated post data back to the store.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl

@Inject
class RealPostRepository(
    private val postStore: PostStore
) : PostRepository {
    override suspend fun getPost(id: Int): Post? {
        return postStore.fresh<Int, Post, Boolean>(id)
    }

    override suspend fun updatePost(
        postId: Int,
        likesCount: Long?,
        commentsCount: Long?,
        sharesCount: Long?,
        viewsCount: Long?,
        isFavoritedByCurrentUser: Boolean?
    ): Post {
        val prevPost = postStore.get<Int, Post, Boolean>(postId)

        val nextPost = prevPost.copy(
            likesCount = likesCount ?: prevPost.likesCount,
            commentsCount = commentsCount ?: prevPost.commentsCount,
            sharesCount = sharesCount ?: prevPost.sharesCount,
            viewsCount = viewsCount ?: prevPost.viewsCount,
            isFavoritedByCurrentUser = isFavoritedByCurrentUser ?: prevPost.isFavoritedByCurrentUser
        )

        val writeRequest = StoreWriteRequest.of<Int, Post, Boolean>(
            key = postId,
            value = nextPost
        )

        return when (postStore.write(writeRequest)) {
            is StoreWriteResponse.Error -> prevPost
            is StoreWriteResponse.Success -> nextPost
        }
    }
}
```

--------------------------------

### Configure commonMain Dependencies in Gradle

Source: https://store.mobilenativefoundation.org/docs/quickstart

Include the Store library in the `commonMain` source set dependencies within your `build.gradle.kts` file. This makes the library available in your shared code.

```kotlin
commonMain {
  dependencies {
    implementation(libs.store)
  }
}
```

--------------------------------

### Create Post Fetcher Factory

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

Creates a Fetcher for Post operations, handling different query types like FindOne, FindMany, FindAll, ObserveOne, and ObserveMany. Uses Fetcher.ofFlow to support observing changes over time.

```kotlin
class PostFetcherFactory(
    private val client: PostOperations,
    private val trailsDatabase: TrailsDatabase,
) {

    fun create(): Fetcher<PostOperation, Output> =
        Fetcher.ofFlow { operation ->

            require(operation is Operation.Query)

            val mutableSharedFlow = MutableSharedFlow<Output>(
                replay = 8,
                extraBufferCapacity = 20,
                onBufferOverflow = BufferOverflow.DROP_OLDEST,
            )

            when (operation) {
                is Operation.Query.FindOne -> {
                    findAndEmitOne(operation) { mutableSharedFlow.emit(it) }
                }
                is Operation.Query.FindMany -> {
                    findAndEmitMany(operation) { mutableSharedFlow.emit(it) }
                }
                is Operation.Query.FindAll -> {
                    findAndEmitAll { mutableSharedFlow.emit(it) }
                }
                is Operation.Query.ObserveOne -> {
                    observeOneAndEmitUpdates(operation) { mutableSharedFlow.emit(it) }
                }
                is Operation.Query.ObserveMany -> {
                    observeManyAndEmitUpdates(operation) { mutableSharedFlow.emit(it) }
                }
            }

            mutableSharedFlow.asSharedFlow()
        }

    private suspend fun findAndEmitOne(
        operation: Operation.Query.FindOne<Post.Key>,
        emit: suspend (Output) -> Unit,
    ) {
        val post = client.findOne(operation.key.id)
        emit(Output.Single(post))
    }

    private suspend fun findAndEmitMany(
        operation: Operation.Query.FindMany<Post.Key>,
        emit: suspend (Output) -> Unit,
    ) {
        val posts = client.findMany(operation.keys.ids.map { it.id })
        emit(Output.Collection(posts))
    }

    private suspend fun findAndEmitAll(emit: suspend (Output) -> Unit) {
        val posts = client.findAll()
        emit(Output.Collection(posts))
    }

    private suspend fun observeOneAndEmitUpdates(
        operation: Operation.Query.ObserveOne<Post.Key>,
        emit: suspend (Output) -> Unit,
    ) {
        client.observeOne(operation.key.id).collect { post ->
            emit(Output.Single(post))
        }
    }

    private suspend fun observeManyAndEmitUpdates(
        operation: Operation.Query.ObserveMany<Post.Key>,
        emit: suspend (Output) -> Unit,
    ) {
        client.observeMany(operation.keys.map { it.id }).collect { posts ->
            emit(Output.Collection(posts))
        }
    }
}

```

--------------------------------

### Add Store Dependency using Version Catalogs

Source: https://store.mobilenativefoundation.org/docs/quickstart

Add the Store library dependency to your project's `libs.versions.toml` file. This is the recommended approach for managing dependencies in Gradle projects.

```toml
[versions]
store = "5.1.0"

[libraries]
store = { module = "org.mobilenativefoundation.store:store5", version.ref = "store" }
```

--------------------------------

### Display Post Detail Screen UI

Source: https://store.mobilenativefoundation.org/docs/quickstart

Composes the UI for the Post Detail Screen, rendering either a loading view or the detailed post view based on the current state. It handles user interactions like favoriting and unfavoriting.

```kotlin
package org.mobilenativefoundation.trails.xplat.feat.postDetailScreen.impl

@Inject
class PostDetailScreenUI : PostDetailScreen.UI {
    @Composable
    override fun Content(state: PostDetailScreen.State, modifier: Modifier) {
      when (state) {
        is PostDetailScreen.State.Loading -> {
          LoadingView()
        }

        is PostDetailScreen.State.Loaded -> {
          PostDetailView(
            post = state.post,
            onFavorite = { state.eventSink(PostDetailScreen.Event.Favorite) },
            onUnfavorite = { state.eventSink(PostDetailScreen.Event.Unfavorite) }
          )
        }
      }
    }
}
```

--------------------------------

### Implement the Source of Truth

Source: https://store.mobilenativefoundation.org/docs/quickstart

Configures a Source of Truth that reads from and writes to a local SqlDelight database. It defines how to query and insert post entities.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createSourceOfTruth(): SourceOfTruth<Int, PostEntity, Post> =
  SourceOfTruth.of(
      reader = { id ->
          flow {
              // Query the database for a post
              emit(trailsDatabase.postQueries.selectPostById(id.toLong()))
          }
      },
      writer = { _, postEntity ->
          trailsDatabase.postQueries.insertPost(postEntity)
      }
  )
```

--------------------------------

### Add Store Dependency Directly

Source: https://store.mobilenativefoundation.org/docs/quickstart

If not using Version Catalogs, add the Store library dependency directly to your `build.gradle.kts` file. Ensure you use the correct version number.

```kotlin
dependencies {
    implementation("org.mobilenativefoundation.store:store5:5.1.0")
}
```

--------------------------------

### PostStoreFactory Implementation

Source: https://store.mobilenativefoundation.org/docs/quickstart

Factory class for creating a PostStore. It orchestrates the creation of various components like Fetcher, Source of Truth, Converter, Updater, and Bookkeeper.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

class PostStoreFactory(
    private val client: PostOperations,
    private val trailsDatabase: TrailsDatabase,
) {

    fun create(): PostStore {
        return MutableStoreBuilder.from(
            fetcher = createFetcher(),
            sourceOfTruth = createSourceOfTruth(),
            converter = createConverter()
        ).build(
            updater = createUpdater(),
            bookkeeper = createBookkeeper()
        )
    }

    private fun createFetcher(): Fetcher<Int, PostNetworkModel> {...}

    private fun createSourceOfTruth(): SourceOfTruth<Int, PostEntity, Post> {...}

    private fun createConverter(): Converter<PostNetworkModel, PostEntity, Post> {...}

    private fun createUpdater(): Updater<Int, Post, Boolean> {...}

    private fun createBookkeeper(): Bookkeeper<Int> {...}
}

```

--------------------------------

### Initiate Local Data Mutation

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/updater

Create a StoreWriteRequest to update local data in the Store.

```kotlin
val writeRequest = StoreWriteRequest.of(key, value)
mutableStore.write(writeRequest)
```

--------------------------------

### Post Detail Screen API Definition

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the Circuit Screen, State, and Event for the post detail screen. Includes states for loading and loaded data, and events for user interactions like favoriting.

```kotlin
package org.mobilenativefoundation.trails.xplat.feat.postDetailScreen.api

interface PostDetailScreen : Screen {
    sealed interface State : CircuitUiState {
        data class Loaded(
          val post: Post,
          val eventSink: (Event) -> Unit,
        ) : State
        data object Loading: State
    }

    sealed interface Event : CircuitUiEvent {
        data object Favorite: Event
        data object Unfavorite: Event
    }

    interface UI : CircuitUI<State>
    interface Presenter : CircuitPresenter<State>
}
```

--------------------------------

### Create Type Aliases for PostStore

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/setting-up-store-for-crud-operations

Creates type aliases for `PostOperation`, `Output`, and `PostStore` to simplify and improve the readability of code related to Post data management.

```kotlin
typealias PostOperation = Operation<Post.Key, Post.Properties, Post.Edges, Post.Node>
typealias Output = Output<Post>
typealias PostStore = MutableStore<PostOperation, Output>
```

--------------------------------

### Create PostStore using PostStoreFactory

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

This factory class constructs a PostStore by assembling various components responsible for fetching, storing, and updating post data. It utilizes a Converter that passes data through without transformation.

```kotlin
class PostStoreFactory(
    private val client: PostOperations,
    private val trailsDatabase: TrailsDatabase,
    private val coroutineDispatcher: CoroutineDispatcher,
) {
    private val fetcherFactory = PostFetcherFactory(client)
    private val sourceOfTruthReader = PostSourceOfTruthReader(trailsDatabase, coroutineDispatcher)
    private val sourceOfTruthWriter = PostSourceOfTruthWriter(trailsDatabase)
    private val sourceOfTruthFactory = PostSourceOfTruthFactory(sourceOfTruthReader, sourceOfTruthWriter)
    private val updaterFactory = PostUpdaterFactory(client)
    private val bookkeeperFactory = PostBookkeeperFactory(trailsDatabase)

    fun create(): PostStore =
        MutableStoreBuilder
            .from(
                fetcher = fetcherFactory.create(),
                sourceOfTruth = sourceOfTruthFactory.create(),
                converter = createConverter(),
            ).build(
                updater = updaterFactory.create(),
                bookkeeper = bookkeeperFactory.create(),
            )

    private fun createConverter(): Converter<PostNetworkModel, PostEntity, Post> =
        Converter
            .Builder<PostOutput, PostOutput, PostOutput>()
            .fromOutputToLocal { it }
            .fromNetworkToLocal { it }
            .build()
}

```

--------------------------------

### Create Network Flow

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/store

Initiates the network flow for fetching data. The FetcherController ensures only one network call per key.

```kotlin
val networkFlow = createNetworkFlow(request, networkLock)
```

--------------------------------

### Local Database Model (SQLDelight)

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the schema for storing post data in a local SQLDelight database. Maps network fields to database columns, including primary keys, foreign keys, and data types.

```sql
package org.mobilenativefoundation.trails.xplat.lib.db

CREATE TABLE postEntity (
    id INTEGER PRIMARY KEY,
    creator_id INTEGER NOT NULL,
    caption TEXT,
    created_at TEXT NOT NULL,
    likes_count INTEGER NOT NULL,
    comments_count INTEGER NOT NULL,
    shares_count INTEGER NOT NULL,
    views_count INTEGER NOT NULL,
    is_sponsored INTEGER NOT NULL,
    cover_url TEXT NOT NULL,
    platform TEXT AS Platform NOT NULL,
    location_name TEXT,
    is_favorited_by_current_user INTEGER NOT NULL,
    FOREIGN KEY (creator_id) REFERENCES creatorEntity(id)
);
```

--------------------------------

### Fetch Fresh Data from Store5

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/fetcher

Extension function to force a fresh data fetch from the Store. It bypasses loading and no-new-data states, returning the first available data.

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

--------------------------------

### Source of Truth Read or Network Fetch

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/store

Reads from SourceOfTruth if available and fetch is not explicitly requested, otherwise initiates a combined disk/network read.

```kotlin
if (request.fetch) {
  diskNetworkCombined(request, sourceOfTruth)
} else {
  sourceOfTruth.reader(request.key, diskLock).transform { response -> ... }
}
```

--------------------------------

### Initialize Thread Safety Mechanisms

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/mutable-store

Ensures that thread safety mechanisms and write request queues are initialized for a given key before proceeding with operations.

```kotlin
safeInitStore(request.key)
```

--------------------------------

### Implement the Updater

Source: https://store.mobilenativefoundation.org/docs/quickstart

Creates an Updater that makes a network call to update a post. It returns a success or error result based on the network operation.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createUpdater(): Updater<Int, Post, Boolean> =
  Updater.by(
      post = { _, updatedPost ->
          val networkModel = updatedPost.asNetworkModel()
          val success = client.updatePost(networkModel)
          if (success) {
              UpdaterResult.Success.Typed(success)
          } else {
              UpdaterResult.Error.Message("Something went wrong.")
          }
      }
  )
```

--------------------------------

### Create PostUpdaterFactory

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

Factory class for creating Updater instances. It handles the logic for synchronizing local mutations with the remote data source for Post operations. This is invoked on reads if conflicts might exist.

```kotlin
class PostUpdaterFactory(
    private val client: PostOperations,
) {

    fun create(): Updater<PostOperation, PostOutput, PostWriteResponse> = Updater.by(
        post = { operation, post ->
            handleOperation(operation, post)
        },
        onCompletion = null
    )

    private suspend fun handleOperation(operation: PostOperation, post: PostOutput): UpdaterResult {
        return when (operation) {
            is Operation.Mutation.Create.InsertOne -> {
                require(post is PostOutput.Single && post.value is Post.Properties)
                client.insertOne(post.value as Post.Properties)
            }

            is Operation.Mutation.Create.InsertMany -> {
                require(post is PostOutput.Collection && post.items.all { it is Post.Properties })
                client.insertMany(post.items.map { it as Post.Properties })
            }

            is Operation.Mutation.Update.UpdateOne -> {
                require(post is PostOutput.Single && post.value is Post.Node)
                client.updateOne(post.value as Post.Node)
            }

            is Operation.Mutation.Update.UpdateMany -> {
                require(post is PostOutput.Collection && post.items.all { it is Post.Node })
                client.updateMany(post.items.map { it as Post.Node })
            }

            is Operation.Mutation.Upsert.UpsertOne -> {
                require(post is PostOutput.Single && post.value is Post.Properties)
                client.upsertOne(post.value as Post.Properties)
            }
            is Operation.Mutation.Delete.DeleteOne -> {
                client.deleteOne(operation.key)
            }

            is Operation.Mutation.Delete.DeleteMany -> {
                client.deleteMany(operation.keys)
            }

            is Operation.Mutation.Delete.DeleteAll -> {
                client.deleteAll()
            }

            is Operation.Query.FindOne -> {
                require(post is PostOutput.Single && post.value is Post.Node)
                client.updateOne(post.value as Post.Node)
            }
            is Operation.Query.FindMany -> {
                require(post is PostOutput.Collection && post.items.all { it is Post.Node })
                client.updateMany(post.items.map { it as Post.Node })
            }
            is Operation.Query.FindAll -> {
                require(post is PostOutput.Collection && post.items.all { it is Post.Node })
                client.updateMany(post.items.map { it as Post.Node })
            }
            is Operation.Query.ObserveOne -> {
                require(post is PostOutput.Single && post.value is Post.Node)
                client.updateOne(post.value as Post.Node)
            }
            is Operation.Query.ObserveMany -> {
                require(post is PostOutput.Collection && post.items.all { it is Post.Node })
                client.updateMany(post.items.map { it as Post.Node })
            }
        }
    }
}
```

--------------------------------

### Decide Data Source - Early Exit

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/store

Determines the data source. Emits 'NoNewData' if neither SourceOfTruth nor network fetch is possible or requested.

```kotlin
if (sourceOfTruth == null && !request.fetch) {
  emit(StoreReadResponse.NoNewData(origin = StoreReadResponseOrigin.Cache))
  return@flow
}
```

--------------------------------

### PostStore Factory

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the factory for creating a PostStore, outlining dependencies and methods for creating store components.

```kotlin
typealias PostStore = Store<Int, Post>

class PostStoreFactory(
    private val client: PostOperations,
    private val trailsDatabase: TrailsDatabase,
) {

    fun create(): PostStore {
        TODO()
    }

    private fun createFetcher(): Fetcher<Int, PostNetworkModel> {
        TODO()
    }

    private fun createSourceOfTruth(): SourceOfTruth<Int, PostEntity, Post> {
        TODO()
    }

    private fun createConverter(): Converter<PostNetworkModel, PostEntity, Post> {
        TODO()
    }

    private fun createUpdater(): Updater<Int, Post, Boolean> {
        TODO()
    }

    private fun createBookkeeper(): Bookkeeper<Int> {
        TODO()
    }
}
```

--------------------------------

### Create a Bookkeeper with Custom Logic

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/bookkeeper

Implement a Bookkeeper by providing custom functions for retrieving, setting, and clearing failed sync records. This is useful when you need to integrate with your own storage mechanism.

```kotlin
val bookkeeper = Bookkeeper.by(
    getLastFailedSync = { key ->
        // Retrieve timestamp from storage
    },
    setLastFailedSync = { key, timestamp ->
        // Save timestamp to storage
        true
    },
    clear = { key ->
        // Remove entry from storage
        true
    },
    clearAll = {
        // Clear all entries from storage
        true
    }
)
```

--------------------------------

### Network Data Model

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the structure for a post fetched from the network. Includes details like ID, creator, caption, platform, timestamps, engagement counts, sponsorship status, and cover URL.

```kotlin
package org.mobilenativefoundation.trails.backend.models

import kotlinx.datetime.LocalDateTime
import kotlinx.serialization.Serializable

@Serializable
data class PostNetworkModel(
    val id: Int,
    val creatorId: Int,
    val caption: String?,
    val platform: Platform,
    val createdAt: LocalDateTime,
    val likesCount: Long,
    val commentsCount: Long,
    val sharesCount: Long,
    val viewsCount: Long,
    val isSponsored: Boolean,
    val locationName: String?,
    val coverUrl: String,
    val isFavoritedByCurrentUser: Boolean
)
```

--------------------------------

### Define DataSources Class

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/setting-up-store-for-crud-operations

Defines the `DataSources` class to specify data fetching locations (memory, disk, remote) and provides common configurations.

```kotlin
data class DataSources(val memory: Boolean, val disk: Boolean, val remote: Boolean) {
    companion object {
        val all = DataSources(memory = true, disk = true, remote = true)
        val localOnly = DataSources(memory = true, disk = true, remote = false)
        val remoteOnly = DataSources(memory = false, disk = false, remote = true)
    }
}
```

--------------------------------

### PostSourceOfTruthReader Implementation

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

This Kotlin class implements a `Reader` for `Post` entities, handling different query operations like `FindOne`, `FindAll`, `FindMany`, `ObserveOne`, and `ObserveMany`. It interacts with a `TrailsDatabase` to retrieve data and emits results using a provided `emit` function. Returns `null` for empty results to signal a potential network fetch.

```kotlin
class PostSourceOfTruthReader(
    private val trailsDatabase: TrailsDatabase,
    coroutineDispatcher: CoroutineDispatcher,
) {
    private val coroutineScope = CoroutineScope(coroutineDispatcher)

    fun handleRead(
        operation: Operation.Query<Post.Key, Post.Properties, Post.Edges, Post.Node>,
        emit: suspend (Output?) -> Unit,
    ) {
        when (operation) {
            is Operation.Query.FindOne -> findOne(operation, emit)
            is Operation.Query.FindAll -> findAll(emit)
            is Operation.Query.FindMany -> findMany(operation, emit)
            is Operation.Query.ObserveOne -> observeOne(operation, emit)
            is Operation.Query.ObserveMany -> observeMany(operation, emit)
        }
    }

    private fun findOne(
        operation: Operation.Query.FindOne<Post.Key>,
        emit: suspend (Output?) -> Unit,
    ) {
        coroutineScope.launch {
            val entity = 
                trailsDatabase
                    .postQueries
                    .selectPostById(operation.key.id.toLong())
                    .executeAsOneOrNull()
            val output = entity?.asNode()?.let { Output.Single(it) }
            emit(output)
        }
    }

    private fun findMany(
        operation: Operation.Query.FindMany<Post.Key>,
        emit: suspend (Output?) -> Unit,
    ) {
        coroutineScope.launch {
            val entities = 
                trailsDatabase
                    .postQueries
                    .selectPostsByIds(operation.keys.map {}.map { it.toLong() })
                    .executeAsList()

            val output = 
                if (entities.isEmpty()) {
                    null
                } else {
                    Output.Collection(entities.map { it.asNode() })
                }
            emit(output)
        }
    }

    private fun findAll(emit: suspend (Output?) -> Unit) {
        coroutineScope.launch {
            val entities = trailsDatabase.postQueries.selectAllPosts().executeAsList()

            val output = 
                if (entities.isEmpty()) {
                    null
                } else {
                    Output.Collection(entities.map { it.asNode() })
                }
            emit(output)
        }
    }

    private fun observeOne(
        operation: Operation.Query.ObserveOne<Post.Key>,
        emit: suspend (Output?) -> Unit,
    ) {
        coroutineScope.launch {
            trailsDatabase.postQueries.selectPostById(operation.key.id.toLong()).asFlow().collect { query ->
                val entity = query.executeAsOneOrNull()
                val output = entity?.asNode()?.let { Output.Single(it) }
                emit(output)
            }
        }
    }

    private fun observeMany(
        operation: Operation.Query.ObserveMany<Post.Key>,
        emit: suspend (Output?) -> Unit,
    ) {
        coroutineScope.launch {
            trailsDatabase
                .postQueries
                .selectPostsByIds(operation.keys.map {}.map { it.toLong() })
                .asFlow()
                .collect { query ->
                    val entities = query.executeAsList()

                    val output = 
                        if (entities.isEmpty()) {
                            null
                        } else {
                            Output.Collection(entities.map { it.asNode() })
                        }
                    emit(output)
                }
        }
    }
}
```

--------------------------------

### Finding the First Failed Sync

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

This function retrieves failed create, update, and delete operations for a given ID and returns the timestamp of the earliest failure, or null if no failures are found.

```kotlin
private suspend fun firstFailedSyncOrNull(id: Long): Long? {
        val failedCreates =
            trailsDatabase.postBookkeepingQueries
                .getFailedCreates(id)
                .executeAsList()
        val failedUpdates =
            trailsDatabase.postBookkeepingQueries
                .getFailedUpdates(id)
                .executeAsList()
        val failedDeletes =
            trailsDatabase.postBookkeepingQueries
                .getFailedDeletes(id)
                .executeAsList()

        return failedCreates.firstOrNull()?.timestamp
            ?: failedUpdates.firstOrNull()?.timestamp
            ?: failedDeletes.firstOrNull()?.timestamp
    }
```

--------------------------------

### Convert Domain Model to Local Database Model

Source: https://store.mobilenativefoundation.org/docs/quickstart

Converts a domain model representation of a post to a local database entity. This is necessary when saving data from the application to local storage.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.extensions

object PostExtensions {
    // Convert from the domain model to the local database model.

    fun Post.asPostEntity(): PostEntity {
        return PostEntity(
            id = this.id.toLong(),
            creator_id = this.creatorId.toLong(),
            caption = this.caption,
            created_at = createdAt.toString(),
            likes_count = this.likesCount,
            comments_count = this.commentsCount,
            shares_count = this.sharesCount,
            views_count = this.viewsCount,
            is_sponsored = if (this.isSponsored) 1 else 0,
            cover_url = this.coverURL,
            platform = this.platform,
            location_name = this.locationName,
            is_favorited_by_current_user = if (this.isFavoritedByCurrentUser) 1 else 0
        )
    }
}
```

--------------------------------

### Convert Local Database Model to Domain Model

Source: https://store.mobilenativefoundation.org/docs/quickstart

Converts a local database entity representation of a post to its domain model equivalent. This is used when retrieving data from local storage and preparing it for application use.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.extensions

object PostExtensions {
    // Convert from the local database model to the domain model.

    fun PostEntity.asPost(): Post {
        return Post(
            id = this.id.toInt(),
            creatorId = this.creator_id.toInt(),
            caption = this.caption,
            createdAt = LocalDateTime.parse(this.created_at),
            likesCount = this.likes_count.toLong(),
            commentsCount = this.comments_count.toLong(),
            sharesCount = this.shares_count.toLong(),
            viewsCount = this.views_count.toLong(),
            isSponsored = this.is_sponsored == 1L,
            coverURL = this.cover_url,
            platform = this.platform,
            locationName = this.location_name,
            isFavoritedByCurrentUser = this.is_favorited_by_current_user == 1L
        )
    }
}
```

--------------------------------

### Combine and Emit Data

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/store

Combines data streams from network and source of truth, emitting responses and updating the memory cache as needed.

```kotlin
emitAll(
  stream.transform { output: StoreReadResponse<Output> ->
    emit(output)
    // Update memory cache if needed
  },
)
```

--------------------------------

### Record Failed Server Sync Attempt

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/mutable-store

Records a failed server synchronization attempt using the Bookkeeper. This is done when the server update fails.

```kotlin
bookkeeper?.setLastFailedSync(request.key)
```

--------------------------------

### Attempt Server Synchronization

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/updater

Invoke the Updater to post the latest value to the remote data source.

```kotlin
val updaterResult = updater.post(writeRequest.key, writeRequest.value)
```

--------------------------------

### Handling Bookkeeper Operations

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/implementing-crud-operations-in-store

This code block demonstrates how the Bookkeeper class handles different types of operations, including queries and mutations. It shows how to clear failed syncs based on the operation type and keys.

```kotlin
is Operation.Query.ObserveOne -> {
                clearFailedSyncs(operation.key.id.toLong())
            }

            is Operation.Query.ObserveMany -> {
                operation.keys.forEach { key ->
                    clearFailedSyncs(key.id.toLong())
                }
            }
            is Operation.Mutation.Create.InsertOne -> {
                clearFailedSyncs(operation.key.id.toLong())
            }

            is Operation.Mutation.Create.InsertMany -> {
                operation.keys.forEach { key ->
                    clearFailedSyncs(key.id.toLong())
                }
            }

            is Operation.Mutation.Update.UpdateOne -> {
                clearFailedSyncs(operation.key.id.toLong())
            }

            is Operation.Mutation.Update.UpdateMany -> {
                operation.keys.forEach { key ->
                    clearFailedSyncs(key.id.toLong())
                }
            }

            is Operation.Mutation.Upsert.UpsertOne -> {
                clearFailedSyncs(operation.key.id.toLong())
            }

            is Operation.Mutation.Update.UpsertMany -> {
                operation.keys.forEach { key ->
                    clearFailedSyncs(key.id.toLong())
                }
            }

            is Operation.Mutation.Delete.DeleteOne -> {
                clearFailedSyncs(operation.key.id.toLong())
            }

            is Operation.Mutation.Delete.DeleteMany -> {
                operation.keys.forEach { key ->
                    clearFailedSyncs(key.id.toLong())
                }
            }

            is Operation.Mutation.Delete.DeleteAll -> {
                clearAllFailedSyncs()
            }
```

--------------------------------

### Define Create Mutations

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/setting-up-store-for-crud-operations

Defines `Create` operations within the `Mutation` class for inserting single or multiple entities.

```kotlin
sealed class Mutation<out K : Model.Key, out P : Model.Properties, out E : Model.Edges, out N : Model.Node<K, P, E>> : Operation<K, P, E, N>() {

    sealed class Create<K : Model.Key, P : Model.Properties, E : Model.Edges> : Mutation<K, P, E, Nothing>() {

        data class InsertOne<P: Model.Properties>(
            val properties: P
        ) : Create<Nothing, P, Nothing>()

        data class InsertMany<P: Model.Properties>(
            val properties: List<P>
        ) : Create<Nothing, P, Nothing>()
    }
}
```

--------------------------------

### MutableStore Interface

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/mutable-store

The MutableStore interface defines the contract for managing data with support for mutations, synchronization, and offline operations.

```APIDOC
## MutableStore Interface

### Description
Provides methods for data retrieval and mutations, including synchronization, conflict resolution, and offline support.

### Methods

#### `stream`

Returns a Flow of StoreReadResponse for a given StoreReadRequest.

* **request** (StoreReadRequest<Key>) - Required - The request configuration for data retrieval.

#### `write`

Performs a data mutation and returns a StoreWriteResponse.

* **request** (StoreWriteRequest<Key, Output, Response>) - Required - The request configuration for the data mutation.

#### `clear`

Clears the data item identified by the given key from the local store.

* **key** (Key) - Required - The key identifying the data item to be cleared.

#### `clearAll`

Clears all data items from the local store.

```

--------------------------------

### Create a Custom Validator

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/validator

Use the Validator.by factory method to create a custom validator. Provide a lambda function that defines your validation logic.

```kotlin
val validator = Validator.by {
    // Your custom validation logic here
}
```

--------------------------------

### Emit Write Response

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/updater

Emit a StoreWriteResponse to consumers, indicating the success or failure of the write operation.

```kotlin
emit(storeWriteResponse)
```

--------------------------------

### Post Repository API

Source: https://store.mobilenativefoundation.org/docs/quickstart

Defines the interface for fetching and updating post data. This API is feature-agnostic and intended for reuse across different parts of the application.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.api

interface PostRepository {
    suspend fun getPost(id: Int): Post?
    suspend fun updatePost(
        postId: Int,
        likesCount: Long? = null,
        commentsCount: Long? = null,
        sharesCount: Long? = null,
        viewsCount: Long? = null,
        isFavoritedByCurrentUser: Boolean? = null
    ): Post
}
```

--------------------------------

### SourceOfTruth Interface Definition

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

Defines the contract for a local data source, including methods for reading, writing, deleting, and deleting all data.

```kotlin
interface SourceOfTruth<Key : Any, Local : Any, Output : Any> {
    fun reader(key: Key): Flow<Output?>
    suspend fun write(key: Key, value: Local)
    suspend fun delete(key: Key)
    suspend fun deleteAll()
}
```

--------------------------------

### Write Fetched Data to Source of Truth

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

Writes data fetched from the network into the local Source of Truth.

```kotlin
sourceOfTruth.write(key, networkData)
```

--------------------------------

### Implement Model Interface in Post

Source: https://store.mobilenativefoundation.org/docs/use-cases/store5/setting-up-store-for-crud-operations

Refactors the Post class to implement the generalized Model interface. This allows defining operations on different aspects of a Post, such as its key, properties, and edges.

```kotlin
@Serializable
sealed interface Post : Model<Post.Key, Post.Properties, Post.Edges> {
    @Serializable
    data class Key(val id: Int) : Model.Key

    @Serializable
    data class Properties(
        val creatorId: Int,
        val caption: String?,
        val createdAt: LocalDateTime,
        val likesCount: Long,
        val commentsCount: Long,
        val sharesCount: Long,
        val viewsCount: Long,
        val isSponsored: Boolean,
        val coverURL: String,
        val platform: Platform,
        val locationName: String?
    ) : Model.Properties, Post

    @Serializable
    data class Edges(
        val creator: Creator.Node,
        val hashtags: List<Hashtag.Node>,
        val mentions: List<Mention.Node>,
        val media: List<Media.Node>
    ) : Model.Edges

    @Serializable
    data class Node(
        override val key: Key,
        override val properties: Properties
    ) : Model.Node<Key, Properties, Edges>, Post {
        val id: Int = this.key.id
        val caption: String = this.properties.caption.orEmpty()
    }

    @Serializable
    data class Composite(
        override val node: Node,
        override val edges: Edges
    ) : Model.Composite<Key, Properties, Edges>, Post
}
```

--------------------------------

### Implement the Bookkeeper

Source: https://store.mobilenativefoundation.org/docs/quickstart

Implements a Bookkeeper to track failed syncs, enabling conflict resolution after local mutations. It retrieves and sets the last failed sync timestamp.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.store

private fun createBookkeeper(): Bookkeeper<Int> =
  Bookkeeper.by(
      getLastFailedSync = { id ->
          trailsDatabase.postBookkeepingQueries
              .selectMostRecentFailedSync(id).executeAsOneOrNull()?.let { failedSync ->
                  timestampToEpochMilliseconds(timestamp = failedSync.timestamp)
              }
      },
      setLastFailedSync = { id, timestamp ->
          try {
              trailsDatabase.postBookkeepingQueries.insertFailedSync(
                  PostFailedSync(
                      post_id = id,
                      timestamp = epochMillisecondsToTimestamp(timestamp)
                  )
              )
          }
      }
  )
```

--------------------------------

### FetcherResult.Error.Exception

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/fetcher

Represents an exception that occurred during fetching. Use this when a Throwable is caught.

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

--------------------------------

### Domain Data Model

Source: https://store.mobilenativefoundation.org/docs/quickstart

Represents the post data within the application's domain layer. This model is used for internal application logic and may differ slightly from network or database models.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.models

import kotlinx.datetime.LocalDateTime

data class Post(
    val id: Int,
    val creatorId: Int,
    val caption: String?,
    val createdAt: LocalDateTime,
    val likesCount: Long,
    val commentsCount: Long,
    val sharesCount: Long,
    val viewsCount: Long,
    val isSponsored: Boolean,
    val coverURL: String,
    val platform: Platform,
    val locationName: String?,
    val isFavoritedByCurrentUser: Boolean
)
```

--------------------------------

### SourceOfTruth Interface

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/source-of-truth

The SourceOfTruth interface defines the contract for a local data store, including methods for reading, writing, and deleting data.

```APIDOC
## SourceOfTruth Interface

### Description
Defines the contract for a local data store that ensures data consistency and enables offline support. It provides methods to read, write, and delete data items identified by a key.

### Methods

#### `reader(key: Key)`
Reads data from the local data source for a given key. Returns a cold Flow emitting the domain data model associated with the key.

- **key** (Key) - Required - The unique key identifying the data item to be retrieved.

#### `write(key: Key, value: Local)`
Writes data to the local data source for a given key.

- **key** (Key) - Required - The unique key identifying the data item.
- **value** (Local) - Required - The data to be written, in the local data source format.

#### `delete(key: Key)`
Deletes a specific data item from the local data source.

- **key** (Key) - Required - The unique key identifying the data item to be deleted.

#### `deleteAll()`
Deletes all data items from the local data source.
```

--------------------------------

### Update Local Store with New Value

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/updater

Delegate the writing of the new value to the local data source using RealStore.

```kotlin
delegate.write(writeRequest.key, writeRequest.value)
```

--------------------------------

### Convert Network Model to Domain Model

Source: https://store.mobilenativefoundation.org/docs/quickstart

Converts a network model representation of a post to its domain model equivalent. This is useful for transforming data received from an API into a usable format within the application.

```kotlin
package org.mobilenativefoundation.trails.xplat.lib.market.post.impl.extensions

object PostExtensions {
    // Convert from the network model to the domain model.

    fun PostNetworkModel.asPost(): Post {
        return Post(
            id = this.id,
            creatorId = this.creatorId,
            caption = this.caption,
            createdAt = this.createdAt,
            likesCount = this.likesCount,
            commentsCount = this.commentsCount,
            sharesCount = this.sharesCount,
            viewsCount = this.viewsCount,
            isSponsored = this.isSponsored,
            coverURL = this.coverUrl,
            platform = this.platform.asPlatform(),
            locationName = this.locationName,
            isFavoritedByCurrentUser = this.isFavoritedByCurrentUser
        )
    }
}
```

--------------------------------

### Store Interface Definition

Source: https://store.mobilenativefoundation.org/docs/concepts/store5/store

Defines the core interface for the Store component, outlining methods for streaming data, clearing individual items, and clearing all data.

```kotlin
interface Store<Key : Any, Output : Any> {
  fun stream(request: StoreReadRequest<Key>): Flow<StoreReadResponse<Output>>
  suspend fun clear(key: Key)
  suspend fun clearAll()
}
```
Tokens:
Raw