familia 2.0.0.pre13 → 2.0.0.pre15

data/lib/familia/{autoloader.rb → features/autoloader.rb}

@@ -1,11 +1,41 @@
-# frozen_string_literal: true
+# lib/familia/features/autoloader.rb
 
-module Familia
+module Familia::Features
   # Provides autoloading functionality for Ruby files based on patterns and conventions.
   #
   # Used by the Features module at library startup to load feature files, and available
   # as a utility for other modules requiring file autoloading capabilities.
   module Autoloader
+    using Familia::Refinements::SnakeCase
+
+    # Autoloads feature files when this module is included.
+    #
+    # Discovers and loads all Ruby files in the features/ directory relative to the
+    # including module's location. Typically used by Familia::Features.
+    #
+    # @param base [Module] the module including this autoloader
+    def self.included(base)
+
+      # Get the directory where the including module is defined
+      # This should be lib/familia for the Features module
+      base_path = File.dirname(caller_locations(1, 1).first.path)
+      model_name = base.name.snake_case
+      dir_patterns = [
+        File.join(base_path, 'features', '*.rb'),
+        File.join(base_path, model_name, 'features', '*.rb'),
+        File.join(base_path, model_name, 'features.rb'),
+      ]
+
+      # Ensure the Features module exists within the base module
+      unless base.const_defined?(:Features) || model_name.eql?('features')
+        base.const_set(:Features, Module.new)
+      end
+
+
+      # Use the shared autoload_files method
+      autoload_files(dir_patterns, log_prefix: "Autoloader[#{model_name}]")
+    end
+
     # Autoloads Ruby files matching the given patterns.
     #
     # @param patterns [String, Array<String>] file patterns to match (supports Dir.glob patterns)
@@ -15,6 +45,7 @@ module Familia
       patterns = Array(patterns)
 
       patterns.each do |pattern|
+        Familia.ld "[#{log_prefix}] Autoloader loading features from #{pattern}"
         Dir.glob(pattern).each do |file_path|
           basename = File.basename(file_path)
 
@@ -26,28 +57,5 @@ module Familia
         end
       end
     end
-
-    # Autoloads feature files when this module is included.
-    #
-    # Discovers and loads all Ruby files in the features/ directory relative to the
-    # including module's location. Typically used by Familia::Features.
-    #
-    # @param base [Module] the module including this autoloader
-    def self.included(base)
-      # Get the directory where the including module is defined
-      # This should be lib/familia for the Features module
-      base_path = File.dirname(caller_locations(1, 1).first.path)
-      features_dir = File.join(base_path, 'features')
-
-      Familia.ld "[DEBUG] Autoloader loading features from #{features_dir}"
-
-      return unless Dir.exist?(features_dir)
-
-      # Use the shared autoload_files method
-      autoload_files(
-        File.join(features_dir, '*.rb'),
-        log_prefix: 'Autoloader'
-      )
-    end
   end
 end

data/lib/familia/features/encrypted_fields.rb

@@ -255,6 +255,8 @@ module Familia
     # - Insider threats with application access
     #
     module EncryptedFields
+      Familia::Base.add_feature self, :encrypted_fields
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
@@ -430,8 +432,6 @@ module Familia
           end
         end
       end
-
-      Familia::Base.add_feature self, :encrypted_fields
     end
   end
 end

data/lib/familia/features/expiration/extensions.rb

@@ -0,0 +1,61 @@
+# lib/familia/features/expiration/extensions.rb
+
+module Familia
+  # Add a default update_expiration method for all classes that include
+  # Familia::Base. Since expiration is a core feature, we can confidently
+  # call `horreum_instance.update_expiration` without defensive programming
+  # even when expiration is not enabled for the horreum_instance class.
+  module Base
+    # Base implementation of update_expiration that maintains API compatibility
+    # with the :expiration feature's implementation.
+    #
+    # This is a no-op implementation that gets overridden by the :expiration
+    # feature. It accepts an optional default_expiration parameter to maintain
+    # interface compatibility with the overriding implementations.
+    #
+    # @param default_expiration [Numeric, nil] Time To Live in seconds
+    # @return [nil] Always returns nil for the base implementation
+    #
+    # @note This is a no-op implementation. Classes that need expiration
+    #       functionality should include the :expiration feature.
+    #
+    # @example Enable expiration feature
+    #   class MyModel < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 1.hour
+    #   end
+    #
+    def update_expiration(default_expiration: nil)
+      Familia.ld <<~LOG
+        [update_expiration] Expiration feature not enabled for #{self.class}.
+        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+      LOG
+      nil
+    end
+
+    # Base implementation of ttl that returns -1 (no expiration set)
+    #
+    # @return [Integer] Always returns -1 for the base implementation
+    #
+    def ttl
+      -1
+    end
+
+    # Base implementation of expires? that returns false
+    #
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expires?
+      false
+    end
+
+    # Base implementation of expired? that returns false
+    #
+    # @param threshold [Numeric] Ignored in base implementation
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expired?(_threshold = 0)
+      false
+    end
+  end
+end

data/lib/familia/features/expiration.rb

@@ -1,5 +1,7 @@
 # lib/familia/features/expiration.rb
 
+require_relative 'expiration/extensions'
+
 module Familia
   module Features
     # Expiration is a feature that provides Time To Live (TTL) management for Familia
@@ -149,7 +151,9 @@ module Familia
     module Expiration
       @default_expiration = nil
 
-      using Familia::Refinements::TimeUtils
+      Familia::Base.add_feature self, :expiration
+
+      using Familia::Refinements::TimeLiterals
 
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
@@ -354,67 +358,6 @@ module Familia
         redis.persist(dbkey)
       end
 
-      Familia::Base.add_feature self, :expiration
-    end
-  end
-end
-
-module Familia
-  # Add a default update_expiration method for all classes that include
-  # Familia::Base. Since expiration is a core feature, we can confidently
-  # call `horreum_instance.update_expiration` without defensive programming
-  # even when expiration is not enabled for the horreum_instance class.
-  module Base
-    # Base implementation of update_expiration that maintains API compatibility
-    # with the :expiration feature's implementation.
-    #
-    # This is a no-op implementation that gets overridden by the :expiration
-    # feature. It accepts an optional default_expiration parameter to maintain
-    # interface compatibility with the overriding implementations.
-    #
-    # @param default_expiration [Numeric, nil] Time To Live in seconds
-    # @return [nil] Always returns nil for the base implementation
-    #
-    # @note This is a no-op implementation. Classes that need expiration
-    #       functionality should include the :expiration feature.
-    #
-    # @example Enable expiration feature
-    #   class MyModel < Familia::Horreum
-    #     feature :expiration
-    #     default_expiration 1.hour
-    #   end
-    #
-    def update_expiration(default_expiration: nil)
-      Familia.ld <<~LOG
-        [update_expiration] Expiration feature not enabled for #{self.class}.
-        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
-      LOG
-      nil
-    end
-
-    # Base implementation of ttl that returns -1 (no expiration set)
-    #
-    # @return [Integer] Always returns -1 for the base implementation
-    #
-    def ttl
-      -1
-    end
-
-    # Base implementation of expires? that returns false
-    #
-    # @return [Boolean] Always returns false for the base implementation
-    #
-    def expires?
-      false
-    end
-
-    # Base implementation of expired? that returns false
-    #
-    # @param threshold [Numeric] Ignored in base implementation
-    # @return [Boolean] Always returns false for the base implementation
-    #
-    def expired?(_threshold = 0)
-      false
     end
   end
 end

data/lib/familia/features/external_identifier.rb

@@ -5,6 +5,9 @@ module Familia
     # Familia::Features::ExternalIdentifier
     #
     module ExternalIdentifier
+
+      Familia::Base.add_feature self, :external_identifier, depends_on: [:object_identifier]
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
@@ -99,7 +102,7 @@ module Familia
             klass.define_method :"#{method_name}=" do |value|
               # Remove old mapping if extid is changing
               old_value = instance_variable_get(:"@#{field_name}")
-              self.class.extid_lookup.del(old_value) if old_value && old_value != value && respond_to?(:identifier)
+              self.class.extid_lookup.remove_field(old_value) if old_value && old_value != value
 
               # Set the new value
               instance_variable_set(:"@#{field_name}", value)
@@ -153,7 +156,7 @@ module Familia
           find_by_id(primary_id)
         rescue Familia::NotFound
           # If the object was deleted but mapping wasn't cleaned up
-          extid_lookup.del(extid)
+          extid_lookup.remove_field(extid)
           nil
         end
       end
