ruvector/npm/core/README.md

@ruvector/core

High-performance Rust vector database for Node.js with HNSW indexing and SIMD optimizations.

Features

• 🚀 Blazing Fast: Rust + SIMD optimizations for maximum performance
• 🎯 HNSW Indexing: State-of-the-art approximate nearest neighbor search
• 📦 Zero-Copy: Efficient buffer sharing between Rust and Node.js
• 🔍 Multiple Distance Metrics: Euclidean, Cosine, Dot Product, Manhattan
• 💾 Persistent Storage: Optional disk-based storage with memory mapping
• 🔧 Quantization: Scalar, Product, and Binary quantization support
• 📊 TypeScript: Full type definitions included
• 🌍 Cross-Platform: Linux, macOS, and Windows support

Installation

npm install @ruvector/core

The package will automatically install the correct native binding for your platform:

• Linux x64 (GNU)
• Linux ARM64 (GNU)
• macOS x64 (Intel)
• macOS ARM64 (Apple Silicon)
• Windows x64 (MSVC)

Quick Start

import { VectorDB, DistanceMetric } from '@ruvector/core';

// Create a database
const db = new VectorDB({
  dimensions: 384,
  distanceMetric: DistanceMetric.Cosine,
  storagePath: './vectors.db',
  hnswConfig: {
    m: 32,
    efConstruction: 200,
    efSearch: 100
  }
});

// Insert vectors
const id = await db.insert({
  vector: new Float32Array([1.0, 2.0, 3.0, ...])
});

// Search for similar vectors
const results = await db.search({
  vector: new Float32Array([1.0, 2.0, 3.0, ...]),
  k: 10
});

console.log(results);
// [{ id: 'vector-id', score: 0.95 }, ...]

API Reference

VectorDB

Constructor

new VectorDB(options: DbOptions)

Creates a new vector database with the specified options.

Options:

• dimensions (number, required): Vector dimensions
• distanceMetric (DistanceMetric, optional): Distance metric (default: Cosine)
• storagePath (string, optional): Path for persistent storage (default: './ruvector.db')
• hnswConfig (HnswConfig, optional): HNSW index configuration
• quantization (QuantizationConfig, optional): Quantization configuration

Static Methods

VectorDB.withDimensions(dimensions: number): VectorDB

Creates a vector database with default options.

Instance Methods

insert(entry: VectorEntry): Promise

Inserts a vector into the database.

const id = await db.insert({
  id: 'optional-id',
  vector: new Float32Array([1, 2, 3])
});

insertBatch(entries: VectorEntry[]): Promise<string[]>

Inserts multiple vectors in a batch.

const ids = await db.insertBatch([
  { vector: new Float32Array([1, 2, 3]) },
  { vector: new Float32Array([4, 5, 6]) }
]);

search(query: SearchQuery): Promise<SearchResult[]>

Searches for similar vectors.

const results = await db.search({
  vector: new Float32Array([1, 2, 3]),
  k: 10,
  efSearch: 100
});

delete(id: string): Promise

Deletes a vector by ID.

const deleted = await db.delete('vector-id');

get(id: string): Promise<VectorEntry | null>

Retrieves a vector by ID.

const entry = await db.get('vector-id');

len(): Promise

Returns the number of vectors in the database.

const count = await db.len();

isEmpty(): Promise

Checks if the database is empty.

const empty = await db.isEmpty();

Types

DistanceMetric

enum DistanceMetric {
  Euclidean = 'Euclidean',
  Cosine = 'Cosine',
  DotProduct = 'DotProduct',
  Manhattan = 'Manhattan'
}

DbOptions

interface DbOptions {
  dimensions: number;
  distanceMetric?: DistanceMetric;
  storagePath?: string;
  hnswConfig?: HnswConfig;
  quantization?: QuantizationConfig;
}

HnswConfig

interface HnswConfig {
  m?: number;
  efConstruction?: number;
  efSearch?: number;
  maxElements?: number;
}

QuantizationConfig

interface QuantizationConfig {
  type: 'none' | 'scalar' | 'product' | 'binary';
  subspaces?: number;
  k?: number;
}

Performance

rUvector delivers exceptional performance:

• 150x faster than pure JavaScript implementations
• 1M+ vectors/second insertion rate
• Sub-millisecond search latency
• 4-32x memory reduction with quantization

Platform Support

Platform	Architecture	Package
Linux	x64	@ruvector/core-linux-x64-gnu
Linux	ARM64	@ruvector/core-linux-arm64-gnu
macOS	x64 (Intel)	@ruvector/core-darwin-x64
macOS	ARM64 (Apple Silicon)	@ruvector/core-darwin-arm64
Windows	x64	@ruvector/core-win32-x64-msvc

License

MIT

Links

• GitHub Repository
• Documentation
• Issue Tracker