Cache Functions - Soli MVC Documentation

Configuration

Cache connects to a SoliKV instance via environment variables or programmatic configuration:

SOLIKV_RESP_HOST - SoliKV host (default: localhost)
SOLIKV_RESP_PORT - SoliKV RESP port (default: 6380)
SOLIKV_TOKEN - Optional token for authentication
Default TTL: 3600 seconds (1 hour)
Key prefix: soli:cache: (isolates cache keys from other KV data)

# In .env file
SOLIKV_RESP_HOST=localhost
SOLIKV_RESP_PORT=6380
SOLIKV_TOKEN=my-secret-token

# Or configure programmatically
Cache.configure("my-solikv-host", "my-secret-token")

# Set default TTL
cache_config(1800)  # 30 minute default TTL

Cache Static Methods

Call methods directly on the Cache class without instantiation.

Cache.set(key, value, ttl_seconds?)

Stores a value in the cache.

key (String) - Cache key
value (Any) - Value to cache (JSON serialized)
ttl_seconds (Int, optional) - Time to live (default: 3600)

Returns: null

Cache.set("user:123", { "name": "Alice" })
Cache.set("session", data, 1800)  # 30 minute TTL

Cache.get(key)

Retrieves a value from the cache.

Returns: Any|null - Cached value or null if not found/expired

let user = Cache.get("user:123")
if user != null
    println("Cached user: " + user["name"])
end

Cache.delete(key)

Removes a value from the cache.

Returns: Bool - true if key was removed

Cache.has(key)

Checks if a key exists in the cache.

Returns: Bool

Cache.clear()

Removes all cache entries (only keys with the soli:cache: prefix).

Returns: null

Cache.clear_expired()

No-op. SoliKV handles TTL expiration automatically.

Returns: null

Cache.keys()

Returns all cache keys (prefix stripped).

Returns: Array

Cache.size()

Returns the number of entries in the cache.

Returns: Int

Cache.ttl(key)

Gets the remaining TTL for a key in seconds.

Returns: Int|null - Seconds remaining, or null if key doesn't exist

Cache.touch(key, ttl)

Sets or updates the TTL for an existing key.

Returns: Bool - true if key existed and was updated

Cache.fetch(key, ttl?) do...end

Cache-aside pattern: returns cached value on hit, or executes the block on miss, caches and returns the result.

key (String) - Cache key
ttl (Int, optional) - Time to live in seconds (default: 3600)
do...end - Block to execute on cache miss

Returns: Any - Cached value or block result

# Basic usage
let user = Cache.fetch("user:123") do
    User.find(123)
end

# With TTL (5 minutes)
let user = Cache.fetch("user:123", 300) do
    User.find(123)
end

# Without block — acts like Cache.get()
let user = Cache.fetch("user:123")

Cache.configure(host, token?)

Programmatically configure the SoliKV connection.

host (String) - SoliKV URL
token (String, optional) - Bearer token

Returns: null

Cache Instance

Create a Cache instance using cache(). All instances share the same underlying SoliKV store.

let c = cache()
c.set("key", "value")
let value = c.get("key")

Global Functions

Global cache functions are also available and share the same SoliKV store.

cache_set(key, value, ttl?)

Store a value in cache

cache_get(key)

Retrieve a value from cache

cache_delete(key)

Remove a value from cache

cache_has(key)

Check if key exists

cache_clear()

Clear all cache entries

cache_config(ttl)

Set default TTL in seconds

cache_keys()

List all cache keys

cache_size()

Get number of cache entries

cache_ttl(key)

Get remaining TTL for a key

cache_touch(key, ttl)

Update TTL for existing key

Complete Example

# Using static methods (recommended)
Cache.set("user:123", { "name": "Alice", "email": "[email protected]" })
Cache.set("session", session_data, 1800)  # 30 minute TTL

# Retrieve data
let user = Cache.get("user:123")
if user != null
    println("Cached user: " + user["name"])
end

# Check existence
if Cache.has("user:123")
    println("User still cached")
end

# Update TTL
Cache.touch("user:123", 3600)

# List keys and size
let keys = Cache.keys()
let count = Cache.size()

# Clear cache
Cache.clear()

# Global functions also work
cache_set("global_key", "value")
let value = cache_get("global_key")

Practical Example: Database Query Caching

Using Cache.fetch for concise cache-aside pattern:

# Cache-aside with Cache.fetch — one line instead of five
let user = Cache.fetch("user:" + str(user_id), 300) do
    User.find(user_id)
end

# Equivalent manual approach:
def get_user_cached(user_id)
    let cache_key = "user:" + str(user_id)
    let cached = Cache.get(cache_key)

    if cached != null
        return cached
    end

    let user = User.find(user_id)
    Cache.set(cache_key, user, 300)
    user
end