Key/value object store for Kotlin. Persist any serializable object. Multiplatform compatible - JVM, Android, JS, Native, iOS.
Store an object
val shelf = Shelf(FileStorage(File(...)), KotlinxSerializer())
shelf.item("thing").put(Thing(...))
Get it
val thing = shelf.item("thing").get<Thing>()
Get typed lists
shelf.item("things").put(listOf(Thing(...), Thing(...))
val things = shelf.item("things").getList<Thing>()
If data is older than 60 seconds, load new
fun newListOfThings() : List<Thing> = ...
fun getListOfThings() =
shelf.item("things")
.apply { if (olderThan(60)) put(newListOfThings()) }
.getList<Thing>()
Remove it
shelf.item("thing").remove()
Remove all
shelf.clear()
Remove only items older than 60 seconds
shelf.all().filter { it.olderThan(60) }.forEach { it.remove() }
The default serializer for Shelf depends on the Kotlinx Serialization library.
Primitive type classes work automatically.
For custom classes, annotate with @Serializable
, and register with Shelf:
@Serializable
data class Thing(...)
@Serializable
data class Whatever(...)
shelf.serializer = KotlinxSerializer().apply {
register(Thing.serializer())
register(Whatever.serializer())
}
For JVM targets, there is also a MoshiSerializer
for Moshi.
The DiskStorage
class depends on delegates for each platform.
By inspecting the code, you can see that
for Kotlin/Native targets, the delegate is NSUserDefaults
,
for Kotlin/JS targets, it is LocalStorage
,
and for Kotlin/JVM it is File("/tmp")
.
Native and JS platforms should work without configuration.
For JVM environments, you should choose an appropriate location on the file system to use.
For example, on Android, this can be acquired from Context.getCacheDir()
.
val shelf = Shelf(FileStorage(context.getCacheDir()))
You can also create your own own implementations of Shelf.Storage
or Shelf.Serializer
.
val shelf = Shelf(MyOwnStorage(...), MyOwnSerializer(...))
repositories {
jcenter()
}
Current Version
$shelf_version = 2.0.4
Common multiplatform source set
dependencies {
implementation 'com.toddway.shelf:shelf:$shelf_version'
}
iOS/Native source set
dependencies {
implementation 'com.toddway.shelf:shelf-ios:$shelf_version'
}
Android/JVM source set
dependencies {
implementation 'com.toddway.shelf:shelf-jvm:$shelf_version'
}
Javascript source set
dependencies {
implementation 'com.toddway.shelf:shelf-js:$shelf_version'
}
The library has common tests that can be run (and should pass) on a local JVM:
./gradlew jvmTest
a local iOS simulator:
./gradlew iosTest
and a local web browser:
./gradlew karma-run-single
Copyright 2016-Present Todd Way
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.