familia 1.0.0.pre.rc1 → 1.0.0.pre.rc3

data/lib/familia/horreum/serialization.rb

@@ -1,24 +1,75 @@
 # rubocop:disable all
 #
 module Familia
-  # InstanceMethods - Module containing instance-level methods for Familia
-  #
-  # This module is included in classes that include Familia, providing
-  # instance-level functionality for Redis operations and object management.
+
+
+  # Familia::Horreum
   #
   class Horreum
-
-    # Methods that call load and dump (InstanceMethods)
+    # Serialization: Where Objects Go to Become Strings (and Vice Versa)!
+    #
+    # This module is chock-full of methods that'll make your head spin (in a
+    # good way)! We've got loaders, dumpers, and refreshers galore. It's like
+    # a laundromat for your data, but instead of quarters, it runs on Redis commands.
+    #
+    # A Note on Our Refreshing Refreshers:
+    # In the wild world of Ruby, '!' usually means "Watch out! I'm dangerous!"
+    # But here in Familia-land, we march to the beat of a different drummer.
+    # Our refresh! method is the real deal, doing all the heavy lifting.
+    # The non-bang refresh? Oh, it's just as rowdy, but it plays nice with
+    # method chaining. It's like the polite twin who still knows how to party.
+    #
+    # Remember: In Familia, refreshing isn't just a chore, it's a chance to
+    # dance with data! Whether you bang(!) or not, you're still invited to
+    # the Redis disco.
+    #
+    # (P.S. If you're reading these docs, lol sorry. I asked Claude 3.5 to
+    # write in the style of _why the lucky stiff today and got this uncanny
+    # valley response. I hope you enjoy reading it as much as I did writing
+    # the prompt for it. - @delano).
+    #
+    # (Ahem! What I meant to say was that if you're reading this, congratulations!
+    # You've stumbled upon the secret garden of documentation. Feel free to smell
+    # the Ruby roses, but watch out for the Redis thorns!)
     #
     module Serialization
-      #include Familia::RedisType::Serialization
 
       attr_writer :redis
 
+      # Summon the mystical Redis connection from the depths of instance or class.
+      #
+      # This method is like a magical divining rod, always pointing to the nearest
+      # source of Redis goodness. It first checks if we have a personal Redis
+      # connection (@redis), and if not, it borrows the class's connection.
+      #
+      # @return [Redis] A shimmering Redis connection, ready for your bidding.
+      #
+      # @example Finding your Redis way
+      #   puts object.redis
+      #   # => #<Redis client v4.5.1 for redis://localhost:6379/0>
+      #
       def redis
         @redis || self.class.redis
       end
 
+      # Perform a sacred Redis transaction ritual.
+      #
+      # This method creates a protective circle around your Redis operations,
+      # ensuring they all succeed or fail together. It's like a group hug for your
+      # data operations, but with more ACID properties.
+      #
+      # @yield [conn] A block where you can perform your Redis incantations.
+      # @yieldparam conn [Redis] A Redis connection in multi mode.
+      #
+      # @example Performing a Redis rain dance
+      #   transaction do |conn|
+      #     conn.set("weather", "rainy")
+      #     conn.set("mood", "melancholic")
+      #   end
+      #
+      # @note This method temporarily replaces your Redis connection with a multi
+      #   connection. Don't worry, it puts everything back where it found it when it's done.
+      #
       def transaction
         original_redis = self.redis
 
@@ -32,25 +83,74 @@ module Familia
         end
       end
 
-      # A thin wrapper around `commit_fields` that updates the timestamps and
-      # returns a boolean.
+      # Save our precious data to Redis, with a sprinkle of timestamp magic!
+      #
+      # This method is like a conscientious historian, not only recording your
+      # object's current state but also meticulously timestamping when it was
+      # created and last updated. It's the record keeper of your data's life story!
+      #
+      # @return [Boolean] true if the save was successful, false if Redis was grumpy.
+      #
+      # @example Preserving your pet rock for posterity
+      #   rocky = PetRock.new(name: "Dwayne")
+      #   rocky.save
+      #   # => true (Dwayne is now immortalized in Redis)
+      #
+      # @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
         Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
 
-        # Update timestamp fields
+        # Update our object's life story
+        self.key ||= self.identifier
         self.updated = Familia.now.to_i
-        self.created = Familia.now.to_i unless self.created
+        self.created ||= Familia.now.to_i
 
-        # Thr return value of commit_fields is an array of strings: ["OK"].
+        # Commit our tale to the Redis chronicles
         ret = commit_fields # e.g. ["OK"]
 
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
-        # Convert the return value to a boolean
-        ret.all? { |value| value == "OK" }
+        # Did Redis accept our offering?
+        ret.uniq.all? { |value| value == "OK" }
       end
 
-      # +return: [Array<String>] The return value of the Redis multi command
+      # Apply a smattering of fields to this object like fairy dust.
+      #
+      # @param fields [Hash] A magical bag of named attributes to sprinkle onto this instance.
+      #   Each key-value pair is like a tiny spell, ready to enchant our object's properties.
+      #
+      # @return [self] Returns the newly bejeweled instance, now sparkling with fresh attributes.
+      #
+      # @example Giving your object a makeover
+      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys named Jackie")
+      #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire", @loves="little boys named Jackie">
+      #
+      def apply_fields(**fields)
+        fields.each do |field, value|
+          # Whisper the new value into the object's ear (if it's listening)
+          send("#{field}=", value) if respond_to?("#{field}=")
+        end
+        self
+      end
+
+      # Commit our precious fields to Redis.
+      #
+      # This method performs a sacred ritual, sending our cherished attributes
+      # on a journey through the ethernet to find their resting place in Redis.
+      #
+      # @return [Array<String>] A mystical array of strings, cryptic messages from the Redis gods.
+      #
+      # @note Be warned, young programmer! This method dabbles in the arcane art of transactions.
+      #   Side effects may include data persistence and a slight tingling sensation.
+      #
+      # @example Offering your changes to the Redis deities
+      #   unicorn.name = "Charlie"
+      #   unicorn.horn_length = "magnificent"
+      #   unicorn.commit_fields
+      #   # => ["OK", "OK"] (The Redis gods are pleased with your offering)
+      #
       def commit_fields
         Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
         transaction do |conn|
@@ -59,33 +159,107 @@ module Familia
         end
       end
 
+      # Dramatically vanquish this object from the face of Redis! (ed: delete it)
+      #
+      # This method is the doomsday device of our little data world. It will
+      # mercilessly eradicate all traces of our object from Redis, leaving naught
+      # but digital dust in its wake. Use with caution, lest you accidentally
+      # destroy the wrong data-verse!
+      #
+      # @return [void] Returns nothing, for nothing remains after destruction.
+      #
+      # @example Bidding a fond farewell to your pet rock
+      #   rocky = PetRock.new(name: "Dwayne")
+      #   rocky.destroy!
+      #   # => *poof* Rocky is no more. A moment of silence, please.
+      #
+      # @note If debugging is enabled, this method will leave a trace of its
+      #   destructive path, like breadcrumbs for future data archaeologists.
+      #
+      # @see #delete! The actual hitman carrying out the deed.
+      #
       def destroy!
         Familia.trace :DESTROY, redis, redisuri, caller(1..1) if Familia.debug?
         delete!
       end
 
+
+      # Refreshes the object's state by querying Redis and overwriting the
+      # current field values. This method performs a destructive update on the
+      # object, regardless of unsaved changes.
+      #
+      # @note This is a destructive operation that will overwrite any unsaved
+      #   changes.
+      # @return The list of field names that were updated.
+      def refresh!
+        Familia.trace :REFRESH, redis, redisuri, caller(1..1) if Familia.debug?
+        fields = hgetall
+        Familia.ld "[refresh!] #{self.class} #{rediskey} #{fields.keys}"
+        optimistic_refresh(**fields)
+      end
+
+      # Refreshes the object's state and returns self to allow method chaining.
+      # This method calls refresh! internally, performing the actual Redis
+      # query and state update.
+      #
+      # @note While this method allows chaining, it still performs a
+      #   destructive update like refresh!.
+      # @return [self] Returns the object itself after refreshing, allowing
+      #   method chaining.
+      def refresh
+        refresh!
+        self
+      end
+
+      # Transform this object into a magical hash of wonders!
+      #
+      # This method performs an alchemical transmutation, turning our noble object
+      # into a more plebeian hash. But fear not, for in this form, it can slip through
+      # the cracks of the universe (or at least, into Redis) with ease.
+      #
+      # @return [Hash] A glittering hash, each key a field name, each value a Redis-ready treasure.
+      #
+      # @example Turning your dragon into a hash
+      #   dragon.to_h
+      #   # => {"name"=>"Puff", "breathes"=>"fire", "age"=>1000}
+      #
+      # @note Watch in awe as each field is lovingly prepared for its Redis adventure!
+      #
       def to_h
-        # Use self.class.fields to efficiently generate a hash
-        # of all the fields for this object
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
-          prepared = val.to_s
+          prepared = to_redis(val)
           Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
           hsh[field] = prepared
           hsh
         end
       end
 
+      # Line up all our attributes in a neat little array parade!
+      #
+      # This method marshals all our object's attributes into an orderly procession,
+      # ready to march into Redis in perfect formation. It's like a little data army,
+      # but friendlier and less prone to conquering neighboring databases.
+      #
+      # @return [Array] A splendid array of Redis-ready values, in the order of our fields.
+      #
+      # @example Arranging your unicorn's attributes in a line
+      #   unicorn.to_a
+      #   # => ["Charlie", "magnificent", 5]
+      #
+      # @note Each value is carefully disguised in its Redis costume before joining the parade.
+      #
       def to_a
         self.class.fields.map do |field|
           val = send(field)
-          Familia.ld " [to_a] field: #{field} val: #{val}"
-          to_redis(val)
+          prepared = to_redis(val)
+          Familia.ld " [to_a] field: #{field} val: #{val.class} prepared: #{prepared.class}"
+          prepared
         end
       end
 
-      # The to_redis method in Familia::Redistype and Familia::Horreum serve similar purposes
-      # but have some key differences in their implementation:
+      # The to_redis method in Familia::Redistype and Familia::Horreum serve
+      # similar purposes but have some key differences in their implementation:
       #
       # Similarities:
       # - Both methods aim to serialize various data types for Redis storage
@@ -97,16 +271,19 @@ module Familia
       # - Familia::Horreum had more explicit type checking and conversion
       # - Familia::Redistype includes more extensive debug tracing
       #
-      # The centralized Familia.distinguisher method accommodates both approaches by:
-      # 1. Handling a wide range of data types, including those from both implementations
+      # The centralized Familia.distinguisher method accommodates both approaches
+      # by:
+      # 1. Handling a wide range of data types, including those from both
+      #    implementations
       # 2. Providing a 'strict_values' option for flexible type handling
       # 3. Supporting custom serialization through a dump_method
       # 4. Including debug tracing similar to Familia::Redistype
       #
-      # By using Familia.distinguisher, we achieve more consistent behavior across
-      # different parts of the library while maintaining the flexibility to handle
-      # various data types and custom serialization needs. This centralization
-      # also makes it easier to extend or modify serialization behavior in the future.
+      # By using Familia.distinguisher, we achieve more consistent behavior
+      # across different parts of the library while maintaining the flexibility
+      # to handle various data types and custom serialization needs. This
+      # centralization also makes it easier to extend or modify serialization
+      # behavior in the future.
       #
       def to_redis(val)
         prepared = Familia.distinguisher(val, false)
@@ -115,40 +292,46 @@ module Familia
           prepared = val.send(dump_method)
         end
 
-        Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}" if prepared.nil?
+        if prepared.nil?
+          Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}"
+        end
+
         prepared
       end
 
+      # Set an expiration date for our data, like a "best before" sticker for Redis!
+      #
+      # This method gives our data a lifespan in Redis. It's like telling Redis,
+      # "Hey, this data is fresh now, but it might get stale after a while!"
+      #
+      # @param ttl [Integer, nil] The Time To Live in seconds. If nil, we'll check
+      #   our options for a default expiration time.
+      #
+      # @return [Boolean] true if the expiration was set successfully, false otherwise.
+      #   It's like asking Redis, "Did you stick that expiration label on properly?"
+      #
+      # @example Making your pet rock data mortal
+      #   rocky.update_expiration(86400) # Dwayne will live in Redis for one day
+      #
+      # @note If the TTL is zero, we assume our data wants to live forever.
+      #   Immortality in Redis! Who wouldn't want that?
+      #
       def update_expiration(ttl = nil)
         ttl ||= opts[:ttl]
-        return if ttl.to_i.zero? # nil will be zero
+        ttl = ttl.to_i
+
+        return if ttl.zero?
 
-        Familia.ld "#{rediskey} to #{ttl}"
-        expire ttl.to_i
+        Familia.ld "Setting expiration for #{rediskey} to #{ttl} seconds"
+
+        # EXPIRE command returns 1 if the timeout was set, 0 if key does not
+        # exist or the timeout could not be set.
+        expire(ttl).positive?
       end
+
     end
+    # End of Serialization module
 
     include Serialization # these become Horreum instance methods
   end
 end
-
-__END__
-
-
-
-# From RedisHash
-def save
-  hsh = { :key => identifier }
-  ret = commit_fields hsh
-  ret == "OK"
-end
-
-def update_fields hsh={}
-  check_identifier!
-  hsh[:updated] = OT.now.to_i
-  hsh[:created] = OT.now.to_i unless has_key?(:created)
-  ret = update hsh  # update is defined in HashKey
-  ## NOTE: caching here like this only works if hsh has all keys
-  #self.cache.replace hsh
-  ret
-end

data/lib/familia/horreum/utils.rb

@@ -27,9 +27,10 @@ module Familia
       # Whether this is a Horreum or RedisType object, the value is taken
       # from the `identifier` method).
       #
-      def rediskey(suffix = self.suffix, ignored = nil)
+      def rediskey(suffix = nil, ignored = nil)
         Familia.ld "[#rediskey] #{identifier} for #{self.class}"
         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.rediskey identifier, suffix
       end
 

data/lib/familia/horreum.rb

@@ -94,6 +94,15 @@ module Familia
         # end
       end
 
+      # Automatically add a 'key' field if it's not already defined
+      # This ensures that every object has a unique identifier
+      unless self.class.fields.include?(:key)
+        # Define the 'key' field for this class
+        # This approach allows flexibility in how identifiers are generated
+        # while ensuring each object has a consistent way to be referenced
+        self.class.field :key # , default: -> { identifier }
+      end
+
       # Implementing classes can define an init method to do any
       # additional initialization. Notice that this is called
       # after the fields are set.
@@ -145,23 +154,64 @@ module Familia
       end
     end
 
+    # Initializes the object with positional arguments.
+    # Maps each argument to a corresponding field in the order they are defined.
+    #
+    # @param args [Array] List of values to be assigned to fields
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
     def initialize_with_positional_args(*args)
-      self.class.fields.zip(args).each do |field, value|
-        send(:"#{field}=", value) if value
+      Familia.trace :INITIALIZE_ARGS, redis, args, caller(1..1) if Familia.debug?
+      self.class.fields.zip(args).filter_map do |field, value|
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
       end
     end
     private :initialize_with_positional_args
 
-    def initialize_with_keyword_args(**kwargs)
-      self.class.fields.each do |field|
+    # Initializes the object with keyword arguments.
+    # Assigns values to fields based on the provided hash of field names and values.
+    # Handles both symbol and string keys to accommodate different sources of data.
+    #
+    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_keyword_args(**fields)
+      Familia.trace :INITIALIZE_KWARGS, redis, fields.keys, caller(1..1) if Familia.debug?
+      self.class.fields.filter_map do |field|
         # Redis will give us field names as strings back, but internally
-        # we use symbols. So we do both.
-        value = kwargs[field.to_sym] || kwargs[field.to_s]
-        send(:"#{field}=", value) if value
+        # we use symbols. So we check for both.
+        value = fields[field.to_sym] || fields[field.to_s]
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
       end
     end
     private :initialize_with_keyword_args
 
+    # A thin wrapper around the private initialize method that accepts a field
+    # hash and refreshes the existing object.
+    #
+    # This method is part of horreum.rb rather than serialization.rb because it
+    # operates solely on the provided values and doesn't query Redis or other
+    # external sources. That's why it's called "optimistic" refresh: it assumes
+    # the provided values are correct and updates the object accordingly.
+    #
+    # @see #refresh!
+    #
+    # @param fields [Hash] A hash of field names and their new values to update
+    #   the object with.
+    # @return [Array] The list of field names that were updated.
+    def optimistic_refresh(**fields)
+      Familia.ld "[optimistic_refresh] #{self.class} #{rediskey} #{fields.keys}"
+      initialize_with_keyword_args(**fields)
+    end
+
     # Determines the unique identifier for the instance
     # This method is used to generate Redis keys for the object
     def identifier
@@ -183,7 +233,7 @@ module Familia
                   end
 
       # If the unique_id is nil, raise an error
