Decypher
decypher is a node.js library packing a handful of utilities to deal with cypher queries.
It includes the following:
- A Yesql-like query loader.
- A query builder.
- An expression builder.
- Miscellaneous helpers.
Installation
You can install decypher from npm likewise:
npm install decypher
or from github if you need the latest development version:
npm install git+https://github.com/Yomguithereal/decypher.git
Query loader
Query files
Write one or more cypher queries per file:
File containing a single query
// Any comments...MATCH (n)-[r]-(t)RETURN n,r,t LIMIT 100;
File containing multiple named queries
// name: first// Retrieve book nodesMATCH (b:Book)RETURN b; // name: second// Retrieve vocabulary nodesMATCH (v:Vocabulary)RETURN v;
Decyphering
Just require decypher and use it to load your queries:
var decypher = ;// Or to only load the relevant codevar decypher = ; // Loading a single query;>>> 'MATCH (n)-[r]-(t)\nRETURN n,r,t LIMIT 100;' // Loading multiple named queries;>>> first: 'MATCH (b:Book)\nRETURN b;' second: 'MATCH (v:Vocabulary)\nRETURN v;' // Loading a batch of files at once;>>> single: 'MATCH (n)-[r]-(t)\nRETURN n,r,t LIMIT 100;' multiple: first: 'MATCH (b:Book)\nRETURN b;' second: 'MATCH (v:Vocabulary)\nRETURN v;' // Loading the content of a folder // folder/// - single.cypher// - multiple.cypher;>>> single: 'MATCH (n)-[r]-(t)\nRETURN n,r,t LIMIT 100;' multiple: first: 'MATCH (b:Book)\nRETURN b;' second: 'MATCH (v:Vocabulary)\nRETURN v;' // Choosing a different extension when loading a folder;
Now that if what you want is only to parse cypher strings because you retrieved the files on your, own, you can alternatively use decypher.parse
.
Query builder
Note that this query builder is widely inspired by the query-builder package by @shesek but fixed and updated to support cypher's latest evolutions.
The result object of the builder is also made to match @thingdom node-neo4j specifications for the db.cypher
method.
var Query = Query;// Or to only load the relevant codevar Query = ; // Creating a queryvar cypher = ; // Compiling to stringcypher;// orcypher;>>> `MATCH (n:Node) WHERE n.title = {title} RETURN n;` // Retrieving the query's parameterscypher;>>> title: 'The best title' // Retrieving the query's statements as an arraycypher;>>> 'MATCH (n:Node)' 'WHERE n.title = {title}' 'RETURN n' // Retrieving all of the above at oncevar query params statements = cypher; // You can also alternatively interpolate the params into the query// (Useful for debugging but unsafe!!!)cypher;>>> `MATCH (n:Node) WHERE n.title = "The best title" RETURN n;` // Note that multi words statements like `ORDER BY` have to be written in camel-case:cypher; // You can also set a bunch of params at oncecypher;cypher; // If you need to pass multiple query parts at once & separated by a comma// just pass an array of strings instead of a single string.cypher;>>> 'CREATE (a:Actor), (m:Movie)' // You can also add arbitrary parts to the query if requiredcypher;cypher; // It's possible to directly pass an expression to the query builder:cypher;>>> 'WHERE a OR b' // It's also possible to pass a descriptive object that will build a// relationship pattern using the `helpers.relationshipPattern` function:cypher;>>> 'MATCH (a)-[r]->(b)' // Finally, you can segment your query for conveniencevar cypher = start = cypher end = cypher; end;start; cypher;>>> `MATCH (a:Actor) RETURN a;`
Special cases
FOREACH
query; // Using a sub query (params will be merged into the main query)var subquery = ;subquery;query;
Expression builder
The expression builder lets you build where
expression easily:
var Expression = Expression;// Or to only load the relevant codevar Expression = ; var expr = 'a = b';expr; expr;// orexpr;>>> 'a = b AND c = d' // Note that you can nest expressions:var expr = 'a = b';expr ; expr;>>> 'a = b OR (c = d AND e = f)' expr;>>> false
Note that expressions can be directly fed to the Query builder.
Helpers
Escaping identifiers
var helpers = helpers;// Or to only load the relevant codevar helpers = ; helpers;>>> '`Complex ``Identifier```'
Escaping literal maps
var helpers = helpers;// Or to only load the relevant codevar helpers = ; helpers;>>> '{hello: "world", `complex key`: 3}' // Indicating parameter keyshelpers;>>> '{name: {name}, number: 2}'
Building node patterns
var helpers = helpers;// Or to only load the relevant codevar helpers = ; // Possible options are:// * `identifier`: a string// * `label` or `labels`: a string or an array of strings// * `data`:// - if string, will produce a single parameter// - if object, will stringify it// * `paramKeys`: will be passed to escapeLiteralMap when stringifying data helpers;>>> '()' helpers;>>> '(n)' helpers;>>> '(n:Node)' helpers;>>> '(n:Node {title: "Hello"})' helpers;>>> '(n {paramName})' helpers;>>> '(:Chapter {title: {title}})'
Building relationship patterns
var helpers = helpers;// Or to only load the relevant codevar helpers = ; // Possible options are:// * `direction`: "in" or "out"// * `identifier`: a string// * `type` or `types`: a string or an array of strings// * `data`:// - if string, will produce a single parameter// - if object, will stringify it// * `paramKeys`: will be passed to escapeLiteralMap when stringifying data// * `source`: the source node (passed to the `nodePattern` function)// * `target`: the target node (passed to the `nodePattern` function) helpers;>>> '--' helpers;>>> '-[r]-' helpers;>>> '-[r:KNOWS]->' helpers;>>> '<-[:PLAYS_IN|:KNOWS]-' helpers;>>> '<-[r {paramName}]-' helpers;>>> '-[:KNOWS {since: 1975}]-' helpers;>>> '(a)-[:PLAYED_IN]->(m:Movie)'
Building search patterns
Note that it will escape for query for regular expression use through the escape-regexp
module.
var helpers = helpers;// Or to only load the relevant codevar helpers = ; // Possible options are:// * `flags` [`'ius'`]: Flags for the regular expression.// * `partial` [`true`]: Should the match be partial (wrapped in `.*query.*`)? helpers;>>> '(?ius).*john.*' helpers;>>> '(?im).*john.*' helpers;>>> 'john'
Contribution
Contributions are of course more than welcome. Be sure to add and pass any relevant unit tests before submitting any code.
git clone git@github.com:Yomguithereal/decypher.gitcd decypher # Installing dependencies npm install # Running unit tests npm test
Roadmap
- Some helpers
- A batch