familia 2.0.0.pre8 → 2.0.0.pre12

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

@@ -34,6 +34,35 @@ module Familia
             word.to_s.split('_').map(&:capitalize).join
           end
 
+          # Define a class-level tracked collection
+          #
+          # @param collection_name [Symbol] Name of the class-level collection
+          # @param score [Symbol, Proc, nil] How to calculate the score
+          # @param on_destroy [Symbol] What to do when object is destroyed (:remove, :ignore)
+          #
+          # @example Class-level tracking (using class_ prefix convention)
+          #   class_tracked_in :all_customers, score: :created_at
+          #   class_tracked_in :active_users, score: -> { status == 'active' ? Time.now.to_i : 0 }
+          def class_tracked_in(collection_name, score: nil, on_destroy: :remove)
+
+            klass_name = (name || self.to_s).downcase
+
+            # Store metadata for this tracking relationship
+            tracking_relationships << {
+              context_class: klass_name,
+              context_class_name: name || self.to_s,
+              collection_name: collection_name,
+              score: score,
+              on_destroy: on_destroy
+            }
+
+            # Generate class-level collection methods
+            generate_tracking_class_methods(self, collection_name)
+
+            # Generate instance methods for class-level tracking
+            generate_tracking_instance_methods('class', collection_name, score)
+          end
+
           # Define a tracked_in relationship
           #
           # @param context_class [Class, Symbol] The class that owns the collection
@@ -49,10 +78,9 @@ module Familia
           #   tracked_in Team, :domains, score: :added_at
           #   tracked_in Organization, :all_domains, score: :created_at
           def tracked_in(context_class, collection_name, score: nil, on_destroy: :remove)
-            # Handle special :global context
-            if context_class == :global
-              context_class_name = 'Global'
-            elsif context_class.is_a?(Class)
+
+            # Handle class context
+            if context_class.is_a?(Class)
               class_name = context_class.name
               context_class_name = if class_name.include?('::')
                                      # Extract the last part after the last ::
@@ -60,7 +88,6 @@ module Familia
                                    else
                                      class_name
                                    end
-            # Extract just the class name, handling anonymous classes
             else
               context_class_name = camelize_word(context_class)
             end
@@ -74,12 +101,8 @@ module Familia
               on_destroy: on_destroy
             }
 
-            # Generate class methods on the context class (skip for global)
-            if context_class == :global
-              generate_global_class_methods(self, collection_name)
-            else
-              generate_context_class_methods(context_class, collection_name)
-            end
+            # Generate context class methods
+            generate_context_class_methods(context_class, collection_name)
 
             # Generate instance methods on this class
             generate_tracking_instance_methods(context_class_name, collection_name, score)
@@ -92,21 +115,21 @@ module Familia
 
           private
 
-          # Generate global collection methods (e.g., Domain.global_all_domains)
-          def generate_global_class_methods(target_class, collection_name)
-            # Generate global collection getter method
-            target_class.define_singleton_method("global_#{collection_name}") do
-              collection_key = "global:#{collection_name}"
+          # Generate class-level collection methods (e.g., User.all_users)
+          def generate_tracking_class_methods(target_class, collection_name)
+            # Generate class-level collection getter method
+            target_class.define_singleton_method("#{collection_name}") do
+              collection_key = "#{self.name.downcase}:#{collection_name}"
               Familia::SortedSet.new(nil, dbkey: collection_key, logical_database: logical_database)
             end
 
-            # Generate global add method (e.g., Domain.add_to_global_all_domains)
+            # Generate class-level add method (e.g., User.add_to_all_users)
             target_class.define_singleton_method("add_to_#{collection_name}") do |item, score = nil|
-              collection = send("global_#{collection_name}")
+              collection = send("#{collection_name}")
 
               # Calculate score if not provided
               score ||= if item.respond_to?(:calculate_tracking_score)
-                          item.calculate_tracking_score(:global, collection_name)
+                          item.calculate_tracking_score('class', collection_name)
                         else
                           item.current_score
                         end
@@ -117,9 +140,9 @@ module Familia
               collection.add(score, item.identifier)
             end
 
-            # Generate global remove method
+            # Generate class-level remove method
             target_class.define_singleton_method("remove_from_#{collection_name}") do |item|
-              collection = send("global_#{collection_name}")
+              collection = send("#{collection_name}")
               collection.delete(item.identifier)
             end
           end
@@ -304,6 +327,23 @@ module Familia
             end
           end
 
+          # Add to class-level tracking collections automatically
+          def add_to_class_tracking_collections
+            return unless self.class.respond_to?(:tracking_relationships)
+
+            self.class.tracking_relationships.each do |config|
+              context_class_name = config[:context_class_name]
+              context_class = config[:context_class]
+              collection_name = config[:collection_name]
+
+              # Only auto-add to class-level collections (where context_class matches self.class)
+              if context_class_name.downcase == self.class.name.downcase
+                # Call the class method to add this object
+                self.class.send("add_to_#{collection_name}", self)
+              end
+            end
+          end
+
           # Remove from all tracking collections (used during destroy)
           def remove_from_all_tracking_collections
             return unless self.class.respond_to?(:tracking_relationships)

data/lib/familia/features/relationships.rb

@@ -49,8 +49,8 @@ module Familia
     #     tracked_in Organization, :all_domains, score: :created_at
     #
     #     # O(1) lookups with Redis hashes
-    #     indexed_by :display_name, in: Customer, index_name: :domain_index
-    #     indexed_by :display_name, in: :global, index_name: :global_domain_index
+    #     indexed_by :display_name, :domain_index, context: Customer
+    #     indexed_by :display_name, :global_domain_index, context: :global
     #
     #     # Context-aware membership (no method collisions)
     #     member_of Customer, :domains
@@ -66,7 +66,7 @@ module Familia
     #
     #   # Indexing methods
     #   Customer.find_by_display_name(name) # O(1) lookup
-    #   Domain.find_by_display_name_globally(name) # Global lookup
+    #   Domain.find_by_display_name(name) # Global lookup
     #
     #   # Membership methods (collision-free naming)
     #   domain.add_to_customer_domains(customer)  # Specific collection
@@ -264,15 +264,22 @@ module Familia
           # This can be overridden by subclasses to set up initial relationships
         end
 
-        # Override save to update relationships
+        # Override save to update relationships automatically
         def save(update_expiration: true)
           result = super
 
-          if result && respond_to?(:update_all_indexes)
-            # Update all indexes with current field values
-            update_all_indexes
+          if result
+            # Automatically update all indexes when object is saved
+            if respond_to?(:update_all_indexes)
+              update_all_indexes
+            end
+
+            # Auto-add to class-level tracking collections
+            if respond_to?(:add_to_class_tracking_collections)
+              add_to_class_tracking_collections
+            end
 
-            # NOTE: Tracking and membership updates are typically done explicitly
+            # NOTE: Relationship-specific membership and tracking updates are done explicitly
             # since we need to know which specific collections this object should be in
           end
 

data/lib/familia/features/safe_dump.rb

@@ -1,12 +1,18 @@
 # lib/familia/features/safe_dump.rb
 
+# rubocop:disable ThreadSafety/ClassInstanceVariable
+#
+#   Class instance variables are used here for feature configuration
+#   (e.g., @dump_method, @load_method). These are set once and not mutated
+#   at runtime, so thread safety is not a concern for this feature.
+#
 module Familia::Features
   # SafeDump is a mixin that allows models to define a list of fields that are
   # safe to dump. This is useful for serializing objects to JSON or other
   # formats where you want to ensure that only certain fields are exposed.
   #
-  # To use SafeDump, include it in your model and define a list of fields that
-  # are safe to dump. The fields can be either symbols or hashes. If a field is
+  # To use SafeDump, include it in your model and use the DSL methods to define
+  # safe dump fields. The fields can be either symbols or hashes. If a field is
   # a symbol, the method with the same name will be called on the object to
   # retrieve the value. If the field is a hash, the key is the field name and
   # the value is a lambda that will be called with the object as an argument.
