familia 2.0.0.pre15 → 2.0.0.pre17

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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      module Indexing
+        # Generators for multi-value index (1:many) methods
+        #
+        # Multi-value indexes use UnsortedSet DataType for grouping objects by field value.
+        # Each field value gets its own set of object identifiers.
+        #
+        # Example:
+        #   multi_index :department, :dept_index, within: Company
+        #
+        # Generates on Company (destination):
+        #   - company.sample_from_department(dept, count=1)
+        #   - company.find_all_by_department(dept)
+        #   - company.dept_index_for(dept_value)
+        #   - company.rebuild_dept_index
+        #
+        # Generates on Employee (self):
+        #   - employee.add_to_company_dept_index(company)
+        #   - employee.remove_from_company_dept_index(company)
+        #   - employee.update_in_company_dept_index(company, old_dept)
+        module MultiIndexGenerators
+          module_function
+
+          using Familia::Refinements::StylizeWords
+
+          # Main setup method that orchestrates multi-value index creation
+          #
+          # @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] Parent class for instance-scoped index (required)
+          # @param query [Boolean] Whether to generate query methods
+          def setup(indexed_class:, field:, index_name:, within:, query:)
+            # Multi-index always requires a parent context
+            target_class = within
+            resolved_class = Familia.resolve_class(target_class)
+
+            # Store metadata for this indexing relationship
+            indexed_class.indexing_relationships << IndexingRelationship.new(
+              field:             field,
+              target_class:      target_class,
+              index_name:        index_name,
+              query:            query,
+              cardinality:       :multi,
+            )
+
+            # Always generate the factory method - required by mutation methods
+            if target_class.is_a?(Class)
+              generate_factory_method(resolved_class, index_name)
+            end
+
+            # Generate query methods on the parent class (optional)
+            if query && target_class.is_a?(Class)
+              generate_query_methods_destination(indexed_class, field, resolved_class, index_name)
+            end
+
+            # Generate mutation methods on the indexed class
+            generate_mutation_methods_self(indexed_class, field, resolved_class, index_name)
+          end
+
+          # Generates the factory method ON THE PARENT CLASS (Company when within: Company):
+          # - company.index_name_for(field_value) - DataType factory (always needed)
+          #
+          # This method is required by mutation methods even when query: false
+          #
+          # @param target_class [Class] The parent class (e.g., Company)
+          # @param index_name [Symbol] Name of the index (e.g., :dept_index)
+          def generate_factory_method(target_class, index_name)
+            actual_target_class = Familia.resolve_class(target_class)
+
+            actual_target_class.class_eval do
+              # Helper method to get index set for a specific field value
+              # This acts as a factory for field-value-specific DataTypes
+              define_method("#{index_name}_for") do |field_value|
+                # Return properly managed DataType instance with parameterized key
+                index_key = "#{index_name}:#{field_value}"
+                Familia::UnsortedSet.new(index_key, parent: self)
+              end
+            end
+          end
+
+          # Generates query methods ON THE PARENT CLASS (Company when within: Company):
+          # - company.sample_from_department(dept, count=1) - random sampling
+          # - company.find_all_by_department(dept) - all objects
+          # - company.rebuild_dept_index - rebuild index
+          #
+          # @param indexed_class [Class] The class being indexed (e.g., Employee)
+          # @param field [Symbol] The field to index (e.g., :department)
+          # @param target_class [Class] The parent class (e.g., Company)
+          # @param index_name [Symbol] Name of the index (e.g., :dept_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)
+
+            # Generate instance sampling method (e.g., company.sample_from_department)
+            actual_target_class.class_eval do
+
+              define_method("sample_from_#{field}") do |field_value, count = 1|
+                index_set = send("#{index_name}_for", field_value) # i.e. UnsortedSet
+
+                # Get random members efficiently (O(1) via SRANDMEMBER with count)
+                # Returns array even for count=1 for consistent API
+                index_set.sample(count).map do |id|
+                  indexed_class.new(index_set.deserialize_value(id))
+                end
+              end
+
+              # Generate bulk query method (e.g., company.find_all_by_department)
+              define_method("find_all_by_#{field}") do |field_value|
+                index_set = send("#{index_name}_for", field_value) # i.e. UnsortedSet
+
+                # Get all members from set
+                index_set.members.map { |id| indexed_class.new(id) }
+              end
+
+              # Generate method to rebuild the index for this parent instance
+              define_method("rebuild_#{index_name}") do
+                # This would need to be implemented based on how you track which
+                # objects belong to this parent instance
+                # For now, just a placeholder
+              end
+            end
+          end
+
+          # Generates mutation methods ON THE INDEXED CLASS (Employee):
+          # - employee.add_to_company_dept_index(company)
+          # - employee.remove_from_company_dept_index(company)
+          # - employee.update_in_company_dept_index(company, old_dept)
+          #
+          # @param indexed_class [Class] The class being indexed (e.g., Employee)
+          # @param field [Symbol] The field to index (e.g., :department)
+          # @param target_class [Class] The parent class (e.g., Company)
+          # @param index_name [Symbol] Name of the index (e.g., :dept_index)
+          def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
+            target_class_config = target_class.config_name
+            indexed_class.class_eval do
+              method_name = "add_to_#{target_class_config}_#{index_name}"
+              Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance|
+                return unless target_instance
+
+                field_value = send(field)
+                return unless field_value
+
+                # Use helper method on target instance instead of manual instantiation
+                index_set = target_instance.send("#{index_name}_for", field_value)
+
+                # Use UnsortedSet DataType method (no scoring)
+                index_set.add(identifier)
+              end
+
+              method_name = "remove_from_#{target_class_config}_#{index_name}"
+              Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance|
+                return unless target_instance
+
+                field_value = send(field)
+                return unless field_value
+
+                # Use helper method on target instance instead of manual instantiation
+                index_set = target_instance.send("#{index_name}_for", field_value)
+
+                # Remove using UnsortedSet DataType method
+                index_set.remove(identifier)
+              end
+
+              method_name = "update_in_#{target_class_config}_#{index_name}"
+              Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance, old_field_value = nil|
+                return unless target_instance
+
+                new_field_value = send(field)
+
+                # Use Familia's transaction method for atomicity with DataType abstraction
+                target_instance.transaction do |_tx|
+                  # Remove from old index if provided - use helper method
+                  if old_field_value
+                    old_index_set = target_instance.send("#{index_name}_for", old_field_value)
+                    old_index_set.remove(identifier)
+                  end
+
+                  # Add to new index if present - use helper method
+                  if new_field_value
+                    new_index_set = target_instance.send("#{index_name}_for", new_field_value)
+                    new_index_set.add(identifier)
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      module Indexing
+        # Generators for unique index (1:1) methods
+        #
+        # Unique indexes use HashKey DataType for field-to-object identifier mapping.
+        # Each field value maps to exactly one object identifier.
+        #
+        # Example (instance-scoped):
+        #   unique_index :badge_number, :badge_index, within: Company
+        #
+        # Generates on Company (destination):
+        #   - company.find_by_badge_number(badge)
+        #   - company.find_all_by_badge_number([badges])
+        #   - company.badge_index
+        #   - company.rebuild_badge_index
+        #
+        # Generates on Employee (self):
+        #   - employee.add_to_company_badge_index(company)
+        #   - employee.remove_from_company_badge_index(company)
+        #   - employee.update_in_company_badge_index(company, old_badge)
+        #
+        # Example (class-level):
+        #   unique_index :email, :email_index
+        #
+        # Generates on Employee (class):
+        #   - Employee.find_by_email(email)
+        #   - Employee.find_all_by_email([emails])
+        #   - Employee.email_index
+        #   - Employee.rebuild_email_index
+        #
+        # Generates on Employee (self):
+        #   - employee.add_to_class_email_index (called automatically on save)
+        #   - employee.remove_from_class_email_index
+        #   - employee.update_in_class_email_index(old_email)
+        #
+        # Note: Class-level indexes auto-populate on save(). Instance-scoped indexes
+        # (with within:) remain manual as they require parent context.
+        module UniqueIndexGenerators
+          module_function
+
+          using Familia::Refinements::StylizeWords
+
+          # Main setup method that orchestrates unique index creation
+          #
+          # @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 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
+              k = Familia.resolve_class(within)
+              [k, :instance]
+            else
+              [indexed_class, :class]
+            end
+
+            # Store metadata for this indexing relationship
+            indexed_class.indexing_relationships << IndexingRelationship.new(
+              field:             field,
+              target_class:      target_class,
+              index_name:        index_name,
+              query:             query,
+              cardinality:       :unique,
+            )
+
+            # Generate appropriate methods based on scope type
+            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)
+              end
+              generate_mutation_methods_self(indexed_class, field, target_class, index_name)
+            when :class
+              # Class-level index (no within:)
+              indexed_class.send(:ensure_index_field, indexed_class, index_name, :class_hashkey)
+              generate_query_methods_class(field, index_name, indexed_class) if query
+              generate_mutation_methods_class(field, index_name, indexed_class)
+            end
+          end
+
+          # Generates query methods ON THE PARENT 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
+          # - company.rebuild_badge_index - rebuild index
+          #
+          # @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 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)
+
+            # Ensure the index field is declared (creates accessor that returns DataType)
+            actual_target_class.send(:ensure_index_field, actual_target_class, index_name, :hashkey)
+
+            # Generate instance query method (e.g., company.find_by_badge_number)
+            actual_target_class.class_eval do
+              define_method("find_by_#{field}") do |field_value|
+                # Use declared field accessor instead of manual instantiation
+                index_hash = send(index_name)
+
+                # Get the identifier from the hash
+                object_id = index_hash[field_value.to_s]
+                return nil unless object_id
+
+                indexed_class.new(object_id)
+              end
+
+              # Generate bulk query method (e.g., company.find_all_by_badge_number)
+              define_method("find_all_by_#{field}") do |field_values|
+                field_values = Array(field_values)
+                return [] if field_values.empty?
+
+                # Use declared field accessor instead of manual instantiation
+                index_hash = send(index_name)
+
+                # Get all identifiers from the hash
+                object_ids = index_hash.values_at(*field_values.map(&:to_s))
+                # Filter out nil values and instantiate objects
+                object_ids.compact.map { |object_id| indexed_class.new(object_id) }
+              end
+
+              # Accessor method already created by ensure_index_field above
+              # No need to manually define it here
+
+              # Generate method to rebuild the unique index for this parent instance
+              define_method("rebuild_#{index_name}") do
+                # Use declared field accessor instead of manual instantiation
+                index_hash = send(index_name)
+
+                # Clear existing index using DataType method
+                index_hash.clear
+
+                # Rebuild from all existing objects
+                # This would need to scan through all objects belonging to this parent
+                # Implementation depends on how objects are stored/tracked
+              end
+            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)
+          # - employee.remove_from_company_badge_index(company)
+          # - employee.update_in_company_badge_index(company, old_badge)
+          #
+          # @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 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
+            indexed_class.class_eval do
+              method_name = "add_to_#{target_class_config}_#{index_name}"
+              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance|
+                return unless target_instance
+
+                field_value = send(field)
+                return unless field_value
+
+                # Use declared field accessor on target instance
+                index_hash = target_instance.send(index_name)
+
+                # Use HashKey DataType method
+                index_hash[field_value.to_s] = identifier
+              end
+
+              method_name = "remove_from_#{target_class_config}_#{index_name}"
+              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance|
+                return unless target_instance
+
+                field_value = send(field)
+                return unless field_value
+
+                # Use declared field accessor on target instance
+                index_hash = target_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}"
+              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |target_instance, old_field_value = nil|
+                return unless target_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)
+
+                  # Remove old value if provided
+                  index_hash.remove(old_field_value.to_s) if old_field_value
+
+                  # Add new value if present
+                  index_hash[new_field_value.to_s] = identifier if new_field_value
+                end
+              end
+            end
+          end
+
+          # Generates query methods ON THE INDEXED CLASS (Employee):
+          # Class-level methods (singleton):
+          # - Employee.find_by_email(email)
+          # - Employee.find_all_by_email([emails])
+          # - Employee.email_index
+          # - Employee.rebuild_email_index
+          def generate_query_methods_class(field, index_name, indexed_class)
+            indexed_class.define_singleton_method("find_by_#{field}") do |field_value|
+              index_hash = send(index_name) # Access the class-level hashkey DataType
+              object_id = index_hash[field_value.to_s]
+
+              return nil unless object_id
+
+              new(object_id)
+            end
+
+            # Generate class-level bulk query method
+            indexed_class.define_singleton_method("find_all_by_#{field}") do |field_values|
+              field_values = Array(field_values)
+              return [] if field_values.empty?
+
+              index_hash = send(index_name) # Access the class-level hashkey DataType
+              object_ids = index_hash.values_at(*field_values.map(&:to_s))
+              # Filter out nil values and instantiate objects
+              object_ids.compact.map { |object_id| new(object_id) }
+            end
+
+            # The index accessor method is already created by the class_hashkey declaration
+            # No need to manually create it - Horreum handles this automatically
+
+            # Generate method to rebuild the class-level index
+            indexed_class.define_singleton_method("rebuild_#{index_name}") do
+              index_hash = send(index_name) # Access the class-level hashkey DataType
+
+              # Clear existing index using DataType method
+              index_hash.clear
+
+              # Rebuild from all existing objects
+              # This would need to scan through all objects of this class
+              # Implementation depends on how objects are stored/tracked
+            end
+          end
+
+          # Generates mutation methods ON THE INDEXED CLASS (Employee):
+          # Instance methods for class-level index operations:
+          # - employee.add_to_class_email_index
+          # - employee.remove_from_class_email_index
+          # - employee.update_in_class_email_index(old_email)
+          def generate_mutation_methods_class(field, index_name, indexed_class)
+            indexed_class.class_eval do
+              define_method("add_to_class_#{index_name}") do
+                index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
+                field_value = send(field)
+
+                return unless field_value
+
+                index_hash[field_value.to_s] = identifier
+              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)
+
+                return unless field_value
+
+                index_hash.remove(field_value.to_s)
+              end
+
+              define_method("update_in_class_#{index_name}") do |old_field_value = nil|
+                new_field_value = send(field)
+
+                # Use class-level transaction for atomicity with DataType abstraction
+                self.class.transaction do |_tx|
+                  index_hash = self.class.send(index_name) # Access the class-level hashkey DataType
+
+                  # Remove old value if provided
+                  index_hash.remove(old_field_value.to_s) if old_field_value
+
+                  # Add new value if present
+                  index_hash[new_field_value.to_s] = identifier if new_field_value
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end