@yoch/frozenminisearch 1.2.3 → 1.3.0

package/dist/browser/index.d.ts

@@ -0,0 +1,693 @@
+/**
+ * Wildcard query symbol (matches all documents).
+ * Use {@link FrozenMiniSearch.wildcard} in application code.
+ */
+declare const WILDCARD_QUERY: unique symbol;
+
+/**
+ * BM25+ algorithm parameters.
+ */
+type BM25Params = {
+    k: number;
+    b: number;
+    d: number;
+};
+type LowercaseCombinationOperator = 'or' | 'and' | 'and_not';
+type CombinationOperator = LowercaseCombinationOperator | Uppercase<LowercaseCombinationOperator> | Capitalize<LowercaseCombinationOperator>;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Search options to customize the search behavior.
+ */
+type SearchOptions = {
+    /**
+     * Names of the fields to search in. If omitted, all fields are searched.
+     */
+    fields?: string[];
+    /**
+     * Function used to filter search results, for example on the basis of stored
+     * fields. It takes as argument each search result and should return a boolean
+     * to indicate if the result should be kept or not.
+     */
+    filter?: (result: SearchResult) => boolean;
+    /**
+     * Key-value object of field names to boosting values. By default, fields are
+     * assigned a boosting factor of 1. If one assigns to a field a boosting value
+     * of 2, a result that matches the query in that field is assigned a score
+     * twice as high as a result matching the query in another field, all else
+     * being equal.
+     */
+    boost?: {
+        [fieldName: string]: number;
+    };
+    /**
+     * Function to calculate a boost factor for each query term. Returning a
+     * factor lower than 1 reduces the importance of the term, greater than 1
+     * increases it, and exactly 1 is neutral.
+     */
+    boostTerm?: (term: string, i: number, terms: string[]) => number;
+    /**
+     * Relative weights to assign to prefix search results and fuzzy search
+     * results. Exact matches are assigned a weight of 1.
+     */
+    weights?: {
+        fuzzy: number;
+        prefix: number;
+    };
+    /**
+     * Function to calculate a boost factor for documents. It takes as arguments
+     * the document ID, and a term that matches the search in that document, and
+     * the value of the stored fields for the document (if any). A falsy value
+     * skips the search result completely.
+     */
+    boostDocument?: (documentId: any, term: string, storedFields?: Record<string, unknown>) => number;
+    /**
+     * Controls whether to perform prefix search. Either a boolean, or a function
+     * called per query term that returns a boolean.
+     */
+    prefix?: boolean | ((term: string, index: number, terms: string[]) => boolean);
+    /**
+     * Controls whether to perform fuzzy search. Either a boolean (default
+     * fuzziness), a number (explicit edit distance ≥ 1, or fractional 0–1 of the
+     * term length), or a function returning either.
+     */
+    fuzzy?: boolean | number | ((term: string, index: number, terms: string[]) => boolean | number);
+    /**
+     * Maximum fuzziness when using a fractional fuzzy value. Defaults to 6.
+     */
+    maxFuzzy?: number;
+    /**
+     * The operand to combine partial results for each term. Defaults to "OR".
+     */
+    combineWith?: CombinationOperator;
+    /**
+     * Function to tokenize the search query. By default, the same tokenizer used
+     * for indexing is used also for search.
+     */
+    tokenize?: (text: string) => string[];
+    /**
+     * Function to process or normalize terms in the search query. By default, the
+     * same term processor used for indexing is used also for search.
+     */
+    processTerm?: (term: string) => string | string[] | null | undefined | false;
+    /**
+     * BM25+ algorithm parameters. Customizing these is almost never necessary.
+     */
+    bm25?: BM25Params;
+};
+/**
+ * `SearchOptions` with library defaults filled in. Used as the canonical shape
+ * resolved by `MiniSearch` / `FrozenMiniSearch` before passing options around.
+ */
+type SearchOptionsWithDefaults = SearchOptions & {
+    boost: {
+        [fieldName: string]: number;
+    };
+    weights: {
+        fuzzy: number;
+        prefix: number;
+    };
+    prefix: boolean | ((term: string, index: number, terms: string[]) => boolean);
+    fuzzy: boolean | number | ((term: string, index: number, terms: string[]) => boolean | number);
+    maxFuzzy: number;
+    combineWith: CombinationOperator;
+    bm25: BM25Params;
+};
+/**
+ * Configuration options compatible with the MiniSearch constructor.
+ *
+ * @typeParam T  The type of documents being indexed.
+ */
+type Options<T = any> = {
+    /** Names of the document fields to be indexed. */
+    fields: string[];
+    /** Name of the ID field, uniquely identifying a document. Defaults to `"id"`. */
+    idField?: string;
+    /** Names of fields to store, so that search results would include them. */
+    storeFields?: string[];
+    /** Function used to extract the value of each field in documents. */
+    extractField?: (document: T, fieldName: string) => any;
+    /** Function used to turn field values into strings for indexing. */
+    stringifyField?: (fieldValue: any, fieldName: string) => string;
+    /** Function used to split a field value into individual terms to be indexed. */
+    tokenize?: (text: string, fieldName?: string) => string[];
+    /** Function used to process a term before indexing or search (e.g. stemming). */
+    processTerm?: (term: string, fieldName?: string) => string | string[] | null | undefined | false;
+    /** Function called to log messages from the library. */
+    logger?: (level: LogLevel, message: string, code?: string) => void;
+    /** Auto-vacuum behaviour after MiniSearch `discard`; defaults to `true`. */
+    autoVacuum?: boolean | AutoVacuumOptions;
+    /** Default search options. */
+    searchOptions?: SearchOptions;
+    /** Default auto-suggest options. */
+    autoSuggestOptions?: SearchOptions;
+};
+/**
+ * Canonical `Options<T>` with defaults filled in. Shared by `MiniSearch`,
+ * `FrozenMiniSearch`, the frozen builder, and the binary load path so they
+ * cannot drift.
+ */
+type OptionsWithDefaults<T = any> = Options<T> & {
+    storeFields: string[];
+    idField: string;
+    extractField: (document: T, fieldName: string) => any;
+    stringifyField: (fieldValue: any, fieldName: string) => string;
+    tokenize: (text: string, fieldName: string) => string[];
+    processTerm: (term: string, fieldName: string) => string | string[] | null | undefined | false;
+    logger: (level: LogLevel, message: string, code?: string) => void;
+    autoVacuum: false | AutoVacuumOptions;
+    searchOptions: SearchOptionsWithDefaults;
+    autoSuggestOptions: SearchOptions;
+};
+/** Browser snapshot compression (`zstd` not supported). */
+type BrowserBinaryCompression = 'auto' | 'raw' | 'zlib';
+/** Browser `saveBinaryAsync()` options (no zstd). */
+type BrowserSaveBinaryAsyncOptions = {
+    compression?: BrowserBinaryCompression;
+};
+/**
+ * A search-completion suggestion.
+ */
+type Suggestion = {
+    /** The suggested phrase. */
+    suggestion: string;
+    /** The suggestion as an array of terms. */
+    terms: string[];
+    /** Score for the suggestion. */
+    score: number;
+};
+/**
+ * Match information for a search result: keys are terms that matched, values
+ * are the list of fields each term was found in.
+ */
+type MatchInfo = {
+    [term: string]: string[];
+};
+/**
+ * A single search result, including the document ID, terms that matched, the
+ * match information, the score, and all the stored fields.
+ */
+type SearchResult = {
+    /** The document ID. */
+    id: any;
+    /** Document terms that matched (e.g. `"motorcycle"` for prefix `"moto"`). */
+    terms: string[];
+    /** Query terms that matched (e.g. `"moto"` for prefix `"moto"`). */
+    queryTerms: string[];
+    /** Score of the search result. */
+    score: number;
+    /** Match information, see {@link MatchInfo}. */
+    match: MatchInfo;
+    /** Stored fields are merged onto the result. */
+    [key: string]: any;
+};
+/** A boolean combination of sub-queries. */
+type QueryCombination = SearchOptions & {
+    queries: Query[];
+};
+/**
+ * Wildcard query symbol, used to match all documents.
+ * Use {@link FrozenMiniSearch.wildcard}.
+ */
+type Wildcard = typeof WILDCARD_QUERY;
+/**
+ * Search query expression: a query string, an expression tree combining
+ * several queries with `AND`/`OR`/`AND_NOT`, or the wildcard symbol.
+ */
+type Query = QueryCombination | string | Wildcard;
+/**
+ * Options controlling vacuuming behaviour.
+ */
+type VacuumOptions = {
+    /** Number of terms traversed per batch. Defaults to 1000. */
+    batchSize?: number;
+    /** Wait time between batches in milliseconds. Defaults to 10. */
+    batchWait?: number;
+};
+/**
+ * Minimum thresholds for `dirtCount` and `dirtFactor` triggering an automatic
+ * vacuum.
+ */
+type VacuumConditions = {
+    /** Minimum dirt count; defaults to 20. */
+    minDirtCount?: number;
+    /** Minimum dirt factor; defaults to 0.1. */
+    minDirtFactor?: number;
+};
+/**
+ * Options controlling auto-vacuum behaviour. Combines {@link VacuumOptions} and
+ * {@link VacuumConditions}.
+ */
+type AutoVacuumOptions = VacuumOptions & VacuumConditions;
+
+/**
+ * Runtime stored fields. Single store field → one column (no per-doc Record at rest).
+ * Wire format stays row JSON; encode/decode can skip intermediate row arrays when layout is known.
+ */
+type StoredFieldsLayout = {
+    kind: 'none';
+} | {
+    kind: 'single';
+    field: string;
+    values: unknown[];
+} | {
+    kind: 'multi';
+    rows: (Record<string, unknown> | undefined)[];
+};
+
+declare const OR: LowercaseCombinationOperator;
+declare const AND: LowercaseCombinationOperator;
+declare const AND_NOT: LowercaseCombinationOperator;
+interface RawResultValue {
+    score: number;
+    terms: string[];
+    match: MatchInfo;
+}
+type RawResult = Map<number, RawResultValue>;
+/** Posting list for one (term, field): docId -> term frequency */
+interface PostingListLike {
+    readonly size: number;
+    forEachDoc(callback: (docId: number, termFreq: number) => void): void;
+}
+/** term -> fieldId -> posting list */
+interface FieldTermDataLike {
+    get(fieldId: number): PostingListLike | undefined;
+}
+interface FinalizeSearchParams {
+    rawResults: RawResult;
+    getExternalId: (docId: number) => unknown;
+    getStoredFields?: (docId: number) => Record<string, unknown> | undefined;
+    /** When set, copies stored fields in place (no per-doc row allocation for single-column layouts). */
+    storedFieldsLayout?: StoredFieldsLayout;
+    filter?: (result: SearchResult) => boolean;
+    skipSort?: boolean;
+}
+/** Merge search options, apply wildcard skipSort, then {@link finalizeSearchResults}. */
+declare function finalizeRawSearchResults(rawResults: RawResult, query: Query, searchOptions: SearchOptions, globalSearchOptions: SearchOptionsWithDefaults, getExternalId: (docId: number) => unknown, getStoredFields?: (docId: number) => Record<string, unknown> | undefined, storedFieldsLayout?: StoredFieldsLayout): SearchResult[];
+declare function finalizeSearchResults(params: FinalizeSearchParams): SearchResult[];
+
+type SuggestionHit = Pick<SearchResult, 'score' | 'terms'>;
+/** Aggregate search hits into ranked phrase suggestions. */
+declare function suggestFromSearchResults(hits: Iterable<SuggestionHit>): Suggestion[];
+/** Build suggestions from raw search hits without materializing full public results. */
+declare function suggestFromRawResults(rawResults: RawResult): Suggestion[];
+
+/**
+ * Smallest unsigned typed array that can hold the structure's indices. Widths
+ * are chosen adaptively at build time (`packedIndexArray` in `layout.ts`); reads via
+ * `arr[i]` are width-agnostic, so query code never branches on the concrete type.
+ */
+type PackedIndexArray = Uint8Array | Uint16Array | Uint32Array;
+type PackedTermRef = {
+    termIndex: number;
+    length: number;
+};
+type PackedFuzzyRef = PackedTermRef & {
+    distance: number;
+};
+/** In-memory packed string radix map (term → payload). */
+interface PackedStringRadixMap<V = number> {
+    readonly size: number;
+    get(term: string): V | undefined;
+    entries(): Iterable<[string, V]>;
+    prefixRefs(prefix: string): Iterable<PackedTermRef>;
+    /** Lazy generator; see `packedRadixFuzzyRefs` in `fuzzy.ts` for rationale. */
+    fuzzyRefs(term: string, maxDistance: number): Iterable<PackedFuzzyRef>;
+    termByIndex(termIndex: number): string;
+    termLengthByIndex(termIndex: number): number;
+    /** @deprecated Internal benchmark/compat wrapper. Prefer `prefixRefs` + `termByIndex`. */
+    prefixEntries(prefix: string): Iterable<[string, V]>;
+    /**
+     * @deprecated Internal benchmark/compat wrapper. Prefer `fuzzyRefs` + `termByIndex`.
+     *
+     * Fuzzy matches for `term` within `maxDistance` edit distance. Yields every matching
+     * `[term, value, distance]`; iteration order is implementation-defined (compare sets, not order).
+     */
+    fuzzyEntries(term: string, maxDistance: number): Iterable<[string, V, number]>;
+    packedByteLength(): number;
+    packedNodeCount(): number;
+    packedEdgeCount(): number;
+}
+interface PackedRadixTreeData {
+    readonly size: number;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly labelHeap: string;
+    /**
+     * CSR edge offsets, length `nodeCount + 1`. Node `n` owns edges
+     * `[nodeEdgeOffset[n], nodeEdgeOffset[n + 1])`; the final entry equals
+     * `edgeCount`. Replaces the former `nodeFirstEdge`/`nodeEdgeCount` pair: edges
+     * are laid out contiguously in node order, so the per-node first index is just
+     * the prefix sum of the counts and need not be stored separately.
+     */
+    readonly nodeEdgeOffset: PackedIndexArray;
+    /**
+     * Leaf payload per node (term index for a frozen index). Meaningful only when
+     * the node has a leaf, i.e. `nodeLeafOrder[n] !== 0`; otherwise the cell is
+     * unused (stored as `0`). Width adapts to the largest payload.
+     */
+    readonly nodeValue: PackedIndexArray;
+    /**
+     * Leaf slot among a node's siblings, encoded as `slot + 1` with `0` meaning
+     * "no leaf". This avoids a wide sentinel: the column adapts to the largest
+     * child count instead of forcing `Uint32`. Decode with {@link decodeLeafSlot}.
+     */
+    readonly nodeLeafOrder: PackedIndexArray;
+    readonly edgeLabelStart: PackedIndexArray;
+    readonly edgeLabelLength: PackedIndexArray;
+    readonly edgeChild: PackedIndexArray;
+}
+
+/**
+ * Node-indexed parent pointers enabling per-term reconstruction without ever
+ * materializing a global path blob. Reconstruction climbs leaf → root in
+ * O(depth) and touches only the terms actually requested, which is the whole
+ * point of deferring string materialization.
+ *
+ * - `leafNodeByTermIndex[ti]` is the node carrying term `ti`'s leaf.
+ * - `parentNode[node]` is `node`'s parent (root = node `0`, value unused).
+ * - `parentEdge[node]` is the edge index linking `parentNode[node]` to `node`.
+ *
+ * All three are built by cheap linear scans (O(nodeCount + edgeCount)), with no
+ * recursion and no per-term allocation, so building them is far cheaper than the
+ * former whole-tree DFS + path-edge blob.
+ */
+type PackedLazyTermMetadata = {
+    leafNodeByTermIndex: PackedIndexArray;
+    parentNode: PackedIndexArray;
+    parentEdge: PackedIndexArray;
+};
+
+declare class PackedRadixTree implements PackedStringRadixMap<number>, PackedRadixTreeData {
+    readonly size: number;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    readonly labelHeap: string;
+    readonly nodeEdgeOffset: PackedIndexArray;
+    readonly nodeValue: PackedIndexArray;
+    readonly nodeLeafOrder: PackedIndexArray;
+    readonly edgeLabelStart: PackedIndexArray;
+    readonly edgeLabelLength: PackedIndexArray;
+    readonly edgeChild: PackedIndexArray;
+    private _lazyTermMetadata;
+    private constructor();
+    static fromData(data: PackedRadixTreeData): PackedRadixTree;
+    private findEdge;
+    get(term: string): number | undefined;
+    entries(): IterableIterator<[string, number]>;
+    /** @deprecated Internal benchmark/compat wrapper. Prefer `prefixRefs` + `termByIndex`. */
+    prefixEntries(prefix: string): IterableIterator<[string, number]>;
+    prefixRefs(prefix: string): IterableIterator<PackedTermRef>;
+    /**
+     * Walk `prefix` to the subtree root; returns accumulated heap label prefix string.
+     * `null` when no terms share the prefix.
+     */
+    private resolvePrefixWalk;
+    private resolvePrefixWalkRef;
+    /**
+     * Follow `key` from the root. Shared by exact lookup and prefix iteration.
+     * Mid-edge stop uses the full edge label in `prefix` (SearchableMap parity).
+     */
+    private walkKey;
+    /**
+     * Depth-first traversal matching {@link SearchableMap}'s `TreeIterator`, which
+     * visits siblings in reverse Map-insertion order (last key first). The leaf, if
+     * any, sits at `nodeLeafOrder` among the original sibling slots; everything else
+     * is an edge. Exact order matters for prefix iteration and autoSuggest parity.
+     */
+    private emitSubtree;
+    private emitSubtreeRefs;
+    /** @deprecated Internal benchmark/compat wrapper. Prefer `fuzzyRefs` + `termByIndex`. */
+    fuzzyEntries(term: string, maxDistance: number): Iterable<[string, number, number]>;
+    fuzzyRefs(term: string, maxDistance: number): Iterable<PackedFuzzyRef>;
+    lazyTermMetadata(): PackedLazyTermMetadata;
+    termLengthByIndex(termIndex: number): number;
+    termByIndex(termIndex: number): string;
+    packedByteLength(): number;
+    packedNodeCount(): number;
+    packedEdgeCount(): number;
+}
+
+/** Frozen term index used by {@link FrozenMiniSearch} (packed radix tree). */
+type FrozenTermIndex = PackedRadixTree;
+
+type IdLookupMode = 'identity' | 'lazy-map';
+interface IdToShortIdLookup {
+    readonly mode: IdLookupMode;
+    readonly mapEntryCount: number;
+    has(id: unknown): boolean;
+    get(id: unknown): number | undefined;
+}
+
+type DocIdArray = Uint16Array | Uint32Array;
+/** Adaptive-width unsigned column for term frequencies (u8 or u16; never u32). */
+type FreqArray = Uint8Array | Uint16Array;
+
+type FieldIdArray = Uint8Array | Uint16Array;
+type PostingsLayoutKind = 'dense' | 'sparse';
+interface FrozenPostingsLayout {
+    fieldCount: number;
+    termCount: number;
+    nextId: number;
+    layout: PostingsLayoutKind;
+    docIdWidth: 16 | 32;
+    /** Width of sparse field id column; null when layout is dense. */
+    sparseFieldIdWidth: 8 | 16 | null;
+    allDocIds: DocIdArray;
+    allFreqs: FreqArray;
+    denseOffsets: Uint32Array | null;
+    denseLengths: Uint32Array | null;
+    sparseTermStarts: Uint32Array | null;
+    sparseFieldIds: FieldIdArray | null;
+    sparseOffsets: Uint32Array | null;
+    sparseLengths: Uint32Array | null;
+}
+/** Single rebindable {@link FieldTermDataLike} per frozen index (O(1) RAM). */
+type FrozenFieldTermFlyweight = FieldTermDataLike & {
+    bind(termIndex: number): FrozenFieldTermFlyweight;
+};
+
+/** Adaptive-width unsigned column (1/2/4 bytes per element) for field lengths and packed radix columns. */
+type FieldLengthArray = PackedIndexArray;
+
+interface FrozenMemoryBreakdown {
+    termCount: number;
+    documentCount: number;
+    nextId: number;
+    postings: {
+        slotCount: number;
+        layout: string;
+        docIdWidth: number;
+        allDocIdsBytes: number;
+        allFreqsBytes: number;
+        offsetsBytes: number;
+        lengthsBytes: number;
+        totalTypedBytes: number;
+    };
+    radixTree: {
+        nodeCount: number;
+        edgeCount: number;
+        estimatedBytes: number;
+    };
+    documents: {
+        externalIdsSlots: number;
+        storedFieldsSlots: number;
+        idLookupMode: string;
+        idToShortIdEntries: number;
+        fieldLengthMatrixBytes: number;
+        avgFieldLengthBytes: number;
+        storedFieldsJsonBytes: number;
+    };
+    estimatedStructuredBytes: number;
+}
+/**
+ * Low-level parameters for {@link assembleFrozen} (custom frozen index pipelines).
+ * Field types are part of the public surface for advanced assembly; typical apps use
+ * {@link buildFrozenFromDocuments}, {@link FrozenMiniSearch.fromJson}, or binary load instead.
+ */
+interface FrozenAssembleParams<T = any> {
+    options: OptionsWithDefaults<T>;
+    documentCount: number;
+    nextId: number;
+    fieldIds: {
+        [field: string]: number;
+    };
+    fieldCount: number;
+    externalIds: unknown[];
+    idLookup: IdToShortIdLookup;
+    storedFields: StoredFieldsLayout;
+    fieldLengthMatrix: FieldLengthArray;
+    avgFieldLength: Float32Array;
+    index: FrozenTermIndex;
+    termCount: number;
+    postings: FrozenPostingsLayout;
+}
+
+/** MiniSearch JSON snapshot (`toJSON` wire format, `serializationVersion` 1 or 2). */
+type SerializedIndexEntry = Record<string, number>;
+type MiniSearchSnapshot = {
+    documentCount: number;
+    nextId: number;
+    documentIds: {
+        [shortId: string]: unknown;
+    };
+    fieldIds: {
+        [fieldName: string]: number;
+    };
+    fieldLength: {
+        [shortId: string]: number[];
+    };
+    averageFieldLength: number[];
+    storedFields: {
+        [shortId: string]: Record<string, unknown> | undefined;
+    };
+    dirtCount?: number;
+    index: [string, {
+        [fieldId: string]: SerializedIndexEntry | {
+            ds: SerializedIndexEntry;
+        };
+    }][];
+    serializationVersion: number;
+};
+
+interface FrozenIndexBuilderHints {
+    /** Pre-size per-document arrays when the final document count is known. */
+    estimatedDocumentCount?: number;
+    /** Hint for initial growable posting column capacity per (term, field) slot. */
+    estimatedPostingsPerSlot?: number;
+}
+/** Incremental builder for {@link FrozenMiniSearch} without materializing a full `documents[]` array. */
+declare class FrozenIndexBuilder<T> {
+    private readonly _options;
+    private readonly _fieldIds;
+    private readonly _fieldCount;
+    private _index;
+    private readonly _postings;
+    private readonly _termCount;
+    private readonly _externalIds;
+    private readonly _storedFields;
+    private readonly _fieldLengthData;
+    private readonly _avgFieldLength;
+    private readonly _seenIds;
+    private readonly _fieldTermFreqScratch;
+    private readonly _rawTokenScratch;
+    private readonly _tokenScratch;
+    private _nextId;
+    private _frozen;
+    constructor(options: Options<T>, hints?: FrozenIndexBuilderHints);
+    /** Number of documents indexed so far (not yet frozen). */
+    get documentCount(): number;
+    add(document: T): void;
+    /**
+     * Adds all the given documents to the index.
+     *
+     * @param documents  An array of documents to be indexed
+     */
+    addAll(documents: readonly T[]): void;
+    /**
+     * Adds all the given documents to the index asynchronously.
+     *
+     * Returns a promise that resolves (to `undefined`) when the indexing is done.
+     * This method is useful when indexing many documents, to avoid blocking the main
+     * thread. The indexing is performed asynchronously and in chunks. Finalize with
+     * {@link freezeFrozenIndexBuilder} when done.
+     *
+     * @param documents  An array of documents to be indexed
+     * @param options  Configuration options
+     * @return A promise resolving to `undefined` when the indexing is done
+     */
+    addAllAsync(documents: readonly T[], options?: {
+        chunkSize?: number;
+    }): Promise<void>;
+    /**
+     * Finalize this builder into assembly params. Call {@link assembleFrozen} or
+     * {@link freezeFrozenIndexBuilder} to obtain a {@link FrozenMiniSearch} instance.
+     */
+    freezeParams(): FrozenAssembleParams<T>;
+}
+/** Create an incremental builder for {@link FrozenMiniSearch}. */
+declare function createFrozenIndexBuilder<T>(options: Options<T>, hints?: FrozenIndexBuilderHints): FrozenIndexBuilder<T>;
+
+declare function frozenMemoryBreakdown(frozen: FrozenMiniSearchCore): FrozenMemoryBreakdown;
+type FrozenMiniSearchCtor<T, I extends FrozenMiniSearchCore<T>> = new (params: FrozenAssembleParams<T>) => I;
+declare class FrozenMiniSearchCore<T = any> {
+    protected readonly _options: OptionsWithDefaults<T>;
+    protected readonly _index: FrozenTermIndex;
+    protected readonly _documentCount: number;
+    protected readonly _nextId: number;
+    protected readonly _externalIds: unknown[];
+    protected readonly _idLookup: IdToShortIdLookup;
+    protected readonly _fieldIds: {
+        [field: string]: number;
+    };
+    protected readonly _fieldCount: number;
+    protected readonly _fieldLengthMatrix: FieldLengthArray;
+    protected readonly _avgFieldLength: Float32Array;
+    protected readonly _storedFields: StoredFieldsLayout;
+    protected readonly _termCount: number;
+    protected readonly _postings: FrozenPostingsLayout;
+    protected readonly _fieldTermFlyweight: FrozenFieldTermFlyweight;
+    private readonly _aggregateContext;
+    private readonly _queryEngineParams;
+    private readonly _hasStoredFields;
+    constructor(params: FrozenAssembleParams<T>);
+    static readonly wildcard: typeof WILDCARD_QUERY;
+    get documentCount(): number;
+    get termCount(): number;
+    memoryBreakdown(): FrozenMemoryBreakdown;
+    has(id: unknown): boolean;
+    getStoredFields(id: unknown): Record<string, unknown> | undefined;
+    search(query: Query, searchOptions?: SearchOptions): SearchResult[];
+    /**
+     * Without a `filter`, aggregates suggestions from raw query hits (no full result materialization).
+     * With a `filter`, uses {@link search} so stored fields are available to the predicate.
+     */
+    autoSuggest(queryString: string, options?: SearchOptions): Suggestion[];
+    /** Build a read-only index in one pass from documents. */
+    static fromDocuments<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, documents: readonly T[], options: Options<T>): I;
+    /**
+     * Export this index as a MiniSearch wire snapshot (`serializationVersion: 2`).
+     * Use for migration or interchange with the `minisearch` package (`JSON.stringify` works via this method).
+     * Term order in `index` may differ from MiniSearch native `toJSON`; search scores stay equivalent.
+     */
+    toJSON(): MiniSearchSnapshot;
+    /**
+     * Build a new frozen index **from** a MiniSearch JSON snapshot string (import / migration).
+     * Accepts the wire format produced by MiniSearch `toJSON` or by {@link toJSON} on this class.
+     * No runtime dependency on the `minisearch` package.
+     */
+    static fromJson<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, json: string, options?: Options<T>): I;
+    /**
+     * Same as {@link fromJson} with a pre-parsed snapshot object.
+     * `storedFields` are shallow-copied; callers must not mutate nested values
+     * after load if they intend to keep the index immutable.
+     */
+    static fromMiniSearchSnapshot<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, snapshot: MiniSearchSnapshot, options?: Options<T>): I;
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
+    static fromMiniSearch<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, source: {
+        toJSON(): MiniSearchSnapshot;
+    }, options?: Options<T>): I;
+    /**
+     * Build a read-only index from an async stream of documents (e.g. CSV parser).
+     * For sync iterables, use {@link createFrozenIndexBuilder} with `for...of` instead.
+     *
+     * @param hints  Optional builder hints; `estimatedDocumentCount` pre-allocates
+     *   per-document arrays when the final document count is known upfront.
+     */
+    static fromAsyncIterable<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, iterable: AsyncIterable<T>, options: Options<T>, hints?: FrozenIndexBuilderHints): Promise<I>;
+    private getFieldLength;
+    private executeQuery;
+}
+
+declare function assembleFrozen<T>(params: FrozenAssembleParams<T>): FrozenMiniSearchBrowser<T>;
+declare class FrozenMiniSearchBrowser<T = any> extends FrozenMiniSearchCore<T> {
+    saveBinaryAsync(saveOptions?: BrowserSaveBinaryAsyncOptions): Promise<Uint8Array>;
+    private binarySnapshotInput;
+    static loadBinaryAsync<T>(buffer: Uint8Array, options?: Options<T>): Promise<FrozenMiniSearchBrowser<T>>;
+    private static fromBinarySnapshot;
+}
+
+declare function buildFrozenFromDocuments<T>(documents: readonly T[], options: Options<T>): FrozenMiniSearchBrowser<T>;
+declare function freezeFrozenIndexBuilder<T>(builder: FrozenIndexBuilder<T>): FrozenMiniSearchBrowser<T>;
+
+export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearchBrowser as FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearchBrowser as default, finalizeRawSearchResults, finalizeSearchResults, freezeFrozenIndexBuilder, frozenMemoryBreakdown, suggestFromRawResults, suggestFromSearchResults };
+export type { BM25Params, BrowserBinaryCompression, BrowserSaveBinaryAsyncOptions, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };