@yoch/frozenminisearch 1.2.3 → 1.3.0

package/dist/es/index.d.ts

@@ -164,11 +164,10 @@ type BinaryCompression = 'auto' | 'raw' | 'zstd' | 'zlib';
 type SaveBinaryOptions = {
     /**
      * Compression codec for the payload.
-     * - `auto`: one pass; payloads under 64 B stay raw; otherwise zstd when available
-     *   (else zlib on Node < 22.15), kept only when strictly smaller than raw
+     * - `auto`: one pass; payloads under 64 B stay raw; otherwise zlib when it shrinks
      * - `raw`: never compress
-     * - `zstd`: always zstd-compress, even when larger than raw; requires Node 22.15+ to write
-     * - `zlib`: always deflate, even when larger than raw; readable on Node 20+
+     * - `zstd`: always zstd-compress; requires Node 22.15+ to write
+     * - `zlib`: always deflate; readable on Node 20+ and in the browser build
      */
     compression?: BinaryCompression;
 };
@@ -247,9 +246,57 @@ type 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
@@ -421,25 +468,14 @@ interface FrozenPostingsLayout {
     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;
 
-/**
- * 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)[];
-};
-
 interface FrozenMemoryBreakdown {
     termCount: number;
     documentCount: number;
@@ -540,6 +576,7 @@ declare class FrozenIndexBuilder<T> {
     private readonly _avgFieldLength;
     private readonly _seenIds;
     private readonly _fieldTermFreqScratch;
+    private readonly _rawTokenScratch;
     private readonly _tokenScratch;
     private _nextId;
     private _frozen;
@@ -577,27 +614,25 @@ declare class FrozenIndexBuilder<T> {
 /** Create an incremental builder for {@link FrozenMiniSearch}. */
 declare function createFrozenIndexBuilder<T>(options: Options<T>, hints?: FrozenIndexBuilderHints): FrozenIndexBuilder<T>;
 
-declare function frozenMemoryBreakdown(frozen: FrozenMiniSearch): FrozenMemoryBreakdown;
-/** Instantiate {@link FrozenMiniSearch} from pre-built flat index parts (full validation). */
-declare function assembleFrozen<T>(params: FrozenAssembleParams<T>): FrozenMiniSearch<T>;
-declare function buildFrozenFromDocuments<T>(documents: readonly T[], options: Options<T>): FrozenMiniSearch<T>;
-/** Finalize a {@link FrozenIndexBuilder} into a read-only index. */
-declare function freezeFrozenIndexBuilder<T>(builder: FrozenIndexBuilder<T>): FrozenMiniSearch<T>;
-declare class FrozenMiniSearch<T = any> {
-    private readonly _options;
-    private readonly _index;
-    private readonly _documentCount;
-    private readonly _nextId;
-    private readonly _externalIds;
-    private readonly _idLookup;
-    private readonly _fieldIds;
-    private readonly _fieldCount;
-    private readonly _fieldLengthMatrix;
-    private readonly _avgFieldLength;
-    private readonly _storedFields;
-    private readonly _termCount;
-    private readonly _postings;
-    private readonly _fieldTermFlyweight;
+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;
@@ -609,42 +644,35 @@ declare class FrozenMiniSearch<T = any> {
     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[];
-    /** Serialize this index as a frozen binary snapshot (synchronous). */
-    saveBinarySync(saveOptions?: SaveBinaryOptions): Buffer;
-    /** Non-blocking snapshot serialization with the selected compression codec. */
-    saveBinaryAsync(saveOptions?: SaveBinaryOptions): Promise<Buffer>;
-    /** Load a frozen binary snapshot. */
-    static loadBinarySync<T>(buffer: Buffer, options?: Options<T>): FrozenMiniSearch<T>;
-    /** Load a frozen binary snapshot with streaming decompression when needed (bounded memory). */
-    static loadBinaryAsync<T>(buffer: Buffer, options?: Options<T>): Promise<FrozenMiniSearch<T>>;
-    private static fromBinarySnapshot;
     /** Build a read-only index in one pass from documents. */
-    static fromDocuments<T>(documents: readonly T[], options: Options<T>): FrozenMiniSearch<T>;
+    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).
-     * Not the primary persistence format — prefer {@link saveBinarySync} for production (size and load time).
      * 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.
-     * Distinct from {@link loadBinarySync}: JSON is MiniSearch interchange, not the native frozen binary.
      * No runtime dependency on the `minisearch` package.
      */
-    static fromJson<T>(json: string, options?: Options<T>): FrozenMiniSearch<T>;
+    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>(snapshot: MiniSearchSnapshot, options?: Options<T>): FrozenMiniSearch<T>;
+    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>(source: {
+    static fromMiniSearch<T, I extends FrozenMiniSearchCore<T>>(this: FrozenMiniSearchCtor<T, I>, source: {
         toJSON(): MiniSearchSnapshot;
-    }, options?: Options<T>): FrozenMiniSearch<T>;
+    }, 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.
@@ -652,10 +680,29 @@ declare class FrozenMiniSearch<T = any> {
      * @param hints  Optional builder hints; `estimatedDocumentCount` pre-allocates
      *   per-document arrays when the final document count is known upfront.
      */
-    static fromAsyncIterable<T>(iterable: AsyncIterable<T>, options: Options<T>, hints?: FrozenIndexBuilderHints): Promise<FrozenMiniSearch<T>>;
+    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;
 }
 
-export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, freezeFrozenIndexBuilder, frozenMemoryBreakdown };
+/** Build a read-only Node index in one pass from documents. */
+declare function buildFrozenFromDocuments<T>(documents: readonly T[], options: Options<T>): FrozenMiniSearch<T>;
+/** Finalize a {@link FrozenIndexBuilder} into a read-only Node index. */
+declare function freezeFrozenIndexBuilder<T>(builder: FrozenIndexBuilder<T>): FrozenMiniSearch<T>;
+/** Instantiate {@link FrozenMiniSearch} from pre-built flat index parts (full validation). */
+declare function assembleFrozen<T>(params: FrozenAssembleParams<T>): FrozenMiniSearch<T>;
+declare class FrozenMiniSearch<T = any> extends FrozenMiniSearchCore<T> {
+    /** Serialize this index as a frozen binary snapshot (synchronous). */
+    saveBinarySync(saveOptions?: SaveBinaryOptions): Buffer;
+    /** Non-blocking snapshot serialization with the selected compression codec. */
+    saveBinaryAsync(saveOptions?: SaveBinaryOptions): Promise<Buffer>;
+    private binarySnapshotInput;
+    /** Load a frozen binary snapshot. */
+    static loadBinarySync<T>(buffer: Buffer, options?: Options<T>): FrozenMiniSearch<T>;
+    /** Load a frozen binary snapshot with streaming decompression when needed (bounded memory). */
+    static loadBinaryAsync<T>(buffer: Buffer, options?: Options<T>): Promise<FrozenMiniSearch<T>>;
+    private static fromBinarySnapshot;
+}
+
+export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, finalizeRawSearchResults, finalizeSearchResults, freezeFrozenIndexBuilder, frozenMemoryBreakdown, suggestFromRawResults, suggestFromSearchResults };
 export type { BM25Params, BinaryCompression, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SaveBinaryOptions, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };