verso-db 0.1.1

package/dist/presets.d.ts

@@ -0,0 +1,91 @@
+/**
+ * HNSW Parameter Presets
+ *
+ * These presets are optimized based on extensive benchmarking to achieve
+ * the target recall@10 >= 95% for different dataset sizes and dimensions.
+ *
+ * Key parameters:
+ * - M: Maximum connections per node (higher = better recall, more memory)
+ * - efConstruction: Beam width during index building (higher = better quality, slower build)
+ * - efSearch: Beam width during search (higher = better recall, slower search)
+ */
+export interface HNSWPreset {
+    name: string;
+    description: string;
+    M: number;
+    efConstruction: number;
+    efSearch: number;
+    expectedRecall: number;
+    targetDimensions: string;
+    targetDatasetSize: string;
+}
+/**
+ * Preset for low-dimensional vectors (128D or less)
+ * Suitable for: Image features, word2vec, GloVe embeddings
+ */
+export declare const PRESET_LOW_DIM: HNSWPreset;
+/**
+ * Preset for medium-dimensional vectors (256-512D)
+ * Suitable for: Sentence embeddings, smaller transformer outputs
+ */
+export declare const PRESET_MEDIUM_DIM: HNSWPreset;
+/**
+ * Preset for high-dimensional vectors (768D+)
+ * Suitable for: BERT, GPT embeddings, Cohere, OpenAI embeddings
+ * This is the recommended preset for RAG applications
+ *
+ * Benchmarked on Cohere Wikipedia 1024D (495K vectors):
+ * - efSearch=128: 99.2% recall, 168 QPS, 10.72ms P99
+ */
+export declare const PRESET_HIGH_DIM: HNSWPreset;
+/**
+ * Preset for very high-dimensional vectors (1536D+)
+ * Suitable for: OpenAI text-embedding-ada-002, text-embedding-3-large
+ *
+ * Scaled from PRESET_HIGH_DIM benchmarks (higher M for higher dimensions)
+ */
+export declare const PRESET_VERY_HIGH_DIM: HNSWPreset;
+/**
+ * Preset for small datasets (<10K vectors)
+ * Prioritizes recall over speed since brute-force is viable
+ */
+export declare const PRESET_SMALL_DATASET: HNSWPreset;
+/**
+ * Preset for large datasets (100K-1M vectors)
+ * Balances recall with build time and memory
+ *
+ * Benchmarked on Cohere Wikipedia 1024D (495K vectors):
+ * - efSearch=128: 99.2% recall, 168 QPS
+ */
+export declare const PRESET_LARGE_DATASET: HNSWPreset;
+/**
+ * Preset for maximum recall (prioritizes accuracy over speed)
+ * Use when recall is critical and latency is acceptable
+ */
+export declare const PRESET_MAX_RECALL: HNSWPreset;
+/**
+ * Preset for minimum latency (prioritizes speed over recall)
+ * Use when latency is critical and 90% recall is acceptable
+ */
+export declare const PRESET_LOW_LATENCY: HNSWPreset;
+/**
+ * All available presets
+ */
+export declare const PRESETS: Record<string, HNSWPreset>;
+/**
+ * Get recommended preset based on dimension and dataset size
+ *
+ * For high-dimensional vectors (768D+), dimension takes priority over dataset size
+ * because recall degrades significantly without higher M values.
+ */
+export declare function getRecommendedPreset(dimension: number, datasetSize?: number): HNSWPreset;
+/**
+ * Get preset by name
+ */
+export declare function getPreset(name: string): HNSWPreset | undefined;
+/**
+ * RAG-specific preset recommendation
+ * For typical RAG applications using popular embedding models
+ */
+export declare function getRAGPreset(embeddingModel: string): HNSWPreset;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,UAS5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAS/B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,UAS7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,UASlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,UASlC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,UASlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAS/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAShC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAS9C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAkBxF;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE9D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,CAyB/D"}

