familia 1.1.0.pre.rc1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7e5fe48e629eab30af342be4ad81f6afe5854b33b678b926b9c3470c0515627
-  data.tar.gz: 1d938baae35feb17f3d9855055152fdb0ba441317315fd3b2de6932e3c47e0cf
+  metadata.gz: 4a664f87a493fffb0e362752c8f988c8de27d83008f3a796b66737e3d15e771d
+  data.tar.gz: cb22d85f774e40a7b656713760f2f1e31b154171620038c282ce2dbe5e88492b
 SHA512:
-  metadata.gz: 707e9aba376653fa439ab1ffc85c4b794f1f52444dbed86a093f1d9c93a1952d8f84fe465cdcf8798bf0f72e5a4099586f1895cad5225f6d81899deeedcbf3a5
-  data.tar.gz: a9323482330bef4a632d92fd6828da32f0be7aa4f107d659e4440a2e3a09ad3dd0c2011d90a5e1a3380ca85fdf5afe47fb4634e9cf21951986d92115523bfbba
+  metadata.gz: 3942bab094053731bd0d45c47a89c7bde62d26b99339cd2fad36e5481b28f91cd3eecb17c8ef6f77e3e486858151f6d5821e973f9fb7c068431abf11634806db
+  data.tar.gz: 32933d4adbb991b3cb790f4a47134f7e428fa617b3f33d3068d98a2e795d2ee58b2654ac22fb913abdc46dd0f3459bcdfd50d71273a137d2f337c4da521e475d

data/.gitignore

@@ -8,6 +8,7 @@
 *.env
 *.log
 *.md
+!README.md
 *.txt
 !LICENSE.txt
 .ruby-version

data/.pre-commit-config.yaml

@@ -64,6 +64,6 @@ repos:
         stages: [prepare-commit-msg]
         name: Link commit to Github issue
         args:
-          - "--default=[NOJIRA]"
+          - "--default="
           - "--pattern=[a-zA-Z0-9]{0,10}-?[0-9]{1,5}"
           - "--template=[#{}]"

data/VERSION.yml

@@ -1,5 +1,4 @@
 ---
 :MAJOR: 1
-:MINOR: 1
+:MINOR: 2
 :PATCH: 0
-:PRE: rc1

data/lib/familia/horreum/commands.rb

@@ -22,22 +22,26 @@ module Familia
         redis.move rediskey, db
       end
 
-      # Checks if the calling object's key exists in Redis and has a non-zero size.
+      # Checks if the calling object's key exists in Redis.
       #
-      # This method retrieves the Redis URI associated with the calling object's class
-      # using `Familia.redis_uri_by_class`. It then checks if the specified key exists
-      # in Redis and that its size is not zero. If debugging is enabled, it logs the
-      # existence check using `Familia.trace`.
+      # @param check_size [Boolean] When true (default), also verifies the hash has a non-zero size.
+      #   When false, only checks key existence regardless of content.
+      # @return [Boolean] Returns `true` if the key exists in Redis. When `check_size` is true,
+      #   also requires the hash to have at least one field.
       #
-      # @return [Boolean] Returns `true` if the key exists in Redis and its size is not zero, otherwise `false`.
-      # @example
-      #   if some_object.exists?
-      #     # perform action
-      #   end
-      def exists?
-        true_or_false = self.class.redis.exists?(rediskey) && !size.zero?
-        Familia.trace :EXISTS, redis, "#{key} #{true_or_false.inspect}", caller(1..1) if Familia.debug?
-        true_or_false
+      # @example Check existence with size validation (default behavior)
+      #   some_object.exists?                    # => false for empty hashes
+      #   some_object.exists?(check_size: true)  # => false for empty hashes
+      #
+      # @example Check existence only
+      #   some_object.exists?(check_size: false)  # => true for empty hashes
+      #
+      # @note The default behavior maintains backward compatibility by treating empty hashes
+      #   as non-existent. Use `check_size: false` for pure key existence checking.
+      def exists?(check_size: true)
+        key_exists = self.class.redis.exists?(rediskey)
+        return key_exists unless check_size
+        key_exists && !size.zero?
       end
 
       # Returns the number of fields in the main object hash

data/lib/familia/horreum/serialization.rb

@@ -121,8 +121,9 @@ module Familia
       def save update_expiration: true
         Familia.trace :SAVE, redis, redisuri, caller(1..1) if Familia.debug?
 
-        # Update our object's life story
-        self.key ||= self.identifier
+        # Update our object's life story, keeping the mandatory built-in
+        # key field in sync with the field that is the chosen identifier.
+        self.key = self.identifier
         self.created ||= Familia.now.to_i if respond_to?(:created)
         self.updated = Familia.now.to_i if respond_to?(:updated)
 
