verso-db 0.1.4 → 0.2.0

package/dist/encoding/DeltaEncoder.js

@@ -0,0 +1,199 @@
+/**
+ * Delta Encoding with Varint for Neighbor Lists
+ *
+ * Implements delta-encoded neighbor lists as used by Qdrant for ~38% storage reduction.
+ * Neighbor IDs are sorted, then stored as deltas with variable-length encoding.
+ *
+ * Format:
+ * - First ID stored as full uint32
+ * - Subsequent IDs stored as varint deltas from previous ID
+ *
+ * Varint encoding (like Protocol Buffers):
+ * - Values 0-127: 1 byte
+ * - Values 128-16383: 2 bytes
+ * - Values 16384-2097151: 3 bytes
+ * - Values 2097152-268435455: 4 bytes
+ * - Larger: 5 bytes
+ */
+import { VectorDBError } from '../errors.js';
+/**
+ * Encode an unsigned integer as a varint
+ * Returns the number of bytes written
+ */
+export function encodeVarint(value, buffer, offset) {
+    let v = value >>> 0; // Ensure unsigned
+    let bytesWritten = 0;
+    while (v >= 0x80) {
+        buffer[offset + bytesWritten] = (v & 0x7f) | 0x80;
+        v >>>= 7;
+        bytesWritten++;
+    }
+    buffer[offset + bytesWritten] = v;
+    return bytesWritten + 1;
+}
+/**
+ * Decode a varint from buffer
+ * Returns [value, bytesRead]
+ */
+export function decodeVarint(buffer, offset) {
+    let result = 0;
+    let shift = 0;
+    let bytesRead = 0;
+    while (offset + bytesRead < buffer.length) {
+        const byte = buffer[offset + bytesRead];
+        if (shift < 28) {
+            result |= (byte & 0x7f) << shift;
+        }
+        else {
+            // At shift >= 28, use multiplication to avoid sign-bit corruption from << on int32
+            result = (result + (byte & 0x7f) * (2 ** shift)) >>> 0;
+        }
+        bytesRead++;
+        if ((byte & 0x80) === 0) {
+            return [result >>> 0, bytesRead];
+        }
+        shift += 7;
+        if (shift > 35) {
+            throw new VectorDBError('Varint too long', 'CORRUPT_INDEX');
+        }
+    }
+    throw new VectorDBError('Unexpected end of buffer', 'CORRUPT_INDEX');
+}
+/**
+ * Calculate the number of bytes needed to encode a varint
+ */
+export function varintSize(value) {
+    let v = value >>> 0;
+    let size = 1;
+    while (v >= 0x80) {
+        v >>>= 7;
+        size++;
+    }
+    return size;
+}
+/**
+ * Delta-encode a sorted array of neighbor IDs
+ * Returns the encoded buffer
+ */
+export function deltaEncodeNeighbors(neighbors, preSorted = false) {
+    if (neighbors.length === 0) {
+        return new Uint8Array(0);
+    }
+    for (let i = 0; i < neighbors.length; i++) {
+        const id = neighbors[i];
+        if (!Number.isInteger(id) || id < 0 || id > 0xFFFFFFFF) {
+            throw new VectorDBError(`Invalid neighbor ID at index ${i}: ${id}`, 'VALIDATION_ERROR');
+        }
+    }
+    // Sort neighbors for optimal delta encoding
+    const sorted = preSorted ? neighbors : neighbors.slice().sort((a, b) => a - b);
+    // Calculate required buffer size
+    let size = 4; // First ID as uint32
+    let prev = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        const delta = sorted[i] - prev;
+        size += varintSize(delta);
+        prev = sorted[i];
+    }
+    // Encode
+    const buffer = new Uint8Array(size);
+    const view = new DataView(buffer.buffer);
+    // First ID as full uint32 (little-endian)
+    view.setUint32(0, sorted[0], true);
+    let offset = 4;
+    // Remaining as deltas
+    prev = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        const delta = sorted[i] - prev;
+        offset += encodeVarint(delta, buffer, offset);
+        prev = sorted[i];
+    }
+    return buffer;
+}
+/**
+ * Decode a delta-encoded neighbor list
+ * Returns the original neighbor IDs (sorted)
+ */
+export function deltaDecodeNeighbors(buffer, count) {
+    if (count === 0 || buffer.length === 0) {
+        return [];
+    }
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    const neighbors = new Array(count);
+    // First ID as full uint32
+    neighbors[0] = view.getUint32(0, true);
+    let offset = 4;
+    // Remaining as deltas
+    for (let i = 1; i < count; i++) {
+        const [delta, bytesRead] = decodeVarint(buffer, offset);
+        neighbors[i] = neighbors[i - 1] + delta;
+        offset += bytesRead;
+    }
+    return neighbors;
+}
+/**
+ * Calculate the encoded size for a neighbor list without actually encoding
+ * Useful for calculating total buffer size before serialization
+ */
+export function deltaEncodedSize(neighbors, preSorted = false) {
+    if (neighbors.length === 0) {
+        return 0;
+    }
+    for (let i = 0; i < neighbors.length; i++) {
+        const id = neighbors[i];
+        if (!Number.isInteger(id) || id < 0 || id > 0xFFFFFFFF) {
+            throw new VectorDBError(`Invalid neighbor ID at index ${i}: ${id}`, 'VALIDATION_ERROR');
+        }
+    }
+    const sorted = preSorted ? neighbors : neighbors.slice().sort((a, b) => a - b);
+    let size = 4; // First ID as uint32
+    let prev = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        const delta = sorted[i] - prev;
+        size += varintSize(delta);
+        prev = sorted[i];
+    }
+    return size;
+}
+/**
+ * Batch encode multiple neighbor lists efficiently
+ * Returns a single buffer with all encoded lists concatenated
+ * Also returns offsets for each list
+ */
+export function deltaEncodeBatch(neighborLists) {
+    // Sort each list once, then pass pre-sorted to both size calculation and encoding
+    const sortedLists = neighborLists.map(list => list.length > 0 ? list.slice().sort((a, b) => a - b) : list);
+    // Calculate total size and individual sizes
+    const sizes = sortedLists.map(list => deltaEncodedSize(list, true));
+    const totalSize = sizes.reduce((a, b) => a + b, 0);
+    // Allocate single buffer
+    const buffer = new Uint8Array(totalSize);
+    const offsets = [];
+    let currentOffset = 0;
+    for (let i = 0; i < sortedLists.length; i++) {
+        offsets.push(currentOffset);
+        if (sortedLists[i].length > 0) {
+            const encoded = deltaEncodeNeighbors(sortedLists[i], true);
+            buffer.set(encoded, currentOffset);
+            currentOffset += encoded.length;
+        }
+    }
+    return { buffer, offsets, sizes };
+}
+/**
+ * Decode a batch of neighbor lists from a single buffer
+ */
+export function deltaDecodeBatch(buffer, offsets, sizes, counts) {
+    const results = [];
+    for (let i = 0; i < offsets.length; i++) {
+        if (counts[i] === 0 || sizes[i] === 0) {
+            results.push([]);
+        }
+        else {
+            const slice = buffer.subarray(offsets[i], offsets[i] + sizes[i]);
+            results.push(deltaDecodeNeighbors(slice, counts[i]));
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=DeltaEncoder.js.map

package/dist/encoding/DeltaEncoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeltaEncoder.js","sourceRoot":"","sources":["../../src/encoding/DeltaEncoder.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,97 @@
+/**
+ * Base error class for all VectorDB errors
+ */
+export class VectorDBError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'VectorDBError';
+        this.code = code;
+    }
+}
+/**
+ * Thrown when vector dimensions don't match expected dimensions
+ */
+export class DimensionMismatchError extends VectorDBError {
+    expected;
+    actual;
+    constructor(expected, actual, context) {
+        const message = context
+            ? `${context}: expected dimension ${expected}, got ${actual}`
+            : `Dimension mismatch: expected ${expected}, got ${actual}`;
+        super(message, 'DIMENSION_MISMATCH');
+        this.name = 'DimensionMismatchError';
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/**
+ * Thrown when attempting to add a vector with an ID that already exists
+ */
+export class DuplicateVectorError extends VectorDBError {
+    ids;
+    constructor(ids) {
+        const message = ids.length === 1
+            ? `Vector with ID '${ids[0]}' already exists`
+            : `Vectors with IDs already exist: ${ids.join(', ')}`;
+        super(message, 'DUPLICATE_VECTOR');
+        this.name = 'DuplicateVectorError';
+        this.ids = ids;
+    }
+}
+/**
+ * Thrown when a requested collection does not exist
+ */
+export class CollectionNotFoundError extends VectorDBError {
+    collectionName;
+    constructor(collectionName) {
+        super(`Collection '${collectionName}' does not exist`, 'COLLECTION_NOT_FOUND');
+        this.name = 'CollectionNotFoundError';
+        this.collectionName = collectionName;
+    }
+}
+/**
+ * Thrown when attempting to create a collection that already exists
+ */
+export class CollectionExistsError extends VectorDBError {
+    collectionName;
+    constructor(collectionName) {
+        super(`Collection '${collectionName}' already exists`, 'COLLECTION_EXISTS');
+        this.name = 'CollectionExistsError';
+        this.collectionName = collectionName;
+    }
+}
+/**
+ * Thrown when a storage operation fails
+ */
+export class StorageError extends VectorDBError {
+    operation;
+    path;
+    constructor(operation, message, path) {
+        super(`Storage ${operation} failed: ${message}`, 'STORAGE_ERROR');
+        this.name = 'StorageError';
+        this.operation = operation;
+        this.path = path;
+    }
+}
+/**
+ * Thrown when quantization operations fail
+ */
+export class QuantizationError extends VectorDBError {
+    constructor(message) {
+        super(message, 'QUANTIZATION_ERROR');
+        this.name = 'QuantizationError';
+    }
+}
+/**
+ * Thrown when a vector is not found in the index
+ */
+export class VectorNotFoundError extends VectorDBError {
+    vectorId;
+    constructor(vectorId) {
+        super(`Vector '${vectorId}' not found`, 'VECTOR_NOT_FOUND');
+        this.name = 'VectorNotFoundError';
+        this.vectorId = vectorId;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * verso - High-performance vector search with HNSW indexing
+ * verso-db - High-performance vector search with HNSW indexing
  *
  * Features:
  * - HNSW algorithm for approximate nearest neighbor search
@@ -7,13 +7,13 @@
  * - Int8 scalar quantization for 4x memory reduction
  * - Batch query support for improved throughput
  * - Parameter presets for different use cases
- * - Multi-platform: Bun (file system) and Browser (OPFS)
+ * - Multi-platform: Bun/Node.js (file system) and Browser (OPFS)
  *
  * @example
  * ```typescript
- * import { VectorDB, getRecommendedPreset } from 'verso';
+ * import { VectorDB, getRecommendedPreset } from 'verso-db';
  *
- * const db = new VectorDB();
+ * const db = new VectorDB({ storagePath: './vectors' });
  * const preset = getRecommendedPreset(768);
  *
  * const collection = await db.createCollection('my-vectors', {
@@ -36,29 +36,28 @@
  * ```
  *
  * @packageDocumentation
- * @module verso
+ * @module verso-db
  */
 export { VectorDB } from './VectorDB';
-export type { VectorDBConfig } from './VectorDB';
+export type { VectorDBConfig, CollectionConfig } from './VectorDB';
 export { Collection } from './Collection';
-export type { AddConfig, QueryConfig, QueryResult } from './Collection';
+export type { AddConfig, QueryConfig, QueryResult, CollectionOptions } from './Collection';
 export { HNSWIndex } from './HNSWIndex';
-export type { DistanceMetric, Node } from './HNSWIndex';
-export type { DistanceBackend } from './backends/DistanceBackend';
-export { JsDistanceBackend, dotProductFast, l2SquaredFast, normalizeInPlace, cosineDistanceFast } from './backends/JsDistanceBackend';
-export { BinaryHeap } from './BinaryHeap';
-export { MaxBinaryHeap } from './MaxBinaryHeap';
-export { ScalarQuantizer, QuantizedVectorStore, dotProductInt8, l2SquaredInt8, cosineDistanceInt8 } from './quantization/ScalarQuantizer';
-export type { QuantizationParams } from './quantization/ScalarQuantizer';
+export type { DistanceMetric } from './HNSWIndex';
 export type { HNSWPreset } from './presets';
 export { PRESET_LOW_DIM, PRESET_MEDIUM_DIM, PRESET_HIGH_DIM, PRESET_VERY_HIGH_DIM, PRESET_SMALL_DATASET, PRESET_LARGE_DATASET, PRESET_MAX_RECALL, PRESET_LOW_LATENCY, PRESETS, getRecommendedPreset, getPreset, getRAGPreset } from './presets';
+export { ScalarQuantizer } from './quantization/ScalarQuantizer';
+export type { QuantizationParams } from './quantization/ScalarQuantizer';
 export type { StorageBackend, StorageOptions } from './storage/StorageBackend';
 export { BunStorageBackend } from './storage/BunStorageBackend';
 export { MemoryBackend } from './storage/MemoryBackend';
 export { OPFSBackend } from './storage/OPFSBackend';
 export { createStorageBackend, getRecommendedStorageType, isStorageTypeAvailable, type StorageType, type CreateStorageOptions, } from './storage/createStorageBackend';
-export { WriteAheadLog, WALOperationType, type WALEntry, } from './storage/WriteAheadLog';
-export { BatchWriter, createBatchWriter, type BatchWriterOptions, } from './storage/BatchWriter';
-export { deltaEncodeNeighbors, deltaDecodeNeighbors, deltaEncodedSize, encodeVarint, decodeVarint, } from './encoding/DeltaEncoder';
+export { WriteAheadLog, WALOperationType } from './storage/WriteAheadLog';
+export type { WALEntry } from './storage/WriteAheadLog';
+export { BatchWriter, createBatchWriter } from './storage/BatchWriter';
+export type { BatchWriterOptions } from './storage/BatchWriter';
+export { WorkerPool } from './WorkerPool';
+export { WorkerSearchState } from './SearchWorker';
 export { VectorDBError, DimensionMismatchError, DuplicateVectorError, CollectionNotFoundError, CollectionExistsError, StorageError, QuantizationError, VectorNotFoundError, } from './errors';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGxD,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AACxC,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,OAAO,EACP,oBAAoB,EACpB,SAAS,EACT,YAAY,EACb,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,KAAK,QAAQ,GACd,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACb,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,OAAO,EACP,oBAAoB,EACpB,SAAS,EACT,YAAY,EACb,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGzE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,YAAY,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACvE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,UAAU,CAAC"}