familia 2.0.0.pre7 → 2.0.0.pre10

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)
@@ -372,7 +412,6 @@ module Familia
             memberships
           end
         end
-
       end
     end
   end

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/transient_fields.rb

@@ -182,9 +182,7 @@ module Familia
       def clear_transient_fields!
         self.class.transient_fields.each do |field_name|
           field_value = instance_variable_get("@#{field_name}")
-          if field_value.respond_to?(:clear!)
-            field_value.clear!
-          end
+          field_value.clear! if field_value.respond_to?(:clear!)
         end
       end
 
@@ -213,13 +211,13 @@ module Familia
       def transient_fields_summary
         self.class.transient_fields.each_with_object({}) do |field_name, summary|
           field_value = instance_variable_get("@#{field_name}")
-          if field_value.nil?
-            summary[field_name] = nil
-          elsif field_value.respond_to?(:cleared?) && field_value.cleared?
-            summary[field_name] = "[CLEARED]"
-          else
-            summary[field_name] = "[REDACTED]"
-          end
+          summary[field_name] = if field_value.nil?
+                                  nil
+                                elsif field_value.respond_to?(:cleared?) && field_value.cleared?
+                                  '[CLEARED]'
+                                else
+                                  '[REDACTED]'
+                                end
         end
       end
 

data/lib/familia/features.rb

@@ -1,17 +1,15 @@
 # lib/familia/features.rb
 
 module Familia
-
   FeatureDefinition = Data.define(:name, :depends_on)
 
   # Familia::Features
   #
   module Features
-
     @features_enabled = nil
     attr_reader :features_enabled
 
-    def feature(feature_name = nil)
+    def feature(feature_name = nil, **options)
       @features_enabled ||= []
 
       return features_enabled if feature_name.nil?
@@ -28,22 +26,28 @@ module Familia
         return
       end
 
-      if Familia.debug?
-        Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}", caller(1..1)
+      Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}", caller(1..1) if Familia.debug?
+
+      # Check dependencies and raise error if missing
+      feature_def = Familia::Base.feature_definitions[feature_name]
+      if feature_def&.depends_on&.any?
+        missing = feature_def.depends_on - features_enabled
+        if missing.any?
+          raise Familia::Problem,
+                "Feature #{feature_name} requires missing dependencies: #{missing.join(', ')}"
+        end
       end
 
       # Add it to the list available features_enabled for Familia::Base classes.
       features_enabled << feature_name
 
-      klass = Familia::Base.features_available[feature_name]
-
-      # Validate dependencies
-      feature_def = Familia::Base.feature_definitions[feature_name]
-      if feature_def&.depends_on&.any?
-        missing = feature_def.depends_on - features_enabled
-        raise Familia::Problem, "#{feature_name} requires: #{missing.join(', ')}" if missing.any?
+      # Store feature options if any were provided using the new pattern
+      if options.any?
+        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
 
@@ -58,7 +62,6 @@ module Familia
       # We'd need to extend the DataType instances for each Horreum subclass. That
       # avoids it getting included multiple times per DataType
     end
-
   end
 end
 

data/lib/familia/horreum/core/serialization.rb

@@ -135,7 +135,7 @@ module Familia
             multi.hmset(dbkey, to_h_for_storage)
           end
 
-          result.is_a?(Array)  # transaction succeeded
+          result.is_a?(Array) # transaction succeeded
         end
       end
 
@@ -463,9 +463,7 @@ module Familia
       #
       def serialize_value(val)
         # Security: Handle ConcealedString safely - extract encrypted data for storage
-        if val.respond_to?(:encrypted_value)
-          return val.encrypted_value
-        end
+        return val.encrypted_value if val.respond_to?(:encrypted_value)
 
         prepared = Familia.distinguisher(val, strict_values: false)
 
@@ -530,6 +528,5 @@ module Familia
         end
       end
     end
-
   end
 end

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,6 +237,40 @@ module Familia
         field_types[field_type.name] = field_type
       end
 
+      # Get feature options for a specific feature or all features
+      #
+      # @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
+      #
+      def feature_options(feature_name = nil)
+        @feature_options ||= {}
+        return @feature_options if feature_name.nil?
+
+        @feature_options[feature_name.to_sym] || {}
+      end
+
+      # Add feature options for a specific feature
+      #
+      # This method provides a clean way for features to set their default options
+      # without worrying about initialization state. Similar to register_field_type
+      # for field types.
+      #
+      # @param feature_name [Symbol] The feature name
+      # @param options [Hash] The options to add/merge
+      # @return [Hash] The updated options for the feature
+      #
+      def add_feature_options(feature_name, **options)
+  @feature_options ||= {}
+  @feature_options[feature_name.to_sym] ||= {}
+
+  # Only set defaults for options that don't already exist
+  options.each do |key, value|
+    @feature_options[feature_name.to_sym][key] ||= value
+  end
+
+  @feature_options[feature_name.to_sym]
+end
+
       # Create and register a transient field type
       #
       # @param name [Symbol] The field name

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

data/lib/familia/version.rb

@@ -2,7 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  unless defined?(Familia::VERSION)
-    VERSION = '2.0.0.pre7'
-  end
+  VERSION = '2.0.0.pre10'.freeze unless defined?(Familia::VERSION)
 end

data/setup.cfg

@@ -0,0 +1,12 @@
+[scriv]
+format = md
+categories = Added, Changed, Deprecated, Removed, Fixed, Security, Documentation, AI Assistance
+version_scheme = semver
+entry_title_template = [{{ version }}] - {{ date }}
+fragment_directory = changelog.d/fragments
+template_file = changelog.d/template.md.j2
+output_file = CHANGELOG.md
+main_branches = main, develop
+md_header_level = 2
+end_marker = scriv-end-here
+start_marker = scriv-insert-here

data/try/core/errors_try.rb

@@ -58,7 +58,7 @@ begin
 rescue Familia::NotConnected => e
   e.message.include?('No client for')
 end
-# > true
+#=> true
 
 ## KeyNotFoundError stores key
 begin

data/try/features/{encrypted_fields_core_try.rb → encrypted_fields/encrypted_fields_core_try.rb}

@@ -1,6 +1,6 @@
 # try/features/encrypted_fields_core_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../helpers/test_helpers'
 require 'base64'
 
 

data/try/features/{encrypted_fields_integration_try.rb → encrypted_fields/encrypted_fields_integration_try.rb}

@@ -2,7 +2,7 @@
 
 # Test constants will be redefined in each test since variables don't persist
 
-require_relative '../helpers/test_helpers'
+require_relative '../../helpers/test_helpers'
 require 'base64'
 
 

data/try/features/{encrypted_fields_no_cache_security_try.rb → encrypted_fields/encrypted_fields_no_cache_security_try.rb}

@@ -3,7 +3,7 @@
 # Security tests for the no-cache encryption strategy
 # These tests verify that we maintain security properties by NOT caching derived keys
 
-require_relative '../helpers/test_helpers'
+require_relative '../../helpers/test_helpers'
 
 test_keys = {
   v1: Base64.strict_encode64('a' * 32),

data/try/features/{encrypted_fields_security_try.rb → encrypted_fields/encrypted_fields_security_try.rb}

@@ -1,6 +1,6 @@
 # try/features/encrypted_fields_security_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../helpers/test_helpers'
 require 'base64'
 
 # Define all test classes up front to avoid tryouts retry conflicts

data/try/features/{expiration_try.rb → expiration/expiration_try.rb}

@@ -1,6 +1,6 @@
 # try/features/expiration_try.rb
 
-require_relative '../helpers/test_helpers'
+require_relative '../../helpers/test_helpers'
 
 Familia.debug = false