@vercel/kv2 0.0.1

package/docs/schema-and-trees.md

@@ -0,0 +1,222 @@
+[Home](../README.md) | [Previous: Metadata](metadata.md) | [Next: Indexes](indexes.md)
+
+# Schema and Trees
+
+For hierarchical data, define a schema and fetch trees with batched concurrent loading.
+
+## Defining a Schema
+
+Use `defineSchema()` to declare your entity hierarchy with patterns and value types:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+```
+
+Each node in the schema defines:
+- `pattern` — a glob pattern for matching keys at that level
+- `value` — a type witness (use `{} as T`)
+- `children` — optional nested entity definitions
+
+## Creating a Schema KV
+
+Combine a schema with a KV store:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+
+const kv = createKV({ prefix: "kanban/" });
+const kanban = createSchemaKV(schema, kv);
+```
+
+## Type-Safe Key Builders
+
+The schema KV provides key builders that produce correctly-formatted keys:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+
+const kv = createKV({ prefix: "kanban/" });
+const kanban = createSchemaKV(schema, kv);
+
+kanban.key.boards("board-1");                    // "board-1"
+kanban.key.columns("board-1", "col-1");          // "board-1/columns/col-1"
+kanban.key.tasks("board-1", "col-1", "task-1");  // "board-1/columns/col-1/tasks/task-1"
+```
+
+## Fetching Trees
+
+Use `tree()` to fetch an entity and all its descendants. Internally, it makes a single `keys()` call to discover descendants, then `getMany()` to fetch values concurrently:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+
+const kv = createKV({ prefix: "kanban/" });
+const kanban = createSchemaKV(schema, kv);
+
+const board = await kanban.tree("boards", "board-1");
+console.log(board.value.name);
+```
+
+## Lazy Iteration
+
+Children on a tree node are async iterables. They support `page()`, `collect()`, `count()`, and `keys()`:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+
+const kv = createKV({ prefix: "kanban/" });
+const kanban = createSchemaKV(schema, kv);
+
+const board = await kanban.tree("boards", "board-1");
+
+// Iterate children lazily
+for await (const column of board.columns) {
+  console.log(column.value.name);
+  for await (const task of column.tasks) {
+    console.log(task.value.title);
+  }
+}
+```
+
+## CRUD via Schema
+
+The schema KV provides typed `get`, `set`, and `delete` methods:
+
+```typescript
+import { defineSchema, createSchemaKV, createKV } from "@vercel/kv2";
+
+interface Board { name: string }
+interface Column { name: string; order: number }
+interface Task { title: string; done: boolean }
+
+const schema = defineSchema("kanban/", {
+  boards: {
+    pattern: "*",
+    value: {} as Board,
+    children: {
+      columns: {
+        pattern: "columns/*",
+        value: {} as Column,
+        children: {
+          tasks: { pattern: "tasks/*", value: {} as Task }
+        }
+      }
+    }
+  }
+});
+
+const kv = createKV({ prefix: "kanban/" });
+const kanban = createSchemaKV(schema, kv);
+
+// Set a board
+await kanban.set("boards", { name: "Sprint 1" }, undefined, "board-1");
+
+// Get a specific task
+const task = await kanban.get("tasks", "board-1", "col-1", "task-1");
+if (task.exists) {
+  console.log((await task.value).title);
+}
+
+// Delete a column
+await kanban.delete("columns", "board-1", "col-1");
+```

package/docs/streaming.md

@@ -0,0 +1,61 @@
+[Home](../README.md) | [Previous: Caching](caching.md) | [Next: Copy-on-Write Branches](copy-on-write-branches.md)
+
+# Streaming
+
+## Why Streaming?
+
+By default, `result.value` buffers the entire value into memory before returning it. For a 2 KB JSON object that's fine, but for a 50 MB image or a large dataset it means your serverless function allocates 50 MB of RAM just to pass the bytes through to a response.
+
+Streaming avoids this. With `result.stream` you get a `ReadableStream<Uint8Array>` that flows bytes directly from blob storage to the consumer — memory stays flat regardless of value size.
+
+Use streaming when you're:
+- Serving files or media to clients without processing them
+- Piping data between storage and another service
+- Working near your function's memory limit
+
+## Streaming Reads
+
+Use `result.stream` instead of `result.value` to read without buffering:
+
+```typescript
+const result = await kv.get("large-file");
+if (result.exists) {
+  const stream = await result.stream;
+  // Pipe directly to the HTTP response — no buffering
+  const response = new Response(stream);
+}
+```
+
+## Streaming Writes
+
+Pass a `ReadableStream<Uint8Array>` to `set()` to write without buffering the full payload:
+
+```typescript
+const stream = new ReadableStream<Uint8Array>({
+  start(controller) {
+    controller.enqueue(new TextEncoder().encode("hello world"));
+    controller.close();
+  },
+});
+
+await kv.set("streamed-value", stream, metadata);
+```
+
+This is useful for proxying uploads or piping data from another source directly into the store.
+
+## Large Value Threshold
+
+Values below the threshold (default: 1 MB) are inlined in a single JSON blob — small and fast. Values above it are stored in a binary format that separates the header (metadata) from the payload, enabling streaming without parsing the entire blob.
+
+You can tune the threshold:
+
+```typescript
+import { KV2 } from "@vercel/kv2";
+
+const kv = new KV2({
+  prefix: "files/",
+  largeValueThreshold: 512 * 1024, // 512KB
+});
+```
+
+Lower it if you serve many medium-sized values and want to stream them. Raise it (or leave the default) if your values are mostly small JSON and you want the simplicity of a single fetch.

package/docs/testing-and-tracing.md

@@ -0,0 +1,141 @@
+[Home](../README.md) | [Previous: Copy-on-Write Branches](copy-on-write-branches.md) | [Next: CLI](cli.md)
+
+# Testing and Tracing
+
+## Testing
+
+### FakeBlobStore
+
+An in-memory blob store for unit tests. No network calls, no tokens needed:
+
+```typescript
+import { FakeBlobStore } from "@vercel/kv2/testing";
+import { KV2 } from "@vercel/kv2";
+
+const blobStore = new FakeBlobStore();
+const kv = new KV2({ prefix: "test/", blobStore });
+
+await kv.set("key", { hello: "world" });
+const result = await kv.get("key");
+```
+
+### FakeCache
+
+An in-memory cache with call tracking and programmable error injection:
+
+```typescript
+import { FakeCache } from "@vercel/kv2/testing";
+import { KV2 } from "@vercel/kv2";
+
+const cache = new FakeCache();
+const blobStore = new FakeBlobStore();
+const kv = new KV2({ prefix: "test/", blobStore, cache });
+```
+
+### createTestKV
+
+A convenience factory that creates a KV2 backed by `FakeBlobStore` (or real Vercel Blob when `INTEGRATION_TEST=1`):
+
+```typescript
+import { createTestKV } from "@vercel/kv2/testing";
+
+const { kv, blobStore, cleanup } = createTestKV();
+
+await kv.set("key", { hello: "world" });
+
+// Clean up after tests
+await cleanup();
+```
+
+### Integration Tests
+
+Set environment variables and run:
+
+```bash
+INTEGRATION_TEST=1 pnpm test
+```
+
+Required env vars for integration tests:
+- `BLOB_READ_WRITE_TOKEN` — Vercel Blob access token
+- `PROTECTION_BYPASS` — Protection bypass token
+
+## Tracing
+
+### Built-in Tracers
+
+**No-op tracer** — zero overhead, the default:
+
+```typescript
+import { noopTracer, KV2 } from "@vercel/kv2";
+
+const kv = new KV2({ prefix: "app/", tracer: noopTracer });
+```
+
+**Console tracer** — logs span timing and attributes to console:
+
+```typescript
+import { consoleTracer, KV2 } from "@vercel/kv2";
+
+const kv = new KV2({ prefix: "app/", tracer: consoleTracer });
+// [KV] kv.get 2.3ms key=users/alice source=blob
+```
+
+### OpenTelemetry
+
+Adapt an OpenTelemetry tracer with `createOtelTracer()`:
+
+```typescript
+import { createOtelTracer, KV2 } from "@vercel/kv2";
+
+// Provide any OTEL-compatible tracer
+const otelTracer: import("@vercel/kv2").OtelTracerLike = {
+  startSpan(name, options) {
+    return {
+      setAttribute() {},
+      setStatus() {},
+      recordException() {},
+      end() {},
+    };
+  },
+};
+
+const tracer = createOtelTracer(otelTracer);
+const kv = new KV2({ prefix: "app/", tracer });
+```
+
+### Statistics Tracer
+
+Collect timing data for performance analysis:
+
+```typescript
+import { createStatsTracer, KV2 } from "@vercel/kv2";
+
+const { tracer, printStats, getStats, clear } = createStatsTracer();
+const kv = new KV2({ prefix: "app/", tracer });
+
+// ... run operations ...
+
+// Print a summary table
+printStats();
+
+// Get stats for a specific operation
+const stats = getStats("kv.get");
+if (stats) {
+  console.log(`avg: ${stats.avg}ms, p95: ${stats.p95}ms`);
+}
+```
+
+### Traced Operations
+
+KV2 emits spans for these operations:
+
+| Span Name | Description |
+|-----------|-------------|
+| `kv.get` | Single key read |
+| `kv.set` | Single key write |
+| `kv.delete` | Single key delete |
+| `kv.keys` | Key listing |
+| `kv.entries` | Entry listing |
+| `kv.getMany` | Batch read |
+
+Each span includes attributes like `key`, `source` (cache/blob), and `hit` (cache hit/miss).

package/docs/typed-stores.md

@@ -0,0 +1,68 @@
+[Home](../README.md) | [Previous: Iterating and Pagination](iterating-and-pagination.md) | [Next: Optimistic Locking](optimistic-locking.md)
+
+# Typed Stores
+
+## Why Typed Stores?
+
+A bare KV store is untyped — every `get()` returns `unknown` and every `set()` accepts anything. As your app grows you end up with ad-hoc key conventions ("users/" + id, "posts/" + slug) scattered across your codebase and `as User` casts at every call site.
+
+Typed stores solve this by giving you a narrow, strongly-typed view over a slice of your keyspace:
+
+- **Type safety** — `get()` returns `Post`, `set()` only accepts `Post`. No casts, no runtime surprises.
+- **Key namespacing** — the store owns its prefix, so you work with short relative keys (`"hello-world"`) instead of full paths (`"posts/hello-world"`).
+- **Composability** — stores nest, so you can model `posts/drafts/` or `users/active/` as their own typed sub-stores without any string concatenation.
+
+## Creating a Typed Store
+
+Use `getStore<T>()` to create a type-safe sub-store with automatic key prefixing:
+
+```typescript
+interface Post {
+  title: string;
+  content: string;
+}
+
+const posts = kv.getStore<Post>("posts/");
+
+await posts.set("hello-world", { title: "Hello", content: "World" });
+
+const result = await posts.get("hello-world");
+if (result.exists) {
+  const post = await result.value; // Post
+  console.log(post.title);
+}
+```
+
+## Key Prefixing
+
+Keys are relative to the store. The store prepends its prefix automatically, so you never build key strings by hand:
+
+```typescript
+const posts = kv.getStore<Post>("posts/");
+
+// You use relative keys
+await posts.set("hello-world", { title: "Hello", content: "World" });
+
+for await (const key of posts.keys()) {
+  console.log(key); // "hello-world" (not "posts/hello-world")
+}
+```
+
+## Nested Stores
+
+Stores can be nested. Prefixes accumulate, giving you a natural hierarchy without manual string building:
+
+```typescript
+interface Post {
+  title: string;
+  content: string;
+}
+
+const posts = kv.getStore<Post>("posts/");
+const drafts = posts.getStore<Post>("drafts/");
+
+await drafts.set("my-draft", { title: "Draft", content: "..." });
+// Actual blob path includes: "posts/drafts/my-draft"
+```
+
+This lets different parts of your application own their own keyspace — a `drafts` module only sees draft keys and can't accidentally read or overwrite published posts.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@vercel/kv2",
+  "version": "0.0.1",
+  "description": "KV2 - A type-safe KV store backed by Vercel private blobs with regional caching",
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/chaos",
+    "README.md",
+    "SKILL.md",
+    "docs"
+  ],
+  "bin": {
+    "kv2": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./testing/test-index": {
+      "import": "./dist/testing/test-index.js"
+    }
+  },
+  "keywords": [
+    "kv",
+    "cache",
+    "vercel",
+    "blob"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@vercel/blob": "2.2.0-f6bb7b4-20260204165325",
+    "@vercel/functions": "^3.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "dotenv": "^17.2.3",
+    "knip": "^5.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "cli": "node dist/cli.js",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "check": "biome check --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "test": "tsc && node dist/testing/run-tests.js",
+    "test:integration": "INTEGRATION_TEST=1 sh -c 'tsc && node dist/testing/run-tests.js'",
+    "knip": "knip",
+    "validate": "pnpm run knip && pnpm run typecheck && pnpm run test"
+  }
+}