@vercel/kv2 0.0.1

package/dist/schema/schema-kv.js

@@ -0,0 +1,96 @@
+import { createKeyBuilders } from "./key-builders.js";
+import { buildTree } from "./tree.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 function createSchemaKV(schema, kv) {
+    const keyBuilders = createKeyBuilders(schema);
+    // Implementation uses `any` internally for simpler code,
+    // but the public interface is fully type-safe via SchemaKV<P, E>
+    const impl = {
+        raw: kv,
+        key: keyBuilders,
+        async tree(type, ...ids) {
+            const node = schema.entities[type];
+            if (!node) {
+                throw new Error(`Unknown entity type: ${type}`);
+            }
+            // Build the root key using the key builder
+            const keyBuilder = keyBuilders[type];
+            const rootKey = keyBuilder(...ids);
+            // The root ID is the last ID provided
+            const rootId = ids[ids.length - 1] || rootKey;
+            // SINGLE keys() call to get all descendant keys
+            const allKeys = [rootKey];
+            for await (const key of kv.keys(`${rootKey}/`)) {
+                allKeys.push(key);
+            }
+            // Build the tree with lazy child iterators
+            return buildTree(kv, allKeys, rootKey, rootId, node);
+        },
+        async get(type, ...ids) {
+            const keyBuilder = keyBuilders[type];
+            const key = keyBuilder(...ids);
+            const result = await kv.get(key);
+            if (!result.exists)
+                return null;
+            return {
+                value: await result.value,
+                metadata: result.metadata,
+            };
+        },
+        async set(type, value, metadata, ...ids) {
+            const keyBuilder = keyBuilders[type];
+            const key = keyBuilder(...ids);
+            await kv.set(key, value, metadata);
+        },
+        async delete(type, ...ids) {
+            const keyBuilder = keyBuilders[type];
+            const key = keyBuilder(...ids);
+            await kv.delete(key);
+        },
+    };
+    return impl;
+}
+//# sourceMappingURL=schema-kv.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema-kv.js","sourceRoot":"","sources":["../../src/schema/schema-kv.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,cAAc,CAI5B,MAAuB,EAAE,EAAmB;IAC7C,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE9C,yDAAyD;IACzD,iEAAiE;IACjE,MAAM,IAAI,GAAG;QACZ,GAAG,EAAE,EAAE;QACP,GAAG,EAAE,WAAW;QAEhB,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,GAAG,GAAa;YACxC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAkB,CAAC;YACpD,IAAI,CAAC,IAAI,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;YACjD,CAAC;YAED,2CAA2C;YAC3C,MAAM,UAAU,GACf,WACA,CAAC,IAAI,CAAC,CAAC;YACR,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;YAEnC,sCAAsC;YACtC,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC;YAE9C,gDAAgD;YAChD,MAAM,OAAO,GAAa,CAAC,OAAO,CAAC,CAAC;YACpC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;YAED,2CAA2C;YAC3C,OAAO,SAAS,CACf,EAAE,EACF,OAAO,EACP,OAAO,EACP,MAAM,EACN,IAIC,CACD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,GAAG,GAAa;YACvC,MAAM,UAAU,GACf,WACA,CAAC,IAAI,CAAC,CAAC;YACR,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;YAE/B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC;YAEhC,OAAO;gBACN,KAAK,EAAE,MAAM,MAAM,CAAC,KAAK;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;aACzB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CACR,IAAY,EACZ,KAAc,EACd,QAAiB,EACjB,GAAG,GAAa;YAEhB,MAAM,UAAU,GACf,WACA,CAAC,IAAI,CAAC,CAAC;YACR,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;YAE/B,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpC,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,GAAG,GAAa;YAC1C,MAAM,UAAU,GACf,WACA,CAAC,IAAI,CAAC,CAAC;YACR,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;YAE/B,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;KACD,CAAC;IAEF,OAAO,IAAiC,CAAC;AAC1C,CAAC"}

