Neo4j JavaScript Driver

When to Use

Use this skill when working with the neo4j-driver package in JavaScript/TypeScript. Covers driver initialization, session management, the impersonation security model, transaction functions with retries, Neo4j type handling (Integer, DateTime, Node, Relationship), and mapping driver results to UI-consumable shapes.

1. Installation

npm install neo4j-driver

2. Driver Initialization

Create a single driver instance for the application lifetime. The driver manages a connection pool internally.

import neo4j, { Driver } from "neo4j-driver";

let driver: Driver | null = null;

export const initDriver = ( uri: string, user: string, password: string, ): Driver => { driver = neo4j.driver(uri, neo4j.auth.basic(user, password), { maxConnectionPoolSize: 50, connectionAcquisitionTimeout: 60000, // 60s maxTransactionRetryTime: 30000, // 30s }); return driver; };

export const getDriver = (): Driver => { if (!driver) throw new Error("Driver not initialized. Call initDriver() first."); return driver; };

export const closeDriver = async (): Promise<void> => { if (driver) { await driver.close(); driver = null; } };

Environment Configuration

export const NEO4J_CONFIG = { uri: import.meta.env.VITE_NEO4J_URI || "neo4j://localhost:7687", user: import.meta.env.VITE_NEO4J_USER || "neo4j", password: import.meta.env.VITE_NEO4J_PASSWORD || "password", database: import.meta.env.VITE_NEO4J_DATABASE || "neo4j", };

Verify Connectivity

const driver = initDriver(config.uri, config.user, config.password); await driver.verifyConnectivity(); console.log("Connected to Neo4j");

3. Session Management

Sessions are lightweight and should be created per unit of work, then closed.

import { Session } from "neo4j-driver";

export const getSession = (mode: "READ" | "WRITE" = "READ"): Session => { return getDriver().session({ database: NEO4J_CONFIG.database, defaultAccessMode: mode === "READ" ? neo4j.session.READ : neo4j.session.WRITE, }); };

Session Helper (Auto-Close)

export const withSession = async <T>( fn: (session: Session) => Promise<T>, mode: "READ" | "WRITE" = "READ", ): Promise<T> => { const session = getSession(mode); try { return await fn(session); } finally { await session.close(); } };

4. Impersonation (Two-Tier Security)

The application connects as a service account and impersonates the actual user. Neo4j RBAC enforces data-level permissions for the impersonated user.

export const getImpersonatedSession = (userEmail: string): Session => { return getDriver().session({ database: NEO4J_CONFIG.database, impersonatedUser: userEmail, // Executes as this user's Neo4j RBAC role }); };

export const withImpersonation = async <T>( userEmail: string, fn: (session: Session) => Promise<T>, ): Promise<T> => { const session = getImpersonatedSession(userEmail); try { return await fn(session); } finally { await session.close(); } };

Usage

// User only sees data their Neo4j role permits const transactions = await withImpersonation( "john.smith@company.com", async (session) => { const result = await session.run( MATCH (t:Transaction) WHERE t.timestamp >= $startDate RETURN t ORDER BY t.timestamp DESC LIMIT 100, { startDate }, ); return result.records.map((r) => r.get("t").properties); }, );

Prerequisites

• Neo4j Enterprise Edition 5.x

• Service account with GRANT IMPERSONATE privilege

• Users created in Neo4j mapped to IdP identities

5. Transaction Functions

Prefer executeRead / executeWrite over raw session.run() . They provide automatic retries for transient errors (network blips, leader changes).

// Read transaction with automatic retries const persons = await withSession(async (session) => { return session.executeRead(async (tx) => { const result = await tx.run( MATCH (p:Person {id: $personId})-[:OWNS]->(a:Account) RETURN p, collect(a) AS accounts, { personId }, ); return result.records.map((record) => ({ person: record.get("p").properties, accounts: record.get("accounts").map((a: any) => a.properties), })); }); });

// Write transaction with automatic retries await withSession(async (session) => { return session.executeWrite(async (tx) => { await tx.run(CREATE (p:Person $props), { props: { id: crypto.randomUUID(), name: "Jane Doe" }, }); }); }, "WRITE");

6. Neo4j Type Handling

The driver returns Neo4j-specific types that must be converted before use in UI code.

Integer

Neo4j integers are 64-bit. The driver wraps them in neo4j.Integer objects.

import neo4j from "neo4j-driver";

// Check if a value is a Neo4j Integer if (neo4j.isInt(value)) { const jsNumber = value.toNumber(); // Safe for values < Number.MAX_SAFE_INTEGER const jsString = value.toString(); // Safe for any value const jsBigInt = value.toBigInt(); // Native BigInt }

DateTime

if (neo4j.isDateTime(value)) { const isoString = value.toString(); // ISO 8601 string const jsDate = value.toStandardDate(); // JavaScript Date object }

if (neo4j.isDate(value)) { const isoString = value.toString(); // YYYY-MM-DD }

if (neo4j.isDuration(value)) { const str = value.toString(); // ISO 8601 duration }

Node, Relationship, Path

// Node record.get("n").identity; // neo4j.Integer (internal ID) record.get("n").elementId; // string (stable element ID — use this) record.get("n").labels; // string[] record.get("n").properties; // Record<string, any>

// Relationship record.get("r").identity; // neo4j.Integer record.get("r").elementId; // string record.get("r").type; // string (relationship type) record.get("r").startNodeElementId; // string record.get("r").endNodeElementId; // string record.get("r").properties; // Record<string, any>

// Path record.get("path").start; // Node record.get("path").end; // Node record.get("path").segments; // Array<{ start, relationship, end }> record.get("path").length; // number

7. Result-to-UI Data Mapping

Convert Neo4j driver results into shapes that Zustand stores and NVL components expect.

Property Mapping (Handle Neo4j Types)

function mapProperties( props: Record<string, unknown>, ): Record<string, unknown> { const mapped: Record<string, unknown> = {}; for (const [key, value] of Object.entries(props)) { if (neo4j.isInt(value)) { mapped[key] = value.toNumber(); } else if (neo4j.isDateTime(value) || neo4j.isDate(value)) { mapped[key] = value.toString(); } else if (neo4j.isDuration(value)) { mapped[key] = value.toString(); } else { mapped[key] = value; } } return mapped; }

Neo4j Node → Application GraphNode

interface GraphNode { id: string; labels: string[]; properties: Record<string, unknown>; }

function toGraphNode(neo4jNode: any): GraphNode { return { id: neo4jNode.elementId, labels: neo4jNode.labels, properties: mapProperties(neo4jNode.properties), }; }

Neo4j Relationship → Application GraphRelationship

interface GraphRelationship { id: string; type: string; source: string; target: string; properties: Record<string, unknown>; }

function toGraphRelationship(neo4jRel: any): GraphRelationship { return { id: neo4jRel.elementId, type: neo4jRel.type, source: neo4jRel.startNodeElementId, target: neo4jRel.endNodeElementId, properties: mapProperties(neo4jRel.properties), }; }

Full Query → Store Data

export const expandNetwork = async (personId: string, hops: number = 2) => { return withSession(async (session) => { const result = await session.executeRead(async (tx) => { return tx.run( MATCH path = (p:Person {id: $personId})-[*1..${hops}]-(connected) RETURN nodes(path) AS nodes, relationships(path) AS rels LIMIT 500, { personId }, ); });

const nodesMap = new Map<string, GraphNode>();
const relsMap = new Map<string, GraphRelationship>();

for (const record of result.records) {
  for (const node of record.get("nodes")) {
    nodesMap.set(node.elementId, toGraphNode(node));
  }
  for (const rel of record.get("rels")) {
    relsMap.set(rel.elementId, toGraphRelationship(rel));
  }
}

return {
  nodes: Array.from(nodesMap.values()),
  relationships: Array.from(relsMap.values()),
};

}); };

8. Parameterized Queries

Always use parameters. Never concatenate user input into Cypher strings.

// ✅ Parameterized — safe, enables query plan caching const result = await session.run( MATCH (p:Person {id: $personId})-[r*1..2]-(connected) WHERE connected.timestamp >= $startDate RETURN p, r, connected LIMIT $limit, { personId: id, startDate: startDate.toISOString(), limit: neo4j.int(100) }, );

// ❌ String interpolation — Cypher injection risk const result = await session.run( MATCH (p:Person {id: '${id}'})-[r*1..2]-(connected) RETURN p, );

9. Error Handling

import { Neo4jError } from "neo4j-driver";

export const handleNeo4jError = (error: unknown): never => { if (error instanceof Neo4jError) { switch (error.code) { case "Neo.ClientError.Security.Unauthorized": throw new Error("Invalid Neo4j credentials"); case "Neo.ClientError.Security.Forbidden": throw new Error("User does not have permission for this operation"); case "Neo.ClientError.Statement.SyntaxError": throw new Error(Invalid Cypher query: ${error.message}); case "Neo.ClientError.Schema.ConstraintValidationFailed": throw new Error(Constraint violation: ${error.message}); case "Neo.TransientError.Transaction.DeadlockDetected": throw new Error("Deadlock detected — retry the operation"); default: throw new Error(Neo4j error [${error.code}]: ${error.message}); } } throw error; };

Transient Error Retry

executeRead /executeWrite handle transient retries automatically. If using raw session.run() , catch and retry transient errors:

const isTransientError = (error: unknown): boolean => error instanceof Neo4jError && error.code.startsWith("Neo.TransientError");

10. Connection Lifecycle

// App startup const driver = initDriver(config.uri, config.user, config.password); await driver.verifyConnectivity();

// App shutdown (or React cleanup) useEffect(() => { return () => { closeDriver(); }; }, []);

Anti-Patterns

Anti-Pattern Why It Fails Fix

Storing the driver in React state useState(neo4j.driver(...)) — driver is not serializable, gets recreated on re-render Store driver in a module-level variable

Creating a new driver per query Bypasses connection pooling, exhausts resources Create one driver at app startup, reuse it

Not closing sessions Connection pool exhaustion — queries start timing out Always close in finally or use withSession helper

String concatenation in Cypher Cypher injection vulnerability Always use parameterized queries

Ignoring neo4j.Integer type toNumber() silently overflows for values > Number.MAX_SAFE_INTEGER

Use toString() for display, toBigInt() for arithmetic on large values

Using record.get('n').identity

Internal numeric ID — can change across database restarts Use record.get('n').elementId (stable string identifier)

Not mapping Neo4j types before storing in Zustand Zustand stores (and JSON serialization) can't handle neo4j.Integer or neo4j.DateTime

Always map with toNumber() / toString() before storing

Using session.run() for multi-statement transactions No automatic retry on transient errors, no transaction boundary Use session.executeRead(tx => ...) or session.executeWrite(tx => ...)