@wiscale/velesdb-wasm 0.5.2 → 0.6.0

package/README.md

@@ -9,7 +9,8 @@ WebAssembly build of [VelesDB](https://github.com/cyberlife-coder/VelesDB) - vec
 
 - **In-browser vector search** - No server required
 - **SIMD optimized** - Uses WASM SIMD128 for fast distance calculations
-- **Multiple metrics** - Cosine, Euclidean, Dot Product
+- **Multiple metrics** - Cosine, Euclidean, Dot Product, Hamming, Jaccard
+- **Memory optimization** - SQ8 (4x) and Binary (32x) quantization
 - **Lightweight** - Minimal bundle size
 
 ## Installation
@@ -72,7 +73,10 @@ store.reserve(50000);
 ```typescript
 class VectorStore {
   // Create a new store
-  constructor(dimension: number, metric: 'cosine' | 'euclidean' | 'dot');
+  constructor(dimension: number, metric: 'cosine' | 'euclidean' | 'dot' | 'hamming' | 'jaccard');
+  
+  // Create with storage mode (sq8/binary for memory optimization)
+  static new_with_mode(dimension: number, metric: string, mode: 'full' | 'sq8' | 'binary'): VectorStore;
   
   // Create with pre-allocated capacity (performance optimization)
   static with_capacity(dimension: number, metric: string, capacity: number): VectorStore;
@@ -81,6 +85,7 @@ class VectorStore {
   readonly len: number;
   readonly is_empty: boolean;
   readonly dimension: number;
+  readonly storage_mode: string;  // "full", "sq8", or "binary"
 
   // Methods
   insert(id: bigint, vector: Float32Array): void;
@@ -89,7 +94,7 @@ class VectorStore {
   remove(id: bigint): boolean;
   clear(): void;
   reserve(additional: number): void;  // Pre-allocate memory
-  memory_usage(): number;
+  memory_usage(): number;  // Accurate for each storage mode
 }
 ```
 
@@ -100,6 +105,31 @@ class VectorStore {
 | `cosine` | Cosine similarity | Text embeddings (BERT, GPT) |
 | `euclidean` | L2 distance | Image features, spatial data |
 | `dot` | Dot product | Pre-normalized vectors |
+| `hamming` | Hamming distance | Binary vectors, fingerprints |
+| `jaccard` | Jaccard similarity | Set similarity, sparse vectors |
+
+## Storage Modes (Memory Optimization)
+
+Reduce memory usage with quantization:
+
+```javascript
+// Full precision (default) - best recall
+const full = new VectorStore(768, 'cosine');
+
+// SQ8: 4x memory reduction (~1% recall loss)
+const sq8 = VectorStore.new_with_mode(768, 'cosine', 'sq8');
+
+// Binary: 32x memory reduction (~5-10% recall loss)
+const binary = VectorStore.new_with_mode(768, 'hamming', 'binary');
+
+console.log(sq8.storage_mode);  // "sq8"
+```
+
+| Mode | Memory (768D) | Compression | Use Case |
+|------|---------------|-------------|----------|
+| `full` | 3080 bytes | 1x | Default, max precision |
+| `sq8` | 784 bytes | **4x** | Scale, RAM-constrained |
+| `binary` | 104 bytes | **32x** | Edge, IoT, mobile PWA |
 
 ## IndexedDB Persistence
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@wiscale/velesdb-wasm",
   "type": "module",
   "description": "VelesDB for WebAssembly - Vector search in the browser",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "license": "Elastic-2.0",
   "repository": {
     "type": "git",

package/velesdb_wasm.d.ts

@@ -1,6 +1,24 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Storage mode for vector quantization.
+ */
+export enum StorageMode {
+  /**
+   * Full f32 precision (4 bytes per dimension)
+   */
+  Full = 0,
+  /**
+   * SQ8: 8-bit scalar quantization (1 byte per dimension, 4x compression)
+   */
+  SQ8 = 1,
+  /**
+   * Binary: 1-bit quantization (1 bit per dimension, 32x compression)
+   */
+  Binary = 2,
+}
+
 export class VectorStore {
   free(): void;
   [Symbol.dispose](): void;
@@ -23,6 +41,22 @@ export class VectorStore {
    * Returns memory usage estimate in bytes.
    */
   memory_usage(): number;
+  /**
+   * Creates a new vector store with specified storage mode for memory optimization.
+   *
+   * # Arguments
+   *
+   * * `dimension` - Vector dimension
+   * * `metric` - Distance metric
+   * * `mode` - Storage mode: "full", "sq8", or "binary"
+   *
+   * # Storage Modes
+   *
+   * - `full`: Best recall, 4 bytes/dimension
+   * - `sq8`: 4x compression, ~1% recall loss
+   * - `binary`: 32x compression, ~5-10% recall loss
+   */
+  static new_with_mode(dimension: number, metric: string, mode: string): VectorStore;
   /**
    * Creates a new vector store with pre-allocated capacity.
    *
@@ -193,6 +227,10 @@ export class VectorStore {
    * * `additional` - Number of additional vectors to reserve space for
    */
   reserve(additional: number): void;
+  /**
+   * Returns the storage mode.
+   */
+  readonly storage_mode: string;
   /**
    * Returns the number of vectors in the store.
    */
@@ -224,16 +262,18 @@ export interface InitOutput {
   readonly vectorstore_load: (a: number, b: number) => number;
   readonly vectorstore_memory_usage: (a: number) => number;
   readonly vectorstore_new: (a: number, b: number, c: number, d: number) => void;
+  readonly vectorstore_new_with_mode: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
   readonly vectorstore_remove: (a: number, b: bigint) => number;
   readonly vectorstore_reserve: (a: number, b: number) => void;
   readonly vectorstore_save: (a: number, b: number, c: number) => number;
   readonly vectorstore_search: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly vectorstore_storage_mode: (a: number, b: number) => void;
   readonly vectorstore_with_capacity: (a: number, b: number, c: number, d: number, e: number) => void;
-  readonly __wasm_bindgen_func_elem_382: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_381: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_93: (a: number, b: number, c: number) => void;
-  readonly __wasm_bindgen_func_elem_92: (a: number, b: number) => void;
-  readonly __wasm_bindgen_func_elem_429: (a: number, b: number, c: number, d: number) => void;
+  readonly __wasm_bindgen_func_elem_97: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_96: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_390: (a: number, b: number, c: number) => void;
+  readonly __wasm_bindgen_func_elem_389: (a: number, b: number) => void;
+  readonly __wasm_bindgen_func_elem_437: (a: number, b: number, c: number, d: number) => void;
   readonly __wbindgen_export: (a: number, b: number) => number;
   readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_export3: (a: number) => void;

package/velesdb_wasm.js

@@ -251,16 +251,16 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-function __wasm_bindgen_func_elem_382(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_382(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_97(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_97(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_93(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_93(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_390(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_390(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_429(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_429(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_437(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_437(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const __wbindgen_enum_IdbTransactionMode = ["readonly", "readwrite", "versionchange", "readwriteflush", "cleanup"];
@@ -269,6 +269,25 @@ const VectorStoreFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_vectorstore_free(ptr >>> 0, 1));
 
+/**
+ * Storage mode for vector quantization.
+ * @enum {0 | 1 | 2}
+ */
+export const StorageMode = Object.freeze({
+    /**
+     * Full f32 precision (4 bytes per dimension)
+     */
+    Full: 0, "0": "Full",
+    /**
+     * SQ8: 8-bit scalar quantization (1 byte per dimension, 4x compression)
+     */
+    SQ8: 1, "1": "SQ8",
+    /**
+     * Binary: 1-bit quantization (1 bit per dimension, 32x compression)
+     */
+    Binary: 2, "2": "Binary",
+});
+
 /**
  * A vector store for in-memory vector search.
  *
@@ -277,6 +296,12 @@ const VectorStoreFinalization = (typeof FinalizationRegistry === 'undefined')
  * Uses contiguous memory layout for optimal cache locality and fast
  * serialization. Vector data is stored in a single buffer rather than
  * individual Vec allocations.
+ *
+ * # Storage Modes
+ *
+ * - `Full`: f32 precision, best recall
+ * - `SQ8`: 4x memory reduction, ~1% recall loss
+ * - `Binary`: 32x memory reduction, ~5-10% recall loss
  */
 export class VectorStore {
     static __wrap(ptr) {
@@ -332,6 +357,64 @@ export class VectorStore {
         const ret = wasm.vectorstore_memory_usage(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Returns the storage mode.
+     * @returns {string}
+     */
+    get storage_mode() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.vectorstore_storage_mode(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Creates a new vector store with specified storage mode for memory optimization.
+     *
+     * # Arguments
+     *
+     * * `dimension` - Vector dimension
+     * * `metric` - Distance metric
+     * * `mode` - Storage mode: "full", "sq8", or "binary"
+     *
+     * # Storage Modes
+     *
+     * - `full`: Best recall, 4 bytes/dimension
+     * - `sq8`: 4x compression, ~1% recall loss
+     * - `binary`: 32x compression, ~5-10% recall loss
+     * @param {number} dimension
+     * @param {string} metric
+     * @param {string} mode
+     * @returns {VectorStore}
+     */
+    static new_with_mode(dimension, metric, mode) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(metric, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(mode, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.vectorstore_new_with_mode(retptr, dimension, ptr0, len0, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return VectorStore.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Creates a new vector store with pre-allocated capacity.
      *
@@ -900,7 +983,7 @@ function __wbg_get_imports() {
                 const a = state0.a;
                 state0.a = 0;
                 try {
-                    return __wasm_bindgen_func_elem_429(a, state0.b, arg0, arg1);
+                    return __wasm_bindgen_func_elem_437(a, state0.b, arg0, arg1);
                 } finally {
                     state0.a = a;
                 }
@@ -1021,12 +1104,12 @@ function __wbg_get_imports() {
     };
     imports.wbg.__wbindgen_cast_5672704bc77a612c = function(arg0, arg1) {
         // Cast intrinsic for `Closure(Closure { dtor_idx: 44, function: Function { arguments: [Externref], shim_idx: 45, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_381, __wasm_bindgen_func_elem_382);
+        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_389, __wasm_bindgen_func_elem_390);
         return addHeapObject(ret);
     };
     imports.wbg.__wbindgen_cast_9cdd8d1a79740578 = function(arg0, arg1) {
         // Cast intrinsic for `Closure(Closure { dtor_idx: 6, function: Function { arguments: [NamedExternref("Event")], shim_idx: 7, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_92, __wasm_bindgen_func_elem_93);
+        const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_96, __wasm_bindgen_func_elem_97);
         return addHeapObject(ret);
     };
     imports.wbg.__wbindgen_cast_d6cd19b81560fd6e = function(arg0) {