cypher-dsl 0.1.0.alpha.1

data/lib/cypher_dsl/list_predicate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # The list predicates `all(x IN list WHERE condition)`, `any(…)`, `none(…)`, `single(…)`.
+  # Built with `Cypher.all(:x).in(list).where(condition)` (or `any`, `none`, `single`).
+  class ListPredicate < Condition
+    attr_reader :predicate, :variable, :list, :condition
+
+    def initialize(predicate, variable, list, condition)
+      super()
+      @predicate = predicate
+      @variable = SymbolicName.of(variable)
+      @list = list
+      @condition = condition
+      freeze
+    end
+
+    # `Cypher.all(:x)`: waiting for `in(list)` and then `where(condition)`.
+    class Ongoing
+      def initialize(predicate, variable, list = nil)
+        @predicate = predicate
+        @variable = variable
+        @list = list
+        freeze
+      end
+
+      def in(list) = Ongoing.new(@predicate, @variable, Expression.coerce(list))
+
+      def where(condition) = ListPredicate.new(@predicate, @variable, @list, Condition.coerce(condition))
+    end
+  end
+end

data/lib/cypher_dsl/literal.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A literal value rendered inline: strings, numbers, booleans, NULL and lists.
+  # Hashes become a {MapExpression}; expressions are returned unchanged.
+  class Literal
+    include Expression
+
+    attr_reader :value
+
+    def self.of(value)
+      case value
+      when Expression then value
+      when Hash then MapExpression.of(value)
+      when Array then ListExpression.of(value)
+      else new(value)
+      end
+    end
+
+    def initialize(value)
+      @value = value.frozen? ? value : value.dup.freeze
+      freeze
+    end
+
+    TRUE = new(true)
+    FALSE = new(false)
+    NULL = new(nil)
+  end
+end

data/lib/cypher_dsl/map_expression.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A map literal such as `{name: 'Alice', age: $age}`. Keys are strings,
+  # values are expressions.
+  class MapExpression
+    include Expression
+
+    attr_reader :entries
+
+    # Accepts a single Hash or alternating keys and values, as `Cypher.map_of` does.
+    def self.of(*keys_and_values)
+      return keys_and_values.first if keys_and_values.size == 1 && keys_and_values.first.is_a?(MapExpression)
+
+      pairs = if keys_and_values.size == 1 && keys_and_values.first.is_a?(Hash)
+                keys_and_values.first.to_a
+              else
+                raise ArgumentError, 'map_of needs an even number of arguments' if keys_and_values.size.odd?
+
+                keys_and_values.each_slice(2).to_a
+              end
+      new(pairs.map { |key, value| [key.to_s, Expression.coerce(value)] })
+    end
+
+    def initialize(entries)
+      @entries = entries.map(&:freeze).freeze
+      freeze
+    end
+
+    def empty? = entries.empty?
+  end
+end

data/lib/cypher_dsl/map_projection.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A map projection `n{.name, .age, total: count(x), .*}`.
+  #
+  # Entries follow the Java rules: a name followed by an expression is a
+  # `key: expression` pair, a lone name is a property lookup `.name`, an
+  # expression on its own is rendered as is, and `Cypher.asterisk` is `.*`.
+  class MapProjection
+    include Expression
+
+    attr_reader :subject, :entries
+
+    def initialize(subject, entries)
+      @subject = subject
+      @entries = MapProjection.parse(entries).freeze
+      freeze
+    end
+
+    def and(*more_entries) = MapProjection.new(subject, entries + more_entries.flatten)
+
+    # Entries already parsed (arrays, from `and`) pass through untouched.
+    def self.parse(raw_entries)
+      entries = []
+      pending_key = nil
+      raw_entries.each do |entry|
+        if pending_key
+          entries << (name?(entry) ? [:lookup, pending_key] : [:pair, pending_key, Expression.coerce(entry)])
+          pending_key = name?(entry) ? entry.to_s : nil
+        elsif name?(entry)
+          pending_key = entry.to_s
+        else
+          entries << parse_expression(entry)
+        end
+      end
+      entries << [:lookup, pending_key] if pending_key
+      entries
+    end
+
+    def self.parse_expression(entry)
+      case entry
+      when Array then entry # already parsed (from `and`)
+      when Asterisk then [:all]
+      when Property
+        raise ArgumentError, 'Cannot project nested properties!' if entry.nested?
+
+        [:property, entry]
+      when AliasedExpression then [:pair, entry.alias_name.value, entry]
+      when SymbolicName, Node, Relationship then [:expression, entry]
+      else
+        raise ArgumentError,
+              "#{entry.inspect} of type #{entry.class} cannot be used with an implicit name as map entry."
+      end
+    end
+
+    def self.name?(entry) = entry.is_a?(String) || entry.is_a?(Symbol)
+  end
+end

data/lib/cypher_dsl/merge_action.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `ON CREATE SET …` / `ON MATCH SET …` attached to a MERGE.
+  MergeAction = Data.define(:type, :operations) do
+    # `MergeAction.of(:on_create, set_clause)`; the type may also be given as `:ON_CREATE`.
+    def self.of(type, set_clause)
+      new(type: type.to_s.downcase.to_sym, operations: set_clause.operations)
+    end
+  end
+end

data/lib/cypher_dsl/named_path.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A named path `p = (a)-[]->(b)`, optionally with a path selector such as
+  # `p = ANY SHORTEST …`. Usable as a pattern element in MATCH and as an
+  # expression (`p`) afterwards. Built with `Cypher.path(:p).defined_by(pattern)`
+  # or `Cypher.any_shortest.named(:p).defined_by(pattern)`.
+  class NamedPath
+    include Expression
+
+    attr_reader :symbolic_name, :pattern, :selector
+
+    def initialize(symbolic_name, pattern, selector: nil)
+      @symbolic_name = symbolic_name
+      @pattern = pattern
+      @selector = selector
+      freeze
+    end
+
+    alias required_symbolic_name symbolic_name
+    alias as_expression symbolic_name
+
+    # `Cypher.path(:p)`: waiting for `defined_by`, or `get` for a bare reference to the name.
+    class Ongoing
+      def initialize(symbolic_name, selector: nil)
+        @symbolic_name = symbolic_name
+        @selector = selector
+        freeze
+      end
+
+      # Defining a path by another named path reuses that path.
+      def defined_by(pattern)
+        return pattern if pattern.is_a?(NamedPath)
+
+        NamedPath.new(@symbolic_name, pattern, selector: @selector)
+      end
+
+      def get = @symbolic_name
+    end
+
+    # `Cypher.any_shortest` and friends: a path selector waiting for `named`.
+    class Selector
+      attr_reader :keyword
+
+      def self.shortest_k(count, groups: false)
+        raise ArgumentError, 'The path count needs to be greater than 0.' unless count.positive?
+
+        new("SHORTEST #{count}#{' GROUPS' if groups}")
+      end
+
+      def initialize(keyword)
+        @keyword = keyword
+        freeze
+      end
+
+      def named(name) = Ongoing.new(SymbolicName.of(name), selector: self)
+    end
+  end
+end

data/lib/cypher_dsl/no_condition.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # The empty condition: it renders nothing and disappears when combined with
+  # another condition, which lets callers build conditions incrementally.
+  class NoCondition < Condition
+    INSTANCE = new.freeze
+
+    def and(other) = Condition.coerce(other)
+    def or(other) = Condition.coerce(other)
+    def xor(other) = Condition.coerce(other)
+    def not = self
+  end
+end

data/lib/cypher_dsl/node.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A node pattern `(name:Label {props} WHERE condition)`. Used as an expression
+  # it stands for its symbolic name.
+  #
+  # Nodes are value objects; the one piece of lazily computed state is the
+  # generated name an unnamed node receives when something references it, as
+  # in the Java `getRequiredSymbolicName`.
+  class Node
+    include Expression
+
+    attr_reader :labels, :properties, :where_condition
+
+    # The explicit name, or the generated one once {#required_symbolic_name} was called.
+    attr_reader :symbolic_name
+
+    def initialize(labels:, symbolic_name: nil, properties: nil, where_condition: nil)
+      @labels = labels.freeze
+      @symbolic_name = symbolic_name
+      @properties = properties
+      @where_condition = where_condition
+    end
+
+    def named(name) = with(symbolic_name: SymbolicName.of(name))
+
+    def with_properties(*keys_and_values) = with(properties: MapExpression.of(*keys_and_values))
+
+    # The inline predicate `(n WHERE condition)`.
+    def where(condition) = with(where_condition: Condition.coerce(condition))
+
+    def named? = !@symbolic_name.nil?
+
+    # The name of this node, generating one if it has none (and keeping it, as in Java).
+    def required_symbolic_name
+      @symbolic_name ||= SymbolicName.unresolved(name_hint) # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+
+    # The first plain label, lower-cased, or `n` for nodes without one.
+    def name_hint = labels.first.is_a?(String) ? labels.first.downcase : 'n'
+    alias as_expression required_symbolic_name
+
+    def property(*names) = Property.new(required_symbolic_name, names)
+
+    # The condition `n:Label`, checking the node for the given labels.
+    def has_labels(*labels) = HasLabelCondition.new(self, labels)
+
+    # `n += {…}` and `n = {…}`, for use in SET.
+    def mutate(expression) = Operation.new(self, '+=', Expression.coerce(expression))
+    def set(expression) = Operation.new(self, '=', Expression.coerce(expression))
+
+    # The map projection `n{…}`, built on the (possibly generated) name.
+    def project(*entries) = MapProjection.new(required_symbolic_name, entries.flatten)
+
+    # `id(n)`; deprecated in Neo4j 5 in favour of {#element_id}, kept for parity.
+    def internal_id = FunctionInvocation.new('id', [required_symbolic_name])
+
+    # `labels(n)`.
+    def labels_function = FunctionInvocation.new('labels', [required_symbolic_name])
+
+    # `elementId(n)`.
+    def element_id = FunctionInvocation.new('elementId', [required_symbolic_name])
+
+    def relationship_to(other, *types) = Relationship.create(self, :ltr, other, types)
+    def relationship_from(other, *types) = Relationship.create(self, :rtl, other, types)
+    def relationship_between(other, *types) = Relationship.create(self, :uni, other, types)
+
+    # `relationship_with(other, Relationship::Direction::LTR, 'TYPE')`: the direction as a value.
+    def relationship_with(other, direction, *types)
+      unless Relationship::Direction::ALL.include?(direction)
+        raise ArgumentError, "Unknown direction #{direction.inspect}, use one of Relationship::Direction"
+      end
+
+      Relationship.create(self, direction, other, types)
+    end
+
+    private
+
+    def with(**changes)
+      Node.new(labels:, symbolic_name: @symbolic_name, properties:, where_condition:, **changes)
+    end
+  end
+end

data/lib/cypher_dsl/operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A binary operation such as `n.x = true` or `a + b`.
+  class Operation
+    include Expression
+
+    attr_reader :left, :operator, :right
+
+    ASSIGNMENTS = ['=', '+='].freeze
+
+    def initialize(left, operator, right)
+      @left = left
+      @operator = operator
+      @right = right
+      freeze
+    end
+
+    # Assignments (`n.p = x`) render bare; arithmetic renders in parentheses.
+    def assignment? = ASSIGNMENTS.include?(operator)
+  end
+end

data/lib/cypher_dsl/parameter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A query parameter, rendered as `$name`, optionally carrying its value.
+  # An anonymous parameter has no name of its own; the renderer assigns
+  # `pcdsl01`, `pcdsl02`, … per statement, sharing a name between anonymous
+  # parameters with equal values.
+  class Parameter
+    include Expression
+
+    NO_VALUE = Object.new.freeze
+
+    attr_reader :name, :value
+
+    def self.anonymous(value) = new(nil, value)
+
+    # A leading `$` in the name is tolerated and dropped.
+    def initialize(name, value = NO_VALUE)
+      @name = name&.to_s&.delete_prefix('$')
+      raise ArgumentError, 'A parameter name must not be empty.' if @name && @name.empty?
+
+      @value = value
+      freeze
+    end
+
+    def with_value(value) = Parameter.new(name, value)
+
+    def anonymous? = name.nil?
+    def value? = !value.equal?(NO_VALUE)
+
+    # Named parameters are equal by name and value, anonymous ones by value.
+    def ==(other)
+      other.is_a?(Parameter) && other.name == name && other.value == value
+    end
+    alias eql? ==
+    def hash = [self.class, name, value].hash
+
+    def to_s = "$#{Renderer::Escaper.escape_parameter_name(name || '?')}"
+  end
+end

