activecypher 0.3.0 → 0.5.0

data/lib/active_cypher/generators/templates/relationship.rb.erb

@@ -2,10 +2,11 @@
 
 class <%= class_name %> < ApplicationGraphRelationship
   from_class :<%= options[:from] %>
-    to_class   :<%= options[:to]   %>
-    type       :<%= relationship_type %>
-
-    <% attributes.each do |attr| -%>
-    attribute :<%= attr.name %>, :<%= attr.type || "string" %>
-  <% end -%>
+  to_class   :<%= options[:to] %>
+  type       :<%= relationship_type %>
+<% if attributes.any? -%>
+<% attributes.each do |attr| -%>
+  attribute :<%= attr.name %>, :<%= attr.type || "string" %>
+<% end -%>
+<% end -%>
 end

data/lib/active_cypher/instrumentation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module ActiveCypher
+  # Instrumentation for ActiveCypher operations.
+  # Because every database operation needs a stopwatch and an audience.
+  module Instrumentation
+    # ------------------------------------------------------------------
+    # Core instrumentation method
+    # ------------------------------------------------------------------
+
+    # Instruments an operation and publishes an event with timing information.
+    # @param operation [String, Symbol] The operation name (prefixed with 'active_cypher.')
+    # @param payload [Hash] Additional context for the event
+    # @yield The operation to instrument
+    # @return [Object] The result of the block
+    def instrument(operation, payload = {})
+      # Start timing with monotonic clock for accuracy (because wall time is for amateurs)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Run the actual operation
+      result = yield
+
+      # Calculate duration in milliseconds (because counting seconds is so 1990s)
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1_000).round(2)
+
+      # Add duration to payload
+      payload[:duration_ms] = duration_ms
+
+      # Publish event via ActiveSupport::Notifications
+      event_name = operation.to_s.start_with?('active_cypher.') ? operation.to_s : "active_cypher.#{operation}"
+      ActiveSupport::Notifications.instrument(event_name, payload)
+
+      # Also log if we have logging capabilities
+      log_instrumented_event(operation, payload) if respond_to?(:logger)
+
+      # Return the original result
+      result
+    end
+
+    # ------------------------------------------------------------------
+    # Specialized instrumentation methods
+    # ------------------------------------------------------------------
+
+    # Instruments a database query.
+    # @param cypher [String] The Cypher query
+    # @param params [Hash] Query parameters
+    # @param context [String] Additional context (e.g., "Model.find")
+    # @param metadata [Hash] Additional metadata
+    # @yield The query operation
+    # @return [Object] The result of the block
+    def instrument_query(cypher, params = {}, context: 'Query', metadata: {}, &)
+      truncated_cypher = cypher.to_s.gsub(/\s+/, ' ').strip
+      truncated_cypher = "#{truncated_cypher[0...97]}..." if truncated_cypher.length > 100
+
+      payload = metadata.merge(
+        cypher: truncated_cypher,
+        params: sanitize_params(params),
+        context: context
+      )
+
+      instrument('query', payload, &)
+    end
+
+    # Instruments a connection operation.
+    # @param operation [Symbol] The connection operation (:connect, :disconnect, etc)
+    # @param config [Hash] Connection configuration
+    # @param metadata [Hash] Additional metadata
+    # @yield The connection operation
+    # @return [Object] The result of the block
+    def instrument_connection(operation, config = {}, metadata: {}, &)
+      payload = metadata.merge(
+        config: sanitize_config(config)
+      )
+
+      instrument("connection.#{operation}", payload, &)
+    end
+
+    # Instruments a transaction operation.
+    # @param operation [Symbol] The transaction operation (:begin, :commit, :rollback)
+    # @param transaction_id [String, Integer] Transaction identifier (if available)
+    # @param metadata [Hash] Additional metadata
+    # @yield The transaction operation
+    # @return [Object] The result of the block
+    def instrument_transaction(operation, transaction_id = nil, metadata: {}, &)
+      payload = metadata.dup
+      payload[:transaction_id] = transaction_id if transaction_id
+
+      instrument("transaction.#{operation}", payload, &)
+    end
+
+    # ------------------------------------------------------------------
+    # Sanitization methods
+    # ------------------------------------------------------------------
+
+    # Sanitizes query parameters to remove sensitive values.
+    # @param params [Hash, Object] The parameters to sanitize
+    # @return [Hash, Object] Sanitized parameters
+    def sanitize_params(params)
+      return params unless params.is_a?(Hash)
+
+      params.each_with_object({}) do |(key, value), sanitized|
+        sanitized[key] = if sensitive_key?(key)
+                           '[FILTERED]'
+                         elsif value.is_a?(Hash)
+                           sanitize_params(value)
+                         else
+                           value
+                         end
+      end
+    end
+
+    # Sanitizes connection configuration to remove sensitive values.
+    # @param config [Hash] The configuration to sanitize
+    # @return [Hash] Sanitized configuration
+    def sanitize_config(config)
+      return {} unless config.is_a?(Hash)
+
+      config.each_with_object({}) do |(key, value), result|
+        result[key] = if sensitive_key?(key)
+                        '[FILTERED]'
+                      elsif value.is_a?(Hash)
+                        sanitize_config(value)
+                      else
+                        value
+                      end
+      end
+    end
+
+    # Determines if a key contains sensitive information that should be filtered.
+    # @param key [String, Symbol] The key to check
+    # @return [Boolean] True if the key contains sensitive information
+    def sensitive_key?(key)
+      return true if key.to_s.match?(/\b(password|token|secret|credential|key)\b/i)
+
+      # Check against Rails filter parameters if available
+      if defined?(Rails) && Rails.application
+        Rails.application.config.filter_parameters.any? do |pattern|
+          case pattern
+          when Regexp
+            key.to_s =~ pattern
+          when Symbol, String
+            key.to_s == pattern.to_s
+          else
+            false
+          end
+        end
+      else
+        false
+      end
+    end
+
+    private
+
+    # ------------------------------------------------------------------
+    # Logging integration
+    # ------------------------------------------------------------------
+    # Logs an instrumented event if logging is available.
+    # @param operation [String, Symbol] The operation name
+    # @param payload [Hash] The event payload
+    def log_instrumented_event(operation, payload)
+      return unless respond_to?(:log_debug)
+
+      # Format duration if available
+      duration_text = payload[:duration_ms] ? " (#{payload[:duration_ms]} ms)" : ''
+      operation_name = operation.to_s.sub(/^active_cypher\./, '')
+
+      case operation_name
+      when /query/
+        log_debug("QUERY#{duration_text}: #{payload[:cypher]}")
+        log_debug("PARAMS: #{payload[:params].inspect}") if payload[:params]
+      when /connection/
+        op = operation_name.sub(/^connection\./, '')
+        log_debug("CONNECTION #{op.upcase}#{duration_text}")
+      when /transaction/
+        op = operation_name.sub(/^transaction\./, '')
+        tx_id = payload[:transaction_id] ? " (ID: #{payload[:transaction_id]})" : ''
+        log_debug("TRANSACTION #{op.upcase}#{tx_id}#{duration_text}")
+      else
+        # Generic fallback, for when you just don't know how to categorize your problems
+        log_debug("#{operation_name.upcase}#{duration_text}")
+      end
+    end
+  end
+end

data/lib/active_cypher/model/connection_owner.rb

@@ -28,6 +28,15 @@ module ActiveCypher
         @@connection_handler ||= ActiveCypher::ConnectionHandler.new # rubocop:disable Style/ClassVars
         def connection_handler = @@connection_handler
 
+        # Returns the adapter class being used by this model
+        # @return [Class] The adapter class (e.g., Neo4jAdapter, MemgraphAdapter)
+        def adapter_class
+          conn = connection
+          return nil unless conn
+
+          conn.class
+        end
+
         # 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
@@ -45,6 +54,12 @@ module ActiveCypher
           ActiveCypher::RuntimeRegistry.current_shard = previous_shard
         end
       end
+
+      # Instance method to access the adapter class
+      # @return [Class] The adapter class (e.g., Neo4jAdapter, MemgraphAdapter)
+      def adapter_class
+        self.class.adapter_class
+      end
     end
   end
 end

data/lib/active_cypher/model/core.rb

@@ -4,10 +4,9 @@ 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.
+    # 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
 
@@ -24,6 +23,61 @@ module ActiveCypher
         cattr_accessor :connection, instance_accessor: false
         class_attribute :configurations, instance_accessor: false,
                                          default: ActiveSupport::HashWithIndifferentAccess.new
+
+        # Use array instead of set to preserve insertion order of labels
+        class_attribute :custom_labels, default: []
+      end
+
+      class_methods do
+        # Define a label for the model. Can be called multiple times to add multiple labels.
+        # @param label_name [Symbol, String] The label name
+        # @return [Array] The collection of custom labels
+        #
+        # @example Single label
+        #   class PetNode < ApplicationGraphNode
+        #     label :Pet
+        #   end
+        #
+        # @example Multiple labels
+        #   class PetNode < ApplicationGraphNode
+        #     label :Pet
+        #     label :Animal
+        #   end
+        def label(label_name)
+          # Convert to symbol for consistency
+          label_sym = label_name.to_sym
+
+          # Add to the collection if not already present
+          # Using array to preserve insertion order
+          self.custom_labels = custom_labels.dup << label_sym unless custom_labels.include?(label_sym)
+
+          custom_labels
+        end
+
+        # Get all labels for this model
+        # @return [Array<Symbol>] All labels for this model
+        def labels
+          # Return custom labels if any exist, otherwise use default label
+          custom_labels.empty? ? [default_label] : custom_labels
+        end
+
+        # Returns the primary label for the model
+        # @return [Symbol] The primary label
+        def label_name
+          # Use the first custom label if any exist
+          return custom_labels.first if custom_labels.any?
+
+          # Otherwise fall back to default behavior
+          default_label
+        end
+
+        # Computes the default label for the model based on class name
+        # Strips 'Node' or 'Record' suffix, returns as symbol, capitalized
+        def default_label
+          base = name.split('::').last
+          base = base.sub(/(Node|Record)\z/, '')
+          base.to_sym
+        end
       end
 
       attr_reader :new_record

