sema-cache 0.1.0

API reference · 10 exports

Source declarations and literal docstrings from this release. Package code was not executed.

cache/clear!

(cache/clear! c)
Remove every entry. The :hits/:misses/:evictions counters are preserved; :size drops to 0. Returns nil.

Source: package.sema:170

cache/contains?

(cache/contains? c k)
Return #t if k has a live (non-expired) entry, #f otherwise. Does not touch LRU recency and does not count toward :hits/:misses.

Source: package.sema:159

cache/evict!

(cache/evict! c k)
Remove k from the cache. Returns #t if it was present, #f otherwise. Manual eviction does not count toward the :evictions stat (which tracks capacity- and TTL-driven evictions only).

Source: package.sema:164

cache/get

(cache/get c k . default)
Return the cached value for k, or default (nil) on a miss. A hit counts toward :hits and refreshes LRU recency; a miss — including an expired entry — counts toward :misses. nil values are cacheable, so a nil return is ambiguous: use cache/contains? or a sentinel default to distinguish.

Source: package.sema:131

cache/get-or

(cache/get-or c k thunk)
Return the cached value for k, or run thunk, cache its result, and return it. A hit refreshes LRU recency and never calls thunk — a cached nil is a hit too (stored entries are distinguished from misses internally, not by value). A miss runs thunk exactly once and stores the result, evicting if full.

Source: package.sema:141

cache/kv-cache

(cache/kv-cache name path . opts)
Open a persistent cache backed by the stdlib kv store (a JSON file at path). name is the process-local kv handle; entries survive across runs in the file. Keys must be strings. Values must round-trip through JSON: keywords become strings, string map keys come back as keywords, NaN/Infinity floats become nil — cache only JSON-representable data. Options: :ttl-ms (nil = no expiry), :clock-fn (for testing; defaults to time-ms). There is no :max-size/:policy — the kv file has no recency index and every write rewrites the whole file, so capacity eviction belongs in an in-memory cache/new, not here. Returns a handle usable with every cache/* function; the :hits/:misses/:evictions counters are per-process and reset on each open.

Source: package.sema:206

cache/memoize

(cache/memoize f . opts)
Return a memoized version of f backed by an internal cache/new. The cache key is the full argument list (equal?-based), so multi-arg and variadic functions work; (m 1 2) and (m 2 1) are distinct keys. Accepts the same options map as cache/new, plus :cache — a pre-built handle to use instead, which lets you inspect cache/stats or evict entries from outside.

Source: package.sema:183

cache/new

(cache/new . opts)
Create an in-memory cache handle. Options: :max-size (1024) entries before eviction, :ttl-ms (nil = no expiry) milliseconds after write before an entry expires, :policy :lru (default, evicts the least-recently-used entry) or :fifo (evicts the oldest insertion; re-putting a key counts as re-insertion), :clock-fn (for testing; defaults to time-ms). Expired entries are evicted lazily on access and never count as hits. Keys are compared with equal?, so lists, strings, and maps all work as keys.

Source: package.sema:52

cache/put!

(cache/put! c k v)
Store v under k, evicting per the cache's policy if it is full. Overwriting an existing key never evicts; it refreshes the entry's TTL clock, LRU recency, and (for :fifo) its insertion order. Returns nil.

Source: package.sema:153

cache/stats

(cache/stats c)
Return {:hits n :misses n :evictions n :size n} for the cache.

Source: package.sema:175