familia 2.0.0.pre18 → 2.0.0.pre19

data/lib/familia/features/relationships/indexing/unique_index_generators.rb

@@ -49,11 +49,11 @@ module Familia
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index
           # @param index_name [Symbol] Name of the index
-          # @param within [Class, Symbol, nil] Parent class for instance-scoped index
+          # @param within [Class, Symbol, nil] Scope class for instance-scoped index
           # @param query [Boolean] Whether to generate query methods
           def setup(indexed_class:, field:, index_name:, within:, query:)
             # Normalize parameters and determine scope type
-            target_class, scope_type = if within
+            scope_class, scope_type = if within
               k = Familia.resolve_class(within)
               [k, :instance]
             else
@@ -63,7 +63,8 @@ module Familia
             # Store metadata for this indexing relationship
             indexed_class.indexing_relationships << IndexingRelationship.new(
               field:             field,
-              target_class:      target_class,
+              scope_class:       scope_class,
+              within:            within,
               index_name:        index_name,
               query:             query,
               cardinality:       :unique,
@@ -73,10 +74,10 @@ module Familia
             case scope_type
             when :instance
               # Instance-scoped index (within: Company)
-              if query && target_class.is_a?(Class)
-                generate_query_methods_destination(indexed_class, field, target_class, index_name)
+              if query && scope_class.is_a?(Class)
+                generate_query_methods_destination(indexed_class, field, scope_class, index_name)
               end
-              generate_mutation_methods_self(indexed_class, field, target_class, index_name)
+              generate_mutation_methods_self(indexed_class, field, scope_class, index_name)
             when :class
               # Class-level index (no within:)
               indexed_class.send(:ensure_index_field, indexed_class, index_name, :class_hashkey)
@@ -85,7 +86,8 @@ module Familia
             end
           end
 
-          # Generates query methods ON THE PARENT CLASS (Company when within: Company):
+          # Generates query methods ON THE SCOPE CLASS (Company when within: Company)
+          #
           # - company.find_by_badge_number(badge) - find by field value
           # - company.find_all_by_badge_number([badges]) - batch lookup
           # - company.badge_index - DataType accessor
@@ -93,17 +95,17 @@ module Familia
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :badge_number)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :badge_index)
-          def generate_query_methods_destination(indexed_class, field, target_class, index_name)
-            # Resolve target class using Familia pattern
-            actual_target_class = Familia.resolve_class(target_class)
+          def generate_query_methods_destination(indexed_class, field, scope_class, index_name)
+            # Resolve scope class using Familia pattern
+            actual_scope_class = Familia.resolve_class(scope_class)
 
             # Ensure the index field is declared (creates accessor that returns DataType)
-            actual_target_class.send(:ensure_index_field, actual_target_class, index_name, :hashkey)
+            actual_scope_class.send(:ensure_index_field, actual_scope_class, index_name, :hashkey)
 
             # Generate instance query method (e.g., company.find_by_badge_number)
-            actual_target_class.class_eval do
+            actual_scope_class.class_eval do
               define_method(:"find_by_#{field}") do |provided_value|
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
@@ -121,7 +123,10 @@ module Familia
 
               # Generate bulk query method (e.g., company.find_all_by_badge_number)
               define_method(:"find_all_by_#{field}") do |provided_ids|
-                provided_ids = Array(provided_ids)
+                # Convert to array and filter nil inputs before querying Redis.
+                # This prevents wasteful lookups for empty string keys (nil.to_s → "").
+                # Output may contain fewer elements than input (standard ORM behavior).
+                provided_ids = Array(provided_ids).compact
                 return [] if provided_ids.empty?
 
                 # Use declared field accessor instead of manual instantiation
@@ -129,7 +134,8 @@ module Familia
 
                 # Get all identifiers from the hash
                 record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
-                # Filter out nil values and instantiate objects
+
+                # Filter out nil values (non-existent records) and instantiate objects
                 record_ids.compact.map { |record_id|
                   indexed_class.find_by_identifier(record_id)
                 }
@@ -153,63 +159,102 @@ module Familia
             end
           end
 
-          # Generates mutation methods ON THE INDEXED CLASS (Employee):
-          # Instance methods for parent-scoped unique index operations:
-          # - employee.add_to_company_badge_index(company)
+          # Generates mutation methods ON THE INDEXED CLASS (Employee)
+          #
+          # Instance methods for scope-scoped unique index operations:
+          # - employee.add_to_company_badge_index(company) - automatically validates uniqueness
           # - employee.remove_from_company_badge_index(company)
           # - employee.update_in_company_badge_index(company, old_badge)
