verso-db 0.1.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"WriteAheadLog.d.ts","sourceRoot":"","sources":["../../src/storage/WriteAheadLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,oBAAY,gBAAgB;IAC1B,UAAU,IAAI;IACd,aAAa,IAAI;IACjB,kBAAkB,IAAI;IACtB,UAAU,IAAI;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;OAIG;gBACS,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAE,MAAY;IAK1D;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAKhC;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnE;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BxF;;OAEG;IACG,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBnF;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;OAEG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgC5B;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IA4BxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE;IAQhF;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE;IAcrG;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAQ1F;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAS9B"}

package/dist/storage/createStorageBackend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Storage Backend Factory
+ *
+ * Auto-detects the best storage backend for the current environment:
+ * - Bun/Node.js: BunStorageBackend (file system)
+ * - Modern browsers: OPFSBackend (Origin Private File System)
+ * - Fallback: MemoryBackend (in-memory)
+ */
+import type { StorageBackend, StorageOptions } from './StorageBackend';
+export type StorageType = 'auto' | 'bun' | 'opfs' | 'memory';
+export interface CreateStorageOptions extends StorageOptions {
+    /** Force a specific storage type */
+    type?: StorageType;
+}
+/**
+ * Create the optimal storage backend for the current environment
+ *
+ * @param options Configuration options
+ * @returns Initialized storage backend
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect best backend
+ * const storage = await createStorageBackend();
+ *
+ * // Force specific backend
+ * const bunStorage = await createStorageBackend({ type: 'bun', path: './data' });
+ * const memStorage = await createStorageBackend({ type: 'memory' });
+ * ```
+ */
+export declare function createStorageBackend(options?: CreateStorageOptions): Promise<StorageBackend>;
+/**
+ * Get the recommended storage type for the current environment
+ */
+export declare function getRecommendedStorageType(): StorageType;
+/**
+ * Check if a specific storage type is available
+ */
+export declare function isStorageTypeAvailable(type: StorageType): boolean;
+//# sourceMappingURL=createStorageBackend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createStorageBackend.d.ts","sourceRoot":"","sources":["../../src/storage/createStorageBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,oCAAoC;IACpC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAmBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA+ClG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAYvD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAajE"}

package/dist/storage/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Storage Module
+ *
+ * Provides pluggable storage backends for vector index persistence.
+ * Supports multiple platforms:
+ * - Bun/Node.js: File system with Bun.file APIs
+ * - Modern browsers: OPFS (Origin Private File System)
+ * - Testing/fallback: In-memory storage
+ *
+ * @example
+ * ```typescript
+ * import { createStorageBackend, WriteAheadLog } from 'bun-vector-search/storage';
+ *
+ * // Auto-detect best storage for current environment
+ * const storage = await createStorageBackend();
+ *
+ * // Use WAL for incremental writes
+ * const wal = new WriteAheadLog('./index');
+ * await wal.appendVector(1, new Float32Array([1, 2, 3]));
+ * await wal.flush();
+ * ```
+ */
+export type { StorageBackend, StorageOptions } from './StorageBackend';
+export { BunStorageBackend } from './BunStorageBackend';
+export { MemoryBackend } from './MemoryBackend';
+export { OPFSBackend } from './OPFSBackend';
+export { createStorageBackend, getRecommendedStorageType, isStorageTypeAvailable, type StorageType, type CreateStorageOptions, } from './createStorageBackend';
+export { WriteAheadLog, WALOperationType, type WALEntry, } from './WriteAheadLog';
+export { BatchWriter, createBatchWriter, type BatchWriterOptions, } from './BatchWriter';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "verso-db",
+  "version": "0.1.1",
+  "description": "High-performance vector search with HNSW indexing for Bun and Browser. 100% recall, 4x memory reduction with Int8 quantization.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "bun": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target browser && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir ./dist",
+    "test": "bun test",
+    "test:browser": "vitest --config vitest.browser.config.ts run",
+    "test:browser:watch": "vitest --config vitest.browser.config.ts",
+    "test:browser:ui": "vitest --config vitest.browser.config.ts --ui",
+    "prepublishOnly": "bun run build",
+    "bench": "bun run benchmarks/vector_search.bench.ts && bun run benchmarks/hnsw.bench.ts && bun run benchmarks/storage.bench.ts",
+    "benchmark:recall": "bun run benchmarks/recall_validation.bench.ts",
+    "benchmark:memory": "bun run benchmarks/memory_usage_final.bench.ts",
+    "release": "semantic-release",
+    "publish:dry": "bunx npm publish --dry-run"
+  },
+  "keywords": [
+    "vector",
+    "search",
+    "hnsw",
+    "embedding",
+    "similarity",
+    "nearest-neighbor",
+    "knn",
+    "ann",
+    "bun",
+    "browser",
+    "opfs",
+    "rag",
+    "ai",
+    "machine-learning",
+    "typescript"
+  ],
+  "author": "Brian Sunter",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/briansunter/verso.git"
+  },
+  "bugs": {
+    "url": "https://github.com/briansunter/verso/issues"
+  },
+  "homepage": "https://github.com/briansunter/verso#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@huggingface/hub": "^2.7.0",
+    "@lancedb/lancedb": "^0.22.3",
+    "@qdrant/js-client-rest": "^1.16.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/bun": "latest",
+    "@vitest/browser": "^4.0.14",
+    "@vitest/browser-playwright": "^4.0.14",
+    "hnsw": "^1.0.3",
+    "hyparquet": "^1.21.1",
+    "hyparquet-compressors": "^1.1.1",
+    "mitata": "^1.0.34",
+    "playwright": "^1.57.0",
+    "semantic-release": "^25.0.2",
+    "simsimd": "^6.5.5",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.14",
+    "wabt": "^1.0.39"
+  }
+}

package/src/BinaryHeap.ts

@@ -0,0 +1,131 @@
+export class BinaryHeap {
+  private ids: Uint32Array;
+  private dists: Float32Array;
+  private _size: number;
+  private capacity: number;
+  private lastPoppedValue: number = 0;
+
+  constructor(capacity: number) {
+    this.capacity = capacity;
+    this.ids = new Uint32Array(capacity);
+    this.dists = new Float32Array(capacity);
+    this._size = 0;
+  }
+
+  /**
+   * Push an element onto the heap.
+   * When at capacity, simply returns without adding (caller manages bounds).
+   * This is the correct behavior for HNSW candidate exploration.
+   */
+  push(id: number, dist: number): void {
+    if (this._size >= this.capacity) {
+      // At capacity - don't add more elements.
+      // The caller is responsible for managing heap bounds.
+      return;
+    }
+
+    this.ids[this._size] = id;
+    this.dists[this._size] = dist;
+    this._size++;
+    this.heapifyUp(this._size - 1);
+  }
+
+  pop(): number {
+    if (this._size === 0) return -1;
+
+    const result = this.ids[0];
+    this.lastPoppedValue = this.dists[0];
+    this._size--;
+    if (this._size > 0) {
+      this.ids[0] = this.ids[this._size];
+      this.dists[0] = this.dists[this._size];
+      this.heapifyDown(0);
+    }
+    return result;
+  }
+
+  peek(): number {
+    return this._size > 0 ? this.ids[0] : -1;
+  }
+
+  peekValue(): number {
+    return this._size > 0 ? this.dists[0] : Infinity;
+  }
+
+  getLastPoppedValue(): number {
+    return this.lastPoppedValue;
+  }
+
+  size(): number {
+    return this._size;
+  }
+
+  clear(): void {
+    this._size = 0;
+  }
+
+  isEmpty(): boolean {
+    return this._size === 0;
+  }
+
+  getCapacity(): number {
+    return this.capacity;
+  }
+
+  private heapifyUp(index: number): void {
+    // Cache array references to avoid repeated property lookups
+    const ids = this.ids;
+    const dists = this.dists;
+
+    while (index > 0) {
+      // Use bitwise shift for faster integer division
+      const parentIndex = (index - 1) >> 1;
+      if (dists[parentIndex] <= dists[index]) break;
+
+      // Inline swap for performance
+      const tmpId = ids[index];
+      ids[index] = ids[parentIndex];
+      ids[parentIndex] = tmpId;
+
+      const tmpDist = dists[index];
+      dists[index] = dists[parentIndex];
+      dists[parentIndex] = tmpDist;
+
+      index = parentIndex;
+    }
+  }
+
+  private heapifyDown(index: number): void {
+    // Cache array references to avoid repeated property lookups
+    const ids = this.ids;
+    const dists = this.dists;
+    const size = this._size;
+
+    while (true) {
+      const leftChild = (index << 1) + 1; // 2 * index + 1
+      const rightChild = leftChild + 1;   // 2 * index + 2
+      let smallest = index;
+
+      if (leftChild < size && dists[leftChild] < dists[smallest]) {
+        smallest = leftChild;
+      }
+
+      if (rightChild < size && dists[rightChild] < dists[smallest]) {
+        smallest = rightChild;
+      }
+
+      if (smallest === index) break;
+
+      // Inline swap for performance
+      const tmpId = ids[index];
+      ids[index] = ids[smallest];
+      ids[smallest] = tmpId;
+
+      const tmpDist = dists[index];
+      dists[index] = dists[smallest];
+      dists[smallest] = tmpDist;
+
+      index = smallest;
+    }
+  }
+}