Key-Value Store

Fast key-value storage with TTL support. Ideal for caching, sessions, and temporary state.

For store configuration, see Store.

Loading

local store = require("store")

Acquiring a Store

Get a store resource by registry ID:

local cache, err = store.get("app:cache")
if err then
    return nil, err
end

cache:set("user:123", {name = "Alice"}, 3600)
local user = cache:get("user:123")

cache:release()

Returns: Store, error

Storing Values

Store a value with optional TTL:

local cache = store.get("app:cache")

-- Simple set
cache:set("user:123:name", "Alice")

-- Set with TTL (expires in 300 seconds)
cache:set("session:abc", {user_id = 123, role = "admin"}, 300)

Returns: boolean, error

Retrieving Values

Get a value by key:

local user = cache:get("user:123")
if not user then
    -- Key not found or expired
end

Returns: any, error

Returns nil and an errors.NOT_FOUND error if the key doesn't exist or has expired.

Checking Existence

Check if a key exists without retrieving:

if cache:has("lock:" .. resource_id) then
    return nil, errors.new("CONFLICT", "Resource is locked")
end

Returns: boolean, error

Deleting Keys

Remove a key from the store:

cache:delete("session:" .. session_id)

Returns: boolean, error

Returns true if deleted, false if key didn't exist.

Reading Entry Metadata

entry returns the value together with its version — an opaque string used for optimistic concurrency:

local e, err = cache:entry("user:123")
if e then
    print(e.key, e.value, e.version)
end

Returns: Entry, error — {key: string, value: any, version: string}

Listing Keys

List entries in deterministic key order, with paging:

local page, err = cache:list({ prefix = "session:", limit = 100 })
for _, e in ipairs(page.items) do
    print(e.key, e.value)
end

-- next page
if page.has_more then
    page = cache:list({ prefix = "session:", after = page.cursor })
end

Returns: Page, error — {items: Entry[], cursor: string, has_more: boolean}

Conditional Writes

put writes a value and returns its new Entry. Options enable optimistic concurrency:

-- create only if the key does not exist
local e, err = cache:put("lock:job-1", owner, { only_if_absent = true })
if err and err:kind() == errors.ALREADY_EXISTS then
    -- someone else holds it
end

-- compare-and-set: write only if the version still matches
local cur = cache:entry("config")
local e2, err2 = cache:put("config", new_value, { if_version = cur.version })
if err2 and err2:kind() == errors.CONFLICT then
    -- a concurrent writer changed it; re-read and retry
end

only_if_absent and if_version are mutually exclusive.

Returns: Entry, error

Store Capabilities

info reports the backend and what it supports, so code can adapt to whichever store is bound:

local info = cache:info()
-- info.backend      -> one of store.backend.* (e.g. "kv.raft")
-- info.consistency  -> one of store.consistency.* (e.g. "linearizable")
-- info.durable / info.list / info.versioned / info.conditional_put / info.ttl  (booleans)

Returns: Info, error — {id, backend, consistency, durable, list, versioned, conditional_put, ttl}

Constants

if cache:info().consistency == store.consistency.LINEARIZABLE then
    -- safe to use compare-and-set
end

Store Methods

Permissions

Store operations are subject to security policy evaluation.

Errors

store.get() and all methods on the store handle (get, entry, set, put, list, has, delete, info) return structured errors (use err:kind()).

See Error Handling for working with errors.