@vercel/kv2 0.0.1

package/docs/cli.md

@@ -0,0 +1,123 @@
+[Home](../README.md) | [Previous: Testing and Tracing](testing-and-tracing.md) | [Next: API Reference](api-reference.md)
+
+# CLI Explorer
+
+An interactive command-line tool for exploring and manipulating KV stores. Read-only by default; pass `--allow-writes` to enable mutations.
+
+## Installation
+
+The package exposes a `kv2` binary. After installing:
+
+```bash
+npx kv2 help
+```
+
+Or add it as a dev dependency and run via your package manager:
+
+```bash
+npm install -D @vercel/kv2
+npx kv2 keys
+```
+
+## Usage
+
+```bash
+kv2 [options] [command] [args...]
+kv2 [options]                        # interactive REPL
+```
+
+```bash
+# One-shot commands
+kv2 keys                                # List keys (first 100)
+kv2 keys users/                         # List keys under a prefix
+kv2 --all keys                          # List all keys
+kv2 --limit 500 keys                    # List first 500 keys
+kv2 get users/alice                     # Print value as JSON to stdout
+kv2 --verbose get users/alice           # Also show version/metadata on stderr
+kv2 --allow-writes set foo '{"a":1}'    # Set a value
+kv2 --allow-writes del foo              # Delete a key
+
+# Interactive REPL
+kv2                                     # Launches kv2> prompt
+```
+
+## Commands
+
+| Command | Description | Writes? |
+|---------|-------------|---------|
+| `keys [prefix]` | List keys, one per line | No |
+| `get <key>` | Print JSON value to stdout | No |
+| `set <key> <json> [metadata-json]` | Set a value | Yes |
+| `del <key>` | Delete a key | Yes |
+| `help` | Show usage | No |
+
+Write commands (`set`, `del`) are rejected unless `--allow-writes` is passed.
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--prefix <prefix>` | Key prefix passed to `createKV()` | _(none)_ |
+| `--env <env>` | Override `VERCEL_ENV` | `development` |
+| `--branch <branch>` | Override `VERCEL_GIT_COMMIT_REF` | `local` |
+| `--limit <n>` | Max keys to list | `100` |
+| `--all` | List all keys (no limit) | _(disabled)_ |
+| `--allow-writes` | Enable write operations | _(disabled)_ |
+| `--verbose` | Show metadata and version on `get` | _(disabled)_ |
+
+## Prefix matters
+
+The blob path structure is `cached-kv/{env}/{branch}/{prefix}{key}.value`. If your app uses `createKV({ prefix: "myapp/" })`, the CLI must use `--prefix myapp/` to see those keys:
+
+```bash
+kv2 --prefix myapp/ keys
+kv2 --prefix myapp/ get users/alice
+```
+
+## stdout / stderr contract
+
+In one-shot mode, stdout contains only data (for piping) and stderr contains everything else (status, colors, errors).
+
+| Command | stdout | stderr |
+|---------|--------|--------|
+| `keys` | one key per line | `N key(s)` count |
+| `get` | JSON value (pretty-printed) | key, version, metadata (with `--verbose`) |
+| `get` (not found) | _(nothing)_ | "Key not found: X" |
+| `set` | _(nothing)_ | "Set X (version: ...)" |
+| `del` | _(nothing)_ | "Deleted X" |
+
+This enables piping:
+
+```bash
+kv2 keys | wc -l                          # Count keys
+kv2 get users/alice | jq .name            # Extract field
+kv2 keys | xargs -I{} kv2 get {}          # Dump all values
+```
+
+## Interactive REPL
+
+Running `kv2` without a command launches an interactive REPL. On startup it prints the current context:
+
+```
+KV CLI Explorer
+  env:     development
+  branch:  local
+  prefix:  (none)
+  writes:  disabled
+  Type "help" for commands, Ctrl+C to exit.
+
+kv2> keys
+kv2> get users/alice
+kv2> exit
+```
+
+The same commands work in REPL mode. Type `exit`, `quit`, or press Ctrl+C to leave.
+
+## Environment
+
+The CLI automatically loads `.env.local` via dotenv (if installed). You can also export `BLOB_READ_WRITE_TOKEN` directly:
+
+```bash
+export BLOB_READ_WRITE_TOKEN=vercel_blob_...
+kv2 keys
+```

package/docs/copy-on-write-branches.md

@@ -0,0 +1,98 @@
+[Home](../README.md) | [Previous: Streaming](streaming.md) | [Next: Testing and Tracing](testing-and-tracing.md)
+
+# Copy-on-Write Branches
+
+## The Problem
+
+Most apps store data alongside code, but deployment pipelines treat them very differently. Code is branched, reviewed, and merged — you can test a feature branch in isolation without touching production. Data usually isn't: your preview deployment either points at production data (risky — a bug can corrupt it) or starts with an empty database (useless — you can't test real workflows).
+
+## How Copy-on-Write Solves This
+
+Copy-on-write gives every preview branch a virtual fork of production data — without copying anything. On a preview branch:
+
+- **Reads** check the branch's local storage first, then transparently fall back to production
+- **Writes** go only to local storage — production is never modified
+- **Deletes** create a tombstone so the key stops falling back to production
+
+The result: your preview deployment sees the full production dataset, but any changes it makes are isolated. When you merge, the branch's writes are discarded — the code change is what matters, not the test data.
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+// On preview branch "feature-x":
+const kv = createKV({ prefix: "app/" });
+
+// Read falls back to production/main if not found locally
+const user = await kv.get("users/alice"); // Found in production
+
+// Write only affects this branch
+await kv.set("users/alice", { name: "Alice Updated" });
+
+// Delete creates tombstone (won't fall back to production)
+await kv.delete("users/bob");
+```
+
+## When to Use This
+
+Copy-on-write is most valuable when:
+
+- **Preview deployments need realistic data** — test a new dashboard layout against actual content, not seed data
+- **Multiple developers work in parallel** — each branch gets its own isolated overlay, no cross-contamination
+- **You want safe data migrations** — test a schema change against production data in a preview branch before merging
+- **Staging environments** — create a long-lived branch that mirrors production for QA
+
+It's less useful when your data is purely ephemeral (e.g. session tokens) or when each environment genuinely needs its own independent dataset.
+
+## Automatic Environment Detection
+
+`createKV()` detects the environment from Vercel's built-in variables and sets up upstream automatically — no configuration needed for the common case:
+
+| Environment | Behavior |
+|-------------|----------|
+| `production` + `main` | Direct KV2, no upstream (it's the root) |
+| `preview` branch | UpstreamKV with fallback to same env + `main` |
+| Same env and branch as upstream | Direct KV2, no upstream (avoid self-reference) |
+
+## Configuring Upstream
+
+### Custom Upstream
+
+Point a branch at a specific upstream environment and branch:
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+const kv = createKV({
+  prefix: "app/",
+  upstream: { env: "production", branch: "main" },
+});
+```
+
+### Disabled Upstream
+
+For fully isolated environments with no fallback:
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+const kv = createKV({
+  prefix: "app/",
+  upstream: null, // no fallback — isolated environment
+});
+```
+
+## The Manifest
+
+`UpstreamKV` uses a `ManifestLog` to track which keys have been written or deleted locally. On read, it checks the manifest to decide whether to read from local storage or fall back to upstream.
+
+The manifest is stored in a separate blob namespace (`_manifest/{env}/{branch}/`) to avoid interfering with data key listings.
+
+## Branch Name Encoding
+
+Branch names are URL-encoded and lowercased to be filesystem-safe. Long branch names (> 64 chars) are truncated with a hash suffix to preserve uniqueness:
+
+```
+feature/foo      → feature%2Ffoo
+feature-foo      → feature-foo
+very-long-name…  → very-long-name…-<8-char-hash>
+```

package/docs/getting-started.md

@@ -0,0 +1,61 @@
+[Home](../README.md) | [Next: Iterating and Pagination](iterating-and-pagination.md)
+
+# Getting Started
+
+## Installation
+
+```bash
+npm install @vercel/kv2
+# or
+pnpm add @vercel/kv2
+```
+
+## Quick Start
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+// Creates KV with automatic upstream fallback to production/main
+const kv = createKV({ prefix: "myapp/" });
+
+interface User {
+  name: string;
+  email: string;
+}
+
+// Type-safe sub-store
+const users = kv.getStore<User>("users/");
+
+await users.set("alice", { name: "Alice", email: "alice@example.com" });
+
+const result = await users.get("alice");
+if (result.exists) {
+  console.log((await result.value).name); // "Alice"
+}
+```
+
+## Environment Setup
+
+`@vercel/kv2` requires a Vercel Blob token and uses environment variables for automatic branch detection:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BLOB_READ_WRITE_TOKEN` | Yes | Vercel Blob access token |
+| `VERCEL_ENV` | Auto | Set by Vercel (`production`, `preview`, `development`) |
+| `VERCEL_GIT_COMMIT_REF` | Auto | Current git branch, set by Vercel |
+
+For local development, set the token in a `.env` file:
+
+```
+BLOB_READ_WRITE_TOKEN=vercel_blob_...
+```
+
+## How It Works
+
+`@vercel/kv2` stores data as JSON blobs in Vercel Blob storage with an edge cache layer for low-latency reads:
+
+1. **Writes** go directly to Vercel Blob, then invalidate the cache
+2. **Reads** check the edge cache first, falling back to Blob storage on cache miss
+3. **Preview branches** use copy-on-write: reads fall back to production data, writes stay isolated to the branch
+
+This gives you strong consistency for writes with fast cached reads, while branch isolation enables safe preview deployments without affecting production data.

package/docs/indexes.md

@@ -0,0 +1,122 @@
+[Home](../README.md) | [Previous: Schema and Trees](schema-and-trees.md) | [Next: Caching](caching.md)
+
+# Indexes
+
+Secondary indexes allow you to look up entries by attributes other than the primary key.
+
+## Defining Indexes
+
+Pass an `indexes` record to `getStore()`. Each index defines a `key` function that extracts the index key from the value:
+
+```typescript
+interface Doc {
+  slug: string;
+  status: string;
+  tags: string[];
+  title: string;
+  content: string;
+  authorId: string;
+}
+
+const docs = kv.getStore<Doc, undefined, "bySlug" | "byStatus">("docs/", {
+  bySlug: {
+    key: (doc) => doc.slug,
+    unique: true,
+  },
+  byStatus: {
+    key: (doc) => doc.status,
+  },
+});
+```
+
+## Unique Indexes
+
+Set `unique: true` to enforce uniqueness. A `KVIndexConflictError` is thrown if a duplicate is detected:
+
+```typescript
+import { KVIndexConflictError } from "@vercel/kv2";
+
+try {
+  await docs.set("doc-2", {
+    slug: "existing-slug", // already used by another doc
+    status: "draft",
+    tags: [],
+    title: "Duplicate",
+    content: "",
+    authorId: "author-1",
+  });
+} catch (error) {
+  if (error instanceof KVIndexConflictError) {
+    console.log(error.indexName); // "bySlug"
+    console.log(error.indexKey);  // "existing-slug"
+  }
+}
+```
+
+## Multi-Value Indexes
+
+Return an array from the `key` function to index an entry under multiple keys:
+
+```typescript
+interface Doc {
+  slug: string;
+  status: string;
+  tags: string[];
+  title: string;
+  content: string;
+  authorId: string;
+}
+
+const docs = kv.getStore<Doc, undefined, "byTag">("docs/", {
+  byTag: {
+    key: (doc) => doc.tags, // each tag becomes an index entry
+  },
+});
+
+await docs.set("doc-1", {
+  slug: "hello",
+  status: "published",
+  tags: ["typescript", "tutorial"],
+  title: "Hello",
+  content: "World",
+  authorId: "author-1",
+});
+
+// Find all docs tagged "typescript"
+for await (const key of docs.keys({ byTag: "typescript" })) {
+  console.log(key); // "doc-1"
+}
+```
+
+## Non-Unique Indexes
+
+Query non-unique indexes with `keys()` and `entries()`:
+
+```typescript
+// Find all published docs
+for await (const key of docs.keys({ byStatus: "published" })) {
+  console.log(key);
+}
+
+// Iterate entries by index
+for await (const [key, entry] of docs.entries({ byStatus: "draft" })) {
+  console.log(key, (await entry.value).title);
+}
+```
+
+## Index Maintenance
+
+Indexes are maintained automatically on `set()` and `delete()`. When you update a value, old index entries are removed and new ones are created.
+
+## Reindexing
+
+If indexes are added after data exists, or if index data becomes inconsistent, rebuild indexes with `reindex()`:
+
+```typescript
+const result = await docs.reindex();
+console.log(result.indexed); // number of entries reindexed
+```
+
+## Orphan Handling
+
+Index entries pointing to deleted primary keys are self-healing: they are automatically cleaned up during reads.

package/docs/iterating-and-pagination.md

@@ -0,0 +1,93 @@
+[Home](../README.md) | [Previous: Getting Started](getting-started.md) | [Next: Typed Stores](typed-stores.md)
+
+# Iterating and Pagination
+
+## Iterating Keys
+
+Use `keys()` to iterate over all keys in a store:
+
+```typescript
+for await (const key of users.keys()) {
+  console.log(key);
+}
+```
+
+Filter by prefix:
+
+```typescript
+for await (const key of kv.keys("users/active/")) {
+  console.log(key);
+}
+```
+
+## Iterating Entries
+
+`entries()` fetches values concurrently (default: 20 concurrent requests):
+
+```typescript
+for await (const [key, entry] of users.entries()) {
+  console.log(key, await entry.value);
+}
+```
+
+With a prefix filter:
+
+```typescript
+for await (const [key, entry] of users.entries("active/")) {
+  console.log(key, entry.metadata);
+}
+```
+
+## Fetching Multiple Keys
+
+Use `getMany()` to fetch specific keys with bounded concurrency:
+
+```typescript
+const results = await users.getMany(["alice", "bob", "charlie"]);
+for (const [key, entry] of results) {
+  console.log(key, await entry.value);
+}
+```
+
+## Cursor-Based Pagination
+
+Both `keys()` and `entries()` support cursor-based pagination for HTTP APIs.
+
+### Paginating Keys
+
+```typescript
+const page = await kv.keys("users/").page(10);
+console.log(page.keys);     // string[]
+console.log(page.cursor);   // string | undefined (pass to next call)
+```
+
+### Paginating Entries
+
+```typescript
+const page = await kv.entries<User>("users/").page(10);
+for (const [key, entry] of page.entries) {
+  console.log(key, await entry.value);
+}
+```
+
+### Next.js API Route Example
+
+```typescript
+async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  const { keys, cursor: nextCursor } = await users.keys().page(20, cursor);
+  const entries = await users.getMany(keys);
+
+  return Response.json({
+    users: await Promise.all(
+      keys.map(async (k) => {
+        const entry = entries.get(k);
+        return entry ? await entry.value : null;
+      }),
+    ),
+    nextCursor,
+  });
+}
+```

package/docs/metadata.md

@@ -0,0 +1,82 @@
+[Home](../README.md) | [Previous: Optimistic Locking](optimistic-locking.md) | [Next: Schema and Trees](schema-and-trees.md)
+
+# Metadata
+
+## Typed Metadata
+
+Parameterize `createKV<M>()` with a metadata type. Metadata is stored alongside each entry and is available immediately (no lazy loading):
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+interface Metadata {
+  updatedAt: number;
+  version: number;
+}
+
+interface User {
+  name: string;
+  email: string;
+}
+
+const kv = createKV<Metadata>({ prefix: "app/" });
+const users = kv.getStore<User>("users/");
+
+// Metadata is required on set
+await users.set("alice", { name: "Alice", email: "alice@example.com" }, { updatedAt: Date.now(), version: 1 });
+
+const result = await users.get("alice");
+if (result.exists) {
+  console.log(result.metadata.version); // 1 — available immediately
+  console.log((await result.value).name); // "Alice" — lazy loaded
+}
+```
+
+## Metadata on Sub-Stores
+
+Sub-stores inherit the metadata type from their parent:
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+interface Metadata {
+  updatedAt: number;
+  version: number;
+}
+
+interface Post {
+  title: string;
+  content: string;
+}
+
+const kv = createKV<Metadata>({ prefix: "app/" });
+const posts = kv.getStore<Post>("posts/");
+
+// Same metadata type required
+await posts.set("hello", { title: "Hello", content: "World" }, { updatedAt: Date.now(), version: 1 });
+```
+
+## Metadata Without Values
+
+Since metadata is available without loading the value, you can filter entries efficiently:
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+interface Metadata {
+  updatedAt: number;
+  version: number;
+}
+
+const kv = createKV<Metadata>({ prefix: "app/" });
+
+// Iterate entries and inspect metadata before deciding to load the value
+for await (const [key, entry] of kv.entries("posts/")) {
+  // metadata is immediately available
+  if (entry.metadata.updatedAt > Date.now() - 86400_000) {
+    // Only load the value for recent entries
+    const value = await entry.value;
+    console.log(key, value);
+  }
+}
+```

package/docs/optimistic-locking.md

@@ -0,0 +1,72 @@
+[Home](../README.md) | [Previous: Typed Stores](typed-stores.md) | [Next: Metadata](metadata.md)
+
+# Optimistic Locking
+
+## Why Optimistic Locking?
+
+KV stores don't have multi-key transactions the way a SQL database does. If two requests read a value, modify it, and write it back at the same time, one update silently overwrites the other — a lost update.
+
+Optimistic locking prevents this: every entry carries a `version` (an etag). When you write, you can say "only succeed if the version is still what I read." If someone else wrote in between, the store rejects your write with a `KVVersionConflictError` and you retry with fresh data. No locks are held, so throughput stays high — conflicts are detected, not prevented.
+
+## Version-Based Updates
+
+The simplest API is `entry.update()`. It captures the version at read time and passes it through automatically:
+
+```typescript
+const entry = await users.get("alice");
+if (entry.exists) {
+  const user = await entry.value;
+  user.name = "Alice Updated";
+
+  // Throws KVVersionConflictError if another process modified it
+  await entry.update(user);
+}
+```
+
+## Transactions via Read-Modify-Write
+
+Because there are no multi-key locks, the pattern for a "transaction" is a retry loop: read the current state, compute the new state, attempt the write, and retry if a conflict is detected. This is safe for any single-key mutation:
+
+```typescript
+import { KVVersionConflictError } from "@vercel/kv2";
+
+async function incrementCounter(key: string): Promise<number> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const entry = await kv.get<{ count: number }>(key);
+    if (!entry.exists) throw new Error("Key not found");
+
+    const current = await entry.value;
+    try {
+      await entry.update({ count: current.count + 1 });
+      return current.count + 1;
+    } catch (error) {
+      if (error instanceof KVVersionConflictError) continue;
+      throw error;
+    }
+  }
+  throw new Error("Max retries exceeded");
+}
+```
+
+This is the same approach databases like DynamoDB and CouchDB use for conditional writes. It works well when conflicts are rare (most workloads) and degrades gracefully when they aren't — retries are cheap because reads are cached.
+
+## Manual Version Control
+
+For more control, pass `expectedVersion` in `SetOptions` directly:
+
+```typescript
+const { version } = await kv.set("counter", { count: 0 }, metadata);
+
+// Later, conditionally update only if version matches
+await kv.set("counter", { count: 1 }, metadata, { expectedVersion: version });
+```
+
+This is useful when the version comes from an external source (e.g. a form submission that includes the etag it was editing).
+
+## Create-Only Writes
+
+Use `override: false` to ensure a key is only written if it doesn't already exist — useful for generating unique IDs or claiming resources:
+
+```typescript
+await kv.set("user/new-id", userData, metadata, { override: false });
+```