Skip to content
A Cypher parser/linter addon module for NodeJS.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
addon
docs
example
src
test
.codebeatignore
.dockerignore
.gitignore
.npmignore
.travis.yml
Dockerfile
LICENSE
README.md
binding.gyp
install-dependencies.sh
package-lock.json
package.json
tsconfig.json
tslint.json

README.md

Build Status macOS Linux TypeScript codecov codebeat badge Docs License
NPM

cypher-parser

A cypher graph query language parser/linter addon module for NodeJS.
It relies on libcypher-parser and rapidjson under the hood.

Features

  • Promise support
  • C++ addon parses queries in a worker thread
  • Typescript support with interfaces defined for full AST
  • Outputs json AST
  • Outputs text description of AST
  • Outputs error with position and description
  • Optional ANSI color support for text and error output
  • API Documentation

Supported Systems

  • Node 6.x, 8.x, 9.x, 10.x
  • linux-x64
  • darwin-x64 (OSX >= 10.7)

Sorry Windows users, the libcypher-parser depencency cannot be built on your systems. You can still run a docker container on Windows to use it.

Installation

npm install cypher-parser

The installation process will try to download a pre-built binary module matching your Node and OS version.
If it cannot be found, you will have to first run the steps in Custom Build.

Usage

The cypher-parser module has only one exported function: parse.
It takes a query string or a ParseParameters object as input, and returns a promise as output.
On success, the promise returns a ParseResult object or a string.
On failure, a CypherParserError object is thrown. It contains a ParseResult object for more details.

export interface ParseParameters {
  query: string;      // The cypher query to parse.
  width?: number;     // Width of the text AST output. Default 0.
  dumpAst?: boolean;  // If true, the ParseResult will contain a text description of the AST tree. Default false.
  rawJson?: boolean;  // If true, the result will be a json string instead of a ParseResult object. Default false.
  colorize?: boolean; // If true, the text AST output and error descriptions will be ANSI colored. Nice for console output.
}
export interface ParseResult {
  ast: string;                        // A text description of the AST tree.
  errors: ParseError[];               // Array of parse error encountered.
  directives: parseResultDirective[]; // Parsed cypher directives.
  roots: ast.AstNode[];               // The AST tree of the parsed query. Can be walked by programs. See API doc for details.
  nnodes: number;                     // Number of nodes parsed.
}
  • Typescript
import * as cypher from "cypher-parser";

async function testCypher() {
  const query = "MATCH (node1:Label1)-->(node2:Label2)\n" +
    "WHERE node1.propertyA = {value}\n" +
    "RETURN node2.propertyA, node2.propertyB";

  try {
    const result = await cypher.parse({
      query: query,
      dumpAst: true,
      colorize: true
    });
    console.log(result.ast);
  } catch (e) {
    const result: cypher.CypherParserError = e;
    for (const error of result.parseResult.errors) {
      console.log(error.position.line + ":" + error.position.column + ": " + error.message);
      console.log(error.context);
      console.log(" ".repeat(error.contextOffset) + "^");
      console.log(result.parseResult.ast);
    }
  }
}
  • Javascript
var cypher = require('cypher-parser');

async function testCypher() {
  var query = "MATCH (node1:Label1)-->(node2:Label2)\n" +
    "WHERE node1.propertyA = {value}\n" +
    "RETURN node2.propertyA, node2.propertyB";

  try {
    var result = await cypher.parse({
      query: query,
      dumpAst: true,
      colorize: true
    });
    console.log(result.ast);
  } catch (e) {
    for (var i = 0; i < e.parseResult.errors.length; i++) {
      var error = e.errors[i];
      console.log(error.position.line + ":" + error.position.column + ": " + error.message);
      console.log(error.context);
      console.log(" ".repeat(error.contextOffset) + "^");
      console.log(e.parseResult.ast);
    }
  }
}

Custom Build

In case a binary distribution is not available for your system, you must install build tools and compile the libcypher-parser dependency like this:

  • make, C++ and Pyton
sudo apk add make gcc g++ python
  • libcypher-parser
wget https://github.com/cleishm/libcypher-parser/releases/download/v0.6.0/libcypher-parser-0.6.0.tar.gz \
&& tar zxvpf libcypher-parser-0.6.0.tar.gz \
&& rm libcypher-parser-0.6.0.tar.gz \
&& cd libcypher-parser-0.6.0 \
&& ./configure --prefix=/usr/local CFLAGS='-fPIC' \
&& make clean check \
&& make install \
&& cd .. \
&& rm -rf libcypher-parser-0.6.0
You can’t perform that action at this time.