Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/npm/wasm/README.md

@@ -0,0 +1,263 @@
+# @ruvector/wasm
+
+WebAssembly bindings for Ruvector - High-performance vector database for browsers and Node.js.
+
+## Features
+
+- 🚀 **High Performance**: SIMD-accelerated vector operations
+- 🌐 **Universal**: Works in browsers and Node.js
+- 🎯 **Multiple Distance Metrics**: Cosine, Euclidean, Dot Product, Manhattan
+- 🔍 **Fast Search**: HNSW indexing for approximate nearest neighbor search
+- 💾 **Persistent Storage**: IndexedDB (browser) and file system (Node.js)
+- 🦀 **Rust-powered**: Built with Rust and WebAssembly
+
+## Installation
+
+```bash
+npm install @ruvector/wasm
+```
+
+## Quick Start
+
+### Browser
+
+```javascript
+import { VectorDB } from '@ruvector/wasm/browser';
+
+// Create database
+const db = new VectorDB({ dimensions: 128 });
+await db.init();
+
+// Insert vectors
+const vector = new Float32Array(128).fill(0.5);
+const id = db.insert(vector, 'my-vector', { label: 'example' });
+
+// Search
+const results = db.search(vector, 10);
+console.log(results);
+
+// Save to IndexedDB
+await db.saveToIndexedDB();
+```
+
+### Node.js
+
+```javascript
+import { VectorDB } from '@ruvector/wasm/node';
+
+// Create database
+const db = new VectorDB({ dimensions: 128 });
+await db.init();
+
+// Insert vectors
+const vector = new Float32Array(128).fill(0.5);
+const id = db.insert(vector, 'my-vector', { label: 'example' });
+
+// Search
+const results = db.search(vector, 10);
+console.log(results);
+```
+
+### Universal (Auto-detect)
+
+```javascript
+import { VectorDB } from '@ruvector/wasm';
+
+// Works in both browser and Node.js
+const db = new VectorDB({ dimensions: 128 });
+await db.init();
+
+const vector = new Float32Array(128).fill(0.5);
+const id = db.insert(vector);
+const results = db.search(vector, 10);
+```
+
+## API Reference
+
+### VectorDB
+
+#### Constructor
+
+```typescript
+new VectorDB(options: DbOptions)
+```
+
+Options:
+- `dimensions: number` - Vector dimensions (required)
+- `metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan'` - Distance metric (default: 'cosine')
+- `useHnsw?: boolean` - Use HNSW index (default: true)
+
+#### Methods
+
+##### init()
+
+Initialize the database (must be called before use).
+
+```typescript
+await db.init(): Promise<void>
+```
+
+##### insert()
+
+Insert a single vector.
+
+```typescript
+db.insert(
+  vector: Float32Array | number[],
+  id?: string,
+  metadata?: Record<string, any>
+): string
+```
+
+##### insertBatch()
+
+Insert multiple vectors efficiently.
+
+```typescript
+db.insertBatch(entries: VectorEntry[]): string[]
+```
+
+##### search()
+
+Search for similar vectors.
+
+```typescript
+db.search(
+  query: Float32Array | number[],
+  k: number,
+  filter?: Record<string, any>
+): SearchResult[]
+```
+
+##### delete()
+
+Delete a vector by ID.
+
+```typescript
+db.delete(id: string): boolean
+```
+
+##### get()
+
+Get a vector by ID.
+
+```typescript
+db.get(id: string): VectorEntry | null
+```
+
+##### len()
+
+Get the number of vectors.
+
+```typescript
+db.len(): number
+```
+
+##### isEmpty()
+
+Check if database is empty.
+
+```typescript
+db.isEmpty(): boolean
+```
+
+##### getDimensions()
+
+Get vector dimensions.
+
+```typescript
+db.getDimensions(): number
+```
+
+##### save()
+
+Save database to persistent storage.
+
+```typescript
+await db.save(path?: string): Promise<void>
+```
+
+### Utility Functions
+
+#### detectSIMD()
+
+Check if SIMD is supported.
+
+```typescript
+const hasSIMD = await detectSIMD();
+```
+
+#### version()
+
+Get library version.
+
+```typescript
+const ver = await version();
+```
+
+#### benchmark()
+
+Run performance benchmark.
+
+```typescript
+const opsPerSec = await benchmark('insert', 1000, 128);
+```
+
+## Types
+
+### VectorEntry
+
+```typescript
+interface VectorEntry {
+  id?: string;
+  vector: Float32Array | number[];
+  metadata?: Record<string, any>;
+}
+```
+
+### SearchResult
+
+```typescript
+interface SearchResult {
+  id: string;
+  score: number;
+  vector?: Float32Array;
+  metadata?: Record<string, any>;
+}
+```
+
+### DbOptions
+
+```typescript
+interface DbOptions {
+  dimensions: number;
+  metric?: 'euclidean' | 'cosine' | 'dotproduct' | 'manhattan';
+  useHnsw?: boolean;
+}
+```
+
+## Performance
+
+Ruvector WASM delivers exceptional performance:
+
+- **SIMD Acceleration**: Up to 4x faster with WebAssembly SIMD
+- **HNSW Index**: Sub-linear search complexity
+- **Zero-copy**: Efficient memory usage with transferable objects
+- **Batch Operations**: Optimized bulk inserts
+
+## Browser Compatibility
+
+- Chrome 91+ (SIMD support)
+- Firefox 89+ (SIMD support)
+- Safari 16.4+ (SIMD support)
+- Edge 91+ (SIMD support)
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub Repository](https://github.com/ruvnet/ruvector)
+- [Documentation](https://github.com/ruvnet/ruvector#readme)
+- [Issues](https://github.com/ruvnet/ruvector/issues)