@@ -137,6 +138,41 @@ module Familia
         ret.successful?
       end
 
+      # Updates multiple fields atomically in a Redis transaction.
+      #
+      # @param fields [Hash] Field names and values to update. Special key :update_expiration
+      #   controls whether to update key expiration (default: true)
+      # @return [MultiResult] Transaction result
+      #
+      # @example Update multiple fields without affecting expiration
+      #   metadata.batch_update(viewed: 1, updated: Time.now.to_i, update_expiration: false)
+      #
+      # @example Update fields with expiration refresh
+      #   user.batch_update(name: "John", email: "john@example.com")
+      #
+      def batch_update(**kwargs)
+        update_expiration = kwargs.delete(:update_expiration) { true }
+        fields = kwargs
+
+        Familia.trace :BATCH_UPDATE, redis, fields.keys, caller(1..1) if Familia.debug?
+
+        command_return_values = transaction do |conn|
+          fields.each do |field, value|
+            prepared_value = serialize_value(value)
+            conn.hset rediskey, field, prepared_value
+            # Update instance variable to keep object in sync
+            send("#{field}=", value) if respond_to?("#{field}=")
+          end
+        end
+
+        # Update expiration if requested and supported
+        self.update_expiration(ttl: nil) if update_expiration && respond_to?(:update_expiration)
+
+        # Return same MultiResult format as other methods
+        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
+        MultiResult.new(summary_boolean, command_return_values)
+      end
+
       # Apply a smattering of fields to this object like fairy dust.
       #
       # @param fields [Hash] A magical bag of named attributes to sprinkle onto
@@ -267,6 +303,26 @@ module Familia
         delete!
       end
 
+      # The Great Nilpocalypse: clear_fields!
+      #
+      # Imagine your object as a grand old mansion, every room stuffed with
+      # trinkets, secrets, and the odd rubber duck. This method? It flings open
+      # every window and lets a wild wind of nothingness sweep through, leaving
+      # each field as empty as a poet’s wallet.
+      #
+      # All your precious attributes—gone! Swept into the void! It’s a spring
+      # cleaning for the soul, a reset button for your existential dread.
+      #
+      # @return [void] Nothing left but echoes and nils.
+      #
+      # @example The Vanishing Act
+      #   wizard.clear_fields!
+      #   # => All fields are now nil, like a spell gone slightly too well.
+      #
+      def clear_fields!
+        self.class.fields.each { |field| send("#{field}=", nil) }
+      end
+
       # The Great Redis Refresh-o-matic 3000
       #
       # Imagine your object as a forgetful time traveler. This method is like
@@ -335,8 +391,10 @@ module Familia
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
           prepared = serialize_value(val)
-          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
-          hsh[field] = prepared
+          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
@@ -403,18 +461,47 @@ module Familia
       def serialize_value(val)
         prepared = Familia.distinguisher(val, strict_values: false)
 
-        if prepared.nil? && val.respond_to?(dump_method)
-          prepared = val.send(dump_method)
+        # If the distinguisher returns nil, try using the dump_method but only
+        # use JSON serialization for complex types that need it.
+        if prepared.nil? && (val.is_a?(Hash) || val.is_a?(Array))
+          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : JSON.dump(val)
         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}##{name}"
+          Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}"
         end
 
         prepared
       end
       alias to_redis serialize_value
 
+      # Converts a Redis string value back to its original Ruby type
+      #
+      # This method attempts to deserialize JSON strings back to their original
+      # Hash or Array types. Simple string values are returned as-is.
+      #
+      # @param val [String] The string value from Redis to deserialize
+      # @param symbolize_keys [Boolean] Whether to symbolize hash keys (default: true for compatibility)
+      # @return [Object] The deserialized value (Hash, Array, or original string)
+      #
+      def deserialize_value(val, symbolize: true)
+        return val if val.nil? || val == ""
+
+        # Try to parse as JSON first for complex types
+        begin
+          parsed = JSON.parse(val, symbolize_names: symbolize)
+          # Only return parsed value if it's a complex type (Hash/Array)
+          # Simple values should remain as strings
+          return parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
+        rescue JSON::ParserError
+          # Not valid JSON, return as-is
+        end
+
+        val
+      end
+      alias from_redis deserialize_value
+
     end
     # End of Serialization module
 
@@ -474,6 +561,11 @@ module Familia
       def tuple
         [successful?, results]
       end
+      alias to_a tuple
+
+      def to_h
+        { success: successful?, results: results }
+      end
 
       # Convenient method to check if the commit was successful.
       #

