Store
A tiny Kotlin multiplatform library that assists in saving and restoring objects to and from disk using kotlinx.coroutines, kotlinx.serialisation and okio. Inspired by RxStore
Features
-
🔒 Read-write locks; with a mutex FIFO lock -
💾 In-memory caching; read once from disk and reuse -
🕺 Multiplatform!
Adding to your project
KStore is published on Maven Central
repositories {
mavenCentral()
}
Include the dependency in commonMain
. Latest version
sourceSets {
val commonMain by getting {
implementation("io.github.xxfast:kstore:<version>")
}
}
Usage
Given that you have a @Serializable
model
@Serializable data class Pet(val name: String, val age: Int) // Any serializable
val mylo = Pet(name = "Mylo", age = 1)
Create a store
val store: KStore<Pet> = storeOf("path/to/file")
For full configuration and platform instructions, see here
Get value
Get a value once
val mylo: Pet? = store.get()
Or observe for changes
val pets: Flow<Pet?> = store.updates
Set value
store.set(mylo)
Update a value
store.update { pet: Pet? ->
pet?.copy(age = pet.age + 1)
}
Note: this maintains a single mutex lock transaction, unlike get()
and a subsequent set()
Delete/Reset value
store.delete()
You can also reset a value back to its default (if set, see here)
store.reset()
Lists
KStore provides you with some convenient extensions to manage stores that contain lists.
Create a list store
val listStore: KStore<List<Pet>> = listStoreOf("path/to/file") // same as [storeOf], but defaults to empty list
Get values
val pets: List<Cat> = store.getOrEmpty()
val pet: Cat = store.get(0)
or observe values
val pets: Flow<List<Cat>> = store.updatesOrEmpty
Add or remove elements
store.plus(cat)
store.minus(cat)
Map elements
store.map { cat -> cat.copy(cat.age = cat.age + 1) }
store.mapIndexed { index, cat -> cat.copy(cat.age = index) }
Configurations
Everything you want is in the factory method
private val store: KStore<Pet> = storeOf(
path = filePathTo("file.json"), // required
default = null, // optional
enableCache = true, // optional
serializer = Json, // optional
)
Platform configurations
Getting a path to a file is different for each platform and you will need to define how this works for each platform
expect fun filePathTo(fileName: String): String
On Android
actual fun filePathTo(fileName: String): String = "${context.filesDir.path}/$fileName"
On iOS & other Apple platforms
actual fun filePathTo(fileName: String): String = "${NSHomeDirectory()}/$fileName"
On Desktop
This depends on where you want to save your files, but generally you should save your files in a user data directory. Here i'm using harawata's appdirs to get the platform specific app dir
actual fun filePathTo(fileName: String): String {
// implementation("net.harawata:appdirs:1.2.1")
val appDir: String = AppDirsFactory.getInstance().getUserDataDir(PACKAGE_NAME, VERSION, ORGANISATION)
return "$appDir/$fileName"
}
On JS Browser
TODO
On NodeJS
TODO
Licence
Copyright 2021 Isuru Rajapakse
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.