@vercel/kv2

@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: "[e-mail]" });

const result = await users.get("alice");
if (result.exists) {
  console.log((await result.value).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

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

Environment Variables

BLOB_READ_WRITE_TOKEN=vercel_blob_...

See Getting Started for full environment setup.

Testing

pnpm test              # Unit tests (fake blob store)
pnpm test:integration  # Integration tests (real Vercel Blob)

License

ISC