neo4j-driver-javascript-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

编写连接Neo4j的JS/TS代码（Node.js或浏览器环境）
配置驱动、会话、事务或执行查询
调试Integer处理、结果消费、会话泄漏、异步错误
为驱动对象添加TypeScript类型注解

When NOT to Use

不适用场景

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

编写/优化Cypher查询 → 使用
```
neo4j-cypher-skill
```
升级驱动版本 → 使用
```
neo4j-migration-skill
```
RxJS会话API → 参考references/rxjs-session.md

Install

安装

bash

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

bash

npm install neo4j-driver   # 或：yarn add neo4j-driver

Environment Variables

环境变量

Load connection config from environment — never hardcode credentials.

bash

undefined

从环境变量加载连接配置——切勿硬编码凭证。

bash

undefined

.env file (add to .gitignore)

.env 文件（添加到.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.

NEO4J_URI=neo4j+s://xxx.databases.neo4j.io NEO4J_USERNAME=neo4j NEO4J_PASSWORD=secret NEO4J_DATABASE=neo4j


```javascript
// npm install dotenv（适用于Node.js < 20或.env自动加载关闭的情况）
import 'dotenv/config'   // 或：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+ 可通过

--env-file .env

原生加载

.env

文件。Next.js / Vite会自动加载

.env

——无需导入dotenv。

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

在启动时创建一个驱动实例，全局共享。切勿为每个请求创建新实例。

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()   // 启动时如果无法连接则快速失败
// 关闭时：
await driver.close()

URI协议：

协议	传输方式	适用场景
`neo4j+s://`	TLS + 集群路由	Aura环境；生产集群
`neo4j://`	明文 + 集群路由	本地开发集群
`bolt+s://`	TLS，单实例	启用TLS的单个Neo4j实例
`bolt://`	明文，单实例	本地单实例

认证选项：

javascript

neo4j.auth.basic(user, password)   // 用户名/密码认证
neo4j.auth.bearer(token)           // SSO / JWT认证
neo4j.auth.kerberos(base64Ticket)  // Kerberos认证
neo4j.auth.none()                  // 无认证（仅开发环境使用）

Web框架中的单例模式——创建一次，全局导入：

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 }
}

无服务器环境（Lambda/Vercel/Workers）：设置

maxConnectionPoolSize: 5

；无法保证

SIGTERM

信号。

Choose the Right API

选择合适的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

API	适用场景	自动重试	返回结果
`driver.executeQuery()`	大多数查询的默认选择	✅	立即获取所有记录
`session.executeRead/Write()`	处理大量结果、流式传输、多查询事务	✅	延迟加载流
`session.run()`	`LOAD CSV` 、 `CALL IN TRANSACTIONS` 、脚本场景	❌	延迟加载流

executeQuery

— Default

executeQuery

— 默认选择

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 })

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'))   // 使用.get()——记录并非普通对象
}

// 写入操作并统计结果
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)   // ✅ 必须调用.updates()

始终指定

database

——省略会导致额外的网络往返。

❌ 切勿使用模板字符串拼接Cypher：

javascript

// ❌ 存在注入风险 + 禁用查询计划缓存
await driver.executeQuery(`MATCH (p:Person {name: '${name}'}) RETURN p`)
// ✅ 使用参数化查询
await driver.executeQuery('MATCH (p:Person {name: $name}) RETURN p', { name })

Managed Transactions (

executeRead

executeWrite

)

托管事务（

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')

遇到临时故障时会自动重试。务必在回调内部消费记录——回调返回后流会失效。

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' }
    )
    // ✅ 在事务开启时收集数据；返回普通数据
    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()   // 务必放在finally块中
}

关键注意事项：
await tx.run()
返回的是流句柄，而非记录。

javascript

// ❌ 返回流；事务关闭；records = []
return await tx.run('MATCH (p:Person) RETURN p.name AS name')

// ✅ 在回调内部完整收集数据
const result = await tx.run('MATCH (p:Person) RETURN p.name AS name')
return (await result.collect()).map(r => r.get('name'))

// ✅ 或使用for-await流式处理
for await (const record of result) { names.push(record.get('name')) }

