js/cache
js/cache.ts
fino:cache — expiry, invalidation, and eviction policy over fino:store.
cache(store) is the only cache constructor. Applications choose and own a
generic backing store directly; memory, SQLite, Redis, and other providers
do not need cache-specific wrapper classes.
Expiry
When a store exposes its optional expiration capability, cache writes pass
TTL to that provider. A Redis-like provider can therefore use SET PX, and
Fino does not duplicate expiry metadata or schedule external cleanup. For a
plain store, the cache records an absolute expiry and removes stale entries
lazily when they are read.
Tags and optional process-local LRU eviction remain cache policy. Values are
not serialized by this layer; they follow the backing store's value rules,
including native Uint8Array support.
import { cache, responseCache } from 'fino:cache';
import { memoryStore } from 'fino:store';
import { App } from 'fino:net/http/app';
const values = cache(memoryStore(), { maxEntries: 1_000 });
await values.set('user:1', { name: 'Ada' }, { ttlMs: 60_000 });
const app = new App().layer(responseCache(values, { ttlMs: 5_000 }));Interfaces
interface CacheClock {
Clock used by the fallback expiry policy.
Methods
now(): number
Return the current Unix timestamp in milliseconds.
interface CacheSetOptions {
Options applied when writing one cache entry.
Properties
ttlMs?: number
Milliseconds until expiry. Omit for no expiry.
tags?: string[]
Tags used by invalidateTags() to remove related entries.
interface Cache {
Small async cache interface independent of any backing provider.
The provider owns value identity and serialization. Missing and expired
entries return null; cache namespaces and tag invalidation remain isolated.
Methods
get<T = unknown>(key: string): Promise<T | null>
Read key, returning null when it is missing or expired.
set<T = unknown>(key: string, value: T, options?: CacheSetOptions): Promise<void>
Store value with optional TTL and invalidation tags.
delete(key: string): Promise<void>
Delete key. Missing keys are ignored.
invalidateTags(tags: string[]): Promise<void>
Delete entries carrying any of tags.
namespace(name: string): Cache
Return a cache view in an isolated child namespace.
interface CacheOptions {
Options for cache().
Properties
maxEntries?: number
Maximum entries retained by this process across namespace views.
clock?: CacheClock
Clock used only when the provider has no native expiry capability.
interface ResponseCacheOptions {
Options for responseCache().
Properties
ttlMs: number
TTL applied to every stored response.
methods?: string[]
HTTP methods to cache. Defaults to GET and HEAD.
statuses?: number[]
Response statuses to cache. Defaults to [200].
vary?: string[]
Request header names included in the cache key.
header?: false | string
Diagnostic header name, or false to disable it. Defaults to x-fino-cache.
Functions
function cache(store: Store, options: CacheOptions = {}): Cache
Add cache policy to a caller-owned store.
The returned cache occupies an isolated child namespace. Store lifecycle and serialization remain the caller's and provider's responsibility.
function responseCache(cache: Cache, options: ResponseCacheOptions): LayerMiddleware
Create HTTP response-cache middleware for fino:net/http/app.
Requests whose method is in methods are keyed by method, URL, and selected
request headers. Cacheable responses retain their body as Uint8Array and
are replayed without base64 conversion. Responses with Set-Cookie or
Cache-Control: no-store bypass storage.