@yoch/frozenminisearch 1.2.4 → 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;
 };
@@ -271,6 +270,15 @@ interface RawResultValue {
     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;
@@ -460,6 +468,10 @@ 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;
@@ -564,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;
@@ -601,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;
@@ -638,41 +649,30 @@ declare class FrozenMiniSearch<T = any> {
      * 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.
@@ -680,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;
 }
 
+/** 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 };