familia 1.0.0.pre.rc4 → 1.0.0.pre.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b514a58bc45692f39123cce853a679078eccd78362a78facc397a1df6d94629d
-  data.tar.gz: d29686d172bec525bee366ab54ad4e81a5903547a9a2d98c68df8ca81853c7dc
+  metadata.gz: 4d368f329560a1afd7252a2c8de830a7230334933cd00715b4b952e44d9fbf63
+  data.tar.gz: edd7b843ff07cf87aa2fe46766d7b0fd6dfa814b5404c9ca04bc42de18b05619
 SHA512:
-  metadata.gz: cd750e1ee120eb666563e9c8c552f721926ccceaa032cd0cefcf4fad7920225ab1edc4961cf3a5a7c38d81ecab3c21b446e91a75347d51a4bc196c14f5ed94fd
-  data.tar.gz: 6c52919952e7ce8232cf1023fafe567655580a73e4d36dd0a38b8842cb618387272db6950380f71efa01797439d9542303d3addd8c94e841255923998b93589f
+  metadata.gz: 0f4db87dbaa2c12636d8293a477ef1e2a000364d3e6e2515cac90dad7277efc29d3670103cdf4f7697960ec90012ddec7071004146785ec7d3c838863e1a241b
+  data.tar.gz: a1812fce749dc485753a10c39281feb1babab24fd95ecdd553398c4a07a800836d7bf4ac4a7574ee987d4d181842e089cd732efa343141a0bf4610594ea8f1cd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (1.0.0.pre.rc4)
+    familia (1.0.0.pre.rc6)
       redis (>= 4.8.1, < 6.0)
       uri-redis (~> 1.3)
 

data/README.md

@@ -1,4 +1,4 @@
-# Familia - 1.0.0-rc4 (August 2024)
+# Familia - 1.0.0-rc6 (August 2024)
 
 **Organize and store Ruby objects in Redis. A powerful Ruby ORM (of sorts) for Redis.**
 

data/VERSION.yml

@@ -2,4 +2,4 @@
 :MAJOR: 1
 :MINOR: 0
 :PATCH: 0
-:PRE: rc4
+:PRE: rc6

data/lib/familia/base.rb

@@ -43,7 +43,7 @@ module Familia
     #
     # @note This method is a no-op. It's like shouting into the void, but less echo-y.
     #
-    def update_expiration(_ = nil)
+    def update_expiration(*)
       Familia.info "[update_expiration] Skipped for #{rediskey}. #{self.class} data is immortal!"
       nil
     end

data/lib/familia/features/expiration.rb

@@ -3,7 +3,7 @@
 
 
 module Familia::Features
-  #
+
   module Expiration
     @ttl = nil
 
@@ -37,27 +37,27 @@ module Familia::Features
       @ttl || self.class.ttl
     end
 
-    # Yo, check it out! We're gonna give our Redis data an expiration date!
+    # Sets an expiration time for the Redis data associated with this object.
     #
-    # It's like slapping a "Best Before" sticker on your favorite snack,
-    # but for data. How cool is that?
+    # This method allows setting a Time To Live (TTL) for the data in Redis,
+    # after which it will be automatically removed.
     #
-    # @param ttl [Integer, nil] The Time To Live in seconds. Nil? No worries!
-    #   We'll dig up the default from our secret stash.
+    # @param ttl [Integer, nil] The Time To Live in seconds. If nil, the default
+    #   TTL will be used.
     #
-    # @return [Boolean] Did Redis pin that expiry note successfully?
-    #   True for "Yep!", false for "Oops, butter fingers!"
+    # @return [Boolean] Returns true if the expiration was set successfully,
+    #   false otherwise.
     #
-    # @example Teaching your pet rock the concept of mortality
-    #   rocky.update_expiration(86400) # Dwayne gets to party in Redis for one whole day!
+    # @example Setting an expiration of one day
+    #   object.update_expiration(86400)
     #
-    # @note If TTL is zero, your data gets a VIP pass to the Redis eternity club.
-    #   Fancy, huh?
+    # @note If TTL is set to zero, the expiration will be removed, making the
+    #   data persist indefinitely.
     #
