activecypher 0.7.2 → 0.8.0

data/lib/cyrel/ast/literal_node.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # Immutable AST node for literal values using Ruby's Data class
+    # Because sometimes you just want to say what you mean, immutably
+    LiteralNode = Data.define(:value) do
+      def accept(visitor)
+        visitor.visit_literal_node(self)
+      end
+
+      def to_ast
+        self
+      end
+
+      # Pattern matching support
+      def deconstruct
+        [value]
+      end
+
+      def deconstruct_keys(_keys)
+        { value: value }
+      end
+
+      # Type inference
+      def inferred_type
+        case value
+        when String then :string
+        when Symbol then :parameter
+        when Integer then :integer
+        when Float then :float
+        when TrueClass, FalseClass then :boolean
+        when NilClass then :null
+        else :unknown
+        end
+      end
+    end
+  end
+end

data/lib/cyrel/ast/load_csv_node.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # AST node for LOAD CSV clause (extension)
+    # For when you need to import data from the ancient format of CSV
+    class LoadCsvNode < ClauseNode
+      attr_reader :url, :variable, :with_headers, :fieldterminator
+
+      def initialize(url, variable, with_headers: false, fieldterminator: nil)
+        @url = url
+        @variable = variable
+        @with_headers = with_headers
+        @fieldterminator = fieldterminator
+      end
+
+      protected
+
+      def state
+        [@url, @variable, @with_headers, @fieldterminator]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/match_node.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # AST node for MATCH and OPTIONAL MATCH clauses
+    # Because finding things in graphs is what we're all about
+    class MatchNode < ClauseNode
+      attr_reader :pattern, :optional, :path_variable
+
+      def initialize(pattern, optional: false, path_variable: nil)
+        @pattern = pattern
+        @optional = optional
+        @path_variable = path_variable
+      end
+
+      protected
+
+      def state
+        [@pattern, @optional, @path_variable]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/merge_node.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # AST node for MERGE clauses
+    # For when you want to find or create, the Schrödinger's cat of graph operations
+    class MergeNode < ClauseNode
+      attr_reader :pattern, :on_create, :on_match
+
+      def initialize(pattern, on_create: nil, on_match: nil)
+        @pattern = pattern
+        @on_create = on_create
+        @on_match = on_match
+      end
+
+      protected
+
+      def state
+        [@pattern, @on_create, @on_match]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/node.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # Base class for all AST nodes
+    # Because every tree needs roots, even if they're just pretending to be organized
+    class Node
+      # Accept a visitor for the visitor pattern
+      # It's like accepting guests, but these guests judge your entire structure
+      def accept(visitor)
+        method_name = "visit_#{self.class.name.demodulize.underscore}"
+        if visitor.respond_to?(method_name)
+          visitor.send(method_name, self)
+        else
+          raise NotImplementedError,
+                "Visitor #{visitor.class} doesn't know how to visit #{self.class}. " \
+                "Did you forget to implement #{method_name}?"
+        end
+      end
+
+      # Equality for testing and debugging
+      # Because sometimes you need to know if two trees fell in the same forest
+      def ==(other)
+        self.class == other.class && state == other.state
+      end
+
+      protected
+
+      # Override in subclasses to define equality state
+      # The essence of what makes this node unique, like a fingerprint but less criminal
+      def state
+        instance_variables.map { |var| instance_variable_get(var) }
+      end
+    end
+  end
+end

