@grafeo-db/js

Node.js/TypeScript bindings for Grafeo, a high-performance, embeddable graph database with a Rust core.

Installation

npm install @grafeo-db/js

Quick Start

import { GrafeoDB } from '@grafeo-db/js';

// In-memory database
const db = GrafeoDB.create();

// Or persistent
// const db = GrafeoDB.create('./my-graph');

// Create nodes
db.createNode(['Person'], { name: 'Alice', age: 30 });
db.createNode(['Person'], { name: 'Bob', age: 25 });
db.createEdge(0, 1, 'KNOWS', { since: 2024 });

// Query with GQL
const result = await db.execute('MATCH (p:Person) WHERE p.age > 20 RETURN p.name, p.age');
for (const row of result.toArray()) {
  console.log(row);
}

db.close();

API Reference

Database

// Create / open
const db = GrafeoDB.create();           // in-memory
const db = GrafeoDB.create('./path');    // persistent
const db = GrafeoDB.open('./path');      // open existing

// Properties
db.nodeCount;   // number of nodes
db.edgeCount;   // number of edges

Query Languages

All query methods return Promise<QueryResult> and accept optional parameters:

await db.execute(gql, params?);         // GQL (ISO standard)
await db.executeCypher(query, params?);  // Cypher
await db.executeGremlin(query, params?); // Gremlin
await db.executeGraphql(query, params?); // GraphQL
await db.executeSparql(query);           // SPARQL

Node & Edge CRUD

const node = db.createNode(['Label'], { key: 'value' });
const edge = db.createEdge(sourceId, targetId, 'TYPE', { key: 'value' });

const n = db.getNode(id);     // JsNode | null
const e = db.getEdge(id);     // JsEdge | null

db.setNodeProperty(id, 'key', 'value');
db.setEdgeProperty(id, 'key', 'value');

db.deleteNode(id);  // returns boolean
db.deleteEdge(id);  // returns boolean

Transactions

const tx = db.beginTransaction();
try {
  await tx.execute("INSERT (:Person {name: 'Carol'})");
  tx.commit();
} catch (e) {
  tx.rollback();
}

// Node.js 22+ with explicit resource management:
using tx = db.beginTransaction();
await tx.execute("INSERT (:Person {name: 'Carol'})");
tx.commit(); // auto-rollback if not committed

QueryResult

result.columns;          // column names
result.length;           // row count
result.executionTimeMs;  // execution time (ms)
result.get(0);           // single row as object
result.toArray();        // all rows as objects
result.scalar();         // first column of first row
result.nodes();          // extracted nodes
result.edges();          // extracted edges

Vector Search

// Create an HNSW index
await db.createVectorIndex('Document', 'embedding', 384);

// Bulk insert
const ids = await db.batchCreateNodes('Document', 'embedding', vectors);

// Search
const results = await db.vectorSearch('Document', 'embedding', queryVector, 10);

Features

• GQL, Cypher, SPARQL, Gremlin, and GraphQL query languages
• Full node/edge CRUD with property management
• ACID transactions with automatic rollback
• HNSW vector similarity search with batch operations
• Async/await API backed by Rust + Tokio
• TypeScript definitions included

Links

• Documentation
• GitHub
• Python Package
• WASM Package

License

Apache-2.0