Skip to content

A simple API for creating and managing state in Kotlin Multiplatform applications.

License

Notifications You must be signed in to change notification settings

jordond/state-holder

Repository files navigation

State Holder

Maven Central Kotlin Build License

Compose Multiplatform badge-jvm badge-apple badge-js

A simple library for managing state in Kotlin Multiplatform projects, using Kotlin Coroutines and StateFlow.

You can view the KDocs at docs.stateholder.dev.

Note: This library is still in alpha, documentation is not finished.

Table of Contents

Motivation

State Holder is a library that aims to make state management in Kotlin Multiplatform projects easier. It provides a simple API for creating and managing state with very little boilerplate. It provides some extensions to make consuming the state easier (currently only Android).

This library is very un-opinionated and does not force you to use any particular architecture. You can create your StateHolder anywhere you want. This also means you are responsible for scoping the state, and on Android persisting the state across process death.

Planned Features

Currently this library is in a very early stage. There are a few more features I wish to add such as:

  • Support for retaining state across process death on Android
  • Extensions for other platforms (iOS, JS, JVM, etc)
  • Documentation

Setup

You can add this library to your project using Gradle.

Multiplatform

To add to a multiplatform project, add the dependency to the common source-set:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("dev.stateholder:core:1.0.1")

                // Optional Compose extensions
                implementation("dev.stateholder.extensions-compose:1.0.1")

                // Optional Voyager extensions
                implementation("dev.stateholder.extensions-voyager:1.0.1")

                // Optional Android-only extensions (not KMP friendly)
                implementation("dev.stateholder.extensions-android:1.0.1")
            }
        }
    }
}

Platforms

Artifact Android Desktop iOS macOS tv/watchOS Browser JS (Node)
core
extensions-compose
extensions-voyager
extensions-android

Android

For an Android only project, add the dependency to app level build.gradle.kts:

dependencies {
    // The core library
    implementation("dev.stateholder:core:1.0.1")

    // Optional Compose extensions
    implementation("dev.stateholder:extensions-compose:1.0.1")

    // Optional Voyager extensions
    implementation("dev.stateholder.extensions-voyager:1.0.1")

    // Optional Android extensions
    implementation("dev.stateholder:extensions-android:1.0.1")
}

Version Catalog

[versions]
stateholder = "1.0.1"

[libraries]
stateholder-core = { module = "dev.stateholder:core", version.ref = "stateholder" }
stateholder-extensions-compose = { module = "dev.stateholder:extensions-compose", version.ref = "stateholder" }
stateholder-extensions-android = { module = "dev.stateholder:extensions-android", version.ref = "stateholder" }
stateholder-extensions-voyager = { module = "dev.stateholder:extensions-voyager", version.ref = "stateholder" }

Usage

The :core artifact provides the following interfaces:

  • StateHolder
    • Contains the state and provides methods for updating it.
  • StateOwner
    • Exposes a StateFlow<State> to consumers.
  • StateProvider
    • Wrapper around Any that provides state to a StateHolder.

Creating a StateHolder

WIP

Updating State

WIP

Consuming State

WIP

Android Extensions

WIP

License

See LICENSE for more information.