activecypher 0.0.0 → 0.2.0

data/lib/active_cypher/model/querying.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Querying: The module that lets you pretend your graph is just a really weird table.
+    #   # Because what’s more fun than chaining scopes and pretending you’re not writing Cypher by hand?
+    module Querying
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # -- default label -----------------------------------------------
+        # Returns the symbolic label name for the model, e.g., :user_node
+        # @return [Symbol] The label name for the model
+        def label_name = model_name.element.to_sym
+
+        # -- basic query builders ----------------------------------------
+        # Return a base Relation, applying the default scope if it exists
+        # @return [Relation] The base relation for the model
+        # Because nothing says "default" like a scope you forgot you set.
+        def all
+          relation = Relation.new(self)
+          relation = relation.merge(_default_scope.call(self)) if _default_scope
+          relation
+        end
+
+        # Proxy methods to chain basic query clauses off `all`
+        # @param conditions [Hash, Cyrel::Expression::Base] The conditions for the where clause
+        # @return [Relation]
+        def where(conditions) = all.where(conditions)
+
+        # @param val [Integer] The limit value
+        # @return [Relation]
+        def limit(val)        = all.limit(val)
+
+        # @return [Relation]
+        def order(*)          = all.order(*)
+
+        # -- find / create -----------------------------------------------
+        # Find a node by internal DB ID. Returns the record or dies dramatically.
+        # @param internal_db_id [String] The internal database ID
+        # @return [Object] The found record
+        # @raise [ActiveCypher::RecordNotFound] if not found
+        # Because sometimes you want to find a node, and sometimes you want to find existential dread.
+        def find(internal_db_id)
+          node_alias = :n
+
+          query = Cyrel
+                  .match(Cyrel.node(label_name).as(node_alias))
+                  .where(Cyrel.element_id(node_alias).eq(internal_db_id))
+                  .return_(node_alias, Cyrel.element_id(node_alias).as(:internal_id))
+                  .limit(1)
+
+          Relation.new(self, query).first or
+            raise ActiveCypher::RecordNotFound,
+                  "#{name} with internal_id=#{internal_db_id.inspect} not found"
+        end
+
+        # Instantiates and immediately saves a new record. YOLO mode.
+        # @param attrs [Hash] Attributes for the new record
+        # @return [Object] The new, possibly persisted record
+        # Because sometimes you just want to live dangerously.
+        def create(attrs = {}) = new(attrs).tap(&:save)
+      end
+    end
+  end
+end

data/lib/active_cypher/railtie.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+require 'active_cypher/logging'
+require 'active_cypher/cypher_config'
+
+module ActiveCypher
+  class Railtie < ::Rails::Railtie
+    initializer 'active_cypher.logger' do
+      ActiveSupport.on_load(:active_cypher) do
+        ActiveCypher::Logging.backend = Rails.logger
+
+        # Honour Rails.env level unless the user set AC_LOG_LEVEL
+        ActiveCypher::Logging.backend.level = Rails.logger.level unless ENV['AC_LOG_LEVEL']
+      end
+    end
+
+    initializer 'active_cypher.load_multi_db' do |_app|
+      configs = ActiveCypher::CypherConfig.for('*') # entire merged hash
+      %i[writing reading analytics].each do |role|
+        next unless (cfg = configs[role])
+
+        pool = ActiveCypher::ConnectionPool.new(cfg)
+        ActiveCypher::Base.connection_handler.set(role, :default, pool)
+      end
+    end
+
+    generators do
+      require 'active_cypher/generators/install_generator'
+      require 'active_cypher/generators/node_generator'
+      require 'active_cypher/generators/relationship_generator'
+    end
+  end
+end

data/lib/active_cypher/relation.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+
+module ActiveCypher
+  # Chainable, lazily evaluated Cypher query.
+  # Because what you really want is to pretend your database is just a big Ruby array.
+  class Relation
+    include Enumerable
+
+    attr_reader :model_class, :cyrel_query
+
+    # Methods that trigger query execution
+    # Because nothing says "performance" like loading everything at once.
+    LOAD_METHODS = %i[each to_a first last count size length any? empty?].freeze
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+    # Initializes a Relation. Because direct SQL was too mainstream.
+    # @param model_class [Class] The model class for the relation
+    # @param cyrel_query [Object, nil] The Cyrel query object
+    def initialize(model_class, cyrel_query = nil)
+      @model_class = model_class
+      @cyrel_query = cyrel_query || default_query
+      @records     = nil
+    end
+
+    # ------------------------------------------------------------------
+    # Query‑builder helpers
+    # ------------------------------------------------------------------
+    # Because chaining methods is more fun than writing actual queries.
+    # @param conditions [Hash, Cyrel::Expression::Base] The conditions for the where clause
+    # @return [Relation] A new relation with the where clause applied
+    def where(conditions)
+      new_query = @cyrel_query.clone
+      node_alias = :n
+
+      case conditions
+      when Hash
+        conditions.each do |key, value|
+          expr      = Cyrel.prop(node_alias, key).eq(value)
+          new_query = new_query.where(expr)
+        end
+      when Cyrel::Expression::Base
+        new_query = new_query.where(conditions)
+      else
+        raise ArgumentError,
+              "Unsupported type for #where: #{conditions.class}. " \
+              'Pass a Hash or Cyrel::Expression.'
+      end
+
+      spawn(new_query)
+    end
+
+    # Because sometimes you want less data, but never less abstraction.
+    # @param value [Integer] The limit value
+    # @return [Relation]
+    def limit(value)
+      spawn(@cyrel_query.clone.limit(value))
+    end
+
+    # ORDER support: coming soon, like your next vacation.
+    # @return [Relation]
+    def order(*_args)
+      # TODO: Implement proper ORDER support
+      spawn(@cyrel_query)
+    end
+
+    # Merges another relation, because why not double the confusion.
+    # @param _other [Relation]
+    # @return [Relation]
+    def merge(_other)
+      spawn(@cyrel_query.clone)
+    end
+
+    # ------------------------------------------------------------------
+    # Enumerable / loader
+    # ------------------------------------------------------------------
+    # Pretend this is just an array. Your database will never know.
+    # @yield [record] Yields each record in the relation
+    def each(&)
+      load_records unless loaded?
+      @records.each(&)
+    end
+
+    # Because everyone wants to be first.
+    # @return [Object, nil] The first record
+    def first
+      load_records unless loaded?
+      @records.first
+    end
+
+    # Or last, if you're feeling dramatic.
+    # @return [Object, nil] The last record
+    def last
+      load_records unless loaded?
+      @records.last
+    end
+
+    # Counting records: the only math most devs trust.
+    # @return [Integer] The number of records
+    def count
+      load_records unless loaded?
+      @records.count
+    end
+    alias size   count
+    alias length count
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    # Checks if we've already loaded the records, or if we're still living in denial.
+    # @return [Boolean]
+    def loaded?
+      !@records.nil?
+    end
+
+    # Resets the loaded records, for when you want to pretend nothing ever happened.
+    # @return [void]
+    def reset!
+      @records = nil
+    end
+
+    private
+
+    # Default: MATCH (n:Label) RETURN n, elementId(n) AS internal_id
+    # Because writing Cypher by hand is for people with too much free time.
+    # @return [Object] The default Cyrel query
+    def default_query
+      label      = model_class.model_name.element
+      node_alias = :n
+
+      Cyrel
+        .match(Cyrel.node(label).as(node_alias))
+        .return_(node_alias, Cyrel.element_id(node_alias).as(:internal_id))
+    end
+
+    # Actually loads the records from the database, shattering the illusion of laziness.
+    # @return [void]
+    def load_records
+      cypher, params = @cyrel_query.to_cypher
+      raw            = model_class.connection.execute_cypher(
+        cypher, params || {}, 'Load Relation'
+      )
+      @records = map_results(raw)
+    end
+
+    # Maps raw database results into something you can almost believe is a real object.
+    # @param raw_results [Array<Hash, Array>] The raw results from the database
+    # @return [Array<Object>] The mapped records
+    def map_results(raw_results)
+      raw_results.map do |row|
+        # ------------------------------------------------------------
+        # 1. Pull out the node payload and the elementId string
+        # ------------------------------------------------------------
+        if row.is_a?(Hash)
+          node_payload = row[:n] || row['n'] || row
+          element_id   = row[:internal_id] || row['internal_id']
+        else # Array row: [node, id]
+          node_payload, element_id = row
+        end
+
+        # ------------------------------------------------------------
+        # 2. If the node is still in Bolt array form [78, [...]],
+        #    convert it to { "name"=>"Bob", ... }
+        # ------------------------------------------------------------
+        if node_payload.is_a?(Array) && node_payload.first == 78
+          # Re‑use the adapter's private helper for consistency
+          node_payload = model_class.connection
+                                    .send(:process_node, node_payload)
+        end
+
+        # Now we have a plain hash of properties
+        attrs = node_payload.with_indifferent_access
+        attrs[:internal_id] = element_id if element_id
+        # Use instantiate instead of new to mark records as persisted
+        model_class.instantiate(attrs)
+      end
+    end
+
+    # Spawns a new Relation, because immutability is trendy.
+    # @param new_query [Object] The new Cyrel query
+    # @return [Relation]
+    def spawn(new_query)
+      self.class.new(@model_class, new_query)
+    end
+  end
+end