+          # - employee.guard_unique_company_badge_index!(company) - manual validation
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :badge_number)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :badge_index)
-          def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
-            target_class_config = target_class.config_name
+          def generate_mutation_methods_self(indexed_class, field, scope_class, index_name)
+            scope_class_config = scope_class.config_name
             indexed_class.class_eval do
-              method_name = :"add_to_#{target_class_config}_#{index_name}"
+              method_name = :"add_to_#{scope_class_config}_#{index_name}"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use declared field accessor on target instance
-                index_hash = target_instance.send(index_name)
+                # Automatically validate uniqueness before adding to index.
+                # Skip validation inside transactions since guard methods require read
+                # operations not available in MULTI/EXEC blocks.
+                unless Fiber[:familia_transaction]
+                  guard_method = :"guard_unique_#{scope_class_config}_#{index_name}!"
+                  send(guard_method, scope_instance) if respond_to?(guard_method)
+                end
+
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
 
-                # Use HashKey DataType method
+                # Set the value (guard already validated uniqueness)
                 index_hash[field_value.to_s] = identifier
               end
 
-              method_name = :"remove_from_#{target_class_config}_#{index_name}"
+              # Add a guard method to enforce unique constraint on this instance-scoped index
+              #
+              # @param scope_instance [Object] The scope instance providing uniqueness context (e.g., a Company)
+              # @raise [Familia::RecordExistsError] if a record with the same field value
+              #   exists in the scope's index. Values are compared as strings.
+              # @return [void]
+              #
+              # @example
+              #   employee.guard_unique_company_badge_index!(company)
+              #
+              method_name = :"guard_unique_#{scope_class_config}_#{index_name}!"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use declared field accessor on target instance
-                index_hash = target_instance.send(index_name)
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
+                existing_id = index_hash.get(field_value.to_s)
+
+                if existing_id && existing_id != identifier
+                  raise Familia::RecordExistsError,
+                    "#{self.class} exists in #{scope_instance.class} with #{field}=#{field_value}"
+                end
+              end
+
+              method_name = :"remove_from_#{scope_class_config}_#{index_name}"
+              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
+
+                field_value = send(field)
+                return unless field_value
+
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
 
                 # Remove using HashKey DataType method
                 index_hash.remove(field_value.to_s)
               end
 
-              method_name = :"update_in_#{target_class_config}_#{index_name}"
+              method_name = :"update_in_#{scope_class_config}_#{index_name}"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance, old_field_value = nil|
-                return unless target_instance
+              define_method(method_name) do |scope_instance, old_field_value = nil|
+                return unless scope_instance
 
                 new_field_value = send(field)
 
                 # Use Familia's transaction method for atomicity with DataType abstraction
-                target_instance.transaction do |_tx|
-                  # Use declared field accessor on target instance
-                  index_hash = target_instance.send(index_name)
+                scope_instance.transaction do |_tx|
+                  # Use declared field accessor on scope instance
+                  index_hash = scope_instance.send(index_name)
 
                   # Remove old value if provided
                   index_hash.remove(old_field_value.to_s) if old_field_value
@@ -228,10 +273,12 @@ module Familia
           # - Employee.email_index
           # - Employee.rebuild_email_index
           def generate_query_methods_class(field, index_name, indexed_class)
+            # Generate class-level single record method
             indexed_class.define_singleton_method(:"find_by_#{field}") do |provided_id|
-              index_hash = send(index_name) # Access the class-level hashkey DataType
+              index_hash = send(index_name) # access the class-level hashkey DataType
 
-              # Get the identifier from the hash using .get method.
+              # Get the identifier from the db hashkey using .get method.
+              #
               # We use .get instead of [] because it's part of the standard interface
               # common across all DataType classes (List, UnsortedSet, SortedSet, HashKey).
               # While unique indexes always use HashKey, using .get maintains consistency
@@ -245,12 +292,18 @@ module Familia
 
             # Generate class-level bulk query method
             indexed_class.define_singleton_method(:"find_all_by_#{field}") do |provided_ids|