data/lib/familia/horreum.rb

@@ -72,7 +72,14 @@ module Familia
     end
 
     # Instance initialization
-    # This method sets up the object's state, including Redis-related data
+    # This method sets up the object's state, including Redis-related data.
+    #
+    # Usage:
+    #
+    #   Session.new("abc123", "user456")                   # positional (brittle)
+    #   Session.new(sessid: "abc123", custid: "user456")   # hash (robust)
+    #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
+    #
     def initialize(*args, **kwargs)
       Familia.ld "[Horreum] Initializing #{self.class}"
       initialize_relatives
@@ -81,7 +88,7 @@ module Familia
       # 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/
+      # instantiated.
       unless self.class.fields.include?(:key)
         # Define the 'key' field for this class
         # This approach allows flexibility in how identifiers are generated
@@ -89,25 +96,45 @@ module Familia
         self.class.field :key
       end
 
-      # If there are positional arguments, they should be the field
-      # values in the order they were defined in the implementing class.
+      # Detect if first argument is a hash (legacy support)
+      if args.size == 1 && args.first.is_a?(Hash) && kwargs.empty?
+        kwargs = args.first
+        args = []
+      end
+
+      # Initialize object with arguments using one of three strategies:
       #
-      # Handle keyword arguments
-      # Fields is a known quantity, so we iterate over it rather than kwargs
-      # to ensure that we only set fields that are defined in the class. And
-      # to avoid runaways.
-      if args.any?
-        initialize_with_positional_args(*args)
-      elsif kwargs.any?
+      # 1. **Keyword Arguments** (Recommended): Order-independent field assignment
+      #    Example: Customer.new(name: "John", email: "john@example.com")
+      #    - Robust against field reordering
+      #    - Self-documenting
+      #    - Only sets provided fields
+      #
+      # 2. **Positional Arguments** (Legacy): Field assignment by definition order
+      #    Example: Customer.new("john@example.com", "password123")
+      #    - Brittle: breaks if field order changes
+      #    - Compact syntax
+      #    - Maps to fields in class definition order
+      #
+      # 3. **No Arguments**: Object created with all fields as nil
+      #    - Minimal memory footprint in Redis
+      #    - Fields set on-demand via accessors or save()
+      #    - Avoids default value conflicts with nil-skipping serialization
+      #
+      # Note: We iterate over self.class.fields (not kwargs) to ensure only
+      # defined fields are set, preventing typos from creating undefined attributes.
+      #
+      if kwargs.any?
         initialize_with_keyword_args(**kwargs)
+      elsif args.any?
+        initialize_with_positional_args(*args)
       else
         Familia.ld "[Horreum] #{self.class} initialized with no arguments"
-        # If there are no arguments, we need to set the default values
-        # for the fields. This is done in the order they were defined.
-        # self.class.fields.each do |field|
-        #  default = self.class.defaults[field]
-        #  send(:"#{field}=", default) if default
-        # end
+        # Default values are intentionally NOT set here to:
+        # - Maintain Redis memory efficiency (only store non-nil values)
+        # - Avoid conflicts with nil-skipping serialization logic
+        # - Preserve consistent exists? behavior (empty vs default-filled objects)
+        # - Keep initialization lightweight for unused fields
       end
 
       # Implementing classes can define an init method to do any
@@ -203,6 +230,12 @@ module Familia
     end
     private :initialize_with_keyword_args
 
+    def initialize_with_keyword_args_from_redis(**fields)
+      # Deserialize Redis string values back to their original types
+      deserialized_fields = fields.transform_values { |value| deserialize_value(value) }
+      initialize_with_keyword_args(**deserialized_fields)
+    end
+
     # A thin wrapper around the private initialize method that accepts a field
     # hash and refreshes the existing object.
     #
@@ -218,7 +251,7 @@ module Familia
     # @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)
+      initialize_with_keyword_args_from_redis(**fields)
     end
 
     # Determines the unique identifier for the instance
@@ -247,6 +280,19 @@ module Familia
 
       unique_id
     end
+
+    # The principle is: **If Familia objects have `to_s`, then they should work
+    # everywhere strings are expected**, including as Redis hash field names.
+    def to_s
+      # Enable polymorphic string usage for Familia objects
+      # This allows passing Familia objects directly where strings are expected
+      # without requiring explicit .identifier calls
+      identifier.to_s
+    rescue => e
+      # Fallback for cases where identifier might fail
+      Familia.ld "[#{self.class}#to_s] Failed to get identifier: #{e.message}"
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
   end
 end
 

data/lib/familia/redistype/types/hashkey.rb

