neo4j

Neo4j driver (REST API client) for Node.js

npm install neo4j
24 downloads in the last day
138 downloads in the last week
854 downloads in the last month

Node-Neo4j

This is a client library for accessing Neo4j, a graph database, from Node.js. It uses Neo4j's REST API.

This library supports and has been tested against Neo4j 1.5 through Neo4j 1.9.

Installation

npm install neo4j

Usage

To start, create a new instance of the GraphDatabase class pointing to your Neo4j instance:

var neo4j = require('neo4j');
var db = new neo4j.GraphDatabase('http://localhost:7474');

Node.js is asynchronous, which means this library is too: most functions take callbacks and return immediately, with the callbacks being invoked when the corresponding HTTP requests and responses finish.

Here's a simple example:

var node = db.createNode({hello: 'world'});     // instantaneous, but...
node.save(function (err, node) {    // ...this is what actually persists.
    if (err) {
        console.err('Error saving new node to database:', err);
    } else {
        console.log('Node saved to database with id:', node.id);
    }
});

Because async flow in Node.js can be significantly tricky to handle, we strongly recommend using a flow control tool or library to help. Our personal favorite is Streamline.js, but other popular choices are async, Step, Seq, TameJS and IcedCoffeeScript.

Once you've gotten the basics down, skim through the full API documentation to see what this library can do, and take a look at @aseemk's node-neo4j-template app for a complete usage example. (The models/User.js file in particular is the one that interacts with this library.)

This library is now officially "v1", but "v2" will almost certainly have breaking changes in order to support Neo4j 2.0 and generally improve the API (roadmap). You can be sheltered from these changes if you simply specify your node-neo4j dependency as 1.x or ~1.0 instead of *.

Development

git clone git@github.com:thingdom/node-neo4j.git
cd node-neo4j
npm install && npm run clean

You'll also need a local Neo4j database instance for the tests:

NEO4J_VERSION=neo4j-community-1.9.4
curl http://dist.neo4j.org/$NEO4J_VERSION-unix.tar.gz --O $NEO4J_VERSION-unix.tar.gz
tar -zxvf $NEO4J_VERSION-unix.tar.gz
rm $NEO4J_VERSION-unix.tar.gz
ln -s $NEO4J_VERSION/bin/neo4j neo4j

If you're new to Neo4j, read the Getting Started page. Start the server:

./neo4j start

Stop the server:

./neo4j stop

To run the tests:

npm test

Important: The tests are written assuming Neo4j >=1.7 and will now fail on prior Neo4j versions, but the library supports prior Neo4j versions just fine.

This library is written in CoffeeScript, using Streamline.js syntax. The tests automatically compile the code on-the-fly, but you can also generate compiled .js files from the source ._coffee files manually:

npm run build

This is in fact what's run each time this library is published to npm. But please don't check the generated .js files in; to remove:

npm run clean

When compiled .js files exist, changes to the source ._coffee files will not be picked up automatically; you'll need to rebuild.

If you npm link this module into another app (like node-neo4j-template) and you want the code compiled on-the-fly during development, you can create an index.js file under lib/ with the following:

require('coffee-script');
require('streamline').register();
module.exports = require('./index._coffee');

But don't check this in! That would cause all clients to compile the code on-the-fly every time, which isn't desirable in production.

Changes

See the Changelog for the full history of changes and releases.

License

This library is licensed under the Apache License, Version 2.0.

Feedback

If you encounter any bugs or other issues, please file them in the issue tracker.

We also now have a Google Group! Post questions and participate in general discussions there.

npm loves you