@@ -19,97 +25,85 @@ module Familia::Features
   #
   #   feature :safe_dump
   #
-  #   @safe_dump_fields = [
-  #     :objid,
-  #     :updated,
-  #     :created,
-  #     { :active => ->(obj) { obj.active? } }
-  #   ]
+  #   safe_dump_field :objid
+  #   safe_dump_field :updated
+  #   safe_dump_field :created
+  #   safe_dump_field :active, ->(obj) { obj.active? }
   #
-  # Internally, all fields are normalized to the hash syntax and stored in
-  # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
-  # of symbols in the order they were defined. From the example above, it would
-  # return `[:objid, :updated, :created, :active]`.
-  #
-  # Standalone Usage:
-  #
-  # You can also use SafeDump by including it in your model and defining the
-  # safe dump fields using the class instance variable `@safe_dump_fields`.
-  #
-  # Example:
+  # Alternatively, you can define multiple fields at once:
   #
-  #   class MyModel
-  #     include Familia::Features::SafeDump
+  #   safe_dump_fields :objid, :updated, :created,
+  #                    { active: ->(obj) { obj.active? } }
   #
-  #     @safe_dump_fields = [
-  #       :id, :name, { active: ->(obj) { obj.active? } }
-  #     ]
-  #   end
+  # Internally, all fields are normalized to the hash syntax and stored in
+  # @safe_dump_field_map. `SafeDump.safe_dump_fields` returns only the list
+  # of symbols in the order they were defined.
   #
   module SafeDump
     @dump_method = :to_json
     @load_method = :from_json
 
-    @safe_dump_fields = []
-    @safe_dump_field_map = {}
-
     def self.included(base)
-      Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
+      Familia.trace(:LOADED, self, base, caller(1..1)) if Familia.debug?
       base.extend ClassMethods
 
-      # Optionally define safe_dump_fields in the class to make
-      # sure we always have an array to work with.
-      base.instance_variable_set(:@safe_dump_fields, []) unless base.instance_variable_defined?(:@safe_dump_fields)
-
-      # Ditto for the field map
-      return if base.instance_variable_defined?(:@safe_dump_field_map)
-
+      # Initialize the safe dump field map
       base.instance_variable_set(:@safe_dump_field_map, {})
     end
 
+    # SafeDump::ClassMethods
+    #
+    # These methods become available on the model class
     module ClassMethods
-      def set_safe_dump_fields(*fields)
-        @safe_dump_fields = fields
+      # Define a single safe dump field
+      # @param field_name [Symbol] The name of the field
+      # @param callable [Proc, nil] Optional callable to transform the value
+      def safe_dump_field(field_name, callable = nil)
+        @safe_dump_field_map ||= {}
+
+        field_name = field_name.to_sym
+        field_value = callable || lambda { |obj|
+          if obj.respond_to?(:[]) && obj[field_name]
+            obj[field_name] # Familia::DataType classes
+          elsif obj.respond_to?(field_name)
+            obj.send(field_name) # Regular method calls
+          end
+        }
+
+        @safe_dump_field_map[field_name] = field_value
       end
 
-      # `SafeDump.safe_dump_fields` returns only the list
-      # of symbols in the order they were defined.
-      def safe_dump_fields
-        @safe_dump_fields.map do |field|
-          field.is_a?(Symbol) ? field : field.keys.first
+      # Define multiple safe dump fields at once
+      # @param fields [Array] Mixed array of symbols and hashes
+      def safe_dump_fields(*fields)
+        # If no arguments, return field names (getter behavior)
+        return safe_dump_field_names if fields.empty?
+
+        # Otherwise, define fields (setter behavior)
+        fields.each do |field|
+          if field.is_a?(Symbol)
+            safe_dump_field(field)
+          elsif field.is_a?(Hash)
+            field.each do |name, callable|
+              safe_dump_field(name, callable)
+            end
+          end
         end
       end
 
-      # `SafeDump.safe_dump_field_map` returns the field map
-      # that is used to dump the fields. The keys are the
-      # field names and the values are callables that will
-      # expect to receive the instance object as an argument.
-      #
-      # The map is cached on the first call to this method.
-      #
+      # Returns an array of safe dump field names in the order they were defined
+      def safe_dump_field_names
+        (@safe_dump_field_map || {}).keys
+      end
+
+      # Returns the field map used for dumping
       def safe_dump_field_map
-        return @safe_dump_field_map if @safe_dump_field_map.any?
+        @safe_dump_field_map || {}
+      end
 
-        # Operate directly on the @safe_dump_fields array to
-        # build the map. This way we'll get the elements defined
-        # in the hash syntax (i.e. since the safe_dump_fields getter
-        # method returns only the symbols).
-        @safe_dump_field_map = @safe_dump_fields.each_with_object({}) do |el, map|
-          if el.is_a?(Symbol)
-            field_name = el
-            callable = lambda { |obj|
-              if obj.respond_to?(:[]) && obj[field_name]
-                obj[field_name] # Familia::DataType classes
-              elsif obj.respond_to?(field_name)
-                obj.send(field_name) # Onetime::Models::RedisHash classes via method_missing 😩
-              end
-            }
-          else
-            field_name = el.keys.first
-            callable = el.values.first
-          end
-          map[field_name] = callable
-        end
+      # Legacy method for setting safe dump fields (for backward compatibility)
+      def set_safe_dump_fields(*fields)
+        safe_dump_fields(*fields)
       end
     end
 
@@ -155,5 +149,5 @@ module Familia::Features
 
     Familia::Base.add_feature self, :safe_dump
   end
-  # end SafeDump
 end
+# rubocop:enable ThreadSafety/ClassInstanceVariable

data/lib/familia/features.rb

@@ -5,18 +5,108 @@ module Familia
 
   # Familia::Features
   #
+  # This module provides the feature system for Familia classes. Features are
+  # modular capabilities that can be mixed into classes with configurable options.
+  # Features provide a powerful way to:
+  #
+  # - **Add new methods**: Both class and instance methods can be added
+  # - **Override existing methods**: Extend or replace default behavior
+  # - **Add new fields**: Define additional data storage capabilities
+  # - **Manage complexity**: Large, complex model classes can use features to
+  #   organize functionality into focused, reusable modules
+  #
+  # ## Feature Options Storage
+  #
+  # Feature options are stored **per-class** using class-level instance variables.
+  # This means each Familia::Horreum subclass maintains its own isolated set of
+  # feature options. When you enable a feature with options in different models,
+  # each model stores its own separate configuration without interference.
+  #
+  # ## Project Organization with Autoloader
+  #
+  # For large projects, use {Familia::Features::Autoloader} to automatically load
+  # project-specific features from a dedicated directory structure. This helps
+  # organize complex models by separating features into individual files.
+  #
+  # @example Different models with different feature options
+  #   class UserModel < Familia::Horreum
+  #     feature :object_identifier, generator: :uuid_v4
+  #   end
+  #
+  #   class SessionModel < Familia::Horreum
+  #     feature :object_identifier, generator: :hex
+  #   end
+  #
+  #   UserModel.feature_options(:object_identifier)    #=> {generator: :uuid_v4}
+  #   SessionModel.feature_options(:object_identifier) #=> {generator: :hex}
+  #
+  # @example Using features for complexity management
+  #   class ComplexModel < Familia::Horreum
+  #     # Organize functionality using features
+  #     feature :expiration           # TTL management
+  #     feature :safe_dump           # API-safe serialization
+  #     feature :relationships       # CRUD operations for related objects
+  #     feature :custom_validation   # Project-specific validation logic
+  #     feature :audit_trail         # Change tracking
+  #   end
+  #
+  # @example Project-specific features with autoloader
+  #   # In your model file: app/models/customer.rb
+  #   class Customer < Familia::Horreum
+  #     module Features
+  #       include Familia::Features::Autoloader
+  #       # Automatically loads all .rb files from app/models/customer/features/
+  #     end
+  #   end
+  #
+  # @see Familia::Features::Autoloader For automatic feature loading
+  #
   module Features
     @features_enabled = nil
     attr_reader :features_enabled
 
+    # Enables a feature for the current class with optional configuration.
+    #
+    # Features are modular capabilities that can be mixed into Familia::Horreum
+    # classes. Each feature can be configured with options that are stored
+    # **per-class**, ensuring complete isolation between different models.
+    #
+    # @param feature_name [Symbol, String, nil] the name of the feature to enable.
+    #   If nil, returns the list of currently enabled features.
+    # @param options [Hash] configuration options for the feature. These are
+    #   stored per-class and do not interfere with other models' configurations.
+    # @return [Array, nil] the list of enabled features if feature_name is nil,
+    #   otherwise nil
+    #
+    # @example Enable feature without options
+    #   class User < Familia::Horreum
+    #     feature :expiration
+    #   end
+    #
+    # @example Enable feature with options (per-class storage)
+    #   class User < Familia::Horreum
+    #     feature :object_identifier, generator: :uuid_v4
+    #   end
+    #
+    #   class Session < Familia::Horreum
+    #     feature :object_identifier, generator: :hex  # Different options
+    #   end
+    #
+    #   # Each class maintains separate options:
+    #   User.feature_options(:object_identifier)    #=> {generator: :uuid_v4}
+    #   Session.feature_options(:object_identifier) #=> {generator: :hex}
+    #
+    # @raise [Familia::Problem] if the feature is not supported
+    #
     def feature(feature_name = nil, **options)
       @features_enabled ||= []
 
       return features_enabled if feature_name.nil?
 
-      # If there's a value provied check that it's a valid feature
+      # If there's a value provided check that it's a valid feature
       feature_name = feature_name.to_sym
-      unless Familia::Base.features_available.key?(feature_name)
+      feature_class = Familia::Base.find_feature(feature_name, self)
+      unless feature_class
         raise Familia::Problem, "Unsupported feature: #{feature_name}"
       end
 
@@ -46,10 +136,8 @@ module Familia
         add_feature_options(feature_name, **options)
       end
 
-      klass = Familia::Base.features_available[feature_name]
-
       # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-      include klass
+      include feature_class
 
       # NOTE: Do we want to extend Familia::DataType here? That would make it
       # possible to call safe_dump on relations fields (e.g. list, zset, hashkey).

data/lib/familia/horreum/subclass/definition.rb

@@ -177,6 +177,8 @@ module Familia
       # configuration values. This is particularly useful when mapping
       # familia models with specific database numbers in the configuration.
       #
+      # Familia::Horreum::DefinitionMethods#config_name
+      #
       # @example V2::Session.config_name => 'session'
       #
       # @return [String] The underscored class name as a string
@@ -235,10 +237,36 @@ module Familia
         field_types[field_type.name] = field_type
       end
 
-      # Get feature options for a specific feature or all features
+      # Retrieves feature options for the current class.
+      #
+      # Feature options are stored **per-class** in instance variables, ensuring
+      # complete isolation between different Familia::Horreum subclasses. Each
+      # class maintains its own @feature_options hash that does not interfere
+      # with other classes' configurations.
+      #
+      # @param feature_name [Symbol, String, nil] the name of the feature to get options for.
+      #   If nil, returns the entire feature options hash for this class.
+      # @return [Hash] the feature options hash, either for a specific feature or all features
+      #
+      # @example Getting options for a specific feature
+      #   class MyModel < Familia::Horreum
+      #     feature :object_identifier, generator: :uuid_v4
+      #   end
+      #
+      #   MyModel.feature_options(:object_identifier) #=> {generator: :uuid_v4}
+      #   MyModel.feature_options                     #=> {object_identifier: {generator: :uuid_v4}}
+      #
+      # @example Per-class isolation
+      #   class UserModel < Familia::Horreum
+      #     feature :object_identifier, generator: :uuid_v4
+      #   end
       #
