╔╗╔┌─┐┌─┐ ╦ ╦ ╦ ╔═╗┌─┐┬─┐┌─┐┌─┐┬─┐
║║║├┤ │ │ ╚═║ ║ ╠═╝├─┤├┬┘└─┐├┤ ├┬┘
╝╚╝└─┘└─┘ ╩ ╚╝ ╩ ┴ ┴┴└─└─┘└─┘┴└─
(Ascii-art generated by patorjk.com)
Part of the Neo4J Line of Packages
isomorphic-node
^
|
+
isomorphic-cypher <--+ template-query-object
^ ^
| |
| +
| + neo4j-query-object
+ |
simple-neo4j <------+ neo4j-parser
|
+ cypher-tools
ascii-chart generated by asciiflow.com
Upgrade to 2.0
2.0 brings in a lot of changes and consequently breaks support with pre 2.0 versions. If you have version 1.x or before make sure to read UPGRADE-2.0.md but it essentially involves converting the numeric parameters to single parameter object-form.
About
Neo4J parser is designed to be dropped into a library or project that works with Neo4J but doesn't want to deal with parsing the replies from its restful service.
The restful service is suppose to be more Javascript friendly as its communication is in Javascripts own JSON format but in reality it can be very cumbersome to go through often requiring layers of iteration and type checking even for just one single property return like a string or boolean.
Because of this, many people have turned away from writing a Neo4J driver that fits their own needs to avoid dealing with parsing the reply and often turn to popular libraries that try to wrap the database in a pretty bow creating many issues in and of itself.
This fixes that by encouraging you to write your own driver, when you get to the JSON reply bit leave it to this package, it takes in the entire JSON reply and spits it out in a nice and very easy native Javascript object that you can use in most cases with just 1 line of code.
Checkout the usage and other details below for some better insight
How this package breaks down a Neo4J restful reply
This describes how it breaks it down which is the focal point of the package, but theres a bit more it does which is explained next after this section.
columns are first, the column name is what all the items flow under
return {key: "value"} as column,
{movie: "action"} as theOne
{
column: {
key: "value"
},
theOne: {
movie: "action"
}
}
result.theOne.movie === "action" // Super easy
returned objects under that column have there keys and values merged
return {
hello: "world"
} as hello
union
return {
key: "value"
} as hello
{
hello: {
key: "value",
hello: "world"
}
}
So complexities of union returns are made transparent, the end result is still predicable and easy requiring no loops or involved logic
result.hello.key === "value"
objects with duplicate keys have a numeric suffix appended
return {
hello: "world"
} as column
union
return {
hello: "world"
} as column
{
column: {
hello: "world",
hello0: "world2"
}
}
This keeps everything nice and predictable while preventing any duplication complexities
result.column.hello0 === "world2"
non-object returns use a numerical index as the key
return "The Matrix" as movie
union
return 1234 as movie
{
movie: {
0: "The Matrix",
1: 1234
}
}
Many granular returns will be just a single value, not an object, again, its simply assigned an index number in place of key
of course everything can be mixed
return {
hello: "world"
} as col
union
return {
hello: "world2"
}
union
return 1234 as col
union
return ["An", "Array"] as col
{
col: {
0: 1234,
1: ["An", "Array"],
hello: "world"
hello0: "world2"
}
}
Making things even more simple
The above is super simple to work with, but its made even easier. The result object is only a piece of what's returned. There are many convenience properties already prepared for you and ready alongside the result.
These are gathered during parsing so no cpu time is wasted and can make things even more simpler. This is the full object returned from the parser.
{
result // The parsed object as mentioned above
firstValue // The first parsed value of the first parsed column
firstColumn // The first parsed column in whole
rawResult // The unparsed result, its the raw object form of this result entry
rawBody // The JSON string itself
}
Many times you'll be returning a simple value from the database, you don't know or care about the column, you just want the value you requested. Of course you can always pull it from the parsed result but the convenience property makes it much easier
return "The One"
firstValue === "The One"
The again you may be returning an entire object, you don't care about the column name, nor are you returning any other columns, your just interested in the one object your returning
return {
hello: "world",
movies: ["Action", "Adventure"]
}
firstColumn === {
hello: "world",
movies: ["Action", "Adventure"]
}
firstValue === "world"
The result will always include 2 raw properties, 1 is the native javascript reply straight from the database, its pulled from the JSON string as a native javascript object, but no more parsing is done from there.
The other is the actual JSON reply string. These are given in case you find them useful in any way, it may come in handy or edge cases or custom solutions.
Raw / Unparsed Mode
The final topic is raw mode, in raw mode, all properties in the parsed object are undefined except for the 2 raw properties mentioned above, you'll gain some speed increase from it but you'll be responsible for your own parsing.
Raw mode is flexible, it can be enabled for all the parsed queries by passing true to parsers raw option or it can be selectively enabled for certain queries in the response by passing a function to the parser's isRaw property which will be called once for each query index in the response, a value of true activates raw mode for that query and false disables it.
This package is solid
This package is actively tested with Jasmine and thoroughly documented throughout. It also contains complete JSDoc comments and full online JSDoc generated documentation.
Do you like this package or have an issue?
If this package has helped you I encourage you to follow it, give it a star, or fork it on github. If you have any ideas, suggestions, issues, or ways to improve upon it then let us know over at github by filing an issue.
Contributions are also encouraged and the CONTRIBUTING.md file shows all the details on development and how to contribute back but its mostly just commit changes and send a pull request.
This project is licensed Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0.txt
Run it in your browser
Thanks to TonicDev, you now have a way to run this package right in your browser to test it out. If your on the NPM site you can see the TonicDev link on the right-hand side, otherwise you can always go to the link below.
TonicDev will load up a preset example we provide that you can play around with to get a feel for this package.
https://tonicdev.com/npm/neo4j-parser
How to develop
To develop, git clone this repository and npm install to install the
development dependencies. Make sure to run npm run build when
needed such as before tests and such which will compile ES6/7 to ES5 and
re-generate the docs. You can run those individually if you want with
npm run docs and npm run compile.
For testing, just run npm run test
Then just push the changes and send a pull-request back
This project makes use of github project pages using the "gh-pages" branch and JSDoc for all documentation and tutorials. So the way things are done for the docs is this
- Compile and test docs in master branch until happy
- Commit to git
- Run
npm run pages
- This will switch to the gh-pages branch, merge from master, and switch back
- Run
git push --all
Documentation
Detailed documentation exists for this package, it should already by viewable on clone. Feel free to look through it for any questions you may have. The source code is also heavily documented if you want to look through it as well for answers.
Online docs exist here http://junestoolbox.github.io/neo4j-parser/docs
Whats New
Check out the CHANGELOG.md file for latest changes and updates