data/lib/cyrel/ast/optimized_nodes.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # Optimized nodes using Data for frequently used, simple nodes
+    # These benefit from Data's automatic hash/== and immutability
+
+    # For simple value nodes, Data is perfect
+    module OptimizedNodes
+      # Literal values - these are created frequently and benefit from Data
+      LiteralData = Data.define(:value) do
+        def accept(visitor)
+          visitor.visit_literal_data(self)
+        end
+      end
+
+      # Simple expression nodes that benefit from fast equality
+      PropertyAccessData = Data.define(:variable, :property_name) do
+        def accept(visitor)
+          visitor.visit_property_access_data(self)
+        end
+      end
+
+      # Skip and Limit are perfect for Data - simple, immutable
+      SkipData = Data.define(:expression) do
+        def accept(visitor)
+          visitor.visit_skip_data(self)
+        end
+      end
+
+      LimitData = Data.define(:expression) do
+        def accept(visitor)
+          visitor.visit_limit_data(self)
+        end
+      end
+    end
+
+    # Optimized cache that takes advantage of Data's hash/==
+    class OptimizedCache
+      include Singleton
+
+      def initialize
+        @cache = {}
+        @max_size = 1000
+        @mutex = Mutex.new
+      end
+
+      def fetch(node)
+        # Data objects have reliable hash/== so we can use them directly as keys
+        @mutex.synchronize do
+          if @cache.key?(node)
+            @cache[node]
+          else
+            value = yield
+            store(node, value)
+            value
+          end
+        end
+      end
+
+      private
+
+      def store(node, value)
+        if @cache.size >= @max_size
+          # LRU eviction
+          @cache.shift
+        end
+        @cache[node] = value
+      end
+    end
+
+    # Example of how to use Data nodes effectively
+    class HybridApproach
+      # Use Data for simple, frequently created nodes
+      # Use Classes for complex nodes with behavior
+
+      def self.create_literal(value)
+        # Literals are perfect for Data - immutable, simple
+        OptimizedNodes::LiteralData.new(value)
+      end
+
+      def self.create_match(pattern, optional: false)
+        # Complex nodes with optional parameters stay as classes
+        MatchNode.new(pattern, optional: optional)
+      end
+
+      def self.benchmark_hybrid
+        require 'benchmark'
+
+        n = 10_000
+        puts "\nHybrid Approach Benchmark:"
+        puts '-' * 40
+
+        Benchmark.bm(35) do |x|
+          x.report('Create literals (Class)') do
+            n.times { |i| LiteralNode.new(i) }
+          end
+
+          x.report('Create literals (Data)') do
+            n.times { |i| OptimizedNodes::LiteralData.new(i) }
+          end
+
+          # Cache performance with Data nodes
+          cache = OptimizedCache.instance
+          literals = 100.times.map { |i| OptimizedNodes::LiteralData.new(i) }
+
+          x.report('Cache lookups (Data as key)') do
+            n.times do |i|
+              node = literals[i % 100]
+              cache.fetch(node) { "value_#{i}" }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cyrel/ast/order_by_node.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class OrderByNode < ClauseNode
+      attr_reader :items
+
+      def initialize(items)
+        # items is an array of [expression, direction] pairs
+        # e.g., [[expr1, :asc], [expr2, :desc]]
+        @items = items
+      end
+
+      protected
+
+      def state
+        [@items]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/pattern_node.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # Base class for pattern nodes (nodes, relationships, paths)
+    # Because graphs need patterns like developers need coffee
+    class PatternNode < Node
+    end
+  end
+end

data/lib/cyrel/ast/query_integrated_compiler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # Compiler that integrates with the Query's parameter system
+    # Like a diplomat that speaks both AST and Query fluently
+    class QueryIntegratedCompiler < Compiler
+      attr_reader :query
+
+      def initialize(query)
+        # Store current loop_variables before calling super
+        old_loop_variables = @loop_variables
+        super()
+        @query = query
+        # Restore loop_variables if they were set before initialization
+        @loop_variables = old_loop_variables if old_loop_variables
+      end
+
+      protected
+
+      # Override to use the query's parameter registration
+      def register_parameter(value)
+        @query.register_parameter(value)
+      end
+    end
+  end
+end

data/lib/cyrel/ast/remove_node.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # AST node for REMOVE clauses
+    # For when you need to Marie Kondo your graph properties and labels
+    class RemoveNode < ClauseNode
+      attr_reader :items
+
+      def initialize(items)
+        @items = items
+      end
+
+      protected
+
+      def state
+        [@items]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/return_node.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class ReturnNode < ClauseNode
+      attr_reader :items, :distinct
+
+      def initialize(items, distinct: false)
+        # items is an array of expressions/identifiers to return
+        @items = items
+        @distinct = distinct
+      end
+
+      protected
+
+      def state
+        [@items, @distinct]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/set_node.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class SetNode < ClauseNode
+      attr_reader :assignments
+
+      def initialize(assignments)
+        # assignments is an array of processed assignment tuples
+        @assignments = assignments
+      end
+
+      protected
+
+      def state
+        [@assignments]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/simple_cache.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Cyrel
+  module AST
+    # Simple thread-safe compilation cache
+    # Because compiling the same query twice is like watching reruns
+    class SimpleCache
+      include Singleton
+
+      def initialize
+        @cache = {}
+        @mutex = Mutex.new
+        @max_size = 1000
+      end
+
+      def fetch(key)
+        @mutex.synchronize do
+          if @cache.key?(key)
+            @cache[key]
+          elsif block_given?
+            value = yield
+            store(key, value)
+            value
+          end
+        end
+      end
+
+      def clear!
+        @mutex.synchronize { @cache.clear }
+      end
+
+      def size
+        @mutex.synchronize { @cache.size }
+      end
+
+      private
+
+      def store(key, value)
+        # Simple LRU: remove oldest entries when cache is full
+        if @cache.size >= @max_size
+          # Remove half of the oldest entries
+          (@max_size / 2).times { @cache.shift }
+        end
+        @cache[key] = value
+      end
+    end
+  end
+end

data/lib/cyrel/ast/skip_node.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class SkipNode < ClauseNode
+      attr_reader :amount
+
+      def initialize(amount)
+        @amount = amount
+      end
+
+      protected
+
+      def state
+        [@amount]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/union_node.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    # AST node for UNION and UNION ALL clauses
+    # Because sometimes you need to combine queries like a database DJ
+    class UnionNode < ClauseNode
+      attr_reader :queries, :all
+
+      def initialize(queries, all: false)
+        @queries = queries
+        @all = all
+      end
+
+      protected
+
+      def state
+        [@queries, @all]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/unwind_node.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class UnwindNode < ClauseNode
+      attr_reader :expression, :alias_name
+
+      def initialize(expression, alias_name)
+        @expression = expression
+        @alias_name = alias_name
+      end
+
+      protected
+
+      def state
+        [@expression, @alias_name]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/where_node.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class WhereNode < ClauseNode
+      attr_reader :conditions
+
+      def initialize(conditions)
+        # conditions is an array of expression objects
+        @conditions = conditions
+      end
+
+      protected
+
+      def state
+        [@conditions]
+      end
+    end
+  end
+end