@@ -16,7 +16,7 @@ module Familia
     # +return+ [Integer] Returns 1 if the field is new and added, 0 if the
     #  field already existed and the value was updated.
     def []=(field, val)
-      ret = redis.hset rediskey, field, serialize_value(val)
+      ret = redis.hset rediskey, field.to_s, serialize_value(val)
       update_expiration
       ret
     rescue TypeError => e
@@ -31,12 +31,12 @@ module Familia
     alias store []=
 
     def [](field)
-      deserialize_value redis.hget(rediskey, field)
+      deserialize_value redis.hget(rediskey, field.to_s)
     end
     alias get []
 
     def fetch(field, default = nil)
-      ret = self[field]
+      ret = self[field.to_s]
       if ret.nil?
         raise IndexError, "No such index for: #{field}" if default.nil?
 
@@ -62,7 +62,7 @@ module Familia
     alias all hgetall
 
     def key?(field)
-      redis.hexists rediskey, field
+      redis.hexists rediskey, field.to_s
     end
     alias has_key? key?
     alias include? key?
@@ -72,12 +72,12 @@ module Familia
     # @param field [String] The field to remove
     # @return [Integer] The number of fields that were removed (0 or 1)
     def remove_field(field)
-      redis.hdel rediskey, field
+      redis.hdel rediskey, field.to_s
     end
     alias remove remove_field # deprecated
 
     def increment(field, by = 1)
-      redis.hincrby(rediskey, field, by).to_i
+      redis.hincrby(rediskey, field.to_s, by).to_i
     end
     alias incr increment
     alias incrby increment
@@ -100,7 +100,8 @@ module Familia
     alias merge! update
 
     def values_at *fields
-      elements = redis.hmget(rediskey, *fields.flatten.compact)
+      string_fields = fields.flatten.compact.map(&:to_s)
+      elements = redis.hmget(rediskey, *string_fields)
       deserialize_values(*elements)
     end
 

data/lib/familia/redistype/types/sorted_set.rb

@@ -2,7 +2,6 @@
 
 module Familia
   class SortedSet < RedisType
-
     # Returns the number of elements in the sorted set
     # @return [Integer] number of elements
     def element_count

data/lib/familia.rb

@@ -1,6 +1,7 @@
 # rubocop:disable all
 # frozen_string_literal: true
 
+require 'json'
 require 'redis'
 require 'uri/redis'
 

data/try/28_redis_horreum_serialization_try.rb

