@vercel/kv2 0.0.1

package/dist/readme.test.js

@@ -0,0 +1,285 @@
+/**
+ * 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
+ */
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { describe, expect, it } from "./testing/vitest-compat.js";
+const README_PATH = path.join(import.meta.dirname, "..", "README.md");
+const DOCS_DIR = path.join(import.meta.dirname, "..", "docs");
+function parseMarkdown(filePath) {
+    return fs.readFileSync(filePath, "utf-8");
+}
+/**
+ * Get all docs/*.md files sorted by name
+ */
+function getDocFiles() {
+    if (!fs.existsSync(DOCS_DIR))
+        return [];
+    return fs
+        .readdirSync(DOCS_DIR)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .map((f) => path.join(DOCS_DIR, f));
+}
+/**
+ * Extract TypeScript code blocks from markdown
+ */
+function extractTypeScriptBlocks(content) {
+    const blocks = [];
+    const pattern = /```typescript\n([\s\S]*?)```/g;
+    for (const match of content.matchAll(pattern)) {
+        blocks.push(match[1]);
+    }
+    return blocks;
+}
+/**
+ * Rename duplicate const/let declarations to avoid redeclaration errors
+ */
+function renameDuplicateDeclarations(code) {
+    const varCounts = new Map();
+    return code.replace(/\b(const|let)\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=/g, (match, keyword, varName) => {
+        const count = (varCounts.get(varName) || 0) + 1;
+        varCounts.set(varName, count);
+        if (count > 1) {
+            return `${keyword} ${varName}_${count} =`;
+        }
+        return match;
+    });
+}
+/**
+ * Add implied imports and wrap in async IIFE
+ */
+function addImpliedImports(code) {
+    // Rewrite package imports to local path aliases
+    code = code.replace(/"@vercel\/kv2\/testing"/g, '"kv/testing"');
+    code = code.replace(/'@vercel\/kv2\/testing'/g, "'kv/testing'");
+    code = code.replace(/"@vercel\/kv2"/g, '"kv"');
+    code = code.replace(/'@vercel\/kv2'/g, "'kv'");
+    // Symbols auto-imported from "kv"
+    const kvSymbols = [
+        "createKV",
+        "KV2",
+        "TypedKV",
+        "UpstreamKV",
+        "KVVersionConflictError",
+        "KVIndexConflictError",
+        "defineSchema",
+        "createSchemaKV",
+        "noopTracer",
+        "consoleTracer",
+        "createOtelTracer",
+        "createStatsTracer",
+    ];
+    // Symbols auto-imported from "kv/testing"
+    const testingSymbols = ["FakeBlobStore", "FakeCache", "createTestKV"];
+    // Check which symbols are used but not explicitly imported
+    const kvNeeded = [];
+    const testingNeeded = [];
+    for (const sym of kvSymbols) {
+        if (code.includes(sym) &&
+            !new RegExp(`import\\s*\\{[^}]*\\b${sym}\\b[^}]*\\}\\s*from\\s*["']kv["']`).test(code) &&
+            !new RegExp(`import\\s*\\(\\s*["']kv["']\\s*\\)\\.${sym}`).test(code)) {
+            kvNeeded.push(sym);
+        }
+    }
+    for (const sym of testingSymbols) {
+        if (code.includes(sym) &&
+            !new RegExp(`import\\s*\\{[^}]*\\b${sym}\\b[^}]*\\}\\s*from\\s*["']kv/testing["']`).test(code)) {
+            testingNeeded.push(sym);
+        }
+    }
+    const imports = [];
+    if (kvNeeded.length > 0) {
+        imports.push(`import { ${kvNeeded.join(", ")} } from "kv";`);
+    }
+    if (testingNeeded.length > 0) {
+        imports.push(`import { ${testingNeeded.join(", ")} } from "kv/testing";`);
+    }
+    // Extract existing imports from code
+    const existingImports = code.match(/^import .*/gm) || [];
+    const codeWithoutImports = code.replace(/^import .*\n?/gm, "").trim();
+    // Combine all imports (existing first, then implied)
+    const allImports = [...existingImports, ...imports];
+    // Rename duplicate variable declarations
+    const scopedCode = renameDuplicateDeclarations(codeWithoutImports);
+    // Wrap non-import code in async IIFE
+    const wrappedCode = `(async () => {\n${scopedCode}\n})();`;
+    if (allImports.length === 0) {
+        return wrappedCode;
+    }
+    return `${allImports.join("\n")}\n\n${wrappedCode}`;
+}
+/**
+ * Compile TypeScript blocks in a single tsc invocation
+ */
+function compileTypeScriptBlocks(blocks, filePrefix = "example") {
+    const tmpDir = path.join(import.meta.dirname, "..", ".docs-test-tmp");
+    fs.mkdirSync(tmpDir, { recursive: true });
+    try {
+        const files = [];
+        // Write all blocks to files
+        for (let i = 0; i < blocks.length; i++) {
+            const code = addImpliedImports(blocks[i]);
+            const fileName = `${filePrefix}-${i}.ts`;
+            const filePath = path.join(tmpDir, fileName);
+            fs.writeFileSync(filePath, code);
+            files.push(filePath);
+        }
+        if (files.length === 0)
+            return;
+        // Create ephemeral type definitions for types assumed in examples
+        const ephemeralTypes = `
+// Types commonly used in README and docs examples
+interface User {
+  name: string;
+  email: string;
+}
+
+interface Post {
+  title: string;
+  content: string;
+}
+
+interface Metadata {
+  updatedAt: number;
+  version: number;
+}
+
+interface Board {
+  name: string;
+}
+
+interface Column {
+  name: string;
+  order: number;
+}
+
+interface Task {
+  title: string;
+  done: boolean;
+}
+
+// Doc-specific types
+interface Doc {
+  slug: string;
+  status: string;
+  tags: string[];
+  title: string;
+  content: string;
+  authorId: string;
+}
+
+// Ambient variables for examples that don't define their own
+declare const kv: import("kv").KV2<any>;
+declare const users: import("kv").TypedKV<User, any>;
+declare const posts: import("kv").TypedKV<Post, any>;
+declare const docs: import("kv").TypedKV<Doc, any, "bySlug" | "byStatus" | "byTag">;
+declare const metadata: any;
+declare const userData: any;
+declare const entry: import("kv").KVEntry<any, any>;
+declare const newValue: any;
+declare const docData: Doc;
+`;
+        fs.writeFileSync(path.join(tmpDir, "example-types.d.ts"), ephemeralTypes);
+        // Create tsconfig for type checking
+        const tsconfig = {
+            compilerOptions: {
+                target: "ES2022",
+                module: "NodeNext",
+                moduleResolution: "NodeNext",
+                strict: true,
+                skipLibCheck: true,
+                noEmit: true,
+                esModuleInterop: true,
+                paths: {
+                    kv: [path.join(import.meta.dirname, "index.ts")],
+                    "kv/testing": [path.join(import.meta.dirname, "testing", "index.ts")],
+                },
+            },
+            include: [...files, path.join(tmpDir, "example-types.d.ts")],
+        };
+        fs.writeFileSync(path.join(tmpDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
+        // Run tsc to check all files
+        try {
+            execSync("npx tsc --project tsconfig.json", {
+                cwd: tmpDir,
+                encoding: "utf-8",
+                stdio: "pipe",
+            });
+        }
+        catch (error) {
+            const execError = error;
+            const output = execError.stdout || execError.stderr || "";
+            // Parse errors
+            const errorLines = output
+                .split("\n")
+                .filter((line) => line.includes("error TS"));
+            if (errorLines.length > 0) {
+                throw new Error(`TypeScript errors in ${filePrefix} examples:\n${errorLines.slice(0, 10).join("\n")}` +
+                    (errorLines.length > 10
+                        ? `\n... and ${errorLines.length - 10} more`
+                        : ""));
+            }
+        }
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+describe("README validation", () => {
+    it("should have TypeScript code blocks", () => {
+        const readme = parseMarkdown(README_PATH);
+        const blocks = extractTypeScriptBlocks(readme);
+        expect(blocks.length).toBeGreaterThan(0);
+    });
+    it("should document KVLike interface methods", () => {
+        const readme = parseMarkdown(README_PATH);
+        const requiredMethods = [
+            "get",
+            "set",
+            "delete",
+            "keys",
+            "entries",
+            "getMany",
+        ];
+        for (const method of requiredMethods) {
+            expect(readme).toContain(method);
+        }
+    });
+    it("should document createKV options", () => {
+        const readme = parseMarkdown(README_PATH);
+        expect(readme).toContain("prefix");
+        expect(readme).toContain("upstream");
+    });
+    it("should have valid TypeScript syntax in all examples", () => {
+        const readme = parseMarkdown(README_PATH);
+        const blocks = extractTypeScriptBlocks(readme);
+        compileTypeScriptBlocks(blocks, "readme-example");
+    });
+});
+describe("docs/ validation", () => {
+    const docFiles = getDocFiles();
+    it("should have doc files", () => {
+        expect(docFiles.length).toBeGreaterThan(0);
+    });
+    for (const docFile of docFiles) {
+        const basename = path.basename(docFile);
+        it(`${basename} should have valid markdown`, () => {
+            const content = parseMarkdown(docFile);
+            expect(content.length).toBeGreaterThan(0);
+        });
+        it(`${basename} should have valid TypeScript syntax`, () => {
+            const content = parseMarkdown(docFile);
+            const blocks = extractTypeScriptBlocks(content);
+            if (blocks.length > 0) {
+                compileTypeScriptBlocks(blocks, `doc-${basename.replace(".md", "")}`);
+            }
+        });
+    }
+});
+//# sourceMappingURL=readme.test.js.map

package/dist/readme.test.js.map

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

package/dist/schema/define-schema.d.ts

@@ -0,0 +1,35 @@
+import type { SchemaDef, SchemaNodeDef } from "./types.js";
+/**
+ * Define a schema for hierarchical KV entities.
+ *
+ * @param prefix - Root prefix for all keys (should end with "/")
+ * @param entities - Entity definitions with patterns and types
+ * @returns Schema definition for use with createSchemaKV()
+ *
+ * @example
+ * ```ts
+ * const schema = defineSchema("boards/", {
+ *   boards: {
+ *     pattern: "*",
+ *     value: {} as Board,
+ *     metadata: {} as BoardMeta,
+ *     children: {
+ *       columns: {
+ *         pattern: "columns/*",
+ *         value: {} as Column,
+ *         metadata: {} as ColumnMeta,
+ *         children: {
+ *           tasks: {
+ *             pattern: "tasks/*",
+ *             value: {} as Task,
+ *             metadata: {} as TaskMeta,
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function defineSchema<const P extends string, const E extends Record<string, SchemaNodeDef<any, any, any>>>(prefix: P, entities: E): SchemaDef<P, E>;
+//# sourceMappingURL=define-schema.d.ts.map

package/dist/schema/define-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.d.ts","sourceRoot":"","sources":["../../src/schema/define-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAC3B,KAAK,CAAC,CAAC,SAAS,MAAM,EAEtB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAC3D,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAQzC"}

package/dist/schema/define-schema.js

@@ -0,0 +1,70 @@
+/**
+ * Define a schema for hierarchical KV entities.
+ *
+ * @param prefix - Root prefix for all keys (should end with "/")
+ * @param entities - Entity definitions with patterns and types
+ * @returns Schema definition for use with createSchemaKV()
+ *
+ * @example
+ * ```ts
+ * const schema = defineSchema("boards/", {
+ *   boards: {
+ *     pattern: "*",
+ *     value: {} as Board,
+ *     metadata: {} as BoardMeta,
+ *     children: {
+ *       columns: {
+ *         pattern: "columns/*",
+ *         value: {} as Column,
+ *         metadata: {} as ColumnMeta,
+ *         children: {
+ *           tasks: {
+ *             pattern: "tasks/*",
+ *             value: {} as Task,
+ *             metadata: {} as TaskMeta,
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function defineSchema(prefix, entities) {
+    // Validate the schema
+    validateSchema(entities);
+    return {
+        prefix,
+        entities,
+    };
+}
+/**
+ * Validates schema definition for common errors.
+ */
+function validateSchema(entities) {
+    for (const [name, node] of Object.entries(entities)) {
+        validateNode(name, node, []);
+    }
+}
+function validateNode(name, node, parentPath) {
+    const fullPath = [...parentPath, name].join(".");
+    // Validate pattern
+    if (!node.pattern) {
+        throw new Error(`Schema node "${fullPath}" is missing a pattern`);
+    }
+    // Pattern should be "*" or "prefix/*"
+    if (node.pattern !== "*" && !node.pattern.endsWith("/*")) {
+        throw new Error(`Schema node "${fullPath}" has invalid pattern "${node.pattern}". ` +
+            `Pattern must be "*" or end with "/*".`);
+    }
+    // Validate children recursively
+    if (node.children) {
+        for (const [childName, childNode] of Object.entries(node.children)) {
+            validateNode(childName, childNode, [
+                ...parentPath,
+                name,
+            ]);
+        }
+    }
+}
+//# sourceMappingURL=define-schema.js.map

package/dist/schema/define-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.js","sourceRoot":"","sources":["../../src/schema/define-schema.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,YAAY,CAI1B,MAAS,EAAE,QAAW;IACvB,sBAAsB;IACtB,cAAc,CAAC,QAAQ,CAAC,CAAC;IAEzB,OAAO;QACN,MAAM;QACN,QAAQ;KACR,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,QAAuC;IAC9D,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC9B,CAAC;AACF,CAAC;AAED,SAAS,YAAY,CACpB,IAAY,EACZ,IAAmB,EACnB,UAAoB;IAEpB,MAAM,QAAQ,GAAG,CAAC,GAAG,UAAU,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjD,mBAAmB;IACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,gBAAgB,QAAQ,wBAAwB,CAAC,CAAC;IACnE,CAAC;IAED,sCAAsC;IACtC,IAAI,IAAI,CAAC,OAAO,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACd,gBAAgB,QAAQ,0BAA0B,IAAI,CAAC,OAAO,KAAK;YAClE,uCAAuC,CACxC,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpE,YAAY,CAAC,SAAS,EAAE,SAA0B,EAAE;gBACnD,GAAG,UAAU;gBACb,IAAI;aACJ,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/schema/index.d.ts

@@ -0,0 +1,4 @@
+export { defineSchema } from "./define-schema.js";
+export { createSchemaKV } from "./schema-kv.js";
+export type { SchemaNodeDef, SchemaDef, TreeNode, TreeNodeIterator, TreeNodePage, TreeNodeWithChildren, KeyBuilders, SchemaKV, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,YAAY,EACX,aAAa,EACb,SAAS,EACT,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,QAAQ,GACR,MAAM,YAAY,CAAC"}

package/dist/schema/index.js

@@ -0,0 +1,5 @@
+// Schema definition
+export { defineSchema } from "./define-schema.js";
+// Schema KV
+export { createSchemaKV } from "./schema-kv.js";
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/schema/key-builders.d.ts

@@ -0,0 +1,40 @@
+import type { KeyBuilders, SchemaDef, SchemaNodeDef } from "./types.js";
+/**
+ * Create type-safe key builder functions from a schema.
+ *
+ * Each entity in the schema gets a key builder function that takes
+ * the appropriate ID arguments and returns the full key path.
+ *
+ * @example
+ * ```ts
+ * const key = createKeyBuilders(schema);
+ *
+ * key.boards("board-1")                    // → "board-1"
+ * key.columns("board-1", "col-1")          // → "board-1/columns/col-1"
+ * key.tasks("board-1", "col-1", "task-1")  // → "board-1/columns/col-1/tasks/task-1"
+ * ```
+ */
+export declare function createKeyBuilders<P extends string, E extends Record<string, SchemaNodeDef<any, any, any>>>(schema: SchemaDef<P, E>): KeyBuilders<E>;
+/**
+ * Create a regex pattern for matching keys of a specific entity type.
+ *
+ * Used internally to filter keys from a keys() call by entity type.
+ *
+ * @param node - The schema node to create a pattern for
+ * @param parentPatterns - Patterns from ancestor nodes
+ * @returns RegExp that matches keys of this entity type
+ *
+ * @example
+ * ```ts
+ * // For columns under a board:
+ * // parentPatterns = ["*"], pattern = "columns/*"
+ * // → /^([^/]+)\/columns\/([^/]+)$/
+ * ```
+ */
+export declare function createKeyPattern(node: SchemaNodeDef, parentPatterns: string[]): RegExp;
+/**
+ * Extract the ID from a key given a regex pattern.
+ * Returns the last capture group (the entity's own ID).
+ */
+export declare function extractIdFromKey(key: string, pattern: RegExp): string | null;
+//# sourceMappingURL=key-builders.d.ts.map

package/dist/schema/key-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-builders.d.ts","sourceRoot":"","sources":["../../src/schema/key-builders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAChC,CAAC,SAAS,MAAM,EAEhB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EACrD,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAQzC;AAoED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,aAAa,EACnB,cAAc,EAAE,MAAM,EAAE,GACtB,MAAM,CAiBR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5E"}

package/dist/schema/key-builders.js

@@ -0,0 +1,124 @@
+/**
+ * Create type-safe key builder functions from a schema.
+ *
+ * Each entity in the schema gets a key builder function that takes
+ * the appropriate ID arguments and returns the full key path.
+ *
+ * @example
+ * ```ts
+ * const key = createKeyBuilders(schema);
+ *
+ * key.boards("board-1")                    // → "board-1"
+ * key.columns("board-1", "col-1")          // → "board-1/columns/col-1"
+ * key.tasks("board-1", "col-1", "task-1")  // → "board-1/columns/col-1/tasks/task-1"
+ * ```
+ */
+export function createKeyBuilders(schema) {
+    const builders = {};
+    for (const [name, node] of Object.entries(schema.entities)) {
+        builders[name] = createNodeKeyBuilder(node, [], name);
+    }
+    return builders;
+}
+/**
+ * Creates a key builder for a single node, including nested child builders.
+ */
+function createNodeKeyBuilder(node, parentPatterns, name) {
+    // Build the key function
+    const keyFn = createKeyFunction(node.pattern, parentPatterns);
+    // Add child builders as properties on the function
+    if (node.children) {
+        const currentPatterns = [...parentPatterns, node.pattern];
+        for (const [childName, childNode] of Object.entries(node.children)) {
+            keyFn[childName] =
+                createNodeKeyBuilder(childNode, currentPatterns, childName);
+        }
+    }
+    return keyFn;
+}
+/**
+ * Creates the actual key function for a pattern.
+ */
+function createKeyFunction(pattern, parentPatterns) {
+    // Count total wildcards in parent patterns + this pattern
+    const allPatterns = [...parentPatterns, pattern];
+    return (...ids) => {
+        let idIndex = 0;
+        const segments = [];
+        for (const p of allPatterns) {
+            if (p === "*") {
+                // Single wildcard at this level
+                if (idIndex >= ids.length) {
+                    throw new Error(`Missing ID argument at position ${idIndex}`);
+                }
+                segments.push(ids[idIndex++]);
+            }
+            else if (p.endsWith("/*")) {
+                // Pattern with prefix like "columns/*"
+                const prefix = p.slice(0, -2); // Remove "/*"
+                segments.push(prefix);
+                if (idIndex >= ids.length) {
+                    throw new Error(`Missing ID argument at position ${idIndex}`);
+                }
+                segments.push(ids[idIndex++]);
+            }
+            else {
+                // Static pattern (no wildcard)
+                segments.push(p);
+            }
+        }
+        return segments.join("/");
+    };
+}
+/**
+ * Create a regex pattern for matching keys of a specific entity type.
+ *
+ * Used internally to filter keys from a keys() call by entity type.
+ *
+ * @param node - The schema node to create a pattern for
+ * @param parentPatterns - Patterns from ancestor nodes
+ * @returns RegExp that matches keys of this entity type
+ *
+ * @example
+ * ```ts
+ * // For columns under a board:
+ * // parentPatterns = ["*"], pattern = "columns/*"
+ * // → /^([^/]+)\/columns\/([^/]+)$/
+ * ```
+ */
+export function createKeyPattern(node, parentPatterns) {
+    const allPatterns = [...parentPatterns, node.pattern];
+    const regexParts = [];
+    for (const p of allPatterns) {
+        if (p === "*") {
+            regexParts.push("([^/]+)");
+        }
+        else if (p.endsWith("/*")) {
+            const prefix = p.slice(0, -2);
+            regexParts.push(escapeRegex(prefix));
+            regexParts.push("([^/]+)");
+        }
+        else {
+            regexParts.push(escapeRegex(p));
+        }
+    }
+    return new RegExp(`^${regexParts.join("/")}$`);
+}
+/**
+ * Extract the ID from a key given a regex pattern.
+ * Returns the last capture group (the entity's own ID).
+ */
+export function extractIdFromKey(key, pattern) {
+    const match = key.match(pattern);
+    if (!match)
+        return null;
+    // Return the last captured group (the entity's own ID)
+    return match[match.length - 1];
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=key-builders.js.map

package/dist/schema/key-builders.js.map

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

package/dist/schema/schema-kv.d.ts

@@ -0,0 +1,48 @@
+import type { KVLike } from "../types.js";
+import type { SchemaDef, SchemaKV, SchemaNodeDef } from "./types.js";
+/**
+ * Create a schema-aware KV interface.
+ *
+ * Provides type-safe operations with key builders and lazy tree iteration.
+ *
+ * @param schema - Schema definition from defineSchema()
+ * @param kv - Underlying KV store (typically from kv.getStore())
+ * @returns SchemaKV interface with type-safe operations
+ *
+ * @example
+ * ```ts
+ * const schema = defineSchema("boards/", {
+ *   boards: {
+ *     pattern: "*",
+ *     value: {} as Board,
+ *     metadata: {} as BoardMeta,
+ *     children: {
+ *       columns: {
+ *         pattern: "columns/*",
+ *         value: {} as Column,
+ *         children: {
+ *           tasks: { pattern: "tasks/*", value: {} as Task }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const kv = createSchemaKV(schema, rawKV.getStore("boards/"));
+ *
+ * // Type-safe key builders
+ * kv.key.boards("board-1")                    // → "board-1"
+ * kv.key.columns("board-1", "col-1")          // → "board-1/columns/col-1"
+ *
+ * // Lazy tree with batched fetching
+ * const board = await kv.tree("boards", "board-1");
+ * for await (const col of board.columns) {
+ *   console.log(col.value.name);
+ *   for await (const task of col.tasks) {
+ *     console.log(task.value.title);
+ *   }
+ * }
+ * ```
+ */
+export declare function createSchemaKV<P extends string, E extends Record<string, SchemaNodeDef<any, any, any>>>(schema: SchemaDef<P, E>, kv: KVLike<unknown>): SchemaKV<P, E>;
+//# sourceMappingURL=schema-kv.d.ts.map

package/dist/schema/schema-kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-kv.d.ts","sourceRoot":"","sources":["../../src/schema/schema-kv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAC7B,CAAC,SAAS,MAAM,EAEhB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EACrD,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAoF9D"}