package/dist/quantization/ScalarQuantizer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Scalar Quantizer for Int8 vector compression
+ *
+ * Provides 4x memory reduction by converting Float32 vectors to Int8.
+ * Expected performance:
+ * - Memory: 4x reduction (32 bits → 8 bits per dimension)
+ * - Speed: ~3.5x faster distance calculations (smaller data, better cache)
+ * - Recall: <2% loss compared to float32
+ *
+ * Uses range quantization: maps [min, max] to [-128, 127]
+ */
+export interface QuantizationParams {
+    min: Float32Array;
+    max: Float32Array;
+    scale: Float32Array;
+    offset: Float32Array;
+}
+export declare class ScalarQuantizer {
+    private dimension;
+    private params;
+    private trained;
+    constructor(dimension: number);
+    /**
+     * Train the quantizer on a set of vectors to determine optimal range
+     */
+    train(vectors: Float32Array[]): void;
+    /**
+     * Get training status
+     */
+    isTrained(): boolean;
+    /**
+     * Get quantization parameters
+     */
+    getParams(): QuantizationParams | null;
+    /**
+     * Set quantization parameters (for loading saved quantizer)
+     */
+    setParams(params: QuantizationParams): void;
+    /**
+     * Quantize a single float32 vector to int8
+     */
+    quantize(vector: Float32Array): Int8Array;
+    /**
+     * Quantize multiple vectors
+     */
+    quantizeBatch(vectors: Float32Array[]): Int8Array[];
+    /**
+     * Dequantize an int8 vector back to float32 (for rescoring)
+     */
+    dequantize(vector: Int8Array): Float32Array;
+    /**
+     * Serialize quantization parameters for saving
+     */
+    serialize(): ArrayBuffer;
+    /**
+     * Load quantization parameters
+     */
+    static deserialize(buffer: ArrayBuffer): ScalarQuantizer;
+}
+/**
+ * Fast Int8 distance calculations
+ * These are optimized for quantized vectors and provide significant speedup
+ */
+/**
+ * Compute dot product between two Int8 vectors
+ * Uses 8-wide unrolling for better ILP (instruction-level parallelism)
+ */
+export declare function dotProductInt8(a: Int8Array, b: Int8Array): number;
+/**
+ * Compute L2 squared distance between two Int8 vectors
+ * Uses 8-wide unrolling for better ILP
+ */
+export declare function l2SquaredInt8(a: Int8Array, b: Int8Array): number;
+/**
+ * Compute approximate cosine distance for Int8 vectors
+ * Note: This is approximate because quantization changes magnitude
+ * Uses 8-wide unrolling with separate accumulators for better ILP
+ */
+export declare function cosineDistanceInt8(a: Int8Array, b: Int8Array): number;
+/**
+ * QuantizedVectorStore - Efficient storage for quantized vectors
+ */
+export declare class QuantizedVectorStore {
+    private quantizer;
+    private vectors;
+    private originalVectors;
+    private keepOriginals;
+    constructor(dimension: number, keepOriginals?: boolean);
+    /**
+     * Train the quantizer and add vectors
+     */
+    addVectors(vectors: Float32Array[]): void;
+    /**
+     * Get quantized vector by index
+     */
+    getQuantized(index: number): Int8Array;
+    /**
+     * Get original float32 vector by index (for rescoring)
+     */
+    getOriginal(index: number): Float32Array | null;
+    /**
+     * Get number of vectors
+     */
+    size(): number;
+    /**
+     * Calculate memory usage in bytes
+     */
+    memoryUsage(): {
+        quantized: number;
+        original: number;
+        total: number;
+    };
+}
+//# sourceMappingURL=ScalarQuantizer.d.ts.map

package/dist/quantization/ScalarQuantizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScalarQuantizer.d.ts","sourceRoot":"","sources":["../../src/quantization/ScalarQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,OAAO,CAAkB;gBAErB,SAAS,EAAE,MAAM;IAI7B;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAsCpC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,SAAS,IAAI,kBAAkB,GAAG,IAAI;IAItC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAK3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS;IAkBzC;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE;IAQnD;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY;IAiB3C;;OAEG;IACH,SAAS,IAAI,WAAW;IAuBxB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe;CAqBzD;AAED;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAyBjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAkChE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAwCrE;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,aAAa,CAAU;gBAEnB,SAAS,EAAE,MAAM,EAAE,aAAa,UAAO;IAOnD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAazC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAItC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAK/C;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,WAAW,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAOtE"}

