activecypher 0.3.0 → 0.6.0

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -3,6 +3,38 @@
 module ActiveCypher
   module ConnectionAdapters
     class MemgraphAdapter < AbstractBoltAdapter
+      # Register this adapter with the registry
+      Registry.register('memgraph', self)
+
+      # Use id() for Memgraph instead of elementId()
+      ID_FUNCTION = 'id'
+
+      # Helper methods for Cypher query generation with IDs
+      def self.with_direct_id(id)
+        "id(r) = #{id}"
+      end
+
+      def self.with_param_id
+        'id(r) = $id'
+      end
+
+      def self.with_direct_node_ids(a_id, b_id)
+        "id(p) = #{a_id} AND id(h) = #{b_id}"
+      end
+
+      def self.with_param_node_ids
+        'id(p) = $from_id AND id(h) = $to_id'
+      end
+
+      def self.return_id
+        'id(r) AS rid'
+      end
+
+      # Return self as id_handler for compatibility with tests
+      def id_handler
+        self.class
+      end
+
       # Memgraph defaults to **implicit auto‑commit** transactions :contentReference[oaicite:1]{index=1},
       # so we simply run the Cypher and return the rows.
       def execute_cypher(cypher, params = {}, ctx = 'Query')
@@ -34,6 +66,18 @@ module ActiveCypher
         true
       end
 
+      # Override prepare_params to handle arrays correctly for Memgraph
+      # Memgraph's UNWIND requires actual arrays/lists, not maps
+      def prepare_params(raw)
+        case raw
+        when Hash  then raw.transform_keys(&:to_s).transform_values { |v| prepare_params(v) }
+        when Array then raw.map { |v| prepare_params(v) } # Keep arrays as arrays for Memgraph
+        when Time, Date, DateTime then raw.iso8601
+        when Symbol then raw.to_s
+        else raw # String/Integer/Float/Boolean/NilClass
+        end
+      end
+
       class ProtocolHandler < AbstractProtocolHandler
         def extract_version(agent)
           agent[%r{Memgraph/([\d.]+)}, 1] || 'unknown'

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -3,6 +3,32 @@
 module ActiveCypher
   module ConnectionAdapters
     class Neo4jAdapter < AbstractBoltAdapter
+      Registry.register('neo4j', self)
+
+      # Use elementId() for Neo4j
+      ID_FUNCTION = 'elementId'
+
+      # Helper methods for Cypher query generation with IDs
+      def self.with_direct_id(id)
+        "elementId(r) = #{id}"
+      end
+
+      def self.with_param_id
+        'elementId(r) = $id'
+      end
+
+      def self.with_direct_node_ids(a_id, b_id)
+        "elementId(p) = #{a_id} AND elementId(h) = #{b_id}"
+      end
+
+      def self.with_param_node_ids
+        'elementId(p) = $from_id AND elementId(h) = $to_id'
+      end
+
+      def self.return_id
+        'elementId(r) AS rid'
+      end
+
       def execute_cypher(cypher, params = {}, ctx = 'Query')
         connect
         session = connection.session # thin wrapper around Bolt::Session
@@ -16,7 +42,7 @@ module ActiveCypher
       end
 
       # Explicit TX helpers — optional but handy.
-      def begin_transaction = (@tx = @connection.session.begin_transaction)
+      def begin_transaction(**) = (@tx = @connection.session.begin_transaction(**))
       def commit_transaction(_)   = @tx&.commit
       def rollback_transaction(_) = @tx&.rollback
 