-              provided_ids = Array(provided_ids)
+              # Convert to array and filter nil inputs before querying Redis.
+              # This prevents wasteful lookups for empty string keys (nil.to_s → "").
+              # Output may contain fewer elements than input (standard ORM behavior).
+              provided_ids = Array(provided_ids).compact
               return [] if provided_ids.empty?
 
-              index_hash = send(index_name) # Access the class-level hashkey DataType
+              index_hash = send(index_name) # access the class-level hashkey DataType
+
+              # Get multiple identifiers from the db hashkey using .values_at
               record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
-              # Filter out nil values and instantiate objects
+
+              # Filter out nil values (non-existent records) and instantiate objects
               record_ids.compact.map { |record_id|
                 indexed_class.find_by_identifier(record_id)
               }
@@ -285,9 +338,28 @@ module Familia
 
                 return unless field_value
 
+                # Just set the value - uniqueness should be validated before save
                 index_hash[field_value.to_s] = identifier
               end
 
+              # Add a guard method to enforce unique constraint on this specific index
+              #
+              # @raise [Familia::RecordExistsError] if a record with the same
+              # field value exists. Values are compared as strings.
+              #
+              # @return [void]
+              define_method(:"guard_unique_#{index_name}!") do
+                field_value = send(field)
+                return unless field_value
+
+                index_hash = self.class.send(index_name)
+                existing_id = index_hash.get(field_value.to_s)
+
+                if existing_id && existing_id != identifier
+                  raise Familia::RecordExistsError, "#{self.class} exists #{field}=#{field_value}"
+                end
+              end
+
               define_method(:"remove_from_class_#{index_name}") do
                 index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
                 field_value = send(field)

data/lib/familia/features/relationships/indexing.rb

@@ -50,7 +50,7 @@ module Familia
       # Terminology:
       # - unique_index: 1:1 field-to-object mapping (HashKey)
       # - multi_index: 1:many field-to-objects mapping (UnsortedSet, no scores)
-      # - within: parent class for instance-scoped indexes
+      # - within: scope class providing uniqueness boundary for instance-scoped indexes
       # - query: whether to generate find_by_* methods (default: true)
       #
       # Key Patterns:
@@ -89,7 +89,7 @@ module Familia
           #
           # @param field [Symbol] The field to index on
           # @param index_name [Symbol] Name of the index
-          # @param within [Class, Symbol] The parent class that owns the index
+          # @param within [Class, Symbol] The scope class providing uniqueness context
           # @param query [Boolean] Whether to generate query methods
           #
           # @example Instance-scoped multi-value indexing
@@ -109,7 +109,7 @@ module Familia
           #
           # @param field [Symbol] The field to index on
           # @param index_name [Symbol] Name of the index hash
-          # @param within [Class, Symbol] Optional parent class for instance-scoped unique index
+          # @param within [Class, Symbol] Optional scope class for instance-scoped unique index
           # @param query [Boolean] Whether to generate query methods
           #
           # @example Class-level unique index
@@ -136,70 +136,68 @@ module Familia
 
           # Ensure proper DataType field is declared for index
           # Similar to ensure_collection_field in participation system
-          def ensure_index_field(target_class, index_name, field_type)
-            return if target_class.method_defined?(index_name) || target_class.respond_to?(index_name)
+          def ensure_index_field(scope_class, index_name, field_type)
+            return if scope_class.method_defined?(index_name) || scope_class.respond_to?(index_name)
 
-            target_class.send(field_type, index_name)
+            scope_class.send(field_type, index_name)
           end
         end
 
         # Instance methods for indexed objects
         module ModelInstanceMethods
-          # Update all indexes for a given parent context
-          # For class-level indexes (class_indexed_by), parent_context should be nil
-          # For relationship indexes (indexed_by), parent_context should be the parent instance
-          def update_all_indexes(old_values = {}, parent_context = nil)
+          # Update all indexes for a given scope context
+          # For class-level indexes (unique_index without within:), scope_context should be nil
+          # For instance-scoped indexes (with within:), scope_context should be the scope instance
+          def update_all_indexes(old_values = {}, scope_context = nil)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
               field = config.field
               index_name = config.index_name
-              target_class = config.target_class
               old_field_value = old_values[field]
 
               # Determine which update method to call
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:)
                 send("update_in_class_#{index_name}", old_field_value)
               else
-                # Relationship index (unique_index or multi_index with within:) - requires parent context
-                next unless parent_context
+                # Instance-scoped index (unique_index or multi_index with within:) - requires scope context
+                next unless scope_context
 
                 # Use config_name for method naming
-                target_class_config = Familia.resolve_class(config.target_class).config_name
-                send("update_in_#{target_class_config}_#{index_name}", parent_context, old_field_value)
+                scope_class_config = Familia.resolve_class(config.scope_class).config_name
+                send("update_in_#{scope_class_config}_#{index_name}", scope_context, old_field_value)
               end
             end
           end
 
-          # Remove from all indexes for a given parent context
-          # For class-level indexes (class_indexed_by), parent_context should be nil
-          # For relationship indexes (indexed_by), parent_context should be the parent instance
-          def remove_from_all_indexes(parent_context = nil)
+          # Remove from all indexes for a given scope context
+          # For class-level indexes (unique_index without within:), scope_context should be nil
+          # For instance-scoped indexes (with within:), scope_context should be the scope instance
+          def remove_from_all_indexes(scope_context = nil)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
               index_name = config.index_name
-              target_class = config.target_class
 
               # Determine which remove method to call
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:)
                 send("remove_from_class_#{index_name}")
               else
-                # Relationship index (unique_index or multi_index with within:) - requires parent context
-                next unless parent_context
+                # Instance-scoped index (unique_index or multi_index with within:) - requires scope context
+                next unless scope_context
 
                 # Use config_name for method naming
-                target_class_config = Familia.resolve_class(config.target_class).config_name
-                send("remove_from_#{target_class_config}_#{index_name}", parent_context)
+                scope_class_config = Familia.resolve_class(config.scope_class).config_name
+                send("remove_from_#{scope_class_config}_#{index_name}", scope_context)
               end
             end
           end
 
           # Get all indexes this object appears in
-          # Note: For target-scoped indexes, this only shows class-level indexes
-          # since target-scoped indexes require a specific target instance
+          # Note: For instance-scoped indexes, this only shows class-level indexes
+          # since instance-scoped indexes require a specific scope instance
           #
           # @return [Array<Hash>] Array of index information
           def current_indexings
@@ -210,19 +208,18 @@ module Familia
             self.class.indexing_relationships.each do |config|
               field = config.field
               index_name = config.index_name
-              target_class = config.target_class
               cardinality = config.cardinality
               field_value = send(field)
 
               next unless field_value
 
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:) - check hash key using DataType
                 index_hash = self.class.send(index_name)
                 next unless index_hash.key?(field_value.to_s)
 
                 memberships << {
-                  target_class: 'class',
+                  scope_class: 'class',
                   index_name: index_name,
                   field: field,
                   field_value: field_value,
@@ -231,17 +228,17 @@ module Familia
                   type: 'unique_index',
                 }
               else
-                # Instance-scoped index (unique_index or multi_index with within:) - cannot check without target instance
-                # This would require scanning all possible target instances
+                # Instance-scoped index (unique_index or multi_index with within:) - cannot check without scope instance
+                # This would require scanning all possible scope instances
                 memberships << {
-                  target_class: config.target_class_config_name,
+                  scope_class: config.scope_class_config_name,
                   index_name: index_name,
                   field: field,
                   field_value: field_value,
-                  index_key: 'target_dependent',
+                  index_key: 'scope_dependent',
                   cardinality: cardinality,
                   type: cardinality == :unique ? 'unique_index' : 'multi_index',
-                  note: 'Requires target instance for verification',
+                  note: 'Requires scope instance for verification',
                 }
               end
             end
@@ -249,9 +246,9 @@ module Familia
             memberships
           end
 
-          # Check if this object is indexed in a specific target
+          # Check if this object is indexed in a specific scope
           # For class-level indexes, checks the hash key
-          # For target-scoped indexes, returns false (requires target instance)
+          # For instance-scoped indexes, returns false (requires scope instance)
           def indexed_in?(index_name)
             return false unless self.class.respond_to?(:indexing_relationships)
 
@@ -262,14 +259,12 @@ module Familia
             field_value = send(field)
             return false unless field_value
 
-            target_class = config.target_class
-
-            if target_class == self.class
+            if config.within.nil?
               # Class-level index (class_indexed_by) - check hash key using DataType
               index_hash = self.class.send(index_name)
               index_hash.key?(field_value.to_s)
             else
-              # Target-scoped index (indexed_by) - cannot verify without target instance
+              # Instance-scoped index (with within:) - cannot verify without scope instance
               false
             end
           end

data/lib/familia/features/relationships/indexing_relationship.rb

@@ -14,20 +14,30 @@ module Familia
       # Similar to ParticipationRelationship but for attribute-based lookups
       # rather than collection membership.
       #
+      # Terminology:
+      # - `scope_class`: The class that provides the uniqueness boundary for
+      #   instance-scoped indexes. For example, in `unique_index :badge_number,
+      #   :badge_index, within: Company`, the Company is the scope class.
+      # - `within`: Preserves the original DSL parameter to explicitly distinguish
+      #   class-level indexes (within: nil) from instance-scoped indexes (within:
+      #   SomeClass). This avoids brittle class comparisons and prevents issues
+      #   with inheritance scenarios.
+      #
       IndexingRelationship = Data.define(
         :field,              # Symbol - field being indexed (e.g., :email, :department)
         :index_name,         # Symbol - name of the index (e.g., :email_index, :dept_index)
-        :target_class,       # Class/Symbol - parent class for instance-scoped indexes (within:)
+        :scope_class,        # Class/Symbol - scope class for instance-scoped indexes (within:)
+        :within,             # Class/Symbol/nil - within: parameter (nil for class-level, Class for instance-scoped)
         :cardinality,        # Symbol - :unique (1:1) or :multi (1:many)
         :query               # Boolean - whether to generate query  methods
       ) do
         #
-        # Get the normalized config name for the target class
+        # Get the normalized config name for the scope class
         #
         # @return [String] The config name (e.g., "user", "company", "test_company")
         #
-        def target_class_config_name
-          target_class.config_name
+        def scope_class_config_name
+          scope_class.config_name
         end
       end
     end

data/lib/familia/field_type.rb

@@ -143,7 +143,8 @@ module Familia
           val = args.first
 
           # If no value provided, return current stored value
-          return hget(field_name) if val.nil?
+          # Handle Redis::Future objects during transactions
+          return hget(field_name) if val.nil? || val.is_a?(Redis::Future)
 
           begin
             # Trace the operation if debugging is enabled

data/lib/familia/horreum/connection.rb

@@ -6,40 +6,16 @@ module Familia
     # Provides connection handling, transactions, and URI normalization for both
     # class-level operations (e.g., Customer.dbclient) and instance-level operations
     # (e.g., customer.dbclient)
+    #
+    # Includes shared connection behavior from Familia::Connection::Behavior, providing:
+    # - URI normalization (normalize_uri)
+    # - Connection creation (create_dbclient)
+    # - Transaction method signatures
+    # - Pipeline method signatures
     module Connection
-      attr_reader :uri
-
-      # Normalizes various URI formats to a consistent URI object
-      # Considers the class/instance logical_database when uri is nil or Integer
-      def normalize_uri(uri)
-        case uri
-        when Integer
-          new_uri = Familia.uri.dup
-          new_uri.db = uri
-          new_uri
-        when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) }
-          URI.parse(uri)
-        when URI
-          uri
-        when nil
-          # Use logical_database if available, otherwise fall back to Familia.uri
-          if respond_to?(:logical_database) && logical_database
-            new_uri = Familia.uri.dup
-            new_uri.db = logical_database
-            new_uri
-          else
-            Familia.uri
-          end
-        else
-          raise ArgumentError, "Invalid URI type: #{uri.class.name}"
-        end
-      end
+      include Familia::Connection::Behavior
 
-      # Creates a new Database connection instance using the class/instance configuration
-      def create_dbclient(uri = nil)
-        parsed_uri = normalize_uri(uri)
-        Familia.create_dbclient(parsed_uri)
-      end
+      attr_reader :uri
 
       # Returns the Database connection for the class using Chain of Responsibility pattern.
       #
@@ -277,9 +253,9 @@ module Familia
         @provider_connection_handler ||= Familia::Connection::ProviderConnectionHandler.new
 
         # Determine the appropriate class context
-        # When called from instance: self is instance, self.class is the model class
-        # When called from class: self is the model class
-        klass = self.is_a?(Class) ? self : self.class
+        # When called from instance: self is instance, use the model class connection
+        # When called from class: we'll use our own connection
+        klass = is_a?(Class) ? self : self.class
 
         # Always check class first for @dbclient since instance-level connections were removed
         @cached_connection_handler ||= Familia::Connection::CachedConnectionHandler.new(klass)