@vercel/kv2 0.0.1

package/dist/testing/perf-test.js

@@ -0,0 +1,101 @@
+/**
+ * Performance comparison test: raw blob access vs cached reads
+ */
+import { VercelBlobStore } from "../blob-store.js";
+import { KV2 } from "../cached-kv.js";
+import { cleanupTestBlobs, uniqueTestPrefix } from "./index.js";
+async function readBlobDirect(blobStore, path) {
+    const result = await blobStore.get(path, { access: "public" });
+    if (!result)
+        return null;
+    const chunks = [];
+    const reader = result.stream.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}
+export async function runPerfTest(iterations = 10) {
+    const prefix = uniqueTestPrefix();
+    const blobStore = new VercelBlobStore();
+    const kv = new KV2({ prefix, blobStore });
+    const testValue = {
+        data: "x".repeat(1000), // 1KB payload
+        nested: { deeply: { value: 42 } },
+        array: Array.from({ length: 100 }, (_, i) => i),
+    };
+    // Write test data
+    await kv.set("perf-test-key", testValue, { test: true });
+    const blobPath = `cached-kv/${prefix}perf-test-key`;
+    // Raw blob reads - direct blob store access, bypasses all caching
+    const rawBlobReads = [];
+    for (let i = 0; i < iterations; i++) {
+        const start = performance.now();
+        const buffer = await readBlobDirect(blobStore, blobPath);
+        if (buffer) {
+            // Parse the blob to simulate full read
+            const headerLength = buffer.readUInt32BE(0);
+            const headerJson = buffer.subarray(4, 4 + headerLength).toString("utf-8");
+            JSON.parse(headerJson);
+        }
+        rawBlobReads.push(performance.now() - start);
+    }
+    // Cached reads via KV2 - uses @vercel/functions cache
+    const cachedReads = [];
+    // First read to populate cache
+    const warmup = await kv.get("perf-test-key");
+    if (warmup.exists)
+        await warmup.value;
+    for (let i = 0; i < iterations; i++) {
+        const start = performance.now();
+        const result = await kv.get("perf-test-key");
+        if (result.exists) {
+            await result.value;
+        }
+        cachedReads.push(performance.now() - start);
+    }
+    // Cleanup
+    await cleanupTestBlobs(prefix, blobStore);
+    // Calculate stats
+    const rawBlobAvg = rawBlobReads.reduce((a, b) => a + b, 0) / rawBlobReads.length;
+    const cachedAvg = cachedReads.reduce((a, b) => a + b, 0) / cachedReads.length;
+    const speedup = rawBlobAvg / cachedAvg;
+    const summary = [
+        "",
+        "=".repeat(60),
+        "PERFORMANCE COMPARISON: Raw Blob vs Cached Reads",
+        "=".repeat(60),
+        "",
+        `Iterations: ${iterations}`,
+        "Payload size: ~1KB JSON",
+        "",
+        "Direct Blob Store Reads (no cache):",
+        `  Average: ${rawBlobAvg.toFixed(2)}ms`,
+        `  Min: ${Math.min(...rawBlobReads).toFixed(2)}ms`,
+        `  Max: ${Math.max(...rawBlobReads).toFixed(2)}ms`,
+        `  All: [${rawBlobReads.map((r) => `${r.toFixed(0)}ms`).join(", ")}]`,
+        "",
+        "KV2 Reads (with regional cache):",
+        `  Average: ${cachedAvg.toFixed(2)}ms`,
+        `  Min: ${Math.min(...cachedReads).toFixed(2)}ms`,
+        `  Max: ${Math.max(...cachedReads).toFixed(2)}ms`,
+        `  All: [${cachedReads.map((r) => `${r.toFixed(0)}ms`).join(", ")}]`,
+        "",
+        "-".repeat(60),
+        `SPEEDUP: ${speedup.toFixed(1)}x faster with cache`,
+        "-".repeat(60),
+        "",
+    ].join("\n");
+    return {
+        rawBlobReads,
+        cachedReads,
+        rawBlobAvg,
+        cachedAvg,
+        speedup,
+        summary,
+    };
+}
+//# sourceMappingURL=perf-test.js.map

package/dist/testing/perf-test.js.map

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

package/dist/testing/run-tests.d.ts

@@ -0,0 +1,2 @@
+import "./test-index.js";
+//# sourceMappingURL=run-tests.d.ts.map

package/dist/testing/run-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-tests.d.ts","sourceRoot":"","sources":["../../src/testing/run-tests.ts"],"names":[],"mappings":"AAiHA,OAAO,iBAAiB,CAAC"}