data/lib/active_cypher/connection_adapters/registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module ConnectionAdapters
+    # Registry: Because every adapter wants to feel special, and every ORM needs a secret society.
+    # This class is the adapter speakeasy—register your adapter, get on the list, and maybe, just maybe,
+    # you'll get to connect to a database tonight. Under the hood, it's just a hash, a dash of Ruby mischief,
+    # and the occasional existential dread when you realize your adapter isn't registered.
+    class Registry
+      class << self
+        # The sacred scroll of adapters. Not inherited, not shared—just ours.
+        def adapters
+          @adapters ||= {}
+        end
+
+        # Register an adapter class for a specific database type.
+        # Because every adapter wants to be chosen, but only a few make the cut.
+        # @param adapter_type [String] The adapter type name (e.g., 'neo4j', 'memgraph')
+        # @param adapter_class [Class] The adapter class to register
+        def register(adapter_type, adapter_class)
+          adapters[adapter_type.to_s.downcase] = adapter_class
+        end
+
+        # Get all registered adapters (for those who like to peek behind the curtain).
+        # @return [Hash] The hash of registered adapters
+        def adapters_dup
+          adapters.dup
+        end
+
+        # Summon an adapter from a connection URL.
+        # @param url [String] Connection URL (e.g., "neo4j://user:pass@localhost:7687")
+        # @param options [Hash] Additional options for the connection
+        # @return [AbstractAdapter] An instance of the appropriate adapter
+        def create_from_url(url, options = {})
+          resolver = ActiveCypher::ConnectionUrlResolver.new(url)
+          config = resolver.to_hash
+          return nil unless config
+
+          create_from_config(config, options)
+        end
+
+        # Conjure an adapter from a configuration hash.
+        # @param config [Hash] Configuration hash with adapter, host, port, etc.
+        # @param options [Hash] Additional options for the connection
+        # @return [AbstractAdapter] An instance of the appropriate adapter, or a cryptic error if you angered the registry spirits.
+        def create_from_config(config, options = {})
+          adapter_type = config[:adapter].to_s.downcase
+          adapter_class = adapters[adapter_type]
+          unless adapter_class
+            # Try to require the adapter file dynamically
+            begin
+              require "active_cypher/connection_adapters/#{adapter_type}_adapter"
+            rescue LoadError
+              # Ignore, will raise below
+            end
+            adapter_class = adapters[adapter_type]
+          end
+          raise ActiveCypher::ConnectionError, "No adapter registered for '#{adapter_type}'. The registry is silent (and so is require)." unless adapter_class
+
+          full_config = config.merge(options)
+          adapter_class.new(full_config)
+        end
+
+        # Creates a Bolt driver from a connection URL, because sometimes you want to skip the foreplay and go straight to disappointment.
+        # @param url [String] Connection URL
+        # @param pool_size [Integer] Connection pool size
+        # @param options [Hash] Additional options
+        # @return [Bolt::Driver] The configured driver, or a ticket to the debugging underworld.
+        def create_driver_from_url(url, pool_size: 5, options: {})
+          resolver = ActiveCypher::ConnectionUrlResolver.new(url)
+          config = resolver.to_hash
+          return nil unless config
+
+          adapter = create_from_config(config, options)
+          return nil unless adapter
+
+          # Always use 'bolt' scheme for driver creation, regardless of adapter
+          uri = "bolt://#{config[:host]}:#{config[:port]}"
+          auth_token = {
+            scheme: 'basic',
+            principal: config[:username],
+            credentials: config[:password]
+          }
+          ActiveCypher::Bolt::Driver.new(
+            uri: uri,
+            adapter: adapter,
+            auth_token: auth_token,
+            pool_size: pool_size
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/connection_handler.rb

@@ -2,8 +2,23 @@
 
 module ActiveCypher
   class ConnectionHandler
-    def initialize = @role_shard_map = Hash.new { |h, k| h[k] = {} }
-    def set(role, shard, pool) = (@role_shard_map[role][shard] = pool)
-    def pool(role, shard)      = @role_shard_map.dig(role, shard)
+    def initialize
+      # One-level hash: db_key -> pool
+      @db_key_map = {}
+    end
+
+    # Set a connection pool
+    # @param db_key [Symbol] The database key (e.g., :primary, :neo4j)
+    # @param pool [ConnectionPool] The connection pool
+    def set(db_key, pool)
+      @db_key_map[db_key.to_sym] = pool
+    end
+
+    # Get a connection pool
+    # @param db_key [Symbol] The database key (e.g., :primary, :neo4j)
+    # @return [ConnectionPool, nil] The connection pool, or nil if not found
+    def pool(db_key)
+      @db_key_map[db_key.to_sym]
+    end
   end
 end

data/lib/active_cypher/connection_pool.rb

@@ -5,7 +5,7 @@ require 'timeout'
 
 module ActiveCypher
   class ConnectionPool
-    attr_reader :spec
+    attr_reader :spec, :connection_key
 
     def initialize(spec)
       @spec = spec.symbolize_keys
@@ -44,28 +44,10 @@ module ActiveCypher
         conn = @conn_ref.value
         return conn if conn&.active?
 
-        # Slow path —create a new connection with retry logic
-        retries = 0
-        max_retries = @spec[:max_retries]
-
-        begin
-          new_conn = build_connection
-          @conn_ref.set(new_conn)
-          @retry_count.set(0) # Reset retry count on success
-          return new_conn
-        rescue StandardError => e
-          retries += 1
-          if retries <= max_retries
-            # Exponential backoff
-            sleep_time = 0.1 * (2**(retries - 1))
-            sleep(sleep_time)
-            retry
-          else
-            # Track persistent failures
-            @retry_count.update { |count| count + 1 }
-            raise ConnectionError, "Failed to establish connection after #{max_retries} attempts: #{e.message}"
-          end
-        end
+        # Create a new connection
+        new_conn = build_connection
+        @conn_ref.set(new_conn)
+        return new_conn
       end
     end
     alias checkout connection

data/lib/active_cypher/connection_url_resolver.rb

@@ -15,6 +15,12 @@ module ActiveCypher
   # - memgraph+ssl://
   # - memgraph+ssc://
   #
+  # Database resolution:
+  # - If specified in path: neo4j://localhost:7687/custom_db → db=custom_db
+  # - Otherwise defaults based on adapter:
+  #   - neo4j://localhost:7687 → db=neo4j
+  #   - memgraph://localhost:7687 → db=memgraph
+  #
   # The output of to_hash follows a consistent pattern:
   # {
   #   adapter: "neo4j", # or "memgraph"
@@ -22,7 +28,7 @@ module ActiveCypher
   #   password: "pass",
   #   host: "localhost",
   #   port: 7687,
-  #   database: nil, # or optional
+  #   database: "neo4j", # or "memgraph" or custom path value
   #   ssl: true,
   #   ssc: false,
   #   options: {} # future-proof for params like '?timeout=30'
@@ -83,8 +89,13 @@ module ActiveCypher
       options = extract_query_params(uri.query)
 
       # Extract database from path, if present
-      database = uri.path.empty? ? nil : uri.path.sub(%r{^/}, '')
-      database = nil if database&.empty?
+      path_database = uri.path.empty? ? nil : uri.path.sub(%r{^/}, '')
+      path_database = nil if path_database&.empty?
+
+      # Determine database using factory pattern:
+      # 1. Use path database if specified
+      # 2. Otherwise fall back to adapter name as default
+      database = path_database || adapter
 
       # The to_s conversion handles nil values
       username = uri.user.to_s.empty? ? nil : CGI.unescape(uri.user)

data/lib/active_cypher/cypher_config.rb

@@ -23,7 +23,8 @@ module ActiveCypher
         return nil if ENV['ACTIVE_CYPHER_SILENT_MISSING'] == 'true'
 
         # Otherwise, raise a descriptive error
-        raise "Could not load ActiveCypher configuration. No such file - #{file}. Please run 'rails generate active_cypher:install' to create the configuration file."
+        raise "Could not load ActiveCypher configuration. No such file - #{file}. " \
+              "Please run 'rails generate active_cypher:install' to create the configuration file."
       end
 
       ## ------------------------------------------------------------

data/lib/active_cypher/fixtures/dsl_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Context for evaluating fixture profile DSL files.
+    # Provides node and relationship methods for use in profiles.
+    class DSLContext
+      attr_reader :nodes, :relationships
+
+      def initialize
+        @nodes = []
+        @relationships = []
+        @refs = {}
+      end
+
+      # DSL: node :ref, ModelClass, props
+      def node(ref, model_class, **props)
+        raise ArgumentError, "Duplicate node ref: #{ref.inspect}" if @refs.key?(ref)
+
+        @refs[ref] = :node
+        @nodes << { ref: ref, model_class: model_class, props: props }
+      end
+
+      # DSL: relationship :ref, :from_ref, :TYPE, :to_ref, props
+      def relationship(ref, from_ref, type, to_ref, **props)
+        raise ArgumentError, "Duplicate relationship ref: #{ref.inspect}" if @refs.key?(ref)
+        raise ArgumentError, "Unknown from_ref: #{from_ref.inspect}" unless @refs.key?(from_ref)
+        raise ArgumentError, "Unknown to_ref: #{to_ref.inspect}" unless @refs.key?(to_ref)
+
+        @refs[ref] = :relationship
+        @relationships << {
+          ref: ref,
+          from_ref: from_ref,
+          type: type,
+          to_ref: to_ref,
+          props: props
+        }
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/evaluator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Evaluator orchestrates node and relationship creation for a fixture profile.
+    class Evaluator
+      def initialize(registry: Registry, node_builder: NodeBuilder.new, rel_builder: RelBuilder.new)
+        @registry = registry
+        @node_builder = node_builder
+        @rel_builder = rel_builder
+      end
+
+      # Evaluate a sequence of DSL instructions (AST or direct calls).
+      # Each instruction is a hash: { type: :node/:relationship, args: [...] }
+      def evaluate(instructions)
+        instructions.each do |inst|
+          case inst[:type]
+          when :node
+            ref = inst[:ref]
+            model_class = inst[:model_class]
+            props = inst[:props]
+            @node_builder.build(ref, model_class, props)
+          when :relationship
+            ref = inst[:ref]
+            from_ref = inst[:from_ref]
+            type = inst[:rel_type]
+            to_ref = inst[:to_ref]
+            props = inst[:props]
+            @rel_builder.build(ref, from_ref, type, to_ref, props)
+          else
+            raise ArgumentError, "Unknown instruction type: #{inst[:type]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/node_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    class NodeBuilder
+      # Builds a node and registers it like a bouncer at a VIP graph party.
+      #
+      # @param ref [Symbol, String] Logical ref name (e.g., :john, :spaceship_42)
+      # @param model_class [Class] The model class (must know how to connect and label itself)
+      # @param props [Hash] Properties to assign to the node
+      # @return [Object] Instantiated model object with DB-assigned internal_id
+      def self.build(ref, model_class, props)
+        conn = model_class.connection
+        labels = model_class.labels
+
+        # Because even Cypher likes a well-dressed node.
+        label_clause = labels.map { |label| "`#{label}`" }.join(':')
+
+        # Build and fire the CREATE query.
+        # We use id(n) because elementId(n) lies to us with strings.
+        cypher = <<~CYPHER
+          CREATE (n:#{label_clause} $props)
+          RETURN n, id(n) AS internal_id, properties(n) AS props
+        CYPHER
+
+        result = conn.execute_cypher(cypher, props: props)
+        record = result.first
+
+        # Extract properties returned by the DB
+        node_props = record[:props] || record['props'] || {}
+        node_props['internal_id'] = record[:internal_id] || record['internal_id']
+
+        # Instantiate and tag it like we own it
+        instance = model_class.instantiate(node_props)
+        Registry.add(ref, instance)
+        instance
+      end
+
+      # Bulk create nodes. Still uses single `CREATE` per node,
+      # just slices the list to avoid melting your graph engine.
+      #
+      # @param nodes [Array<Hash>] List of { ref:, model_class:, props: }
+      # @param batch_size [Integer] How many to process per slice
+      def self.bulk_build(nodes, batch_size: 200)
+        nodes.each_slice(batch_size) do |batch|
+          batch.each do |node|
+            build(node[:ref], node[:model_class], node[:props])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Parses a fixture profile file using instance_eval in a DSL context.
+    class Parser
+      attr_reader :file, :dsl_context
+
+      def initialize(file)
+        @file = file
+        @dsl_context = ActiveCypher::Fixtures::DSLContext.new
+      end
+
+      # Evaluates the profile file in the DSL context.
+      # Returns the DSLContext instance (which accumulates node/rel declarations).
+      def parse
+        code = File.read(file)
+        dsl_context.instance_eval(code, file)
+        dsl_context
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/registry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Singleton registry for logical ref => model instance mapping
+    class Registry
+      @store = {}
+
+      class << self
+        # Store loaded instance
+        # @param ref [Symbol, String]
+        # @param obj [Object]
+        def add(ref, obj)
+          raise ArgumentError, "Duplicate fixture ref: #{ref.inspect}" if @store.key?(ref.to_sym)
+
+          @store[ref.to_sym] = obj
+        end
+
+        # Fetch in tests (`[]` delegate)
+        # @param ref [Symbol, String]
+        # @return [Object, nil]
+        def get(ref)
+          @store[ref.to_sym]
+        end
+
+        # Purge registry between loads
+        def reset!
+          @store.clear
+        end
+
+        # Allow bracket access: Registry[:foo]
+        def [](ref)
+          get(ref)
+        end
+
+        # For debugging or introspection
+        def all
+          @store.dup
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/rel_builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    class RelBuilder
+      # Builds a relationship between two nodes, enforcing cross-DB safety.
+      #
+      # @param _ref [Symbol, String] Logical reference for this relationship (not used for DB, but for registry/uniqueness)
+      # @param from_ref [Symbol, String] Logical ref of the start node
+      # @param type [Symbol, String] Relationship type (e.g., :LIKES)
+      # @param to_ref [Symbol, String] Logical ref of the end node
+      # @param props [Hash] Optional properties for the relationship
+      # @raise [ActiveCypher::FixtureError] if cross-DB relationship is attempted
+      # @return [void]
+      def build(_ref, from_ref, type, to_ref, props = {})
+        from = Registry.get(from_ref)
+        to   = Registry.get(to_ref)
+
+        raise FixtureError, "Missing from node: #{from_ref}" unless from
+        raise FixtureError, "Missing to node: #{to_ref}" unless to
+
+        from_conn = from.class.connection
+        to_conn   = to.class.connection
+
+        raise FixtureError, 'Cross-database relationship? Sorry, your data has commitment issues.' if from_conn != to_conn
+
+        from_label = from.class.labels.first
+        to_label   = to.class.labels.first
+
+        cypher = <<~CYPHER
+          MATCH (a:#{from_label} {name: $from_name}), (b:#{to_label} {name: $to_name})
+          CREATE (a)-[r:#{type} $props]->(b)
+          RETURN r
+        CYPHER
+
+        from_conn.execute_cypher(
+          cypher,
+          from_name: from.name,
+          to_name: to.name,
+          props: props
+        )
+
+        nil
+      end
+
+      # Bulk create relationships for performance using UNWIND batching
+      # @param rels [Array<Hash>] relationship definitions (from DSLContext)
+      # @param batch_size [Integer] batch size for UNWIND
+      def self.bulk_build(rels, batch_size: 200)
+        # Check all relationships for cross-DB violations first
+        rels.each do |rel|
+          from = Registry.get(rel[:from_ref])
+          to = Registry.get(rel[:to_ref])
+          raise FixtureError, "Both endpoints must exist: #{rel[:from_ref]}, #{rel[:to_ref]}" unless from && to
+
+          from_conn = from.class.connection
+          to_conn   = to.class.connection
+          raise FixtureError, 'Cross-database relationship? Sorry, your data has commitment issues.' if from_conn != to_conn
+        end
+
+        # Group by connection
+        grouped = rels.group_by do |rel|
+          from = Registry.get(rel[:from_ref])
+          from.class.connection
+        end
+
+        grouped.each do |conn, group|
+          group.each_slice(batch_size) do |batch|
+            unwind_batch = batch.map do |rel|
+              from = Registry.get(rel[:from_ref])
+              to   = Registry.get(rel[:to_ref])
+
+              {
+                from_name: from.name,
+                from_label: from.class.labels.first,
+                to_name: to.name,
+                to_label: to.class.labels.first,
+                props: rel[:props] || {},
+                type: rel[:type].to_s
+              }
+            end
+
+            cypher = <<~CYPHER
+              UNWIND $rows AS row
+              MATCH (a:#{unwind_batch.first[:from_label]} {name: row.from_name})
+              MATCH (b:#{unwind_batch.first[:to_label]} {name: row.to_name})
+              CREATE (a)-[r:#{unwind_batch.first[:type]} {props: row.props}]->(b)
+            CYPHER
+
+            conn.execute_cypher(cypher, rows: unwind_batch)
+          end
+        end
+      end
+    end
+  end
+end