回调可能会执行多次（临时故障时重试）——请勿在回调内部执行副作用操作：

javascript

// ❌ 每次重试都会调用fetch()
await session.executeWrite(async tx => {
  await fetch('https://api.example.com/notify')
  await tx.run('CREATE ...')
})
// ✅ 在事务提交确认后执行副作用操作
await session.executeWrite(async tx => { await tx.run('MERGE ...') })
await fetch('https://api.example.com/notify')

session.run

— Implicit Transactions

session.run

— 隐式事务

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()
}

不会自动重试。仅适用于

LOAD CSV

CALL IN TRANSACTIONS

/ 脚本场景。

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

会话关闭 — 务必放在

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())

javascript

// ❌ 如果executeRead抛出异常，会话会泄漏
session.executeRead(async tx => { ... })
  .then(result => doSomething(result))
  .then(() => session.close())

// ✅ 保证会话关闭
try {
  const result = await session.executeRead(async tx => { ... })
  doSomething(result)
} finally {
  await session.close()
}

// ✅ Promise链等价写法
session.executeRead(async tx => { ... })
  .then(doSomething)
  .catch(handleError)
  .finally(() => session.close())

Integer Handling

Integer处理

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() })

Neo4j的整数是64位；JS的

Number

是IEEE 754标准（仅在2^53−1以内是安全的）。驱动默认返回自定义的

Integer

类型。

三种模式：

javascript

// 模式1（默认）：Integer类 — 支持所有数值，但需要转换
const driver1 = neo4j.driver(URI, auth)
// record.get('count') → Integer { low: 42, high: 0 }

// 模式2：原生JS数字 — 仅在Number.MAX_SAFE_INTEGER范围内安全
const driver2 = neo4j.driver(URI, auth, { disableLosslessIntegers: true })
// record.get('count') → 42

// 模式3：BigInt — 精度准确，但会导致JSON.stringify失败
const driver3 = neo4j.driver(URI, auth, { useBigInt: true })
// record.get('count') → 42n

使用Integer类：

javascript

const count = record.get('count')        // Integer { low: 42, high: 0 }
neo4j.isInt(count)                       // true
neo4j.integer.inSafeRange(count)         // 在调用toNumber()前检查是否安全
count.toNumber()                         // 42  (仅在MAX_SAFE_INTEGER范围内安全)
count.toString()                         // '42' (始终安全)
count.toBigInt()                         // 42n

// 传递整数参数 — 普通JS数字会作为FLOAT发送
await driver.executeQuery('CREATE (p:Person {age: $age})', { age: neo4j.int(30) })

JSON序列化陷阱：

javascript

// ❌ Integer → {"low":42,"high":0}
JSON.stringify({ age: record.get('age') })
// ❌ BigInt → TypeError: Do not know how to serialize a BigInt
// ✅ 先转换
JSON.stringify({ age: record.get('age').toNumber() })
// ✅ 或使用disableLosslessIntegers: true
// ❌ 时间类型 → 静默转为{}
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.

记录不是普通对象——使用

.get()

方法：

javascript

const record = records[0]
record.get('name')    // ✅ 通过键名访问
record.get(0)         // ✅ 通过索引访问
record.keys           // ['name', 'age']
record.has('name')    // true
record.name           // ❌ undefined
record['name']        // ❌ undefined

record.toObject()

返回普通JS键名但值仍然是驱动类型（Integer、时间类型）。未经转换的话无法安全地进行JSON序列化。

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.

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') { /* 唯一约束错误 */ }
    if (err.code === SERVICE_UNAVAILABLE) { /* 无法连接 */ }
    if (err.code === SESSION_EXPIRED)     { /* 开启新会话 */ }
    if (err.retriable) { /* 临时错误 — executeQuery已自动重试至上限 */ }
  }
}

executeQuery

和

executeRead/Write

会自动重试可重试错误。

session.run

不会。

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

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)
  }
)

// 带类型的节点 — Integer泛型会随disableLosslessIntegers设置变化
const node = record.get('p') as Node<Integer>
const age: number = node.properties.age.toNumber()
// 当disableLosslessIntegers: true时 → Node<number>; age已经是number类型

Batch Writes with UNWIND

使用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' }
)

javascript

// ❌ 每个条目对应一个事务
for (const p of people) { await driver.executeQuery('CREATE ...', p) }

// ✅ 单个事务完成
await driver.executeQuery(
  `UNWIND $people AS person
   MERGE (p:Person {name: person.name})
   SET p.age = person.age`,
  { people },   // 普通对象数组；数字字段必须是JS数字，而非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

错误做法	修复方案
使用模板字符串拼接Cypher	使用 `$param` 占位符
`record.name` / `record['name']`	使用 `record.get('name')`
对Integer直接使用 `JSON.stringify`	先调用 `.toNumber()` 或设置 `disableLosslessIntegers`
对时间类型直接使用 `JSON.stringify`	先调用 `.toString()`
`summary.counters.nodesCreated`	使用 `summary.counters.updates().nodesCreated`
省略 `database` 参数	始终指定 `{ database: 'neo4j' }`
从事务回调返回 `result`	返回 `await result.collect()` 或映射后的普通数据
`.then(() => session.close())`	使用 `try/finally { await session.close() }`
在事务回调内部执行副作用操作	移到外部——回调可能会重试
为每个请求创建新驱动实例	在启动时创建一次，全局共享
在浏览器中使用 `bolt://` 或 `neo4j://`	使用 `neo4j+s://` （WSS协议）
在UNWIND数组中使用Integer	先转换为普通JS `Number`
在无服务器环境中设置 `maxConnectionPoolSize: 100`	每个函数实例设置5–10

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)

按需加载：

references/data-types.md — 完整类型映射表、时间类型、图类型（Node/Relationship/Path）、空间类型（Point/WGS-84/Cartesian）、
```
toNative()
```
转换工具
references/advanced-patterns.md — 显式事务、因果一致性/书签、连接池调优、结果转换器、延迟加载流、仓库模式
references/browser-usage.md — WebSocket URI、CORS、打包器配置、安全指南
references/rxjs-session.md — RxJS会话API（
```
rxSession.run()
```
、可观察模式）

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)

在启动时创建一个驱动实例并全局共享
每个查询/会话都指定
```
database
```
参数
在启动时调用
```
await driver.verifyConnectivity()
```
在
```
finally
```
块中调用
```
session.close()
```
使用
```
.get()
```
访问记录——不使用点语法/方括号语法
在JSON序列化前对Integer调用
```
.toNumber()
```
/
```
.toString()
```
在JSON序列化前对时间类型调用
```
.toString()
```
访问计数器字段前调用
```
summary.counters.updates()
```
使用
```
$param
```
占位符——不在Cypher中使用字符串拼接
事务回调返回普通数据（而非流）；副作用操作放在回调外部
写入操作使用
```
neo4j.int()
```
传递整数参数
读取操作使用
```
executeRead
```
；写入操作使用
```
executeWrite
```
浏览器环境：使用
```
neo4j+s://
```
URI（WebSocket）

neo4j-driver-javascript-skill

Original

Translation

When to Use

适用场景

When NOT to Use

不适用场景

Install

安装

Environment Variables

环境变量

.env file (add to .gitignore)

.env 文件（添加到.gitignore）

Driver Lifecycle

驱动生命周期

Choose the Right API

选择合适的API

executeQuery — Default

executeQuery — 默认选择

Managed Transactions (executeRead / executeWrite)

托管事务（executeRead / executeWrite）

session.run — Implicit Transactions

session.run — 隐式事务

Session Close — Always in finally

会话关闭 — 务必放在finally块中

Integer Handling

Integer处理

Record Access

记录访问

Error Handling

错误处理

TypeScript

TypeScript

Batch Writes with UNWIND

使用UNWIND批量写入

Common Mistakes

常见错误

References

参考资料

Checklist

检查清单

`executeQuery`
— Default

`executeQuery`
— 默认选择

Managed Transactions (
`executeRead`
/
`executeWrite`
)

托管事务（
`executeRead`
/
`executeWrite`
）

`session.run`
— Implicit Transactions

`session.run`
— 隐式事务

Session Close — Always in
`finally`

会话关闭 — 务必放在
`finally`
块中