package/dist/schema/tree.d.ts

@@ -0,0 +1,14 @@
+import type { KVLike } from "../types.js";
+import type { SchemaNodeDef, TreeNodeWithChildren } from "./types.js";
+/**
+ * Build the root of a tree from fetched data.
+ *
+ * @param kv - The KV store
+ * @param allKeys - All keys from keys() call (including root)
+ * @param rootKey - The root entity key
+ * @param rootId - The root entity ID
+ * @param rootNode - The schema node for the root
+ * @returns Root tree node with child iterators, or null if not found
+ */
+export declare function buildTree<V, M, C extends Record<string, SchemaNodeDef>>(kv: KVLike<unknown>, allKeys: string[], rootKey: string, rootId: string, rootNode: SchemaNodeDef<V, M, C>): Promise<TreeNodeWithChildren<V, M, C> | null>;
+//# sourceMappingURL=tree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/schema/tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EACX,aAAa,EAIb,oBAAoB,EACpB,MAAM,YAAY,CAAC;AAoMpB;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC5E,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAe/C"}

package/dist/schema/tree.js

@@ -0,0 +1,135 @@
+import { createKeyPattern, extractIdFromKey } from "./key-builders.js";
+/**
+ * Build a tree node from a fetched value, including lazy child iterators.
+ *
+ * @param kv - The KV store to fetch from
+ * @param allKeys - All keys from the initial keys() call
+ * @param key - The key of this node
+ * @param id - The extracted ID of this node
+ * @param value - The fetched value
+ * @param metadata - The fetched metadata
+ * @param node - The schema node definition
+ * @param parentPatterns - Patterns from ancestor nodes
+ * @returns TreeNode with child iterators attached
+ */
+function buildTreeNode(kv, allKeys, key, id, value, metadata, node, parentPatterns) {
+    const treeNode = {
+        id,
+        key,
+        value,
+        metadata,
+    };
+    // Add child iterators based on schema
+    if (node.children) {
+        const currentPatterns = [...parentPatterns, node.pattern];
+        for (const [childName, childNode] of Object.entries(node.children)) {
+            treeNode[childName] =
+                createChildIterator(kv, allKeys, key, childNode, currentPatterns);
+        }
+    }
+    return treeNode;
+}
+/**
+ * Create a lazy iterator for child nodes.
+ *
+ * The iterator batches all value fetches on first access, then yields
+ * tree nodes one by one. This provides both lazy evaluation (no fetch
+ * until iteration) and efficient batching (all fetches in parallel).
+ */
+function createChildIterator(kv, allKeys, parentKey, childNode, parentPatterns) {
+    // Create pattern to match child keys
+    const childPattern = createKeyPattern(childNode, parentPatterns);
+    // Filter keys that match this child type and are under the parent
+    const childPrefix = parentKey + "/";
+    const matchingKeys = allKeys.filter((k) => {
+        if (!k.startsWith(childPrefix))
+            return false;
+        // Get the relative key (after parent prefix) and check if it matches
+        // Actually, we need to match the full key pattern
+        return childPattern.test(k);
+    });
+    // Sort keys for consistent ordering
+    matchingKeys.sort();
+    let fetchedNodes = null;
+    let fetchPromise = null;
+    // Fetch all children with bounded concurrency
+    async function fetchAll() {
+        if (fetchedNodes !== null)
+            return fetchedNodes;
+        if (fetchPromise !== null)
+            return fetchPromise;
+        fetchPromise = (async () => {
+            // Use getMany for bounded concurrent fetching
+            const entries = await kv.getMany(matchingKeys);
+            const nodes = [];
+            for (const key of matchingKeys) {
+                const entry = entries.get(key);
+                if (!entry)
+                    continue;
+                const id = extractIdFromKey(key, childPattern);
+                if (!id)
+                    continue;
+                nodes.push(buildTreeNode(kv, allKeys, key, id, await entry.value, entry.metadata, childNode, parentPatterns));
+            }
+            fetchedNodes = nodes;
+            return fetchedNodes;
+        })();
+        return fetchPromise;
+    }
+    const iterator = {
+        async *[Symbol.asyncIterator]() {
+            const nodes = await fetchAll();
+            for (const node of nodes) {
+                yield node;
+            }
+        },
+        async page(limit, cursor) {
+            // Cursor is just an offset into matchingKeys
+            const offset = cursor ? Number.parseInt(cursor, 10) : 0;
+            const pageKeys = matchingKeys.slice(offset, offset + limit);
+            // Fetch values for this page
+            const entries = await kv.getMany(pageKeys);
+            const items = [];
+            for (const key of pageKeys) {
+                const entry = entries.get(key);
+                if (!entry)
+                    continue;
+                const id = extractIdFromKey(key, childPattern);
+                if (!id)
+                    continue;
+                items.push(buildTreeNode(kv, allKeys, key, id, await entry.value, entry.metadata, childNode, parentPatterns));
+            }
+            const nextOffset = offset + limit;
+            const nextCursor = nextOffset < matchingKeys.length ? String(nextOffset) : undefined;
+            return { items, cursor: nextCursor };
+        },
+        async collect() {
+            return fetchAll();
+        },
+        count() {
+            return matchingKeys.length;
+        },
+        keys() {
+            return [...matchingKeys];
+        },
+    };
+    return iterator;
+}
+/**
+ * Build the root of a tree from fetched data.
+ *
+ * @param kv - The KV store
+ * @param allKeys - All keys from keys() call (including root)
+ * @param rootKey - The root entity key
+ * @param rootId - The root entity ID
+ * @param rootNode - The schema node for the root
+ * @returns Root tree node with child iterators, or null if not found
+ */
+export async function buildTree(kv, allKeys, rootKey, rootId, rootNode) {
+    // Fetch root value
+    const result = await kv.get(rootKey);
+    if (!result.exists)
+        return null;
+    return buildTreeNode(kv, allKeys, rootKey, rootId, await result.value, result.metadata, rootNode, []);
+}
+//# sourceMappingURL=tree.js.map

