v2 redesign!

[aseemk]

With its own v2, Neo4j is now pretty firmly Cypher-first. It'd be great to update this driver's design and API to reflect and optimize for that, too.

E.g. people frequently request a method to add labels to a node. But since that's typically done at creation time, it's better to do that in the create transaction directly. Neo4j's REST API doesn't support that, but Cypher does.

There are still some things that are only accessible via the REST API today, so this driver would still need to support those things. E.g. query all labels; write to legacy indexes (needed for fulltext search); and soon, manage authentication.

Big-picture: does it make sense to have an object-oriented design anymore? Or should the driver really be pretty functional now — stateless, just like HTTP/REST?

Opening this issue to discuss all of these things.

[aseemk]

High level features/scenarios to support:

• Cypher queries
  • Let me make a simple, single query (with parameters).
    • Properly dictionary-ify result rows. (No one wants to access "column i".)
    • Properly translate error responses to Error objects.
  • Let me make multiple, transactional queries. (Both in one request and across requests.)
  • The plan is to use @brian-gates's cypher-stream for this.
• REST API for management
  • List schema indexes and constraints
  • Legacy indexing
  • Coming soon: authentication
  • Let me make arbitrary HTTP requests to the API, e.g. for custom plugins
• Shortcuts? AKA convenience methods around common Cypher queries. E.g.:
  • CRUD a node with the given properties and labels
  • CRUD schema-based indexes and constraints

Feel free to suggest others/changes and I'll edit this.

[brian-gates]

👍 :)

[aseemk]

Okay, I've spec'ed out a stab at what the v2 API looks like at a detailed level. It's long, but thorough. Please TAL; feedback welcome! (cc @jexp @chanadian)

https://github.com/thingdom/node-neo4j/blob/v2/API_v2.md

@brian-gates @wfreeman: your guys' feedback on the thinking behind the (simple, minimal) transactions API in particular would be great!

https://github.com/thingdom/node-neo4j/blob/v2/API_v2.md#transactions

Obviously heavily influenced by the design and capabilities of cypher-stream, but also keeping in mind @brian-gates's point (that I agree with) that if anybody really needs more power than this API ends up giving, they're always free to use cypher-stream directly. =)

Super excited. Still going to be a long road of impl. though. ;) Thanks guys!

[aseemk]

If you have any feedback, feel free to comment on the PR directly: #145.