@vercel/kv2 0.0.1

package/dist/manifest-log.js

@@ -0,0 +1,128 @@
+import { KV2 } from "./cached-kv.js";
+const MANIFEST_CACHE_KEY = "__manifest__";
+/**
+ * Manifest for tracking key sources (local vs upstream vs tombstone).
+ *
+ * Individual entries stored in blob for persistence.
+ * Aggregated manifest cached as single entry for fast cross-instance reads.
+ */
+export class ManifestLog {
+    kv;
+    cache;
+    cacheKey;
+    constructor(blobStore, manifestPrefix, cache) {
+        this.kv = new KV2({
+            prefix: manifestPrefix,
+            blobStore,
+            // Pass same cache to inner KV for test isolation
+            // (avoids falling back to global Vercel runtime cache singleton)
+            cache,
+        });
+        this.cache = cache;
+        this.cacheKey = `manifest:${manifestPrefix}`;
+    }
+    /**
+     * Get the source for a specific key.
+     * Returns null if key is not in manifest (unknown).
+     */
+    async getKeySource(key) {
+        const manifest = await this.loadManifest();
+        return manifest.get(key) ?? null;
+    }
+    /**
+     * Record a key as local or upstream.
+     */
+    async recordAdd(key, source) {
+        await this.kv.set(key, { source });
+        await this.invalidateCache();
+    }
+    /**
+     * Record a key deletion (tombstone).
+     */
+    async recordDelete(key) {
+        await this.kv.set(key, { source: "tombstone" });
+        await this.invalidateCache();
+    }
+    /**
+     * Delete a manifest entry (for cleanup).
+     */
+    async remove(key) {
+        await this.kv.delete(key);
+        await this.invalidateCache();
+    }
+    /**
+     * Delete all manifest entries.
+     */
+    async destroy() {
+        for await (const key of this.kv.keys()) {
+            await this.kv.delete(key);
+        }
+        await this.invalidateCache();
+    }
+    /**
+     * Get all manifest entries.
+     */
+    async getAll() {
+        return this.loadManifest();
+    }
+    /**
+     * Get manifest state with keys map.
+     */
+    async getManifest() {
+        return { keys: await this.loadManifest() };
+    }
+    /**
+     * Load manifest from cache or blob.
+     * Caches aggregated result for fast repeated reads.
+     */
+    async loadManifest() {
+        // Try cache first
+        if (this.cache) {
+            try {
+                const cached = (await this.cache.get(this.cacheKey));
+                if (cached?.entries) {
+                    return new Map(cached.entries);
+                }
+            }
+            catch {
+                // Cache miss or error, fall through to blob
+            }
+        }
+        // Load from blob
+        const entries = new Map();
+        for await (const key of this.kv.keys()) {
+            const result = await this.kv.get(key);
+            if (result.exists) {
+                entries.set(key, await result.value);
+            }
+        }
+        // Cache the aggregated result
+        if (this.cache) {
+            try {
+                const toCache = {
+                    entries: Array.from(entries.entries()),
+                };
+                await this.cache.set(this.cacheKey, toCache, { ttl: 3600 });
+            }
+            catch {
+                // Cache write failed, continue without caching
+            }
+        }
+        return entries;
+    }
+    /**
+     * Invalidate the cached manifest.
+     */
+    async invalidateCache() {
+        if (this.cache) {
+            try {
+                // Use expireTag if available, otherwise set to empty
+                await this.cache.set(this.cacheKey, null, { ttl: 0 });
+            }
+            catch {
+                // Ignore cache invalidation errors
+            }
+        }
+    }
+}
+//# sourceMappingURL=manifest-log.js.map

package/dist/manifest-log.js.map

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

package/dist/memory-cache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-memory cache for local development.
+ * State is stored in globalThis to persist across HMR reloads.
+ */
+import type { CacheLike } from "./types.js";
+export declare class MemoryCache implements CacheLike {
+    private state;
+    constructor();
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, options?: {
+        tags?: string[];
+        ttl?: number;
+    }): Promise<void>;
+    expireTag(tag: string): Promise<void>;
+}
+export declare function getMemoryCache(): MemoryCache;
+/**
+ * Check if memory cache should be used.
+ * Returns true when running locally (not on Vercel) and not in integration test mode.
+ */
+export declare function shouldUseMemoryCache(): boolean;
+//# sourceMappingURL=memory-cache.d.ts.map

