familia 2.0.0.pre15 → 2.0.0.pre17

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

@@ -1,85 +1,132 @@
 # lib/familia/features/relationships/indexing.rb
 
+require_relative 'indexing_relationship'
+require_relative 'indexing/multi_index_generators'
+require_relative 'indexing/unique_index_generators'
+
 module Familia
   module Features
     module Relationships
-      # Indexing module for indexed_by relationships using Redis hashes
-      # Provides O(1) lookups for finding objects by field values
+      # Indexing module for attribute-based lookups using Valkey/Redis data structures.
+      # Provides O(1) field-to-object mappings without relationship semantics.
+      #
+      # @example Class-level unique index (1:1 mapping via HashKey)
+      #   class User < Familia::Horreum
+      #     feature :relationships
+      #     field :email
+      #     unique_index :email, :email_lookup
+      #   end
+      #
+      #   user = User.new(user_id: 'u1', email: 'alice@example.com')
+      #   user.save  # Automatically populates email_lookup index
+      #   User.find_by_email('alice@example.com')  # → user
+      #
+      # @example Instance-scoped unique index (within parent, 1:1 via HashKey)
+      #   class Employee < Familia::Horreum
+      #     feature :relationships
+      #     field :badge_number
+      #     unique_index :badge_number, :badge_index, within: Company
+      #   end
+      #
+      #   company = Company.new(company_id: 'c1')
+      #   employee = Employee.new(emp_id: 'e1', badge_number: '12345')
+      #   employee.add_to_company_badge_index(company)
+      #   company.find_by_badge_number('12345')  # → employee
+      #
+      # @example Instance-scoped multi-value index (within parent, 1:many via UnsortedSet)
+      #   class Employee < Familia::Horreum
+      #     feature :relationships
+      #     field :department
+      #     multi_index :department, :dept_index, within: Company
+      #   end
+      #
+      #   company = Company.new(company_id: 'c1')
+      #   emp1 = Employee.new(emp_id: 'e1', department: 'engineering')
+      #   emp2 = Employee.new(emp_id: 'e2', department: 'engineering')
+      #   emp1.add_to_company_dept_index(company)
+      #   emp2.add_to_company_dept_index(company)
+      #   company.find_all_by_department('engineering')  # → [emp1, emp2]
+      #
+      # 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
+      # - query: whether to generate find_by_* methods (default: true)
+      #
+      # Key Patterns:
+      # - Class unique: "user:email_index" → HashKey
+      # - Instance unique: "company:c1:badge_index" → HashKey
+      # - Instance multi: "company:c1:dept_index:engineering" → UnsortedSet
+      #
+      # Auto-Indexing:
+      # Class-level unique_index declarations automatically populate on save():
+      #   user = User.new(email: 'test@example.com')
+      #   user.save  # Auto-indexes email → user_id
+      # Instance-scoped indexes (with within:) remain manual (require parent context).
+      #
+      # Design Philosophy:
+      # Indexing is for finding objects by attribute, not ordering them.
+      # Use multi_index with UnsortedSet (no temporal scores), then sort in Ruby:
+      #   employees = company.find_all_by_department('eng')
+      #   sorted = employees.sort_by(&:hire_date)
+
       module Indexing
+        using Familia::Refinements::StylizeWords
+
         # Class-level indexing configurations
         def self.included(base)
-          base.extend ClassMethods
-          base.include InstanceMethods
+          base.extend ModelClassMethods
+          base.include ModelInstanceMethods
           super
         end
 
-        module ClassMethods
+        # Indexing::ModelClassMethods
+        #
+        module ModelClassMethods
           # Define an indexed_by relationship for fast lookups
           #
+          # Define a multi-value index (1:many mapping)
+          #
           # @param field [Symbol] The field to index on
-          # @param index_name [Symbol] Name of the index hash
-          # @param parent [Class, Symbol] The parent class that owns the index
-          # @param finder [Boolean] Whether to generate finder methods
+          # @param index_name [Symbol] Name of the index
+          # @param within [Class, Symbol] The parent class that owns the index
+          # @param query [Boolean] Whether to generate query methods
           #
-          # @example Basic indexing
-          #   indexed_by :display_name, parent: Customer, index_name: :domain_index
+          # @example Instance-scoped multi-value indexing
+          #   multi_index :department, :dept_index, within: Company
           #
-          # @example Parent-based indexing
-          #   indexed_by :user_id, :user_memberships, parent: User
-          def indexed_by(field, index_name, parent:, finder: true)
-            context_class = parent
-            context_class_name = if context_class.is_a?(Class)
-                                   # Extract just the class name without module prefixes or object representations
-                                   class_name = context_class.name
-                                   class_name = class_name.split('::').last if class_name
-                                   class_name || context_class.to_s.split('::').last
-                                 else
-                                   # For symbol parent, convert to string
-                                   context_class.to_s
-                                 end
-
-            # Store metadata for this indexing relationship
-            indexing_relationships << {
+          def multi_index(field, index_name, within:, query: true)
+            MultiIndexGenerators.setup(
+              indexed_class: self,
               field: field,
-              context_class: context_class,
-              context_class_name: context_class_name,
               index_name: index_name,
-              finder: finder
-            }
-
-            # Generate finder methods on the context class
-            if finder && context_class.is_a?(Class)
-              generate_context_finder_methods(context_class, field, index_name)
-            end
-
-            # Generate instance methods for relationship indexing
-            generate_relationship_index_methods(context_class_name, field, index_name)
+              within: within,
+              query: query,
+            )
           end
 
-          # Define a class-level indexed lookup
+          # Define a unique index lookup (1:1 mapping)
           #
           # @param field [Symbol] The field to index on
           # @param index_name [Symbol] Name of the index hash
-          # @param finder [Boolean] Whether to generate finder methods
+          # @param within [Class, Symbol] Optional parent class for instance-scoped unique index
+          # @param query [Boolean] Whether to generate query methods
+          #
+          # @example Class-level unique index
+          #   unique_index :email, :email_lookup
+          #   unique_index :username, :username_lookup, query: false
+          #
+          # @example Instance-scoped unique index
+          #   unique_index :badge_number, :badge_index, within: Company
           #
-          # @example Class-level indexing (using class_ prefix convention)
-          #   class_indexed_by :email, :email_lookup
-          #   class_indexed_by :username, :username_lookup, finder: false
-          def class_indexed_by(field, index_name, finder: true)
-            # Store metadata for this indexing relationship
-            indexing_relationships << {
+          def unique_index(field, index_name, within: nil, query: true)
+            UniqueIndexGenerators.setup(
+              indexed_class: self,
               field: field,
-              context_class: self,
-              context_class_name: name,
               index_name: index_name,
-              finder: finder
-            }
-
-            # Generate class-level finder methods if requested
-            generate_class_finder_methods(field, index_name) if finder
-
-            # Generate instance methods for class-level indexing
-            generate_direct_index_methods(field, index_name)
+              within: within,
+              query: query,
+            )
           end
 
           # Get all indexing relationships for this class
@@ -87,244 +134,114 @@ module Familia
             @indexing_relationships ||= []
           end
 
-          private
-
-          # Helper method to camelize a word without ActiveSupport dependency
-          def camelize_word(word)
-            word.to_s.split('_').map(&:capitalize).join
-          end
-
-          # Generate finder methods on the context class (e.g., Customer.find_by_display_name)
-          def generate_context_finder_methods(context_class, field, index_name)
-            # Resolve context class if it's a symbol/string
-            actual_context_class = context_class.is_a?(Class) ? context_class : Object.const_get(camelize_word(context_class))
-
-            # Store reference to the indexed class for the finder methods
-            indexed_class = self
-
-            # Generate finder method (e.g., Customer.find_by_display_name)
-            actual_context_class.define_singleton_method("find_by_#{field}") do |field_value|
-              index_key = "#{self.name.downcase}:#{index_name}"
-              object_id = dbclient.hget(index_key, field_value.to_s)
-
-              return nil unless object_id
-
-              indexed_class.new(object_id)
-            end
-
-            # Generate bulk finder method (e.g., Customer.find_all_by_display_name)
-            actual_context_class.define_singleton_method("find_all_by_#{field}") do |field_values|
-              return [] if field_values.empty?
-
-              index_key = "#{self.name.downcase}:#{index_name}"
-              object_ids = dbclient.hmget(index_key, *field_values.map(&:to_s))
-
-              # Filter out nil values and instantiate objects
-              object_ids.compact.map { |object_id| indexed_class.new(object_id) }
-            end
-
-            # Generate method to get the index hash directly
-            actual_context_class.define_singleton_method(index_name) do
-              index_key = "#{self.name.downcase}:#{index_name}"
-              Familia::HashKey.new(nil, dbkey: index_key, logical_database: logical_database)
-            end
-
-            # Generate method to rebuild the index
-            actual_context_class.define_singleton_method("rebuild_#{index_name}") do
-              index_key = "#{self.name.downcase}:#{index_name}"
-
-              # Clear existing index
-              dbclient.del(index_key)
-
-              # This is a simplified version - in practice, you'd need to iterate
-              # through all objects that should be in this index
-              # Implementation would depend on how you track which objects belong to this context
-            end
-          end
-
-          # Generate class-level finder methods
-          def generate_class_finder_methods(field, index_name)
-            # Generate class-level finder method (e.g., Domain.find_by_display_name)
-            define_singleton_method("find_by_#{field}") do |field_value|
-              index_key = "#{self.name.downcase}:#{index_name}"
-              object_id = dbclient.hget(index_key, field_value.to_s)
-
-              return nil unless object_id
-
-              new(object_id)
-            end
-
-            # Generate class-level bulk finder method
-            define_singleton_method("find_all_by_#{field}") do |field_values|
-              return [] if field_values.empty?
-
-              index_key = "#{self.name.downcase}:#{index_name}"
-              object_ids = dbclient.hmget(index_key, *field_values.map(&:to_s))
-
-              # Filter out nil values and instantiate objects
-              object_ids.compact.map { |object_id| self.new(object_id) }
-            end
-
-            # Generate method to get the class-level index hash directly
-            define_singleton_method("#{index_name}") do
-              index_key = "#{self.name.downcase}:#{index_name}"
-              Familia::HashKey.new(nil, dbkey: index_key, logical_database: logical_database)
-            end
-
-            # Generate method to rebuild the class-level index
-            define_singleton_method("rebuild_#{index_name}") do
-              index_key = "#{self.name.downcase}:#{index_name}"
-
-              # Clear existing index
-              dbclient.del(index_key)
-
-              # 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
-
-          # Generate instance methods for class-level indexing (class_indexed_by)
-          def generate_direct_index_methods(field, index_name)
-            # Class-level index methods
-            define_method("add_to_class_#{index_name}") do
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              field_value = send(field)
-
-              return unless field_value
-
-              dbclient.hset(index_key, field_value.to_s, identifier)
-            end
-
-            define_method("remove_from_class_#{index_name}") do
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              field_value = send(field)
-
-              return unless field_value
-
-              dbclient.hdel(index_key, field_value.to_s)
-            end
-
-            define_method("update_in_class_#{index_name}") do |old_field_value = nil|
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              new_field_value = send(field)
-
-              dbclient.multi do |tx|
-                # Remove old value if provided
-                tx.hdel(index_key, old_field_value.to_s) if old_field_value
-
-                # Add new value if present
-                tx.hset(index_key, new_field_value.to_s, identifier) if new_field_value
-              end
-            end
-          end
-
-          # Generate instance methods for relationship indexing (indexed_by with parent:)
-          def generate_relationship_index_methods(context_class_name, field, index_name)
-            # All indexes are stored at class level - parent is only conceptual
-            define_method("add_to_#{context_class_name.downcase}_#{index_name}") do |context_instance = nil|
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              field_value = send(field)
-
-              return unless field_value
+          # 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)
 
-              dbclient.hset(index_key, field_value.to_s, identifier)
-            end
-
-            define_method("remove_from_#{context_class_name.downcase}_#{index_name}") do |context_instance = nil|
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              field_value = send(field)
-
-              return unless field_value
-
-              dbclient.hdel(index_key, field_value.to_s)
-            end
-
-            define_method("update_in_#{context_class_name.downcase}_#{index_name}") do |context_instance = nil, old_field_value = nil|
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              new_field_value = send(field)
-
-              dbclient.multi do |tx|
-                # Remove old value if provided
-                tx.hdel(index_key, old_field_value.to_s) if old_field_value
-
-                # Add new value if present
-                tx.hset(index_key, new_field_value.to_s, identifier) if new_field_value
-              end
-            end
+            target_class.send(field_type, index_name)
           end
         end
 
         # Instance methods for indexed objects
-        module InstanceMethods
-          # Update all indexes
-          def update_all_indexes(old_values = {})
+        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)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
-              field = config[:field]
-              index_name = config[:index_name]
-              context_class = config[:context_class]
+              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 context_class == self.class
-                # Class-level index (class_indexed_by)
+              if target_class == self.class
+                # Class-level index (unique_index without within:)
                 send("update_in_class_#{index_name}", old_field_value)
               else
-                # Relationship index (indexed_by with parent:)
-                context_class_name = config[:context_class_name].downcase
-                send("update_in_#{context_class_name}_#{index_name}", nil, old_field_value)
+                # Relationship index (unique_index or multi_index with within:) - requires parent context
+                next unless parent_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)
               end
             end
           end
 
-          # Remove from all indexes
-          def remove_from_all_indexes
+          # 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)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
-              index_name = config[:index_name]
-              context_class = config[:context_class]
+              index_name = config.index_name
+              target_class = config.target_class
 
               # Determine which remove method to call
-              if context_class == self.class
-                # Class-level index (class_indexed_by)
+              if target_class == self.class
+                # Class-level index (unique_index without within:)
                 send("remove_from_class_#{index_name}")
               else
-                # Relationship index (indexed_by with parent:)
-                context_class_name = config[:context_class_name].downcase
-                send("remove_from_#{context_class_name}_#{index_name}", nil)
+                # Relationship index (unique_index or multi_index with within:) - requires parent context
+                next unless parent_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)
               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
           #
           # @return [Array<Hash>] Array of index information
-          def indexing_memberships
+          def current_indexings
             return [] unless self.class.respond_to?(:indexing_relationships)
 
             memberships = []
 
             self.class.indexing_relationships.each do |config|
-              field = config[:field]
-              index_name = config[:index_name]
-              context_class = config[:context_class]
+              field = config.field
+              index_name = config.index_name
+              target_class = config.target_class
+              cardinality = config.cardinality
               field_value = send(field)
 
               next unless field_value
 
-              # All indexes are stored at class level
-              index_key = "#{self.class.name.downcase}:#{index_name}"
-              if dbclient.hexists(index_key, field_value.to_s)
+              if target_class == self.class
+                # 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 << {
-                  context_class: context_class == self.class ? 'class' : config[:context_class_name].downcase,
+                  target_class: 'class',
                   index_name: index_name,
                   field: field,
                   field_value: field_value,
-                  index_key: index_key,
-                  type: context_class == self.class ? 'class_indexed_by' : 'indexed_by'
+                  index_key: index_hash.dbkey,
+                  cardinality: cardinality,
+                  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
+                memberships << {
+                  target_class: config.target_class_config_name,
+                  index_name: index_name,
+                  field: field,
+                  field_value: field_value,
+                  index_key: 'target_dependent',
+                  cardinality: cardinality,
+                  type: cardinality == :unique ? 'unique_index' : 'multi_index',
+                  note: 'Requires target instance for verification',
                 }
               end
             end
@@ -332,20 +249,29 @@ module Familia
             memberships
           end
 
-          # Check if this object is indexed in a specific context
+          # Check if this object is indexed in a specific target
+          # For class-level indexes, checks the hash key
+          # For target-scoped indexes, returns false (requires target instance)
           def indexed_in?(index_name)
             return false unless self.class.respond_to?(:indexing_relationships)
 
-            config = self.class.indexing_relationships.find { |rel| rel[:index_name] == index_name }
+            config = self.class.indexing_relationships.find { |rel| rel.index_name == index_name }
             return false unless config
 
-            field = config[:field]
+            field = config.field
             field_value = send(field)
             return false unless field_value
 
-            # For the cleaned-up API, all indexes are class-level
-            index_key = "#{self.class.name.downcase}:#{index_name}"
-            dbclient.hexists(index_key, field_value.to_s)
+            target_class = config.target_class
+
+            if target_class == self.class
+              # 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
+              false
+            end
           end
         end
       end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      using Familia::Refinements::StylizeWords
+
+      # IndexingRelationship
+      #
+      # Stores metadata about indexing relationships defined at class level.
+      # Used to configure code generation and runtime behavior for unique_index
+      # and multi_index declarations.
+      #
+      # Similar to ParticipationRelationship but for attribute-based lookups
+      # rather than collection membership.
+      #
+      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:)
+        :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
+        #
+        # @return [String] The config name (e.g., "user", "company", "test_company")
+        #
+        def target_class_config_name
+          target_class.config_name
+        end
+      end
+    end
+  end
+end