@yoch/frozenminisearch 1.0.2 → 1.2.0

package/dist/es/index.d.ts

@@ -113,7 +113,7 @@ type SearchOptionsWithDefaults = SearchOptions & {
     bm25: BM25Params;
 };
 /**
- * Configuration options passed to the {@link MiniSearch} constructor.
+ * Configuration options compatible with the MiniSearch constructor.
  *
  * @typeParam T  The type of documents being indexed.
  */
@@ -134,7 +134,7 @@ type Options<T = any> = {
     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 {@link MiniSearch.discard}; defaults to `true`. */
+    /** Auto-vacuum behaviour after MiniSearch `discard`; defaults to `true`. */
     autoVacuum?: boolean | AutoVacuumOptions;
     /** Default search options. */
     searchOptions?: SearchOptions;
@@ -158,6 +158,20 @@ type OptionsWithDefaults<T = any> = Options<T> & {
     searchOptions: SearchOptionsWithDefaults;
     autoSuggestOptions: SearchOptions;
 };
+/** Compression codec selection for frozen binary snapshots. */
+type BinaryCompression = 'auto' | 'raw' | 'zstd' | 'zlib';
+/** Options for `saveBinarySync()` / `saveBinaryAsync()`. */
+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
+     * - `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+
+     */
+    compression?: BinaryCompression;
+};
 /**
  * A search-completion suggestion.
  */
@@ -459,7 +473,7 @@ interface FrozenMemoryBreakdown {
 /**
  * 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.fromMiniSearchJson}, or binary load instead.
+ * {@link buildFrozenFromDocuments}, {@link FrozenMiniSearch.fromJson}, or binary load instead.
  */
 interface FrozenAssembleParams<T = any> {
     options: OptionsWithDefaults<T>;
@@ -479,7 +493,7 @@ interface FrozenAssembleParams<T = any> {
     postings: FrozenPostingsLayout;
 }
 
-/** Lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format). */
+/** MiniSearch JSON snapshot (`toJSON` wire format, `serializationVersion` 1 or 2). */
 type SerializedIndexEntry = Record<string, number>;
 type MiniSearchSnapshot = {
     documentCount: number;
@@ -596,28 +610,37 @@ declare class FrozenMiniSearch<T = any> {
     search(query: Query, searchOptions?: SearchOptions): SearchResult[];
     autoSuggest(queryString: string, options?: SearchOptions): Suggestion[];
     /** Serialize this index as a frozen binary snapshot (synchronous). */
-    saveBinarySync(): Buffer;
-    /** Non-blocking zstd compression; same output as {@link saveBinarySync}. */
-    saveBinaryAsync(): Promise<Buffer>;
+    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 zstd decompression (bounded memory). */
+    /** 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>;
     /**
-     * Convert a lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format) into a
-     * frozen index. No runtime dependency on the `minisearch` package.
+     * 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 fromMiniSearchJson<T>(json: string, options?: Options<T>): FrozenMiniSearch<T>;
+    static fromJson<T>(json: string, options?: Options<T>): FrozenMiniSearch<T>;
     /**
-     * Same as {@link fromMiniSearchJson} with a pre-parsed snapshot object.
+     * 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>;
-    /** Accepts any object exposing `toJSON()` in lucaong MiniSearch snapshot shape. */
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
     static fromMiniSearch<T>(source: {
         toJSON(): MiniSearchSnapshot;
     }, options?: Options<T>): FrozenMiniSearch<T>;
@@ -634,4 +657,4 @@ declare class FrozenMiniSearch<T = any> {
 }
 
 export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, freezeFrozenIndexBuilder, frozenMemoryBreakdown };
-export type { BM25Params, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };
+export type { BM25Params, BinaryCompression, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SaveBinaryOptions, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };