familia 2.0.0.pre3 → 2.0.0.pre5

data/lib/familia/horreum/{class_methods.rb → management_methods.rb}

@@ -1,242 +1,22 @@
-# lib/familia/horreum/class_methods.rb
+# lib/familia/horreum/management_methods.rb
 
 require_relative 'related_fields_management'
 
 module Familia
   class Horreum
-    # Class-level instance variables
-    # These are set up as nil initially and populated later
-    @dbclient = nil # TODO
-    @identifier_field = nil
-    @default_expiration = nil
-    @logical_database = nil
-    @uri = nil
-    @suffix = nil
-    @prefix = nil
-    @fields = nil # []
-    @class_related_fields = nil # {}
-    @related_fields = nil # {}
-    @dump_method = nil
-    @load_method = nil
-
-    # ClassMethods: Provides class-level functionality for Horreum
+    # ManagementMethods: Provides class-level functionality for Horreum
+    # records.
     #
     # This module is extended into classes that include Familia::Horreum,
     # providing methods for Database operations and object management.
     #
-    # Key features:
+    # # Key features:
     # * Includes RelatedFieldsManagement for DataType field handling
-    # * Defines methods for managing fields, identifiers, and dbkeys
     # * Provides utility methods for working with Database objects
     #
-    module ClassMethods
-      include Familia::Settings
+    module ManagementMethods
       include Familia::Horreum::RelatedFieldsManagement
 
-      # Sets or retrieves the unique identifier field for the class.
-      #
-      # This method defines or returns the field or method that contains the unique
-      # identifier used to generate the dbkey for the object. If a value is provided,
-      # it sets the identifier field; otherwise, it returns the current identifier field.
-      #
-      # @param [Object] val the field name or method to set as the identifier field (optional).
-      # @return [Object] the current identifier field.
-      #
-      def identifier_field(val = nil)
-        if val
-          # Validate identifier field definition at class definition time
-          case val
-          when Symbol, String, Proc
-            @identifier_field = val
-          else
-            raise Problem, <<~ERROR
-              Invalid identifier field definition: #{val.inspect}.
-              Use a field name (Symbol/String) or Proc.
-            ERROR
-          end
-        end
-        @identifier_field
-      end
-
-      # Defines a field for the class and creates accessor methods.
-      #
-      # This method defines a new field for the class, creating getter and setter
-      # instance methods similar to `attr_accessor`. It also generates a fast
-      # writer method for immediate persistence to Redis.
-      #
-      # @param [Symbol, String] name the name of the field to define.
-      #
-      def field(name)
-        fields << name
-        attr_accessor name
-
-        # Every field gets a fast attribute method for immediately persisting
-        fast_attribute! name
-      end
-
-      # Defines a fast attribute method with a bang (!) suffix for a given
-      # attribute name. Fast attribute methods are used to immediately read or
-      # write attribute values from/to Redis. Calling a fast attribute method
-      # has no effect on any of the object's other attributes and does not
-      # trigger a call to update the object's expiration time.
-      #
-      # The dynamically defined method performs the following:
-      # - Acts as both a reader and a writer method.
-      # - When called without arguments, retrieves the current value from Redis.
-      # - When called with an argument, persists the value to Database immediately.
-      # - Checks if the correct number of arguments is provided (zero or one).
-      # - Converts the provided value to a format suitable for Database storage.
-      # - Uses the existing accessor method to set the attribute value when
-      #   writing.
-      # - Persists the value to Database immediately using the hset command when
-      #   writing.
-      # - Includes custom error handling to raise an ArgumentError if the wrong
-      #   number of arguments is given.
-      # - Raises a custom error message if an exception occurs during the
-      #   execution of the method.
-      #
-      # @param [Symbol, String] name the name of the attribute for which the
-      #   fast method is defined.
-      # @return [Object] the current value of the attribute when called without
-      #   arguments.
-      # @raise [ArgumentError] if more than one argument is provided.
-      # @raise [RuntimeError] if an exception occurs during the execution of the
-      #   method.
-      #
-      def fast_attribute!(name = nil)
-        # Fast attribute accessor method for the '#{name}' attribute.
-        # This method provides immediate read and write access to the attribute
-        # in Redis.
-        #
-        # When called without arguments, it retrieves the current value of the
-        # attribute from Redis.
-        # When called with an argument, it immediately persists the new value to
-        # Redis.
-        #
-        # @overload #{name}!
-        #   Retrieves the current value of the attribute from Redis.
-        #   @return [Object] the current value of the attribute.
-        #
-        # @overload #{name}!(value)
-        #   Sets and immediately persists the new value of the attribute to
-        #   Redis.
-        #   @param value [Object] the new value to set for the attribute.
-        #   @return [Object] the newly set value.
-        #
-        # @raise [ArgumentError] if more than one argument is provided.
-        # @raise [RuntimeError] if an exception occurs during the execution of
-        #   the method.
-        #
-        # @note This method bypasses any object-level caching and interacts
-        #   directly with Redis. It does not trigger updates to other attributes
-        #   or the object's expiration time.
-        #
-        # @example
-        #
-        #      def #{name}!(*args)
-        #        # Method implementation
-        #      end
-        #
-        define_method :"#{name}!" do |*args|
-          # Check if the correct number of arguments is provided (exactly one).
-          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0 or 1)" if args.size > 1
-
-          val = args.first
-
-          # If no value is provided to this fast attribute method, make a call
-          # to the db to return the current stored value of the hash field.
-          return hget name if val.nil?
-
-          begin
-            # Trace the operation if debugging is enabled.
-            Familia.trace :FAST_WRITER, dbclient, "#{name}: #{val.inspect}", caller(1..1) if Familia.debug?
-
-            # Convert the provided value to a format suitable for Database storage.
-            prepared = serialize_value(val)
-            Familia.ld "[.fast_attribute!] #{name} val: #{val.class} prepared: #{prepared.class}"
-
-            # Use the existing accessor method to set the attribute value.
-            send :"#{name}=", val
-
-            # Persist the value to Database immediately using the hset command.
-            hset name, prepared
-          rescue Familia::Problem => e
-            # Raise a custom error message if an exception occurs during the execution of the method.
-            raise "#{name}! method failed: #{e.message}", e.backtrace
-          end
-        end
-      end
-
-      # Returns the list of field names defined for the class in the order
-      # that they were defined. i.e. `field :a; field :b; fields => [:a, :b]`.
-      def fields
-        @fields ||= []
-        @fields
-      end
-
-      def class_related_fields
-        @class_related_fields ||= {}
-        @class_related_fields
-      end
-
-      def related_fields
-        @related_fields ||= {}
-        @related_fields
-      end
-
-      def has_relations?
-        @has_relations ||= false
-      end
-
-      def logical_database(v = nil)
-        Familia.trace :DB, Familia.dbclient, "#{@logical_database} #{v}", caller(1..1) if Familia.debug?
-        @logical_database = v unless v.nil?
-        @logical_database || parent&.logical_database
-      end
-
-      def all(suffix = nil)
-        suffix ||= self.suffix
-        # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| find_by_key(k) }
-      end
-
-      def any?(filter = '*')
-        matching_keys_count(filter) > 0
-      end
-
-      # Returns the number of dbkeys matching the given filter pattern
-      # @param filter [String] dbkey pattern to match (default: '*')
-      # @return [Integer] Number of matching keys
-      def matching_keys_count(filter = '*')
-        dbclient.keys(dbkey(filter)).compact.size
-      end
-      alias size matching_keys_count # For backwards compatibility
-
-      def suffix(a = nil, &blk)
-        @suffix = a || blk if a || !blk.nil?
-        @suffix || Familia.default_suffix
-      end
-
-      # Sets or retrieves the prefix for generating Redis keys.
-      #
-      # @param a [String, Symbol, nil] the prefix to set (optional).
-      # @return [String, Symbol] the current prefix.
-      #
-      # The exception is only raised when both @prefix is nil/falsy AND name is nil,
-      # which typically occurs with anonymous classes that haven't had their prefix
-      # explicitly set.
-      #
-      def prefix(a = nil)
-        @prefix = a if a
-        @prefix || begin
-          if name.nil?
-            raise Problem, 'Cannot generate prefix for anonymous class. ' \
-                           'Use `prefix` method to set explicitly.'
-          end
-          name.downcase.gsub('::', Familia.delim).to_sym
-        end
-      end
-
       # Creates and persists a new instance of the class.
       #
       # @param *args [Array] Variable number of positional arguments to be passed
