cypher-tag

A JavaScript template literal tag for Cypher in GraphQL.

Motivation

The neo4j-graphql-js and @neo4j/graphql libraries define a @cypher directive used for statically embedding Cypher statements on fields. This allows for writing custom operations that translate GraphQL to Cypher, on top of the default translation logic.

directive @cypher(statement: String!) on FIELD_DEFINITION ...

But there is no syntax highlighting for Cypher within GraphQL and attempting to define a cypher or cql tag must handle for nested composition.

Syntax Highlighting

If you install the Cypher Query Language Tools for Neo4j VSCode extension, then syntax highlighting will be supported when using the cql template literal tag.

Not Highlighted

When using cql, the tagged template literal is wrapped with a GraphQL Block String when compiled.

So instead of writing:

type Type {
  field: OutputType @cypher(statement: " ... ")
}

Or writing:

type Type {
  field: OutputType @cypher(statement: """
    ...
  """)
}

You can write:

type Type {
  field: OutputType @cypher(statement: ${cql`
    ... 
  `})
}

Highlighted

Composition

You can use the cql tag to compose the Cypher of another cql tag. This enables composition and reuse of Cypher template variables, perhaps while using imperative tooling, making your @cypher directives DRY. One caveat with the VSCode extension is that syntax highlighting breaks when cql is used on a variable but has a space behind it.

Roadmap

• Static validation of Cypher in string literals tagged with cql
• Corresponding VSCode extension
  • Improved syntax highlighting
  • IntelliSense integration with GraphQL schema
  • Activity bar tab with directory navigation for only files containing cql