@vercel/kv2 (Under Development)

A type-safe key-value store backed by Vercel Blob with edge caching and copy-on-write branch isolation.

Installation

npm install @vercel/kv2
# or
pnpm add @vercel/kv2

Quick Start

import { createKV } from "@vercel/kv2";

const kv = createKV({ prefix: "myapp/" });

interface User {
  name: string;
  email: string;
}

const users = kv.getStore<User>("users/");

await users.set("alice", { name: "Alice", email: "[email protected]" });

const result = await users.get("alice");
if (result.exists) {
  console.log((await result.value).name); // "Alice"
}

// Or use getValue() for a simpler read (returns undefined if not found)
const user = await users.getValue("alice");
console.log(user?.name); // "Alice"

// Delete, iterate keys, entries, getMany — see docs
await users.delete("alice");

Features

| Feature | Description | Docs | |---------|-------------|------| | Typed Stores | Type-safe sub-stores with automatic key prefixing | Typed Stores | | Iteration | entries() and getMany() with bounded concurrency | Iterating and Pagination | | Pagination | Cursor-based pagination for HTTP APIs | Iterating and Pagination | | Optimistic Locking | Version-based conflict detection and retry | Optimistic Locking | | Metadata | Typed per-entry metadata, available without loading values | Metadata | | Schema & Trees | Hierarchical data with batched tree loading | Schema and Trees | | Indexes | Secondary indexes with unique constraints | Indexes | | Edge Caching | Write-through cache with tag invalidation | Caching | | Streaming | Large values streamed without buffering | Streaming | | Copy-on-Write | Preview branches inherit from production | Copy-on-Write Branches | | CLI Explorer | Interactive KV store explorer for debugging | CLI |

Documentation

1. Getting Started — installation, quick start, environment setup
2. Iterating and Pagination — keys, entries, getMany, cursor pagination
3. Typed Stores — getStore, key prefixing, nested stores
4. Optimistic Locking — versions, conflict detection, retry patterns
5. Metadata — typed metadata, filtering without loading values
6. Schema and Trees — defineSchema, tree loading, key builders
7. Indexes — secondary indexes, unique constraints, reindexing
8. Caching — cache hierarchy, TTL, custom cache
9. Streaming — binary format, large values, streaming reads/writes
10. Copy-on-Write Branches — branch isolation, upstream config
11. Testing and Tracing — unit testing, tracers, stats
12. CLI — interactive KV store explorer
13. API Reference — full interface and options documentation

Environment Variables

BLOB_READ_WRITE_TOKEN=vercel_blob_...

See Getting Started for full environment setup.

License

ISC