activecypher 0.0.0 → 0.3.0

data/lib/active_cypher/model/abstract.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Adds `self.abstract_class = true` support, mimicking ActiveRecord’s
+# approach to abstract base classes. No runtime enforcement—just vibes,
+# a sprinkle of Ruby sorcery, and the hope you know what you're doing.
+# Because nothing says "enterprise" like a flag that means "please ignore me."
+#
+# This module gives every subclass an `abstract_class` boolean,
+# along with the `abstract_class?` reader. You can assign this flag
+# in your base class to signal “do not instantiate me,” like a digital
+# “Do Not Resuscitate” order. It's the ORM equivalent of a velvet rope at a nightclub,
+# or a protective circle against accidental instantiation.
+#
+# === Example
+#
+#   class ApplicationGraphNode < ActiveCypher::Base
+#     self.abstract_class = true
+#   end
+#
+#   class PersonNode < ApplicationGraphNode
+#     attribute :name, :string
+#   end
+#
+#   ApplicationGraphNode.abstract_class?  # => true
+#   PersonNode.abstract_class?            # => false
+#
+# Querying an abstract class will raise a runtime error—
+# eventually. Maybe. Down in the adapter layer where your dreams go to die.
+# Or at least where your stacktraces go to get longer. If only you had a talisman
+# against such errors—perhaps.
+#
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Adds support for marking a class as abstract, so you can feel important and uninstantiable.
+    #   # No runtime enforcement—just vibes, a dash of Ruby witchcraft, and the hope you know what you're doing.
+    #   # It's the ORM equivalent of a velvet rope at a nightclub, or a magical ward against instantiation.
+    module Abstract
+      extend ActiveSupport::Concern
+
+      included do
+        # Define a per-class flag for abstract status.
+        # Default is false, because chaos is opt-in.
+        class_attribute :abstract_class, instance_accessor: false, default: false
+
+        # Ensure subclasses are born concrete unless they say otherwise.
+        # Because every child deserves a chance to disappoint you in its own way.
+        # This is the Ruby equivalent of breaking the circle and letting the spirits loose.
+        def self.inherited(subclass)
+          super
+          subclass.abstract_class = false
+        end
+      end
+
+      class_methods do
+        # Sets whether this class is abstract.
+        #
+        # @param value [Boolean] true to mark the class as abstract.
+        # @return [void]
+        def abstract_class=(value)
+          self.abstract_class = !!value
+        end
+
+        # Checks if this class is abstract.
+        #
+        # @return [Boolean] true if the class is abstract.
+        def abstract_class? = abstract_class
+
+        # Override query methods to raise if called on an abstract class.
+        # Because nothing says “don’t do that” like a runtime exception.
+        # It's like a velvet rope for your ORM: "Sorry, you're not on the list."
+        # If you try to cross this boundary, beware: you may awaken ancient bugs
+        %i[all where limit order].each do |method|
+          undef_method method if method_defined?(method)
+          define_method(method) do |*args, **kw|
+            if abstract_class?
+              raise ActiveCypher::AbstractClassError,
+                    "#{name} is abstract; `.#{method}` is not allowed. (But hey, at least you tried. Next time, bring a spellbook.)"
+            end
+
+            super(*args, **kw)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/model/attributes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Attributes: Because every model needs a place to store its baggage.
+    #   # Provides helpers for attribute persistence, so you can pretend your data is tidy.
+    #   # Also, because every good ORM needs a little bit of witchcraft to make things “just work.”
+    #   # If you see something working and can't explain why, it's probably quantum Ruby entanglement.
+    module Attributes
+      extend ActiveSupport::Concern
+
+      # Helpers
+      private
+
+      # Returns the attributes to be persisted, minus the internal_id.
+      # Because sometimes you just want to forget where you came from.
+      # @return [Hash] The attributes suitable for persistence
+      def attributes_for_persistence
+        attributes.except('internal_id').compact
+      end
+    end
+  end
+end

