@wiscale/velesdb-wasm 0.5.1

package/README.md

@@ -0,0 +1,207 @@
+# VelesDB WASM
+
+[![npm](https://img.shields.io/npm/v/velesdb-wasm)](https://www.npmjs.com/package/velesdb-wasm)
+[![License](https://img.shields.io/badge/license-ELv2-blue)](https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE)
+
+WebAssembly build of [VelesDB](https://github.com/cyberlife-coder/VelesDB) - vector search in the browser.
+
+## Features
+
+- **In-browser vector search** - No server required
+- **SIMD optimized** - Uses WASM SIMD128 for fast distance calculations
+- **Multiple metrics** - Cosine, Euclidean, Dot Product
+- **Lightweight** - Minimal bundle size
+
+## Installation
+
+```bash
+npm install velesdb-wasm
+```
+
+## Usage
+
+```javascript
+import init, { VectorStore } from 'velesdb-wasm';
+
+async function main() {
+  // Initialize WASM module
+  await init();
+
+  // Create a vector store (768 dimensions, cosine similarity)
+  const store = new VectorStore(768, 'cosine');
+
+  // Insert vectors (use BigInt for IDs)
+  store.insert(1n, new Float32Array([0.1, 0.2, ...]));
+  store.insert(2n, new Float32Array([0.3, 0.4, ...]));
+
+  // Search for similar vectors
+  const query = new Float32Array([0.15, 0.25, ...]);
+  const results = store.search(query, 5); // Top 5 results
+
+  // Results: [[id, score], [id, score], ...]
+  console.log(results);
+}
+
+main();
+```
+
+### High-Performance Bulk Insert
+
+For optimal performance when inserting many vectors:
+
+```javascript
+// Pre-allocate capacity (avoids repeated memory allocations)
+const store = VectorStore.with_capacity(768, 'cosine', 100000);
+
+// Batch insert (much faster than individual inserts)
+const batch = [
+  [1n, [0.1, 0.2, ...]],
+  [2n, [0.3, 0.4, ...]],
+  // ... more vectors
+];
+store.insert_batch(batch);
+
+// Or reserve capacity on existing store
+store.reserve(50000);
+```
+
+## API
+
+### VectorStore
+
+```typescript
+class VectorStore {
+  // Create a new store
+  constructor(dimension: number, metric: 'cosine' | 'euclidean' | 'dot');
+  
+  // Create with pre-allocated capacity (performance optimization)
+  static with_capacity(dimension: number, metric: string, capacity: number): VectorStore;
+
+  // Properties
+  readonly len: number;
+  readonly is_empty: boolean;
+  readonly dimension: number;
+
+  // Methods
+  insert(id: bigint, vector: Float32Array): void;
+  insert_batch(batch: Array<[bigint, number[]]>): void;  // Bulk insert
+  search(query: Float32Array, k: number): Array<[bigint, number]>;
+  remove(id: bigint): boolean;
+  clear(): void;
+  reserve(additional: number): void;  // Pre-allocate memory
+  memory_usage(): number;
+}
+```
+
+## Distance Metrics
+
+| Metric | Description | Best For |
+|--------|-------------|----------|
+| `cosine` | Cosine similarity | Text embeddings (BERT, GPT) |
+| `euclidean` | L2 distance | Image features, spatial data |
+| `dot` | Dot product | Pre-normalized vectors |
+
+## IndexedDB Persistence
+
+Save and restore your vector store for offline-first applications with built-in async methods:
+
+```javascript
+import init, { VectorStore } from 'velesdb-wasm';
+
+async function main() {
+  await init();
+
+  // Create and populate a store
+  const store = new VectorStore(768, 'cosine');
+  store.insert(1n, new Float32Array(768).fill(0.1));
+  store.insert(2n, new Float32Array(768).fill(0.2));
+
+  // Save to IndexedDB (single async call)
+  await store.save('my-vectors-db');
+  console.log('Saved!', store.len, 'vectors');
+
+  // Later: Load from IndexedDB
+  const restored = await VectorStore.load('my-vectors-db');
+  console.log('Restored!', restored.len, 'vectors');
+
+  // Clean up: Delete database
+  await VectorStore.delete_database('my-vectors-db');
+}
+
+main();
+```
+
+### Persistence API
+
+```typescript
+class VectorStore {
+  // Save to IndexedDB (async)
+  save(db_name: string): Promise<void>;
+  
+  // Load from IndexedDB (async, static)
+  static load(db_name: string): Promise<VectorStore>;
+  
+  // Delete IndexedDB database (async, static)
+  static delete_database(db_name: string): Promise<void>;
+  
+  // Manual binary export/import (for localStorage, file download, etc.)
+  export_to_bytes(): Uint8Array;
+  static import_from_bytes(bytes: Uint8Array): VectorStore;
+}
+```
+
+### Binary Format
+
+| Field | Size | Description |
+|-------|------|-------------|
+| Magic | 4 bytes | `"VELS"` |
+| Version | 1 byte | Format version (1) |
+| Dimension | 4 bytes | Vector dimension (u32 LE) |
+| Metric | 1 byte | 0=cosine, 1=euclidean, 2=dot |
+| Count | 8 bytes | Number of vectors (u64 LE) |
+| Vectors | variable | id (8B) + data (dim × 4B) each |
+
+### Performance
+
+Ultra-fast serialization thanks to contiguous memory layout:
+
+| Operation | 10k vectors (768D) | Throughput |
+|-----------|-------------------|------------|
+| Export | ~7 ms | **4479 MB/s** |
+| Import | ~10 ms | **2943 MB/s** |
+
+## Use Cases
+
+- **Browser-based RAG** - 100% client-side semantic search
+- **Offline-first apps** - Works without internet, persists to IndexedDB
+- **Privacy-preserving AI** - Data never leaves the browser
+- **Electron/Tauri apps** - Desktop AI without a server
+- **PWA applications** - Full offline support with service workers
+
+## Building from Source
+
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+
+# Build for browser
+wasm-pack build --target web
+
+# Build for Node.js
+wasm-pack build --target nodejs
+```
+
+## Performance
+
+Typical latencies on modern browsers:
+
+| Operation | 768D vectors | 10K vectors |
+|-----------|--------------|-------------|
+| Insert | ~1 µs | ~10 ms |
+| Search | ~50 µs | ~5 ms |
+
+## License
+
+Elastic License 2.0 (ELv2)
+
+See [LICENSE](https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE) for details.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@wiscale/velesdb-wasm",
+  "type": "module",
+  "description": "VelesDB for WebAssembly - Vector search in the browser",
+  "version": "0.5.1",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cyberlife-coder/VelesDB"
+  },
+  "files": [
+    "velesdb_wasm_bg.wasm",
+    "velesdb_wasm.js",
+    "velesdb_wasm.d.ts"
+  ],
+  "main": "velesdb_wasm.js",
+  "types": "velesdb_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/velesdb_wasm.d.ts

@@ -0,0 +1,264 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class VectorStore {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Inserts multiple vectors in a single batch operation.
+   *
+   * This is significantly faster than calling `insert()` multiple times
+   * because it pre-allocates memory and reduces per-call overhead.
+   *
+   * # Arguments
+   *
+   * * `batch` - JavaScript array of `[id, Float32Array]` pairs
+   *
+   * # Errors
+   *
+   * Returns an error if any vector dimension doesn't match store dimension.
+   */
+  insert_batch(batch: any): void;
+  /**
+   * Returns memory usage estimate in bytes.
+   */
+  memory_usage(): number;
+  /**
+   * Creates a new vector store with pre-allocated capacity.
+   *
+   * This is more efficient when you know the approximate number of vectors
+   * you'll be inserting, as it avoids repeated memory allocations.
+   *
+   * # Arguments
+   *
+   * * `dimension` - Vector dimension
+   * * `metric` - Distance metric: "cosine", "euclidean", or "dot"
+   * * `capacity` - Number of vectors to pre-allocate space for
+   *
+   * # Errors
+   *
+   * Returns an error if the metric is not recognized.
+   */
+  static with_capacity(dimension: number, metric: string, capacity: number): VectorStore;
+  /**
+   * Deletes the `IndexedDB` database.
+   *
+   * Use this to clear all persisted data.
+   *
+   * # Arguments
+   *
+   * * `db_name` - Name of the `IndexedDB` database to delete
+   *
+   * # Errors
+   *
+   * Returns an error if the deletion fails.
+   */
+  static delete_database(db_name: string): Promise<void>;
+  /**
+   * Exports the vector store to a binary format.
+   *
+   * The binary format contains:
+   * - Header: dimension (u32), metric (u8), count (u64)
+   * - For each vector: id (u64), data (f32 array)
+   *
+   * Use this to persist data to `IndexedDB` or `localStorage`.
+   *
+   * # Errors
+   *
+   * This function currently does not return errors but uses `Result`
+   * for future extensibility.
+   *
+   * # Performance
+   *
+   * Perf: Pre-allocates exact buffer size to avoid reallocations.
+   * Throughput: ~1600 MB/s on 10k vectors (768D)
+   */
+  export_to_bytes(): Uint8Array;
+  /**
+   * Imports a vector store from binary format.
+   *
+   * Use this to restore data from `IndexedDB` or `localStorage`.
+   *
+   * # Errors
+   *
+   * Returns an error if:
+   * - The data is too short or corrupted
+   * - The magic number is invalid
+   * - The version is unsupported
+   * - The metric byte is invalid
+   */
+  static import_from_bytes(bytes: Uint8Array): VectorStore;
+  /**
+   * Creates a new vector store with the specified dimension and distance metric.
+   *
+   * # Arguments
+   *
+   * * `dimension` - Vector dimension (e.g., 768 for BERT, 1536 for GPT)
+   * * `metric` - Distance metric: "cosine", "euclidean", or "dot"
+   *
+   * # Errors
+   *
+   * Returns an error if the metric is not recognized.
+   */
+  constructor(dimension: number, metric: string);
+  /**
+   * Loads a vector store from `IndexedDB`.
+   *
+   * This method restores all vectors from the browser's `IndexedDB`.
+   *
+   * # Arguments
+   *
+   * * `db_name` - Name of the `IndexedDB` database
+   *
+   * # Errors
+   *
+   * Returns an error if the database doesn't exist or is corrupted.
+   *
+   * # Example
+   *
+   * ```javascript
+   * const store = await VectorStore.load("my-vectors");
+   * console.log(store.len); // Number of restored vectors
+   * ```
+   */
+  static load(db_name: string): Promise<VectorStore>;
+  /**
+   * Saves the vector store to `IndexedDB`.
+   *
+   * This method persists all vectors to the browser's `IndexedDB`,
+   * enabling offline-first applications.
+   *
+   * # Arguments
+   *
+   * * `db_name` - Name of the `IndexedDB` database
+   *
+   * # Errors
+   *
+   * Returns an error if `IndexedDB` is not available or the save fails.
+   *
+   * # Example
+   *
+   * ```javascript
+   * const store = new VectorStore(768, "cosine");
+   * store.insert(1n, vector1);
+   * await store.save("my-vectors");
+   * ```
+   */
+  save(db_name: string): Promise<void>;
+  /**
+   * Clears all vectors from the store.
+   */
+  clear(): void;
+  /**
+   * Inserts a vector with the given ID.
+   *
+   * # Arguments
+   *
+   * * `id` - Unique identifier for the vector
+   * * `vector` - `Float32Array` of the vector data
+   *
+   * # Errors
+   *
+   * Returns an error if vector dimension doesn't match store dimension.
+   */
+  insert(id: bigint, vector: Float32Array): void;
+  /**
+   * Removes a vector by ID.
+   */
+  remove(id: bigint): boolean;
+  /**
+   * Searches for the k nearest neighbors to the query vector.
+   *
+   * # Arguments
+   *
+   * * `query` - Query vector as `Float32Array`
+   * * `k` - Number of results to return
+   *
+   * # Returns
+   *
+   * Array of [id, score] pairs sorted by relevance.
+   *
+   * # Errors
+   *
+   * Returns an error if query dimension doesn't match store dimension.
+   */
+  search(query: Float32Array, k: number): any;
+  /**
+   * Pre-allocates memory for the specified number of additional vectors.
+   *
+   * Call this before bulk insertions to avoid repeated allocations.
+   *
+   * # Arguments
+   *
+   * * `additional` - Number of additional vectors to reserve space for
+   */
+  reserve(additional: number): void;
+  /**
+   * Returns the number of vectors in the store.
+   */
+  readonly len: number;
+  /**
+   * Returns true if the store is empty.
+   */
+  readonly is_empty: boolean;
+  /**
+   * Returns the vector dimension.
+   */
+  readonly dimension: number;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_vectorstore_free: (a: number, b: number) => void;
+  readonly vectorstore_clear: (a: number) => void;
+  readonly vectorstore_delete_database: (a: number, b: number) => number;
+  readonly vectorstore_dimension: (a: number) => number;
+  readonly vectorstore_export_to_bytes: (a: number, b: number) => void;
+  readonly vectorstore_import_from_bytes: (a: number, b: number, c: number) => void;
+  readonly vectorstore_insert: (a: number, b: number, c: bigint, d: number, e: number) => void;
+  readonly vectorstore_insert_batch: (a: number, b: number, c: number) => void;
+  readonly vectorstore_is_empty: (a: number) => number;
+  readonly vectorstore_len: (a: number) => number;
+  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_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_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 __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;
+  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+  readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;