-    # @raise [Familia::Problem] If you try to feed it non-numbers or time-travel
-    #   (negative numbers). It's strict, but fair!
+    # @raise [Familia::Problem] Raises an error if the TTL is not a non-negative
+    #   integer.
     #
-    def update_expiration(ttl = nil)
+  def update_expiration(ttl = nil)
       ttl ||= self.ttl
       # It's important to raise exceptions here and not just log warnings. We
       # don't want to silently fail at setting expirations and cause data
@@ -67,14 +67,15 @@ module Familia::Features
       # good reason for the ttl to not be set in the first place. If the
       # class doesn't have a ttl, the default comes from Familia.ttl (which
       # is 0).
-      raise Familia::Problem, "TTL must be a number (#{ttl.class})" unless ttl.is_a?(Numeric)
-      raise Familia::Problem, "TTL must be positive (#{ttl})" unless ttl.is_a?(Numeric)
+      unless ttl.is_a?(Numeric)
+        raise Familia::Problem, "TTL must be a number (#{ttl.class} in #{self.class})"
+      end
 
       if ttl.zero?
         return Familia.ld "[update_expiration] No expiration for #{self.class} (#{rediskey})"
       end
 
-      Familia.info "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
+      Familia.ld "[update_expiration] Expires #{rediskey} in #{ttl} seconds"
 
       # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
       # not exist or the timeout could not be set. Via redis-rb here, it's

data/lib/familia/horreum/class_methods.rb

@@ -78,7 +78,11 @@ module Familia
         fast_writer! name
       end
 
-      # Defines a writer method with a bang (!) suffix for a given attribute name.
+      # Defines a fast writer method with a bang (!) suffix for a given
+      # attribute name. Fast writer methods are used to immediately persist
+      # attribute values to Redis. Calling a fast writer method has no
+      # effect on any of the object's other attributes and does not trigger
+      # a called to update the object's expiration time.
       #
       # The dynamically defined method performs the following:
       # - Checks if the correct number of arguments is provided (exactly one).
@@ -97,18 +101,18 @@ module Familia
           # Check if the correct number of arguments is provided (exactly one).
           raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1)" if args.size != 1
 
-          value = args.first
+          val = args.first
 
           begin
             # Trace the operation if debugging is enabled.
-            Familia.trace :FAST_WRITER, redis, "#{name}: #{value.inspect}", caller(1..1) if Familia.debug?
+            Familia.trace :FAST_WRITER, redis, "#{name}: #{val.inspect}", caller(1..1) if Familia.debug?
 
             # Convert the provided value to a format suitable for Redis storage.
-            prepared = to_redis(value)
-            Familia.ld "[.fast_writer!] #{name} val: #{value.class} prepared: #{prepared.class}"
+            prepared = to_redis(val)
+            Familia.ld "[.fast_writer!] #{name} val: #{val.class} prepared: #{prepared.class}"
 
             # Use the existing accessor method to set the attribute value.
-            send :"#{name}=", value
+            send :"#{name}=", val
 
             # Persist the value to Redis immediately using the hset command.
             hset name, prepared

data/lib/familia/horreum/commands.rb

@@ -23,8 +23,9 @@ module Familia
         self.class.exists? identifier, suffix
       end
 
-      # Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
-      # Returns 1 if the timeout was set, 0 if key does not exist or the timeout could not be set.
+      # Sets a timeout on key. After the timeout has expired, the key will
+      # automatically be deleted. Returns 1 if the timeout was set, 0 if key
+      # does not exist or the timeout could not be set.
       #
       def expire(ttl = nil)
         ttl ||= self.class.ttl

data/lib/familia/horreum/serialization.rb

@@ -6,6 +6,32 @@ module Familia
   # Familia::Horreum
   #
   class Horreum