package/dist/memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../src/memory-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4B5C,qBAAa,WAAY,YAAW,SAAS;IAC5C,OAAO,CAAC,KAAK,CAAmB;;IAU1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAelC,GAAG,CACR,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,IAAI,CAAC;IAqBV,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAS3C;AAKD,wBAAgB,cAAc,IAAI,WAAW,CAM5C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAW9C"}

package/dist/memory-cache.js

@@ -0,0 +1,90 @@
+/**
+ * In-memory cache for local development.
+ * State is stored in globalThis to persist across HMR reloads.
+ */
+const globalKey = Symbol.for("kv-memory-cache");
+function getState() {
+    const g = globalThis;
+    if (!g[globalKey]) {
+        g[globalKey] = {
+            data: new Map(),
+            tags: new Map(),
+        };
+    }
+    return g[globalKey];
+}
+let loggedUsage = false;
+export class MemoryCache {
+    state;
+    constructor() {
+        this.state = getState();
+        if (!loggedUsage) {
+            console.log("[MemoryCache] Using in-memory cache for local development");
+            loggedUsage = true;
+        }
+    }
+    async get(key) {
+        const entry = this.state.data.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.state.data.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, options) {
+        const tags = options?.tags ?? [];
+        const ttl = options?.ttl ?? 3600;
+        const entry = {
+            value,
+            tags,
+            expiresAt: Date.now() + ttl * 1000,
+        };
+        this.state.data.set(key, entry);
+        // Track tags
+        for (const tag of tags) {
+            if (!this.state.tags.has(tag)) {
+                this.state.tags.set(tag, new Set());
+            }
+            this.state.tags.get(tag).add(key);
+        }
+    }
+    async expireTag(tag) {
+        const keys = this.state.tags.get(tag);
+        if (keys) {
+            for (const key of keys) {
+                this.state.data.delete(key);
+            }
+            this.state.tags.delete(tag);
+        }
+    }
+}
+// Singleton instance (also stored in globalThis)
+const instanceKey = Symbol.for("kv-memory-cache-instance");
+export function getMemoryCache() {
+    const g = globalThis;
+    if (!g[instanceKey]) {
+        g[instanceKey] = new MemoryCache();
+    }
+    return g[instanceKey];
+}
+/**
+ * Check if memory cache should be used.
+ * Returns true when running locally (not on Vercel) and not in integration test mode.
+ */
+export function shouldUseMemoryCache() {
+    // Don't use on Vercel
+    if (process.env.VERCEL) {
+        return false;
+    }
+    // Don't use during integration tests (they use proxy cache)
+    if (process.env.INTEGRATION_TEST === "1") {
+        return false;
+    }
+    // Use memory cache for local development
+    return true;
+}
+//# sourceMappingURL=memory-cache.js.map

package/dist/memory-cache.js.map

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

package/dist/proxy-cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ProxyCache - A cache implementation that proxies to a deployed cache-proxy endpoint.
+ * This allows local development to use the real Vercel cache.
+ *
+ * Usage:
+ *   // Set environment variables:
+ *   // CACHE_PROXY_URL=https://cached-kv-poc.vercel.app/api/cache-proxy
+ *   // PROTECTION_BYPASS=<your-bypass-token>
+ *
+ *   import { getProxyCache } from "./proxy-cache.js";
+ *   const cache = getProxyCache();
+ *   await cache.set("key", { data: "value" }, { ttl: 3600 });
+ *   const value = await cache.get("key");
+ */
+interface CacheSetOptions {
+    tags?: string[];
+    ttl?: number;
+}
+export interface ProxyCache {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, options?: CacheSetOptions): Promise<void>;
+    expireTag(tag: string): Promise<void>;
+}
+export interface ProxyCacheOptions {
+    /** Base URL of the cache-proxy endpoint */
+    proxyUrl?: string;
+    /** Protection bypass token for Vercel deployment protection */
+    protectionBypass?: string;
+}
+/**
+ * Get a proxy cache instance for local development.
+ * Uses CACHE_PROXY_URL and PROTECTION_BYPASS environment variables.
+ */
+export declare function getProxyCache(options?: ProxyCacheOptions): ProxyCache;
+/**
+ * Check if we should use the proxy cache (running locally with integration tests).
+ */
+export declare function shouldUseProxyCache(): boolean;
+export {};
+//# sourceMappingURL=proxy-cache.d.ts.map

package/dist/proxy-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-cache.d.ts","sourceRoot":"","sources":["../src/proxy-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,UAAU,eAAe;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AA6GD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAKrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAW7C"}

