Quickstart

Let’s build your first Store.

In this example, we’ll build a simple Store to fetch and cache posts for the Trails app.

Prerequisites

Installation

Add the Dependency
1
Add the Dependency
Add the Store library to your project's dependencies. Since we're working with a KMP project, we'll add the dependency to the commonMain source set.
toml
[versions] store = "5.1.0" [libraries] store = { module = "org.mobilenativefoundation.store:store5", version.ref = "store" }
kotlin
commonMain { dependencies { implementation(libs.store) } }
Tip
Understanding Version Catalogs:
The libs.versions.toml file is part of Gradle's Version Catalogs feature, which simplifies dependency management.
If you're not using Version Catalogs, you can add the dependency directly to your build.gradle.kts:
kotlin
dependencies { implementation("org.mobilenativefoundation.store:store5:5.1.0") }
For more information on Version Catalogs, visit the Gradle Documentation.
Sync the Project
2
Sync the Project
After adding the dependency, sync your project with Gradle to download the Store library.

Building a Store

Now, let’s build a simple Store to fetch and cache posts from our API and cache it for offline access.

Define the Data Models

Define the models for a post.

Network Model
Local Database Model
Domain Model

kotlin

package org.mobilenativefoundation.trails.backend.models

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

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

kotlin

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

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
)

Using SqlDelight for Local Database Models:

The SQL schema defined using SqlDelight will generate Kotlin models for you. Here's how the PostEntity class might look after generation:

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
)

For more details on how SqlDelight generates Kotlin classes from SQL schemas, check out the SqlDelight Docs.

Create the API Interface

Define and implement an interface for your network calls. In this example, we'll use Ktor for HTTP requests.

APIs
Implementations

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

kotlin

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

internal object TrailsEndpoints {
    private const val ROOT_API_URL = "https://api.trails.mattramotar.dev"
    fun getPost(id: Int) = "$ROOT_API_URL/posts/$id"
    fun updatePost(id: Int) = "$ROOT_API_URL/posts/$id"
}

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

@Inject
class RealTrailsClient(
    private val postOperations: PostOperations
) : TrailsClient,
    PostOperations by postOperations

Implement Converters

We need to convert between our network model, domain model, and local database model.

Network to Domain
Local Database to Domain
Domain to Local Database
Domain to Network

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

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

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

kotlin

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

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

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

Set Up the Store Factory

We'll use a factory for creating a PostStore instance.

kotlin

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

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

Implement the Fetcher

Our Fetcher will interact with the network data source using the PostOperations interface.

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.")
  }

Implement the Source of Truth

Our Source of Truth will delegate to a local SqlDelight database.

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

Observing Database Changes Over Time:

To ensure your SourceOfTruth observes changes in the database, use asFlow() and appropriate mapping functions.

kotlin

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

Implement the Converter
7
Implement the Converter
Our Converter will convert between our network model, local database model, and domain model using the PostExtensions object.
Note
Understanding the Converter's Role:
The Converter bridges the gap between the network model, local database model, and domain model within the Store.
While you have extension functions for conversions, the Converter integrates these into the Store's pipeline, ensuring data flows correctly through each layer.
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()

Implement the Updater

Our Updater will make a network call to update the post.

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.")
          }
      }
  )

Implement the Bookkeeper

Our Bookkeeper keeps track of failed syncs to enable eagerly resolving conflicts after local mutations.

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

Build the Store

Provide the implementations to the Store Builder.

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> {...}
}

Using the Store

Now, let’s use the Store to fetch and cache post data for the Trails post detail screen.

Create a Post Repository

We'll create a PostRepository that uses the PostStore to fetch and cache post data. The primary reason for this extra layer is it enables us to extract Store from the domain layer as an implementation detail of the PostRepository. It also enables us to add additional methods and strategies to the PostRepository in the future.

API
Implementation

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
}

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

Define the Post Detail Screen

Trails is built with a Circuit architecture. Before we can interact with the PostRepository, we need to define the Screen, State, and Event classes.

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

Implement the Post Detail Presenter

A Circuit Presenter is intended to be the business logic for a screen's UI and a translation layer in front of the data layer. Our PostDetailScreenPresenter will use the PostRepository to load the post data and update the UI in response to user actions.

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) {
          post = postRepository.getPost(postId)
        }

        return if (post != null) {
          PostDetailScreen.State.Loaded(post, eventSink = ::handleEvent)
        } else {
          PostDetailScreen.State.Loading
        }
    }

    private fun handleEvent(prevState: PostDetailScreen.State, event: PostDetailScreen.Event) {
      when (event) {
        is PostDetailScreen.Event.Favorite -> handleFavorite(prevState)
        is PostDetailScreen.Event.Unfavorite -> handleUnfavorite(prevState)
      }
    }

    private fun handleFavorite(prevState: PostDetailScreen.State) {
      val nextPost = postRepository.updatePost(
        postId = postId,
        isFavoritedByCurrentUser = true,
        likesCount = prevState.post.likesCount + 1
      )
      post = nextPost
    }

    private fun handleUnfavorite(prevState: PostDetailScreen.State) {
      val nextPost = postRepository.updatePost(
        postId = postId,
        isFavoritedByCurrentUser = false,
        likesCount = prevState.post.likesCount - 1
      )
      post = nextPost
    }
}

Display the Post Detail Screen

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

Next Steps

Now that you have built your first Store, it’s time to explore what else is possible:

Quickstart

Prerequisites

Installation

Building a Store

Using the Store

Next Steps

Deep Dive into Store

Use Case Guides

Store Cookbook