+    # The Sacred Scrolls of Redis Responses
+    #
+    # Behold! The mystical runes that Redis whispers back to us:
+    #
+    # "OK" - The sweet sound of success, like a tiny "ding!" from the depths of data.
+    # true  - The boolean Buddha nods in agreement.
+    # 1     - A lonely digit, standing tall and proud. "I did something!" it proclaims.
+    # 0     - The silent hero. It tried its best, bless its heart.
+    # nil   - The zen master of responses. It's not nothing, it's... enlightenment!
+    #
+    # These sacred signs are our guide through the Redis wilderness. When we cast
+    # our spells (er, commands), we seek these friendly faces in the returned
+    # smoke signals.
+    #
+    # Should our Redis rituals summon anything else, we pause. We ponder. We
+    # possibly panic. For the unexpected in Redis-land is like finding a penguin
+    # in your pasta - delightfully confusing, but probably not what you ordered.
+    #
+    # May your Redis returns be ever valid, and your data ever flowing!
+    #
+    @valid_command_return_values = ["OK", true, 1, 0, nil]
+
+    class << self
+      attr_accessor :valid_command_return_values
+    end
+
     # 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
@@ -99,7 +125,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
+      def save update_expiration: true
         Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
 
         # Update our object's life story
@@ -108,12 +134,14 @@ module Familia
         self.created ||= Familia.now.to_i
 
         # Commit our tale to the Redis chronicles
-        ret = commit_fields # e.g. ["OK"]
+        #
+        # e.g. `ret`  # => MultiResult.new(true, ["OK", "OK"])
+        ret = commit_fields(update_expiration: update_expiration)
 
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
         # Did Redis accept our offering?
-        ret.uniq.all? { |value| ["OK", true].include?(value) }
+        ret.successful?
       end
 
       # Apply a smattering of fields to this object like fairy dust.
@@ -126,10 +154,10 @@ module Familia
       #   fresh attributes.
       #
       # @example Giving your object a makeover
-      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "little boys
+      #   dragon.apply_fields(name: "Puff", breathes: "fire", loves: "Toys
       #   named Jackie")
       #   # => #<Dragon:0x007f8a1c8b0a28 @name="Puff", @breathes="fire",
-      #   @loves="little boys named Jackie">
+      #   @loves="Toys named Jackie">
       #
       def apply_fields(**fields)
         fields.each do |field, value|
@@ -143,30 +171,75 @@ module Familia
       #
       # This method performs a sacred ritual, sending our cherished attributes
       # on a journey through the ethernet to find their resting place in Redis.
+      # It executes a transaction that includes setting field values and,
+      # if applicable, updating the expiration time.
       #
-      # @return [Array<String>] A mystical array of strings, cryptic messages
-      #   from the Redis gods.
+      # @return [MultiResult] A mystical object containing:
+      #   - success: A boolean indicating if all Redis commands succeeded
+      #   - results: An array of strings, cryptic messages from the Redis gods
+      #
+      # The MultiResult object responds to:
+      #   - successful?: Returns the boolean success value
+      #   - results: Returns the array of command return values
       #
       # @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.
+      #   slight tingling sensation. The method does not raise exceptions for
+      #   unexpected Redis responses, but logs warnings and returns a failure status.
       #
       # @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)
+      #   result = unicorn.commit_fields
+      #   if result.successful?
+      #     puts "The Redis gods are pleased with your offering"
+      #     p result.results  # => ["OK", "OK"]
+      #   else
+      #     puts "The Redis gods frown upon your offering"
+      #     p result.results  # Examine the unexpected values
+      #   end
+      #
+      # @see Familia::Horreum.valid_command_return_values for the list of
+      #   acceptable Redis command return values.
+      #
+      # @note This method performs logging at various levels:
+      #   - Debug: Logs the object's class, Redis key, and current state before committing
+      #   - Warn: Logs any unexpected return values from Redis commands
+      #   - Debug: Logs the final result, including success status and all return values
+      #
+      # @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
-        Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
-        transaction do |conn|
+      def commit_fields update_expiration: true
+        Familia.ld "[commit_fields1] #{self.class} #{rediskey} #{to_h} (update_expiration: #{update_expiration})"
+        command_return_values = transaction do |conn|
           hmset
 
           # Only classes that have the expiration ferature enabled will
           # actually set an expiration time on their keys. Otherwise
-          # this will be a no-op.
-          update_expiration
+          # this will be a no-op that simply logs the attempt.
+          self.update_expiration if update_expiration
         end
