familia 1.0.0.pre.rc5 → 1.0.0.pre.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3218c877946104986176b606caef17360ba262e22372dd61597982f9b97661db
-  data.tar.gz: b699a7b951ccf64c3421c9f79e29f927d3df0a36a0caa005575e118ae8ad000c
+  metadata.gz: 4d368f329560a1afd7252a2c8de830a7230334933cd00715b4b952e44d9fbf63
+  data.tar.gz: edd7b843ff07cf87aa2fe46766d7b0fd6dfa814b5404c9ca04bc42de18b05619
 SHA512:
-  metadata.gz: a19eca2cdcf6fe40e2c4109199938f95c02af3e3f6f4dda247720c983e6340ed725143a350f72b00a7c0c8d16bdab7dfb82ac4314a4d786249381f34fcb2da35
-  data.tar.gz: 2a9b815eed8437ea6514a7d29288ecf151c371ed2013495a5eaa6e2294bf61f75c07c9946c28dbf75fcdd0df7fdc1b5890ab0d83a9354f951c0f43e7718f0df8
+  metadata.gz: 0f4db87dbaa2c12636d8293a477ef1e2a000364d3e6e2515cac90dad7277efc29d3670103cdf4f7697960ec90012ddec7071004146785ec7d3c838863e1a241b
+  data.tar.gz: a1812fce749dc485753a10c39281feb1babab24fd95ecdd553398c4a07a800836d7bf4ac4a7574ee987d4d181842e089cd732efa343141a0bf4610594ea8f1cd

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (1.0.0.pre.rc5)
+    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-rc5 (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: rc5
+: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

@@ -37,25 +37,25 @@ 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)
       ttl ||= self.ttl

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,18 +6,26 @@ module Familia
   # Familia::Horreum
   #
   class Horreum
-    # List of valid return values for Redis commands.
-    # This includes:
-    # - "OK": Indicates successful execution of a command.
-    # - true: Indicates a successful boolean response.
-    # - 1: Indicates success for commands that return a count of affected items.
-    # - 0: Indicates success for commands that return a count of affected items, but no items were affected.
-    # - nil: Indicates the absence of a value, which can be considered a valid outcome in some contexts.
+    # 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!
     #
-    # This list is used to validate the return values of multiple Redis commands executed within methods.
-    # Methods that run multiple Redis commands will check if all return values are included in this list
-    # to determine overall success. If any return value is not in this list, it is considered unexpected
-    # and may be logged or handled accordingly.
     @valid_command_return_values = ["OK", true, 1, 0, nil]
 
     class << self
@@ -117,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
@@ -126,7 +134,9 @@ module Familia
         self.created ||= Familia.now.to_i
 
         # Commit our tale to the Redis chronicles
-        ret = commit_fields # e.g. MultiResult.new(true, ["OK", "OK"])
+        #
+        # e.g. `ret`  # => MultiResult.new(true, ["OK", "OK"])
+        ret = commit_fields(update_expiration: update_expiration)
 
         Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
 
@@ -200,15 +210,15 @@ 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
-        Familia.ld "[commit_fields] #{self.class} #{rediskey} #{to_h}"
+      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
@@ -224,10 +234,10 @@ module Familia
         # 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}"
+          Familia.warn "[commit_fields] Unexpected return values: #{unexpected_values.inspect}"
         end
 
-        Familia.ld "[commit_fields] #{self.class} #{rediskey} #{summary_boolean}: #{command_return_values}"
+        Familia.ld "[commit_fields2] #{self.class} #{rediskey} #{summary_boolean}: #{command_return_values}"
 
         MultiResult.new(summary_boolean, command_return_values)
       end
@@ -256,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
@@ -270,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
@@ -332,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)
@@ -376,31 +409,33 @@ module Familia
     end
     # End of Serialization module
 
-    # Represents the result of a multiple Redis commands.
+    # The magical MultiResult, keeper of Redis's deepest secrets!
     #
-    # This class encapsulates the outcome of a Redis "transaction",
-    # providing both a success indicator and the raw results from
-    # the Redis commands executed during the transaction ("MULTI").
+    # 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] Indicates whether all Redis commands
-    #   in the transaction were successful.
-    # @attr_reader results [Array<String>] An array of return values from
-    #   the Redis commands executed in the transaction.
+    # @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 Creating a MultiResult
+    # @example Summoning a MultiResult from the void
     #   result = MultiResult.new(true, ["OK", "OK"])
     #
-    # @example Checking the success of a commit
+    # @example Divining the success of your Redis ritual
     #   if result.successful?
-    #     puts "All commands succeeded"
+    #     puts "Huzzah! The Redis spirits smile upon you!"
     #   else
-    #     puts "Some commands failed"
+    #     puts "Alas! The Redis gremlins have conspired against us!"
     #   end
     #
-    # @example Accessing raw results
+    # @example Peering into the raw essence of results
     #   result.results.each_with_index do |value, index|
-    #     puts "Command #{index + 1} returned: #{value}"
+    #     puts "Command #{index + 1} whispered back: #{value}"
     #   end
+    #
     class MultiResult
       # @return [Boolean] true if all commands in the transaction succeeded,
       #   false otherwise

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.

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/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

@@ -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.rc5
+  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