Skill v1.0.1

currentAutomated scan100/100

neo4j-contrib/neo4j-skills/neo4j-driver-javascript-skill

+6 new

──Details

PublishedJune 16, 2026 at 09:12 PM

Content Hashsha256:97674f36bee2b128...

Git SHA6d44d3166bf8

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 13.9 KB)

SKILL.md13.9 KBactive

SKILL.md · 423 lines · 13.9 KB

name: neo4j-driver-javascript-skill description: Neo4j JavaScript/TypeScript Driver v6 — driver lifecycle, executeQuery, managed transactions (executeRead/executeWrite), session.run, Integer handling, JSON serialization, record access, async/await patterns, TypeScript types, error handling, and connection setup for Node.js and browser. Use when writing JS/TS code that connects to Neo4j: neo4j.driver(), executeQuery, executeRead, executeWrite, session.run, neo4j.int, record.get, Integer, BookmarkManager, bolt://, neo4j+s://. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT cover driver version migration — use neo4j-migration-skill. compatibility: neo4j-driver v6; Node.js >=18; TypeScript supported via bundled types version: 1.0.1 allowed-tools: Bash WebFetch

When to Use

Writing JS/TS code that connects to Neo4j (Node.js or browser)
Setting up driver, sessions, transactions, or query execution
Debugging Integer handling, result consumption, session leaks, async errors
TypeScript type annotations for driver objects

When NOT to Use

Writing/optimizing Cypher → neo4j-cypher-skill
Upgrading driver version → neo4j-migration-skill
RxJS session API → references/rxjs-session.md

Install

bash

npm install neo4j-driver   # or: yarn add neo4j-driver

Environment Variables

Load connection config from environment — never hardcode credentials.

bash

# .env file (add to .gitignore)
NEO4J_URI=neo4j+s://xxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=secret
NEO4J_DATABASE=neo4j

javascript

// npm install dotenv (for Node.js < 20 or when .env auto-load is off)
import 'dotenv/config'   // or: require('dotenv').config()
const URI      = process.env.NEO4J_URI
const USER     = process.env.NEO4J_USERNAME
const PASSWORD = process.env.NEO4J_PASSWORD
const DATABASE = process.env.NEO4J_DATABASE ?? 'neo4j'

Node 20+ natively loads .env with --env-file .env. Next.js / Vite auto-load .env — no dotenv import needed.

Driver Lifecycle

Create one driver instance at startup. Share everywhere. Never create per-request.

javascript

// CommonJS
const neo4j = require('neo4j-driver')
// ESM / TypeScript
import neo4j from 'neo4j-driver'
const driver = neo4j.driver(
  process.env.NEO4J_URI,                              // 'neo4j+s://xxx.databases.neo4j.io'
  neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD)
)
await driver.verifyConnectivity()   // fail fast on startup if unreachable
// On shutdown:
await driver.close()

URI schemes:

Scheme	Transport	Use
`neo4j+s://`	TLS + cluster routing	Aura; production clusters
`neo4j://`	plaintext + cluster routing	local dev cluster
`bolt+s://`	TLS, single instance	single Neo4j instance with TLS
`bolt://`	plaintext, single instance	local single instance

Auth options:

javascript

neo4j.auth.basic(user, password)   // username/password
neo4j.auth.bearer(token)           // SSO / JWT
neo4j.auth.kerberos(base64Ticket)  // Kerberos
neo4j.auth.none()                  // unauthenticated (dev only)

Singleton for web frameworks — create once, import everywhere:

javascript

// db.js
let _driver = null
export function getDriver() {
  if (!_driver) _driver = neo4j.driver(process.env.NEO4J_URI,
    neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD))
  return _driver
}
export async function closeDriver() {
  if (_driver) { await _driver.close(); _driver = null }
}

Serverless (Lambda/Vercel/Workers): keep maxConnectionPoolSize: 5; no guaranteed SIGTERM.

Choose the Right API

API	Use when	Auto-retry	Result
`driver.executeQuery()`	Default for most queries	✅	eager (all records)
`session.executeRead/Write()`	Large results, streaming, multi-query tx	✅	lazy stream
`session.run()`	`LOAD CSV`, `CALL IN TRANSACTIONS`, scripts	❌	lazy stream

`executeQuery` — Default

javascript

const { records, summary, keys } = await driver.executeQuery(
  'MATCH (p:Person {name: $name})-[:KNOWS]->(f) RETURN f.name AS name',
  { name: 'Alice' },
  { database: 'neo4j', routing: neo4j.routing.READ }
)
for (const record of records) {
  console.log(record.get('name'))   // use .get() — records are NOT plain objects
}
// Write and count results
const { summary: s } = await driver.executeQuery(
  'CREATE (p:Person {name: $name, age: $age})',
  { name: 'Bob', age: neo4j.int(30) },
  { database: 'neo4j' }
)
console.log(s.counters.updates().nodesCreated)   // ✅ must call .updates()

