familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/features/safe_dump.rb

@@ -1,160 +1,155 @@
 # 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 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.
-  # The hash syntax allows you to:
-  #   * define a field name that is different from the method name
-  #   * define a field that requires some computation on-the-fly
-  #   * define a field that is not a method on the object
-  #
-  # Example:
-  #
-  #   feature :safe_dump
-  #
-  #   safe_dump_field :objid
-  #   safe_dump_field :updated
-  #   safe_dump_field :created
-  #   safe_dump_field :active, ->(obj) { obj.active? }
-  #
-  # Alternatively, you can define multiple fields at once:
-  #
-  #   safe_dump_fields :objid, :updated, :created,
-  #                    { 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.
-  #
-  module SafeDump
-    include Familia::Features::Autoloadable
-    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
+module Familia
+  module 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 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.
+    # The hash syntax allows you to:
+    #   * define a field name that is different from the method name
+    #   * define a field that requires some computation on-the-fly
+    #   * define a field that is not a method on the object
+    #
+    # Example:
+    #
+    #   feature :safe_dump
+    #
+    #   safe_dump_field :objid
+    #   safe_dump_field :updated
+    #   safe_dump_field :created
+    #   safe_dump_field :active, ->(obj) { obj.active? }
+    #
+    # Alternatively, you can define multiple fields at once:
+    #
+    #   safe_dump_fields :objid, :updated, :created,
+    #                    { 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.
+    #
+    module SafeDump
+      Familia::Base.add_feature self, :safe_dump
 
-      # Initialize the safe dump field map
-      base.instance_variable_set(:@safe_dump_field_map, {})
-    end
+      using Familia::Refinements::StylizeWords
 
-    # SafeDump::ClassMethods
-    #
-    # These methods become available on the model class
-    module ClassMethods
-      # 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 ||= {}
+      @dump_method = :to_json
+      @load_method = :from_json
 
-        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
-        }
+      def self.included(base)
+        Familia.trace(:LOADED, self, base) if Familia.debug?
+        base.extend ModelClassMethods
 
-        @safe_dump_field_map[field_name] = field_value
+        # Initialize the safe dump field map
+        base.instance_variable_set(:@safe_dump_field_map, {})
       end
 
-      # 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?
+      # SafeDump::ModelClassMethods
+      #
+      # These methods become available on the model class
+      module ModelClassMethods
+        # 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
 
-        # 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)
+        # 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
-      end
 
-      # 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 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
-        @safe_dump_field_map || {}
-      end
+        # Returns the field map used for dumping
+        def safe_dump_field_map
+          @safe_dump_field_map || {}
+        end
 
-      # Legacy method for setting safe dump fields (for backward compatibility)
-      def set_safe_dump_fields(*fields)
-        safe_dump_fields(*fields)
+        # Legacy method for setting safe dump fields (for backward compatibility)
+        def set_safe_dump_fields(*fields)
+          safe_dump_fields(*fields)
+        end
       end
-    end
 
-    # Returns a hash of safe fields and their values. This method
-    # calls the callables defined in the safe_dump_field_map with
-    # the instance object as an argument.
-    #
-    # The return values are not cached, so if you call this method
-    # multiple times, the callables will be called each time.
-    #
-    # Example:
-    #
-    #   class Customer < Familia::HashKey
-    #     include SafeDump
-    #     @safe_dump_fields = [
-    #       :name,
-    #       { :active => ->(cust) { cust.active? } }
-    #     ]
-    #
-    #     def active?
-    #       true # or false
-    #     end
-    #
-    #     cust = Customer.new :name => 'Lucy'
-    #     cust.safe_dump
-    #     #=> { :name => 'Lucy', :active => true }
-    #
-    def safe_dump
-      self.class.safe_dump_field_map.transform_values do |callable|
-        transformed_value = callable.call(self)
-
-        # If the value is a relative ancestor of SafeDump we can
-        # call safe_dump on it, otherwise we'll just return the value as-is.
-        if transformed_value.is_a?(SafeDump)
-          transformed_value.safe_dump
-        else
-          transformed_value
+      # Returns a hash of safe fields and their values. This method
+      # calls the callables defined in the safe_dump_field_map with
+      # the instance object as an argument.
+      #
+      # The return values are not cached, so if you call this method
+      # multiple times, the callables will be called each time.
+      #
+      # Example:
+      #
+      #   class Customer < Familia::HashKey
+      #     include SafeDump
+      #     @safe_dump_fields = [
+      #       :name,
+      #       { :active => ->(cust) { cust.active? } }
+      #     ]
+      #
+      #     def active?
+      #       true # or false
+      #     end
+      #
+      #     cust = Customer.new :name => 'Lucy'
+      #     cust.safe_dump
+      #     #=> { :name => 'Lucy', :active => true }
+      #
+      def safe_dump
+        self.class.safe_dump_field_map.transform_values do |callable|
+          transformed_value = callable.call(self)
+
+          # If the value is a relative ancestor of SafeDump we can
+          # call safe_dump on it, otherwise we'll just return the value as-is.
+          if transformed_value.is_a?(SafeDump)
+            transformed_value.safe_dump
+          else
+            transformed_value
+          end
         end
       end
     end
