activecypher 0.0.0 → 0.3.0

data/lib/active_cypher/utils/logger.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'singleton'
+
+module ActiveCypher
+  module Utils
+    # A singleton logger class for ActiveCypher
+    class Logger
+      include Singleton
+
+      attr_accessor :logger
+
+      def initialize
+        @logger = ::Logger.new($stdout)
+        @logger.level = ::Logger::INFO
+        @logger.formatter = self.class.standard_formatter
+      end
+
+      # Configure the logger
+      # @param options [Hash] Configuration options
+      # @option options [IO] :output Where to send logs (default: $stdout)
+      # @option options [Symbol, Integer] :level Log level (default: :info)
+      # @option options [Proc] :formatter Custom formatter for log messages
+      def configure(options = {})
+        @logger = ::Logger.new(options[:output]) if options[:output]
+
+        if options[:level]
+          level = options[:level]
+          level = ::Logger.const_get(level.to_s.upcase) if level.is_a?(Symbol)
+          @logger.level = level
+        end
+
+        @logger.formatter = options[:formatter] if options[:formatter]
+
+        self
+      end
+
+      # Logger delegation methods
+      %i[debug info warn error fatal].each do |level|
+        define_method(level) do |message|
+          @logger.send(level, message)
+        end
+
+        # Define class methods that delegate to the instance
+        define_singleton_method(level) do |message|
+          instance.send(level, message)
+        end
+      end
+
+      # Get the current logger level
+      # @return [Integer] Current log level
+      def level
+        @logger.level
+      end
+
+      # Set the logger level
+      # @param level [Symbol, Integer] The log level
+      def level=(level)
+        level = ::Logger.const_get(level.to_s.upcase) if level.is_a?(Symbol)
+        @logger.level = level
+      end
+
+      # Class methods that delegate to the instance
+      class << self
+        def configure(options = {})
+          instance.configure(options)
+        end
+
+        def level
+          instance.level
+        end
+
+        def level=(level)
+          instance.level = level
+        end
+
+        # Returns a standard formatter with time stamp
+        # @return [Proc] A standard log formatter
+        def standard_formatter
+          proc do |severity, time, _progname, msg|
+            time_str = time.strftime('%H:%M:%S.%L')
+            "[#{time_str}] #{severity}: #{msg}\n"
+          end
+        end
+
+        # Setup with standard configuration for all examples
+        # @return [self]
+        def setup
+          configure(formatter: standard_formatter)
+        end
+      end
+    end
+  end
+end
+
+# Convenience method for accessing the logger
+def logger
+  ActiveCypher::Utils::Logger.instance.logger
+end

data/lib/active_cypher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  VERSION = '0.3.0'
+end

data/lib/activecypher.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'zeitwerk'
+require_relative 'cyrel'
+require_relative 'active_cypher/version'
+
+# ActiveCypher is a Ruby gem that provides an ActiveRecord-like interface for
+# interacting with Neo4j databases using Cypher queries.
+
+module ActiveCypher
+  # Base error class. Rescue this if you're ready to admit something went wrong,
+  # but you're too emotionally unavailable to care what exactly it was.
+  class Error < StandardError; end
+  # For when you configured something wrong.
+  # A gentle reminder that "boot time" is also "blame time."
+  class ConfigurationError < Error; end
+
+  # You tried to use an adapter that doesn’t exist.
+  # It's not ghosting if it was never real to begin with.
+  class AdapterNotFoundError < ConfigurationError; end
+
+  # You found the adapter, but loading it failed.
+  # Like plugging in a toaster and discovering it's full of bees.
+  class AdapterLoadError < ConfigurationError; end
+
+  # You specified an environment that only exists in your imagination.
+  # Not everyone gets to be 'production', Brad.
+  class UnknownEnvironmentError < ConfigurationError; end
+
+  # The connection string is a lie.
+  # It promised connectivity. It delivered chaos.
+  class UnknownConnectionError < ConfigurationError; end
+
+  # Something went wrong in the connection layer.
+  # Possibly sabotage. Possibly just your code.
+  class ConnectionError < Error; end
+
+  # You never established a connection, and yet here you are—
+  # trying to ask the database for stuff like it owes you rent.
+  class ConnectionNotEstablished < ConnectionError; end
+
+  # The connection timed out. The database waited. It hoped. It gave up.
+  class ConnectionTimeoutError < ConnectionError; end
+
+  # The protocol is broken. Not socially — technically.
+  # Although, honestly, maybe both.
+  class ProtocolError < ConnectionError; end
+
+  # Something exploded during a query.
+  # Could be you. Could be Cypher. Could be fate.
+  class QueryError < Error; end
+
+  # Your Cypher syntax is... interpretive.
+  # Unfortunately, the parser isn’t in the mood for interpretive dance.
+  class CypherSyntaxError < QueryError; end
+
+  # The record you tried to find doesn’t exist.
+  # It heard you were coming and left.
+  class RecordNotFound < QueryError; end
+
+  # Your transaction failed to commit.
+  # So did your hopes and dreams.
+  class TransactionError < QueryError; end
+
+  # Persistence went wrong.
+  # The data tried to stay, but it just couldn't handle the pressure.
+  class PersistenceError < Error; end
+
+  # You tried to save a record, but it ghosted you mid-write.
+  class RecordNotSaved < PersistenceError; end
+
+  # You tried to destroy a record, but it clung to life.
+  # Congratulations. You discovered data with survival instincts.
+  class RecordNotDestroyed < PersistenceError; end
+
+  # Something failed validation.
+  # Probably your logic. Possibly your entire existence.
+  class ValidationError < PersistenceError; end
+
+  # You tried to instantiate an abstract class.
+  # That’s not just bad practice—it’s metaphysically wrong.
+  class AbstractClassError < PersistenceError; end
+
+  # Something went wrong with an association.
+  # Relationships are hard—even for nodes.
+  class AssociationError < Error; end
+
+  # You associated two things that really shouldn’t be talking.
+  # Stop trying to make fetch happen.
+  class AssociationTypeMismatch < AssociationError; end
+
+  # You messed up a has_many :through.
+  # Welcome to the Bermuda Triangle of ORM logic.
+  class HasManyThroughError < AssociationError; end
+end
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/active_cypher/version.rb")
+loader.ignore("#{__dir__}/active_cypher/railtie.rb")
+loader.ignore("#{__dir__}/active_cypher/generators")
+loader.ignore("#{__dir__}/activecypher.rb")
+loader.ignore("#{__dir__}/cyrel.rb")
+loader.inflector.inflect('activecypher' => 'ActiveCypher')
+loader.push_dir("#{__dir__}/cyrel", namespace: Cyrel)
+loader.setup
+
+require 'active_cypher/railtie' if defined?(Rails)

data/lib/cyrel/call_procedure.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Cyrel
+  # Class for handling CALL procedures
+  class CallProcedure
+    def initialize(procedure)
+      @procedure = procedure
+      @yield_fields = []
+      @return_fields = []
+    end
+
+    def yield(*fields)
+      @yield_fields = fields
+      self
+    end
+
+    def return(*fields)
+      @return_fields = fields
+      self
+    end
+
+    def to_cypher
+      parts = ["CALL #{@procedure}()"]
+      parts << "YIELD #{@yield_fields.join(', ')}" if @yield_fields.any?
+      parts << "RETURN #{@return_fields.join(', ')}" if @return_fields.any?
+      parts.join(' ')
+    end
+  end
+end

data/lib/cyrel/clause/call.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a standalone CALL procedure clause.
+    # Example: CALL db.labels() YIELD label WHERE label STARTS WITH 'X' RETURN label
+    class Call < Base
+      attr_reader :procedure_name, :arguments, :yield_items, :where_clause, :return_clause
+
+      # @param procedure_name [String] The name of the procedure (e.g., "db.labels").
+      # @param arguments [Array] Arguments to pass to the procedure (will be parameterized).
+      # @param yield_items [Array<String>, String, nil] Raw string(s) for the YIELD part (e.g., "label", ["id", "name AS nodeName"]).
+      # @param where_clause [Cyrel::Clause::Where, nil] Optional WHERE clause applied after YIELD.
+      # @param return_clause [Cyrel::Clause::Return, nil] Optional RETURN clause applied after WHERE/YIELD.
+      def initialize(procedure_name, arguments: [], yield_items: nil, where: nil, return_items: nil)
+        @procedure_name = procedure_name
+        @arguments = arguments # Store raw arguments, parameterize during render
+        @yield_items = yield_items ? Array(yield_items).join(', ') : nil # Simple string join for now
+
+        @where_clause = case where
+                        when Clause::Where then where
+                        when nil then nil
+                        else Clause::Where.new(*Array(where)) # Coerce Hash/Array/Expression
+                        end
+
+        @return_clause = case return_items
+                         when Clause::Return then return_items
+                         when nil then nil
+                         else Clause::Return.new(*Array(return_items))
+                         end
+      end
+
+      def render(query)
+        rendered_args = @arguments.map { |arg| Expression.coerce(arg).render(query) }.join(', ')
+        call_part = "CALL #{@procedure_name}(#{rendered_args})"
+        yield_part = @yield_items ? " YIELD #{@yield_items}" : ''
+        where_part = @where_clause ? " #{@where_clause.render(query)}" : '' # Render WHERE clause
+        return_part = @return_clause ? " #{@return_clause.render(query)}" : '' # Render RETURN clause
+
+        # Ensure correct ordering and spacing
+        parts = [call_part, yield_part, where_part, return_part]
+        parts.compact.reject(&:empty?).join # Join non-empty parts without extra spaces
+      end
+    end
+  end
+end

data/lib/cyrel/clause/call_subquery.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a CALL { subquery } clause.
+    class CallSubquery < Base
+      attr_reader :subquery
+
+      # @param subquery [Cyrel::Query] The nested query object.
+      def initialize(subquery)
+        super() # Call super for Base initialization
+        raise ArgumentError, "Subquery must be a Cyrel::Query instance, got #{subquery.class}" unless subquery.is_a?(Cyrel::Query)
+
+        @subquery = subquery
+      end
+
+      # Renders the CALL { subquery } clause.
+      # Note: Parameter merging between outer and inner queries needs careful handling.
+      # This basic implementation assumes parameters are managed separately or
+      # the outer query's #merge! handles parameter transfer if the subquery
+      # was built and then passed in.
+      # @param _outer_query [Cyrel::Query] The outer query object (potentially needed for parameter context).
+      # @return [String] The Cypher string fragment for the clause.
+      def render(_outer_query)
+        # We need the subquery's cypher string and parameters.
+        # Parameters from the subquery need to be merged into the outer query.
+        # This is complex. For now, let's assume parameters are handled externally
+        # or the subquery doesn't introduce new parameters conflicting with the outer scope.
+        # A more robust solution would involve the outer query managing all parameters.
+
+        sub_cypher, _sub_params = @subquery.to_cypher
+
+        indented_sub_cypher = sub_cypher.gsub(/^/, '  ') # Indent subquery
+        "CALL {\n#{indented_sub_cypher}\n}" # Construct final string
+
+        # Return final string
+      end
+    end
+  end
+end

data/lib/cyrel/clause/create.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a CREATE clause in a Cypher query.
+    class Create < Base
+      attr_reader :pattern
+
+      # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
+      #   The pattern to create. Typically a Path or Node.
+      def initialize(pattern)
+        # Ensure pattern is a valid type for CREATE
+        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
+          raise ArgumentError,
+                "CREATE pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
+        end
+
+        # NOTE: Creating relationships between existing nodes requires coordination.
+        # The pattern itself should reference existing aliases defined in a preceding MATCH/MERGE.
+        # The Query object might need to track defined aliases if validation is needed here.
+        @pattern = pattern
+      end
+
+      # Renders the CREATE clause.
+      # @param query [Cyrel::Query] The query object for rendering the pattern.
+      # @return [String] The Cypher string fragment for the clause.
+      def render(query)
+        pattern_string = @pattern.render(query)
+        "CREATE #{pattern_string}"
+      end
+    end
+  end
+end

data/lib/cyrel/clause/delete.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a DELETE or DETACH DELETE clause in a Cypher query.
+    class Delete < Base
+      attr_reader :variables, :detach
+
+      # Initializes a DELETE clause.
+      # @param variables [Array<Symbol, String>] An array of variable names (aliases) to delete.
+      # @param detach [Boolean] Whether to use DETACH DELETE.
+      def initialize(*variables, detach: false)
+        @variables = variables.flatten.map(&:to_sym)
+        @detach = detach
+        raise ArgumentError, 'DELETE clause requires at least one variable.' if @variables.empty?
+      end
+
+      # Renders the DELETE or DETACH DELETE clause.
+      # @param _query [Cyrel::Query] The query object (unused for DELETE).
+      # @return [String] The Cypher string fragment for the clause.
+      def render(_query)
+        keyword = @detach ? 'DETACH DELETE' : 'DELETE'
+        variable_list = @variables.join(', ')
+        "#{keyword} #{variable_list}"
+      end
+
+      # Merges variables from another Delete clause.
+      # Note: Merging DETACH and non-DETACH might require specific rules.
+      # This implementation simply combines variables and uses the `detach`
+      # status of the clause being merged into. A more robust implementation
+      # might raise an error or prioritize DETACH if either is true.
+      # @param other_delete [Cyrel::Clause::Delete] The other Delete clause to merge.
+      def merge!(other_delete)
+        @variables.concat(other_delete.variables).uniq!
+        # Decide on detach status - let's prioritize detach=true if either has it
+        @detach ||= other_delete.detach
+        self
+      end
+    end
+  end
+end

data/lib/cyrel/clause/limit.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a LIMIT clause in a Cypher query.
+    class Limit < Base
+      attr_reader :amount
+
+      # Initializes a LIMIT clause.
+      # @param amount [Integer, Cyrel::Expression::Base, Object]
+      #   The maximum number of results to return. Can be an integer literal or an expression
+      #   that evaluates to an integer (typically a parameter).
+      def initialize(amount)
+        @amount = Expression.coerce(amount)
+        # Could add validation here.
+      end
+
+      # Renders the LIMIT clause.
+      # @param query [Cyrel::Query] The query object for rendering the amount expression.
+      # @return [String] The Cypher string fragment for the clause.
+      def render(query)
+        "LIMIT #{@amount.render(query)}"
+      end
+
+      # Merging LIMIT typically replaces the existing value.
+      # @param other_limit [Cyrel::Clause::Limit] The other Limit clause.
+      def replace!(other_limit)
+        @amount = other_limit.amount
+        self
+      end
+    end
+  end
+end

data/lib/cyrel/clause/match.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a MATCH or OPTIONAL MATCH clause in a Cypher query.
+    class Match < Base
+      attr_reader :pattern, :optional, :path_variable
+
+      # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
+      #   The pattern to match. Typically a Path, but could be a single Node for simple matches.
+      # @param optional [Boolean] Whether this is an OPTIONAL MATCH.
+      # @param path_variable [Symbol, String, nil] An optional variable to assign to the matched path.
+      def initialize(pattern, optional: false, path_variable: nil)
+        super() # Call super for Base initialization
+        # Ensure pattern is a valid type
+        unless pattern.is_a?(Cyrel::Pattern::Path) ||
+               pattern.is_a?(Cyrel::Pattern::Node) ||
+               pattern.is_a?(Cyrel::Pattern::Relationship)
+          raise ArgumentError,
+                "Match pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
+        end
+
+        @pattern = pattern
+        @optional = optional
+        @path_variable = path_variable&.to_sym
+      end
+
+      # Renders the MATCH or OPTIONAL MATCH clause.
+      # @param query [Cyrel::Query] The query object for rendering the pattern.
+      # @return [String] The Cypher string fragment for the clause.
+      def render(query)
+        keyword = @optional ? 'OPTIONAL MATCH' : 'MATCH'
+        path_assignment = @path_variable ? "#{@path_variable} = " : ''
+        pattern_string = @pattern.render(query)
+
+        "#{keyword} #{path_assignment}#{pattern_string}"
+      end
+    end
+  end
+end

data/lib/cyrel/clause/merge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a MERGE clause in a Cypher query.
+    # Used to find a pattern or create it if it doesn't exist.
+    class Merge < Base
+      attr_reader :pattern
+
+      # TODO: Add support for ON CREATE SET and ON MATCH SET if needed later.
+
+      # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
+      #   The pattern to merge. Typically a Path or Node.
+      def initialize(pattern)
+        # Ensure pattern is a valid type for MERGE
+        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
+          raise ArgumentError,
+                "MERGE pattern must be a Cyrel::Pattern::Path, Node, or Relationship, got #{pattern.class}"
+        end
+
+        @pattern = pattern
+      end
+
+      # Renders the MERGE clause.
+      # @param query [Cyrel::Query] The query object for rendering the pattern.
+      # @return [String] The Cypher string fragment for the clause.
+      def render(query)
+        pattern_string = @pattern.render(query)
+        "MERGE #{pattern_string}"
+        # TODO: Append ON CREATE SET / ON MATCH SET rendering when implemented.
+      end
+    end
+  end
+end