@@ -462,13 +242,23 @@ module Familia
         Familia.dbkey(prefix, identifier, suffix)
       end
 
-      def dump_method
-        @dump_method || :to_json # Familia.dump_method
+      def all(suffix = nil)
+        suffix ||= self.suffix
+        # objects that could not be parsed will be nil
+        keys(suffix).filter_map { |k| find_by_key(k) }
       end
 
-      def load_method
-        @load_method || :from_json # Familia.load_method
+      def any?(filter = '*')
+        matching_keys_count(filter) > 0
       end
+
+      # Returns the number of dbkeys matching the given filter pattern
+      # @param filter [String] dbkey pattern to match (default: '*')
+      # @return [Integer] Number of matching keys
+      def matching_keys_count(filter = '*')
+        dbclient.keys(dbkey(filter)).compact.size
+      end
+      alias size matching_keys_count # For backwards compatibility
     end
   end
 end

data/lib/familia/horreum/serialization.rb

@@ -1,8 +1,6 @@
 # lib/familia/horreum/serialization.rb
 #
 module Familia
-
-
   # Familia::Horreum
   #
   class Horreum
@@ -26,7 +24,7 @@ module Familia
     #
     # May your Database returns be ever valid, and your data ever flowing!
     #
-    @valid_command_return_values = ["OK", true, 1, 0, nil].freeze
+    @valid_command_return_values = ['OK', true, 1, 0, nil].freeze
 
     class << self
       attr_reader :valid_command_return_values
@@ -59,7 +57,6 @@ module Familia
     # the Ruby roses, but watch out for the Database thorns!)
     #
     module Serialization
-
       # Save our precious data to Redis, with a sprinkle of timestamp magic!
       #
       # This method is like a conscientious historian, not only recording your
@@ -76,7 +73,7 @@ module Familia
       # @note This method will leave breadcrumbs (traces) if you're in debug mode.
       #   It's like Hansel and Gretel, but for data operations!
       #
-      def save update_expiration: true
+      def save(update_expiration: true)
         Familia.trace :SAVE, dbclient, uri, caller(1..1) if Familia.debug?
 
         # No longer need to sync computed identifier with a cache field
@@ -198,11 +195,11 @@ module Familia
       # @note The expiration update is only performed for classes that have
       #   the expiration feature enabled. For others, it's a no-op.
       #
-      def commit_fields update_expiration: true
+      def commit_fields(update_expiration: true)
         prepared_value = to_h
         Familia.ld "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
 
-        result = self.hmset(prepared_value)
+        result = hmset(prepared_value)
 
         # Only classes that have the expiration ferature enabled will
         # actually set an expiration time on their keys. Otherwise
@@ -258,7 +255,7 @@ module Familia
       #   # => All fields are now nil, like a spell gone slightly too well.
       #
       def clear_fields!
-        self.class.fields.each { |field| send("#{field}=", nil) }
+        self.class.field_method_map.each_value { |method_name| send("#{method_name}=", nil) }
       end
 
       # The Great Database Refresh-o-matic 3000
@@ -284,8 +281,15 @@ module Familia
       def refresh!
         Familia.trace :REFRESH, dbclient, uri, caller(1..1) if Familia.debug?
         raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
+
         fields = hgetall
         Familia.ld "[refresh!] #{self.class} #{dbkey} fields:#{fields.keys}"
+
+        # Reset transient fields to nil for semantic clarity and ORM consistency
+        # Transient fields have no authoritative source, so they should return to
+        # their uninitialized state during refresh operations
+        reset_transient_fields!
+
         optimistic_refresh(**fields)
       end
 
@@ -326,14 +330,15 @@ module Familia
       # @note Watch in awe as each field is lovingly prepared for its Database adventure!
       #
       def to_h
-        self.class.fields.inject({}) do |hsh, field|
-          val = send(field)
+        self.class.persistent_fields.each_with_object({}) do |field, hsh|
+          field_type = self.class.field_types[field]
+          method_name = field_type.method_name
+          val = send(method_name)
           prepared = serialize_value(val)
           Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
 
           # Only include non-nil values in the hash for Redis
           hsh[field] = prepared unless prepared.nil?
-          hsh
         end
       end
 