-
-    extend ClassMethods
-
-    Familia::Base.add_feature self, :safe_dump
   end
 end
 # rubocop:enable ThreadSafety/ClassInstanceVariable

data/lib/familia/features/transient_fields/redacted_string.rb

@@ -37,10 +37,10 @@
 #
 # 2. Every .dup, .to_s, +, interpolation, or method call may create hidden
 #    copies:
-#      s = "secret"
-#      t = s.dup        # New object, same content — now two copies
-#      u = s + "123"    # New string — third copy
-#      "#{t}"           # Interpolation — fourth copy
+#      `s = "secret"`
+#      `t = s.dup`        # New object, same content — now two copies
+#      `u = s + "123"`    # New string — third copy
+#      `"#{t}"`           # Interpolation — fourth copy
 #    These copies are *not* controlled by RedactedString and may persist.
 #
 # 3. String Freezing & Immutability
@@ -95,8 +95,8 @@ class RedactedString
   # Example:
   #   token.expose do |plain|
   #     # Good: use directly without copying
-  #     HTTP.post('/api', headers: { 'X-Token' => plain })
-  #     # Avoid: plain.dup, "prefix#{plain}", plain[0..-1], etc.
+  #     `HTTP.post('/api', headers: { 'X-Token' => plain })`
+  #     # Avoid: `plain.dup`, `"prefix#{plain}"`, `plain[0..-1]`, etc.
   #   end
   #   # Value is still accessible after block
   #   token.clear! # Explicitly clear when done

data/lib/familia/features/transient_fields/transient_field_type.rb

@@ -76,7 +76,7 @@ module Familia
     # Transient fields should not have fast writers since they're not
     # persisted to the database.
     #
-    # @param klass [Class] The class to define the method on
+    # @param _klass [Class] The class to define the method on
     #
     def define_fast_writer(_klass)
       # No fast writer for transient fields since they're not persisted
@@ -111,8 +111,8 @@ module Familia
     # This method should not be called since transient fields are not
     # persisted, but we provide it for completeness.
     #
-    # @param value [Object] The value to serialize
-    # @param record [Object] The record instance
+    # @param _value [Object] The value to serialize
+    # @param _record [Object] The record instance
     # @return [nil] Always nil since transient fields are not serialized
     #
     def serialize(_value, _record = nil)
@@ -126,8 +126,8 @@ module Familia
     # This method should not be called since transient fields are not
     # persisted, but we provide it for completeness.
     #
-    # @param value [Object] The value to deserialize
-    # @param record [Object] The record instance
+    # @param _value [Object] The value to deserialize
+    # @param _record [Object] The record instance
     # @return [nil] Always nil since transient fields are not stored
     #
     def deserialize(_value, _record = nil)

data/lib/familia/features/transient_fields.rb

@@ -104,15 +104,17 @@ 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
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
 
         # Initialize transient fields tracking
         base.instance_variable_set(:@transient_fields, []) unless base.instance_variable_defined?(:@transient_fields)
       end
 
-      module ClassMethods
+      module ModelClassMethods
         # Define a transient field that automatically wraps values in RedactedString
         #
         # Transient fields are not persisted to Redis/Valkey and exist only in memory.
