# sema-cache 0.1.0 — API reference

Source declarations extracted without executing package code. Signatures describe declarations, not inferred runtime behavior.

## cache/clear!

```sema
(cache/clear! c)
```

Remove every entry. The :hits/:misses/:evictions counters are preserved;
:size drops to 0. Returns nil.

[Source line 170](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L170)

## cache/contains?

```sema
(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 line 159](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L159)

## cache/evict!

```sema
(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 line 164](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L164)

## cache/get

```sema
(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 line 131](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L131)

## cache/get-or

```sema
(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 line 141](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L141)

## cache/kv-cache

```sema
(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 line 206](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L206)

## cache/memoize

```sema
(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 line 183](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L183)

## cache/new

```sema
(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 line 52](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L52)

## cache/put!

```sema
(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 line 153](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L153)

## cache/stats

```sema
(cache/stats c)
```

Return {:hits n :misses n :evictions n :size n} for the cache.

[Source line 175](https://pkg.sema-lang.com/packages/sema-cache/0.1.0/source/package.sema#L175)

---

Parser: sema-reader 1.37.0

Archive SHA-256: `a076dcd4ef3dc8ab48fbafcb5c0c38bb2d3f7159b585faf562b9b9507bdc4d01`