data/lib/active_cypher/model/callbacks.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  # <= matches your other concerns
+  module Model
+    # @!parse
+    #   # Model::Callbacks provides lifecycle hooks for your models, so you can pretend you have control over what happens and when.
+    #   # Because nothing says "enterprise" like a callback firing at just the wrong moment.
+    #   # Under the hood, it’s all just a little bit of Ruby sorcery, callback witchcraft, and the occasional forbidden incantation from the callback crypt.
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      EVENTS = %i[
+        initialize find validate create update save destroy
+      ].freeze
+
+      included do
+        include ActiveSupport::Callbacks
+        define_callbacks(*EVENTS)
+      end
+
+      class_methods do
+        %i[before after around].each do |kind|
+          EVENTS.each do |evt|
+            define_method("#{kind}_#{evt}") do |*filters, &block|
+              # This is where the callback coven gathers to cast their hooks.
+              set_callback(evt, kind, *filters, &block)
+            end
+          end
+        end
+      end
+
+      private
+
+      # Thin wrapper so models can do `_run(:create) { … }`
+      # Because sometimes you want to feel like you’re orchestrating fate.
+      # @param evt [Symbol] The callback event
+      # @yield Runs inside the callback chain
+      # @return [Object] The result of the block
+      # Warning: This method may summon side effects from the shadow realm, or just invoke a little callback necromancy when you least expect it.
+      def _run(evt) = run_callbacks(evt) { yield if block_given? }
+    end
+  end
+end

data/lib/active_cypher/model/connection_handling.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # Handles connection logic for models, because every ORM needs a way to feel connected.
+    # @note All real connection magic is just Ruby sorcery, a dash of forbidden Ruby incantations, and a sprinkle of ActiveSupport witchcraft.
+    module ConnectionHandling
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Establishes a connection for the model.
+        # Because every model deserves a shot at disappointment.
+        # @note Under the hood, this is just Ruby sorcery and a little forbidden Ruby wizardry to make your config work.
+        def establish_connection(config)
+          cfg = config.symbolize_keys
+
+          # Handle both URL-based and traditional config
+          if cfg[:url]
+            # Use ConnectionUrlResolver for URL-based config
+            resolver = ActiveCypher::ConnectionUrlResolver.new(cfg[:url])
+            resolved_config = resolver.to_hash
+
+            # Merge any additional config options
+            resolved_config = resolved_config.merge(cfg.except(:url)) if resolved_config
+
+            # Bail if URL couldn't be parsed
+            raise ArgumentError, "Invalid connection URL: #{cfg[:url]}" unless resolved_config
+
+            # Get adapter name from resolved config
+            adapter_name = resolved_config[:adapter]
+          else
+            # Traditional config with explicit adapter
+            adapter_name = cfg[:adapter] or raise ArgumentError, 'Missing :adapter'
+            resolved_config = cfg
+          end
+
+          path          = "active_cypher/connection_adapters/#{adapter_name}_adapter"
+          class_name    = "#{adapter_name}_adapter".camelize
+
+          require path
+          adapter_class = ActiveCypher::ConnectionAdapters.const_get(class_name)
+          self.connection = adapter_class.new(resolved_config)
+          connection.connect
+          connection
+        rescue LoadError => e
+          raise AdapterLoadError, "Could not load ActiveCypher adapter '#{adapter_name}' (#{e.message})"
+        end
+
+        # Sets up multiple connections for different roles, because one pool is never enough.
+        # @param mapping [Hash] Role-to-database mapping
+        # @return [void]
+        # Sets up multiple connections for different roles, because one pool is never enough.
+        # @param mapping [Hash] Role-to-database mapping
+        # @return [void]
+        # @note This is where the Ruby gremlins really start dancing—multiple pools, one registry, and a sprinkle of connection witchcraft.
+        def connects_to(mapping)
+          mapping.deep_symbolize_keys.each do |role, db_key|
+            spec = ActiveCypher::CypherConfig.for(db_key) # ← may raise KeyError
+
+            # If spec contains a URL, use ConnectionFactory
+            if spec[:url]
+              factory = ActiveCypher::ConnectionFactory.new(spec[:url])
+              spec = factory.config.merge(spec.except(:url)) if factory.valid?
+            end
+
+            pool = ActiveCypher::ConnectionPool.new(spec)
+            connection_handler.set(role.to_sym, :default, pool)
+          rescue KeyError => e
+            raise ActiveCypher::UnknownConnectionError,
+                  "connects_to #{role}: #{db_key.inspect} – #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/model/connection_owner.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # Mixin for anything that “owns” a connection (nodes, relationships, maybe
+    # graph‑level service objects later). 100 % framework‑agnostic.
+    # @note Because every object wants to feel important by "owning" something, even if it's just a connection.
+    # Moroccan black magick and Ruby sorcery may be involved in keeping these connections alive.
+    module ConnectionOwner
+      extend ActiveSupport::Concern
+      include ActiveCypher::Logging
+      include ActiveCypher::Model::ConnectionHandling
+
+      included do
+        # Every class gets its own adapter slot (overridden by establish_connection)
+        # Because nothing says "flexibility" like a class variable you'll forget exists.
+        # This is where the witchcraft happens: sometimes the right connection just appears.
+        cattr_accessor :connection, instance_accessor: false
+      end
+
+      class_methods do
+        delegate :current_role, :current_shard,
+                 to: ActiveCypher::RuntimeRegistry
+
+        # One handler for all subclasses that include this concern
+        # Because sharing is caring, except when it comes to connection pools.
+        # Summoned by Ruby wizardry: this handler is conjured once and shared by all.
+        @@connection_handler ||= ActiveCypher::ConnectionHandler.new # rubocop:disable Style/ClassVars
+        def connection_handler = @@connection_handler
+
+        # Temporarily switches the current role and shard for the duration of the block.
+        # @param role [Symbol, nil] The role to switch to
+        # @param shard [Symbol] The shard to switch to
+        # @yield The block to execute with the new context
+        # @note Because sometimes you just want to pretend you're connected to something else for a while.
+        # Warning: If you switch too often, you may summon unexpected spirits from the Ruby shadow dimension.
+        def connected_to(role: nil, shard: :default)
+          previous_role  = current_role
+          previous_shard = current_shard
+          ActiveCypher::RuntimeRegistry.current_role  = role  || previous_role
+          ActiveCypher::RuntimeRegistry.current_shard = shard || previous_shard
+          yield
+        ensure
+          ActiveCypher::RuntimeRegistry.current_role  = previous_role
+          ActiveCypher::RuntimeRegistry.current_shard = previous_shard
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/model/core.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Core: The module that tries to make your graph model feel like it belongs in a relational world.
+    #   # Includes every concern under the sun, because why have one abstraction when you can have twelve?
+    #   # Most of this works thanks to a little Ruby sorcery, a dash of witchcraft, and—on rare occasions—some unexplained back magick.
+    module Core
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::API
+        include ActiveModel::Attributes
+        include ActiveModel::Dirty
+        include ActiveCypher::Associations
+        include ActiveCypher::Scoping
+        include ActiveModel::Validations
+
+        attribute :internal_id, :string
+
+        cattr_accessor :connection, instance_accessor: false
+        class_attribute :configurations, instance_accessor: false,
+                                         default: ActiveSupport::HashWithIndifferentAccess.new
+      end
+
+      attr_reader :new_record
+
+      # Initializes a new model instance, because every object deserves a fresh start (and a fresh set of existential crises).
+      #
+      # @param attributes [Hash] Attributes to assign to the new instance
+      # @note If this works and you can't explain why, it's probably back magick.
+      def initialize(attributes = {})
+        _run(:initialize) do # <-- callback wrapper
+          super()
+          assign_attributes(attributes.symbolize_keys) if attributes
+          @new_record = true # Always true for normal initialization, because innocence is fleeting
+          clear_changes_information
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/model/countable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # Mixin that gives any graph element (node or edge) an efficient `.count`
+    #
+    # It issues a single Cypher `COUNT()` query instead of loading rows.
+    # Because sometimes you just want to know how many regrets you have, without reliving each one.
+    # A little ORM sorcery, a dash of witchcraft, and—very rarely—some back magick make this possible.
+    module Countable
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # @return [Integer] total rows for this label / rel‑type
+        # Because loading all the data just to count it is so last decade.
+        # If this returns the right number, thank the database gods—or maybe just the back magick hiding in the adapter.
+        def count
+          cypher, params =
+            if respond_to?(:label_name)          # ⇒ node class
+              ["MATCH (n:#{label_name}) RETURN count(n) AS c", {}]
+            else                                 # ⇒ relationship class
+              ["MATCH ()-[r:#{relationship_type}]-() RETURN count(r) AS c", {}] # ▲ undirected
+            end
+
+          connection.execute_cypher(cypher, params, 'Count').first[:c].to_i
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/model/destruction.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Destruction: The module that lets you banish records from existence with a single incantation.
+    #   # Uses a blend of Ruby sorcery, a dash of witchcraft, and—on rare occasions—some back magick when nothing else will do.
+    module Destruction
+      extend ActiveSupport::Concern
+
+      # Deletes the record from the database. Permanently. No takesies-backsies.
+      #
+      # Runs a Cypher `DETACH DELETE` query on the node.
+      # Freezes the object to prevent further use, as a kind of ceremonial burial.
+      # Because nothing says "closure" like a frozen Ruby object.
+      # If this works and you can't explain why, that's probably back magick.
+      #
+      # @raise [RuntimeError] if the record is new or already destroyed.
+      # @return [Boolean] true if the record was successfully destroyed, false if something caught on fire.
+      def destroy
+        _run(:destroy) do
+          raise 'Cannot destroy a new record' if new_record?
+          raise 'Record already destroyed' if destroyed?
+
+          n      = :n
+          query  = Cyrel.match(Cyrel.node(self.class.label_name).as(n))
+                        .where(Cyrel.id(n).eq(internal_id))
+                        .detach_delete(n)
+
+          cypher = query.to_cypher
+          params = { id: internal_id }
+
+          # Here lies the true sorcery: one line to erase a node from existence.
+          # If the database still remembers it, you may need to consult your local witch.
+          self.class.connection.execute_cypher(cypher, params, 'Destroy')
+          @destroyed = true
+          freeze # To make sure you can't Frankenstein it back to life. Lightning not included.
+          true
+        end
+      rescue StandardError
+        false # Something went wrong. Don’t ask. Just walk away. Or blame the database, that's always fun. If it keeps happening, suspect back magick.
+      end
+
+      # Returns true if this object has achieved full existential closure.
+      # If you see this return true and the record still exists, that's not a bug—it's witchcraft.
+      def destroyed? = @destroyed == true
+    end
+  end
+end

