familia 2.0.0.pre7 → 2.0.0.pre10

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

@@ -17,21 +17,25 @@ module Familia
           # Define an indexed_by relationship for fast lookups
           #
           # @param field [Symbol] The field to index on
-          # @param context [Class, Symbol] The context class that owns the index
           # @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
           #
           # @example Basic indexing
-          #   indexed_by :display_name, context: Customer, index_name: :domain_index
+          #   indexed_by :display_name, parent: Customer, index_name: :domain_index
           #
-          # @example Global indexing
-          #   indexed_by :domain_id, context: :global, index_name: :domain_lookup
-          def indexed_by(field, index_name, context:, finder: true)
-            context_class = context == :global ? :global : context
-            context_class_name = if context_class == :global
-                                   'global'
+          # @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
-                                   (context_class.is_a?(Class) ? context_class.name : context_class.to_s.camelize)
+                                   # For symbol parent, convert to string
+                                   context_class.to_s
                                  end
 
             # Store metadata for this indexing relationship
@@ -44,14 +48,38 @@ module Familia
             }
 
             # Generate finder methods on the context class
-            if finder && context_class != :global
+            if finder && context_class.is_a?(Class)
               generate_context_finder_methods(context_class, field, index_name)
-            elsif finder && context_class == :global
-              generate_global_finder_methods(field, index_name)
             end
 
-            # Generate instance methods for maintaining the index
-            generate_indexing_instance_methods(context_class_name, field, index_name)
+            # Generate instance methods for relationship indexing
+            generate_relationship_index_methods(context_class_name, field, index_name)
+          end
+
+          # Define a class-level indexed lookup
+          #
+          # @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
+          #
+          # @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 << {
+              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)
           end
 
           # Get all indexing relationships for this class
@@ -61,63 +89,49 @@ module Familia
 
           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(context_class.to_s.camelize)
+            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_method("find_by_#{field}") do |field_value|
-              index_key = "#{self.class.name.downcase}:#{identifier}:#{index_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
 
-              # Find the indexed class and instantiate the object
-              indexed_class = nil
-              self.class.const_get(:INDEXED_CLASSES, false)&.each do |klass|
-                if klass.indexing_relationships.any? { |rel| rel[:index_name] == index_name }
-                  indexed_class = klass
-                  break
-                end
-              end
-
-              indexed_class&.new(identifier: object_id)
+              indexed_class.new(object_id)
             end
 
             # Generate bulk finder method (e.g., Customer.find_all_by_display_name)
-            actual_context_class.define_method("find_all_by_#{field}") do |field_values|
+            actual_context_class.define_singleton_method("find_all_by_#{field}") do |field_values|
               return [] if field_values.empty?
 
-              index_key = "#{self.class.name.downcase}:#{identifier}:#{index_name}"
+              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
-              found_objects = object_ids.compact.filter_map do |object_id|
-                # Find the indexed class and instantiate the object
-                indexed_class = nil
-                self.class.const_get(:INDEXED_CLASSES, false)&.each do |klass|
-                  if klass.indexing_relationships.any? { |rel| rel[:index_name] == index_name }
-                    indexed_class = klass
-                    break
-                  end
-                end
-
-                indexed_class&.new(identifier: object_id)
-              end
-
-              found_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_method(index_name) do
-              index_key = "#{self.class.name.downcase}:#{identifier}:#{index_name}"
-              Familia::HashKey.new(nil, dbkey: index_key, logical_database: self.class.logical_database)
+            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_method("rebuild_#{index_name}") do
-              index_key = "#{self.class.name.downcase}:#{identifier}:#{index_name}"
+            actual_context_class.define_singleton_method("rebuild_#{index_name}") do
+              index_key = "#{self.name.downcase}:#{index_name}"
 
               # Clear existing index
               dbclient.del(index_key)
@@ -128,38 +142,38 @@ module Familia
             end
           end
 
-          # Generate global finder methods (when context is :global)
-          def generate_global_finder_methods(field, index_name)
-            # Generate global finder method (e.g., Domain.find_by_display_name_globally)
-            define_method("find_by_#{field}_globally") do |field_value|
-              index_key = "global:#{index_name}"
+          # 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(identifier: object_id)
+              new(object_id)
             end
 
-            # Generate global bulk finder method
-            define_method("find_all_by_#{field}_globally") do |field_values|
+            # Generate class-level bulk finder method
+            define_singleton_method("find_all_by_#{field}") do |field_values|
               return [] if field_values.empty?
 
-              index_key = "global:#{index_name}"
+              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| new(identifier: object_id) }
+              object_ids.compact.map { |object_id| self.new(object_id) }
             end
 
-            # Generate method to get the global index hash directly
-            define_method("global_#{index_name}") do
-              index_key = "global:#{index_name}"
+            # 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 global index
-            define_method("rebuild_global_#{index_name}") do
-              index_key = "global:#{index_name}"
+            # 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)
@@ -170,74 +184,72 @@ module Familia
             end
           end
 
-          # Generate instance methods for maintaining indexes
-          def generate_indexing_instance_methods(context_class_name, field, index_name)
-            # Method to add this object to a specific index
-            # e.g., domain.add_to_customer_domain_index(customer)
-            if context_class_name == 'global'
-              # Global index methods
-              define_method("add_to_global_#{index_name}") do
-                index_key = "global:#{index_name}"
-                field_value = send(field)
+          # 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
+              return unless field_value
 
-                dbclient.hset(index_key, field_value.to_s, identifier)
-              end
+              dbclient.hset(index_key, field_value.to_s, identifier)
+            end
 
-              define_method("remove_from_global_#{index_name}") do
-                index_key = "global:#{index_name}"
-                field_value = send(field)
+            define_method("remove_from_class_#{index_name}") do
+              index_key = "#{self.class.name.downcase}:#{index_name}"
+              field_value = send(field)
 
-                return unless field_value
+              return unless field_value
 
-                dbclient.hdel(index_key, field_value.to_s)
-              end
+              dbclient.hdel(index_key, field_value.to_s)
+            end
 
-              define_method("update_in_global_#{index_name}") do |old_field_value = nil|
-                index_key = "global:#{index_name}"
-                new_field_value = send(field)
+            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
+              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
+                # Add new value if present
+                tx.hset(index_key, new_field_value.to_s, identifier) if new_field_value
               end
-            else
-              define_method("add_to_#{context_class_name.downcase}_#{index_name}") do |context_instance|
-                index_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{index_name}"
-                field_value = send(field)
+            end
+          end
 
-                return unless field_value
+          # 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)
 
-                dbclient.hset(index_key, field_value.to_s, identifier)
-              end
+              return unless field_value
 
-              # Method to remove this object from a specific index
-              define_method("remove_from_#{context_class_name.downcase}_#{index_name}") do |context_instance|
-                index_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{index_name}"
-                field_value = send(field)
+              dbclient.hset(index_key, field_value.to_s, identifier)
+            end
 
-                return unless field_value
+            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)
 
-                dbclient.hdel(index_key, field_value.to_s)
-              end
+              return unless field_value
+
+              dbclient.hdel(index_key, field_value.to_s)
+            end
 
-              # Method to update this object in a specific index (handles field value changes)
-              define_method("update_in_#{context_class_name.downcase}_#{index_name}") do |context_instance, old_field_value = nil|
-                index_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{index_name}"
-                new_field_value = send(field)
+            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
+              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
+                # Add new value if present
+                tx.hset(index_key, new_field_value.to_s, identifier) if new_field_value
               end
             end
           end
@@ -245,49 +257,44 @@ module Familia
 
         # Instance methods for indexed objects
         module InstanceMethods
-          # Update all indexes that this object participates in
+          # Update all indexes
           def update_all_indexes(old_values = {})
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
               field = config[:field]
-              context_class_name = config[:context_class_name]
               index_name = config[:index_name]
-
+              context_class = config[:context_class]
               old_field_value = old_values[field]
 
-              if context_class_name == 'global'
-                send("update_in_global_#{index_name}", old_field_value)
+              # Determine which update method to call
+              if context_class == self.class
+                # Class-level index (class_indexed_by)
+                send("update_in_class_#{index_name}", old_field_value)
               else
-                # For non-global indexes, we'd need to know which context instances
-                # this object should be indexed in. This is a simplified approach.
-                # In practice, you'd need to track relationships or pass context.
+                # 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)
               end
             end
           end
 
-          # Remove from all indexes (used during destroy)
+          # Remove from all indexes
           def remove_from_all_indexes
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
-              field = config[:field]
-              context_class_name = config[:context_class_name]
               index_name = config[:index_name]