package/dist/storage/BatchWriter.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Batch Write Coalescing for Storage Backends
+ *
+ * Buffers writes in memory and flushes them in batches to reduce I/O operations.
+ * This is especially beneficial for:
+ * - OPFS where each write has overhead
+ * - IndexedDB where transactions have cost
+ * - Network storage where round-trips are expensive
+ *
+ * Features:
+ * - Configurable flush thresholds (count and size)
+ * - Automatic flushing when thresholds are reached
+ * - Explicit flush for durability guarantees
+ * - Coalesces multiple writes to the same key
+ */
+import type { StorageBackend } from './StorageBackend';
+export interface BatchWriterOptions {
+    /** Maximum number of pending writes before auto-flush (default: 100) */
+    maxPendingWrites?: number;
+    /** Maximum total size of pending data in bytes before auto-flush (default: 1MB) */
+    maxPendingBytes?: number;
+    /** Auto-flush interval in milliseconds (0 = disabled, default: 0) */
+    autoFlushInterval?: number;
+}
+/**
+ * BatchWriter - Coalesces multiple writes into batched flushes
+ */
+export declare class BatchWriter {
+    private backend;
+    private pendingWrites;
+    private pendingAppends;
+    private pendingBytes;
+    private maxPendingWrites;
+    private maxPendingBytes;
+    private autoFlushInterval;
+    private flushTimer;
+    private isFlushing;
+    private flushPromise;
+    constructor(backend: StorageBackend, options?: BatchWriterOptions);
+    /**
+     * Write data to a key (buffered)
+     * Multiple writes to the same key will coalesce to the last value
+     */
+    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Append data to a key (buffered)
+     * Multiple appends to the same key will be concatenated
+     */
+    append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Delete a key (buffered)
+     * Clears any pending writes/appends for this key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Read data from a key
+     * Returns pending data if available, otherwise reads from backend
+     */
+    read(key: string): Promise<ArrayBuffer | null>;
+    /**
+     * Check if thresholds are exceeded and flush if needed
+     */
+    private checkThresholds;
+    /**
+     * Flush all pending writes to the backend
+     */
+    flush(): Promise<void>;
+    private doFlush;
+    /**
+     * Get statistics about pending writes
+     */
+    getStats(): {
+        pendingWrites: number;
+        pendingAppends: number;
+        pendingBytes: number;
+        maxPendingWrites: number;
+        maxPendingBytes: number;
+    };
+    /**
+     * Check if there are pending writes
+     */
+    hasPendingWrites(): boolean;
+    /**
+     * Start auto-flush timer
+     */
+    private startAutoFlush;
+    /**
+     * Stop auto-flush timer
+     */
+    stopAutoFlush(): void;
+    /**
+     * Close the batch writer, flushing any pending writes
+     */
+    close(): Promise<void>;
+    /**
+     * Get the underlying storage backend
+     */
+    getBackend(): StorageBackend;
+}
+/**
+ * Create a batch writer that wraps an existing storage backend
+ */
+export declare function createBatchWriter(backend: StorageBackend, options?: BatchWriterOptions): BatchWriter;
+//# sourceMappingURL=BatchWriter.d.ts.map

package/dist/storage/BatchWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchWriter.d.ts","sourceRoot":"","sources":["../../src/storage/BatchWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAQD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,cAAc,CAAwC;IAC9D,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,YAAY,CAA8B;gBAEtC,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAWrE;;;OAGG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BvE;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BxE;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBxC;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuCpD;;OAEG;YACW,eAAe;IAQ7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAsBd,OAAO;IAqCrB;;OAEG;IACH,QAAQ,IAAI;QACV,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB;IAUD;;OAEG;IACH,gBAAgB,IAAI,OAAO;IAI3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,aAAa,IAAI,IAAI;IAOrB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,UAAU,IAAI,cAAc;CAG7B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,WAAW,CAEb"}

package/dist/storage/BunStorageBackend.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Bun Storage Backend
+ *
+ * High-performance file system storage using Bun's native APIs.
+ * Features:
+ * - Auto-initializing (no manual init() required)
+ * - Automatic memory mapping for large files
+ * - Efficient async I/O with O(1) append
+ * - Native TypedArray support
+ */
+import type { StorageBackend } from './StorageBackend';
+export declare class BunStorageBackend implements StorageBackend {
+    readonly type = "bun";
+    private basePath;
+    private dirCache;
+    /**
+     * Create a new Bun storage backend
+     * @param basePath Base directory for all storage operations
+     */
+    constructor(basePath?: string);
+    /**
+     * Ensure directory exists, using cache to avoid redundant mkdir calls
+     */
+    private ensureDir;
+    /**
+     * Get the full path for a key
+     */
+    private getFullPath;
+    /**
+     * Ensure base directory exists (optional - operations auto-initialize)
+     * @deprecated No longer required - write/append create directories automatically
+     */
+    init(): Promise<void>;
+    read(key: string): Promise<ArrayBuffer | null>;
+    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(prefix?: string): Promise<string[]>;
+    mkdir(dirPath: string): Promise<void>;
+    /**
+     * Delete all data in the storage directory
+     */
+    clear(): Promise<void>;
+    /**
+     * Get file size without reading the entire file
+     */
+    size(key: string): Promise<number>;
+    /**
+     * Read a file as a stream (for large files)
+     */
+    stream(key: string): ReadableStream<Uint8Array> | null;
+    /**
+     * Get the base path
+     */
+    getBasePath(): string;
+}
+//# sourceMappingURL=BunStorageBackend.d.ts.map

package/dist/storage/BunStorageBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BunStorageBackend.d.ts","sourceRoot":"","sources":["../../src/storage/BunStorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,QAAQ,CAA0B;IAE1C;;;OAGG;gBACS,QAAQ,GAAE,MAA0B;IAIhD;;OAEG;YACW,SAAS;IAMvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAW9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMrC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAexC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAWxC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI;IAMtD;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/storage/MemoryBackend.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-Memory Storage Backend
+ *
+ * Stores all data in memory using a Map. Useful for:
+ * - Testing without file system
+ * - Small datasets that fit in memory
+ * - Browser environments without OPFS/IndexedDB
+ * - Temporary caches
+ */
+import type { StorageBackend } from './StorageBackend';
+export declare class MemoryBackend implements StorageBackend {
+    readonly type = "memory";
+    private storage;
+    private directories;
+    constructor();
+    read(key: string): Promise<ArrayBuffer | null>;
+    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(prefix?: string): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Get memory usage statistics
+     */
+    getStats(): {
+        keyCount: number;
+        totalBytes: number;
+    };
+    /**
+     * Export all data as a serializable object
+     * Useful for debugging or saving state
+     */
+    export(): Record<string, ArrayBuffer>;
+    /**
+     * Import data from a serializable object
+     */
+    import(data: Record<string, ArrayBuffer>): void;
+}
+//# sourceMappingURL=MemoryBackend.d.ts.map

package/dist/storage/MemoryBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryBackend.d.ts","sourceRoot":"","sources":["../../src/storage/MemoryBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,WAAW,CAA0B;;IAMvC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAO9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAelE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxC;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,QAAQ,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAWpD;;;OAGG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAQrC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI;CAKhD"}

package/dist/storage/OPFSBackend.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Origin Private File System (OPFS) Storage Backend
+ *
+ * High-performance browser storage using the File System Access API.
+ * OPFS provides file-like semantics with significantly better performance
+ * than IndexedDB for large binary data (up to 10x faster).
+ *
+ * Features:
+ * - Auto-initializing (no manual init() required)
+ * - High performance for large binary data
+ *
+ * Browser Support:
+ * - Chrome 86+
+ * - Safari 15.2+
+ * - Firefox 111+
+ * - Edge 86+
+ *
+ * Note: This module is designed for browser environments only.
+ * It will not work in Node.js/Bun server environments.
+ */
+import type { StorageBackend } from './StorageBackend';
+export declare class OPFSBackend implements StorageBackend {
+    readonly type = "opfs";
+    private root;
+    private initialized;
+    /**
+     * Initialize the OPFS backend (optional - auto-initializes on first operation)
+     * @deprecated No longer required - operations auto-initialize
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure backend is initialized (lazy init on first use)
+     */
+    private ensureInitialized;
+    /**
+     * Get a file handle, creating parent directories as needed
+     */
+    private getFileHandle;
+    /**
+     * Get a directory handle, creating if needed
+     */
+    private getDirectoryHandle;
+    read(key: string): Promise<ArrayBuffer | null>;
+    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(prefix?: string): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    /**
+     * Clear all data in OPFS
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if OPFS is available in the current environment
+     */
+    static isAvailable(): boolean;
+}
+//# sourceMappingURL=OPFSBackend.d.ts.map

package/dist/storage/OPFSBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSBackend.d.ts","sourceRoot":"","sources":["../../src/storage/OPFSBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,WAAY,YAAW,cAAc;IAChD,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,IAAI,CAA0C;IACtD,OAAO,CAAC,WAAW,CAAkB;IAErC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B;;OAEG;YACW,iBAAiB;IAM/B;;OAEG;YACW,aAAa;IA0B3B;;OAEG;YACW,kBAAkB;IAkB1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAc9C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0BxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;CAG9B"}

