/**
 * ID storage and lookup for OSM entities.
 *
 * Uses a two-level binary search (anchor array + block search) to map 64-bit OSM IDs
 * to internal array indices. Balances memory usage with O(log n) lookup speed.
 *
 * @module
 */
import type { ContentHasher } from "@osmix/shared/content-hasher";
import { type BufferType } from "./typed-arrays.ts";
/**
 * Union type for looking up entities by either OSM ID or internal array index.
 */
export type IdOrIndex = {
    id: number;
} | {
    index: number;
};
/**
 * Serializable state for worker transfer.
 */
export interface IdsTransferables<T extends BufferType = BufferType> {
    /** Entity IDs in insertion order. */
    ids: T;
    /** Sorted IDs for binary search (aliases `ids` if already sorted). */
    sortedIds: T;
    /** Maps sorted position → original insertion index. */
    sortedIdPositionToIndex: T;
    /** Anchor array: every BLOCK_SIZE-th sorted ID. */
    anchors: T;
    /** True if IDs were inserted in ascending order. */
    idsAreSorted: boolean;
}
/**
 * Efficiently store and lookup OSM entity IDs.
 *
 * Stores 64-bit IDs in a Float64Array and maintains a sorted index for O(log n) lookups.
 * Max capacity: ~2^32 entities.
 */
export declare class Ids {
    /** All IDs in insertion order */
    private ids;
    /** Whether buildIndex() has been called */
    private indexBuilt;
    /** True if IDs were added in ascending order (allows index optimization) */
    private idsAreSorted;
    /** Sorted view of IDs for binary search */
    private idsSorted;
    /** Maps position in sorted array → original insertion index */
    private sortedIdPositionToIndex;
    /** Anchor array for two-level binary search: every BLOCK_SIZE-th sorted ID */
    private anchors;
    /**
     * Create a new Ids index.
     * @param transferables - Optional serialized state to reconstruct from.
     */
    constructor(transferables?: IdsTransferables);
    /** Number of IDs stored in this index. */
    get size(): number;
    /** Returns true if buildIndex() has been called and lookups are enabled. */
    isReady(): boolean;
    /** Returns true if IDs were inserted in ascending order. */
    isSorted(): boolean;
    /**
     * Add an ID to the index.
     * @param id - The OSM entity ID to add.
     * @returns The internal array index where this ID was stored.
     * @throws If the index has already been built.
     */
    add(id: number): number;
    /**
     * Get the ID at a specific internal index.
     * @param index - The internal array index.
     * @returns The OSM entity ID at that index.
     */
    at(index: number): number;
    /**
     * Check if an ID exists in this index.
     * @param id - The OSM entity ID to check.
     * @returns True if the ID exists in this index.
     */
    has(id: number): boolean;
    /**
     * Build the index of IDs to positions.
     *
     * If the IDs are not sorted, we need to sort them and build a new index.
     * If the IDs are sorted, we can use the existing index.
     */
    buildIndex(): void;
    /**
     * Look up the internal array index for an OSM entity ID.
     *
     * @param id - The OSM entity ID to look up.
     * @returns The internal array index, or -1 if not found.
     * @throws If the index has not been built.
     */
    getIndexFromId(id: number): number;
    /**
     * Pass an ID or an index, get both.
     */
    idOrIndex(i: IdOrIndex): [index: number, id: number];
    /** Returns the sorted array of IDs for iteration. */
    get sorted(): Float64Array<ArrayBufferLike>;
    /** @internal Iterate sorted IDs with their original storage positions. */
    sortedEntries(): Generator<readonly [id: number, index: number]>;
    /**
     * Get transferable buffers for passing to another thread.
     * @returns Serializable representation of this index.
     */
    transferables(): IdsTransferables;
    /**
     * Get the approximate memory requirements for a given number of IDs in bytes.
     */
    static getBytesRequired(count: number): number;
    /**
     * Update a ContentHasher with the IDs data.
     * Uses the sorted IDs for consistent hashing regardless of insertion order.
     */
    updateHash(hasher: ContentHasher): ContentHasher;
}
//# sourceMappingURL=ids.d.ts.map