neo4j-driver-javascript-skill

## 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](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` / scriptin