@@ -0,0 +1,159 @@
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+@identifier = 'tryouts-28@onetimesecret.com'
+@customer = Customer.new @identifier
+
+## Basic save functionality works
+@customer.name = 'John Doe'
+@customer.save
+#=> true
+
+## to_h returns field hash with all Customer fields
+@customer.to_h.class
+#=> Hash
+
+## to_h includes the fields we set (using symbol keys)
+@customer.to_h[:name]
+#=> "John Doe"
+
+## to_h includes the key field (using symbol keys)
+@customer.to_h[:key]
+#=> "tryouts-28@onetimesecret.com"
+
+## to_a returns field array in definition order
+@customer.to_a.class
+#=> Array
+
+## to_a includes values in field order (name should be at index 5)
+@customer.to_a[5]
+#=> "John Doe"
+
+## batch_update can update multiple fields atomically, to_h
+@result = @customer.batch_update(name: 'Jane Smith', email: 'jane@example.com')
+@result.to_h
+#=> {:success=>true, :results=>[0, 0]}
+
+## batch_update returns successful result, successful?
+@result.successful?
+#=> true
+
+## batch_update returns successful result, tuple
+@result.tuple
+#=> [true, [0, 0]]
+
+## batch_update returns successful result, to_a
+@result.to_a
+#=> [true, [0, 0]]
+
+## batch_update updates object fields in memory, confirm fields changed
+[@customer.name, @customer.email]
+#=> ["Jane Smith", "jane@example.com"]
+
+## batch_update persists to Redis
+@customer.refresh!
+[@customer.name, @customer.email]
+#=> ["Jane Smith", "jane@example.com"]
+
+## batch_update with update_expiration: false works
+@customer.batch_update(name: 'Bob Jones', update_expiration: false)
+@customer.refresh!
+@customer.name
+#=> "Bob Jones"
+
+## apply_fields updates object in memory only (1 of 2)
+@customer.apply_fields(name: 'Memory Only', email: 'memory@test.com')
+[@customer.name, @customer.email]
+#=> ["Memory Only", "memory@test.com"]
+
+## apply_fields doesn't persist to Redis (2 of 2)
+@customer.refresh!
+[@customer.name, @customer.email]
+#=> ["Bob Jones", "jane@example.com"]
+
+## serialize_value handles strings
+@customer.serialize_value("test string")
+#=> "test string"
+
+## serialize_value handles numbers
+@customer.serialize_value(42)
+#=> "42"
+
+## serialize_value handles hashes as JSON
+@customer.serialize_value({key: 'value', num: 123})
+#=> "{\"key\":\"value\",\"num\":123}"
+
+## serialize_value handles arrays as JSON
+@customer.serialize_value([1, 2, 'three'])
+#=> "[1,2,\"three\"]"
+
+## deserialize_value handles JSON strings back to objects
+@customer.deserialize_value('{"key":"value","num":123}')
+#=> {:key=>"value", :num=>123}
+
+## deserialize_value handles JSON arrays
+@customer.deserialize_value('[1,2,"three"]')
+#=> [1, 2, "three"]
+
+## deserialize_value handles plain strings
+@customer.deserialize_value('plain string')
+#=> "plain string"
+
+## transaction method works with block
+result = @customer.transaction do |conn|
+  conn.hset @customer.rediskey, 'temp_field', 'temp_value'
+  conn.hset @customer.rediskey, 'another_field', 'another_value'
+end
+result.size
+#=> 2
+
+## refresh! reloads from Redis
+@customer.refresh!
+@customer.hget('temp_field')
+#=> "temp_value"
+
+## Empty batch_update still works
+result = @customer.batch_update()
+result.successful?
+#=> true
+
+## destroy! removes object from Redis (1 of 2)
+@customer.destroy!
+#=> true
+
+## After destroy!, Redis key no longer exists (2 of 2)
+@customer.exists?
+#=> false
+
+## destroy! removes object from Redis, not the in-memory object (2 of 2)
+@customer.refresh!
+@customer.name
+#=> "Bob Jones"
+
+## clear_fields! removes the in-memory object fields
+@customer.clear_fields!
+@customer.name
+#=> nil
+
+## Fresh customer for testing new field creation
+@fresh_customer = Customer.new 'fresh-customer@test.com'
+@fresh_customer.class
+#=> Customer
+
+## batch_update with new fields returns [1, 1] for new field creation
+@fresh_customer.remove_field('role')
+@fresh_customer.remove_field('planid')
+@fresh_result = @fresh_customer.batch_update(role: 'admin', planid: 'premium')
+@fresh_result.to_h
+#=> {:success=>true, :results=>[1, 1]}
+
+## Fresh customer fields are set correctly
+[@fresh_customer.role, @fresh_customer.planid]
+#=> ["admin", "premium"]
+
+## Fresh customer changes persist to Redis
+@fresh_customer.refresh!
+[@fresh_customer.role, @fresh_customer.planid]
+#=> ["admin", "premium"]

data/try/29_redis_horreum_initialization_try.rb