package/dist/schema/tree.js.map

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

package/dist/schema/types.d.ts

@@ -0,0 +1,135 @@
+import type { KVLike } from "../types.js";
+/**
+ * Schema node definition for hierarchical entities.
+ * Used in defineSchema() to define key patterns and types.
+ */
+export interface SchemaNodeDef<V = unknown, M = unknown, C extends Record<string, any> | undefined = Record<string, any> | undefined, P extends string = string> {
+    /** Pattern for this level. "*" matches a single path segment (ID). */
+    pattern: P;
+    /** Type placeholder for the value (use `{} as YourType`) */
+    value: V;
+    /** Type placeholder for metadata (use `{} as YourMeta`) */
+    metadata?: M;
+    /** Child entity definitions */
+    children?: C;
+}
+type ChildrenOf<N> = N extends SchemaNodeDef<any, any, infer C> ? C extends Record<string, SchemaNodeDef<any, any, any>> ? C : Record<string, never> : Record<string, never>;
+/**
+ * Root schema configuration returned by defineSchema().
+ */
+export interface SchemaDef<P extends string, E extends Record<string, SchemaNodeDef<any, any, any>>> {
+    /** Root prefix for all keys */
+    prefix: P;
+    /** Entity definitions by name */
+    entities: E;
+}
+/**
+ * A tree node representing a fetched entity with its children.
+ * Children are accessed as named properties (e.g., board.columns).
+ */
+export interface TreeNode<V, M> {
+    /** The extracted ID from the key (e.g., "col-1") */
+    id: string;
+    /** The full key path (e.g., "board-1/columns/col-1") */
+    key: string;
+    /** The entity value */
+    value: V;
+    /** The entity metadata */
+    metadata: M;
+}
+/**
+ * Result of paginated tree iteration.
+ */
+export interface TreeNodePage<V, M, C extends Record<string, SchemaNodeDef<any, any, any>>> {
+    items: TreeNodeWithChildren<V, M, C>[];
+    cursor?: string;
+}
+/**
+ * An async iterable over child tree nodes with lazy batch fetching.
+ * On first iteration, all child values are fetched in parallel.
+ */
+export interface TreeNodeIterator<V, M, C extends Record<string, SchemaNodeDef<any, any, any>>> extends AsyncIterable<TreeNodeWithChildren<V, M, C>> {
+    /**
+     * Fetch a page of child nodes.
+     * @param limit - Maximum number of nodes to return
+     * @param cursor - Cursor from previous page (undefined for first page)
+     */
+    page(limit: number, cursor?: string): Promise<TreeNodePage<V, M, C>>;
+    /**
+     * Eagerly collect all child nodes into an array.
+     * Fetches all values if not already fetched.
+     */
+    collect(): Promise<TreeNodeWithChildren<V, M, C>[]>;
+    /**
+     * Get the count of child nodes without fetching values.
+     */
+    count(): number;
+    /**
+     * Get all child keys without fetching values.
+     */
+    keys(): string[];
+}
+/**
+ * A tree node that includes child iterators based on schema.
+ * Child iterators are named from the schema (e.g., board.columns, column.tasks).
+ */
+export type TreeNodeWithChildren<V, M, C extends Record<string, SchemaNodeDef<any, any, any>> | undefined> = TreeNode<V, M> & (C extends Record<string, SchemaNodeDef<any, any, any>> ? {
+    [K in keyof C]: C[K] extends SchemaNodeDef<infer CV, infer CM, any> ? TreeNodeIterator<CV, CM, ChildrenOf<C[K]>> : never;
+} : unknown);
+/**
+ * Extracts the path segments needed for a schema node.
+ * Each "*" in the pattern hierarchy requires an ID argument.
+ */
+export type KeyBuilderArgs<N extends SchemaNodeDef<any, any, any>> = N["pattern"] extends "*" ? [id: string] : N["pattern"] extends `${string}/*` ? [id: string] : [];
+/**
+ * Key builder function type.
+ * Takes ID arguments based on the pattern hierarchy and returns the full key.
+ */
+export type KeyBuilder<N extends SchemaNodeDef<any, any, any>, ParentArgs extends unknown[]> = N["pattern"] extends "*" ? (...args: [...ParentArgs, id: string]) => string : N["pattern"] extends `${string}/*` ? (...args: [...ParentArgs, id: string]) => string : (...args: ParentArgs) => string;
+/**
+ * Recursively builds key builder types for all nodes in schema.
+ */
+type GetChildren<N> = N extends {
+    children: infer C;
+} ? C : never;
+type HasChildren<N> = N extends {
+    children: Record<string, any>;
+} ? true : false;
+export type KeyBuilders<E extends Record<string, SchemaNodeDef<any, any, any>>, ParentArgs extends unknown[] = []> = {
+    [K in keyof E]: E[K] extends SchemaNodeDef<any, any, any> ? KeyBuilder<E[K], ParentArgs> & (HasChildren<E[K]> extends true ? KeyBuilders<GetChildren<E[K]> & Record<string, SchemaNodeDef<any, any, any>>, E[K]["pattern"] extends "*" ? [...ParentArgs, string] : E[K]["pattern"] extends `${string}/*` ? [...ParentArgs, string] : ParentArgs> : unknown) : never;
+};
+/**
+ * Schema-aware KV interface with type-safe operations.
+ */
+export interface SchemaKV<P extends string, E extends Record<string, SchemaNodeDef<any, any, any>>> {
+    /** Access to the underlying KV store */
+    raw: KVLike<unknown>;
+    /** Type-safe key builders for all entity types */
+    key: KeyBuilders<E>;
+    /**
+     * Build a lazy tree starting from a root entity.
+     * Makes a SINGLE keys() call, then lazily batch-fetches values on iteration.
+     *
+     * @param type - The entity type name from the schema
+     * @param ids - ID arguments for the root entity
+     * @returns Tree node with child iterators, or null if not found
+     */
+    tree<K extends keyof E>(type: K, ...ids: E[K] extends SchemaNodeDef<any, any, any> ? KeyBuilderArgs<E[K]> : never): Promise<(E[K] extends SchemaNodeDef<infer V, infer M, infer C> ? TreeNodeWithChildren<V, M, C> : never) | null>;
+    /**
+     * Get a single entity by type and IDs.
+     */
+    get<K extends keyof E>(type: K, ...ids: E[K] extends SchemaNodeDef<any, any, any> ? KeyBuilderArgs<E[K]> : never): Promise<(E[K] extends SchemaNodeDef<infer V, infer M> ? {
+        value: V;
+        metadata: M;
+    } : never) | null>;
+    /**
+     * Set an entity by type and IDs.
+     */
+    set<K extends keyof E>(type: K, value: E[K] extends SchemaNodeDef<infer V> ? V : never, metadata: E[K] extends SchemaNodeDef<infer _V, infer M> ? M : never, ...ids: E[K] extends SchemaNodeDef<any, any, any> ? KeyBuilderArgs<E[K]> : never): Promise<void>;
+    /**
+     * Delete an entity by type and IDs.
+     */
+    delete<K extends keyof E>(type: K, ...ids: E[K] extends SchemaNodeDef<any, any, any> ? KeyBuilderArgs<E[K]> : never): Promise<void>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/schema/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,30 @@
+/**
+ * Core test definitions that can be run with either vitest or vitest-compat.
+ * These functions accept the testing primitives as parameters to allow
+ * framework-agnostic test definitions.
+ */
+type DescribeFn = (name: string, fn: () => void) => void;
+type ItFn = (name: string, fn: () => Promise<void> | void) => void;
+type ExpectFn = <T>(actual: T) => {
+    toBe(expected: T): void;
+    toEqual(expected: unknown): void;
+    toBeGreaterThan(expected: number): void;
+};
+type BeforeEachFn = (fn: () => void) => void;
+type AfterEachFn = (fn: () => void) => void;
+interface TestingPrimitives {
+    describe: DescribeFn;
+    it: ItFn;
+    expect: ExpectFn;
+    beforeEach: BeforeEachFn;
+    afterEach: AfterEachFn;
+}
+export declare function registerCoreTests(t: TestingPrimitives): void;
+export declare function registerBinaryTests(t: TestingPrimitives): void;
+export declare function registerLargeValueTests(t: TestingPrimitives): void;
+export declare function registerTypedKVTests(t: TestingPrimitives): void;
+export declare function registerStreamingTests(t: TestingPrimitives): void;
+export declare function registerStressTests(t: TestingPrimitives): void;
+export declare function registerAllTests(t: TestingPrimitives): void;
+export {};
+//# sourceMappingURL=core-tests.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core-tests.d.ts","sourceRoot":"","sources":["../../src/testing/core-tests.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AACzD,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AACnE,KAAK,QAAQ,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK;IACjC,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC,CAAC;AACF,KAAK,YAAY,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAC7C,KAAK,WAAW,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAE5C,UAAU,iBAAiB;IAC1B,QAAQ,EAAE,UAAU,CAAC;IACrB,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,QAAQ,CAAC;IACjB,UAAU,EAAE,YAAY,CAAC;IACzB,SAAS,EAAE,WAAW,CAAC;CACvB;AAaD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAqI5D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CA4C9D;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAmElE;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CA0D/D;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAkEjE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAkE9D;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAO3D"}