+              context_class = config[:context_class]
 
-              if context_class_name == 'global'
-                send("remove_from_global_#{index_name}")
+              # Determine which remove method to call
+              if context_class == self.class
+                # Class-level index (class_indexed_by)
+                send("remove_from_class_#{index_name}")
               else
-                # For non-global indexes, we'd need to find all context instances
-                # that have this object indexed. This is expensive but necessary for cleanup.
-                pattern = "#{context_class_name.downcase}:*:#{index_name}"
-                field_value = send(field)
-
-                next unless field_value
-
-                dbclient.scan_each(match: pattern) do |key|
-                  dbclient.hdel(key, field_value.to_s)
-                end
+                # Relationship index (indexed_by with parent:)
+                context_class_name = config[:context_class_name].downcase
+                send("remove_from_#{context_class_name}_#{index_name}", nil)
               end
             end
           end
@@ -302,40 +309,23 @@ module Familia
 
             self.class.indexing_relationships.each do |config|
               field = config[:field]
-              context_class_name = config[:context_class_name]
               index_name = config[:index_name]
+              context_class = config[:context_class]
               field_value = send(field)
 
               next unless field_value
 
-              if context_class_name == 'global'
-                index_key = "global:#{index_name}"
-                if dbclient.hexists(index_key, field_value.to_s)
-                  memberships << {
-                    context_class: 'global',
-                    index_name: index_name,
-                    field: field,
-                    field_value: field_value,
-                    index_key: index_key
-                  }
-                end
-              else
-                # Scan for all context instances that have this object indexed
-                pattern = "#{context_class_name.downcase}:*:#{index_name}"
-
-                dbclient.scan_each(match: pattern) do |key|
-                  if dbclient.hexists(key, field_value.to_s)
-                    context_id = key.split(':')[1]
-                    memberships << {
-                      context_class: context_class_name,
-                      context_id: context_id,
-                      index_name: index_name,
-                      field: field,
-                      field_value: field_value,
-                      index_key: key
-                    }
-                  end
-                end
+              # All indexes are stored at class level
+              index_key = "#{self.class.name.downcase}:#{index_name}"
+              if dbclient.hexists(index_key, field_value.to_s)
+                memberships << {
+                  context_class: context_class == self.class ? 'class' : config[:context_class_name].downcase,
+                  index_name: index_name,
+                  field: field,
+                  field_value: field_value,
+                  index_key: index_key,
+                  type: context_class == self.class ? 'class_indexed_by' : 'indexed_by'
+                }
               end
             end
 
@@ -343,7 +333,7 @@ module Familia
           end
 
           # Check if this object is indexed in a specific context
-          def indexed_in?(context_instance, index_name)
+          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 }
@@ -353,17 +343,11 @@ module Familia
             field_value = send(field)
             return false unless field_value
 
-            if config[:context_class_name] == 'global'
-              index_key = "global:#{index_name}"
-            else
-              context_class_name = config[:context_class_name]
-              index_key = "#{context_class_name.downcase}:#{context_instance.identifier}:#{index_name}"
-            end
-
+            # 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)
           end
         end
-
       end
     end
   end

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

@@ -44,32 +44,15 @@ module Familia
             # Method to add this object to the owner's collection
             # e.g., domain.add_to_customer_domains(customer)
             define_method("add_to_#{owner_class_name_lower}_#{collection_name}") do |owner_instance, score = nil|
-              collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
-
-              case type
-              when :sorted_set
-                score ||= calculate_membership_score(owner_class, collection_name)
-                dbclient.zadd(collection_key, score, identifier)
-              when :set
-                dbclient.sadd(collection_key, identifier)
-              when :list
-                dbclient.lpush(collection_key, identifier)
-              end
+              collection = owner_instance.send(collection_name)
+              collection.add(identifier, score: score)
             end
 
             # Method to remove this object from the owner's collection
             # e.g., domain.remove_from_customer_domains(customer)
             define_method("remove_from_#{owner_class_name_lower}_#{collection_name}") do |owner_instance|
-              collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
-
-              case type
-              when :sorted_set
-                dbclient.zrem(collection_key, identifier)
-              when :set
-                dbclient.srem(collection_key, identifier)
-              when :list
-                dbclient.lrem(collection_key, 0, identifier)
-              end
+              collection = owner_instance.send(collection_name)
+              collection.remove(identifier)
             end
 
             # Method to check if this object is in the owner's collection
@@ -77,6 +60,9 @@ module Familia
             define_method("in_#{owner_class_name_lower}_#{collection_name}?") do |owner_instance|
               collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
 
+              # TODO: We should be able to reduce this to a single method call on the DataType class
+              # instance, like we do for remove above (why: each the HashKey, SortedSet, UnsortedSet,
+              # and List classes have a `remove` method that implements the correct behaviour).
               case type
               when :sorted_set
                 !dbclient.zscore(collection_key, identifier).nil?
@@ -123,6 +109,9 @@ module Familia
             define_method("add_to_#{owner_class_name_lower}_#{collection_name}") do |owner_instance, score = nil|
               collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
 
+              # TODO: We should be able to reduce this to a single method call on the DataType class
+              # instance, like we do for remove above (why: each the HashKey, SortedSet, UnsortedSet,
+              # and List classes have a `remove` method that implements the correct behaviour).
               case type
               when :sorted_set
                 # Find the owner class from the stored config
@@ -144,6 +133,9 @@ module Familia
             define_method("remove_from_#{owner_class_name_lower}_#{collection_name}") do |owner_instance|
               collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
 
+              # TODO: We should be able to reduce this to a single method call on the DataType class
+              # instance, like we do for remove above (why: each the HashKey, SortedSet, UnsortedSet,
+              # and List classes have a `remove` method that implements the correct behaviour).
               case type
               when :sorted_set
                 dbclient.zrem(collection_key, identifier)
@@ -159,6 +151,9 @@ module Familia
             define_method("in_#{owner_class_name_lower}_#{collection_name}?") do |owner_instance|
               collection_key = "#{owner_class_name_lower}:#{owner_instance.identifier}:#{collection_name}"
 
+              # TODO: We should be able to reduce this to a single method call on the DataType class
+              # instance, like we do for remove above (why: each the HashKey, SortedSet, UnsortedSet,
+              # and List classes have a `remove` method that implements the correct behaviour).
               case type
               when :sorted_set
                 dbclient.zscore(collection_key, identifier) != nil
@@ -496,7 +491,6 @@ module Familia
             true
           end
         end
-
       end
     end
   end

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

@@ -303,17 +303,15 @@ module Familia
                 permission_bits = decoded[:permissions]
 
                 # Check if this member has the required permission bits
-                if (permission_bits & required_bits) == required_bits
-                  valid_members << [score, member]
-                end
+                valid_members << [score, member] if (permission_bits & required_bits) == required_bits
               end
 
               # Recreate filtered collection if we have valid members
-              if valid_members.any?
-                dbclient.zadd(filtered_key, valid_members)
-                dbclient.expire(filtered_key, 300) # Temporary key cleanup
-                filtered_keys << filtered_key
-              end
+              next unless valid_members.any?
+
+              dbclient.zadd(filtered_key, valid_members)
+              dbclient.expire(filtered_key, 300) # Temporary key cleanup
+              filtered_keys << filtered_key
             end
 
             filtered_keys
@@ -341,9 +339,7 @@ module Familia
               permission_bits = decoded[:permissions]
 
               # Check if this member has the required permission bits
-              if (permission_bits & required_bits) == required_bits
-                valid_members << [score, member]
-              end
+              valid_members << [score, member] if (permission_bits & required_bits) == required_bits
             end
 
             # Create filtered collection
@@ -613,7 +609,6 @@ module Familia
             collection_info
           end
         end
-
       end
     end
   end

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

@@ -40,7 +40,7 @@ module Familia
           configure: 0b00010000,  # 16  - Change settings
           delete:    0b00100000,  # 32  - Remove items
           transfer:  0b01000000,  # 64  - Change ownership
-          admin:     0b10000000   # 128 - Full control
+          admin:     0b10000000,  # 128 - Full control
         }.freeze
 
         # Predefined permission combinations
@@ -60,7 +60,6 @@ module Familia
           owner:          0b11111111   # All permissions
         }.freeze
 
-
         class << self
           # Get permission bit flag value for a permission symbol
           #
@@ -93,7 +92,6 @@ module Familia
             }
           end
 
-
           # Encode a timestamp and permissions into a Redis score
           #
           # @param timestamp [Time, Integer] The timestamp to encode