Small library for asynchronously persisting single instances of data classes with a simple API, leveraging coroutines and serialization, ensuring data integrity and non-blocking operations.
{: .float-left}
{: .float-left}
{: .float-left}
{: .float-left}
{: .float-left}
{: .float-left}
{: .float-left}
Small cross platform library for persisting single instances of kotlin data classes. It's particularly useful as a way to asynchronously persist immutable state.
val state = DashboardState(dashboardId = 777, userName = "erdo")
perSista.write(state)
perSista.read(default = state)
// or from outside a coroutine scope
perSista.write(state){ savedState -> }
perSista.read(default = state){ readState -> }
Add this gradle line to your project (you'll need mavenCentral() in your list of maven repos)
implementation("co.early.persista:persista:2.1.0")
The GPG fingerprint used to sign the maven packages is: 5B83EC7248CCAEED24076AF87D1CC9121D51BA24 see repo root for the GPG public certificate.
Construct PerSista with the folder you want your data saved to, for an android app you'll probably want to use Application.getFilesDir(). Typically you will share this single PerSista instance, just use some form of DI (manual or otherwise) to get it wherever it's needed.
val perSista = PerSista(application.filesDir)
Define your data class, mark it serializable (also don't forget to add the kotlin serialization plugin to gradle)
@Serializable
data class DashboardState(
val dashboardId: Int = 0,
val userName: String,
val drivers: List<Driver> = emptyList(),
val error: Error? = null,
@Transient val isUpdating: Boolean = false
)
@Serializable
data class Driver(
val : Int,
val : String,
val : Int,
val : Int,
val : Int
)
Save an instance like this:
val state = DashboardState(dashboardId = 777, userName = "erdo")
// from inside a coroutine scope
perSista.write(state)
// from outside a coroutine scope
perSista.write(state){ savedState ->
}
Read an instance like this:
val defaultState = DashboardState(userName = "defaultUser")
// from inside a coroutine scope
val state = perSista.read(defaultState)
// from outside a coroutine scope
perSista.read(defaultState){ readState ->
}
PerSista uses Kotlin's built in Serialization to turn data classes into json. Because it needs to accept any data class you might throw at it, it depends on typeOf() internally to work out the class type of the item
PerSista prioritizes correctness over performance, all the reads and writes are guaranteed to be done sequentially as they are performed using a coroutine dispatcher created from a single-threaded Executor (though you can override that if you want)
Persista writes the json representation of the data class to the file system, the example above would generate a file called com.example.DashBoardState with this content:
{"dashboardId":777, "userName":"erdo"}
You can browse the files that are saved on an emulator using Device Explorer in Android Studio (View -> Windows -> Device File Explorer), for an android device they will typically be in: data/data/your.app.package/files/persista
It's up to you to ensure that you only pass something which is serializable to the write method. Because typeOf() is one of those things that behaves differently depending on which kotlin platform you are running on, I've taken a conservative approach, and in the worst case scenario when using PerSista if the write() fails: nothing will happen, if the read() fails: you will receive the default value. Pass a logger in to the constructor if you want to see more detail about what happened.
If you DO want to receive exceptions (during development for instance) pass 'strictMode = true' to the constructor, in that case, the only time you still won't receive an exception when something goes wrong is when an attempted read fails because it can't find the file (that's most likely because a write was never performed in the first place).
Performance is "ok". On a 2017 Pixel XL, PerSista seems to have a setup overhead of around 400ms the first time it writes, after that a small instance of a data class takes around 2-30ms to store, but importantly none of the IO is run on the UI thread anyway so your UI won't be blocked and you won't see any jank.
PerSista has no concept of data class versioning, so if you change the definition of your data class (due to an app upgrade for instance) and kotlin serialization is no longer able to decode the old json to the new data class, you will just get your default value back.
The same advice applies here as would apply to any strategy that uses class names for serialization. The state of your data class will be saved in a file named after the data class's qualified name e.g. "foo.bar.app.DashboardState". If that data class gets obfuscated however, the qualified name could easily be renamed to something like "a.b.c.a". If you release a new version of the app, this time the qualified name could be renamed to "b.c.d.d" and PerSista will consider that a new class. Check the example app's proguard configuration if you want to prevent this behaviour (it's the same as what you are probably already doing to use ktor).
None required on Android, as long as you stick to the internal app directory: Application.getFilesDir()
If you want to unit test a class that uses PerSista, you can of course mock the perSista instance. But you can also use a real PerSista instance with a org.junit.rules.TemporaryFolder and a test dispatcher. See the unit tests in this repo for an example.
There is a complete mini example android app in this repo if you need something to copy-paste to get started.
The non-suspend APIs invoke a functional parameter when they are complete, if you are using PerSista on Android this will arrive on the main thread. For non UI kotlin platforms (which don't have a Dispatchers.Main) you should override the mainDispatcher parameter in the constructor to an available dispatcher of your choice.
Copyright 2015-2024 early.co
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this except compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
Surfaced from shared tags and platforms — no rankings paid for.