feat: introduce SimpleRedisCache for Redis-backed caching

Add `SimpleRedisCache` to support Redis-backed caching with JSON serialization, configurable TTLs, and coroutine-based methods. Extend `RedisApi` with helper functions to streamline cache creation using reified or explicit serializers.

Author: twisti-dev

src/main/kotlin/dev/slne/surf/redis/RedisApi.kt

@@ -1,6 +1,7 @@
 package dev.slne.surf.redis
 
 import dev.slne.surf.redis.RedisApi.Companion.create
+import dev.slne.surf.redis.cache.SimpleRedisCache
 import dev.slne.surf.redis.config.InternalConfig
 import dev.slne.surf.redis.event.RedisEvent
 import dev.slne.surf.redis.event.RedisEventBus
@@ -399,4 +400,46 @@ class RedisApi private constructor(
         syncStructures.add(structure)
         return structure
     }
+
+    /**
+     * Create a [SimpleRedisCache] for the given `namespace` using an automatically derived
+     * serializer for value type `V`.
+     *
+     * This inline variant uses a reified type parameter `V`, allowing the appropriate
+     * `KSerializer<V>` to be obtained via `serializer()`.
+     *
+     * @param namespace Prefix placed before each Redis key.
+     * @param ttl Time-to-live for cache entries as a [kotlin.time.Duration].
+     * @param keyToString Function that converts a key of type `K` to its string representation.
+     *                    Defaults to `toString()`.
+     * @return A new [SimpleRedisCache] instance backed by this [RedisApi].
+     * @see SimpleRedisCache
+     */
+    inline fun <K : Any, reified V : Any> createSimpleCache(
+        namespace: String,
+        ttl: Duration,
+        noinline keyToString: (K) -> String = { it.toString() }
+    ): SimpleRedisCache<K, V> = createSimpleCache(namespace, serializer(), ttl, keyToString)
+
+    /**
+     * Create a [SimpleRedisCache] for the given `namespace` using the provided [KSerializer].
+     *
+     * This variant allows an explicit serializer for the value type `V` to be supplied.
+     *
+     * @param namespace Prefix placed before each Redis key.
+     * @param serializer A [KSerializer] for the value type `V` used for JSON (de-)serialization.
+     * @param ttl Time-to-live for cache entries as a [kotlin.time.Duration].
+     * @param keyToString Function that converts a key of type `K` to its string representation.
+     *                    Defaults to `toString()`.
+     * @return A new [SimpleRedisCache] instance backed by this [RedisApi].
+     * @see SimpleRedisCache
+     */
+    fun <K : Any, V : Any> createSimpleCache(
+        namespace: String,
+        serializer: KSerializer<V>,
+        ttl: Duration,
+        keyToString: (K) -> String = { it.toString() }
+    ): SimpleRedisCache<K, V> {
+        return SimpleRedisCache(namespace, serializer, keyToString, ttl, this)
+    }
 }

src/main/kotlin/dev/slne/surf/redis/cache/SimpleRedisCache.kt

@@ -0,0 +1,140 @@
+package dev.slne.surf.redis.cache
+
+import dev.slne.surf.redis.RedisApi
+import kotlinx.coroutines.reactive.awaitFirstOrNull
+import kotlinx.coroutines.reactive.awaitSingle
+import kotlinx.serialization.KSerializer
+import kotlin.time.Duration
+
+/**
+ * A simple Redis-backed cache for values of type [V] parameterized by key type [K].
+ *
+ * Values are stored as JSON under keys formatted as `<namespace>:<key>`. A configurable
+ * TTL (time-to-live) is applied to each entry. `null` values can optionally be cached
+ * using a sentinel marker.
+ *
+ * This class uses the reactive Redis commands exposed by [RedisApi] and is intended
+ * for coroutine-based usage (suspending methods).
+ *
+ * @param namespace String prefix that is prepended to each Redis key.
+ * @param serializer [KSerializer] used to (de-)serialize values of type [V] to/from JSON.
+ * @param keyToString Function that converts a key of type `K` to its String representation.
+ *                    Default is `toString()`.
+ * @param ttl Time-to-live for cache entries.
+ * @param api Instance of [RedisApi] used to access Redis.
+ */
+class SimpleRedisCache<K : Any, V : Any> internal constructor(
+    private val namespace: String,
+    private val serializer: KSerializer<V>,
+    private val keyToString: (K) -> String = { it.toString() },
+    private val ttl: Duration,
+    private val api: RedisApi
+) {
+    private companion object {
+        private const val NULL_MARKER = "__NULL__"
+    }
+
+    private val commands get() = api.connection.reactive()
+    private fun redisKey(key: K): String = "$namespace:${keyToString(key)}"
+
+    /**
+     * Retrieve a value from the cache.
+     *
+     * Returns `null` if no entry exists or if a cached `null` marker is present.
+     *
+     * @param key The cache key.
+     * @return The cached value of type [V], or `null` if absent or explicitly cached as `null`.
+     */
+    suspend fun getCached(key: K): V? {
+        val raw = commands.get(redisKey(key)).awaitFirstOrNull() ?: return null
+
+        if (raw == NULL_MARKER) {
+            return null
+        }
+
+        return api.json.decodeFromString(serializer, raw)
+    }
+
+    /**
+     * Store a value in the cache.
+     *
+     * The value is serialized to JSON using the provided [KSerializer] and stored with
+     * the configured TTL.
+     *
+     * @param key The cache key.
+     * @param value The value to store.
+     */
+    suspend fun put(key: K, value: V) {
+        putRaw(key, api.json.encodeToString(serializer, value))
+    }
+
+    /**
+     * Internal helper to store already serialized data or sentinel markers.
+     *
+     * @param key The cache key.
+     * @param raw The raw string to store (JSON or sentinel marker).
+     */
+    private suspend fun putRaw(key: K, raw: String) {
+        val redisKey = redisKey(key)
+
+        commands.psetex(
+            redisKey,
+            ttl.inWholeMilliseconds,
+            raw
+        ).awaitSingle()
+    }
+
+    /**
+     * Return the cached value or load it if absent.
+     *
+     * If no entry exists, the provided suspending `loader` is invoked, the result is cached
+     * and then returned.
+     *
+     * @param key The cache key.
+     * @param loader Suspended lambda to load the value if it is not present in the cache.
+     * @return The existing or newly loaded value.
+     */
+    suspend fun cachedOrLoad(key: K, loader: suspend () -> V): V {
+        getCached(key)?.let { return it }
+        val loaded = loader()
+        put(key, loaded)
+        return loaded
+    }
+
+    /**
+     * Return the cached value or load it if absent (nullable variant).
+     *
+     * If the loader returns `null`, the `cacheNull` flag controls whether a sentinel
+     * marker is stored so subsequent calls do not trigger the loader again.
+     *
+     * @param key The cache key.
+     * @param cacheNull If `true`, `null` results are cached using a sentinel marker.
+     * @param loader Suspended lambda to load the nullable value if it is not present.
+     * @return The existing or newly loaded value, or `null`.
+     */
+    suspend fun cachedOrLoadNullable(
+        key: K,
+        cacheNull: Boolean = false,
+        loader: suspend () -> V?
+    ): V? {
+        getCached(key)?.let { return it }
+
+        val loaded = loader()
+        when {
+            loaded != null -> put(key, loaded)
+            cacheNull -> putRaw(key, NULL_MARKER)
+        }
+
+        return loaded
+    }
+
+    /**
+     * Remove an entry from the cache.
+     *
+     * @param key The cache key to remove.
+     * @return The number of keys removed (typically 0 or 1).
+     */
+    suspend fun invalidate(key: K): Long {
+        return commands.del(redisKey(key)).awaitSingle()
+    }
+}