Shelf

Key/value object store for Kotlin. Persist any serializable object. Multiplatform compatible - JVM, Android, JS, Native, iOS.

Basic usage

Initialize a shelf

val shelf = Shelf(FileStorage(applicationContext.cacheDir), MoshiSerializer())

Store an object instance

data class Thing(val id : Int, val name : String) //my custom type

shelf.item("thing").put(Thing(1, "thing 1"))

Get a previously stored item

val thing = shelf.item("thing").get<Thing>()

print(thing.name) //prints "thing 1"

Store and get typed lists

shelf.item("things").put(listOf(Thing(...), Thing(...))
val things = shelf.item("things").getList<Thing>()

Get a previously stored item from disk unless it is older than 60 seconds

fun newListOfThings() : List<Thing> = ...

fun getListOfThings() =
    shelf.item("things")
        .apply { if (olderThan(60)) put(newListOfThings()) }
        .getList<Thing>()

Remove an item

shelf.item("thing").remove()

Remove all items

shelf.clear()

Remove only items older than 60 seconds

shelf.all().filter { it.olderThan(60) }.forEach { it.remove() }

Serialization

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 and a GsonSerializer for Gson.

Storage

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

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.toddway.shelf:Shelf:x.y.z'
}

For library developers

Build checks

The following command runs all configured tests and code analyzers. The output is a summary of results with a link to view HTML reports in a browser

./gradlew checks

Publishing

This library now publishes to Sonatype/Maven Central using the gradle-maven-publish-plugin.
It was previously published to Bintray/JCenter until that service was retired. To publish a new version, update the VERSION_NAME in gradle.properties, then run:

./gradlew publish --no-daemon --no-parallel
./gradlew closeAndReleaseRepository

License

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.