Skip to content

Latest commit

 

History

History

ruvector-graph-wasm

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 
build.sh
build.sh
 
 
package.json
package.json
 
 

README.md

RuVector Graph WASM

WebAssembly bindings for RuVector graph database with Neo4j-inspired API and Cypher support.

Features

  • Neo4j-style API: Familiar node, edge, and relationship operations
  • Hypergraph Support: N-ary relationships beyond binary edges
  • Cypher Queries: Basic Cypher query language support
  • Browser & Node.js: Works in both environments
  • Web Workers: Background query execution
  • Async Operations: Streaming results for large datasets
  • Vector Embeddings: First-class support for semantic relationships

Installation

npm install @ruvector/graph-wasm

Quick Start

Browser (ES Modules)

import init, { GraphDB } from '@ruvector/graph-wasm';

await init();

// Create database
const db = new GraphDB('cosine');

// Create nodes
const aliceId = db.createNode(
  ['Person'],
  { name: 'Alice', age: 30 }
);

const bobId = db.createNode(
  ['Person'],
  { name: 'Bob', age: 35 }
);

// Create relationship
const friendshipId = db.createEdge(
  aliceId,
  bobId,
  'KNOWS',
  { since: 2020 }
);

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

// Get statistics
const stats = db.stats();
console.log(`Nodes: ${stats.nodeCount}, Edges: ${stats.edgeCount}`);

Node.js

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

const db = new GraphDB('cosine');
// ... same API as browser

API Reference

GraphDB

Main class for graph database operations.

Constructor

new GraphDB(metric?: string)
  • metric: Distance metric for hypergraph embeddings
    • "cosine" (default)
    • "euclidean"
    • "dotproduct"
    • "manhattan"

Methods

Node Operations
createNode(labels: string[], properties: object): string

Create a node with labels and properties. Returns node ID.

getNode(id: string): JsNode | null

Retrieve a node by ID.

deleteNode(id: string): boolean

Delete a node and its associated edges.

Edge Operations
createEdge(
  from: string,
  to: string,
  type: string,
  properties: object
): string

Create a directed edge between two nodes.

getEdge(id: string): JsEdge | null

Retrieve an edge by ID.

deleteEdge(id: string): boolean

Delete an edge.

Hyperedge Operations
createHyperedge(
  nodes: string[],
  description: string,
  embedding?: number[],
  confidence?: number
): string

Create an n-ary relationship connecting multiple nodes.

getHyperedge(id: string): JsHyperedge | null

Retrieve a hyperedge by ID.

Query Operations
async query(cypher: string): Promise<QueryResult>

Execute a Cypher query. Supports basic MATCH and CREATE statements.

async importCypher(statements: string[]): Promise<number>

Import multiple Cypher CREATE statements.

exportCypher(): string

Export the entire database as Cypher CREATE statements.

Statistics
stats(): object

Get database statistics:

  • nodeCount: Total number of nodes
  • edgeCount: Total number of edges
  • hyperedgeCount: Total number of hyperedges
  • hypergraphEntities: Entities in hypergraph index
  • hypergraphEdges: Hyperedges in index
  • avgEntityDegree: Average entity degree

Types

JsNode

interface JsNode {
  id: string;
  labels: string[];
  properties: object;
  embedding?: number[];

  getProperty(key: string): any;
  hasLabel(label: string): boolean;
}

JsEdge

interface JsEdge {
  id: string;
  from: string;
  to: string;
  type: string;
  properties: object;

  getProperty(key: string): any;
}

JsHyperedge

interface JsHyperedge {
  id: string;
  nodes: string[];
  description: string;
  embedding: number[];
  confidence: number;
  properties: object;
  order: number; // Number of connected nodes
}

QueryResult

interface QueryResult {
  nodes: JsNode[];
  edges: JsEdge[];
  hyperedges: JsHyperedge[];
  data: object[];
  count: number;
  isEmpty(): boolean;
}

Advanced Features

Async Query Execution

For large result sets, use async query execution with streaming:

import { AsyncQueryExecutor } from '@ruvector/graph-wasm';

const executor = new AsyncQueryExecutor(100); // Batch size
const results = await executor.executeStreaming(
  'MATCH (n:Person) RETURN n'
);

Web Worker Support

Execute queries in the background:

const executor = new AsyncQueryExecutor();
const promise = executor.executeInWorker(
  'MATCH (n) RETURN count(n)'
);

Batch Operations

Optimize multiple operations:

import { BatchOperations } from '@ruvector/graph-wasm';

const batch = new BatchOperations(1000); // Max batch size
await batch.executeBatch([
  'CREATE (n:Person {name: "Alice"})',
  'CREATE (n:Person {name: "Bob"})',
  // ... more statements
]);

Transactions

Atomic operation execution:

import { AsyncTransaction } from '@ruvector/graph-wasm';

const tx = new AsyncTransaction();
tx.addOperation('CREATE (n:Person {name: "Alice"})');
tx.addOperation('CREATE (n:Person {name: "Bob"})');

try {
  await tx.commit();
} catch (error) {
  tx.rollback();
}

Cypher Support

Currently supports basic Cypher operations:

CREATE

CREATE (n:Person {name: "Alice", age: 30})
CREATE (n:Person)-[:KNOWS]->(m:Person)

MATCH

MATCH (n:Person) RETURN n
MATCH (n:Person)-[r:KNOWS]->(m) RETURN n, r, m

Note: Full Cypher support is planned for future releases.

Hypergraph Examples

Creating Multi-Entity Relationships

// Create nodes
const doc1 = db.createNode(['Document'], {
  title: 'AI Research',
  embedding: [0.1, 0.2, 0.3, ...] // 384-dim vector
});

const doc2 = db.createNode(['Document'], {
  title: 'ML Tutorial'
});

const author = db.createNode(['Person'], {
  name: 'Dr. Smith'
});

// Create hyperedge connecting all three
const hyperedgeId = db.createHyperedge(
  [doc1, doc2, author],
  'Documents authored by researcher on related topics',
  null, // Auto-generate embedding from node embeddings
  0.95  // High confidence
);

const hyperedge = db.getHyperedge(hyperedgeId);
console.log(`Hyperedge connects ${hyperedge.order} nodes`);

Performance

  • Zero-copy transfers: Uses WASM memory for efficient data transfer
  • SIMD acceleration: When available in WASM environment
  • Lazy evaluation: Streaming results for large queries
  • Optimized indices: Fast lookups by label, type, and properties

Browser Compatibility

  • Chrome 90+
  • Firefox 88+
  • Safari 15.4+
  • Edge 90+

Building from Source

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build for web
npm run build

# Build for all targets
npm run build:all

# Run tests
npm test

Examples

See the examples directory for more usage examples:

  • Basic graph operations
  • Hypergraph relationships
  • Temporal queries
  • Vector similarity search

Roadmap

  • Full Cypher query parser
  • IndexedDB persistence
  • Graph algorithms (PageRank, community detection)
  • Schema validation
  • Transaction log
  • Multi-graph support
  • GraphQL integration

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

MIT - See LICENSE for details.

Support

Related Projects