package/dist/storage/StorageBackend.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Storage Backend Interface
+ *
+ * Provides a unified interface for persisting vector index data across different platforms:
+ * - Bun/Node.js: File system storage with Bun.file APIs
+ * - Browser: OPFS (Origin Private File System) or IndexedDB
+ * - Testing: In-memory storage
+ *
+ * All operations are async to support both sync and async underlying storage.
+ */
+export interface StorageBackend {
+    /**
+     * Read data from storage
+     * @param key Unique key/path for the data
+     * @returns ArrayBuffer of data or null if not found
+     */
+    read(key: string): Promise<ArrayBuffer | null>;
+    /**
+     * Write data to storage (overwrites existing)
+     * @param key Unique key/path for the data
+     * @param data Data to write
+     */
+    write(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Append data to existing file (for WAL)
+     * @param key Unique key/path for the data
+     * @param data Data to append
+     */
+    append(key: string, data: ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Delete data from storage
+     * @param key Unique key/path to delete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if key exists in storage
+     * @param key Unique key/path to check
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * List all keys with given prefix
+     * @param prefix Optional prefix to filter keys
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Create a directory (for file-based backends)
+     * @param path Directory path to create
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Get storage type identifier
+     */
+    readonly type: string;
+}
+/**
+ * Options for creating a storage backend
+ */
+export interface StorageOptions {
+    /** Base path for file-based storage */
+    path?: string;
+    /** Database name for IndexedDB */
+    dbName?: string;
+    /** Store name for IndexedDB */
+    storeName?: string;
+}
+//# sourceMappingURL=StorageBackend.d.ts.map

package/dist/storage/StorageBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageBackend.d.ts","sourceRoot":"","sources":["../../src/storage/StorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE/C;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzC;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/storage/WriteAheadLog.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Write-Ahead Log (WAL) for Incremental Index Updates
+ *
+ * Provides durability and efficient incremental writes for HNSW index operations.
+ * Instead of rewriting the entire index on each update, operations are appended
+ * to a log file. The log can be compacted into a full snapshot periodically.
+ *
+ * Benefits:
+ * - Fast appends (no full serialization)
+ * - Crash recovery (replay log after restart)
+ * - Reduced I/O for frequent updates
+ */
+export declare enum WALOperationType {
+    ADD_VECTOR = 1,
+    ADD_NEIGHBORS = 2,
+    UPDATE_ENTRY_POINT = 3,
+    CHECKPOINT = 4
+}
+export interface WALEntry {
+    type: WALOperationType;
+    timestamp: number;
+    data: ArrayBuffer;
+}
+/**
+ * WriteAheadLog - Append-only log for incremental index updates
+ */
+export declare class WriteAheadLog {
+    private logPath;
+    private pendingEntries;
+    private flushThreshold;
+    private lastFlushTime;
+    private entryCount;
+    /**
+     * Create a new WAL
+     * @param basePath Base path for the index (WAL will be basePath.wal)
+     * @param flushThreshold Number of entries before auto-flush (default: 100)
+     */
+    constructor(basePath: string, flushThreshold?: number);
+    /**
+     * Get the WAL file path
+     */
+    getPath(): string;
+    /**
+     * Check if WAL file exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Append a vector addition operation to the log
+     */
+    appendVector(id: number, vector: Float32Array): Promise<void>;
+    /**
+     * Append a neighbor update operation to the log
+     */
+    appendNeighbors(nodeId: number, layer: number, neighbors: number[]): Promise<void>;
+    /**
+     * Append entry point update to the log
+     */
+    appendEntryPointUpdate(entryPointId: number, maxLevel: number): Promise<void>;
+    /**
+     * Write a checkpoint marker to the log
+     */
+    checkpoint(): Promise<void>;
+    /**
+     * Serialize a WAL entry to bytes
+     */
+    private serializeEntry;
+    /**
+     * Flush pending entries to disk
+     * Uses O(1) append instead of O(n) read-modify-write
+     */
+    flush(): Promise<void>;
+    /**
+     * Read all entries from the WAL file
+     */
+    readEntries(): Promise<WALEntry[]>;
+    /**
+     * Parse a vector addition entry
+     */
+    static parseVectorEntry(data: ArrayBuffer): {
+        id: number;
+        vector: Float32Array;
+    };
+    /**
+     * Parse a neighbor update entry
+     */
+    static parseNeighborsEntry(data: ArrayBuffer): {
+        nodeId: number;
+        layer: number;
+        neighbors: number[];
+    };
+    /**
+     * Parse an entry point update entry
+     */
+    static parseEntryPointEntry(data: ArrayBuffer): {
+        entryPointId: number;
+        maxLevel: number;
+    };
+    /**
+     * Get entry count since last compact
+     */
+    getEntryCount(): number;
+    /**
+     * Clear the WAL (after successful compaction)
+     */
+    clear(): Promise<void>;
+    /**
+     * Delete the WAL file
+     */
+    delete(): Promise<void>;
+}
+//# sourceMappingURL=WriteAheadLog.d.ts.map