+
+        # The acceptable redis command return values are defined in the
+        # Horreum class. This is to ensure that all commands return values
+        # are validated against a consistent set of values.
+        acceptable_values = Familia::Horreum.valid_command_return_values
+
+        # Check if all return values are valid
+        summary_boolean = command_return_values.uniq.all? { |value|
+          acceptable_values.include?(value)
+        }
+
+        # Log the unexpected
+        unless summary_boolean
+          unexpected_values = command_return_values.reject { |value| acceptable_values.include?(value) }
+          Familia.warn "[commit_fields] Unexpected return values: #{unexpected_values.inspect}"
+        end
+
+        Familia.ld "[commit_fields2] #{self.class} #{rediskey} #{summary_boolean}: #{command_return_values}"
+
+        MultiResult.new(summary_boolean, command_return_values)
       end
 
       # Dramatically vanquish this object from the face of Redis! (ed: delete it)
@@ -193,13 +266,22 @@ module Familia
         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.
+      # The Great Redis Refresh-o-matic 3000
+      #
+      # Imagine your object as a forgetful time traveler. This method is like
+      # zapping it with a memory ray from Redis-topia. ZAP! New memories!
+      #
+      # WARNING: This is not a gentle mind-meld. It's more like a full brain
+      # transplant. Any half-baked ideas floating in your object's head? POOF!
+      # Gone quicker than cake at a hobbit's birthday party. Unsaved spells
+      # will definitely be forgotten.
+      #
+      # @return What do you get for this daring act of digital amnesia? A shiny
+      # list of all the brain bits that got a makeover!
+      #
+      # Remember: In the game of Redis-Refresh, you win or you... well, you
+      # always win, but sometimes you forget why you played in the first place.
       #
-      # @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
@@ -207,14 +289,20 @@ module Familia
         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.
+      # Ah, the magical refresh dance! It's like giving your object a
+      # sip from the fountain of youth.
+      #
+      # This method twirls your object around, dips it into the Redis pool,
+      # and brings it back sparkling clean and up-to-date. It's using the
+      # refresh! spell behind the scenes, so expect some Redis whispering.
+      #
+      # @note Caution, young Rubyist! While this method loves to play
+      #   chain-tag with other methods, it's still got that refresh! kick.
+      #   It'll update your object faster than you can say "matz!"
+      #
+      # @return [self] Your object, freshly bathed in Redis waters, ready
+      #   to dance with more methods in a conga line of Ruby joy!
       #
-      # @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
@@ -269,35 +357,43 @@ module Familia
         end
       end
 
-      # 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
-      # - Both handle basic data types like String, Symbol, and Numeric
-      # - Both have provisions for custom serialization methods
-      #
-      # Differences:
-      # - Familia::Redistype uses the opts[:class] for type hints
-      # - 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
-      # 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.
+      # Behold, the grand tale of two serialization sorcerers:
+      # Familia::Redistype and Familia::Horreum!
+      #
+      # These twin wizards, though cut from the same magical cloth,
+      # have their own unique spells for turning Ruby objects into
+      # Redis-friendly potions. Let's peek into their spell books:
+      #
+      # Shared Incantations:
+      # - Both transform various data creatures for Redis safekeeping
+      # - They tame wild Strings, Symbols, and those slippery Numerics
+      # - Secret rituals (aka custom serialization) are welcome
+      #
+      # Mystical Differences:
+      # - Redistype reads the future in opts[:class] tea leaves
+      # - Horreum prefers to interrogate types more thoroughly
+      # - Redistype leaves a trail of debug breadcrumbs
+      #
+      # But wait! Enter the wise Familia.distinguisher,
+      # a grand unifier of serialization magic!
+      #
+      # This clever mediator:
+      # 1. Juggles a circus of data types from both realms
+      # 2. Offers a 'strict_values' toggle for the type-obsessed
+      # 3. Welcomes custom spells via dump_method
+      # 4. Sprinkles debug fairy dust à la Redistype
+      #
+      # By channeling the Familia.distinguisher, we've created a
+      # harmonious serialization symphony, flexible enough to dance
+      # with any data type that shimmies our way. And should we need
+      # to teach it new tricks, we know just where to wave our wands!
+      #
+      # @param value [Object] The mystical object to be transformed
+      #
+      # @return [String] The transformed, Redis-ready value.
       #
       def to_redis(val)
