class KvCacheStore
implements ICacheStore
Since 0.2.0

A cache store backed by Workers KV.

Two platform properties are worth knowing before choosing this store over a Durable Object or an origin cache:

  • Writes are eventually consistent. A set is not guaranteed visible to a read in another location immediately. KV suits read-heavy, tolerant caching, not coordination.
  • TTLs below 60 seconds are enforced by this store, not by KV. The value carries its own deadline, so a short entry reads as a miss on time even though the key survives up to a minute longer. See kv-envelope.ts.

Examples

Example 1

const cache = ctx.services.get<ICacheStore>(CAPABILITIES.CACHE);
await cache.set('user:1', user, 30); // honored at 30s despite KV's 60s floor

Constructors

KvCacheStore(
clock: CacheClock,
)
Parameters

The KV namespace binding

clock: CacheClock

Wall clock; pass IRuntimeServices

optional
options: KvCacheStoreOptions

Key prefix and default TTL

Methods

clear(): Promise<void>

Removes every key this store owns.

KV has no bulk delete on the binding, so this pages list and issues one delete per key — linear in the number of entries, and worth avoiding on a hot path.

delete(key: string): Promise<boolean>

Removes a cached value.

get<T>(key: string): Promise<T | null>

Reads a cached value.

has(key: string): Promise<boolean>

Reports whether a live entry exists.

set<T>(
key: string,
value: T,
ttlSeconds?: number
): Promise<void>

Stores a value.

Usage

import { KvCacheStore } from "cloudflare-plugin/src/index.ts";