data/lib/cypher_dsl/pattern_comprehension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `[pattern WHERE condition | expression]`. Built with `Cypher.list_based_on(pattern)`,
+  # refined with `where`/`and`/`or`, completed with `returning`.
+  class PatternComprehension
+    include Expression
+
+    attr_reader :pattern, :where_condition, :projection
+
+    def initialize(pattern, where_condition: nil, projection: nil)
+      @pattern = pattern
+      @where_condition = where_condition
+      @projection = projection&.freeze
+      freeze
+    end
+
+    def where(condition) = with(where_condition: Condition.coerce(condition))
+
+    def and(condition) = with(where_condition: where_condition.and(condition))
+    def or(condition) = with(where_condition: where_condition.or(condition))
+
+    def returning(*expressions) = with(projection: expressions.flatten.map { |e| Expression.coerce(e) })
+
+    private
+
+    def with(**changes)
+      PatternComprehension.new(pattern, where_condition:, projection:, **changes)
+    end
+  end
+end

data/lib/cypher_dsl/pattern_expression.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A pattern used where an expression is expected, as in `size((a)-->())`:
+  # names already in scope render bare, names not yet seen are dropped.
+  class PatternExpression
+    include Expression
+
+    attr_reader :pattern
+
+    def initialize(pattern)
+      @pattern = pattern
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/property.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A property lookup such as `n.name`, `n.address.city`, or the dynamic `n[$key]`.
+  # Names are strings; an expression as a name renders as an index lookup.
+  class Property
+    include Expression
+
+    attr_reader :container, :names
+
+    def initialize(container, names)
+      @container = container
+      @names = names.map { |name| name.is_a?(Expression) ? name : name.to_s }.freeze
+      raise ArgumentError, 'A property needs at least one name.' if @names.empty?
+
+      freeze
+    end
+
+    def nested? = names.size > 1
+
+    # `n.prop = value`, for use in SET.
+    def to(expression) = Operation.new(self, '=', Expression.coerce(expression))
+  end
+end

data/lib/cypher_dsl/quantified_path_pattern.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A whole path pattern with a quantifier, `((a)-[:X]->(b)){1,3}`, optionally
+  # with an inline WHERE. Built with `relationship.quantify(quantifier)`.
+  #
+  # Quantifiers come from {.interval}, {.plus} and {.star}; a relationship-only
+  # quantifier (`-[:X]->{1,3}`) is applied with `quantify_relationship`.
+  class QuantifiedPathPattern
+    # `{lower,upper}`, `+` or `*`.
+    Quantifier = Data.define(:lower, :upper, :symbol) do
+      def to_cypher = symbol || "{#{lower || 0},#{upper}}"
+    end
+
+    def self.interval(lower, upper)
+      raise ArgumentError, 'Lower bound must be greater than or equal to zero' if lower&.negative?
+      raise ArgumentError, 'Upper bound must be greater than zero' if upper && upper < 1
+      raise ArgumentError, "Upper bound must be greater than or equal to #{lower}" if lower && upper && upper < lower
+
+      Quantifier.new(lower:, upper:, symbol: nil)
+    end
+
+    def self.plus = Quantifier.new(lower: 1, upper: nil, symbol: '+')
+    def self.star = Quantifier.new(lower: 0, upper: nil, symbol: '*')
+
+    attr_reader :pattern, :quantifier, :where_condition
+
+    def initialize(pattern, quantifier, where_condition: nil)
+      @pattern = pattern
+      @quantifier = quantifier
+      @where_condition = where_condition
+      freeze
+    end
+
+    def where(condition) = QuantifiedPathPattern.new(pattern, quantifier, where_condition: Condition.coerce(condition))
+  end
+end

data/lib/cypher_dsl/raw_expression.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A fragment of Cypher text rendered verbatim: the escape hatch, like `Arel.sql`.
+  class RawExpression
+    include Expression
+
+    attr_reader :content
+
+    def initialize(content)
+      @content = content.to_s
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/reduction.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `reduce(accumulator = initial, variable IN list | mapper)`, built step by
+  # step: `Cypher.reduce(:n).in(list).map(acc.add(n)).accumulate_on(acc).with_initial_value_of(0)`.
+  class Reduction
+    include Expression
+
+    attr_reader :variable, :list, :mapper, :accumulator, :initial_value
+
+    def self.of(variable) = Ongoing.new(variable: SymbolicName.of(variable), list: nil, mapper: nil, accumulator: nil)
+
+    def initialize(variable:, list:, mapper:, accumulator:, initial_value:)
+      @variable = variable
+      @list = list
+      @mapper = mapper
+      @accumulator = accumulator
+      @initial_value = initial_value
+      freeze
+    end
+
+    # The intermediate states; `with_initial_value_of` completes the reduction.
+    Ongoing = Data.define(:variable, :list, :mapper, :accumulator) do
+      def in(list) = with(list: Expression.coerce(list))
+      def map(mapper) = with(mapper: Expression.coerce(mapper))
+      def accumulate_on(accumulator) = with(accumulator: Expression.coerce(accumulator))
+
+      def with_initial_value_of(initial_value)
+        Reduction.new(variable:, list:, mapper:, accumulator:, initial_value: Expression.coerce(initial_value))
+      end
+    end
+  end
+end

