cypher-dsl 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aae0b1907cab6d377de663093abb2aca70b7925b10dafc1596a50ccfc6f8a97f
+  data.tar.gz: 21ad9bce707aabfb247196a75bdfb7de97ffa215e53b210aaa2179dcf0a7b313
+SHA512:
+  metadata.gz: 69811594f30155665847bc68fc4c66471de5e0f8ae1b1a83e39d08fd6d8426720e4206aa260f20358c395a87ba2ff2a530eafe518f7621235267d97831a05754
+  data.tar.gz: bc7823802abd14746151e12ae00050be8070be48b0fbed3ef593ef6654bdd0e6613c5c8ebdd78089d3ffbb7303830f06560cb637bb402d893ec279c57f111e43

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0.alpha.1] - 2026-10-31
+
+First pre-release, reserving the gem name. A Ruby reimplementation of the design of
+[Neo4j's Cypher-DSL for Java](https://github.com/neo4j/cypher-dsl), built test-first from
+specs translated from its test suite (CypherIT, ProcedureCalls, Subqueries, parameter
+collection, IssueRelatedIT, FunctionsIT).
+
+### Added
+
+- Immutable statement builder with MATCH/OPTIONAL MATCH, WHERE, WITH, RETURN, ORDER BY,
+  SKIP/LIMIT, UNWIND, CREATE, MERGE (ON CREATE/ON MATCH), SET, REMOVE, DELETE, FOREACH,
+  CALL procedures (YIELD, YIELD *), CALL subqueries (imports, IN TRANSACTIONS), LOAD CSV,
+  USE, UNION/UNION ALL, FINISH, EXPLAIN/PROFILE.
+- Patterns: nodes, relationships, chains, named paths, quantified path patterns,
+  path selectors, label expressions.
+- Expressions: literals, parameters, maps, lists, map projections, list and pattern
+  comprehensions, list predicates, CASE, reduce(), EXISTS/COUNT/COLLECT subquery
+  expressions, the built-in function catalogue.
+- Renderer with dialects (Neo4j 4, 5, 5.23+), pretty printing, identifier escaping,
+  parameter collection (`Statement#catalog`).
+
+[Unreleased]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.1...HEAD
+[0.1.0.alpha.1]: https://github.com/neo4jrb/cypher-dsl/releases/tag/v0.1.0.alpha.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heinrich Klobuczek and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,14 @@
+cypher-dsl (Ruby)
+Copyright (c) 2026 Heinrich Klobuczek and contributors
+
+This project is a Ruby implementation of the design of Neo4j's Cypher-DSL for
+Java (https://github.com/neo4j/cypher-dsl), Copyright (c) 2019-2026 "Neo4j,"
+Neo4j Sweden AB, licensed under the Apache License, Version 2.0.
+
+The specifications under spec/ are translated from the Cypher-DSL test suite and
+are therefore a derivative work of that Apache-2.0 licensed code. A copy of the
+Apache License, Version 2.0 is available at
+http://www.apache.org/licenses/LICENSE-2.0.
+
+The Ruby source under lib/ is original work licensed under the MIT License (see
+LICENSE.txt).

data/README.md

@@ -0,0 +1,87 @@
+# cypher-dsl
+
+A Ruby DSL (builder) for the [Cypher](https://neo4j.com/docs/cypher-manual/current/)
+query language, modelled on the design of Neo4j's
+[Cypher-DSL for Java](https://github.com/neo4j/cypher-dsl).
+
+**Status: early development.** The API is being built test-first against
+specifications translated from the Java project's test suite, so rendered
+output is meant to match Cypher-DSL byte for byte.
+
+## Design
+
+- **Immutable AST.** Every builder call returns a new object; a built
+  `Statement` is a frozen tree that can be rendered, inspected or transformed.
+- **Part-aware builder.** Cypher is a linear sequence of parts chained by
+  `WITH`, and clauses keep the order you wrote them. The builder's states
+  mirror which clause may follow which, exactly as the Java `StatementBuilder`
+  does.
+- **Rendering is separate from the tree.** A `Renderer` turns a `Statement` into
+  Cypher text and collects parameters; options such as identifier escaping and
+  pretty printing live in a `Configuration`.
+- **Names follow the Java API in snake_case**, so examples and tests from the
+  Java project translate mechanically:
+
+  ```ruby
+  include CypherDSL
+
+  statement = Cypher.match(Cypher.node('S1').named(:n))
+    .where(Cypher.property(:n, :a).is_equal_to(Cypher.literal_of('A')))
+    .with(:n)
+    .match(Cypher.any_node(:n).relationship_to(Cypher.node('S2').named(:m), 'SOMEHOW_RELATED'))
+    .returning(:n, :m)
+    .build
+
+  statement.cypher
+  # => "MATCH (n:`S1`) WHERE n.a = 'A' WITH n MATCH (n)-[:`SOMEHOW_RELATED`]->(m:`S2`) RETURN n, m"
+  ```
+
+- **No ActiveSupport.** The only runtime dependency is Zeitwerk.
+
+## Parameters
+
+Parameters render as `$name`; give them a value and the statement hands back
+the map a driver needs:
+
+```ruby
+statement = Cypher.match(Cypher.node('User').named(:u))
+  .where(Cypher.property(:u, :name).is_equal_to(Cypher.parameter(:name, 'Neo')))
+  .returning(:u)
+  .build
+
+statement.cypher          # => "MATCH (u:`User`) WHERE u.name = $name RETURN u"
+statement.parameters      # => {"name" => "Neo"}
+statement.parameter_names # => ["name"]
+```
+
+`Cypher.anon_parameter(value)` lets the renderer pick the name (`$pcdsl01`, …).
+Binding one name to two different values raises `ConflictingParametersException`.
+
+## Rendering options
+
+```ruby
+config = Renderer::Configuration.new_config
+  .with_dialect(Renderer::Dialect::NEO4J_4)   # default: NEO4J_5_23
+  .always_escape_names(false)                  # default: true, false when pretty printing
+  .with_pretty_print(true)                     # one clause per line, indented blocks
+  .with_indent_style(:tab)                     # or .with_indent_size(4)
+  .build
+Renderer.get_renderer(config).render(statement)
+Renderer.get_renderer(Renderer::Configuration.pretty_printing).render(statement)
+```
+
+The dialect decides how `CALL { }` subqueries import variables (`CALL (u) { … }`
+from Neo4j 5.23 on, `CALL { WITH u … }` before) and whether `elementId()` exists.
+
+## Installation
+
+```ruby
+gem 'cypher-dsl'
+```
+
+Requires Ruby 3.4 or newer.
+
+## Licence
+
+The Ruby source is MIT licensed (see `LICENSE.txt`). The specifications are
+translated from Cypher-DSL's Apache-2.0 test suite; see `NOTICE`.

data/lib/cypher_dsl/aliased_expression.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `expression AS alias`.
+  class AliasedExpression
+    include Expression
+
+    attr_reader :delegate, :alias_name
+
+    def initialize(delegate, alias_name)
+      @delegate = delegate
+      @alias_name = SymbolicName.of(alias_name)
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/asterisk.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # The `*` in `RETURN *`.
+  class Asterisk
+    include Expression
+
+    INSTANCE = new.freeze
+  end
+end

data/lib/cypher_dsl/case_expression.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `CASE [subject] WHEN condition THEN value … [ELSE default] END`.
+  # Built with `Cypher.case_expression`, `.when(…).then(…)` pairs and `else_default`.
+  class CaseExpression
+    include Expression
+
+    attr_reader :subject, :whens, :default
+
+    def initialize(subject: nil, whens: [], default: nil)
+      @subject = subject
+      @whens = whens.freeze
+      @default = default
+      freeze
+    end
+
+    def when(condition) = OngoingWhen.new(self, Expression.coerce(condition))
+
+    def else_default(default_value) = with(default: Expression.coerce(default_value))
+
+    def with(**changes) = CaseExpression.new(subject:, whens:, default:, **changes)
+
+    # A `WHEN` waiting for its `THEN`.
+    class OngoingWhen
+      def initialize(case_expression, condition)
+        @case_expression = case_expression
+        @condition = condition
+        freeze
+      end
+
+      def then(value)
+        @case_expression.with(whens: @case_expression.whens + [[@condition, Expression.coerce(value)]])
+      end
+    end
+  end
+end

data/lib/cypher_dsl/clauses/call.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `CALL name.parts(arguments) [YIELD items] [WHERE condition]`.
+    Call = Data.define(:name_parts, :arguments, :yield_items, :where)
+  end
+end

data/lib/cypher_dsl/clauses/call_subquery.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `CALL (imports) { body } [IN TRANSACTIONS [OF n ROWS]]`; the body is a
+    # statement or a raw Cypher fragment, `imports` a list of names or the asterisk.
+    CallSubquery = Data.define(:body, :imports, :in_transactions, :rows)
+  end
+end

data/lib/cypher_dsl/clauses/create.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `CREATE pattern, …`.
+    Create = Data.define(:pattern_elements)
+  end
+end

data/lib/cypher_dsl/clauses/delete.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `[DETACH] DELETE expression, …`.
+    Delete = Data.define(:detach, :expressions)
+  end
+end

data/lib/cypher_dsl/clauses/finish.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `FINISH`: terminates a query without returning rows (Neo4j 5.19+).
+    Finish = Data.define
+  end
+end

data/lib/cypher_dsl/clauses/foreach.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `FOREACH (variable IN list | updating clauses)`.
+    Foreach = Data.define(:variable, :list, :clauses)
+  end
+end

data/lib/cypher_dsl/clauses/load_csv.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `LOAD CSV [WITH HEADERS] FROM 'uri' AS alias`.
+    LoadCsv = Data.define(:uri, :with_headers, :alias_name)
+  end
+end

data/lib/cypher_dsl/clauses/match.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `[OPTIONAL] MATCH pattern [WHERE condition]`.
+    Match = Data.define(:optional, :pattern_elements, :where)
+  end
+end

data/lib/cypher_dsl/clauses/merge.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `MERGE pattern [ON CREATE SET …] [ON MATCH SET …]`; actions keep call order.
+    Merge = Data.define(:pattern_elements, :actions)
+  end
+end

data/lib/cypher_dsl/clauses/order.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `ORDER BY item, …`; attached to RETURN or WITH.
+    Order = Data.define(:items)
+  end
+end

data/lib/cypher_dsl/clauses/raw_return.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # Items rendered without the RETURN keyword, for raw fragments that carry their own.
+    RawReturn = Data.define(:items)
+  end
+end

data/lib/cypher_dsl/clauses/remove.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `REMOVE n.prop, n:Label`.
+    Remove = Data.define(:items)
+  end
+end

data/lib/cypher_dsl/clauses/return.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `RETURN [DISTINCT] items [ORDER BY …] [SKIP …] [LIMIT …]`.
+    Return = Data.define(:distinct, :items, :order, :skip, :limit)
+  end
+end

data/lib/cypher_dsl/clauses/set.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `SET n.prop = value, …`.
+    Set = Data.define(:operations)
+  end
+end

data/lib/cypher_dsl/clauses/unwind.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `UNWIND expression AS variable`.
+    Unwind = Data.define(:expression, :variable)
+  end
+end

data/lib/cypher_dsl/clauses/use.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `USE graph`.
+    Use = Data.define(:graph)
+  end
+end

data/lib/cypher_dsl/clauses/with.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # `WITH [DISTINCT] items [ORDER BY …] [SKIP …] [LIMIT …] [WHERE …]`; ends a query part.
+    With = Data.define(:distinct, :items, :order, :skip, :limit, :where)
+  end
+end

data/lib/cypher_dsl/clauses.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Factory methods for clause objects, mirroring the Java `Clauses` class. Most
+  # code goes through the {StatementBuilder}; these exist for building clause
+  # lists by hand, e.g. the body of a FOREACH.
+  module Clauses
+    module_function
+
+    def for_each(variable, list, clauses)
+      Foreach.new(variable: SymbolicName.of(variable), list: Expression.coerce(list), clauses: clauses.freeze)
+    end
+
+    def merge(pattern_elements, actions = [])
+      Merge.new(pattern_elements: pattern_elements.freeze, actions: actions.freeze)
+    end
+
+    def set(operations) = Set.new(operations: operations.freeze)
+    def remove(items) = Remove.new(items: items.freeze)
+
+    def delete(detach, expressions)
+      Delete.new(detach:, expressions: expressions.map { |e| Expression.coerce(e) }.freeze)
+    end
+  end
+end

data/lib/cypher_dsl/collect_expression.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `COLLECT { [WITH imports] statement }`: the statement must end with a RETURN of one column.
+  class CollectExpression
+    include Expression
+
+    MESSAGE = 'The final RETURN clause in a subquery used with COLLECT is mandatory and ' \
+              'the RETURN clause must return exactly one column.'
+
+    attr_reader :statement, :imports
+
+    def initialize(statement, imports = [])
+      raise ArgumentError, MESSAGE unless CollectExpression.single_column?(statement)
+
+      @statement = statement
+      @imports = imports.freeze
+      freeze
+    end
+
+    def self.single_column?(statement)
+      return statement.statements.all? { |inner| single_column?(inner) } if statement.is_a?(UnionQuery)
+
+      last = statement.clauses.last
+      last.is_a?(Clauses::Return) && last.items.size == 1
+    end
+  end
+end

data/lib/cypher_dsl/comparison.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A binary comparison (`a = b`, `a =~ b`, …) or a unary one (`a IS NULL`).
+  class Comparison < Condition
+    attr_reader :left, :operator, :right
+
+    def initialize(left, operator, right)
+      super()
+      @left = left
+      @operator = operator
+      @right = right
+      freeze
+    end
+
+    def unary? = right.nil?
+
+    # Negating a null check flips it instead of wrapping it in NOT.
+    def not
+      case operator
+      when 'IS NULL' then Comparison.new(left, 'IS NOT NULL', nil)
+      when 'IS NOT NULL' then Comparison.new(left, 'IS NULL', nil)
+      else super
+      end
+    end
+  end
+end

data/lib/cypher_dsl/compound_condition.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Conditions joined by AND / OR / XOR, or negated with NOT. Rendered in
+  # parentheses; chaining the same operator flattens into one group and empty
+  # conditions drop out.
+  class CompoundCondition < Condition
+    attr_reader :operator, :conditions
+
+    def self.create(operator, left, right)
+      conditions = [left, right].flat_map do |condition|
+        case condition
+        when NoCondition then []
+        when CompoundCondition then condition.operator == operator ? condition.conditions : [condition]
+        else [condition]
+        end
+      end
+      case conditions.size
+      when 0 then NoCondition::INSTANCE
+      when 1 then conditions.first
+      else new(operator, conditions)
+      end
+    end
+
+    def initialize(operator, conditions)
+      super()
+      @operator = operator
+      @conditions = conditions.freeze
+      freeze
+    end
+
+    def negation? = operator == 'NOT'
+  end
+end

data/lib/cypher_dsl/condition.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Base class of boolean expressions; supports chaining with `and`, `or`, `xor` and `not`.
+  # Relationship patterns are accepted wherever a condition is expected.
+  class Condition
+    include Expression
+
+    def self.coerce(value)
+      case value
+      when Condition then value
+      when Relationship, RelationshipChain then RelationshipPatternCondition.new(value)
+      when FunctionInvocation then ExpressionCondition.new(value) # boolean functions such as isEmpty()
+      else raise ArgumentError, "#{value.inspect} is not a condition"
+      end
+    end
+
+    def and(other) = combine('AND', other)
+    def or(other) = combine('OR', other)
+    def xor(other) = combine('XOR', other)
+    def not = CompoundCondition.new('NOT', [self])
+
+    private
+
+    # Chaining conditions flattens same-operator chains; chaining a relationship
+    # pattern (the Java overload) wraps without flattening, as upstream does.
+    def combine(operator, other)
+      return CompoundCondition.new(operator, [self, Condition.coerce(other)]) if pattern?(other)
+
+      CompoundCondition.create(operator, self, Condition.coerce(other))
+    end
+
+    def pattern?(value) = value.is_a?(Relationship) || value.is_a?(RelationshipChain)
+  end
+end

data/lib/cypher_dsl/conflicting_parameters_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Raised when one parameter name is bound to different values within a
+  # statement, or bound in one place and left unbound in another.
+  class ConflictingParametersException < StandardError
+    # `name => Set` of the conflicting values; an unbound use is {Parameter::NO_VALUE}.
+    attr_reader :erroneous_parameters
+
+    def initialize(erroneous_parameters)
+      @erroneous_parameters = erroneous_parameters.freeze
+      super("Conflicting parameter values for #{erroneous_parameters.keys.join(', ')}")
+    end
+  end
+end

data/lib/cypher_dsl/constant_condition.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # The constant conditions `true` and `false`.
+  class ConstantCondition < Condition
+    attr_reader :value
+
+    def initialize(value)
+      super()
+      @value = value
+      freeze
+    end
+
+    TRUE = new(true)
+    FALSE = new(false)
+  end
+end

data/lib/cypher_dsl/count_expression.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `COUNT { pattern }` / `COUNT { statement }`.
+  class CountExpression
+    include Expression
+
+    attr_reader :body, :imports
+
+    def initialize(body, imports = [])
+      @body = body
+      @imports = imports.freeze
+      freeze
+    end
+  end
+end