/**
 * @license
 * Copyright 2025 Steven Roussey <sroussey@gmail.com>
 * SPDX-License-Identifier: Apache-2.0
 */
import { DataPortSchemaObject, FromSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
import { type ITabularMigration, type ITabularMigrationApplier } from "../migrations";
import { BaseTabularStorage } from "./BaseTabularStorage";
import { AnyTabularStorage, AutoGeneratedKeys, DeleteSearchCriteria, InsertEntity, Page, PageRequest, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularSubscribeOptions } from "./ITabularStorage";
export declare const HF_TABULAR_REPOSITORY: import("@workglow/util").ServiceToken<AnyTabularStorage>;
export interface HuggingFaceTabularStorageOptions {
    /** HuggingFace API token for private datasets. */
    token?: string;
    /** Base URL for the HuggingFace Dataset Viewer API. */
    baseUrl?: string;
    indexes?: readonly (keyof any | readonly (keyof any)[])[];
}
/**
 * Read-only tabular storage backed by the HuggingFace Dataset Viewer API.
 * Supports both user-provided schemas and auto-detection via {@link fromDataset}.
 */
export declare class HuggingFaceTabularStorage<Schema extends DataPortSchemaObject, PrimaryKeyNames extends ReadonlyArray<keyof Schema["properties"]>, Entity = FromSchema<Schema, TypedArraySchemaOptions>, PrimaryKey = SimplifyPrimaryKey<Entity, PrimaryKeyNames>, Value = Omit<Entity, PrimaryKeyNames[number] & keyof Entity>, InsertType extends InsertEntity<Entity, AutoGeneratedKeys<Schema>> = InsertEntity<Entity, AutoGeneratedKeys<Schema>>> extends BaseTabularStorage<Schema, PrimaryKeyNames, Entity, PrimaryKey, Value, InsertType> {
    private readonly dataset;
    private readonly config;
    private readonly split;
    private readonly token?;
    private readonly baseUrl;
    constructor(dataset: string, config: string, split: string, schema: Schema, primaryKeyNames: PrimaryKeyNames, options?: HuggingFaceTabularStorageOptions, tabularMigrations?: ReadonlyArray<ITabularMigration>);
    /** Fetches the dataset features and converts them to a JSON Schema. */
    static fromDataset<Entity = any>(dataset: string, config: string, split: string, options?: HuggingFaceTabularStorageOptions): Promise<HuggingFaceTabularStorage<DataPortSchemaObject, readonly ["row_idx"], Entity, number, any, any>>;
    /** Validates the dataset exists and that any user-provided schema lines up. */
    setupDatabase(): Promise<void>;
    /**
     * Returns an in-memory applier for HF tabular storage. NOTE: HF datasets
     * are read-only; backfill ops will throw because `put` is unsupported.
     * DDL ops are no-ops (records are JS objects). Migrations on HF storages
     * are useful only for advancing bookkeeping in lockstep with a producer
     * that re-publishes datasets.
     */
    getMigrationApplier(): ITabularMigrationApplier | null;
    get(key: PrimaryKey): Promise<Entity | undefined>;
    getAll(options?: QueryOptions<Entity>): Promise<Entity[] | undefined>;
    getOffsetPage(offset: number, limit: number): Promise<Entity[] | undefined>;
    /**
     * HuggingFace datasets are read-only, so the concurrency-stability that
     * keyset pagination provides is unnecessary. The HF API also doesn't
     * expose tuple comparisons, so we drive cursor pagination from the
     * `/rows` endpoint's offset and encode the next offset in the cursor.
     *
     * The HF `/rows` endpoint caps each fetch at 100 rows, but the
     * {@link ITabularStorage.getPage} contract lets callers ask for any
     * positive limit. Loop in 100-row chunks until we either fill the
     * caller's `limit` or hit the end of the dataset, so a `getPage({ limit:
     * 200 })` doesn't silently return only 100 rows with a `nextCursor` of
     * `undefined` (which would terminate iteration despite more data).
     */
    getPage(request?: PageRequest<Entity>): Promise<Page<Entity>>;
    size(): Promise<number>;
    put(_value: InsertType): Promise<Entity>;
    putBulk(_values: InsertType[]): Promise<Entity[]>;
    delete(_value: PrimaryKey | Entity): Promise<void>;
    deleteAll(): Promise<void>;
    /** The HF /filter endpoint supports equality only; other operators throw. */
    query(criteria: SearchCriteria<Entity>, options?: QueryOptions<Entity>): Promise<Entity[] | undefined>;
    deleteSearch(_criteria: DeleteSearchCriteria<Entity>): Promise<void>;
    subscribeToChanges(_callback: (change: TabularChangePayload<Entity>) => void, _options?: TabularSubscribeOptions): () => void;
    destroy(): void;
    private fetchApi;
    private rowToEntity;
}
//# sourceMappingURL=HuggingFaceTabularStorage.d.ts.map