-        prepared = Familia.distinguisher(val, false)
+        prepared = Familia.distinguisher(val, strict_values: false)
 
         if prepared.nil? && val.respond_to?(dump_method)
           prepared = val.send(dump_method)
@@ -313,6 +409,73 @@ module Familia
     end
     # End of Serialization module
 
+    # The magical MultiResult, keeper of Redis's deepest secrets!
+    #
+    # This quirky little class wraps up the outcome of a Redis "transaction"
+    # (or as I like to call it, a "Redis dance party") with a bow made of
+    # pure Ruby delight. It knows if your commands were successful and
+    # keeps the results safe in its pocket dimension.
+    #
+    # @attr_reader success [Boolean] The golden ticket! True if all your
+    #   Redis wishes came true in the transaction.
+    # @attr_reader results [Array<String>] A mystical array of return values,
+    #   each one a whisper from the Redis gods.
+    #
+    # @example Summoning a MultiResult from the void
+    #   result = MultiResult.new(true, ["OK", "OK"])
+    #
+    # @example Divining the success of your Redis ritual
+    #   if result.successful?
+    #     puts "Huzzah! The Redis spirits smile upon you!"
+    #   else
+    #     puts "Alas! The Redis gremlins have conspired against us!"
+    #   end
+    #
+    # @example Peering into the raw essence of results
+    #   result.results.each_with_index do |value, index|
+    #     puts "Command #{index + 1} whispered back: #{value}"
+    #   end
+    #
+    class MultiResult
+      # @return [Boolean] true if all commands in the transaction succeeded,
+      #   false otherwise
+      attr_reader :success
+
+      # @return [Array<String>] The raw return values from the Redis commands
+      attr_reader :results
+
+      # Creates a new MultiResult instance.
+      #
+      # @param success [Boolean] Whether all commands succeeded
+      # @param results [Array<String>] The raw results from Redis commands
+      def initialize(success, results)
+        @success = success
+        @results = results
+      end
+
+      # Returns a tuple representing the result of the transaction.
+      #
+      # @return [Array] A tuple containing the success status and the raw results.
+      #   The success status is a boolean indicating if all commands succeeded.
+      #   The raw results is an array of return values from the Redis commands.
+      #
+      # @example
+      #   [true, ["OK", true, 1]]
+      #
+      def tuple
+        [successful?, results]
+      end
+
+      # Convenient method to check if the commit was successful.
+      #
+      # @return [Boolean] true if all commands succeeded, false otherwise
+      def successful?
+        @success
+      end
+      alias success? successful?
+    end
+    # End of MultiResult class
+
     include Serialization # these become Horreum instance methods
   end
 end

data/lib/familia/horreum/utils.rb

@@ -14,7 +14,7 @@ module Familia
 
       def redisuri(suffix = nil)
         u = Familia.redisuri(self.class.uri) # returns URI::Redis
-        u.db ||= self.class.db.to_s # TODO: revisit logic (should the horrerum instance know its uri?)
+        u.db = db if db # override the db if we have one
         u.key = rediskey(suffix)
         u
       end

data/lib/familia/horreum.rb

@@ -24,7 +24,7 @@ module Familia
   class Horreum
     include Familia::Base
 
-    # == Singleton Class Context
+    # Singleton Class Context
     #
     # The code within this block operates on the singleton class (also known as
     # eigenclass or metaclass) of the current class. This means:
@@ -73,6 +73,18 @@ module Familia
       Familia.ld "[Horreum] Initializing #{self.class}"
       initialize_relatives
 
+      # Automatically add a 'key' field if it's not already defined. This ensures
+      # that every object horreum class has a unique identifier field. Ideally
+      # this logic would live somewhere else b/c we only need to call it once
+      # per class definition. Here it gets called every time an instance is
+      # instantiated/
+      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
+
       # If there are positional arguments, they should be the field
       # values in the order they were defined in the implementing class.
       #
@@ -94,15 +106,6 @@ 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.
@@ -233,7 +236,7 @@ module Familia
                   end
 
       # If the unique_id is nil, raise an error
-      raise Problem, "Identifier is nil for #{self.class}" if unique_id.nil?
+      raise Problem, "Identifier is nil for #{self.class} #{rediskey}" if unique_id.nil?
       raise Problem, 'Identifier is empty' if unique_id.empty?
 
       unique_id

data/lib/familia/redistype/serialization.rb

@@ -26,19 +26,19 @@ class Familia::RedisType
     # @raise [Familia::HighRiskFactor] If serialization fails under strict
     #   mode.
     #
-    def to_redis(val, strict_values = true)
+    def to_redis(val, strict_values: true)
       prepared = nil
 
       Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
 
       if opts[:class]
-        prepared = Familia.distinguisher(opts[:class], strict_values)
+        prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
         Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared||'<nil>'}"
       end
 
       if prepared.nil?
         # Enforce strict values when no class option is specified
-        prepared = Familia.distinguisher(val, true)
+        prepared = Familia.distinguisher(val, strict_values: true)
         Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
       end
 

data/lib/familia/redistype.rb

@@ -102,7 +102,12 @@ module Familia
 
       # Apply the options to instance method setters of the same name
       @opts.each do |k, v|
-        Familia.ld " [setting] #{k} #{v}"
+        # Bewarde logging :parent instance here implicitly calls #to_s which for
+        # some classes could include the identifier which could still be nil at
+        # this point. This would result in a Familia::Problem being raised. So
+        # to be on the safe-side here until we have a better understanding of
+        # the issue, we'll just log the class name for each key-value pair.
+        Familia.ld " [setting] #{k} #{v.class}"
         send(:"#{k}=", v) if respond_to? :"#{k}="
       end
 

data/lib/familia/types/sorted_set.rb

@@ -50,7 +50,7 @@ module Familia
     end
 
     def score(val)
-      ret = redis.zscore rediskey, to_redis(val, false)
+      ret = redis.zscore rediskey, to_redis(val, strict_values: false)
       ret&.to_f
     end
     alias [] score
@@ -63,13 +63,13 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = redis.zrank rediskey, to_redis(v, false)
+      ret = redis.zrank rediskey, to_redis(v, strict_values: false)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = redis.zrevrank rediskey, to_redis(v, false)
+      ret = redis.zrevrank rediskey, to_redis(v, strict_values: false)
       ret&.to_i
     end
 
@@ -208,7 +208,7 @@ module Familia
       # the identifier and not a serialized version of the object. So either
       # the value exists in the sorted set or it doesn't -- we don't need to
       # raise an error if it's not found.
-      redis.zrem rediskey, to_redis(val, false)
+      redis.zrem rediskey, to_redis(val, strict_values: false)
     end
     alias remove delete
     alias rem delete

data/lib/familia/utils.rb

@@ -38,7 +38,7 @@ module Familia
   #   # => "193tosc85k3u513do2mtmibchpd2ruh5l3nsp6dnl0ov1i91h7m7"
   #
   def generate_id(length: 32, encoding: 36)
-    raise ArgumentError, "Encoding must be between 2 and 32" unless (1..32).include?(encoding)
+    raise ArgumentError, "Encoding must be between 2 and 36" unless (1..36).include?(encoding)
 
     input = SecureRandom.hex(length)
     Digest::SHA256.hexdigest(input).to_i(16).to_s(encoding)
@@ -69,6 +69,7 @@ module Familia
   # @param uri [String, URI] URI to convert
   # @return [URI::Redis] Redis URI object
   def redisuri(uri)
+    uri ||= Familia.uri
     generic_uri = URI.parse(uri.to_s)
 
     # Create a new URI::Redis object
@@ -77,7 +78,7 @@ module Familia
       userinfo: generic_uri.userinfo,
       host: generic_uri.host,
       port: generic_uri.port,
-      path: generic_uri.path,
+      path: generic_uri.path, # the db is stored in the path
       query: generic_uri.query,
       fragment: generic_uri.fragment
     )
@@ -124,37 +125,60 @@ module Familia
       DIGEST_CLASS.hexdigest(concatenated_string)
     end
 
