11# Neo4j Driver for Javascript
22
3- An alpha-level database driver for a new Neo4j remoting protocol .
3+ An alpha-level database driver for Neo4j 3.0.0+ .
44
55Note: This is in active development, the API is not stable. Please try it out and give us feedback, but expect things to break in the medium term!
66
7+ Find detailed docs at [ alpha.neohq.net] ( http://alpha.neohq.net/docs/javascript-driver/ ) .
8+
79## Include module in Node.js application
810
11+ ``` shell
12+ npm install neo4j-driver
13+ ```
14+
915``` javascript
10- var neo4j = require (' neo4j' v1 ;
16+ var neo4j = require (' neo4j-driver ' v1 ;
1117```
1218
1319## Include in web browser
14- A global object ` neo4j ` will be available.
20+
21+ We build a special browser version of the driver, which supports connecting to Neo4j over WebSockets.
1522
1623``` html
1724<script src =" lib/browser/neo4j-web.min.js" script >
1825```
1926
20- ## Usage examples (for both Node.js and browser environments)
27+ This will make a global ` neo4j ` object available, where you can access the ` v1 ` API at ` neo4j.v1 ` :
2128
2229``` javascript
23- var statement = [' MERGE (alice:Person {name:{name_a},age:{age_a}})'
24- ' MERGE (bob:Person {name:{name_b},age:{age_b}})'
25- ' CREATE UNIQUE (alice)-[alice_knows_bob:KNOWS]->(bob)'
26- ' RETURN alice, bob, alice_knows_bob'
27- ];
30+ var driver = neo4j .v1 .driver (" bolt://localhost"
31+ ```
2832
29- var params = {
30- name_a: ' Alice'
31- age_a: 33 ,
32- name_b: ' Bob'
33- age_b: 44
34- };
33+ ## Usage examples
3534
35+ ``` javascript
3636
37- // Create a Session object to contain all Cypher activity.
37+ // Create a driver instance
3838var driver = neo4j .driver (" bolt://localhost"
39+
40+ // Create a session to run Cypher statements in.
41+ // Note: Always make sure to close sessions when you are done using them!
3942var session = driver .session ();
4043
41- // Run a Cypher statement within an implicit transaction
42- // The streaming way:
43- session .run (statement .join (' ' subscribe ({
44+ // Run a Cypher statement, reading the result in a streaming manner as records arrive:
45+ session
46+ .run (" MATCH (alice {name : {nameParam} }) RETURN alice.age" : ' Alice'
47+ .subscribe ({
4448 onNext : function (record ) {
45- // On receipt of RECORD
46- for ( var i in record) {
47- console . log (i, ' : ' , record[i]);
48- }
49- }, onCompleted : function () {
50- session . close ();
51- }, onError : function (error ) {
52- console .log (error);
49+ console . log (record);
50+ },
51+ onCompleted : function () {
52+ // Completed!
53+ session . close ();
54+ },
55+ onError : function (error ) {
56+ console .log (error);
5357 }
54- });
58+ });
5559
5660// or
57- // the Promise way, where the complete response is collected:
58- session .run (statement .join (' '
59- .then (function (records ){
60- records .forEach (function (record ) {
61- for (var i in record) {
62- console .log (i, ' : '
63- }
64- });
65- session .close ();
66- })
67- .catch (function (error ) {
68- console .log (error);
61+ // the Promise way, where the complete result is collected before we act on it:
62+ session
63+ .run (" MATCH (alice {name : {nameParam} }) RETURN alice.age" : ' Alice'
64+ .then (function (records ){
65+ records .forEach (function (record ) {
66+ console .log (record);
6967 });
68+
69+ // Completed!
70+ session .close ();
71+ })
72+ .catch (function (error ) {
73+ console .log (error);
74+ });
7075```
7176
7277## Building
@@ -84,24 +89,53 @@ See files under `examples/` on how to use.
8489This runs the test suite against a fresh download of Neo4j.
8590Or ` npm test ` if you already have a running version of a compatible Neo4j server.
8691
92+ For development, you can have the build tool rerun the tests each time you change
93+ the source code:
94+
95+ gulp watch-n-test
96+
8797### Testing on windows
88- Running tests on windows requires PhantomJS installed and its bin folder added in windows system variable ` Path ` .
89- To run the same test suite, run ` .\runTest.ps1 ` instead in powershell with admin right.
90- The admin right is required to start/stop Neo4j properly as a system service.
98+ Running tests on windows requires PhantomJS installed and its bin folder added in windows system variable ` Path ` .
99+ To run the same test suite, run ` .\runTest.ps1 ` instead in powershell with admin right.
100+ The admin right is required to start/stop Neo4j properly as a system service.
91101While there is no need to grab admin right if you are running tests against an existing Neo4j server using ` npm test ` .
92102
93103## A note on numbers and the Integer type
94- For this driver to fully map to the Neo4j type system handling of 64-bits Integers is needed.
95- Javascript can saftely represent numbers between ` -(2 ` <sup >` 53 ` </sup >` - 1) ` and ` (2 ` <sup >` 53 ` </sup >` - 1) ` .
96- Therefore, an Integer type is introduced.
104+ The Neo4j type system includes 64-bit integer values.
105+ However, Javascript can only safely represent integers between ` -(2 ` <sup >` 53 ` </sup >` - 1) ` and ` (2 ` <sup >` 53 ` </sup >` - 1) ` .
106+ In order to support the full Neo4j type system, the driver includes an explicit Integer types.
107+ Any time the driver recieves an Integer value from Neo4j, it will be represented with the Integer type by the driver.
97108
98109### Write integers
99- Number written directly e.g. ` session.run("CREATE (n:Node {age: {age}})", {age: 22}) ` will be of type ` Float ` in Neo4j.
100- To write the ` age ` as an integer the ` neo4j.int ` method should be used.
101- E.g. ` session.run("CREATE (n:Node {age: {age}})", {age: neo4j.int(22)}) ` .
110+ Number written directly e.g. ` session.run("CREATE (n:Node {age: {age}})", {age: 22}) ` will be of type ` Float ` in Neo4j.
111+ To write the ` age ` as an integer the ` neo4j.int ` method should be used:
112+
113+ ``` javascript
114+ var neo4j = require (' neo4j-driver' v1 ;
115+
116+ session .run (" CREATE (n {age: {myIntParam}})" : neo4j .int (22 )});
117+ ```
118+
119+ To write integers larger than can be represented as JavaScript numbers, use a string argument to ` neo4j.int ` :
120+
121+ ``` javascript
122+ session .run (" CREATE (n {age: {myIntParam}})" : neo4j .int (" 9223372036854775807"
123+ ```
102124
103125### Read integers
104- To get the value of a from Neo4j received integer, the safeast way would be to use the ` .toString() ` method on
105- an Integer object.
106- E.g. ` console.log(result.age.toString()) ` .
107- To check if a variable is of the Integer type, the method ` neo4j.isInt(variable) ` can be used.
126+ Since Integers can be larger than can be represented as JavaScript numbers, it is only safe to convert Integer instances to JavaScript numbers if you know that they will not exceed ` (2 ` <sup >` 53 ` </sup >` - 1) ` in size:
127+
128+ ``` javascript
129+ var aSmallInteger = neo4j .int (123 );
130+ var aNumber = aSmallInteger .toNumber ();
131+ ```
132+
133+ If you will be handling integers larger than that, you can use the Integer instances directly, or convert them to strings:
134+
135+ ``` javascript
136+ var aLargerInteger = neo4j .int (" 9223372036854775807"
137+ var integerAsString = aLargerInteger .toString ();
138+ ```
139+
140+ To help you work with Integers, the Integer class exposes a large set of arithmetic methods.
141+ Refer to the Integer API docs for details.
0 commit comments