@@ -353,10 +358,12 @@ module Familia
       # before joining the parade.
       #
       def to_a
-        self.class.fields.map do |field|
-          val = send(field)
+        self.class.persistent_fields.collect do |field|
+          field_type = self.class.field_types[field]
+          method_name = field_type.method_name
+          val = send(method_name)
           prepared = serialize_value(val)
-          Familia.ld " [to_a] field: #{field} val: #{val.class} prepared: #{prepared.class}"
+          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class} prepared: #{prepared.class}"
           prepared
         end
       end
@@ -406,9 +413,7 @@ module Familia
         end
 
         # If both the distinguisher and dump_method return nil, log an error
-        if prepared.nil?
-          Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}"
-        end
+        Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}" if prepared.nil?
 
         prepared
       end
@@ -423,7 +428,7 @@ module Familia
       # @return [Object] The deserialized value (Hash, Array, or original string)
       #
       def deserialize_value(val, symbolize: true)
-        return val if val.nil? || val == ""
+        return val if val.nil? || val == ''
 
         # Try to parse as JSON first for complex types
         begin
@@ -438,6 +443,29 @@ module Familia
         val
       end
 
+      private
+
+      # Reset all transient fields to nil
+      #
+      # This method ensures that transient fields return to their uninitialized
+      # state during refresh operations. This provides semantic clarity (refresh
+      # means "reload from authoritative source"), ORM consistency with other
+      # frameworks, and prevents stale transient data accumulation.
+      #
+      # @return [void]
+      #
+      def reset_transient_fields!
+        return unless self.class.respond_to?(:transient_fields)
+
+        self.class.transient_fields.each do |field_name|
+          field_type = self.class.field_types[field_name]
+          next unless field_type&.method_name
+
+          # Set the transient field back to nil
+          send("#{field_type.method_name}=", nil)
+          Familia.ld "[reset_transient_fields!] Reset #{field_name} to nil"
+        end
+      end
     end
 
     include Serialization # these become Horreum instance methods

data/lib/familia/horreum/settings.rb

@@ -1,5 +1,5 @@
 # lib/familia/horreum/settings.rb
-#
+
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
   #
@@ -7,7 +7,6 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-
     # Settings - Module containing settings for Familia::Horreum (InstanceMethods)
     #
     module Settings
@@ -26,6 +25,15 @@ module Familia
         @logical_database || self.class.logical_database
       end
 
+      # Retrieves the prefix for the current instance by delegating to its class.
+      #
+      # @return [String] The prefix associated with the class of the current instance.
+      # @example
+      #   instance.prefix
+      def prefix
+        self.class.prefix
+      end
+
       def suffix
         @suffix || self.class.suffix
       end

data/lib/familia/horreum/utils.rb

@@ -7,17 +7,16 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-
     # Utils - Module containing utility methods for Familia::Horreum (InstanceMethods)
     #
     module Utils
-
-      def uri(suffix = nil)
-        u = Familia.uri(self.class.uri) # returns URI::Redis
-        u.logical_database = logical_database if logical_database # override the logical_database if we have one
-        u.key = dbkey(suffix)
-        u
-      end
+      # def uri
+      #   base_uri = self.class.uri || Familia.uri
+      #   u = base_uri.dup # make a copy to modify safely
+      #   u.logical_database = logical_database if logical_database
+      #   u.key = dbkey
+      #   u
+      # end
 
       # +suffix+ is the value to be used at the end of the db key
       # (e.g. `customer:customer_id:scores` would have `scores` as the suffix
@@ -27,8 +26,9 @@ module Familia
       # Whether this is a Horreum or DataType object, the value is taken
       # from the `identifier` method).
       #
-      def dbkey(suffix = nil, ignored = nil)
+      def dbkey(suffix = nil, _ignored = nil)
         raise Familia::NoIdentifier, "No identifier for #{self.class}" if identifier.to_s.empty?
+
         suffix ||= self.suffix # use the instance method to get the default suffix
         self.class.dbkey identifier, suffix
       end
@@ -36,7 +36,6 @@ module Familia
       def join(*args)
         Familia.join(args.map { |field| send(field) })
       end
-
     end
 
     include Utils # these become Horreum instance methods

data/lib/familia/horreum.rb

@@ -62,7 +62,8 @@ module Familia
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
-        member.extend(ClassMethods)
+        member.extend(DefinitionMethods)
+        member.extend(ManagementMethods)
         member.extend(Connection)
         member.extend(Features)
 
@@ -133,7 +134,11 @@ module Familia
       # Implementing classes can define an init method to do any
       # additional initialization. Notice that this is called
       # after the fields are set.
-      init if respond_to?(:init)
+      init
+    end
+
+    def init(*args, **kwargs)
+      # Default no-op
     end
 
     # Sets up related Database objects for the instance
@@ -150,9 +155,9 @@ module Familia
       #     familia_object.dbkey              == v1:bone:INDEXVALUE:object
       #     familia_object.related_object.dbkey == v1:bone:INDEXVALUE:name
       #
-      self.class.related_fields.each_pair do |name, datatype_definition|
-        klass = datatype_definition.klass
-        opts = datatype_definition.opts
+      self.class.related_fields.each_pair do |name, data_type_definition|
+        klass = data_type_definition.klass
+        opts = data_type_definition.opts
         Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
@@ -215,7 +220,9 @@ module Familia
         # we use symbols. So we check for both.
         value = fields[field.to_sym] || fields[field.to_s]
         if value
-          send(:"#{field}=", value)
+          # Use the mapped method name, not the field name
+          method_name = self.class.field_method_map[field] || field
+          send(:"#{method_name}=", value)
           field.to_sym
         end
       end
@@ -283,9 +290,8 @@ module Familia
     #   # => #<Redis client v5.4.1 for redis://localhost:6379/0>
     #
     def dbclient
-      conn = Fiber[:familia_transaction] || @dbclient || self.class.dbclient
+      Fiber[:familia_transaction] || @dbclient || self.class.dbclient
       # conn.select(self.class.logical_database)
-      conn
     end
 
     def generate_id
@@ -299,13 +305,15 @@ module Familia
       # This allows passing Familia objects directly where strings are expected
       # without requiring explicit .identifier calls
       return super if identifier.to_s.empty?
+
       identifier.to_s
     end
   end
 end
 
-require_relative 'horreum/class_methods'
-require_relative 'horreum/commands'
+require_relative 'horreum/definition_methods'
+require_relative 'horreum/management_methods'
+require_relative 'horreum/database_commands'
 require_relative 'horreum/connection'
 require_relative 'horreum/serialization'
 require_relative 'horreum/settings'

data/lib/familia/logging.rb

@@ -6,14 +6,14 @@ require 'logger'
 module Familia
   @logger = Logger.new($stdout)
   @logger.progname = name
-  @logger.formatter = proc do |severity, datetime, progname, msg|
-    severity_letter = severity[0]  # Get the first letter of the severity
+  @logger.formatter = proc do |severity, datetime, _progname, msg|
+    severity_letter = severity[0] # Get the first letter of the severity
     pid = Process.pid
     thread_id = Thread.current.object_id
-    full_path, line = caller[4].split(":")[0..1]
+    full_path, line = caller(5..5).first.split(':')[0..1]
     parent_path = Pathname.new(full_path).ascend.find { |p| p.basename.to_s == 'familia' }
     relative_path = full_path.sub(parent_path.to_s, 'familia')
-    utc_datetime = datetime.utc.strftime("%m-%d %H:%M:%S.%6N")
+    utc_datetime = datetime.utc.strftime('%m-%d %H:%M:%S.%6N')
 
     # Get the severity letter from the thread local variable or use
     # the default. The thread local variable is set in the trace
@@ -115,6 +115,7 @@ module Familia
 
     def ld(*msg)
       return unless Familia.debug?
+
       @logger.debug(*msg)
     end
 
@@ -152,15 +153,15 @@ module Familia
       # and multi blocks. In some contexts it's nil where the
       # database connection isn't relevant.
       instance_id = if dbclient
-        case dbclient
-        when Redis
-          dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
-        when Redis::Future
-          "Redis::Future"
-        else
-        dbclient.class.name
-        end
-      end
+                      case dbclient
+                      when Redis
+                        dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
+                      when Redis::Future
+                        'Redis::Future'
+                      else
+                        dbclient.class.name
+                      end
+                    end
 
       codeline = if context
                    context = [context].flatten
@@ -170,7 +171,6 @@ module Familia
 
       @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
-
   end
 end