Key-value storage

Use the QUESTPIE key-value service for caches, TTL-backed data, namespaces, and tag invalidation while keeping durable application state in collections.

The key-value service provides a small cache-oriented API on ctx.kv and app.kv. Application code uses one contract while an adapter selects in-memory, Redis, Cloudflare KV, or a custom backend.

When to use KV

KV fits derived or short-lived data:

cached API responses,
feature configuration,
rate-limit buckets,
expiring verification state,
rendered fragments invalidated by tags.

Collections and globals remain the durable source of truth for relational data, workflows, access rules, and records that require transactional updates.

Core API

await ctx.kv.set("weather:bratislava", forecast, 300);

const cached = await ctx.kv.get<Forecast>("weather:bratislava");
const exists = await ctx.kv.has("weather:bratislava");

await ctx.kv.delete("weather:bratislava");
await ctx.kv.clear();

TTL values use seconds. get returns null after expiry or when the key is absent.

Namespaces

Use an adapter keyPrefix when several applications share one backend. Prefixes isolate keys and scope destructive operations such as clear().

Choose stable, readable keys that describe the owner and identity:

const key = `catalog:product:${productId}:summary`;

Tag invalidation

Built-in adapters support optional tag methods for invalidating groups of related keys:

await adapter.setWithTags?.(
	`page:/posts/${slug}`,
	html,
	[`post:${postId}`],
	3600,
);

await adapter.invalidateByTag?.(`post:${postId}`);

Keep a reference to the configured adapter when application code needs tag capabilities. The core KVService stays focused on get, set, has, delete, and clear.

Consistency

Backend semantics matter. In-memory state is process-local. Redis provides shared state with immediate reads. Cloudflare KV is globally distributed and eventually consistent.

Pick the backend from the consistency and durability requirements of the cached value, then keep the application API unchanged.

Choose a backend

See KV adapters for Redis clients, Cloudflare bindings, prefixes, tag indexes, clearing behavior, and custom adapter contracts.

Services, how ctx.kv enters application context.
KV adapters, backend configuration and capabilities.
Hooks, invalidate derived data after committed writes.