@@ -0,0 +1,113 @@
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+## Existing positional argument initialization still works
+@customer1 = Customer.new 'tryouts-29@test.com', '', '', '', '', 'John Doe'
+[@customer1.custid, @customer1.name]
+#=> ["tryouts-29@test.com", "John Doe"]
+
+## Keyword argument initialization works (order independent)
+@customer2 = Customer.new(name: 'Jane Smith', custid: 'jane@test.com', email: 'jane@example.com')
+[@customer2.custid, @customer2.name, @customer2.email]
+#=> ["jane@test.com", "Jane Smith", "jane@example.com"]
+
+## Keyword arguments are order independent (different order, same result)
+@customer3 = Customer.new(email: 'bob@example.com', custid: 'bob@test.com', name: 'Bob Jones')
+[@customer3.custid, @customer3.name, @customer3.email]
+#=> ["bob@test.com", "Bob Jones", "bob@example.com"]
+
+## Legacy hash support (single hash argument)
+@customer4 = Customer.new({custid: 'legacy@test.com', name: 'Legacy User', role: 'admin'})
+[@customer4.custid, @customer4.name, @customer4.role]
+#=> ["legacy@test.com", "Legacy User", "admin"]
+
+## Empty initialization works
+@customer5 = Customer.new
+@customer5.class
+#=> Customer
+
+## Keyword args with save and retrieval
+@customer6 = Customer.new(custid: 'save-test@test.com', name: 'Save Test', email: 'save@example.com')
+@customer6.save
+#=> true
+
+## Saved customer can be retrieved with correct values
+@customer6.refresh!
+[@customer6.custid, @customer6.name, @customer6.email]
+#=> ["save-test@test.com", "Save Test", "save@example.com"]
+
+## Keyword initialization sets key field correctly
+@customer6.key
+#=> "save-test@test.com"
+
+## Mixed valid and nil values in keyword args (nil values stay nil)
+@customer7 = Customer.new(custid: 'mixed@test.com', name: 'Mixed Test', email: nil, role: 'user')
+[@customer7.custid, @customer7.name, @customer7.email, @customer7.role]
+#=> ["mixed@test.com", "Mixed Test", nil, "user"]
+
+## to_h works correctly with keyword-initialized objects
+@customer2.to_h[:name]
+#=> "Jane Smith"
+
+## to_a works correctly with keyword-initialized objects
+@customer2.to_a[5]  # name field should be at index 5
+#=> "Jane Smith"
+
+## Session has limited fields (only sessid defined)
+@session1 = Session.new('sess123')
+@session1.sessid
+#=> "sess123"
+
+## Session with keyword args works
+@session2 = Session.new(sessid: 'keyword-sess')
+@session2.sessid
+#=> "keyword-sess"
+
+## Session with legacy hash
+@session3 = Session.new({sessid: 'hash-sess'})
+@session3.sessid
+#=> "hash-sess"
+
+## CustomDomain with keyword initialization
+@domain1 = CustomDomain.new(display_domain: 'api.example.com', custid: 'domain-test@test.com')
+[@domain1.display_domain, @domain1.custid]
+#=> ["api.example.com", "domain-test@test.com"]
+
+## CustomDomain still works with positional args
+@domain2 = CustomDomain.new('web.example.com', 'positional@test.com')
+[@domain2.display_domain, @domain2.custid]
+#=> ["web.example.com", "positional@test.com"]
+
+## Keyword initialization can skip fields (they remain nil/empty)
+@partial = Customer.new(custid: 'partial@test.com', name: 'Partial User')
+[@partial.custid, @partial.name, @partial.email]
+#=> ["partial@test.com", "Partial User", nil]
+
+## Complex initialization with save/refresh cycle
+@complex = Customer.new(
+  custid: 'complex@test.com',
+  name: 'Complex User',
+  email: 'complex@example.com',
+  role: 'admin',
+  verified: true
+)
+@complex.save
+@complex.refresh!
+[@complex.custid, @complex.name, @complex.role, @complex.verified]
+#=> ["complex@test.com", "Complex User", "admin", "true"]
+
+## Clean up saved test objects
+[@customer6, @complex].map(&:delete!)
+#=> [true, true]
+
+## "Cleaning up" test objects that were never saved returns false.
+@customer1.save
+ret = [
+  @customer1, @customer2, @customer3, @customer4, @customer6, @customer7,
+  @session1, @session2, @session3,
+  @domain1, @domain2,
+  @partial, @complex
+].map(&:destroy!)
+#=> [true, false, false, false, false, false, false, false, false, false, false, false, false]

data/try/91_json_bug_try.rb

@@ -0,0 +1,86 @@
+# try/91_json_bug_try.rb
+
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+# Define a simple model with fields that should handle JSON data
+class JsonTest < Familia::Horreum
+  identifier :id
+  field :id
+  field :config      # This should be able to store Hash objects
+  field :tags        # This should be able to store Array objects
+  field :simple      # This should store simple strings as-is
+end
+
+# Create an instance with JSON data
+@test_obj = JsonTest.new
+@test_obj.id = "json_test_1"
+
+## Test 1: Store a Hash - should serialize to JSON automatically
+@test_obj.config = { theme: "dark", notifications: true, settings: { volume: 80 } }
+@test_obj.config.class
+#=> Hash
+
+## Test 2: Store an Array - should serialize to JSON automatically
+@test_obj.tags = ["ruby", "redis", "json", "familia"]
+@test_obj.tags.class
+#=> Array
+
+## Test 3: Store a simple string - should remain as string
+@test_obj.simple = "just a string"
+@test_obj.simple.class
+#=> String
+
+## Save the object - this should call serialize_value and use to_json
+@test_obj.save
+#=> true
+
+## Verify what's actually stored in Redis (raw)
+raw_data = @test_obj.hgetall
+p [:plop, @test_obj]
+puts "Raw Redis data:"
+raw_data
+#=> {"id"=>"json_test_1", "config"=>"{\"theme\":\"dark\",\"notifications\":true,\"settings\":{\"volume\":80}}", "tags"=>"[\"ruby\",\"redis\",\"json\",\"familia\"]", "simple"=>"just a string", "key"=>"json_test_1"}
+
+## BUG: After refresh, JSON data comes back as strings instead of parsed objects
+@test_obj.refresh!
+
+## Test 4: Hash should be deserialized back to Hash
+puts "Config after refresh:"
+puts @test_obj.config.inspect
+puts "Config class: "
+[@test_obj.config.class, @test_obj.config.inspect]
+#=> [Hash, "{:theme=>\"dark\", :notifications=>true, :settings=>{:volume=>80}}"]
+
+## Test 5: Array should be deserialized back to Array
+puts "Tags after refresh:"
+puts @test_obj.tags.inspect
+puts "Tags class: #{@test_obj.tags.class}"
+@test_obj.tags.inspect
+@test_obj.tags.class
+#=> ["ruby", "redis", "json", "familia"]
+#=> Array
+
+## Test 6: Simple string should remain a string (this works correctly)
+puts "Simple after refresh:"
+puts @test_obj.simple.inspect
+puts "Simple class: #{@test_obj.simple.class}"
+@test_obj.simple.inspect
+@test_obj.simple.class
+#=> "just a string"
+#=> String
+
+## Demonstrate the asymmetry:
+puts "\n=== ASYMMETRY DEMONSTRATION ==="
+puts "Before save: config is #{@test_obj.config.class}"
+@test_obj.config = { example: "data" }
+puts "After assignment: config is #{@test_obj.config.class}"
+@test_obj.save
+puts "After save: config is still #{@test_obj.config.class}"
+@test_obj.refresh!
+puts "After refresh: config is now #{@test_obj.config.class}!"
+
+## Clean up
+@test_obj.destroy!