-    # This method determines the appropriate value to return based on the class of the input argument.
-    # It uses a case statement to handle different classes:
-    # - For Symbol, String, Integer, and Float classes, it traces the operation and converts the value to a string.
-    # - For Familia::Horreum class, it traces the operation and returns the identifier of the value.
-    # - For TrueClass, FalseClass, and NilClass, it traces the operation and converts the value to a string ("true", "false", or "").
+    # This method determines the appropriate transformation to apply based on
+    # the class of the input argument.
+    #
+    # @param [Object] value_to_distinguish The value to be processed. Keep in
+    #   mind that all data in redis is stored as a string so whatever the type
+    #   of the value, it will be converted to a string.
+    # @param [Boolean] strict_values Whether to enforce strict value handling.
+    #   Defaults to true.
+    # @return [String, nil] The processed value as a string or nil for unsupported
+    #   classes.
+    #
+    # The method uses a case statement to handle different classes:
+    # - For `Symbol`, `String`, `Integer`, and `Float` classes, it traces the
+    #   operation and converts the value to a string.
+    # - For `Familia::Horreum` class, it traces the operation and returns the
+    #   identifier of the value.
+    # - For `TrueClass`, `FalseClass`, and `NilClass`, it traces the operation and
+    #   converts the value to a string ("true", "false", or "").
     # - For any other class, it traces the operation and returns nil.
     #
-    # Alternative names for `value_to_distinguish` could be `input_value`, `value`, or `object`.
-    def distinguisher(value_to_distinguish, strict_values = true)
+    # Alternative names for `value_to_distinguish` could be `input_value`, `value`,
+    # or `object`.
+    #
+    def distinguisher(value_to_distinguish, strict_values: true)
       case value_to_distinguish
       when ::Symbol, ::String, ::Integer, ::Float
-        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "string", caller(1..1) if Familia.debug?
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "string", caller(1..1) if Familia.debug?
+
         # Symbols and numerics are naturally serializable to strings
         # so it's a relatively low risk operation.
         value_to_distinguish.to_s
 
       when ::TrueClass, ::FalseClass, ::NilClass
-        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "true/false/nil", caller(1..1) if Familia.debug?
-        # TrueClass, FalseClass, and NilClass are high risk because we can't
-        # reliably determine the original type of the value from the serialized
-        # string. This can lead to unexpected behavior when deserializing. For
-        # example, if a TrueClass value is serialized as "true" and then later
-        # deserialized as a String, it can cause errors in the application. Worse
-        # still, if a NilClass value is serialized as an empty string we lose the
-        # ability to distinguish between a nil value and an empty string when
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "true/false/nil", caller(1..1) if Familia.debug?
+
+        # TrueClass, FalseClass, and NilClass are considered high risk because their
+        # original types cannot be reliably determined from their serialized string
+        # representations. This can lead to unexpected behavior during deserialization.
+        # For instance, a TrueClass value serialized as "true" might be deserialized as
+        # a String, causing application errors. Even more problematic, a NilClass value
+        # serialized as an empty string makes it impossible to distinguish between a
+        # nil value and an empty string upon deserialization. Such scenarios can result
+        # in subtle, hard-to-diagnose bugs. To mitigate these risks, we raise an
+        # exception when encountering these types unless the strict_values option is
+        # explicitly set to false.
         #
         raise Familia::HighRiskFactor, value_to_distinguish if strict_values
         value_to_distinguish.to_s #=> "true", "false", ""
 
       when Familia::Base, Class
-        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
+        Familia.trace :TOREDIS_DISTINGUISHER, redis, "base", caller(1..1) if Familia.debug?
+
+        # When called with a class we simply transform it to its name. For
+        # instances of Familia class, we store the identifier.
         if value_to_distinguish.is_a?(Class)
           value_to_distinguish.name
         else
@@ -162,14 +186,15 @@ module Familia
         end
 
       else
-        #Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
+         Familia.trace :TOREDIS_DISTINGUISHER, redis, "else1 #{strict_values}", caller(1..1) if Familia.debug?
 
         if value_to_distinguish.class.ancestors.member?(Familia::Base)
-          #Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
+          Familia.trace :TOREDIS_DISTINGUISHER, redis, "isabase", caller(1..1) if Familia.debug?
+
           value_to_distinguish.identifier
 
         else
-          #Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
+          Familia.trace :TOREDIS_DISTINGUISHER, redis, "else2 #{strict_values}", caller(1..1) if Familia.debug?
           raise Familia::HighRiskFactor, value_to_distinguish if strict_values
           nil
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc4
+  version: 1.0.0.pre.rc6
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 2024-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis