commonMain.keep.Cache.kt Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of keep-api Show documentation

An API to help caching simple objects

There is a newer version: 3.0.13

@file:JsExport
@file:Suppress("NON_EXPORTABLE_TYPE")

package keep

import keep.exceptions.CacheLoadException
import keep.exceptions.CacheSaveException
import kotlinx.serialization.KSerializer
import koncurrent.Later
import koncurrent.later.then
import koncurrent.later.andThen
import koncurrent.later.andZip
import koncurrent.later.zip
import koncurrent.later.catch
import kotlinx.JsExport

/**
 * An interface to be able to [Cache] different objects
 */
interface Cache {
    /**
     * Should return the set of all available keys in the [Cache]
     */
    fun keys(): Later>

    /**
     * Should return the size of the [Cache] which should ideally equal the number of [keys]
     */
    fun size(): Later

    /**
     * Clears the entire [Cache]
     */
    fun clear(): Later

    /**
     * Removes a [key] from the [Cache]
     * @return the removed object or null if nothing was removed
     */
    fun remove(key: String): Later

    /**
     * Create a [Cache] that is further namespaced with [namespace]
     * @param namespace the namespace to further namespace the [Cache] with
     * @return [Cache]
     */
    fun namespaced(namespace: String): Cache

    /**
     * Save object [T] on to the [Cache] with a [key] and its serializer [serializer]
     *
     * @return a [Later] that
     * - on success: resolves the saved object as it was cached
     * - on failure: rejects with a [CacheSaveException]
     */
    fun  save(key: String, obj: T, serializer: KSerializer): Later

    /**
     * Load object [T] from the [Cache], that was saved with a [key] and its serializer [serializer]
     *
     * @return a [Later] that
     * - on success: resolves to the cached object
     * - on failure: rejects with a [CacheLoadException]
     */
    fun  load(key: String, serializer: KSerializer): Later
}