Stacks Cache

Use @stacksjs/cache for cache-aside reads, explicit TTLs and invalidation.
Read config/cache.ts and the selected factory before assuming shared state.

API and TTL

import { cache } from '@stacksjs/cache'

await cache.set('product:42', { name: 'Widget' }, 60)
const product = await cache.get<{ name: string }>('product:42')
const products = await cache.mget<{ name: string }>(['product:42', 'product:43'])
// mget returns a record keyed by cache key, not an array.

• TTL is in seconds. Zero means forever; omitted TTL uses the factory's
  stdTTL, which defaults to zero. The exported cache/memory singleton is a
  memory instance with no default expiry. Config's ttl value does not silently
  turn that singleton into a configured Redis instance.
• setForever stores without expiry; getTtl reads remaining TTL and
  ttl(key, seconds) updates it. Missing values are undefined.
• mset([{ key, value, ttl? }]) writes entries. del(keyOrKeys) and
  deleteMany(keys) return counts; remove(key) returns void.
• has/missing/take, keys(pattern?), getStats,
  clear/flush and close/disconnect provide the remaining facade API.
  Consult the driver before relying on take for a distributed atomic claim.

Cache-aside and concurrent misses

getOrSet(key, fetcher, ttl?) computes and stores only on a miss.
remember(key, ttl, callback) is its Laravel-style argument order;
rememberForever(key, callback) uses TTL zero.

Concurrent misses share a promise within one StacksCache instance. Its bounded
inflight timeout rejects every joined caller and frees that slot for retry.
The underlying fetcher continues running after timeout; this is not cancellation
or a lock shared across worker processes. For a distributed lock, inspect the
re-exported CacheLock contract and selected driver separately.

Drivers

createMemoryCache(options?) accepts stdTTL, checkPeriod, maxKeys, useClones
and prefix. Clone-on-read/write is enabled by default.
createRedisCache(options?) accepts URL or host/port/credentials/database/TLS
plus TTL/prefix options. createSingleStoreCache(options?) exposes the
experimental SQL-backed cache. createCache(driver, options?) selects one
of memory, redis or singlestore.

The cache export is the same memory instance as memory. Use an explicit
Redis instance for application data that must be shared across processes.
The capability registry proves memory and a versioned Redis core/TTL contract;
TLS/authenticated Redis deployments need separate provider evidence. SingleStore
has no dedicated service conformance matrix. Source:
storage/framework/core/config/src/capabilities.ts.

Tag invalidation and advanced patterns

StacksCache.tags(['products', 'tenant-7']) creates a TaggedCache supporting
put/set/setForever, remember/rememberForever, get/has and flush. Its tag index
uses the same backend; process persistence depends on that backend. Tags label
shared keys rather than granting tenant authorization. Construct an explicit
tenant key/prefix as well when isolation matters.

The package also re-exports CacheAsidePattern, MultiLevelPattern,
RefreshAheadPattern, WriteThroughPattern, BatchOperations, CacheInvalidation,
CacheLock, CircuitBreaker, memoize and RateLimiter from ts-cache. Read the
installed upstream types before using these advanced classes; their signatures
are distinct from StacksCache and auth's RateLimiter.

Source and verification

storage/framework/core/cache/src/drivers/index.ts is the facade/factory
contract. drivers/singlestore.ts owns the experimental backend.
Retained tests: ttl.test.ts, getorset-timeout.test.ts,
tagged-flush-race.test.ts, redis-contract.test.ts and
cache-factory.test.ts under core/cache/tests/.

Representation-aware keys

cacheKey(namespace, dependencies) creates a deterministic key from named
primitive dependencies. Include owner/tenant scope, content version and every
setting affecting the result (for example privacy, locale or theme). Property
order does not change it; delimiter-containing strings cannot collide. Null
and undefined remain distinct. This constructs identity; it does not observe
settings, grant authorization or invalidate already issued public URLs.
The narrow @stacksjs/cache/key entry is pure and browser-bundleable.