README

Neo-js

Background

Neo-js a wrapper around the neo4j REST API. It uses the pure RESTful URIs for most of its operations but uses the cypher language mostly for traversing the graph which seems more appropriate.

The library is well tested as much as I can for a lot of the features that matters. To get a more detailed usage of the library the tests are a good place to look.

The test runner uses the movie sample database that came standard with neo4j. The database will be populated with the sample DB when it runs. Note, all nodes and relationships will be deleted before the test runs.

Test

lib/test folder contains the test and also a good documentation to look at for what is possible with this library.

Installation

npm install neo-js

Basics

First the database needs to be initialized before it can be used. The init method is used to probe the database for endpoints that will used for making requests. This avoids hardcording the endpoints as suggested by the documentation.

DB.init(url).then(function(client){
    // begin to interact with the database using the client
});

Graph Traversing

Querying the graph database uses the Neo4J Cypher Language internally to construct a query that is sent to the server. The result

Find any matching node with a hte Movie label

MATCH (movie:Movie) RETURN movie LIMIT 2

client.nodeEngine().traverse({id:"movies",label:"Movie"})
      .limit(2)
      .execute().then(function(result){
        console.log("Movies",result.movies)
      });

Search for nodes with parameters which will be used as "WHERE" clauses when returning nodes

MATCH (movie:Movie {name:"Carrie Fisher"}) RETURN movie LIMIT 2

client.nodeEngine().traverse({id:"people",label:"Person",params:{name:"Carrie Fisher"}})
      .execute().then(function(result){
        console.log("People",result.people);
      });

Search for nodes and relationships

MATCH (people:Person {name:"Carrie Fisher"}) -[acts:ACTED_IN]-> (movies:Movie)

client.nodeEngine()
        .traverse({id:"people",label:"Person",params:{name:"Carrie Fisher"}})
        .relationship({node:{
            id:"movies",
            label:"Movie"
        },id:"acts",label:"ACTED_IN",direction:"out"})
        .limit(2)
        .execute().then(function(result){
            console.log("People",result.people);
            console.log("Movies",result.movies);
            console.log("Acts",result.acts);
        });

You can run a raw cypher query too in case you need a bit more flexibility. The result will not be parsed though

(n)-[*1.5]->(m)

client.nodeEngine().raw({id:"people",label:"Person",params:{name:"Carrie Fisher"}})
        .relationship({node:{
            id:"movies",
            label:"Movie"
        },id:"acts",label:"ACTED_IN",direction:"out"})
        .limit(2)
        .execute().
        then(function(result){
            console.log("Raw Result",result)
        });

Node

Fetching

Fetching a single node from a know url, will fail if node is not present. The node will be populated with all the required URIS for subsequent requests

var q = new client.graph.Node({url:"http://localhost:7474/db/data/node/27237"});
q.get().then(function(node){
    console.log("Node Properties",node.data)
});

Node Labels

Labels can be added or deleted from a node

node.labels.all().then(function(labels){
    console.log("LABELS",labels) // an array of labels
})

node.labels.add(["Tester"]).then(function(){
    node.labels.all().then(function(){

    });
})

node.labels.remove("Person").then(function(){

});

Node/Relationship Properties

Properties added to Nodes/Relationships is on the data property of the node/relationships. The properties can also be updated

node.properties().then(function(properties){
    console.log("Node Properties",properties);
});

var radonName = "QA TEST " + Math.random();
node.update({
    name:radonName
}).then(function(){

});

Delete a node

Deleting a node will also delete all its relationships. The library uses the batch operation feature of neo4j to delete all the relationships and the node itslef at a go. If any of the operations fail, the whole relationship will fail.

node.remove().then(function(){
    node.get() // this will fail.
});

Relationships

Fetching relationships

The relationship properties an be used to query relationships on a node. The relationship will have a start and end node.These nodes are just nodes with a url.

node.relationships.any().then(function(relationships){
            var relationship = relationships[0];
            console.log("Start Node",relationship.start);
            console.log("End Node",relationship.end);

            relationship.start.get() // retrieves th node
        });

 // retrieve outgoing relationships with labels KNOW and PRODUCED
 node.relationships.out(["KNOW","PRODUCED"]).then(function(relationships){
            expect(relationships.length).to.equal(1);
            var relationship = relationships[0];
            expect(relationship.type).to.equal("PRODUCED");
            done();
        });

Removing relationships

// remove a single relationship
relationship.remove()

// remove all the relationships
node.relationships.removeAll()

Create Relationship

node.relationships.create({
                to:movie.url,
                type:"TESTED",
                data:{
                    created:(new Date()).getTime(),
                    tested:true
                }
            }).then(function(relationship){
                expect(relationship.type).to.equal("TESTED");
                expect(relationship.data.tested).to.equal(true);
                done();
            });

API REFERENCE

coming soon, mean while, have a look at the tests

Usage no npm install needed!