data/lib/active_cypher/model/countable.rb

@@ -16,9 +16,16 @@ module ActiveCypher
         # 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
+            if respond_to?(:label_name) # ⇒ node class
+              if respond_to?(:labels) && labels.any?
+                # Use all custom labels for COUNT operations
+                label_string = labels.map { |l| ":#{l}" }.join
+                ["MATCH (n#{label_string}) RETURN count(n) AS c", {}]
+              else
+                # Fall back to primary label
+                ["MATCH (n:#{label_name}) RETURN count(n) AS c", {}]
+              end
+            else # ⇒ relationship class
               ["MATCH ()-[r:#{relationship_type}]-() RETURN count(r) AS c", {}] # ▲ undirected
             end
 

data/lib/active_cypher/model/destruction.rb

@@ -22,23 +22,30 @@ module ActiveCypher
           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))
+          n = :n
+          # Use all labels for database operations
+          labels = self.class.respond_to?(:labels) ? self.class.labels : [self.class.label_name]
+          query  = Cyrel.match(Cyrel.node(n, labels: labels))
+                        .where(Cyrel.element_id(n).eq(internal_id))
                         .detach_delete(n)
+                        .return_('count(*) as deleted')
 
-          cypher = query.to_cypher
-          params = { id: internal_id }
+          cypher, params = query.to_cypher
+          params ||= {}
 
           # 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
+          result = self.class.connection.execute_cypher(cypher, params, 'Destroy')
+          if result.present? && result.first.present? && (result.first[:deleted] || 0).positive?
+            @destroyed = true
+            freeze # To make sure you can't Frankenstein it back to life. Lightning not included.
+            true
+          else
+            false
+          end
         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.
+        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.

data/lib/active_cypher/model/persistence.rb

@@ -131,8 +131,12 @@ module ActiveCypher
       def create_record
         props = attributes_for_persistence
         n = :n
-        label = self.class.label_name.to_s
-        node = Cyrel.node(n, labels: [label], properties: props)
+
+        # Use all labels for database operations
+        labels = self.class.respond_to?(:labels) ? self.class.labels : [self.class.label_name.to_s]
+
+        # Create node with all labels
+        node = Cyrel.node(n, labels: labels, properties: props)
         query = Cyrel.create(node).return_(Cyrel.element_id(n).as(:internal_id))
         cypher, params = query.to_cypher
         params ||= {}
@@ -166,16 +170,32 @@ module ActiveCypher
         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)
+
+        # Use all labels for database operations
+        labels = self.class.respond_to?(:labels) ? self.class.labels : [self.class.label_name]
+
+        # Match node with all labels
+        query = Cyrel.match(Cyrel.node(n, labels: labels))
+                     .where(Cyrel.element_id(n).eq(internal_id)) # Use element_id explicitly
+
+        # Create separate SET clauses for each property to avoid overwriting existing properties
+        changes.each do |property, value|
+          query = query.set(Cyrel.prop(n, property) => value)
+        end
+
+        query = query.return_(n) # Return the updated node to confirm success
 
         cypher, params = query.to_cypher
         params ||= {}
 
-        self.class.connection.execute_cypher(cypher, params, 'Update')
-        changes_applied
-        true
+        result = self.class.connection.execute_cypher(cypher, params, 'Update')
+
+        if result.present? && result.first.present?
+          changes_applied
+          true
+        else
+          false
+        end
       end
     end
   end

data/lib/active_cypher/model/querying.rb

@@ -45,11 +45,15 @@ module ActiveCypher
         def find(internal_db_id)
           node_alias = :n
 
+          # Use all labels if available, otherwise fall back to the primary label
+          labels = respond_to?(:labels) ? self.labels : [label_name]
+
           query = Cyrel
