npm package: @sustainhawaii/simple-neo4j
Description: Simple Neo4J database driver utilizing cypher query language
Author: June Hanabi
Latest version: 4.3.2

    ╔═╗┬┌┬┐┌─┐┬  ┌─┐ ╔╗╔┌─┐┌─┐ ╦ ╦  ╦
    ╚═╗││││├─┘│  ├┤  ║║║├┤ │ │ ╚═║  ║
    ╚═╝┴┴ ┴┴  ┴─┘└─┘ ╝╚╝└─┘└─┘   ╩ ╚╝
    (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 4.0

4.0 brings in a lot of changes and consequently breaks support with pre 4.0
versions. If you have version 3.x or before make sure to read UPGRADE-4.0.md.

## Overview
-----------------

This is a simple neo4j pure javascript database driver. It takes in one or more
queries, commits them to the database in a single transaction, and parses the
database result into a simple and easy native javascript object, of course the
parser can be disabled if desired.

This class has lots of features, capability, and flexibility. Be sure to check
out below for all what it can do.

### Parser Note

This readme explains the class and its usage, it touches on the parser which
operates behind the scenes to turn the clunky restful api response into a
nice and pretty native javascript object, but it doesn't go into full detail
because it's its own package and I'll just be re-iterating it. This readme
describes the class and how to use it.

If you want to know all about the parser which operates behind-the-scenes on
this class, look at this link https://www.npmjs.com/package/neo4j-parser
which will take you to the package page for it.

## Usage

For simple and quick queries you can get up and running pretty easily with
minimal code.

    simpleNeo4J.execute('return "Hello"')
        .then(function(result)
        {
            // Do some cool stuff here
        });

This is perfect for running a quick and simple query by the database, it
prepares the query and commits it to the database on the spot. Believe
it or not it can be even easier, in this example we're returning a simple value,
and the parser has a convenience property among the full parsed result for that

    simpleNeo4J.execute('return "Hello"')
        .then(function(result)
        {
            result.firstValue === "Hello";
        });

Or if your an ES7 fan like I am

    var value = await simpleNeo4J.execute('return "Hello"');
    value.firstValue === "Hello";

Compare that to many other drivers out there which deal mostly in arrays, loops,
and other more clunky code.

### What about building up a transaction

What if you want to build up a transaction over time instead of executing it
on the spot right there right then all at once. No problem... The syntax is
actually very similar just split into a 2-step process to fit that very need.

    simpleNeo4J.addQuery('return "Hello"')
        .then(function(result)
        {
            // More awesome stuff
        });

    // Possibly more additions later...

    simpleNeo4J.commit();

### How about more control over the query

If you want more control over the query you have quite a number of options at
your disposal and you essentially pass a configuration object instead of a
string to set the options you want to set.

By the way all the options are stored in the docs viewable online (link below)
or on a git clone.

Lets add a meta property which will follow the query through its stages even up
to promise fulfillment or rejection.

    simpleNeo4J.execute({
        query: 'return "Hello"',
        meta: {
            aliasName: "...world"
        }
    }).then(function(result)
    {
        result.queryObj.meta.aliasName === "...world"
    });

or maybe flag raw mode which will selectively disable parsing for this query
only.

    simpleNeo4J.execute({
        query: 'return "Hello"',
        raw: true
    }).then(function(result)
    {
        result.firstValue === undefined
        result.rawResult === // Clunky rest object returned from database unparsed
    });

You can even mix and match as you see fit, for both `execute` and `addQuery`
you can pass a string, an object, or an array of strings, objects, or both.
The class doesn't care and it will all be processed out the same.

    simpleNeo4J.execute([
        'return "Hello"',
        {
            query: "match a return a"
        },
        'match (a:Action:Movie) return a']);

#### what about building up a seperate transaction

The 2-step `addQuery` & `commit` process mentioned above actually has a neat
feature that allows you to specify an alternate queue to add the query to. This
allows you to have multiple queues of queries you can build up if you desire.

    simpleNeo4J.addQuery('return "Hello"', "awesomeQueue")
        .then(function(result)
        {
            // Execution code here
        });

    // Possibly more queries added maybe in the default or other queues

    // Specify a name to commit from a different queue
    simpleNeo4J.commit(undefined, "awesomeQueue");

#### Can I buildup a transaction and still use execute?

Yes, execute commits one or more queries right then and there, as such, it
doesn't use any queues. So you can easily use both together.

    // Add 2 queries to different queues
    simpleNeo4J.addQuery('return "Query 1"');
    simpleNeo4J.addQuery('return "Query 2"', "queue1");

    // Execute right then a 3rd query
    simpleNeo4J.execute('return "Query 3"');

    // Then commit the 2 queues built up earlier
    simpleNeo4J.commit();
    simpleNeo4J.commit(undefined, "queue1");

### What's returned when passing an array though...

When passing an array of strings, objects, both, whatever... A promise is still
returned like normal, but the promise will enclose all the individual promises
of the query objects, in other words, a Promise.all in promise speak.

This works out really well because a Promise.all will reject on the first sign
of rejection, this is exactly what we want because any error that may come up
applies to all queries in any case.

If no error crops up then you'll have an array of results from all the queries
which is also exactly whats desired.

    simpleNeo4J.execute([
        'return "Query 1"',
        'return "Query 2"',
        'return "Query 3"'
    ]).then(function(results)
    {
        console.log(results[0], results[1], results[2]);
    });

#### The value you pass doesn't always equal the promise you'll get

The class carefully safeguards against invalid data throughout, if you pass
all invalid data in array or by itself, then no action will be taken and no
promise will be returned. This should be expected as you wouldn't want the class
to operate on invalid data such as a `boolean` or a `new Date` object for
example.

If an array of invalid data is passed and the array contains only 1 valid data
then you'll get a regular single Promise instead of a Promise that encapsulates
all the promises from the array. If an array contains no valid data then no
promise will be returned.

    simpleNeo4J.execute([
        'return "Query 1"',
        false,
        new Date()
    ]).then(function(result)
    {
        // Just 1 result as the others are clearly invalid so only 1 query
        // was processed and thus 1 promise issued
        console.log(result);
    });

### What about overlap in committing to the database

Only 1 instance of this class is ever needed unless you really want more than
one. That means you can execute several queries at one time in seperate go's
aka transactions even before the others get finished committing to the db.

Despite that, no overlap can happen as only one transaction is committed at a
time, any buildup enters a queue which is gradually processed out until empty.

## 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/simple-neo4j

## 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 which will test & 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`. To auto-copy over docs from master to gh-pages run
`npm run pages` before committing and pushing.

For testing, just run `npm run test`

If you want to contribute back read the `CONTRIBUTING.md` file.

## 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/simple-neo4j/docs

## Whats New
-----------------
Check out the CHANGELOG.md file for latest changes and updates