familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/features/safe_dump.rb

@@ -1,158 +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
-
-    Familia::Base.add_feature self, :safe_dump
-
-    using Familia::Refinements::SnakeCase
-
-    @dump_method = :to_json
-    @load_method = :from_json
-
-    def self.included(base)
-
-      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
+          }
 
-        # 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)
+          @safe_dump_field_map[field_name] = field_value
+        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?
+
+          # 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
   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

@@ -1,6 +1,7 @@
 # lib/familia/features/transient_fields.rb
 
 require_relative 'transient_fields/redacted_string'
+require_relative 'transient_fields/transient_field_type'
 
 module Familia
   module Features
@@ -104,18 +105,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
+      Familia::Base.add_feature self, :transient_fields, depends_on: nil, field_group: :transient_fields
 
       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.
@@ -144,8 +144,12 @@ module Familia
           @transient_fields ||= []
           @transient_fields << name unless @transient_fields.include?(name)
 
+          # Add to field_groups if the group exists
+          if field_groups&.key?(:transient_fields)
+            field_groups[:transient_fields] << name
+          end
+
           # Use the field type system for proper integration
-          require_relative 'transient_fields/transient_field_type'
           field_type = TransientFieldType.new(name, as: as, **kwargs.merge(fast_method: false))
           register_field_type(field_type)
         end
@@ -223,7 +227,6 @@ module Familia
                                 end
         end
       end
-
     end
   end
 end

data/lib/familia/features.rb

@@ -4,7 +4,7 @@
 require_relative 'features/autoloader'
 
 module Familia
-  FeatureDefinition = Data.define(:name, :depends_on)
+  FeatureDefinition = Data.define(:name, :depends_on, :field_group)
 
   # Familia::Features
   #
@@ -120,9 +120,7 @@ module Familia
       # If there's a value provided check that it's a valid feature
       feature_name = feature_name.to_sym
       feature_module = Familia::Base.find_feature(feature_name, self)
-      unless feature_module
-        raise Familia::Problem, "Unsupported feature: #{feature_name}"
-      end
+      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)
@@ -130,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]
@@ -149,23 +147,21 @@ module Familia
       calling_location = caller_locations(1, 1)&.first
       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)
+      # Initialize field group if feature declares one
+      if feature_def&.field_group && respond_to?(:field_group)
+        field_group(feature_def.field_group)
       end
 
+      # Add feature options if the class supports them (Horreum classes)
+      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_module
 
-      # Trigger post-inclusion autoloading for features that support it
-      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
       # 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,8 @@ module Familia
       handle_method_conflict(klass, :"#{method_name}=") do
         klass.define_method :"#{method_name}=" do |value|
           instance_variable_set(:"@#{field_name}", value)
+
+
         end
       end
     end
@@ -145,7 +147,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 +192,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 +205,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 +230,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