Getting StartedNode.js

Getting Started with Node.js

CypherLite provides Node.js bindings built with napi-rs, offering a native N-API addon for high-performance graph database operations.

Installation

Install from npm

npm install cypherlite

Verify the installation

const { open } = require("cypherlite");
console.log("CypherLite loaded successfully");

Pre-built native addons are available for Linux, macOS, and Windows. If no pre-built binary is available, npm will attempt to build from source (requires the Rust toolchain).

Basic Usage

Open a Database

const { open } = require("cypherlite");
 
const db = open("my_graph.cyl");

Create Nodes and Relationships

db.execute("CREATE (a:Person {name: 'Alice', age: 30})");
db.execute("CREATE (b:Person {name: 'Bob', age: 25})");
db.execute(
  "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) " +
  "CREATE (a)-[:KNOWS {since: 2023}]->(b)"
);

Query Data

const result = db.execute("MATCH (n:Person) RETURN n.name, n.age");
for (const row of result) {
  console.log(`${row["n.name"]} (age: ${row["n.age"]})`);
}

Update and Delete

// Update properties
db.execute("MATCH (p:Person {name: 'Alice'}) SET p.age = 31");
 
// Delete a relationship
db.execute(
  "MATCH (a:Person {name: 'Alice'})-[r:KNOWS]->(b) DELETE r"
);
 
// Delete a node
db.execute("MATCH (p:Person {name: 'Bob'}) DELETE p");

Close the Database

db.close();
⚠️

Always call db.close() when finished to ensure all data is flushed to disk and native resources are released.

ES Module Support

CypherLite also works with ES modules:

import { open } from "cypherlite";
 
const db = open("my_graph.cyl");
// ... use the database
db.close();

Building from Source

If you need to build the native addon from source:

cd crates/cypherlite-node
npx napi build --release

Requirements

  • Node.js: 18+ (N-API v9)
  • Platform: Linux, macOS, Windows
  • Build from source: Requires the Rust 1.84+ toolchain
GoOverview