@vercel/kv2 0.0.1

package/dist/upstream-kv.js

@@ -0,0 +1,375 @@
+import { TypedKV } from "./typed-kv.js";
+/**
+ * Wrapper that adds copy-on-write (CoW) behavior to KV2.
+ *
+ * - Reads check manifest to route to local or upstream (avoids unnecessary blob lookups)
+ * - Writes go to local only
+ * - Deletes create tombstones to prevent upstream fallthrough
+ * - keys() returns keys from the manifest (discovered + local)
+ */
+export class UpstreamKV {
+    local;
+    upstream;
+    manifest;
+    constructor(local, upstream, manifest) {
+        this.local = local;
+        this.upstream = upstream;
+        this.manifest = manifest;
+    }
+    /**
+     * Wrap an upstream entry to redirect update() calls through UpstreamKV.set().
+     * This ensures updates write to local storage, not upstream.
+     *
+     * Note: We don't use expectedVersion here because we're creating a new local
+     * shadow of the upstream entry, not updating an existing local entry.
+     */
+    wrapUpstreamEntry(key, entry) {
+        const self = this;
+        return {
+            exists: true,
+            metadata: entry.metadata,
+            version: entry.version,
+            get value() {
+                return entry.value;
+            },
+            get stream() {
+                return entry.stream;
+            },
+            async update(value, metadata) {
+                const meta = metadata ?? entry.metadata;
+                // Write to local without expectedVersion - creates a new local shadow
+                return self.set(key, value, meta);
+            },
+        };
+    }
+    /**
+     * Get a value. Uses manifest to route efficiently:
+     * - Keys marked "local" → check local only
+     * - Keys marked "upstream" → check upstream only (skip local blob lookup)
+     * - Keys marked "tombstone" → return not found
+     * - Unknown keys → check local, then upstream
+     */
+    async get(key) {
+        // Check manifest for this specific key (cached as single entry)
+        const keyMeta = await this.manifest.getKeySource(key);
+        // Tombstoned keys don't exist
+        if (keyMeta?.source === "tombstone") {
+            return {
+                exists: false,
+                metadata: undefined,
+                value: undefined,
+                stream: undefined,
+            };
+        }
+        // Key known to be local - check local only
+        // Local entries' update() already writes to local, so no wrapping needed
+        if (keyMeta?.source === "local") {
+            return this.local.get(key);
+        }
+        // Key known to be upstream - skip local blob lookup, go straight to upstream
+        // Wrap the entry so update() writes to local instead of upstream
+        if (keyMeta?.source === "upstream") {
+            const result = await this.upstream.get(key);
+            if (result.exists) {
+                return this.wrapUpstreamEntry(key, result);
+            }
+            return result;
+        }
+        // Unknown key - check local first, then upstream
+        const localResult = await this.local.get(key);
+        if (localResult.exists) {
+            // Record in manifest for future lookups (only happens once per key)
+            await this.manifest.recordAdd(key, "local");
+            return localResult;
+        }
+        // Try upstream
+        const upstreamResult = await this.upstream.get(key);
+        if (upstreamResult.exists) {
+            // Record discovery for future lookups (only happens once per key)
+            await this.manifest.recordAdd(key, "upstream");
+            // Wrap so update() writes to local
+            return this.wrapUpstreamEntry(key, upstreamResult);
+        }
+        return upstreamResult;
+    }
+    /**
+     * Set a value. Writes to local only.
+     */
+    async set(key, value, ...[metadata, options]) {
+        // Write to local - use type assertion for the complex conditional type
+        const result = await this.local.set(key, value, metadata, options);
+        // Record in manifest - await for consistency
+        await this.manifest.recordAdd(key, "local");
+        return result;
+    }
+    /**
+     * Delete a key. Creates a tombstone to prevent upstream fallthrough.
+     */
+    async delete(key) {
+        // Delete from local
+        await this.local.delete(key);
+        // Record tombstone - await for consistency (next get must see it)
+        await this.manifest.recordDelete(key);
+    }
+    /**
+     * Iterate over keys. Returns merged keys from local, manifest, and upstream,
+     * excluding tombstones.
+     */
+    keys(prefix) {
+        const self = this;
+        return {
+            async *[Symbol.asyncIterator]() {
+                const manifestEntries = await self.manifest.getAll();
+                const seen = new Set();
+                // First yield local keys
+                for await (const key of self.local.keys(prefix)) {
+                    seen.add(key);
+                    yield key;
+                }
+                // Then yield manifest keys (discovered from upstream) not yet seen
+                for (const [key, meta] of manifestEntries) {
+                    if (meta.source === "tombstone")
+                        continue;
+                    if (prefix && !key.startsWith(prefix))
+                        continue;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    yield key;
+                }
+                // Finally yield upstream keys not yet seen or tombstoned
+                for await (const key of self.upstream.keys(prefix)) {
+                    if (seen.has(key))
+                        continue;
+                    if (manifestEntries.get(key)?.source === "tombstone")
+                        continue;
+                    seen.add(key);
+                    yield key;
+                }
+            },
+            async page(limit, cursor) {
+                // Cursor format: "local:cursor" | "upstream:cursor" | undefined
+                // Local keys and manifest are collected fully (typically small)
+                // Upstream uses cursor-based pagination
+                const manifestEntries = await self.manifest.getAll();
+                const tombstones = new Set();
+                for (const [key, meta] of manifestEntries) {
+                    if (meta.source === "tombstone")
+                        tombstones.add(key);
+                }
+                const keys = [];
+                let phase = "local";
+                let phaseCursor;
+                // Parse cursor
+                if (cursor) {
+                    const colonIndex = cursor.indexOf(":");
+                    if (colonIndex !== -1) {
+                        phase = cursor.slice(0, colonIndex);
+                        phaseCursor = cursor.slice(colonIndex + 1) || undefined;
+                    }
+                }
+                const seen = new Set();
+                // Local phase
+                if (phase === "local") {
+                    const { keys: localKeys, cursor: localCursor } = await self.local
+                        .keys(prefix)
+                        .page(limit, phaseCursor);
+                    for (const key of localKeys) {
+                        seen.add(key);
+                        keys.push(key);
+                        if (keys.length >= limit) {
+                            return {
+                                keys,
+                                cursor: localCursor ? `local:${localCursor}` : "manifest:",
+                            };
+                        }
+                    }
+                    // If local has more, continue there next time
+                    if (localCursor) {
+                        return { keys, cursor: `local:${localCursor}` };
+                    }
+                    // Move to manifest phase
+                    phase = "manifest";
+                    phaseCursor = undefined;
+                }
+                // Manifest phase - collect all matching manifest keys not seen
+                if (phase === "manifest") {
+                    for (const [key, meta] of manifestEntries) {
+                        if (meta.source === "tombstone")
+                            continue;
+                        if (prefix && !key.startsWith(prefix))
+                            continue;
+                        if (seen.has(key))
+                            continue;
+                        seen.add(key);
+                        keys.push(key);
+                        if (keys.length >= limit) {
+                            // Can't cursor into manifest easily, move to upstream next
+                            return { keys, cursor: "upstream:" };
+                        }
+                    }
+                    // Move to upstream phase
+                    phase = "upstream";
+                    phaseCursor = undefined;
+                }
+                // Upstream phase
+                if (phase === "upstream") {
+                    const remaining = limit - keys.length;
+                    if (remaining > 0) {
+                        // Need to fetch more from upstream, filtering duplicates and tombstones
+                        let upstreamCursor = phaseCursor;
+                        while (keys.length < limit) {
+                            const { keys: upstreamKeys, cursor: nextCursor } = await self.upstream
+                                .keys(prefix)
+                                .page(remaining * 2, upstreamCursor);
+                            for (const key of upstreamKeys) {
+                                if (seen.has(key) || tombstones.has(key))
+                                    continue;
+                                seen.add(key);
+                                keys.push(key);
+                                if (keys.length >= limit)
+                                    break;
+                            }
+                            upstreamCursor = nextCursor;
+                            if (!upstreamCursor)
+                                break;
+                        }
+                        if (upstreamCursor) {
+                            return { keys, cursor: `upstream:${upstreamCursor}` };
+                        }
+                    }
+                }
+                // No more data
+                return { keys, cursor: undefined };
+            },
+        };
+    }
+    /**
+     * Fetch multiple keys concurrently with bounded concurrency.
+     * Returns a Map of key -> entry for all existing keys.
+     * Uses this.get() which handles local/upstream routing and tombstones.
+     *
+     * @param keys - Array of keys to fetch
+     * @param concurrency - Number of concurrent get operations (default: 20)
+     */
+    async getMany(keys, concurrency = 20) {
+        const results = new Map();
+        // Process keys in batches
+        for (let i = 0; i < keys.length; i += concurrency) {
+            const batch = keys.slice(i, i + concurrency);
+            const batchResults = await Promise.all(batch.map(async (key) => {
+                const result = await this.get(key);
+                return { key, result };
+            }));
+            for (const { key, result } of batchResults) {
+                if (result.exists) {
+                    results.set(key, result);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Iterate over key-value entries with concurrent fetching.
+     * Yields entries as soon as each fetch completes.
+     * Returns merged entries from local and upstream, excluding tombstones.
+     *
+     * @param prefix - Optional prefix to filter keys
+     * @param concurrency - Number of concurrent get operations (default: 20)
+     */
+    entries(prefix, concurrency = 20) {
+        const self = this;
+        return {
+            async *[Symbol.asyncIterator]() {
+                const keyIterator = self.keys(prefix)[Symbol.asyncIterator]();
+                // Pool of in-flight fetches
+                const inFlight = new Map();
+                let keysDone = false;
+                // Start initial batch of fetches
+                while (inFlight.size < concurrency && !keysDone) {
+                    const { done, value: key } = await keyIterator.next();
+                    if (done) {
+                        keysDone = true;
+                        break;
+                    }
+                    inFlight.set(key, self.get(key).then((result) => ({ key, result })));
+                }
+                // Process results as they complete, refilling the pool
+                while (inFlight.size > 0) {
+                    const { key, result } = await Promise.race(inFlight.values());
+                    inFlight.delete(key);
+                    if (result.exists) {
+                        yield [key, result];
+                    }
+                    if (!keysDone) {
+                        const { done, value: nextKey } = await keyIterator.next();
+                        if (done) {
+                            keysDone = true;
+                        }
+                        else {
+                            inFlight.set(nextKey, self.get(nextKey).then((r) => ({ key: nextKey, result: r })));
+                        }
+                    }
+                }
+            },
+            async page(limit, cursor) {
+                // Get a page of keys first
+                const { keys, cursor: nextCursor } = await self
+                    .keys(prefix)
+                    .page(limit, cursor);
+                // Fetch all values concurrently
+                const entriesMap = await self.getMany(keys, concurrency);
+                // Build entries array in key order
+                const entries = [];
+                for (const key of keys) {
+                    const entry = entriesMap.get(key);
+                    if (entry) {
+                        entries.push([key, entry]);
+                    }
+                }
+                return { entries, cursor: nextCursor };
+            },
+        };
+    }
+    /**
+     * Discover all keys from upstream and add to manifest.
+     * Use when you need complete keys() immediately.
+     */
+    async discoverAllKeys() {
+        const state = await this.manifest.getManifest();
+        const known = new Set(state.keys.keys());
+        let discovered = 0;
+        for await (const key of this.upstream.keys()) {
+            if (!known.has(key)) {
+                await this.manifest.recordAdd(key, "upstream");
+                discovered++;
+            }
+        }
+        return discovered;
+    }
+    /**
+     * Delete all local data and manifest (for environment cleanup).
+     */
+    async destroy() {
+        // Delete all local KV data
+        for await (const key of this.local.keys()) {
+            await this.local.delete(key);
+        }
+        // Delete manifest
+        await this.manifest.destroy();
+    }
+    /**
+     * Get the underlying local KV (for advanced use cases).
+     */
+    getLocalKV() {
+        return this.local;
+    }
+    /**
+     * Get a typed sub-store with CoW behavior.
+     * Reads fall back to upstream, writes go to local.
+     */
+    getStore(subPrefix, indexes) {
+        return new TypedKV(this, subPrefix, indexes);
+    }
+}
+//# sourceMappingURL=upstream-kv.js.map

package/dist/upstream-kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-kv.js","sourceRoot":"","sources":["../src/upstream-kv.ts"],"names":[],"mappings":"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"}

package/docs/api-reference.md

@@ -0,0 +1,222 @@
+[Home](../README.md) | [Previous: CLI](cli.md)
+
+# API Reference
+
+## `createKV<M>(options)`
+
+Creates a KV store with automatic environment detection and copy-on-write fallback.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | `""` | Key prefix for namespacing |
+| `upstream` | `UpstreamConfig \| null` | `{ branch: "main" }` | Fallback config, or `null` to disable |
+| `env` | `string` | `VERCEL_ENV` | Environment name |
+| `branch` | `string` | `VERCEL_GIT_COMMIT_REF` | Branch name |
+| `token` | `string` | `BLOB_READ_WRITE_TOKEN` | Blob access token |
+| `blobStore` | `BlobStore` | `VercelBlobStore` | Custom blob store |
+| `cache` | `CacheLike` | auto-detected | Custom cache implementation |
+| `cacheTtl` | `number` | `3600` | Cache TTL in seconds |
+| `largeValueThreshold` | `number` | `1048576` | Byte threshold for binary format |
+| `tracer` | `Tracer` | `noopTracer` | Custom tracer |
+
+Returns `KV2<M>` (on production/main) or `UpstreamKV<M>` (on preview branches).
+
+## `KVLike<M>` Interface
+
+All stores (`KV2`, `UpstreamKV`, `TypedKV`) implement this interface:
+
+```typescript
+interface KVLike<M> {
+  get<V>(key: string): Promise<KVGetResult<V, M>>;
+  set<V>(key: string, value: V | ReadableStream<Uint8Array>, metadata?: M, options?: SetOptions): Promise<KVSetResult>;
+  delete(key: string): Promise<void>;
+  keys(prefix?: string): KeysIterable;
+  entries<V>(prefix?: string): EntriesIterable<V, M>;
+  getMany<V>(keys: string[], concurrency?: number): Promise<Map<string, KVEntry<V, M>>>;
+}
+```
+
+## `KVGetResult<V, M>`
+
+A discriminated union — check `exists` before accessing properties:
+
+```typescript
+const result = await kv.get<User>("key");
+if (result.exists) {
+  result.metadata;     // M — immediately available
+  result.version;      // string — etag for optimistic locking
+  await result.value;  // V — lazy-loaded
+  await result.stream; // ReadableStream<Uint8Array>
+  await result.update(newValue); // conditional write
+}
+```
+
+### Properties (when `exists: true`)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `exists` | `true` | Entry found |
+| `metadata` | `M` | Entry metadata (immediate) |
+| `version` | `string` | Etag for optimistic locking |
+| `value` | `Promise<V>` | Lazily parsed value |
+| `stream` | `Promise<ReadableStream<Uint8Array>>` | Raw byte stream |
+| `update(value, metadata?)` | `Promise<KVSetResult>` | Conditional update using captured version |
+
+### Properties (when `exists: false`)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `exists` | `false` | Entry not found |
+| `metadata` | `undefined` | |
+| `value` | `undefined` | |
+| `stream` | `undefined` | |
+
+## `SetOptions`
+
+```typescript
+interface SetOptions {
+  expectedVersion?: string;  // Only succeed if current version matches
+  override?: boolean;        // Allow overwriting (default: true)
+}
+```
+
+## `KVSetResult`
+
+```typescript
+interface KVSetResult {
+  version: string;  // etag of the written blob
+}
+```
+
+## `KeysIterable`
+
+```typescript
+interface KeysIterable extends AsyncIterable<string> {
+  page(limit: number, cursor?: string): Promise<KeysPage>;
+}
+
+interface KeysPage {
+  keys: string[];
+  cursor?: string;
+}
+```
+
+## `EntriesIterable<V, M>`
+
+```typescript
+interface EntriesIterable<V, M> extends AsyncIterable<[string, KVEntry<V, M>]> {
+  page(limit: number, cursor?: string): Promise<EntriesPage<V, M>>;
+}
+
+interface EntriesPage<V, M> {
+  entries: [string, KVEntry<V, M>][];
+  cursor?: string;
+}
+```
+
+## `TypedKV<V, M, I>`
+
+A typed sub-store with automatic key prefixing and optional secondary indexes.
+
+```typescript
+// Create from any KV
+const users = kv.getStore<User>("users/");
+
+// With indexes
+const docs = kv.getStore<Doc, undefined, "bySlug">("docs/", {
+  bySlug: { key: (doc) => doc.slug, unique: true },
+});
+```
+
+### Methods
+
+All `KVLike<M>` methods plus:
+
+| Method | Description |
+|--------|-------------|
+| `getStore<V, M, I>(prefix, indexes?)` | Create a nested sub-store |
+| `reindex(indexName?)` | Rebuild one or all secondary indexes |
+| `get(indexQuery)` | Look up by index (unique indexes) |
+| `keys(indexQuery)` | List keys matching an index query |
+| `entries(indexQuery)` | List entries matching an index query |
+
+## `KV2<M>`
+
+The core cached KV implementation. Implements `KVLike<M>` plus:
+
+| Method | Description |
+|--------|-------------|
+| `getStore<V, M, I>(prefix, indexes?)` | Create a typed sub-store |
+
+### Constructor Options (`KV2Options`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `PrefixString` | `""` | Global key prefix |
+| `token` | `string` | `BLOB_READ_WRITE_TOKEN` | Blob access token |
+| `largeValueThreshold` | `number` | `1048576` | Binary format threshold (bytes) |
+| `cacheTtl` | `number` | `3600` | Cache TTL (seconds) |
+| `blobStore` | `BlobStore` | `VercelBlobStore` | Blob storage backend |
+| `cache` | `CacheLike` | auto-detected | Cache backend |
+| `tracer` | `Tracer` | `noopTracer` | Tracing backend |
+
+## `UpstreamKV<M>`
+
+Copy-on-write wrapper. Implements `KVLike<M>` with fallback reads to an upstream KV. Created automatically by `createKV()` on preview branches.
+
+## `SchemaKV<P, E>`
+
+Schema-aware KV with type-safe key builders and tree loading:
+
+| Property/Method | Description |
+|----------------|-------------|
+| `raw` | The underlying `KVLike` store |
+| `key` | Type-safe key builders for all entity types |
+| `tree(type, ...ids)` | Fetch an entity and its descendants as a lazy tree |
+| `get(type, ...ids)` | Get a single entity |
+| `set(type, value, metadata, ...ids)` | Set an entity |
+| `delete(type, ...ids)` | Delete an entity |
+
+## Error Classes
+
+### `KVVersionConflictError`
+
+Thrown when a conditional update fails because the entry was modified by another process.
+
+```typescript
+import { KVVersionConflictError } from "@vercel/kv2";
+
+try {
+  await entry.update(newValue);
+} catch (error) {
+  if (error instanceof KVVersionConflictError) {
+    // Retry the read-modify-write cycle
+  }
+}
+```
+
+### `KVIndexConflictError`
+
+Thrown when a unique index constraint is violated.
+
+```typescript
+import { KVIndexConflictError } from "@vercel/kv2";
+
+try {
+  await docs.set("doc-2", docData);
+} catch (error) {
+  if (error instanceof KVIndexConflictError) {
+    console.log(error.indexName); // e.g. "bySlug"
+    console.log(error.indexKey);  // the conflicting key
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BLOB_READ_WRITE_TOKEN` | Yes | Vercel Blob access token |
+| `VERCEL_ENV` | Auto | `production`, `preview`, or `development` |
+| `VERCEL_GIT_COMMIT_REF` | Auto | Current git branch |
+| `PROTECTION_BYPASS` | Integration tests | Protection bypass token |

package/docs/caching.md

@@ -0,0 +1,60 @@
+[Home](../README.md) | [Previous: Indexes](indexes.md) | [Next: Streaming](streaming.md)
+
+# Caching
+
+## How Caching Works
+
+`@vercel/kv2` uses write-through caching with tag-based invalidation:
+
+1. **On write** — the value is written to Vercel Blob and the cache is invalidated by tag
+2. **On read** — the cache is checked first; on cache miss, the value is loaded from Blob and cached
+
+This gives you read-your-writes consistency within a deployment while providing low-latency cached reads across regions.
+
+## Cache Hierarchy
+
+The cache implementation is selected automatically based on the environment:
+
+| Environment | Cache | Notes |
+|-------------|-------|-------|
+| Vercel Production/Preview | Vercel Runtime Cache | Edge-distributed, tag invalidation |
+| Local Development | MemoryCache | In-memory, persists across HMR |
+| Integration Tests | ProxyCache | Connects to Vercel cache proxy |
+
+## Configuration
+
+### Cache TTL
+
+Set the cache TTL in seconds (default: 3600):
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+const kv = createKV({
+  prefix: "app/",
+  cacheTtl: 600, // 10 minutes
+});
+```
+
+### Custom Cache
+
+Provide a custom `CacheLike` implementation:
+
+```typescript
+import { createKV } from "@vercel/kv2";
+
+const kv = createKV({
+  prefix: "app/",
+  cache: {
+    async get(key: string) {
+      return null; // custom get
+    },
+    async set(key: string, value: unknown, options?: { tags?: string[]; ttl?: number }) {
+      // custom set
+    },
+    async expireTag(tag: string) {
+      // custom tag invalidation
+    },
+  },
+});
+```