data/lib/cyrel/clause/order_by.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents an ORDER BY clause in a Cypher query.
+    class OrderBy < Base
+      attr_reader :order_items
+
+      # Initializes an ORDER BY clause.
+      # @param order_items [Array<Array>]
+      #   An array of arrays, where each inner array contains:
+      #   [expression, direction]
+      #   - expression: The expression to order by (coerced).
+      #   - direction: :asc or :desc (Symbol or String).
+      #   e.g., [[Cyrel.prop(:n, :age), :desc], ["name", :asc]]
+      def initialize(*order_items)
+        @order_items = process_items(order_items) # Process the array of pairs directly
+        raise ArgumentError, 'ORDER BY clause requires at least one order item.' if @order_items.empty?
+      end
+
+      # Renders the ORDER BY clause.
+      # @param query [Cyrel::Query] The query object for rendering expressions.
+      # @return [String] The Cypher string fragment for the clause.
+      def render(query)
+        rendered_items = @order_items.map do |item|
+          expression, direction = item
+          rendered_expr = render_expression(expression, query)
+          "#{rendered_expr} #{direction.to_s.upcase}"
+        end.join(', ')
+
+        "ORDER BY #{rendered_items}"
+      end
+
+      # Merging ORDER BY typically replaces the existing order.
+      # @param other_order_by [Cyrel::Clause::OrderBy] The other OrderBy clause.
+      def replace!(other_order_by)
+        @order_items = other_order_by.order_items
+        self
+      end
+
+      private
+
+      def process_items(items)
+        items.map do |item|
+          unless item.is_a?(Array) && item.length == 2
+            raise ArgumentError, "Invalid ORDER BY item format. Expected [expression, :asc/:desc], got #{item.inspect}"
+          end
+
+          expression, direction = item
+          dir_sym = direction.to_s.downcase.to_sym
+          raise ArgumentError, "Invalid ORDER BY direction: #{direction}. Use :asc or :desc." unless %i[asc desc].include?(dir_sym)
+
+          [process_expression(expression), dir_sym]
+        end
+      end
+
+      # Handles coercing the expression part of an order item.
+      def process_expression(expression)
+        case expression
+        when Expression::Base
+          expression
+        when Symbol, String
+          # Assume variable or simple property access string
+          Return::RawIdentifier.new(expression.to_s) # Reuse from Return
+        else
+          Expression.coerce(expression)
+        end
+      end
+
+      # Renders the expression part of an order item.
+      def render_expression(expression, query)
+        if expression.is_a?(Return::RawIdentifier)
+        end
+        expression.render(query)
+      end
+    end
+  end
+end

data/lib/cyrel/clause/remove.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Clause
+    # Represents a REMOVE clause in a Cypher query.
+    # Used for removing properties or labels from nodes/relationships.
+    class Remove < Base
+      attr_reader :items
+
+      # Initializes a REMOVE clause.
+      # @param items [Array<Cyrel::Expression::PropertyAccess, Array>]
+      #   An array containing items to remove:
+      #   - PropertyAccess objects: e.g., Cyrel.prop(:n, :age)
+      #   - Label specifications: e.g., [:n, "OldLabel"]
+      # @param items [Array<Cyrel::Expression::PropertyAccess, Array>] The items to remove.
+      def initialize(items)
+        @items = process_items(items) # Remove flatten, expect correct array structure
+      end
+
+      # Renders the REMOVE clause.
+      # @param query [Cyrel::Query] The query object (used for rendering property access if needed, though unlikely).
+      # @return [String, nil] The Cypher string fragment, or nil if no items to remove.
+      def render(query)
+        return nil if @items.empty?
+
+        remove_parts = @items.map do |item|
+          render_item(item, query)
+        end
+
+        "REMOVE #{remove_parts.join(', ')}"
+      end
+
+      # Merges items from another Remove clause.
+      # @param other_remove [Cyrel::Clause::Remove] The other Remove clause to merge.
+      def merge!(other_remove)
+        # Simple concatenation, assumes no duplicate removals.
+        @items.concat(other_remove.items)
+        self
+      end
+
+      private
+
+      def process_items(items)
+        items.map do |item|
+          case item
+          when Expression::PropertyAccess
+            # Remove property: n.prop
+            [:property, item]
+          when Array
+            unless item.length == 2 && item[0].is_a?(Symbol) && item[1].is_a?(String)
+              raise ArgumentError, "Invalid label removal format. Expected [:variable, 'Label'], got #{item.inspect}"
+            end
+
+            # Remove label: n:Label
+            [:label, item[0], item[1]]
+          else
+            raise ArgumentError, "Invalid item type for REMOVE clause: #{item.class}"
+          end
+        end
+      end
+
+      def render_item(item, query)
+        type, target, value = item
+        case type
+        when :property
+          # target is PropertyAccess
+          target.render(query) # Renders as "variable.property"
+        when :label
+          # target is variable symbol, value is label string
+          "#{target}:#{value}" # Labels are not parameterized
+        end
+      end
+    end
+  end
+end