Always specify database — omitting causes an extra round-trip.

❌ Never template-literal Cypher:

javascript

// ❌ injection risk + disables plan caching
await driver.executeQuery(`MATCH (p:Person {name: '${name}'}) RETURN p`)
// ✅ parameterised
await driver.executeQuery('MATCH (p:Person {name: $name}) RETURN p', { name })

Managed Transactions (`executeRead` / `executeWrite`)

Auto-retried on transient failures. Consume records inside the callback — the stream is gone when the callback returns.

javascript

const session = driver.session({ database: 'neo4j' })
try {
  const names = await session.executeRead(async tx => {
    const result = await tx.run(
      'MATCH (p:Person) WHERE p.name STARTS WITH $prefix RETURN p.name AS name',
      { prefix: 'Al' }
    )
    // ✅ collect() while tx is open; return plain data
    return (await result.collect()).map(r => r.get('name'))
  })
  await session.executeWrite(async tx => {
    await tx.run('MERGE (p:Person {name: $name})', { name: 'Carol' })
  })
} finally {
  await session.close()   // always in finally
}

Critical: `await tx.run()` returns a stream handle, not records.

javascript

// ❌ returns stream; tx closes; records = []
return await tx.run('MATCH (p:Person) RETURN p.name AS name')
// ✅ collect fully inside callback
const result = await tx.run('MATCH (p:Person) RETURN p.name AS name')
return (await result.collect()).map(r => r.get('name'))
// ✅ or stream with for-await
for await (const record of result) { names.push(record.get('name')) }

Callback may execute more than once (retry on transient failure) — no side effects inside:

javascript

// ❌ fetch() called on every retry
await session.executeWrite(async tx => {
  await fetch('https://api.example.com/notify')
  await tx.run('CREATE ...')
})
// ✅ side effects after confirmed commit
await session.executeWrite(async tx => { await tx.run('MERGE ...') })
await fetch('https://api.example.com/notify')

`session.run` — Implicit Transactions

Not auto-retried. Use for LOAD CSV / CALL IN TRANSACTIONS / scripting only.

javascript

const session = driver.session({ database: 'neo4j' })
try {
  const result = await session.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Alice' })
  console.log(result.summary.counters.updates().nodesCreated)
} finally {
  await session.close()
}

Session Close — Always in `finally`

javascript

// ❌ session leaks if executeRead rejects
session.executeRead(async tx => { ... })
  .then(result => doSomething(result))
  .then(() => session.close())
// ✅ guaranteed close
try {
  const result = await session.executeRead(async tx => { ... })
  doSomething(result)
} finally {
  await session.close()
}
// ✅ promise-chain equivalent
session.executeRead(async tx => { ... })
  .then(doSomething)
  .catch(handleError)
  .finally(() => session.close())

Integer Handling

Neo4j integers are 64-bit; JS Number is IEEE 754 (safe up to 2^53−1). Driver returns custom Integer by default.

Three modes:

javascript

// Mode 1 (default): Integer class — safe for all values, requires conversion
const driver1 = neo4j.driver(URI, auth)
// record.get('count') → Integer { low: 42, high: 0 }
// Mode 2: native JS number — only safe within Number.MAX_SAFE_INTEGER
const driver2 = neo4j.driver(URI, auth, { disableLosslessIntegers: true })
// record.get('count') → 42
// Mode 3: BigInt — precise but breaks JSON.stringify
const driver3 = neo4j.driver(URI, auth, { useBigInt: true })
// record.get('count') → 42n

Working with Integer class:

javascript

const count = record.get('count')        // Integer { low: 42, high: 0 }
neo4j.isInt(count)                       // true
neo4j.integer.inSafeRange(count)         // check before toNumber()
count.toNumber()                         // 42  (only safe within MAX_SAFE_INTEGER)
count.toString()                         // '42' (always safe)
count.toBigInt()                         // 42n
// Send integer parameter — plain JS number sends as FLOAT
await driver.executeQuery('CREATE (p:Person {age: $age})', { age: neo4j.int(30) })

JSON serialization pitfalls:

javascript

// ❌ Integer → {"low":42,"high":0}
JSON.stringify({ age: record.get('age') })
// ❌ BigInt → TypeError: Do not know how to serialize a BigInt
// ✅ convert first
JSON.stringify({ age: record.get('age').toNumber() })
// ✅ or use disableLosslessIntegers: true
// ❌ temporal types → {} silently
JSON.stringify({ dt: record.get('created') })
// ✅
JSON.stringify({ dt: record.get('created').toString() })

Record Access

Records are not plain objects — use .get():

javascript

const record = records[0]
record.get('name')    // ✅ by key
record.get(0)         // ✅ by index
record.keys           // ['name', 'age']
record.has('name')    // true
record.name           // ❌ undefined
record['name']        // ❌ undefined

