wifi-densepose/vendor/ruvector/npm/packages/graph-node/README.md

@ruvector/graph-node

Native Node.js bindings for RuVector Graph Database with hypergraph support, Cypher queries, and persistence. 10x faster than WASM.

Features

• Native Performance: Direct NAPI-RS bindings - no WASM overhead
• Hypergraph Support: Multi-node relationships with vector embeddings
• Cypher Queries: Neo4j-compatible query language
• Persistence: ACID-compliant storage with redb backend
• Vector Similarity Search: Fast k-NN search on embeddings
• Graph Traversal: k-hop neighbor discovery
• Transactions: Full ACID support with begin/commit/rollback
• Batch Operations: High-throughput bulk inserts (131K+ ops/sec)
• Zero-Copy: Efficient Float32Array handling
• TypeScript: Full type definitions included

Installation

npm install @ruvector/graph-node

Quick Start

const { GraphDatabase } = require('@ruvector/graph-node');

// Create an in-memory database
const db = new GraphDatabase({
  distanceMetric: 'Cosine',
  dimensions: 384
});

// Or create a persistent database
const persistentDb = new GraphDatabase({
  distanceMetric: 'Cosine',
  dimensions: 384,
  storagePath: './my-graph.db'
});

// Or open an existing database
const existingDb = GraphDatabase.open('./my-graph.db');

// Create nodes
await db.createNode({
  id: 'alice',
  embedding: new Float32Array([1.0, 0.0, 0.0, /* ... */]),
  labels: ['Person', 'Employee'],
  properties: { name: 'Alice', age: '30' }
});

// Create edges
await db.createEdge({
  from: 'alice',
  to: 'bob',
  description: 'KNOWS',
  embedding: new Float32Array([0.5, 0.5, 0.0, /* ... */]),
  confidence: 0.95
});

// Create hyperedges (multi-node relationships)
await db.createHyperedge({
  nodes: ['alice', 'bob', 'charlie'],
  description: 'COLLABORATED_ON_PROJECT',
  embedding: new Float32Array([0.33, 0.33, 0.33, /* ... */]),
  confidence: 0.85
});

// Query with Cypher
const results = await db.query('MATCH (n:Person) RETURN n');

// Vector similarity search
const similar = await db.searchHyperedges({
  embedding: new Float32Array([0.3, 0.3, 0.3, /* ... */]),
  k: 10
});

// Get statistics
const stats = await db.stats();
console.log(\`Nodes: \${stats.totalNodes}, Edges: \${stats.totalEdges}\`);

Benchmarks

Operation	Throughput	Latency
Node Creation	9.17K ops/sec	109ms
Batch Node Creation	131.10K ops/sec	7.63ms
Edge Creation	9.30K ops/sec	107ms
Vector Search (k=10)	2.35K ops/sec	42ms
k-hop Traversal	10.28K ops/sec	9.73ms

Platform Support

Platform	Architecture	Status
Linux	x64 (glibc)	Supported
Linux	arm64 (glibc)	Supported
macOS	x64	Supported
macOS	arm64 (M1/M2)	Supported
Windows	x64	Supported

License

MIT