-                  .match(Cyrel.node(label_name).as(node_alias))
+                  .match(Cyrel.node(node_alias, labels: labels))
                   .where(Cyrel.element_id(node_alias).eq(internal_db_id))
                   .return_(node_alias, Cyrel.element_id(node_alias).as(:internal_id))
                   .limit(1)
+          query.to_cypher
 
           Relation.new(self, query).first or
             raise ActiveCypher::RecordNotFound,

data/lib/active_cypher/relation.rb

@@ -129,11 +129,19 @@ module ActiveCypher
     # 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
 
+      # Use all labels if available, otherwise fall back to primary label
+      labels = if model_class.respond_to?(:labels)
+                 model_class.labels
+               elsif model_class.respond_to?(:label_name)
+                 [model_class.label_name]
+               else
+                 [model_class.model_name.element.to_sym]
+               end
+
       Cyrel
-        .match(Cyrel.node(label).as(node_alias))
+        .match(Cyrel.node(node_alias, labels: labels))
         .return_(node_alias, Cyrel.element_id(node_alias).as(:internal_id))
     end
 

data/lib/active_cypher/version.rb

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

data/lib/cyrel/clause/set.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'cyrel/expression'
+require 'cyrel/expression/property_access'
+
 module Cyrel
   module Clause
     # Represents a SET clause in a Cypher query.
@@ -12,6 +15,7 @@ module Cyrel
       #   - Hash: { variable_or_prop_access => value_expression, ... }
       #     e.g., { Cyrel.prop(:n, :name) => "New Name", Cyrel.prop(:r, :weight) => 10 }
       #     e.g., { n: { name: "New Name", age: 30 } } # For SET n = properties or n += properties
+      #     e.g., { Cyrel.plus(:n) => { name: "New Name" } } # For SET n += { name: ... }
       #   - Array: [[variable, label_string], ...] # For SET n:Label
       #     e.g., [[:n, "NewLabel"], [:m, "AnotherLabel"]]
       #   Note: Mixing hash and array styles in one call is not directly supported, use multiple SET clauses if needed.
@@ -47,17 +51,20 @@ module Cyrel
         case assignments
         when Hash
           assignments.flat_map do |key, value|
-            if key.is_a?(Expression::PropertyAccess)
+            case key
+            when Expression::PropertyAccess
               # SET n.prop = value
               [[:property, key, Expression.coerce(value)]]
-            elsif key.is_a?(Symbol) || key.is_a?(String)
-              # SET n = properties or SET n += properties
-              # We need to decide which operator (= or +=). Defaulting to = for now.
-              # User might need to specify via a different method/option.
-              # Let's assume the value is a hash for this case.
+            when Symbol, String
+              # SET n = properties
               raise ArgumentError, 'Value for variable assignment must be a Hash (for SET n = {props})' unless value.is_a?(Hash)
 
-              [[:variable_properties, key.to_sym, Expression.coerce(value)]]
+              [[:variable_properties, key.to_sym, Expression.coerce(value), :assign]]
+            when Cyrel::Plus
+              # SET n += properties
+              raise ArgumentError, 'Value for variable assignment must be a Hash (for SET n += {props})' unless value.is_a?(Hash)
+
+              [[:variable_properties, key.variable.to_sym, Expression.coerce(value), :merge]]
             else
               raise ArgumentError, "Invalid key type in SET assignments hash: #{key.class}"
             end
@@ -78,15 +85,18 @@ module Cyrel
       end
 
       def render_assignment(assignment, query)
-        type, target, value = assignment
+        type, target, value, op = assignment
         case type
         when :property
           # target is PropertyAccess, value is Expression
           "#{target.render(query)} = #{value.render(query)}"
         when :variable_properties
           # target is variable symbol, value is Expression (Literal Hash)
-          # Using '=' operator here. Could add support for '+=' later.
-          "#{target} = #{value.render(query)}"
+          if op == :merge
+            "#{target} += #{value.render(query)}"
+          else
+            "#{target} = #{value.render(query)}"
+          end
         when :label
           # target is variable symbol, value is label string
           "#{target}:#{value}" # Labels are not parameterized

data/lib/cyrel/expression/property_access.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cyrel/expression/base'
+
 module Cyrel
   module Expression
     # Represents accessing a property on a variable (node or relationship alias).

data/lib/cyrel/plus.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Cyrel
+  class Plus
+    attr_reader :variable
+
+    def initialize(variable)
+      @variable = variable
+    end
+  end
+end

data/lib/cyrel/query.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'cyrel/parameterizable'
 # Require necessary clause and pattern types
 
 # Require all clause types for DSL methods