data/lib/cyrel/ast/with_node.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module AST
+    class WithNode < ClauseNode
+      attr_reader :items, :distinct, :where_conditions
+
+      def initialize(items, distinct: false, where_conditions: nil)
+        # items is an array of expressions/identifiers to project
+        @items = items
+        @distinct = distinct
+        # where_conditions can be nil or an array of expressions
+        @where_conditions = where_conditions
+      end
+
+      protected
+
+      def state
+        [@items, @distinct, @where_conditions]
+      end
+    end
+  end
+end

data/lib/cyrel/clause/unwind.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # UNWIND clause for expanding lists into rows
+    # Like unpacking a suitcase, but for data and with less wrinkled clothes
+    class Unwind < Base
+      attr_reader :expression, :variable
+
+      def initialize(expression, variable)
+        @expression = expression
+        @variable = variable.to_sym
+      end
+
+      def render(query)
+        cypher_parts = ['UNWIND']
+
+        # Handle the expression
+        expr_str = case @expression
+                   when Symbol
+                     # It's a parameter
+                     param_key = query.register_parameter(@expression)
+                     "$#{param_key}"
+                   when Array
+                     # Literal array
+                     "[#{@expression.map { |item| render_array_item(item, query) }.join(', ')}]"
+                   when Expression::Base
+                     # It's already an expression
+                     @expression.render(query)
+                   else
+                     # Try to coerce it
+                     Expression.coerce(@expression).render(query)
+                   end
+
+        cypher_parts << expr_str
+        cypher_parts << 'AS'
+        cypher_parts << @variable.to_s
+
+        cypher_parts.join(' ')
+      end
+
+      private
+
+      def render_array_item(item, query)
+        case item
+        when Array
+          # Nested array
+          "[#{item.map { |v| render_value(v, query) }.join(', ')}]"
+        else
+          render_value(item, query)
+        end
+      end
+
+      def render_value(value, query)
+        case value
+        when String
+          "'#{value.gsub("'", "\\\\'")}'"
+        when Symbol
+          # Symbols in arrays should be rendered as strings
+          "'#{value}'"
+        when Numeric, TrueClass, FalseClass, NilClass
+          value.inspect
+        else
+          # For more complex values, treat as parameter
+          param_key = query.register_parameter(value)
+          "$#{param_key}"
+        end
+      end
+    end
+  end
+end

data/lib/cyrel/expression/literal.rb

@@ -18,11 +18,18 @@ module Cyrel
       # @param query [Cyrel::Query] The query object for parameter registration.
       # @return [String] The parameter placeholder string (e.g., "$p1").
       def render(query)
-        # Special handling for NULL as it doesn't use a parameter
+        # nil is special - render as NULL literal, not a parameter
         return 'NULL' if @value.nil?
 
         param_key = query.register_parameter(@value)
-        "$#{param_key}"
+
+        # If the param_key is the same as the value (for loop variables),
+        # don't add the $ prefix - just render as identifier
+        if param_key == @value && @value.is_a?(Symbol)
+          param_key.to_s
+        else
+          "$#{param_key}"
+        end
       end
 
       # Override comparison methods for direct literal comparison if needed,

data/lib/cyrel/expression/property_access.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'cyrel/expression/base'
+require_relative 'base'
 
 module Cyrel
   module Expression

data/lib/cyrel/functions.rb

@@ -18,14 +18,25 @@ module Cyrel
     # --- Common Cypher Functions ---
 
     # Use elementId() instead of deprecated id()
+    # @deprecated Use {#node_id} instead for adapter-aware ID handling
     def element_id(node_variable)
       Expression::FunctionCall.new(:elementId, Clause::Return::RawIdentifier.new(node_variable.to_s))
     end
 
+    # @deprecated Use {#node_id} instead for adapter-aware ID handling
     def id(node_variable)
       Expression::FunctionCall.new(:id, Clause::Return::RawIdentifier.new(node_variable.to_s))
     end
 
+    # Adapter-aware node ID function
+    # Generates a placeholder that will be replaced by the correct ID function
+    # at execution time based on the database adapter (Neo4j vs Memgraph)
+    # Because databases can't agree on how to name their ID functions,
+    # we'll just pretend they're all the same and fix it later
+    def node_id(node_variable)
+      Expression::FunctionCall.new(:__NODE_ID__, Clause::Return::RawIdentifier.new(node_variable.to_s))
+    end
+
     # Because apparently, COUNT(*) isn’t obvious enough.
     # Handles the 'give me everything and make it snappy' use case.
     def count(expression, distinct: false)