data/lib/cypher_dsl/relationship.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A relationship pattern between two nodes, `(a)-[r:TYPE*1..3 {props} WHERE …]->{1,3}(b)`.
+  # Used as an expression it stands for its symbolic name.
+  class Relationship
+    include Expression
+
+    # Everything between the brackets plus the direction and a relationship quantifier.
+    Details = Data.define(:types, :symbolic_name, :properties, :min, :max, :unbounded, :where, :quantifier) do
+      def empty?
+        symbolic_name.nil? && types.empty? && properties.nil? && !length? && where.nil?
+      end
+
+      def length? = unbounded || !min.nil? || !max.nil?
+    end
+
+    # The direction of a relationship pattern, for {Node#relationship_with}.
+    module Direction
+      LTR = :ltr
+      RTL = :rtl
+      UNI = :uni
+      ALL = [LTR, RTL, UNI].freeze
+    end
+
+    attr_reader :left, :right, :direction, :details
+
+    def self.create(left, direction, right, types)
+      details = Details.new(types: types.map(&:to_s).freeze, symbolic_name: nil, properties: nil,
+                            min: nil, max: nil, unbounded: false, where: nil, quantifier: nil)
+      new(left, direction, right, details)
+    end
+
+    def initialize(left, direction, right, details)
+      @left = left
+      @direction = direction
+      @right = right
+      @details = details
+      @generated_name = nil
+    end
+
+    # The explicit name, or the generated one once {#required_symbolic_name} was called.
+    def symbolic_name = details.symbolic_name || @generated_name
+
+    def named? = !symbolic_name.nil?
+
+    # The name of this relationship, generating one if it has none.
+    def required_symbolic_name
+      details.symbolic_name || (@generated_name ||= SymbolicName.unresolved(details.types.first&.downcase || 'r'))
+    end
+    alias as_expression required_symbolic_name
+
+    def named(name) = with_details(symbolic_name: SymbolicName.of(name))
+
+    def with_properties(*keys_and_values) = with_details(properties: MapExpression.of(*keys_and_values))
+    alias properties with_properties
+
+    def min(minimum) = with_details(min: minimum)
+    def max(maximum) = with_details(max: maximum)
+    def length(minimum, maximum) = with_details(min: minimum, max: maximum)
+    def unbounded = with_details(unbounded: true)
+
+    # The inline predicate `-[r WHERE condition]->`.
+    def where(condition) = with_details(where: Condition.coerce(condition))
+
+    # `-[:X]->{1,3}`: a quantifier on the relationship only.
+    def quantify_relationship(quantifier) = with_details(quantifier:)
+
+    # `((a)-[:X]->(b)){1,3}`: a quantifier on the whole pattern.
+    def quantify(quantifier) = QuantifiedPathPattern.new(self, quantifier)
+
+    # The pattern as a predicate, `WHERE (a)-[:X]->(b)`.
+    def as_condition = RelationshipPatternCondition.new(self)
+
+    def property(*names) = Property.new(required_symbolic_name, names)
+
+    # `r += {…}` and `r = {…}`, for use in SET.
+    def mutate(expression) = Operation.new(self, '+=', Expression.coerce(expression))
+    def set(expression) = Operation.new(self, '=', Expression.coerce(expression))
+
+    # The map projection `r{…}`, built on the (possibly generated) name.
+    def project(*entries) = MapProjection.new(required_symbolic_name, entries.flatten)
+
+    # `elementId(r)`.
+    def element_id = FunctionInvocation.new('elementId', [required_symbolic_name])
+
+    def relationship_to(other, *types) = RelationshipChain.new([self]).relationship_to(other, *types)
+    def relationship_from(other, *types) = RelationshipChain.new([self]).relationship_from(other, *types)
+    def relationship_between(other, *types) = RelationshipChain.new([self]).relationship_between(other, *types)
+
+    private
+
+    def with_details(**changes)
+      Relationship.new(left, direction, right, details.with(**changes))
+    end
+  end
+end