package/dist/proxy-cache.js

@@ -0,0 +1,124 @@
+/**
+ * ProxyCache - A cache implementation that proxies to a deployed cache-proxy endpoint.
+ * This allows local development to use the real Vercel cache.
+ *
+ * Usage:
+ *   // Set environment variables:
+ *   // CACHE_PROXY_URL=https://cached-kv-poc.vercel.app/api/cache-proxy
+ *   // PROTECTION_BYPASS=<your-bypass-token>
+ *
+ *   import { getProxyCache } from "./proxy-cache.js";
+ *   const cache = getProxyCache();
+ *   await cache.set("key", { data: "value" }, { ttl: 3600 });
+ *   const value = await cache.get("key");
+ */
+const DEFAULT_CACHE_PROXY_URL = "https://cached-kv-poc.vercel.app/api/cache-proxy";
+const REQUEST_TIMEOUT_MS = 10000; // 10 second timeout
+class ProxyCacheImpl {
+    proxyUrl;
+    protectionBypass;
+    constructor(options) {
+        this.proxyUrl =
+            options?.proxyUrl ??
+                process.env.CACHE_PROXY_URL ??
+                DEFAULT_CACHE_PROXY_URL;
+        this.protectionBypass =
+            options?.protectionBypass ?? process.env.PROTECTION_BYPASS;
+    }
+    getHeaders(contentType) {
+        const headers = {};
+        if (contentType) {
+            headers["Content-Type"] = contentType;
+        }
+        if (this.protectionBypass) {
+            headers["x-vercel-protection-bypass"] = this.protectionBypass;
+        }
+        return headers;
+    }
+    async fetchWithTimeout(url, options = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+            });
+            return response;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async get(key) {
+        // Pass key in POST body to avoid URL encoding issues with unicode
+        const url = `${this.proxyUrl}?op=get`;
+        const response = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.getHeaders("application/json"),
+            body: JSON.stringify({ key }),
+        });
+        const data = (await response.json());
+        if (data.error) {
+            throw new Error(data.error);
+        }
+        return data.value;
+    }
+    async set(key, value, options) {
+        // Pass key in POST body to avoid URL encoding issues with unicode
+        const url = `${this.proxyUrl}?op=set`;
+        const response = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.getHeaders("application/json"),
+            body: JSON.stringify({
+                key,
+                value,
+                tags: options?.tags,
+                ttl: options?.ttl,
+            }),
+        });
+        const data = (await response.json());
+        if (data.error) {
+            throw new Error(data.error);
+        }
+    }
+    async expireTag(tag) {
+        // Pass tag in POST body to avoid URL encoding issues with unicode
+        const url = `${this.proxyUrl}?op=expireTag`;
+        const response = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.getHeaders("application/json"),
+            body: JSON.stringify({ tag }),
+        });
+        const data = (await response.json());
+        if (data.error) {
+            throw new Error(data.error);
+        }
+    }
+}
+let proxyCacheInstance = null;
+/**
+ * Get a proxy cache instance for local development.
+ * Uses CACHE_PROXY_URL and PROTECTION_BYPASS environment variables.
+ */
+export function getProxyCache(options) {
+    if (!proxyCacheInstance) {
+        proxyCacheInstance = new ProxyCacheImpl(options);
+    }
+    return proxyCacheInstance;
+}
+/**
+ * Check if we should use the proxy cache (running locally with integration tests).
+ */
+export function shouldUseProxyCache() {
+    // On Vercel, use the native cache
+    if (process.env.VERCEL) {
+        return false;
+    }
+    // Only use proxy for integration tests when PROTECTION_BYPASS is set
+    if (process.env.INTEGRATION_TEST !== "1") {
+        return false;
+    }
+    // Use proxy if CACHE_PROXY_URL or PROTECTION_BYPASS is set
+    return !!(process.env.CACHE_PROXY_URL || process.env.PROTECTION_BYPASS);
+}
+//# sourceMappingURL=proxy-cache.js.map

package/dist/proxy-cache.js.map

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

package/dist/readme.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * README and docs/ validation tests
+ *
+ * Ensures documentation stays in sync with the actual codebase:
+ * 1. TypeScript examples compile correctly
+ * 2. API documentation matches KVLike interface
+ */
+export {};
+//# sourceMappingURL=readme.test.d.ts.map

package/dist/readme.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.test.d.ts","sourceRoot":"","sources":["../src/readme.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}