AgentSkillsCN

@ruvector/graph-wasm

采用 Neo4j 风格的 Cypher API,为浏览器与边缘运行时打造 WASM 图数据库。适用于用户需要在浏览器中使用图数据库、执行客户端侧 Cypher 查询、进行基于 WASM 的图遍历、部署边缘知识图,或在无需服务器基础设施的情况下进行离线图操作。

SKILL.md
--- frontmatter
name: "@ruvector/graph-wasm"
description: "WASM graph database with Neo4j-inspired Cypher API for browser and edge runtimes. Use when the user needs a graph database in the browser, client-side Cypher queries, WASM-based graph traversals, edge-deployed knowledge graphs, or offline graph operations without server infrastructure."

@ruvector/graph-wasm

WebAssembly graph database with a Neo4j-inspired API and Cypher query support, enabling graph operations in browsers, Cloudflare Workers, Deno, and any WASM-compatible runtime.

Quick Command Reference

TaskCode
Initialize WASMawait init()
Create graph DBconst gdb = new WasmGraphDB()
Add vertexgdb.addVertex('user', '{"name":"Alice"}')
Add edgegdb.addEdge('v1', 'v2', 'KNOWS')
Cypher querygdb.query("MATCH (n) RETURN n")
Neighborsgdb.neighbors('v1')
Serializeconst bytes = gdb.serialize()
DeserializeWasmGraphDB.deserialize(bytes)

Installation

Hub install (recommended): npx ruvector@latest includes this package. Standalone: npx @ruvector/graph-wasm@latest See Installation Guide for the full ecosystem.

Core API

Initialization

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

await init();
const gdb = new WasmGraphDB();

Vertex Operations

typescript
// Add vertex (returns ID)
const id = gdb.addVertex('user', JSON.stringify({ name: 'Alice', age: 30 }));

// Get vertex
const vertex = gdb.getVertex(id); // { id, label, properties: JSON string }

// Delete vertex
gdb.deleteVertex(id);

// Get all vertices by label
const users = gdb.getVerticesByLabel('user');

Edge Operations

typescript
// Add edge
const edgeId = gdb.addEdge('v1', 'v2', 'KNOWS', JSON.stringify({ since: 2024 }));

// Get edge
const edge = gdb.getEdge(edgeId);

// Delete edge
gdb.deleteEdge(edgeId);

Cypher Queries

typescript
// Create
gdb.query("CREATE (n:Person {name: 'Alice'})");

// Match
const result = gdb.query("MATCH (n:Person) RETURN n.name");

// Relationships
gdb.query("MATCH (a:Person {name:'Alice'}), (b:Person {name:'Bob'}) CREATE (a)-[:KNOWS]->(b)");

// Pattern matching
const result = gdb.query("MATCH (a)-[:KNOWS]->(b) RETURN a.name, b.name");

Graph Algorithms

typescript
const neighbors = gdb.neighbors('v1');                    // Get neighbors
const path = gdb.shortestPath('v1', 'v5');               // Shortest path
const components = gdb.connectedComponents();             // Components

Serialization

typescript
const bytes = gdb.serialize();                            // To bytes
const gdb = WasmGraphDB.deserialize(bytes);               // From bytes

Browser Usage

html
<script type="module">
  import init, { WasmGraphDB } from '@ruvector/graph-wasm';
  await init();
  const gdb = new WasmGraphDB();
  gdb.addVertex('user', '{"name":"Alice"}');
  gdb.addVertex('user', '{"name":"Bob"}');
  gdb.addEdge('user:0', 'user:1', 'KNOWS');
  const result = gdb.query("MATCH (a)-[:KNOWS]->(b) RETURN a, b");
  console.log(result);
</script>

Common Patterns

Browser Knowledge Graph

typescript
await init();
const gdb = new WasmGraphDB();
// Build graph
for (const entity of entities) {
  gdb.addVertex(entity.type, JSON.stringify(entity.props));
}
for (const rel of relationships) {
  gdb.addEdge(rel.from, rel.to, rel.type);
}
// Query
const result = gdb.query("MATCH (a:Topic)-[:RELATED]->(b) RETURN b.name");

Persist to IndexedDB

typescript
const bytes = gdb.serialize();
await idb.put('graph', bytes);
// Later
const stored = await idb.get('graph');
const gdb = WasmGraphDB.deserialize(stored);

Offline Relationship Explorer

typescript
const gdb = new WasmGraphDB();
// Load from pre-built data
const bytes = await fetch('/graph.bin').then(r => r.arrayBuffer());
const gdb = WasmGraphDB.deserialize(new Uint8Array(bytes));
// Explore relationships without server
const related = gdb.query("MATCH (a {id: $id})-[*1..3]->(b) RETURN b", { id: selectedId });

Key Options

FeatureValue
Query languageCypher (subset)
Bundle size~150KB gzipped
AlgorithmsBFS, DFS, shortest path, components
SerializationBinary (Uint8Array)
RuntimesBrowser, Workers, Deno, Bun

RAN DDD Context

Bounded Context: Data Infrastructure

References