@@ -220,8 +222,6 @@ module Familia
                                 end
         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,10 +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
-        raise Familia::Problem, "Unsupported feature: #{feature_name}"
-      end
+      feature_module = Familia::Base.find_feature(feature_name, self)
+      raise Familia::Problem, "Unsupported feature: #{feature_name}" unless feature_module
 
       # If the feature is already available, do nothing but log about it
       if features_enabled.member?(feature_name)
@@ -121,7 +128,7 @@ module Familia
         return
       end
 
-      Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}", caller(1..1) if Familia.debug?
+      Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}" if Familia.debug?
 
       # Check dependencies and raise error if missing
       feature_def = Familia::Base.feature_definitions[feature_name]
@@ -141,22 +148,15 @@ module Familia
       options[:calling_location] = calling_location&.path
 
       # Add feature options if the class supports them (Horreum classes)
-      if respond_to?(:add_feature_options)
-        add_feature_options(feature_name, **options)
-      end
+      add_feature_options(feature_name, **options) if respond_to?(:add_feature_options)
 
       # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-      include feature_class
-
-      # 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)
-      end
+      include feature_module
 
       # 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).
       #
-      # The challenge is that DataType classes (List, Set, etc.) are shared across
+      # The challenge is that DataType classes (List, UnsortedSet, etc.) are shared across
       # all Horreum models. If Customer extends DataType with safe_dump, then
       # Session's lists would also have it. Not ideal. If that's all we wanted
       # then we can do that by looping through every DataType class here.

data/lib/familia/field_type.rb

@@ -116,6 +116,26 @@ module Familia
       handle_method_conflict(klass, :"#{method_name}=") do
         klass.define_method :"#{method_name}=" do |value|
           instance_variable_set(:"@#{field_name}", value)
+
+          # If this field is the identifier and object_identifier feature is loaded,
+          # update objid_lookup mapping when identifier is set after objid generation
+          if respond_to?(:objid) &&
+             self.class.respond_to?(:identifier_field) &&
+             self.class.identifier_field == field_name &&
+             self.class.respond_to?(:objid_lookup)
+            current_objid = instance_variable_get(:@objid)
+            self.class.objid_lookup[current_objid] = value if current_objid && value
+          end
+
+          # If this field is the identifier and external_identifier feature is loaded,
+          # update extid_lookup mapping when identifier is set after extid generation
+          if respond_to?(:extid) &&
+             self.class.respond_to?(:identifier_field) &&
+             self.class.identifier_field == field_name &&
+             self.class.respond_to?(:extid_lookup)
+            current_extid = instance_variable_get(:@extid)
+            self.class.extid_lookup[current_extid] = value if current_extid && value
+          end
         end
       end
     end
@@ -145,7 +165,7 @@ module Familia
 
           begin
             # Trace the operation if debugging is enabled
-            Familia.trace :FAST_WRITER, dbclient, "#{field_name}: #{val.inspect}", caller(1..1) if Familia.debug?
+            Familia.trace :FAST_WRITER, nil, "#{field_name}: #{val.inspect}" if Familia.debug?
 
             # Convert value for database storage
             prepared = serialize_value(val)
@@ -190,7 +210,7 @@ module Familia
     # The default implementation passes values through unchanged.
     #
     # @param value [Object] The value to serialize
-    # @param record [Object] The record instance (for context)
+    # @param _record [Object] The record instance (for context)
     # @return [Object] The serialized value
     #
     def serialize(value, _record = nil)
@@ -203,7 +223,7 @@ module Familia
     # The default implementation passes values through unchanged.
     #
     # @param value [Object] The value to deserialize
-    # @param record [Object] The record instance (for context)
+    # @param _record [Object] The record instance (for context)
     # @return [Object] The deserialized value
     #
     def deserialize(value, _record = nil)
@@ -228,7 +248,7 @@ module Familia
         "method_name=#{@method_name}",
         "fast_method_name=#{@fast_method_name}",
         "on_conflict=#{@on_conflict}",
-        "category=#{category}"
+        "category=#{category}",
       ]
       "#<#{self.class.name} #{attributes.join(' ')}>"
     end