data/lib/active_cypher/relationship.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# lib/active_cypher/relationship.rb
+# ------------------------------------------------------------------
+#  Graph *edge* model — mirrors ActiveRecord::Base but for Cypher
+#  relationships.
+#
+#  Example:
+#
+#     class WorksAtRelationship < ApplicationGraphRelationship
+#       from_class 'PersonNode'
+#       to_class   'CompanyNode'
+#       type       'WORKS_AT'
+#
+#       attribute :title, :string
+#       attribute :since, :integer
+#     end
+#
+#  Persist with:
+#
+#     WorksAtRelationship.create({title: 'CTO'},
+#                                from_node: person,
+#                                to_node:   company)
+# ------------------------------------------------------------------
+require 'active_model'
+require 'active_support'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module ActiveCypher
+  class Relationship
+    # --------------------------------------------------------------
+    # Mix‑ins
+    # --------------------------------------------------------------
+    include ActiveModel::API
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
+    include ActiveModel::Naming
+
+    include Model::ConnectionOwner
+    include Logging
+    include Model::Abstract
+    include Model::ConnectionHandling
+    include Model::Callbacks
+    include Model::Countable
+
+    # --------------------------------------------------------------
+    # Attributes
+    # --------------------------------------------------------------
+    attribute :internal_id, :string
+
+    # --------------------------------------------------------------
+    # Connection fallback
+    # --------------------------------------------------------------
+    # Relationship classes usually share the same Bolt pool as the
+    # node they originate from; delegate there unless the relationship
+    # class was given its own pool explicitly.
+    #
+    #   WorksAtRelationship.connection  # -> PersonNode.connection
+    #
+    def self.connection
+      return @connection if defined?(@connection) && @connection
+
+      begin
+        from_class.constantize.connection
+      rescue StandardError
+        nil
+      end
+    end
+
+    # --------------------------------------------------------------
+    # DSL helpers
+    # --------------------------------------------------------------
+    class_attribute :_from_class_name,   instance_writer: false
+    class_attribute :_to_class_name,     instance_writer: false
+    class_attribute :_relationship_type, instance_writer: false
+
+    class << self
+      attr_reader :last_internal_id
+
+      # -- endpoints ------------------------------------------------
+      def from_class(value = nil)
+        return _from_class_name if value.nil?
+
+        self._from_class_name = value.to_s
+      end
+      alias from_class_name from_class
+
+      def to_class(value = nil)
+        return _to_class_name if value.nil?
+
+        self._to_class_name = value.to_s
+      end
+      alias to_class_name to_class
+
+      # -- type -----------------------------------------------------
+      def type(value = nil)
+        return _relationship_type if value.nil?
+
+        self._relationship_type = value.to_s.upcase
+      end
+      alias relationship_type type
+
+      # -- factories -----------------------------------------------
+      # Mirrors ActiveRecord.create
+      def create(attrs = {}, from_node:, to_node:)
+        new(attrs, from_node: from_node, to_node: to_node).tap(&:save)
+      end
+
+      # Instantiate from DB row, marking the instance as persisted.
+      def instantiate(attributes, from_node: nil, to_node: nil)
+        instance = allocate
+        instance.send(:init_with_attributes,
+                      attributes,
+                      from_node: from_node,
+                      to_node: to_node)
+        instance
+      end
+    end
+
+    # --------------------------------------------------------------
+    # Life‑cycle
+    # --------------------------------------------------------------
+    attr_accessor :from_node, :to_node
+    attr_reader   :new_record
+
+    def initialize(attrs = {}, from_node: nil, to_node: nil)
+      _run(:initialize) do
+        super()
+        assign_attributes(attrs) if attrs
+        @from_node  = from_node
+        @to_node    = to_node
+        @new_record = true
+        clear_changes_information
+      end
+    end
+
+    def new_record?  = @new_record
+    def persisted?   = !new_record? && internal_id.present?
+    def destroyed?   = @destroyed == true
+
+    # --------------------------------------------------------------
+    # Persistence API
+    # --------------------------------------------------------------
+    def save
+      _run(:save) do
+        if new_record?
+          _run(:create) { create_relationship }
+        else
+          _run(:update) { update_relationship }
+        end
+      end
+    rescue StandardError => e
+      log_error "Failed to save #{self.class}: #{e.class} – #{e.message}"
+      false
+    end
+
+    def destroy
+      _run(:destroy) do
+        raise 'Cannot destroy a new relationship' if new_record?
+        raise 'Relationship already destroyed'    if destroyed?
+
+        cypher = 'MATCH ()-[r]-() WHERE elementId(r) = $id DELETE r'
+        params = { id: internal_id }
+
+        self.class.connection.execute_cypher(cypher, params, 'Destroy Relationship')
+        @destroyed = true
+        freeze
+        true
+      end
+    rescue StandardError => e
+      log_error "Failed to destroy #{self.class}: #{e.class} – #{e.message}"
+      false
+    end
+
+    # --------------------------------------------------------------
+    # Private helpers
+    # --------------------------------------------------------------
+    private
+
+    def create_relationship
+      raise 'Source node must be persisted' unless from_node&.persisted?
+      raise 'Target node must be persisted' unless to_node&.persisted?
+
+      props  = attributes.except('internal_id').compact
+      rel_ty = self.class.relationship_type
+      arrow  = '->' # outgoing by default
+
+      parts  = []
+      parts << 'MATCH (a) WHERE elementId(a) = $from_id'
+      parts << 'MATCH (b) WHERE elementId(b) = $to_id'
+      parts << "CREATE (a)-[r:#{rel_ty}]#{arrow}(b)"
+      parts << 'SET r += $props' unless props.empty? # only if we have props
+      parts << 'RETURN elementId(r) AS rid'
+
+      cypher = parts.join(' ')
+      params = {
+        from_id: from_node.internal_id,
+        to_id: to_node.internal_id,
+        props: props
+      }
+
+      row = self.class.connection.execute_cypher(cypher, params, 'Create Relationship').first
+      rid = row && (row[:rid] || row['rid']) or raise 'Relationship creation returned no id'
+
+      self.internal_id = rid
+      self.class.instance_variable_set(:@last_internal_id, rid)
+      @new_record = false
+      changes_applied
+      true
+    rescue StandardError => e
+      log_error "Failed to save #{self.class}: #{e.class} – #{e.message}"
+      false
+    end
+
+    def update_relationship
+      changes = changes_to_save
+      return true if changes.empty?
+
+      cypher = <<~CYPHER
+        MATCH ()-[r]-() WHERE elementId(r) = $id
+        SET r += $props
+      CYPHER
+      params = { id: internal_id, props: changes }
+
+      self.class.connection.execute_cypher(cypher, params, 'Update Relationship')
+      changes_applied
+      true
+    end
+
+    def changes_to_save = changes.transform_values(&:last)
+  end
+end

data/lib/active_cypher/runtime_registry.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module RuntimeRegistry
+    thread_mattr_accessor :current_role, default: :writing
+    thread_mattr_accessor :current_shard, default: :default
+  end
+end

data/lib/active_cypher/scoping.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module ActiveCypher
+  # Provides scoping capabilities for ActiveCypher models.
+  # Allows defining reusable query constraints as class methods.
+  module Scoping
+    extend ActiveSupport::Concern
+
+    included do
+      # Stores defined scopes { scope_name: lambda }
+      class_attribute :_scopes, instance_accessor: false, default: {}
+      # Stores the default scope lambda
+      class_attribute :_default_scope, instance_accessor: false, default: nil
+    end
+
+    class_methods do
+      # Defines a scope for the model.
+      #
+      # A scope represents a commonly used query constraint that can be chained
+      # like other query methods.
+      #
+      # @param name [Symbol] The name of the scope. This will define a class method
+      #   with the same name.
+      # @param body [Proc] A lambda or proc that implements the scope's logic.
+      #   It will be called with the current relation (or the base model class)
+      #   and any arguments passed to the scope. It should return a Relation.
+      # @param block [Proc] Alternative way to pass the scope body as a block.
+      #
+      # @example
+      #   class User < ActiveCypher::Base
+      #     scope :active, -> { where(status: 'active') }
+      #     scope :created_since, ->(date) { where("n.created_at > $date", date: date) } # Assuming Cyrel supports string conditions
+      #   end
+      #
+      #   User.active.created_since(1.week.ago).to_a
+      #
+      def scope(name, body, &block)
+        name = name.to_sym
+        body = block if block_given?
+
+        raise ArgumentError, 'The scope body needs to be a Proc or lambda.' unless body.is_a?(Proc)
+
+        # Store the scope lambda
+        self._scopes = _scopes.merge(name => body)
+
+        # Define the class method for the scope
+        # This method will apply the scope logic to the current relation or create a new one.
+        define_singleton_method(name) do |*args|
+          # Get the base relation (starts with all records of this model)
+          base_relation = all
+
+          # Execute the scope's lambda. It should return a Relation
+          # containing the specific conditions of the scope.
+          # We pass `self` (the model class) and any arguments.
+          scope_relation = body.call(self, *args)
+
+          unless scope_relation.is_a?(ActiveCypher::Relation)
+            # If the lambda doesn't return a Relation, we might need to handle
+            # merging conditions differently, but for now, enforce returning a Relation.
+            raise ArgumentError, 'Scope body must return an ActiveCypher::Relation.'
+          end
+
+          # Merge the scope's relation into the base relation.
+          # The `merge` method (currently a placeholder) is responsible
+          # for combining the Cyrel queries correctly.
+          base_relation.merge(scope_relation)
+        end
+      end
+
+      # Defines the default scope for the model.
+      #
+      # The default scope is automatically applied to all queries for the model
+      # unless explicitly removed using `unscoped`.
+      #
+      # @param body [Proc] A lambda or proc defining the default scope conditions.
+      #   It should return an ActiveCypher::Relation.
+      # @param block [Proc] Alternative way to pass the scope body as a block.
+      #
+      # @example
+      #   class Post < ActiveCypher::Base
+      #     default_scope -> { where(published: true) }
+      #   end
+      #
+      #   Post.all # Automatically applies `where(published: true)`
+      #
+      def default_scope(body = nil, &block)
+        body = block if block_given?
+
+        raise ArgumentError, 'The default scope body must be a Proc or lambda, or nil to remove.' unless body.nil? || body.is_a?(Proc)
+
+        self._default_scope = body
+      end
+    end
+  end
+end