Merge branch 'docs' into develop

jamesfer · Mar 6, 2018 · ecd54d3 · ecd54d3
2 parents 0418ffc + 3570c26
commit ecd54d3
Show file tree

Hide file tree

Showing 32 changed files with 23,825 additions and 85 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 node_modules
 npm_debug.log
+yarn-error.log
 .idea/
 .nyc_output/
 coverage/

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 James Ferguson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/assets/css/main.css b/docs/assets/css/main.css
diff --git a/docs/assets/css/main.css.map b/docs/assets/css/main.css.map
diff --git a/docs/assets/images/icons.png b/docs/assets/images/icons.png
diff --git a/docs/assets/images/icons@2x.png b/docs/assets/images/icons@2x.png
diff --git a/docs/assets/images/widgets.png b/docs/assets/images/widgets.png
diff --git a/docs/assets/images/widgets@2x.png b/docs/assets/images/widgets@2x.png
diff --git a/docs/assets/js/main.js b/docs/assets/js/main.js
diff --git a/docs/assets/js/search.js b/docs/assets/js/search.js
diff --git a/docs/classes/builder.html b/docs/classes/builder.html
diff --git a/docs/classes/connection.html b/docs/classes/connection.html
diff --git a/docs/classes/query.html b/docs/classes/query.html
diff --git a/docs/classes/whereand.html b/docs/classes/whereand.html
diff --git a/docs/classes/wherenot.html b/docs/classes/wherenot.html
diff --git a/docs/classes/whereop.html b/docs/classes/whereop.html
diff --git a/docs/classes/whereor.html b/docs/classes/whereor.html
diff --git a/docs/classes/wherexor.html b/docs/classes/wherexor.html
diff --git a/docs/globals.html b/docs/globals.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/interfaces/credentials.html b/docs/interfaces/credentials.html
diff --git a/docs/interfaces/driver.html b/docs/interfaces/driver.html
diff --git a/docs/interfaces/session.html b/docs/interfaces/session.html
diff --git a/package.json b/package.json
@@ -23,6 +23,7 @@
     "build:prod": "webpack --progress --env.production",
     "test": "nyc --reporter=text --reporter=html mocha src/*.spec.ts src/**/*.spec.ts",
     "release": "./scripts/release.sh",
+    "docs": "typedoc src/builder.ts src/query.ts src/connection.ts src/clauses/index.ts src/clauses/where-comparators.ts src/clauses/where-operators.ts --mode file --theme minimal --out ./docs --excludeExternals --excludeProtected --excludePrivate --ignoreCompilerErrors",
     "ci:test": "nyc --reporter=lcov --reporter=text mocha src/*.spec.ts src/**/*.spec.ts",
     "ci:report": "./node_modules/.bin/nyc report --reporter=text-lcov | coveralls"
   },
@@ -68,6 +69,7 @@
     "source-map-support": "^0.5.0",
     "ts-loader": "^3.1.1",
     "ts-node": "^4.1.0",
+    "typedoc": "^0.10.0",
     "typescript": "^2.5.3",
     "uglifyjs-webpack-plugin": "^0.4.6",
     "webpack": "^3.6.0",

diff --git a/readme.md b/readme.md
@@ -5,14 +5,15 @@
 A flexible and intuitive query builder for Neo4j and Cypher.
 Write queries in Javascript just as you would write them in Cypher.
 
-    let results = await db.matchNode('user', 'User', { email: 'email@email.com' })
+    let results = await db.matchNode('user', 'User', { active: true })
+      .where({ 'user.age': greaterThan(18) })
       .with('user')
       .create([
         cypher.node('user', ''),
-        cypher.relation('out', '', 'HasPost'),
-        cypher.node('post', 'Post', { body: 'Hello!' })
+        cypher.relation('out', '', 'HasVehicle'),
+        cypher.node('vehicle', 'Vehicle', { colour: 'red' })
       ])
-      .ret(['user', 'post'])
+      .ret(['user', 'vehicle'])
       .run();
 
     // Results:
@@ -22,42 +23,69 @@ Write queries in Javascript just as you would write them in Cypher.
     //     labels: [ 'User' ],
     //     properites: { ... },
     //   },
-    //   post: {
+    //   vehicle: {
     //     identity: 4321,
-    //     labels: [ 'Post' ],
+    //     labels: [ 'Vehicle' ],
     //     properties: { ... },
     //   },
     // }]
 
-This package is currently in development and many things are likely to be
-undocumented or to change without warning. However, any feedback is welcome.
+## Quick start
 
-## Usage
+### Installing
 
-### Creating a connection
+    npm install --save cypher-query-builder
+or
+
+    yarn install cypher-query-builder
+
+### Importing
+CommonJS/Node
+
+    const cypher = require('cypher-query-builder');
+    // cypher.Connection
+    // cypher.greaterThan
+    // ....
+
+ES6
+
+    import { Connection, greaterThan } from 'cypher-query-builder';
+
+### Connecting
+
+    const cypher = require('cypher-query-builder');
+
     // Make sure to include the protocol in the hostname
     let db = new cypher.Connection('bolt://localhost', {
       username: 'root',
       password: 'password',
     });
+
 Cypher query builder uses the official Neo4j Nodejs driver over the bolt
 protocol in the background so you can pass any values into connection that
 are accepted by that driver.
 
-The Connection class implements the query builder interface.
+### Querying
+
+ES5
 
     db.matchNode('projects', 'Project')
+      .ret('projects')
+      .run()
+      .then(function (results) {
+        // Do something with results
+      });
+
+ES6
+
+    const results = await db.matchNode('projects', 'Project')
       .ret('projects')
       .run();
 
 `run` will execute the query and return a promise. The results are in the
-_standardish_ Neo4j form of:
+_standardish_ Neo4j form an array of records:
 
-    // An array of all rows
     [
-      // If you return more than one thing in your RETURN clause
-      // there will be multiple properties of each row, like in
-      // the first example. In this case there is only one.
       {
         projects: {
           // Internal Neo4j node id, don't rely on this to stay constant.
@@ -70,21 +98,52 @@ _standardish_ Neo4j form of:
           // Note that Neo4j numbers will automatically be converted to
           // Javascript numbers. This may cause issues because Neo4j can
           // store larger numbers than can be represented in Javascript.
-          // This behaviour is currently in development and may change
+          // This behaviour is currently in consideration and may change
           // in the future.
           properties: { name: 'Project 1' },
         },
       },
       ...
     ]
 
-I've found that the best way to extract the data you want is with lodash.
+### Processing
+
+To extract the results, you can use ES5 array methods or a library like lodash:
 
     // Get all the project nodes (including their id, labels and properties).
-    let projects = map(results, 'projects');
+    let projects = results.map(row => row.projects);
 
     // Get just the properties of the nodes
-    let projectProps = map(results, row => row.projects.properties);
+    let projectProps = results.map(row => row.projects.properties);
+
+## Documentation
+
+For more details on creating a connection, see the 
+[Connection](http://jamesfer.me/cypher-query-builder/classes/connection.html) class.
+
+For more details on clauses and running queries, see the 
+[Query](http://jamesfer.me/cypher-query-builder/classes/query.html) class.
+
+## License
+
+MIT License
+
+Copyright (c) 2018 James Ferguson
 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.