-      raise Problem, "Identifier is nil for #{self}" if unique_id.nil?
+      raise Problem, "Identifier is nil for #{self.class}" if unique_id.nil?
       raise Problem, 'Identifier is empty' if unique_id.empty?
 
       unique_id

data/lib/familia/logging.rb

@@ -3,23 +3,6 @@
 require 'pathname'
 require 'logger'
 
-module LoggerTraceRefinement
-  # Set to same value as Logger::DEBUG since 0 is the floor
-  # without either more invasive changes to the Logger class
-  # or a CustomLogger class that inherits from Logger.
-  TRACE = 2 unless defined?(TRACE)
-  refine Logger do
-
-    def trace(progname = nil, &block)
-      Thread.current[:severity_letter] = 'T'
-      add(LoggerTraceRefinement::TRACE, nil, progname, &block)
-    ensure
-      Thread.current[:severity_letter] = nil
-    end
-
-  end
-end
-
 module Familia
   @logger = Logger.new($stdout)
   @logger.progname = name
@@ -38,7 +21,7 @@ module Familia
     # variable `severity_letter` is arbitrary and could be anything.
     severity_letter = Thread.current[:severity_letter] || severity_letter
 
-    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  <#{relative_path}:#{line}>\n"
+    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  [#{relative_path}:#{line}]\n"
   end
 
   # The Logging module provides a set of methods and constants for logging messages
@@ -120,7 +103,7 @@ module Familia
     attr_reader :logger
 
     # Gives our logger the ability to use our trace method.
-    #using LoggerTraceRefinement if Familia.debug
+    using LoggerTraceRefinement if LoggerTraceRefinement::ENABLED
 
     def info(*msg)
       @logger.info(*msg)
@@ -156,14 +139,14 @@ module Familia
     # @return [nil]
     #
     def trace(label, redis_instance, ident, context = nil)
-      return unless Familia.debug? && ENV.key?('FAMILIA_TRACE')
+      return unless LoggerTraceRefinement::ENABLED
       instance_id = redis_instance&.id
       codeline = if context
                    context = [context].flatten
                    context.reject! { |line| line =~ %r{lib/familia} }
                    context.first
                  end
-      @logger.debug format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
+      @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
     end
 
   end

data/lib/familia/redistype.rb

@@ -61,10 +61,10 @@ module Familia
       end
     end
 
-    attr_reader :name, :parent, :opts
+    attr_reader :keystring, :parent, :opts
     attr_writer :dump_method, :load_method
 
-    # +name+: If parent is set, this will be used as the suffix
+    # +keystring+: If parent is set, this will be used as the suffix
     # for rediskey. Otherwise this becomes the value of the key.
     # If this is an Array, the elements will be joined.
     #
@@ -92,10 +92,10 @@ module Familia
     #
     # Uses the redis connection of the parent or the value of
     # opts[:redis] or Familia.redis (in that order).
-    def initialize(name, opts = {})
+    def initialize(keystring, opts = {})
       #Familia.ld " [initializing] #{self.class} #{opts}"
-      @name = name
-      @name = @name.join(Familia.delim) if @name.is_a?(Array)
+      @keystring = keystring
+      @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
 
       # Remove all keys from the opts that are not in the allowed list
       @opts = opts || {}
@@ -112,7 +112,7 @@ module Familia
 
     # Produces the full redis key for this object.
     def rediskey
-      Familia.ld "[rediskey] #{name} for #{self.class} (#{opts})"
+      Familia.ld "[rediskey] #{keystring} for #{self.class} (#{opts})"
 
       # Return the hardcoded key if it's set. This is useful for
       # support legacy keys that aren't derived in the same way.
@@ -121,15 +121,15 @@ module Familia
       if parent_instance?
         # This is an instance-level redistype object so the parent instance's
         # rediskey method is defined in Familia::Horreum::InstanceMethods.
-        parent.rediskey(name)
+        parent.rediskey(keystring)
       elsif parent_class?
         # This is a class-level redistype object so the parent class' rediskey
         # method is defined in Familia::Horreum::ClassMethods.
-        parent.rediskey(name, nil)
+        parent.rediskey(keystring, nil)
       else
-        # This is a standalone RedisType object where it's name
+        # This is a standalone RedisType object where it's keystring
         # is the full key.
-        name
+        keystring
       end
     end