data/lib/active_cypher/model/inspectable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Adds a custom inspect method for pretty-printing a compact, single-line summary of the object.
+    #   # Because nothing says "debuggable" like a string that pretends your object is more interesting than it is.
+    module Inspectable
+      # Custom object inspection method for pretty-printing a compact,
+      # single-line summary of the object. Output examples:
+      #
+      #   #<UserNode id="26" name="Alice" age=34>   => persisted object
+      #   #<UserNode (new) name="Bob">              => object not yet saved
+      #
+      def inspect
+        # Put 'internal_id' first like it's the main character (even if it's nil)
+        ordered = attributes.dup
+        ordered = ordered.slice('internal_id').merge(ordered.except('internal_id'))
+
+        # Turn each attr into "key: value" because we humans fear raw hashes
+        parts = ordered.map { |k, v| "#{k}: #{v.inspect}" }
+
+        # Wrap it all up in a fake-sane object string, so you can pretend your data is organized.
+        "#<#{self.class} #{parts.join(', ')}>"
+      end
+    end
+  end
+end

data/lib/active_cypher/model/persistence.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Model
+    # @!parse
+    #   # Persistence: Because your data deserves a second chance, even if you don't.
+    #   # A little ORM sorcery, a dash of witchcraft, and—on rare occasions—some unexplained back magick.
+    module Persistence
+      extend ActiveSupport::Concern
+
+      # Saves the current record to the database.
+      #
+      # If it's a new record, it's born into this cruel digital world.
+      # If it already exists, we patch up its regrets.
+      # If it fails, we return false, like cowards.
+      #
+      # @return [Boolean] true if saved successfully, false if the database ghosted us.
+      # Because nothing says "robust" like pretending persistence is easy.
+      # If this works and you can't explain why, that's probably back magick.
+      def save
+        # before_/after_create
+        _run(:save) do
+          if new_record?
+            _run(:create) { create_record }
+          else
+            _run(:update) { update_record }
+          end
+        end
+      rescue RecordNotSaved
+        false
+      end
+
+      # Updates the record's attributes and then saves it.
+      #
+      # You know, like hope. But with hash keys.
+      # Because nothing says "optimism" like update-in-place.
+      # If this method ever fixes a bug you couldn't reproduce, that's just ORM witchcraft.
+      #
+      # @param attrs [Hash] the attributes to assign.
+      # @return [Boolean] true if we pretended hard enough to update.
+      def update(attrs)
+        assign_attributes(attrs)
+        save
+      end
+
+      # Reloads the record from the database and overwrites your foolish edits.
+      #
+      # Great for when you want to feel powerless again.
+      # Because sometimes you just want to see your changes disappear.
+      # If this ever resurrects data you thought was lost, that's not a bug—it's back magick.
+      #
+      # @raise [ActiveCypher::RecordNotFound] if the record is missing. Like your confidence.
+      # @return [self] the refreshed version of yourself, now with 30% more doubt.
+      def reload
+        raise ActiveCypher::RecordNotFound, 'Record not persisted' if new_record?
+
+        fresh = self.class.find(internal_id)
+        unless fresh
+          raise ActiveCypher::RecordNotFound,
+                "#{self.class} with internal_id=#{internal_id.inspect} not found"
+        end
+
+        self.attributes = fresh.attributes
+        clear_changes_information
+        self
+      end
+
+      # Returns true if the record is new and untouched by the database.
+      #
+      # @return [Boolean] true if the record is innocent.
+      # If this ever returns true for a record you thought was persisted, consult your local sorcerer.
+      def new_record? = @new_record
+
+      # Returns true if the record has been saved and now bears a scar (internal_id).
+      #
+      # @return [Boolean] true if the record has a past.
+      # If this ever returns false for a record you see in the database, that's pure ORM sorcery.
+      def persisted? = !new_record? && internal_id.present?
+
+      class_methods do
+        # Factory method for instantiating records from the database.
+        # Because sometimes you want to skip the whole "life cycle" thing.
+        # If this ever returns an object that shouldn't exist, that's back magick at work.
+        #
+        # @param attributes [Hash] Attributes from the database
+        # @return [ActiveCypher::Base, ActiveCypher::Relationship] A record marked as persisted
+        def instantiate(attributes)
+          rec = new # bootstrap
+          rec.assign_attributes(attributes)
+          rec.instance_variable_set(:@new_record, false)
+          rec.clear_changes_information # nothing is “dirty”
+          rec
+        end
+
+        # Bang‑version of `.create` — raises if the record can't be persisted.
+        # For when you want your errors loud and proud.
+        # If this ever succeeds when it shouldn't, that's not a feature—it's back magick.
+        #
+        # @param attrs [Hash]
+        # @return [ActiveCypher::Base] persisted record
+        # @raise [ActiveCypher::RecordNotSaved]
+        def create!(attrs = {})
+          rec = create(attrs)
+          if rec.persisted?
+            rec
+          else
+            raise ActiveCypher::RecordNotSaved,
+                  "#{name} could not be saved: #{rec.errors.full_messages.join(', ')}"
+          end
+        end
+      end
+
+      private
+
+      # # Internal method to initialize a record from the database
+      # # @param attributes [Hash] The attributes from the database
+      # # @return [self]
+      # def init_with_attributes(attrs)
+      #   binding.irb
+      #   assign_attributes(**attrs) if attrs
+      #   @new_record = false # Mark as not new when loading from DB
+      #   clear_changes_information
+      #   self
+      # end
+
+      # Creates the record in the database using Cypher.
+      #
+      # @return [Boolean] true if the database accepted your offering.
+      # Because nothing says "production ready" like a hand-crafted query.
+      # If this method ever works on the first try, that's not engineering—it's back magick.
+      def create_record
+        props = attributes_for_persistence
+        n = :n
+        label = self.class.label_name.to_s
+        node = Cyrel.node(n, labels: [label], properties: props)
+        query = Cyrel.create(node).return_(Cyrel.element_id(n).as(:internal_id))
+        cypher, params = query.to_cypher
+        params ||= {}
+
+        data = self.class.connection.execute_cypher(cypher, params, 'Create')
+        return false if data.blank? || !data.first.key?(:internal_id)
+
+        self.internal_id = data.first[:internal_id].to_s
+        @new_record = false
+        changes_applied
+        true
+      end
+
+      # Returns a hash of attributes that have changed and their spicy new values.
+      #
+      # @return [Hash] the things you dared to modify.
+      # Because tracking regret is what ORMs do best. If this ever returns an empty hash when you know you changed something, that's just ORM sorcery.
+      def changes_to_save
+        changes.transform_values(&:last)
+      end
+
+      # Updates the record in the database using Cypher, if anything changed.
+      #
+      # If nothing changed, we lie about doing work and return true anyway.
+      # Because sometimes you just want to feel productive.
+      # If this method ever updates the database when nothing changed, that's not a bug—it's back magick.
+      #
+      # @return [Boolean] true if we updated something, or just acted like we did.
+      def update_record
+        changes = changes_to_save
+        return true if changes.empty?
+
+        n = :n
+        query = Cyrel.match(Cyrel.node(self.class.label_name).as(n))
+                     .where(Cyrel.id(n).eq(internal_id))
+                     .set(n => changes)
+
+        cypher, params = query.to_cypher
+        params ||= {}
+
+        self.class.connection.execute_cypher(cypher, params, 'Update')
+        changes_applied
+        true
+      end
+    end
+  end
+end