record.toObject() returns plain JS keys but values are still driver types (Integers, temporals). Not JSON-safe without conversion.

Error Handling

javascript

import { Neo4jError, SERVICE_UNAVAILABLE, SESSION_EXPIRED } from 'neo4j-driver'
try {
  await driver.executeQuery('...', {}, { database: 'neo4j' })
} catch (err) {
  if (err instanceof Neo4jError) {
    if (err.code === 'Neo.ClientError.Schema.ConstraintValidationFailed') { /* unique constraint */ }
    if (err.code === SERVICE_UNAVAILABLE) { /* unreachable */ }
    if (err.code === SESSION_EXPIRED)     { /* open a new session */ }
    if (err.retriable) { /* transient — executeQuery already retried to exhaustion */ }
  }
}

executeQuery and executeRead/Write auto-retry retriable errors. session.run does not.

TypeScript

typescript

import neo4j, { Driver, Session, ManagedTransaction, Record, Node, Integer } from 'neo4j-driver'
const driver: Driver = neo4j.driver(URI, neo4j.auth.basic(USER, PASSWORD))
const session: Session = driver.session({ database: 'neo4j' })
const names: string[] = await session.executeRead(
  async (tx: ManagedTransaction): Promise<string[]> => {
    const result = await tx.run('MATCH (p:Person) RETURN p.name AS name')
    return (await result.collect()).map((r: Record) => r.get('name') as string)
  }
)
// Typed node — Integer generic changes with disableLosslessIntegers
const node = record.get('p') as Node<Integer>
const age: number = node.properties.age.toNumber()
// With disableLosslessIntegers: true → Node<number>; age is already number

Batch Writes with UNWIND

javascript

// ❌ one transaction per item
for (const p of people) { await driver.executeQuery('CREATE ...', p) }
// ✅ single transaction
await driver.executeQuery(
  `UNWIND $people AS person
   MERGE (p:Person {name: person.name})
   SET p.age = person.age`,
  { people },   // array of plain objects; numeric fields must be JS numbers, not neo4j.int()
  { database: 'neo4j' }
)

Common Mistakes

Mistake	Fix
Template literal Cypher	Use `$param` placeholders
`record.name` / `record['name']`	`record.get('name')`
`JSON.stringify` on Integer	`.toNumber()` or `disableLosslessIntegers`
`JSON.stringify` on temporal	`.toString()` first
`summary.counters.nodesCreated`	`summary.counters.updates().nodesCreated`
Omit `database`	Always `{ database: 'neo4j' }`
Return `result` from tx callback	Return `await result.collect()` or mapped data
`.then(() => session.close())`	`try/finally { await session.close() }`
Side effects inside tx callback	Move outside — callback may retry
New driver per request	Create once at startup
`bolt://` or `neo4j://` in browser	Use `neo4j+s://` (WSS)
Integer in UNWIND array	Convert to plain JS `Number` first
`maxConnectionPoolSize: 100` in serverless	Use 5–10 per function instance

References

Load on demand:

references/data-types.md — full type mapping table, temporal types, graph types (Node/Relationship/Path), spatial types (Point/WGS-84/Cartesian), toNative() conversion helper
references/advanced-patterns.md — explicit transactions, causal consistency/bookmarks, connection pool tuning, result transformers, lazy streaming, repository pattern
references/browser-usage.md — WebSocket URIs, CORS, bundler config, security guidance
references/rxjs-session.md — RxJS session API (rxSession.run(), observable patterns)

Checklist

[ ] One driver instance created at startup; shared everywhere
[ ] database specified on every query/session
[ ] await driver.verifyConnectivity() called at startup
[ ] session.close() in finally block
[ ] Records accessed with .get() — not dot/bracket notation
[ ] Integer .toNumber() / .toString() called before JSON serialization
[ ] Temporal .toString() called before JSON serialization
[ ] summary.counters.updates() called before accessing counter fields
[ ] $param placeholders used — no string concatenation in Cypher
[ ] Tx callback returns plain data (not stream); side effects outside callback
[ ] Write uses neo4j.int() for integer parameters
[ ] executeRead for reads; executeWrite for writes
[ ] Browser: neo4j+s:// URI (WebSocket)

← v1.0.0 All versions

Skill v1.0.1

When to Use

When NOT to Use

Install

Environment Variables

Driver Lifecycle

Choose the Right API

executeQuery — Default

Managed Transactions (executeRead / executeWrite)

session.run — Implicit Transactions

Session Close — Always in finally

Integer Handling

Record Access

Error Handling

TypeScript

Batch Writes with UNWIND

Common Mistakes

References

Checklist

`executeQuery` — Default

Managed Transactions (`executeRead` / `executeWrite`)

`session.run` — Implicit Transactions

Session Close — Always in `finally`