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