Skip to main content

kv

@rtorcato/cf-common/kv wraps a KVNamespace binding as a typed store. Values go in and come out as JSON, so you work with objects instead of strings.

import { createKvStore } from '@rtorcato/cf-common/kv'
import { getBinding } from '@rtorcato/cf-common/env'
import { CloudflareError } from '@rtorcato/cf-common/errors'

interface Session {
userId: string
createdAt: string
}

const sessions = createKvStore<Session>(getBinding<KVNamespace>(env, 'SESSIONS'))

Read and write​

await sessions.put(id, { userId: 'u_42', createdAt: new Date().toISOString() })

const session = await sessions.get(id) // Session | null
if (!session) throw new CloudflareError('Session not found', { status: 404 })

await sessions.delete(id)

get returns null for a missing key, never undefined.

Expiry and metadata​

// gone in an hour
await sessions.put(id, session, { ttl: 3600 })

// gone at a fixed time (unix seconds)
await sessions.put(id, session, { expiration: Math.floor(Date.now() / 1000) + 86_400 })

// metadata rides along with the key and comes back from list()
await sessions.put(id, session, { metadata: { userId: session.userId } })

ttl maps to KV's expirationTtl, which has a 60-second minimum.

List by prefix​

let cursor: string | undefined
do {
const page = await sessions.list({ prefix: 'u_42:', cursor })
for (const { name, metadata } of page.keys) {
// ...
}
cursor = page.list_complete ? undefined : page.cursor
} while (cursor)

list passes straight through to the binding, so it takes the same options and returns the same shape.

When the value isn't JSON​

If a key holds something that isn't valid JSON, written by another tool for example, get throws a CloudflareError with code KV_PARSE_FAILED. Under defineFetch, that becomes a 500. See errors for how to catch it.

Good to know​

  • KV is eventually consistent. A write can take up to about 60 seconds to reach other locations, so use it for caches, sessions and config, not counters.
  • One store wraps one namespace. Create one per binding.

For a full walkthrough, see the KV cache example. See the kv API reference for every option.