activecypher 0.0.0 → 0.2.0

data/lib/cyrel/node.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/string/inflections'
+
+module Cyrel
+  # The base class for building Cypher queries.
+  class Node
+    # @param label [String] The label of the node.
+    # @param as [Symbol, nil] An optional alias for the node.
+    def initialize(label, as: nil)
+      @label = label
+      @alias = as || label.to_s.underscore.to_sym
+      @conditions = {}
+      @raw_conditions = []
+      @related_node_conditions = {}
+      @optional_match = false
+      @return_fields = []
+      @order_clauses = []
+      @skip_value = nil
+      @limit_value = nil
+      @with_clause = nil
+      @where_after_with = nil
+      @remove_props = []
+      @detach_delete = false
+      @path_variable = nil
+    end
+
+    # Adds conditions to the query.
+    # @param conditions [Hash, String] A hash of conditions or a raw condition string to add to the query.
+    def where(conditions)
+      if conditions.is_a?(String)
+        # Process string-based conditions
+        if @with_clause && !@where_after_with.nil?
+          @where_after_with = "#{@where_after_with} AND #{conditions}"
+        elsif @with_clause
+          @where_after_with = conditions
+        else
+          @raw_conditions << conditions
+        end
+      else
+        conditions = conditions.transform_keys(&:to_s)
+        if @outgoing_relationship && @related_node_label
+          @related_node_conditions.merge!(conditions)
+        else
+          @conditions.merge!(conditions)
+        end
+      end
+      self
+    end
+
+    # Match all nodes of this type
+    def all
+      self
+    end
+
+    # Specifies what to return in the query.
+    # Also raises an exception if you try to be too clever—because your cleverness is not welcome here.
+    # @param fields [Array<Symbol, String>] The fields to return.
+    def return(*fields)
+      fields.each do |field|
+        # Skip validation for path variables and variables from subqueries
+        next if field.is_a?(String) && (field == @path_variable.to_s || (field.match(/^\w+$/) && defined_in_query?(field)))
+
+        if field.is_a?(Symbol) || (field.is_a?(String) && !field.include?('.') && !field.include?(' as ') &&
+                                  !field.include?('(') && !field.match(/\[.+\]/))
+          raise StandardError, 'Ambiguous name. Please use a string with alias.'
+        end
+      end
+      @return_fields = fields
+      self
+    end
+
+    # Defines the pattern to MATCH.
+    # Not to be confused with your desperate search for compatibility on dating apps.
+    def match(pattern)
+      @match_pattern = pattern
+      self
+    end
+
+    def set(properties)
+      @set_properties = properties
+      self
+    end
+
+    def create(properties)
+      @create_properties = properties
+      self
+    end
+
+    def merge(properties)
+      @merge_properties = properties
+      self
+    end
+
+    def remove(*properties)
+      @remove_props.concat(properties)
+      self
+    end
+
+    # Schedules the node for DEATH, WITH DETACHMENT.
+    # Cold, clean, and emotionally unavailable. Just like your ex.
+    def detach_delete
+      @detach_delete = true
+      self
+    end
+
+    def order_by(field, direction = :asc)
+      @order_clauses << { field: field, direction: direction }
+      self
+    end
+
+    def skip(amount)
+      @skip_value = amount
+      self
+    end
+
+    def limit(amount)
+      @limit_value = amount
+      self
+    end
+
+    def with(clause)
+      @with_clause = clause
+      self
+    end
+
+    def as_path(path_variable)
+      @path_variable = path_variable
+      self
+    end
+
+    # Builds a WHERE EXISTS subquery.
+    # A fancy way to say, “Does this thing even exist?”—the same question your self-esteem asks daily.
+    def where_exists(&)
+      subquery = self.class.new(@label, as: @alias)
+      subquery.instance_eval(&)
+      pattern = "(#{@alias})"
+
+      if subquery.instance_variable_get(:@outgoing_relationship)
+        rel = subquery.instance_variable_get(:@outgoing_relationship)
+        rel_node_label = subquery.instance_variable_get(:@related_node_label)
+        pattern += "-[:#{rel}]->(:#{rel_node_label})"
+      end
+
+      @raw_conditions << "EXISTS(#{pattern})"
+      self
+    end
+
+    # Invokes a subquery block. Like a Matryoshka of complexity.
+    # Because why write one query when you can write *two* for double the confusion?
+    def call(&)
+      if block_given?
+        subquery = self.class.new(@label, as: @alias)
+        subquery.instance_eval(&)
+        @call_subquery = subquery
+      else
+        # This is for standalone call
+      end
+      self
+    end
+
+    # Specifies an outgoing relationship.
+    # @param relationship [Symbol] The type of relationship.
+    def outgoing(relationship)
+      @outgoing_relationship = relationship
+      self
+    end
+
+    # Specifies an optional outgoing relationship.
+    # It’s not ghosting, it’s just... optional commitment.
+    def optional_outgoing(relationship)
+      @outgoing_relationship = relationship
+      @optional_match = true
+      self
+    end
+
+    # Specifies a related node.
+    # @param label [String] The label of the related node.
+    # @param as [Symbol, nil] An optional alias for the related node.
+    def node(label, as: nil)
+      @related_node_label = label
+      @related_node_alias = as || label.to_s.underscore.to_sym
+      self
+    end
+
+    # This method assembles the final Cypher query like Dr. Frankenstein assembling a monster:
+    # a bit of this, a stitch of that, and screaming at lightning until it runs.
+    # If this explodes, blame the architecture, not the architect.
+    # @return [String] The Cypher query string.
+    def to_cypher
+      parts = []
+
+      # CREATE or MERGE clauses
+      if @create_properties
+        formatted_props = format_properties(@create_properties)
+        parts << "CREATE (#{@alias}:#{@label} {#{formatted_props}})"
+      elsif @merge_properties
+        formatted_props = format_properties(@merge_properties)
+        parts << "MERGE (#{@alias}:#{@label} {#{formatted_props}})"
+      else
+        # Build MATCH clause
+        match_clause = build_match_clause
+        parts << match_clause if match_clause
+      end
+
+      # Add CALL subquery if present
+      if @call_subquery
+        subquery_cypher = @call_subquery.to_cypher
+        # Format for subquery in CALL
+        subquery_cypher = subquery_cypher.gsub(/^MATCH /, '')
+        parts << "CALL { MATCH #{subquery_cypher} }"
+      end
+
+      # WITH clause
+      parts << "WITH #{@with_clause}" if @with_clause
+      parts << "WHERE #{@where_after_with}" if @where_after_with && @with_clause
+
+      # SET clause for property updates
+      if @set_properties
+        set_parts = @set_properties.map { |k, v| "#{@alias}.#{k} = #{format_value(v)}" }
+        parts << "SET #{set_parts.join(', ')}"
+      end
+
+      # REMOVE clause
+      if @remove_props.any?
+        remove_parts = @remove_props.map { |prop| "#{@alias}.#{prop}" }
+        parts << "REMOVE #{remove_parts.join(', ')}"
+      end
+
+      # DETACH DELETE clause
+      parts << "DETACH DELETE #{@alias}" if @detach_delete
+
+      # RETURN clause
+      if @return_fields.any?
+        return_parts = @return_fields.map do |field|
+          if field.is_a?(Symbol)
+            "#{@alias}.#{field}"
+          elsif field.is_a?(String)
+            # Check if it's a path variable
+            if @path_variable && field == @path_variable.to_s
+              field
+            # Check if it might be a variable from a subquery
+            elsif field.match(/^\w+$/) && defined_in_query?(field)
+              field
+            # Handle function calls (prevent node alias prefix on CASE/function keywords)
+            elsif field.start_with?('CASE ') || field.match(/^\w+\s*\(/)
+              field.gsub(' as ', ' AS ')
+            # Handle pattern comprehensions
+            elsif field.match(/\[.+\]/)
+              field.gsub(' as ', ' AS ')
+            # Handle field with alias syntax
+            elsif field.include?(' as ')
+              modified_field = field.gsub(' as ', ' AS ')
+              if modified_field.include?('.')
+                modified_field
+              else
+                "#{@alias}.#{modified_field}"
+              end
+            # Handle field without dot notation
+            elsif !field.include?('.')
+              "#{@alias}.#{field}"
+            else
+              field
+            end
+          else
+            field
+          end
+        end
+        parts << "RETURN #{return_parts.join(', ')}"
+      end
+
+      # ORDER BY clause
+      if @order_clauses.any?
+        order_parts = @order_clauses.map do |clause|
+          "#{@alias}.#{clause[:field]} #{clause[:direction].to_s.upcase}"
+        end
+        parts << "ORDER BY #{order_parts.join(', ')}"
+      end
+
+      # SKIP and LIMIT
+      parts << "SKIP #{@skip_value}" if @skip_value
+      parts << "LIMIT #{@limit_value}" if @limit_value
+
+      parts.join(' ')
+    end
+
+    private
+
+    def defined_in_query?(field)
+      # Check if this is from a subquery's return
+      if @call_subquery
+        subquery_return = @call_subquery.instance_variable_get(:@return_fields)
+        return true if subquery_return.any? do |f|
+          f.is_a?(String) && (f.include?(" as #{field}") || f.include?(" AS #{field}"))
+        end
+      end
+
+      # Check if it's from a WITH clause
+      return true if @with_clause && (@with_clause.include?(" as #{field}") || @with_clause.include?(" AS #{field}"))
+
+      false
+    end
+
+    def build_match_clause
+      return nil if @create_properties || @merge_properties
+
+      # Start building the initial match clause
+      path_prefix = @path_variable ? "#{@path_variable} = " : ''
+      initial_match = "MATCH #{path_prefix}(#{@alias}:#{@label}"
+
+      # Add property conditions
+      if @conditions.any?
+        formatted_conditions = format_properties(@conditions)
+        initial_match += " {#{formatted_conditions}}"
+      end
+      initial_match += ')'
+
+      # Handle relationship clauses
+      if @outgoing_relationship
+        if @optional_match
+          # For optional matches, create a separate OPTIONAL MATCH clause
+          relationship_match = "OPTIONAL MATCH (#{@alias})-[:#{@outgoing_relationship}]->"
+          node_text = "(#{@related_node_alias}:#{@related_node_label}"
+          if @related_node_conditions.any?
+            formatted_conditions = format_properties(@related_node_conditions)
+            node_text += " {#{formatted_conditions}}"
+          end
+          node_text += ')'
+          match_clause = "#{initial_match} #{relationship_match}#{node_text}"
+        else
+          # For regular matches, include the relationship in the initial MATCH
+          relationship_text = "-[:#{@outgoing_relationship}]->"
+          node_text = "(#{@related_node_alias}:#{@related_node_label}"
+          if @related_node_conditions.any?
+            formatted_conditions = format_properties(@related_node_conditions)
+            node_text += " {#{formatted_conditions}}"
+          end
+          node_text += ')'
+          match_clause = initial_match + relationship_text + node_text
+        end
+      else
+        match_clause = initial_match
+      end
+
+      # Add any additional pattern matching
+      match_clause += " #{@match_pattern}" if @match_pattern
+
+      # Add raw WHERE conditions if any
+      if @raw_conditions.any?
+        where_conditions = @raw_conditions.map do |condition|
+          # Process property references in raw conditions
+          processed_condition = condition
+
+          if condition.match(/\w+\s+(CONTAINS|STARTS WITH|ENDS WITH)\s+/)
+            # Special handling for string operations
+            property = condition.match(/(\w+)\s+(CONTAINS|STARTS WITH|ENDS WITH)/)[1]
+            rest = condition.sub(/^\w+\s+/, '')
+            processed_condition = "#{@alias}.#{property} #{rest}"
+          elsif !condition.include?('(') && !condition.include?('[') && !condition.match(/\s(AND|OR|NOT|XOR|IN|IS|NULL|TRUE|FALSE)\s/)
+            # Add node alias to simple property references
+            processed_condition = "#{@alias}.#{condition}"
+          end
+
+          processed_condition
+        end
+        match_clause += " WHERE #{where_conditions.join(' AND ')}"
+      end
+
+      match_clause
+    end
+
+    # Formats properties into Cypher-compatible key-value pairs.
+    # It's like JSON, but with commitment issues and worse syntax.
+    def format_properties(props)
+      props.map do |k, v|
+        if v.is_a?(Array)
+          "#{k} IN #{format_value(v)}"
+        else
+          "#{k}: #{format_value(v)}"
+        end
+      end.join(', ')
+    end
+
+    def format_value(value)
+      case value
+      when String
+        "\"#{value}\""
+      when Array
+        "[#{value.map { |v| format_value(v) }.join(', ')}]"
+      when Hash
+        "{#{format_properties(value)}}"
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/cyrel/parameterizable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'concurrent'
+
+module Cyrel
+  module Parameterizable
+    extend ActiveSupport::Concern
+
+    private
+
+    # Generates the next parameter key.
+    # p1, p2, p3... it’s like a sad carnival of increasingly desperate guesses.
+    def next_param_key
+      @param_counter ||= 0
+      @param_counter += 1
+      :"p#{@param_counter}"
+    end
+  end
+end

data/lib/cyrel/pattern/node.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'active_model' # ships with Rails 8
+require 'active_model/attributes'
+
+module Cyrel
+  module Pattern
+    class Node
+      include ActiveModel::Model
+      include ActiveModel::Attributes # :contentReference[oaicite:3]{index=3}
+      include Cyrel::Parameterizable
+
+      attribute :alias_name, Cyrel::Types::SymbolType.new
+      attribute :labels,     array: :string, default: []
+      attribute :properties, Cyrel::Types::HashType.new, default: -> { {} }
+
+      validates :alias_name, presence: true
+
+      def initialize(alias_name, labels: nil, properties: {}, **kw)
+        super(
+          { alias_name: alias_name,
+            labels: Array(labels).compact.flatten,
+            properties: properties }.merge(kw)
+        )
+      end
+
+      # ------------------------------------------------------------------
+      # Public: return a *copy* of this Node with a different alias.
+      #
+      #   Cyrel.node('Person').as(:p)      # (:p:Person)
+      #
+      # We dup so the original immutable instance (often reused by the DSL)
+      # isn’t mutated.
+      # ------------------------------------------------------------------
+      def as(new_alias)
+        dup_with(alias_name: new_alias.to_sym)
+      end
+
+      def render(query)
+        base = +"(#{alias_name}"
+        base << ':' << labels.join(':') unless labels.empty?
+        unless properties.empty?
+          params = properties.with_indifferent_access
+          formatted = params.map { |k, v| "#{k}: $#{query.register_parameter(v)}" }.join(', ')
+          base << " {#{formatted}}"
+        end
+        base << ')'
+      end
+
+      def freeze
+        super
+        labels.freeze
+        properties.freeze
+      end
+
+      private
+
+      # Utility used by Node & Relationship to make modified copies
+      def dup_with(**attrs)
+        copy = dup
+        attrs.each { |k, v| copy.public_send("#{k}=", v) }
+        copy
+      end
+    end
+  end
+end

data/lib/cyrel/pattern/path.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Pattern
+    # Represents a linear path pattern in a Cypher query,
+    # consisting of an alternating sequence of Node and Relationship objects.
+    class Path
+      attr_reader :elements
+
+      # @param elements [Array<Cyrel::Pattern::Node, Cyrel::Pattern::Relationship>]
+      #   An array starting with a Node, followed by alternating Relationship and Node objects.
+      def initialize(elements)
+        validate_elements(elements)
+        @elements = elements
+      end
+
+      # Renders the path pattern part of the Cypher query.
+      # @param query [Cyrel::Query] The query object, used for parameter registration.
+      # @return [String] The Cypher string fragment for the path pattern.
+      def render(query)
+        @elements.map { |element| element.render(query) }.join
+      end
+
+      private
+
+      # Validates the structure of the elements array.
+      def validate_elements(elements)
+        raise ArgumentError, 'Path elements must be a non-empty array.' unless elements.is_a?(Array) && elements.any?
+        raise ArgumentError, 'Path must start with a Node.' unless elements.first.is_a?(Cyrel::Pattern::Node)
+
+        elements.each_with_index do |element, index|
+          expected_class = (index.even? ? Cyrel::Pattern::Node : Cyrel::Pattern::Relationship)
+          unless element.is_a?(expected_class)
+            raise ArgumentError,
+                  "Invalid element sequence at index #{index}. Expected #{expected_class}, got #{element.class}."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cyrel/pattern/relationship.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../direction'
+
+module Cyrel
+  module Pattern
+    class Relationship
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include Cyrel::Parameterizable
+
+      attribute :alias_name, Cyrel::Types::SymbolType.new, default: nil
+      attribute :types, array: :string, default: []
+      attribute :properties, Cyrel::Types::HashType.new, default: -> { {} }
+      attribute :direction,  default: Cyrel::Direction::BOTH
+      attribute :length
+
+      def initialize(types:, direction: Cyrel::Direction::BOTH, **kw)
+        # Accept string or array for :types just like the old API
+        super({ types: Array(types) }.merge(kw).merge(direction: direction))
+      end
+
+      def render(query)
+        arrow =
+          case direction # Ruby 3.4 pattern match
+          in Direction::OUT  then '->'
+          in Direction::IN   then '<-'
+          else '-'
+          end
+
+        core = +'['
+        core << "#{alias_name} " if alias_name
+        core << ':' << Array(types).join('|') unless types.empty?
+        core << length_spec
+        core << " #{prop_string(query)}" unless properties.empty?
+        core << ']'
+
+        "#{arrow.start_with?('<') ? arrow : '-'}#{core}#{arrow.end_with?('>') ? arrow : '-'}"
+      end
+
+      private
+
+      # Builds the Cypher length fragment after the relationship type.
+      #
+      #     *        ➜ variable length (any)
+      #     *3       ➜ exact length 3
+      #     *1..5    ➜ range 1 – 5
+      #     *1..     ➜ open range start (1 or more)
+      #     *..5     ➜ open range end   (up to 5)
+      def length_spec
+        return '' if length.nil?
+
+        case length
+        when Integer
+          "*#{length}"
+        when Range
+          start  = length.begin   # nil for ..N ranges
+          finish = length.end     # nil for N.. ranges
+
+          "*#{start if start}..#{finish if finish}"
+        else
+          length # already a string like "*" – keep as‑is
+        end
+      end
+
+      def prop_string(query)
+        formatted = properties.to_h.with_indifferent_access.map do |k, v|
+          "#{k}: $#{query.register_parameter(v)}"
+        end.join(', ')
+        "{#{formatted}}"
+      end
+    end
+  end
+end

data/lib/cyrel/pattern.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Cyrel
+  # Namespace for classes representing structural components of Cypher patterns
+  # (nodes, relationships, paths).
+  module Pattern
+  end
+end