@@ -236,7 +239,7 @@ module Familia
       def destroy!
         # Clean up extid mapping when object is destroyed
         current_extid = instance_variable_get(:@extid)
-        self.class.extid_lookup.del(current_extid) if current_extid
+        self.class.extid_lookup.remove_field(current_extid) if current_extid
 
         super if defined?(super)
       end
@@ -304,7 +307,6 @@ module Familia
         end
       end
 
-      Familia::Base.add_feature self, :external_identifier, depends_on: [:object_identifier]
     end
   end
 end

data/lib/familia/features/object_identifier.rb

@@ -81,6 +81,8 @@ module Familia
     # - Custom generators allow domain-specific security requirements
     #
     module ObjectIdentifier
+      Familia::Base.add_feature self, :object_identifier, depends_on: []
+
       DEFAULT_GENERATOR = :uuid_v7
 
       def self.included(base)
@@ -301,7 +303,6 @@ module Familia
         Familia.trace :OBJID_INIT, dbclient, "Generator strategy: #{generator}", caller(1..1)
       end
 
-      Familia::Base.add_feature self, :object_identifier, depends_on: []
     end
   end
 end

data/lib/familia/features/quantization.rb

@@ -246,7 +246,9 @@ module Familia
     #
     module Quantization
 
-      using Familia::Refinements::TimeUtils
+      Familia::Base.add_feature self, :quantization
+
+      using Familia::Refinements::TimeLiterals
 
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
@@ -397,8 +399,6 @@ module Familia
       end
 
       extend ClassMethods
-
-      Familia::Base.add_feature self, :quantization
     end
   end
 end

data/lib/familia/features/relationships.rb

@@ -98,9 +98,13 @@ module Familia
     #     { owner: team, collection: :domains }
     #   ], min_permission: :read)
     module Relationships
+
+      # Register the feature with Familia
+      Familia::Base.add_feature Relationships, :relationships
+
       # Feature initialization
       def self.included(base)
-        puts "[DEBUG] Relationships included in #{base}"
+        Familia.ld "[#{base}] Relationships included"
         base.extend ClassMethods
         base.include InstanceMethods
 
@@ -108,11 +112,8 @@ module Familia
         base.include ScoreEncoding
         base.include RedisOperations
 
-        puts '[DEBUG] Including Tracking module'
         base.include Tracking
-        puts '[DEBUG] Extending with Tracking::ClassMethods'
         base.extend Tracking::ClassMethods
-        puts "[DEBUG] Base now responds to tracked_in: #{base.respond_to?(:tracked_in)}"
 
         base.include Indexing
         base.extend Indexing::ClassMethods
@@ -466,8 +467,6 @@ module Familia
         end
       end
 
-      # Register the feature with Familia
-      Familia::Base.add_feature Relationships, :relationships
     end
   end
 end

data/lib/familia/features/safe_dump.rb

@@ -41,15 +41,15 @@ module Familia::Features
   # of symbols in the order they were defined.
   #
   module SafeDump
-    include Familia::Features::Autoloadable
+
+    Familia::Base.add_feature self, :safe_dump
+
     using Familia::Refinements::SnakeCase
 
     @dump_method = :to_json
     @load_method = :from_json
 
     def self.included(base)
-      # Call the Autoloadable module's included method for post-inclusion setup
-      super
 
       Familia.trace(:LOADED, self, base, caller(1..1)) if Familia.debug?
       base.extend ClassMethods
@@ -153,8 +153,6 @@ module Familia::Features
     end
 
     extend ClassMethods
-
-    Familia::Base.add_feature self, :safe_dump
   end
 end
 # rubocop:enable ThreadSafety/ClassInstanceVariable

data/lib/familia/features/transient_fields.rb

@@ -104,6 +104,9 @@ module Familia
     # (HashiCorp Vault, AWS Secrets Manager) or languages with secure memory handling.
     #
     module TransientFields
+
+      Familia::Base.add_feature self, :transient_fields, depends_on: nil
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
@@ -221,7 +224,6 @@ module Familia
         end
       end
 
-      Familia::Base.add_feature self, :transient_fields, depends_on: nil
     end
   end
 end

data/lib/familia/features.rb

@@ -1,7 +1,7 @@
 # lib/familia/features.rb
 
 # Load the Autoloader first, then use it to load all other features
-require_relative 'autoloader'
+require_relative 'features/autoloader'
 
 module Familia
   FeatureDefinition = Data.define(:name, :depends_on)
@@ -25,12 +25,21 @@ module Familia
   # feature options. When you enable a feature with options in different models,
   # each model stores its own separate configuration without interference.
   #
-  # ## Project Organization with Autoloadable
+  # ## Project Organization with Autoloader
   #
-  # For large projects, use {Familia::Features::Autoloadable} to automatically load
+  # 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.
   #
+  # ### Class Reopening (Deprecated)
+  #
+  # Direct class reopening still works but generates deprecation warnings:
+  #
+  #   # app/models/customer/safe_dump_extensions.rb
+  #   class Customer
+  #     safe_dump_fields :name, :email  # Works but not recommended
+  #   end
+  #
   # @example Different models with different feature options
   #   class UserModel < Familia::Horreum
   #     feature :object_identifier, generator: :uuid_v4
@@ -57,15 +66,15 @@ module Familia
   #   # In your model file: app/models/customer.rb
   #   class Customer < Familia::Horreum
   #     module Features
-  #       include Familia::Features::Autoloadable
+  #       include Familia::Features::Autoloader
   #       # Automatically loads all .rb files from app/models/customer/features/
   #     end
   #   end
   #
-  # @see Familia::Features::Autoloadable For automatic feature loading
+  # @see Familia::Features::Autoloader For automatic feature loading
   #
   module Features
-    include Familia::Autoloader
+    include Familia::Features::Autoloader
 
     @features_enabled = nil
     attr_reader :features_enabled
@@ -110,8 +119,8 @@ module Familia
 
       # If there's a value provided check that it's a valid feature
       feature_name = feature_name.to_sym
-      feature_class = Familia::Base.find_feature(feature_name, self)
-      unless feature_class
+      feature_module = Familia::Base.find_feature(feature_name, self)
+      unless feature_module
         raise Familia::Problem, "Unsupported feature: #{feature_name}"
       end
 
@@ -146,11 +155,11 @@ module Familia
       end
 
       # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-      include feature_class
+      include feature_module
 
       # Trigger post-inclusion autoloading for features that support it
-      if feature_class.respond_to?(:post_inclusion_autoload)
-        feature_class.post_inclusion_autoload(self, feature_name, options)
+      if feature_module.respond_to?(:post_inclusion_autoload)
+        feature_module.post_inclusion_autoload(self, feature_name, options)
       end
 
       # NOTE: Do we want to extend Familia::DataType here? That would make it

data/lib/familia/field_type.rb

@@ -29,7 +29,7 @@ module Familia
   class FieldType
     attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Initialize a new field type
     #

data/lib/familia/horreum.rb

@@ -31,7 +31,7 @@ module Familia
     include Familia::Horreum::Core
     include Familia::Horreum::Settings
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Singleton Class Context
     #

data/lib/familia/refinements/{time_utils.rb → time_literals.rb}

@@ -1,10 +1,41 @@
-# lib/familia/refinements/time_utils.rb
+# lib/familia/refinements/time_literals.rb
 
 module Familia
   module Refinements
 
-    # Familia::Refinements::TimeUtils
-    module TimeUtils
+    # Familia::Refinements::TimeLiterals
+    #
+    # This module provides a set of refinements for `Numeric` and `String` to
+    # enable readable and expressive time duration and timestamp manipulation.
+    #
+    # The name "TimeLiterals" reflects its core purpose: to allow us to treat
+    # numeric values directly as "literals" of time units (e.g., `5.minutes`,
+    # `1.day`). It extends this concept to include conversions between these
+    # literal time quantities, parsing string representations of time
+    # durations, and performing common timestamp-based calculations
+    # in an intuitive manner.
+    #
+    # @example Expressing durations
+    #   5.minutes.ago           #=> A Time object 5 minutes in the past
+    #   1.day.from_now          #=> A Time object 1 day in the future
+    #   (2.5).hours             #=> 9000.0 (seconds)
+    #
+    # @example Converting between units
+    #   3600.in_hours           #=> 1.0
+    #   86400.in_days           #=> 1.0
+    #
+    # @example Parsing string durations
+    #   "30m".in_seconds        #=> 1800.0
+    #   "2.5h".in_seconds       #=> 9000.0
+    #
+    # @example Timestamp calculations
+    #   timestamp = 2.days.ago.to_i
+    #   timestamp.days_old      #=> ~2.0
+    #   timestamp.older_than?(1.day) #=> true
+    #
+    # @note `to_bytes` also lives here until we find it a better home!
+    #
+    module TimeLiterals
       # Time unit constants
       PER_MICROSECOND = 0.000001
       PER_MILLISECOND = 0.001
@@ -65,7 +96,7 @@ module Familia
         alias_method :month,       :months
         alias_method :year,        :years
 
-        # Fun aliases
+        # Shortest aliases
         alias_method :ms, :milliseconds
         alias_method :μs, :microseconds
 

data/lib/familia/refinements.rb

@@ -2,4 +2,4 @@
 
 require_relative 'refinements/logger_trace'
 require_relative 'refinements/snake_case'
-require_relative 'refinements/time_utils'
+require_relative 'refinements/time_literals'

data/lib/familia/utils.rb

@@ -6,7 +6,7 @@ module Familia
   #
   module Utils
 
-    using Familia::Refinements::TimeUtils
+    using Familia::Refinements::TimeLiterals
 
     # Joins array elements with Familia delimiter
     # @param val [Array] elements to join

data/lib/familia/version.rb

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

data/lib/familia.rb

@@ -82,7 +82,6 @@ module Familia
 end
 
 require_relative 'familia/base'
-require_relative 'familia/features/autoloadable'
 require_relative 'familia/features'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'

data/try/core/autoloader_try.rb

@@ -30,16 +30,16 @@ File.write(@excluded_file, <<~RUBY)
   $autoloader_file_loaded = true
 RUBY
 
-## Test that Familia::Autoloader exists and is a module
-Familia::Autoloader.is_a?(Module)
+## Test that Familia::Features::Autoloader exists and is a module
+Familia::Features::Autoloader.is_a?(Module)
 #=> true
 
 ## Test that autoload_files class method exists
-Familia::Autoloader.respond_to?(:autoload_files)
+Familia::Features::Autoloader.respond_to?(:autoload_files)
 #=> true
 
 ## Test that included class method exists
-Familia::Autoloader.respond_to?(:included)
+Familia::Features::Autoloader.respond_to?(:included)
 #=> true
 
 ## Test autoload_files with single pattern
@@ -47,7 +47,7 @@ $test_feature1_loaded = false
 $test_feature2_loaded = false
 $autoloader_file_loaded = false
 
-Familia::Autoloader.autoload_files(File.join(@features_dir, '*.rb'))
+Familia::Features::Autoloader.autoload_files(File.join(@features_dir, '*.rb'))
 $test_feature1_loaded && $test_feature2_loaded
 #=> true
 
@@ -64,7 +64,7 @@ File.write(@exclude_file, '$exclude_me_loaded = true')
 $include_me_loaded = false
 $exclude_me_loaded = false
 
-Familia::Autoloader.autoload_files(
+Familia::Features::Autoloader.autoload_files(
   File.join(@exclude_features_dir, '*.rb'),
   exclude: ['autoloader.rb']
 )
@@ -88,7 +88,7 @@ File.write(@pattern_file2, '$pattern2_loaded = true')
 $pattern1_loaded = false
 $pattern2_loaded = false
 
-Familia::Autoloader.autoload_files([
+Familia::Features::Autoloader.autoload_files([
   File.join(@pattern_dir1, '*.rb'),
   File.join(@pattern_dir2, '*.rb')
 ])
@@ -99,11 +99,11 @@ $pattern1_loaded && $pattern2_loaded
 ## Test that included method loads features from features directory
 # Create a mock module that includes Autoloader
 @mock_features_module = Module.new do
-  include Familia::Autoloader
+  include Familia::Features::Autoloader
 end
 
 # The Features module already includes Autoloader, so test indirectly
-Familia::Features.ancestors.include?(Familia::Autoloader)
+Familia::Features.ancestors.include?(Familia::Features::Autoloader)
 #=> true
 
 # Cleanup test files and directories

data/try/core/extensions_try.rb

@@ -1,7 +1,7 @@
 require_relative '../helpers/test_helpers'
 
 module RefinedContext
-  using Familia::Refinements::TimeUtils
+  using Familia::Refinements::TimeLiterals
 
   # This helper evaluates code within the refined context using eval.
   # This works because eval executes the code as if it were written