Runtime

@cyphra/runtime wraps the official Neo4j JavaScript driver with Cyphra’s compiled Cypher types (CompiledCypher from @cyphra/query).

Prefer import { CyphraClient, … } from "cyphra" if you use the cyphra meta-package (install on the home page); subpackage imports are equivalent.

Client

import { cypher } from "@cyphra/query";
import { CyphraClient } from "@cyphra/runtime";
 
const client = new CyphraClient({
  uri: process.env.NEO4J_URI!,
  user: process.env.NEO4J_USER!,
  password: process.env.NEO4J_PASSWORD!,
  database: "neo4j", // optional, Neo4j 4+
  debug: false, // when true: logs Cypher text and parameter keys (never values)
});
 
await client.withSession(async (session) => {
  await client.runCompiled(session, cypher`RETURN 1 AS n`);
});
 
await client.close();

Optional driverConfig is passed through as the third argument to neo4j.driver (pool size, connectionAcquisitionTimeout, logging, etc.). Types: import Config from @cyphra/runtime or neo4j-driver.

Sessions and transactions

• session() — you own close(); prefer withSession(fn) so the session is always closed.
• withReadTransaction / withWriteTransaction — delegate to the driver’s executeRead / executeWrite with a managed transaction.

Inside a transaction callback, use runCompiledTx, runCypherTx, queryRecordsTx, queryRecordTx, selectRecordsTx, or selectRecordTx — same behavior as the session variants, but routed through tx.run (required for writes and retry semantics).

import { cypher } from "@cyphra/query";
 
await client.withWriteTransaction(async (tx) => {
  await client.runCompiledTx(tx, cypher`CREATE (n:Tmp { id: ${id} })`);
});

Executing queries

• runCompiled(session, compiled) — run CompiledCypher from cypher\…`orSelectQuery.toCypher()`.
• runCypher(session, strings, ...values) — tagged-template style on the client (same parameter rules as compileCypher).
• queryRecords / queryRecord — runCompiled plus plain row objects (record.toObject()).
• selectRecords / selectRecord — same for a SelectQuery.

Each of the above has a *Tx(tx, …) counterpart for use inside withWriteTransaction / withReadTransaction.

Lower-level helpers toPlainRecords and toPlainRecord map a driver Result (or compatible) to plain objects if you call session.run yourself.

See also

• Queries — cypher tag and SelectQuery builder
• Example app — optional live round-trip with NEO4J_* env vars