data/try/92_symbolize_try.rb

@@ -0,0 +1,96 @@
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+# Test the updated deserialize_value method
+class SymbolizeTest < Familia::Horreum
+  identifier :id
+  field :id
+  field :config
+end
+
+@test_obj = SymbolizeTest.new
+@test_obj.id = "symbolize_test_1"
+
+## Test with a hash containing string keys
+@test_hash = { "name" => "John", "age" => 30, "nested" => { "theme" => "dark" } }
+@test_obj.config = @test_hash
+@test_obj.save
+
+## Original hash has string keys
+@test_hash.keys
+#=> ["name", "age", "nested"]
+
+## After save and refresh, default behavior uses symbol keys
+@test_obj.refresh!
+@test_obj.config.keys
+#=> [:name, :age, :nested]
+
+## Nested hash also has symbol keys
+@test_obj.config[:nested].keys
+#=> [:theme]
+
+## Get raw JSON from Redis
+@raw_json = @test_obj.hget('config')
+@raw_json.class
+#=> String
+
+## deserialize_value with default symbolize: true returns symbol keys
+@symbol_result = @test_obj.deserialize_value(@raw_json)
+@symbol_result.keys
+#=> [:name, :age, :nested]
+
+## Nested hash in symbol result also has symbol keys
+@symbol_result[:nested].keys
+#=> [:theme]
+
+## deserialize_value with symbolize: false returns string keys
+@string_result = @test_obj.deserialize_value(@raw_json, symbolize: false)
+@string_result.keys
+#=> ["name", "age", "nested"]
+
+## Nested hash in string result also has string keys
+@string_result["nested"].keys
+#=> ["theme"]
+
+## Values are preserved correctly in both cases
+@symbol_result[:name]
+#=> "John"
+
+@string_result["name"]
+#=> "John"
+
+## Arrays are handled correctly too
+@test_obj.config = [{ "item" => "value" }, "string", 123]
+@test_obj.save
+@array_json = @test_obj.hget('config')
+#=> "[{\"item\":\"value\"},\"string\",123]"
+
+## Array with symbolize: true converts hash keys to symbols
+@symbol_array = @test_obj.deserialize_value(@array_json)
+@symbol_array[0].keys
+#=> [:item]
+
+## Array with symbolize: false keeps hash keys as strings
+@string_array = @test_obj.deserialize_value(@array_json, symbolize: false)
+@string_array[0].keys
+#=> ["item"]
+
+## Non-hash/array values are returned as-is
+@test_obj.deserialize_value('"just a string"')
+#=> "\"just a string\""
+
+## Non-hash/array values are returned as-is
+@test_obj.deserialize_value('just a string')
+#=> "just a string"
+
+@test_obj.deserialize_value('42')
+#=> "42"
+
+## Invalid JSON returns original string
+@test_obj.deserialize_value('invalid json')
+#=> "invalid json"
+
+## Clean up
+@test_obj.destroy!

data/try/93_string_coercion_try.rb

@@ -0,0 +1,154 @@
+# try/93_string_coercion_try.rb
+
+require_relative '../lib/familia'
+require_relative './test_helpers'
+
+Familia.debug = false
+
+# Error handling: object without proper identifier setup
+class ::BadIdentifierTest < Familia::Horreum
+  # No identifier method defined - should cause issues
+end
+
+@bad_obj = ::BadIdentifierTest.new
+
+# Test polymorphic string usage for Familia objects
+@customer_id = 'customer-string-coercion-test'
+@customer = Customer.new(@customer_id)
+@customer.name = 'John Doe'
+@customer.planid = 'premium'
+@customer.save
+
+@session_id = 'session-string-coercion-test'
+@session = Session.new(@session_id)
+@session.custid = @customer_id
+@session.useragent = 'Test Browser'
+@session.save
+
+## Complex identifier test with array-based identifier
+@bone = Bone.new
+@bone.token = 'test_token'
+@bone.name = 'test_name'
+
+
+## Basic to_s functionality returns identifier
+@customer.to_s
+#=> @customer_id
+
+## String interpolation works seamlessly
+"Customer: #{@customer}"
+#=> "Customer: #{@customer_id}"
+
+## Explicit identifier call returns same value
+@customer.to_s == @customer.identifier
+#=> true
+
+## Session to_s works with generated identifier
+@session.to_s
+#=> @session_id
+
+## Method accepting string parameter works with Familia object
+def lookup_by_id(id_string)
+  id_string.to_s.upcase
+end
+
+lookup_by_id(@customer)
+#=> @customer_id.upcase
+
+## Hash key assignment using Familia object (implicit string conversion)
+@data = {}
+@data[@customer] = 'customer_data'
+@data[@customer]
+#=> 'customer_data'
+
+## Array operations work with mixed types
+@mixed_array = [@customer_id, @customer, @session]
+@mixed_array.map(&:to_s)
+#=> [@customer_id, @customer_id, @session_id]
+
+## String comparison works
+@customer.to_s == @customer_id
+#=> true
+
+## Join operations work seamlessly
+[@customer, 'separator', @session].join(':')
+#=> "#{@customer_id}:separator:#{@session_id}"
+
+## Case statement works with string matching
+def classify_id(obj)
+  case obj.to_s
+  when /customer/
+    'customer_type'
+  when /session/
+    'session_type'
+  else
+    'unknown_type'
+  end
+end
+
+classify_id(@customer)
+#=> 'customer_type'
+
+classify_id(@session)
+#=> 'session_type'
+
+## Polymorphic method accepting both strings and Familia objects
+def process_identifier(id_or_object)
+  # Can handle both string IDs and Familia objects uniformly
+  processed_id = id_or_object.to_s
+  "processed:#{processed_id}"
+end
+
+process_identifier(@customer_id)
+#=> "processed:#{@customer_id}"
+
+process_identifier(@customer)
+#=> "processed:#{@customer_id}"
+
+## Redis storage using object as string key
+@metadata = Familia::HashKey.new 'metadata'
+@metadata[@customer] = 'customer_metadata'
+@metadata[@customer.to_s] # Same key access
+#=> 'customer_metadata'
+
+## Cleanup after test
+@metadata.delete!
+#=> true
+
+@customer.delete!
+#=> true
+
+@session.delete!
+#=> true
+
+## to_s handles identifier errors gracefully
+@bad_obj.to_s.include?('BadIdentifierTest')
+#=> true
+
+## Array-based identifier works with to_s
+@bone.to_s
+#=> 'test_token:test_name'
+
+## String operations on complex identifier
+@bone.to_s.split(':')
+#=> ['test_token', 'test_name']
+
+## Cleanup a key that does not exist
+@bone.delete!
+#=> false
+
+## Cleanup a key that exists
+@bone.save
+@bone.delete!
+#=> true
+
+## Performance consideration: to_s caching behavior
+@customer2 = Customer.new('performance-test')
+@first_call = @customer2.to_s
+@second_call = @customer2.to_s
+@first_call == @second_call
+#=> true
+
+## Delete customer2
+[@customer2.exists?, @customer2.delete!]
+#=> [false, false]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 1.1.0.pre.rc1
+  version: 1.2.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-19 00:00:00.000000000 Z
+date: 2025-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -117,10 +117,15 @@ files:
 - try/25_redis_type_hash_try.rb
 - try/26_redis_bool_try.rb
 - try/27_redis_horreum_try.rb
+- try/28_redis_horreum_serialization_try.rb
+- try/29_redis_horreum_initialization_try.rb
 - try/30_familia_object_try.rb
 - try/35_feature_safedump_try.rb
 - try/40_customer_try.rb
 - try/41_customer_safedump_try.rb
+- try/91_json_bug_try.rb
+- try/92_symbolize_try.rb
+- try/93_string_coercion_try.rb
 - try/test_helpers.rb
 homepage: https://github.com/delano/familia
 licenses: