familia 2.0.0.pre19 → 2.0.0.pre22

data/lib/familia/data_type/serialization.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/serialization.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType
@@ -6,46 +8,45 @@ module Familia
       # Serializes a value for storage in the database.
       #
       # @param val [Object] The value to be serialized.
-      # @param strict_values [Boolean] Whether to enforce strict value
-      #   serialization (default: true).
-      # @return [String, nil] The serialized representation of the value, or nil
-      #   if serialization fails.
+      # @return [String] The JSON-serialized representation of the value.
       #
-      # @note When a class option is specified, it uses Familia.identifier_extractor
-      #   to extract the identifier from objects. Otherwise, it extracts identifiers
-      #   from Familia::Base instances or class names.
+      # Serialization priority:
+      # 1. Familia objects (Base instances or classes) → extract identifier
+      # 2. All other values → JSON serialize for type preservation
       #
-      # @example With a class option
-      #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation across DataType and Horreum.
       #
-      # @example Without a class option
-      #   serialize_value(123) #=> "123"
-      #   serialize_value("hello") #=> "hello"
+      # @example Familia object reference
+      #   serialize_value(customer_obj) #=> "customer_123" (identifier)
       #
-      # @raise [Familia::NotDistinguishableError] If serialization fails under strict
-      #   mode.
+      # @example Primitive values (JSON encoded)
+      #   serialize_value(42)          #=> "42"
+      #   serialize_value("hello")     #=> '"hello"'
+      #   serialize_value(true)        #=> "true"
+      #   serialize_value(nil)         #=> "null"
+      #   serialize_value([1, 2, 3])   #=> "[1,2,3]"
       #
-      def serialize_value(val, strict_values: true)
-        prepared = nil
-
+      def serialize_value(val)
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
-        if opts[:class]
-          prepared = Familia.identifier_extractor(opts[:class])
-          Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
+        # Priority 1: Handle Familia object references - extract identifier
+        # This preserves the existing behavior for storing object references
+        if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+          prepared = val.is_a?(Class) ? val.name : val.identifier
+          Familia.debug "  Familia object: #{val.class} => #{prepared}"
+          return prepared
         end
 
-        if prepared.nil?
-          # Enforce strict values when no class option is specified
-          prepared = Familia.identifier_extractor(val)
-          Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
-        end
+        # Priority 2: Everything else gets JSON serialized for type preservation
+        # This unifies behavior with Horreum fields (Issue #190)
+        prepared = Familia::JsonSerializer.dump(val)
+        Familia.debug "  JSON serialized: #{val.class} => #{prepared}"
 
         if Familia.debug?
-          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>"
+          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}> => #{prepared}<#{prepared.class}>"
         end
 
-        Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
         prepared
       end
 
@@ -77,29 +78,43 @@ module Familia
       #   replaced with nil.
       #
       def deserialize_values_with_nil(*values)
-        Familia.ld "deserialize_values: (#{@opts}) #{values}"
+        Familia.debug "deserialize_values: (#{@opts}) #{values}"
         return [] if values.empty?
-        return values.flatten unless @opts[:class]
 
-        unless @opts[:class].respond_to?(load_method)
-          raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
-        end
+        # If a class option is specified, use class-based deserialization
+        if @opts[:class]
+          unless @opts[:class].respond_to?(load_method)
+            raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+          end
 
-        values.collect! do |obj|
-          next if obj.nil?
+          values.collect! do |obj|
+            next if obj.nil?
 
-          val = @opts[:class].send load_method, obj
-          Familia.ld "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+            val = @opts[:class].send load_method, obj
+            Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
-          val
-        rescue StandardError => e
-          Familia.info val
-          Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
-          Familia.info e.backtrace
-          nil
+            val
+          rescue StandardError => e
+            Familia.info val
+            Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
+            Familia.info e.backtrace
+            nil
+          end
+
+          return values
         end
 
-        values
+        # No class option: JSON deserialize each value for type preservation (Issue #190)
+        values.flatten.collect do |obj|
+          next if obj.nil?
+
+          begin
+            Familia::JsonSerializer.parse(obj)
+          rescue Familia::SerializerError
+            # Fallback for legacy data stored without JSON encoding
+            obj
+          end
+        end
       end
 
       # Deserializes a single value from the database.
@@ -108,13 +123,15 @@ module Familia
       # @return [Object, nil] The deserialized object, the default value if
       #   val is nil, or nil if deserialization fails.
       #
-      # @note If no class option is specified, the original value is
-      #   returned unchanged.
+      # Deserialization priority:
+      # 1. Redis::Future objects → return as-is (transaction handling)
+      # 2. nil values → return default option value
+      # 3. Class option specified → use class-based deserialization
+      # 4. No class option → JSON parse for type preservation
       #
-      # NOTE: Currently only the DataType class uses this method. Horreum
-      # fields are a newer addition and don't support the full range of
-      # deserialization options that DataType supports. It uses serialize_value
-      # for serialization since everything becomes a string in Valkey.
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation. Legacy data stored without JSON
+      # encoding is returned as-is.
       #
       def deserialize_value(val)
         # Handle Redis::Future objects during transactions first
@@ -122,10 +139,20 @@ module Familia
 
         return @opts[:default] if val.nil?
 
-        return val unless @opts[:class]
+        # If a class option is specified, use the existing class-based deserialization
+        if @opts[:class]
+          ret = deserialize_values val
+          return ret&.first # return the object or nil
+        end
 
-        ret = deserialize_values val
-        ret&.first # return the object or nil
+        # No class option: JSON deserialize for type preservation (Issue #190)
+        # This unifies behavior with Horreum fields
+        begin
+          Familia::JsonSerializer.parse(val)
+        rescue Familia::SerializerError
+          # Fallback for legacy data stored without JSON encoding
+          val
+        end
       end
     end
   end

data/lib/familia/data_type/settings.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/settings.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class DataType

data/lib/familia/data_type/types/counter.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/counter.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Counter < StringKey

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/hashkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class HashKey < DataType
@@ -22,8 +24,8 @@ module Familia
       update_expiration
       ret
     rescue TypeError => e
-      Familia.le "[hset]= #{e.message}"
-      Familia.ld "[hset]= #{dbkey} #{field}=#{val}" if Familia.debug
+      Familia.error "[hset]= #{e.message}"
+      Familia.debug "[hset]= #{dbkey} #{field}=#{val}"
       echo :hset, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
       klass = val.class
       msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
@@ -74,8 +76,8 @@ module Familia
       update_expiration if ret == 1
       ret
     rescue TypeError => e
-      Familia.le "[hsetnx] #{e.message}"
-      Familia.ld "[hsetnx] #{dbkey} #{field}=#{val}" if Familia.debug
+      Familia.error "[hsetnx] #{e.message}"
+      Familia.debug "[hsetnx] #{dbkey} #{field}=#{val}"
       echo :hsetnx, Familia.pretty_stack(limit: 1) if Familia.debug # logs via echo to the db and back
       klass = val.class
       msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{dbkey}"
@@ -156,7 +158,7 @@ module Familia
       raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
       fields = hgetall
-      Familia.ld "[refresh!] #{self.class} #{dbkey} #{fields.keys}"
+      Familia.debug "[refresh!] #{self.class} #{dbkey} #{fields.keys}"
 
       # For HashKey, we update by merging the fresh data
       update(fields)

data/lib/familia/data_type/types/listkey.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/listkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class ListKey < DataType

data/lib/familia/data_type/types/lock.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/lock.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Lock < StringKey

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

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/sorted_set.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class SortedSet < DataType
@@ -127,7 +129,7 @@ module Familia
     alias add_element add
 
     def score(val)
-      ret = dbclient.zscore dbkey, serialize_value(val, strict_values: false)
+      ret = dbclient.zscore dbkey, serialize_value(val)
       ret&.to_f
     end
     alias [] score
@@ -140,13 +142,13 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = dbclient.zrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = dbclient.zrevrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrevrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
@@ -267,7 +269,7 @@ module Familia
     end
 
     def increment(val, by = 1)
-      dbclient.zincrby(dbkey, by, val).to_i
+      dbclient.zincrby(dbkey, by, serialize_value(val)).to_i
     end
     alias incr increment
     alias incrby increment
@@ -283,12 +285,7 @@ module Familia
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
       Familia.trace :REMOVE_ELEMENT, nil, "#{value}<#{value.class}>" if Familia.debug?
-      # We use `strict_values: false` here to allow for the deletion of values
-      # that are in the sorted set. If it's a horreum object, the value is
-      # 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.
-      dbclient.zrem dbkey, serialize_value(value, strict_values: false)
+      dbclient.zrem dbkey, serialize_value(value)
     end
     alias remove remove_element # deprecated
 

data/lib/familia/data_type/types/stringkey.rb

@@ -1,9 +1,33 @@
 # lib/familia/data_type/types/stringkey.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class StringKey < DataType
     def init; end
 
+    # StringKey uses raw string serialization (not JSON) because Redis string
+    # operations like INCR, DECR, APPEND operate on raw values.
+    # This overrides the base JSON serialization from DataType.
+    def serialize_value(val)
+      Familia.trace :TOREDIS, nil, "#{val}<#{val.class}>" if Familia.debug?
+
+      # Handle Familia object references - extract identifier
+      if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+        return val.is_a?(Class) ? val.name : val.identifier
+      end
+
+      # StringKey uses raw string conversion for Redis compatibility
+      val.to_s
+    end
+
+    # StringKey returns raw values (not JSON parsed)
+    def deserialize_value(val)
+      return val if val.is_a?(Redis::Future)
+      return @opts[:default] if val.nil?
+      val
+    end
+
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def char_count

data/lib/familia/data_type/types/unsorted_set.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type/types/unsorted_set.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::UnsortedSet

data/lib/familia/data_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/data_type.rb
+#
+# frozen_string_literal: true
 
 require_relative 'data_type/class_methods'
 require_relative 'data_type/settings'

data/lib/familia/encryption/encrypted_data.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/encrypted_data.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption
@@ -15,10 +17,10 @@ module Familia
           # Check for required fields
           required_fields = %i[algorithm nonce ciphertext auth_tag key_version]
           result = required_fields.all? { |field| parsed.key?(field) }
-          Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
+          Familia.debug "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
           result
         rescue Familia::SerializerError => e
-          Familia.ld "[valid?] JSON error: #{e.message}"
+          Familia.debug "[valid?] JSON error: #{e.message}"
           false
         end
       end

data/lib/familia/encryption/manager.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/manager.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/provider.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/providers/aes_gcm_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/aes_gcm_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
 #

data/lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  PROTOTYPE IMPLEMENTATION - NOT FOR PRODUCTION USE ⚠️
 #

data/lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/providers/xchacha20_poly1305_provider.rb
+#
+# frozen_string_literal: true
 
 # ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
 #

data/lib/familia/encryption/registry.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption/registry.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Encryption

data/lib/familia/encryption/request_cache.rb

@@ -1,5 +1,7 @@
 # lib/familia/encryption/request_cache.rb
 #
+# frozen_string_literal: true
+
 # Request-scoped caching for encryption keys (if needed for performance)
 # This should ONLY be enabled if performance testing shows it's necessary
 #

data/lib/familia/encryption.rb

@@ -1,4 +1,6 @@
 # lib/familia/encryption.rb
+#
+# frozen_string_literal: true
 
 require 'base64'
 require 'oj'
@@ -60,9 +62,14 @@ module Familia
     #   end
     class << self
       # Get or create a manager with specific algorithm
+      #
+      # Thread-safe lazy initialization using Concurrent::Map to ensure
+      # only a single Manager instance is created per algorithm even under
+      # concurrent encryption/decryption requests.
+      #
       def manager(algorithm: nil)
-        @managers ||= {}
-        @managers[algorithm] ||= Manager.new(algorithm: algorithm)
+        @managers ||= Concurrent::Map.new
+        @managers.fetch_or_store(algorithm) { Manager.new(algorithm: algorithm) }
       end
 
       # Quick encryption with auto-selected best provider

data/lib/familia/errors.rb

@@ -1,5 +1,7 @@
 # lib/familia/errors.rb
 #
+# frozen_string_literal: true
+
 module Familia
   # Base exception class for all Familia errors
   class Problem < RuntimeError; end

data/lib/familia/features/autoloader.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/autoloader.rb
+#
+# frozen_string_literal: true
 
 # rubocop:disable Style/ClassAndModuleChildren
 module Familia::Features

data/lib/familia/features/encrypted_fields/concealed_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/encrypted_fields/concealed_string.rb
+#
+# frozen_string_literal: true
 
 # ConcealedString
 #

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -1,3 +1,7 @@
+# lib/familia/features/encrypted_fields/encrypted_field_type.rb
+#
+# frozen_string_literal: true
+
 # lib/familia/field_types/encrypted_field_type.rb
 
 require_relative '../../field_type'

data/lib/familia/features/encrypted_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/encrypted_fields.rb
+#
+# frozen_string_literal: true
 
 require_relative 'encrypted_fields/encrypted_field_type'
 
@@ -341,8 +343,6 @@ module Familia
       # Check if this instance has any encrypted fields with values
       #
       # @return [Boolean] true if any encrypted fields have values
-      #
-      # TODO: Missing test coverage
       def encrypted_data?
         self.class.encrypted_fields.any? do |field_name|
           field_value = instance_variable_get("@#{field_name}")

data/lib/familia/features/expiration/extensions.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/expiration/extensions.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Add a default update_expiration method for all classes that include
@@ -24,7 +26,7 @@ module Familia
     # @example MyModel.new.update_expiration(expiration: 3600) # => nothing happens
     #
     def update_expiration(expiration: nil)
-      Familia.ld <<~LOG
+      Familia.debug <<~LOG
         [update_expiration] Expiration feature not enabled for #{self.class}.
         Key: #{dbkey} Arg: #{expiration} (caller: #{caller(1..1)})
       LOG

data/lib/familia/features/expiration.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/expiration.rb
+#
+# frozen_string_literal: true
 
 require_relative 'expiration/extensions'
 
@@ -252,13 +254,13 @@ module Familia
 
         # Handle cascading expiration to related data structures
         if self.class.relations?
-          Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
+          Familia.debug "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
           self.class.related_fields.each do |name, definition|
             # Skip relations that don't have their own expiration settings
             next if definition.opts[:default_expiration].nil?
 
             obj = send(name)
-            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{expiration}"
+            Familia.debug "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{expiration}"
             obj.update_expiration(expiration: expiration)
           end
         end
@@ -280,11 +282,17 @@ module Familia
         # If zero, simply skip setting an expiry for this key. If we were to set
         # 0, Valkey/Redis would drop the key immediately.
         if expiration.zero?
-          Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
+          Familia.debug "[update_expiration] No expiration for #{self.class} (#{dbkey})"
           return true
         end
 
-        Familia.ld "[update_expiration] Expires #{dbkey} in #{expiration} seconds"
+        # Structured TTL operation logging
+        Familia.debug "TTL updated",
+          operation: :expire,
+          key: dbkey,
+          ttl_seconds: expiration,
+          class: self.class.name,
+          identifier: (identifier rescue nil)
 
         # The Valkey/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,