package/dist/testing/run-tests.js

@@ -0,0 +1,141 @@
+// Load environment variables from .env.local before anything else
+import dotenv from "dotenv";
+dotenv.config({ path: ".env.local" });
+import fs from "node:fs";
+import path from "node:path";
+import { printTimingStats, useRealBlobStore, validateIntegrationTestEnv, } from "./index.js";
+import { runTests } from "./vitest-compat.js";
+/**
+ * Finds all *.test.ts files in src/ directory recursively.
+ */
+function findTestFiles(dir) {
+    const results = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory() && entry.name !== "node_modules") {
+            results.push(...findTestFiles(fullPath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".test.ts")) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+/**
+ * Extracts imported test file paths from test-index.ts content.
+ */
+function extractImportedTests(indexContent) {
+    const imports = new Set();
+    const importRegex = /import\s+["']([^"']+\.test\.js)["']/g;
+    for (const match of indexContent.matchAll(importRegex)) {
+        // Convert ./foo.test.js to foo.test.ts
+        const importPath = match[1].replace(/\.js$/, ".ts");
+        imports.add(importPath);
+    }
+    return imports;
+}
+/**
+ * Checks that all test files are imported in test-index.ts.
+ * Only runs when VERCEL_ENV is not set (local development).
+ */
+function checkAllTestsImported() {
+    if (process.env.VERCEL_ENV) {
+        return; // Skip on Vercel deployments
+    }
+    // import.meta.url points to dist/testing/, we need src/testing/
+    const distTestingDir = path.dirname(new URL(import.meta.url).pathname);
+    const projectRoot = path.dirname(path.dirname(distTestingDir)); // Go up from dist/testing/ to project root
+    const srcDir = path.join(projectRoot, "src");
+    const testIndexPath = path.join(srcDir, "testing", "test-index.ts");
+    // Find all test files
+    const allTestFiles = findTestFiles(srcDir);
+    // Read test-index.ts and extract imports
+    const indexContent = fs.readFileSync(testIndexPath, "utf-8");
+    const importedTests = extractImportedTests(indexContent);
+    // Normalize paths relative to test-index.ts location
+    const testIndexDir = path.dirname(testIndexPath);
+    const missingTests = [];
+    for (const testFile of allTestFiles) {
+        // Skip test-index.ts itself and vitest-compat tests
+        if (testFile.includes("test-index") || testFile.includes("vitest-compat")) {
+            continue;
+        }
+        // Convert absolute path to relative import path from test-index.ts
+        const relativePath = path.relative(testIndexDir, testFile);
+        const importPath = relativePath.startsWith(".")
+            ? relativePath
+            : `./${relativePath}`;
+        // Normalize for comparison (../ prefix for files in parent dir)
+        const normalizedImport = importPath.replace(/\\/g, "/");
+        if (!importedTests.has(normalizedImport)) {
+            missingTests.push(testFile);
+        }
+    }
+    if (missingTests.length > 0) {
+        console.error("\x1b[31m=== Missing Test Imports ===\x1b[0m");
+        console.error("The following test files are not imported in test-index.ts:");
+        for (const file of missingTests) {
+            console.error(`  - ${path.relative(srcDir, file)}`);
+        }
+        console.error("\nAdd them to src/testing/test-index.ts");
+        process.exit(1);
+    }
+}
+// Check all tests are imported (local dev only)
+checkAllTestsImported();
+// Validate env vars before loading tests
+validateIntegrationTestEnv();
+import "./test-index.js";
+// Support filtering: `pnpm test -- <filter>`
+// Matches against the full test name (suite > test name).
+const filter = process.argv.filter((a) => a !== "--").slice(2)[0] || undefined;
+if (filter) {
+    console.log(`\x1b[36mFilter: ${filter}\x1b[0m\n`);
+}
+// All tests use isolated context, safe for concurrent execution.
+const concurrency = 30;
+const results = await runTests({
+    filter,
+    concurrency,
+    keepAliveInterval: 5000, // 5 seconds
+    onKeepAlive: (testName, elapsedMs) => {
+        const elapsedSec = Math.floor(elapsedMs / 1000);
+        console.log(`\x1b[33m⏳ [${elapsedSec}s] Still running: ${testName}\x1b[0m`);
+    },
+    onProgress: (result) => {
+        const suitePath = result.suite.join(" > ");
+        const fullName = suitePath ? `${suitePath} > ${result.name}` : result.name;
+        const status = result.passed
+            ? "\x1b[32m✓ PASS\x1b[0m"
+            : "\x1b[31m✗ FAIL\x1b[0m";
+        console.log(`${status} ${fullName} (${result.duration}ms)`);
+        if (!result.passed && result.error) {
+            console.log(`  \x1b[31m${result.error}\x1b[0m`);
+        }
+    },
+});
+console.log("\n=== Test Results ===");
+console.log("Total:", results.total);
+console.log("\x1b[32mPassed:", results.passed, "\x1b[0m");
+if (results.failed > 0) {
+    console.log("\x1b[31mFailed:", results.failed, "\x1b[0m");
+}
+const failures = results.results.filter((r) => !r.passed);
+if (failures.length > 0) {
+    console.log("\n=== FAILURES ===");
+    for (const f of failures) {
+        const suitePath = f.suite.join(" > ");
+        const fullName = suitePath ? `${suitePath} > ${f.name}` : f.name;
+        console.log(`\x1b[31m✗ FAIL ${fullName}\x1b[0m`);
+        if (f.error) {
+            console.log(`  ${f.error}`);
+        }
+    }
+}
+// Print timing stats for integration tests
+if (useRealBlobStore()) {
+    printTimingStats();
+}
+process.exit(results.failed > 0 ? 1 : 0);
+//# sourceMappingURL=run-tests.js.map

package/dist/testing/run-tests.js.map

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

package/dist/testing/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/testing/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/testing/setup.ts"],"names":[],"mappings":""}

package/dist/testing/setup.js

@@ -0,0 +1,3 @@
+import { config } from "dotenv";
+config({ path: ".env.local" });
+//# sourceMappingURL=setup.js.map

package/dist/testing/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/testing/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC"}

package/dist/testing/test-index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Test index - imports all test files to register them with vitest-compat.
+ * Import this file to load all tests before running.
+ */
+import "../blob-format.test.js";
+import "../cache.test.js";
+import "../cached-kv.test.js";
+import "../cached-kv.values.test.js";
+import "../cached-kv.keys.test.js";
+import "../cached-kv.entries.test.js";
+import "../cached-kv.cache.test.js";
+import "../typed-kv.test.js";
+import "../no-metadata.test.js";
+import "../optimistic-locking.test.js";
+import "../schema/schema.test.js";
+import "../manifest-log.test.js";
+import "../upstream-kv.test.js";
+import "../upstream-overlay.test.js";
+import "../create-kv.test.js";
+import "../chaos/boundaries.chaos.test.js";
+import "../chaos/cache.chaos.test.js";
+import "../chaos/concurrency.chaos.test.js";
+import "../chaos/streams.chaos.test.js";
+import "../chaos/malformed.chaos.test.js";
+import "../indexed-kv.test.js";
+import "../cli.test.js";
+import "../readme.test.js";
+//# sourceMappingURL=test-index.d.ts.map

package/dist/testing/test-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-index.d.ts","sourceRoot":"","sources":["../../src/testing/test-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,wBAAwB,CAAC;AAChC,OAAO,kBAAkB,CAAC;AAC1B,OAAO,sBAAsB,CAAC;AAC9B,OAAO,6BAA6B,CAAC;AACrC,OAAO,2BAA2B,CAAC;AACnC,OAAO,8BAA8B,CAAC;AACtC,OAAO,4BAA4B,CAAC;AACpC,OAAO,qBAAqB,CAAC;AAC7B,OAAO,wBAAwB,CAAC;AAChC,OAAO,+BAA+B,CAAC;AAGvC,OAAO,0BAA0B,CAAC;AAGlC,OAAO,yBAAyB,CAAC;AACjC,OAAO,wBAAwB,CAAC;AAChC,OAAO,6BAA6B,CAAC;AACrC,OAAO,sBAAsB,CAAC;AAG9B,OAAO,mCAAmC,CAAC;AAC3C,OAAO,8BAA8B,CAAC;AACtC,OAAO,oCAAoC,CAAC;AAC5C,OAAO,gCAAgC,CAAC;AACxC,OAAO,kCAAkC,CAAC;AAG1C,OAAO,uBAAuB,CAAC;AAG/B,OAAO,gBAAgB,CAAC;AAGxB,OAAO,mBAAmB,CAAC"}

package/dist/testing/test-index.js

@@ -0,0 +1,35 @@
+/**
+ * Test index - imports all test files to register them with vitest-compat.
+ * Import this file to load all tests before running.
+ */
+// Core tests
+import "../blob-format.test.js";
+import "../cache.test.js";
+import "../cached-kv.test.js";
+import "../cached-kv.values.test.js";
+import "../cached-kv.keys.test.js";
+import "../cached-kv.entries.test.js";
+import "../cached-kv.cache.test.js";
+import "../typed-kv.test.js";
+import "../no-metadata.test.js";
+import "../optimistic-locking.test.js";
+// Schema tests
+import "../schema/schema.test.js";
+// CoW / Environment-aware tests
+import "../manifest-log.test.js";
+import "../upstream-kv.test.js";
+import "../upstream-overlay.test.js";
+import "../create-kv.test.js";
+// Chaos tests
+import "../chaos/boundaries.chaos.test.js";
+import "../chaos/cache.chaos.test.js";
+import "../chaos/concurrency.chaos.test.js";
+import "../chaos/streams.chaos.test.js";
+import "../chaos/malformed.chaos.test.js";
+// TypedKV index tests
+import "../indexed-kv.test.js";
+// CLI tests
+import "../cli.test.js";
+// Documentation tests
+import "../readme.test.js";
+//# sourceMappingURL=test-index.js.map

package/dist/testing/test-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-index.js","sourceRoot":"","sources":["../../src/testing/test-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,aAAa;AACb,OAAO,wBAAwB,CAAC;AAChC,OAAO,kBAAkB,CAAC;AAC1B,OAAO,sBAAsB,CAAC;AAC9B,OAAO,6BAA6B,CAAC;AACrC,OAAO,2BAA2B,CAAC;AACnC,OAAO,8BAA8B,CAAC;AACtC,OAAO,4BAA4B,CAAC;AACpC,OAAO,qBAAqB,CAAC;AAC7B,OAAO,wBAAwB,CAAC;AAChC,OAAO,+BAA+B,CAAC;AAEvC,eAAe;AACf,OAAO,0BAA0B,CAAC;AAElC,gCAAgC;AAChC,OAAO,yBAAyB,CAAC;AACjC,OAAO,wBAAwB,CAAC;AAChC,OAAO,6BAA6B,CAAC;AACrC,OAAO,sBAAsB,CAAC;AAE9B,cAAc;AACd,OAAO,mCAAmC,CAAC;AAC3C,OAAO,8BAA8B,CAAC;AACtC,OAAO,oCAAoC,CAAC;AAC5C,OAAO,gCAAgC,CAAC;AACxC,OAAO,kCAAkC,CAAC;AAE1C,sBAAsB;AACtB,OAAO,uBAAuB,CAAC;AAE/B,YAAY;AACZ,OAAO,gBAAgB,CAAC;AAExB,sBAAsB;AACtB,OAAO,mBAAmB,CAAC"}

package/dist/testing/test-setup.d.ts

@@ -0,0 +1,32 @@
+import { KV2 } from "../cached-kv.js";
+import type { KV2Options } from "../types.js";
+import { FakeBlobStore } from "./fake-blob-store.js";
+import { type TestContext as BaseTestContext } from "./vitest-compat.js";
+export interface TestMetadata {
+    createdBy: string;
+    version: number;
+}
+/** Context available to each test */
+export interface KVTestContext extends BaseTestContext {
+    kv: KV2<TestMetadata>;
+    blobStore: FakeBlobStore | undefined;
+    cleanup: () => Promise<void>;
+    isReal: boolean;
+}
+/**
+ * Sets up a test context with beforeAll/afterAll/beforeEach/afterEach hooks.
+ * Uses the test context system for concurrent-safe test execution.
+ *
+ * Each test gets its own isolated FakeBlobStore (for unit tests) or
+ * unique prefix (for integration tests) to enable concurrent execution.
+ */
+export declare function setupTestContext(options?: Partial<KV2Options>): void;
+export { createTestKV, uniqueTestPrefix, useRealBlobStore } from "./index.js";
+export type { PrefixString } from "../types.js";
+/** Typed test function that receives KVTestContext */
+type TypedTestFn = (ctx: KVTestContext) => Promise<void> | void;
+/** Typed `it` that provides KVTestContext to tests */
+export declare const it: (name: string, fn: TypedTestFn) => void;
+/** Typed `test` that provides KVTestContext to tests (alias for `it`) */
+export declare const test: (name: string, fn: TypedTestFn) => void;
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/testing/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../../src/testing/test-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EACN,KAAK,WAAW,IAAI,eAAe,EAOnC,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAc,SAAQ,eAAe;IACrD,EAAE,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IACtB,SAAS,EAAE,aAAa,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;CAChB;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAqDpE;AAED,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,sDAAsD;AACtD,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEhE,sDAAsD;AACtD,eAAO,MAAM,EAAE,GAAI,MAAM,MAAM,EAAE,IAAI,WAAW,KAAG,IAElD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,IAAI,SALQ,MAAM,MAAM,WAAW,KAAG,IAK7B,CAAC"}

package/dist/testing/test-setup.js

@@ -0,0 +1,72 @@
+import { KV2 } from "../cached-kv.js";
+import { FakeBlobStore } from "./fake-blob-store.js";
+import { createTestKV, uniqueTestPrefix, useRealBlobStore } from "./index.js";
+import { afterAll, afterEach, it as baseIt, beforeAll, beforeEach, } from "./vitest-compat.js";
+/** Suite-level cleanup functions (not copied to test context) */
+const suiteCleanupFns = new Map();
+/**
+ * Sets up a test context with beforeAll/afterAll/beforeEach/afterEach hooks.
+ * Uses the test context system for concurrent-safe test execution.
+ *
+ * Each test gets its own isolated FakeBlobStore (for unit tests) or
+ * unique prefix (for integration tests) to enable concurrent execution.
+ */
+export function setupTestContext(options) {
+    // Use a unique key for this suite's cleanup functions
+    const suiteKey = Math.random().toString(36).slice(2);
+    beforeAll(() => {
+        suiteCleanupFns.set(suiteKey, []);
+        if (useRealBlobStore()) {
+            console.log("Running tests against REAL blob store");
+        }
+    });
+    beforeEach((ctx) => {
+        const testCtx = ctx;
+        if (useRealBlobStore()) {
+            // For real blob store, each test gets its own unique prefix
+            const result = createTestKV(options);
+            testCtx.kv = result.kv;
+            testCtx.blobStore = undefined;
+            testCtx.cleanup = result.cleanup;
+            testCtx.isReal = true;
+            // Track cleanup for afterAll (thread-safe push)
+            suiteCleanupFns.get(suiteKey)?.push(result.cleanup);
+        }
+        else {
+            // For unit tests, each test gets its own FakeBlobStore for isolation
+            const blobStore = new FakeBlobStore();
+            const prefix = options?.prefix ?? uniqueTestPrefix();
+            testCtx.kv = new KV2({
+                ...options,
+                prefix,
+                blobStore,
+            });
+            testCtx.blobStore = blobStore;
+            testCtx.cleanup = async () => blobStore.clear();
+            testCtx.isReal = false;
+        }
+    });
+    afterEach((ctx) => {
+        const testCtx = ctx;
+        // Clear the blob store after each test
+        if (testCtx.blobStore) {
+            testCtx.blobStore.clear();
+        }
+    });
+    afterAll(async () => {
+        // Clean up all real blob store prefixes created during tests
+        const cleanups = suiteCleanupFns.get(suiteKey) ?? [];
+        for (const cleanup of cleanups) {
+            await cleanup();
+        }
+        suiteCleanupFns.delete(suiteKey);
+    });
+}
+export { createTestKV, uniqueTestPrefix, useRealBlobStore } from "./index.js";
+/** Typed `it` that provides KVTestContext to tests */
+export const it = (name, fn) => {
+    baseIt(name, fn);
+};
+/** Typed `test` that provides KVTestContext to tests (alias for `it`) */
+export const test = it;
+//# sourceMappingURL=test-setup.js.map

package/dist/testing/test-setup.js.map

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

package/dist/testing/upstream-kv-test-setup.d.ts

@@ -0,0 +1,30 @@
+import { KV2 } from "../cached-kv.js";
+import { ManifestLog } from "../manifest-log.js";
+import type { BlobStore } from "../types.js";
+import { UpstreamKV } from "../upstream-kv.js";
+import { type TestContext as BaseTestContext } from "./vitest-compat.js";
+/** Metadata type for UpstreamKV tests */
+interface TestVersionMetadata {
+    version: number;
+}
+/** Context available to each UpstreamKV test */
+export interface UpstreamKVTestContext extends BaseTestContext {
+    blobStore: BlobStore;
+    localKV: KV2<TestVersionMetadata>;
+    upstreamKV: KV2<TestVersionMetadata>;
+    manifest: ManifestLog;
+    kv: UpstreamKV<TestVersionMetadata>;
+    cleanup?: () => Promise<void>;
+}
+/**
+ * Sets up an UpstreamKV test context.
+ * Each test gets its own isolated FakeBlobStore and UpstreamKV.
+ * Uses real blob store if INTEGRATION_TEST=1.
+ */
+export declare function setupUpstreamKVTestContext(): void;
+/** Typed test function that receives UpstreamKVTestContext */
+type TypedTestFn = (ctx: UpstreamKVTestContext) => Promise<void> | void;
+/** Typed `it` that provides UpstreamKVTestContext to tests */
+export declare const it: (name: string, fn: TypedTestFn) => void;
+export {};
+//# sourceMappingURL=upstream-kv-test-setup.d.ts.map

package/dist/testing/upstream-kv-test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-kv-test-setup.d.ts","sourceRoot":"","sources":["../../src/testing/upstream-kv-test-setup.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAS/C,OAAO,EACN,KAAK,WAAW,IAAI,eAAe,EAInC,MAAM,oBAAoB,CAAC;AAE5B,yCAAyC;AACzC,UAAU,mBAAmB;IAC5B,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC7D,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAClC,UAAU,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACrC,QAAQ,EAAE,WAAW,CAAC;IACtB,EAAE,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAqEjD;AAED,8DAA8D;AAC9D,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAExE,8DAA8D;AAC9D,eAAO,MAAM,EAAE,GAAI,MAAM,MAAM,EAAE,IAAI,WAAW,KAAG,IAElD,CAAC"}

package/dist/testing/upstream-kv-test-setup.js

@@ -0,0 +1,66 @@
+import { VercelBlobStore } from "../blob-store.js";
+import { KV2 } from "../cached-kv.js";
+import { ManifestLog } from "../manifest-log.js";
+import { UpstreamKV } from "../upstream-kv.js";
+import { FakeBlobStore } from "./fake-blob-store.js";
+import { FakeCache } from "./fake-cache.js";
+import { cleanupTestBlobs, getStatsTracer, uniqueTestPrefix, useRealBlobStore, } from "./index.js";
+import { afterEach, it as baseIt, beforeEach, } from "./vitest-compat.js";
+/**
+ * Sets up an UpstreamKV test context.
+ * Each test gets its own isolated FakeBlobStore and UpstreamKV.
+ * Uses real blob store if INTEGRATION_TEST=1.
+ */
+export function setupUpstreamKVTestContext() {
+    beforeEach((ctx) => {
+        const testCtx = ctx;
+        if (useRealBlobStore()) {
+            // Integration test: use real blob store with unique prefix and stats tracer
+            const prefix = uniqueTestPrefix();
+            const tracer = getStatsTracer();
+            testCtx.blobStore = new VercelBlobStore();
+            testCtx.localKV = new KV2({
+                prefix: `${prefix}local/`,
+                blobStore: testCtx.blobStore,
+                tracer,
+            });
+            testCtx.upstreamKV = new KV2({
+                prefix: `${prefix}upstream/`,
+                blobStore: testCtx.blobStore,
+                tracer,
+            });
+            testCtx.manifest = new ManifestLog(testCtx.blobStore, `${prefix}_manifest/`);
+            testCtx.kv = new UpstreamKV(testCtx.localKV, testCtx.upstreamKV, testCtx.manifest);
+            testCtx.cleanup = () => cleanupTestBlobs(prefix, testCtx.blobStore);
+        }
+        else {
+            // Unit test: use fakes
+            testCtx.blobStore = new FakeBlobStore();
+            const cache = new FakeCache();
+            testCtx.localKV = new KV2({
+                prefix: "local/",
+                blobStore: testCtx.blobStore,
+                cache,
+            });
+            testCtx.upstreamKV = new KV2({
+                prefix: "upstream/",
+                blobStore: testCtx.blobStore,
+                cache,
+            });
+            // Manifest uses a separate namespace to avoid being listed with data keys
+            testCtx.manifest = new ManifestLog(testCtx.blobStore, "_manifest/local/", cache);
+            testCtx.kv = new UpstreamKV(testCtx.localKV, testCtx.upstreamKV, testCtx.manifest);
+        }
+    });
+    afterEach(async (ctx) => {
+        const testCtx = ctx;
+        if (testCtx.cleanup) {
+            await testCtx.cleanup();
+        }
+    });
+}
+/** Typed `it` that provides UpstreamKVTestContext to tests */
+export const it = (name, fn) => {
+    baseIt(name, fn);
+};
+//# sourceMappingURL=upstream-kv-test-setup.js.map

package/dist/testing/upstream-kv-test-setup.js.map

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