-      # @param feature_name [Symbol, nil] The feature name to get options for
-      # @return [Hash] The options hash for the feature, or empty hash if none
+      #   class SessionModel < Familia::Horreum
+      #     feature :object_identifier, generator: :hex
+      #   end
+      #
+      #   UserModel.feature_options(:object_identifier)    #=> {generator: :uuid_v4}
+      #   SessionModel.feature_options(:object_identifier) #=> {generator: :hex}
       #
       def feature_options(feature_name = nil)
         @feature_options ||= {}
@@ -253,10 +281,28 @@ module Familia
       # without worrying about initialization state. Similar to register_field_type
       # for field types.
       #
+      # Feature options are stored at the **class level** using instance variables,
+      # ensuring complete isolation between different Familia::Horreum subclasses.
+      # Each class maintains its own @feature_options hash.
+      #
       # @param feature_name [Symbol] The feature name
       # @param options [Hash] The options to add/merge
       # @return [Hash] The updated options for the feature
       #
+      # @note This method only sets defaults for options that don't already exist,
+      #   using the ||= operator to prevent overwrites.
+      #
+      # @example Per-class storage behavior
+      #   class ModelA < Familia::Horreum
+      #     # This stores options in ModelA's @feature_options
+      #     add_feature_options(:my_feature, key: 'value_a')
+      #   end
+      #
+      #   class ModelB < Familia::Horreum
+      #     # This stores options in ModelB's @feature_options (separate from ModelA)
+      #     add_feature_options(:my_feature, key: 'value_b')
+      #   end
+      #
       def add_feature_options(feature_name, **options)
   @feature_options ||= {}
   @feature_options[feature_name.to_sym] ||= {}

data/lib/familia/horreum.rb

@@ -104,39 +104,30 @@ module Familia
         args = []
       end
 
-      # Initialize object with arguments using one of three strategies:
+      # Initialize object with arguments using one of four strategies:
       #
-      # 1. **Keyword Arguments** (Recommended): Order-independent field assignment
-      #    Example: Customer.new(name: "John", email: "john@example.com")
-      #    - Robust against field reordering
-      #    - Self-documenting
-      #    - Only sets provided fields
+      # 1. **Identifier** (Recommended for lookups): A single argument is treated as the identifier.
+      #    Example: Customer.new("cust_123")
+      #    - Robust and convenient for creating objects from an ID.
       #
-      # 2. **Positional Arguments** (Legacy): Field assignment by definition order
-      #    Example: Customer.new("john@example.com", "password123")
-      #    - Brittle: breaks if field order changes
-      #    - Compact syntax
-      #    - Maps to fields in class definition order
+      # 2. **Keyword Arguments** (Recommended for creation): Order-independent field assignment
+      #    Example: Customer.new(name: "John", email: "john@example.com")
       #
-      # 3. **No Arguments**: Object created with all fields as nil
-      #    - Minimal memory footprint in Redis
-      #    - Fields set on-demand via accessors or save()
-      #    - Avoids default value conflicts with nil-skipping serialization
+      # 3. **Positional Arguments** (Legacy): Field assignment by definition order
+      #    Example: Customer.new("cust_123", "John", "john@example.com")
       #
-      # Note: We iterate over self.class.fields (not kwargs) to ensure only
-      # defined fields are set, preventing typos from creating undefined attributes.
+      # 4. **No Arguments**: Object created with all fields as nil
       #
-      if kwargs.any?
+      if args.size == 1 && kwargs.empty?
+        id_field = self.class.identifier_field
+        send(:"#{id_field}=", args.first)
+      elsif kwargs.any?
         initialize_with_keyword_args(**kwargs)
       elsif args.any?
         initialize_with_positional_args(*args)
       else
-      Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
-        # Default values are intentionally NOT set here to:
-        # - Maintain Database memory efficiency (only store non-nil values)
-        # - Avoid conflicts with nil-skipping serialization logic
-        # - Preserve consistent exists? behavior (empty vs default-filled objects)
-        # - Keep initialization lightweight for unused fields
+        Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
+        # Default values are intentionally NOT set here
       end
 
       # Implementing classes can define an init method to do any