familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/data_type/serialization.rb

@@ -1,127 +1,128 @@
 # lib/familia/data_type/serialization.rb
 
-class Familia::DataType
-  module Serialization
-    # Serializes a value for storage in Redis.
-    #
-    # @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.
-    #
-    # @note When a class option is specified, it uses that class's
-    #   serialization method. Otherwise, it relies on Familia.distinguisher for
-    #   serialization.
-    #
-    # @example With a class option
-    #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
-    #
-    # @example Without a class option
-    #   serialize_value(123) #=> "123"
-    #   serialize_value("hello") #=> "hello"
-    #
-    # @raise [Familia::HighRiskFactor] If serialization fails under strict
-    #   mode.
-    #
-    def serialize_value(val, strict_values: true)
-      prepared = nil
+module Familia
+  class DataType
+    module Serialization
+      # 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.
+      #
+      # @note When a class option is specified, it uses that class's
+      #   serialization method. Otherwise, it relies on Familia.distinguisher for
+      #   serialization.
+      #
+      # @example With a class option
+      #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+      #
+      # @example Without a class option
+      #   serialize_value(123) #=> "123"
+      #   serialize_value("hello") #=> "hello"
+      #
+      # @raise [Familia::NotDistinguishableError] If serialization fails under strict
+      #   mode.
+      #
+      def serialize_value(val, strict_values: true)
+        prepared = nil
 
-      Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
+        Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
-      if opts[:class]
-        prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
-        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
-      end
+        if opts[:class]
+          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, strict_values: true)
-        Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
-      end
+        if prepared.nil?
+          # Enforce strict values when no class option is specified
+          prepared = Familia.distinguisher(val, strict_values: true)
+          Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
+        end
+
+        if Familia.debug?
+          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>"
+        end
 
-      if Familia.debug?
-        Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>",
-                      caller(1..1)
+        Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
+        prepared
       end
 
-      Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
-      prepared
-    end
+      # Deserializes multiple values from Valkey/Redis, removing nil values.
+      #
+      # @param values [Array<String>] The values to deserialize.
+      # @return [Array<Object>] Deserialized objects, with nil values removed.
+      #
+      # @see #deserialize_values_with_nil
+      #
+      def deserialize_values(*values)
+        # Avoid using compact! here. Using compact! as the last expression in the
+        # method can unintentionally return nil if no changes are made, which is
+        # not desirable. Instead, use compact to ensure the method returns the
+        # expected value.
+        deserialize_values_with_nil(*values).compact
+      end
 
-    # Deserializes multiple values from Redis, removing nil values.
-    #
-    # @param values [Array<String>] The values to deserialize.
-    # @return [Array<Object>] Deserialized objects, with nil values removed.
-    #
-    # @see #deserialize_values_with_nil
-    #
-    def deserialize_values(*values)
-      # Avoid using compact! here. Using compact! as the last expression in the
-      # method can unintentionally return nil if no changes are made, which is
-      # not desirable. Instead, use compact to ensure the method returns the
-      # expected value.
-      deserialize_values_with_nil(*values).compact
-    end
+      # Deserializes multiple values from Valkey/Redis, preserving nil values.
+      #
+      # @param values [Array<String>] The values to deserialize.
+      # @return [Array<Object, nil>] Deserialized objects, including nil values.
+      #
+      # @raise [Familia::Problem] If the specified class doesn't respond to the
+      #   load method.
+      #
+      # @note This method attempts to deserialize each value using the specified
+      #   class's load method. If deserialization fails for a value, it's
+      #   replaced with nil.
+      #
+      def deserialize_values_with_nil(*values)
+        Familia.ld "deserialize_values: (#{@opts}) #{values}"
+        return [] if values.empty?
+        return values.flatten unless @opts[:class]
 
-    # Deserializes multiple values from Redis, preserving nil values.
-    #
-    # @param values [Array<String>] The values to deserialize.
-    # @return [Array<Object, nil>] Deserialized objects, including nil values.
-    #
-    # @raise [Familia::Problem] If the specified class doesn't respond to the
-    #   load method.
-    #
-    # @note This method attempts to deserialize each value using the specified
-    #   class's load method. If deserialization fails for a value, it's
-    #   replaced with nil.
-    #
-    def deserialize_values_with_nil(*values)
-      Familia.ld "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
 
-      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.ld "[#{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
+        end
 
-        val
-      rescue StandardError => e
-        Familia.info val
-        Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
-        Familia.info e.backtrace
-        nil
+        values
       end
 
-      values
-    end
+      # Deserializes a single value from the database.
+      #
+      # @param val [String, nil] The value to deserialize.
+      # @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.
+      #
+      # 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.
+      #
+      def deserialize_value(val)
+        return @opts[:default] if val.nil?
+        return val unless @opts[:class]
 
-    # Deserializes a single value from the database.
-    #
-    # @param val [String, nil] The value to deserialize.
-    # @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.
-    #
-    # 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.
-    #
-    def deserialize_value(val)
-      return @opts[:default] if val.nil?
-      return val unless @opts[:class]
-
-      ret = deserialize_values val
-      ret&.first # return the object or nil
+        ret = deserialize_values val
+        ret&.first # return the object or nil
+      end
     end
   end
 end

data/lib/familia/data_type/settings.rb

@@ -0,0 +1,96 @@
+# lib/familia/data_type/settings.rb
+
+module Familia
+  class DataType
+    # Settings - Instance-level configuration and introspection methods
+    #
+    # This module provides instance methods for accessing and managing
+    # DataType object configuration, parent relationships, and serialization.
+    #
+    # Key features:
+    # * Parent object relationship management
+    # * URI and database configuration
+    # * Serialization method delegation
+    # * Type introspection
+    #
+    module Settings
+      attr_reader :keystring, :opts, :logical_database
+      attr_reader :uri
+
+      alias url uri
+
+      def class?
+        !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
+      end
+
+      def parent_instance?
+        parent&.is_a?(Horreum::ParentDefinition)
+      end
+
+      def parent_class?
+        parent.is_a?(Class) && parent.ancestors.include?(Familia::Horreum)
+      end
+
+      def parent?
+        parent_class? || parent_instance?
+      end
+
+      def parent
+        # Return cached ParentDefinition if available
+        return @parent if @parent
+
+        # Return class-level parent if no instance parent
+        return self.class.parent unless @parent_ref
+
+        # Create ParentDefinition dynamically from stored reference.
+        # This ensures we get the current identifier value (available after initialization)
+        # rather than a stale nil value from initialization time. Cannot cache due to frozen object.
+        Horreum::ParentDefinition.from_parent(@parent_ref)
+      end
+
+      def parent=(value)
+        case value
+        when Horreum::ParentDefinition
+          @parent = value
+        when nil
+          @parent = nil
+          @parent_ref = nil
+        else
+          # Store parent instance reference for lazy ParentDefinition creation.
+          # During initialization, the parent's identifier may not be available yet,
+          # so we defer ParentDefinition creation until first access for memory efficiency.
+          # Note: @parent_ref is not cleared after use because DataType objects are frozen.
+          @parent_ref = value
+          @parent = nil  # Will be created dynamically in parent method
+        end
+      end
+
+      def uri
+        # Return explicit instance URI if set
+        return @uri if @uri
+
+        # If we have a parent with logical_database, build URI with that database
+        if parent && parent.respond_to?(:logical_database) && parent.logical_database
+          new_uri = (self.class.uri || Familia.uri).dup
+          new_uri.db = parent.logical_database
+          new_uri
+        else
+          # Fall back to class-level URI or global Familia.uri
+          self.class.uri || Familia.uri
+        end
+      end
+
+      def uri=(value)
+        @uri = value
+      end
+
+      def dump_method
+        self.class.dump_method
+      end
+
+      def load_method
+        self.class.load_method
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # lib/familia/data_type/types/counter.rb
 
 module Familia
-  class Counter < String
+  class Counter < StringKey
     def initialize(*args)
       super
       @opts[:default] ||= 0

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

@@ -8,6 +8,8 @@ module Familia
       dbclient.hlen dbkey
     end
     alias size field_count
+    alias length field_count
+    alias count field_count
 
     def empty?
       field_count.zero?
@@ -22,13 +24,14 @@ module Familia
     rescue TypeError => e
       Familia.le "[hset]= #{e.message}"
       Familia.ld "[hset]= #{dbkey} #{field}=#{val}" if Familia.debug
-      echo :hset, caller(1..1).first if Familia.debug # logs via echo to the db and back
+      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}"
       raise e.class, msg
     end
     alias put []=
     alias store []=
+    alias add []=
 
     def [](field)
       deserialize_value dbclient.hget(dbkey, field.to_s)
@@ -55,8 +58,8 @@ module Familia
     end
 
     def hgetall
-      dbclient.hgetall(dbkey).each_with_object({}) do |(k, v), ret|
-        ret[k] = deserialize_value v
+      dbclient.hgetall(dbkey).transform_values do |v|
+        deserialize_value v
       end
     end
     alias all hgetall
@@ -73,7 +76,7 @@ module Familia
     rescue TypeError => e
       Familia.le "[hsetnx] #{e.message}"
       Familia.ld "[hsetnx] #{dbkey} #{field}=#{val}" if Familia.debug
-      echo :hsetnx, caller(1..1).first if Familia.debug # logs via echo to the db and back
+      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}"
       raise e.class, msg
@@ -92,7 +95,8 @@ module Familia
     def remove_field(field)
       dbclient.hdel dbkey, field.to_s
     end
-    alias remove remove_field # deprecated
+    alias remove remove_field
+    alias remove_element remove_field
 
     def increment(field, by = 1)
       dbclient.hincrby(dbkey, field.to_s, by).to_i
@@ -125,15 +129,15 @@ module Familia
 
     # The Great Database Refresh-o-matic 3000 for HashKey!
     #
-    # This method performs a complete refresh of the hash's state from Redis.
+    # This method performs a complete refresh of the hash's state from the database.
     # It's like giving your hash a memory transfusion - out with the old state,
-    # in with the fresh data straight from Redis!
+    # in with the fresh data straight from Valkey/Redis!
     #
     # @note This operation is atomic - it either succeeds completely or fails
     #   safely. Any unsaved changes to the hash will be overwritten.
     #
     # @return [void] Returns nothing, but your hash will be sparkling clean
-    #   with all its fields synchronized with Redis.
+    #   with all its fields synchronized with the database.
     #
     # @raise [Familia::KeyNotFoundError] If the dbkey for this hash no
     #   longer exists. Time travelers beware!
@@ -148,7 +152,7 @@ module Familia
     #     puts "Oops! Our hash seems to have vanished into the Database void!"
     #   end
     def refresh!
-      Familia.trace :REFRESH, dbclient, uri, caller(1..1) if Familia.debug?
+      Familia.trace :REFRESH, nil, uri if Familia.debug?
       raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
       fields = hgetall
@@ -167,7 +171,7 @@ module Familia
     # @return [self] Returns the refreshed hash, ready for more adventures!
     #
     # @raise [Familia::KeyNotFoundError] If the dbkey does not exist.
-    #   The hash must exist in Redis-land for this to work!
+    #   The hash must exist in Valkey/Redis-land for this to work!
     #
     # @example Refresh and chain
     #   my_hash.refresh.keys  # Refresh and get all keys
@@ -179,7 +183,7 @@ module Familia
       self
     end
 
-    Familia::DataType.register self, :hash # legacy, deprecated
+    Familia::DataType.register self, :hash
     Familia::DataType.register self, :hashkey
   end
 end

data/lib/familia/data_type/types/{list.rb → listkey.rb}

@@ -1,20 +1,22 @@
-# lib/familia/data_type/types/list.rb
+# lib/familia/data_type/types/listkey.rb
 
 module Familia
-  class List < DataType
+  class ListKey < DataType
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def element_count
       dbclient.llen dbkey
     end
     alias size element_count
+    alias length element_count
+    alias count element_count
 
     def empty?
       element_count.zero?
     end
 
     def push *values
-      echo :push, caller(1..1).first if Familia.debug
+      echo :push, Familia.pretty_stack(limit: 1) if Familia.debug
       values.flatten.compact.each { |v| dbclient.rpush dbkey, serialize_value(v) }
       dbclient.ltrim dbkey, -@opts[:maxlength], -1 if @opts[:maxlength]
       update_expiration
@@ -23,8 +25,9 @@ module Familia
     alias append push
 
     def <<(val)
-      push val
+      push(val)
     end
+    alias add_element <<
     alias add <<
 
     def unshift *values
@@ -59,6 +62,10 @@ module Familia
     end
     alias slice []
 
+    def member?(value)
+      !dbclient.lpos(dbkey, serialize_value(value)).nil?
+    end
+
     # Removes elements equal to value from the list
     # @param value The value to remove
     # @param count [Integer] Number of elements to remove (0 means all)
@@ -78,7 +85,7 @@ module Familia
     end
 
     def members(count = -1)
-      echo :members, caller(1..1).first if Familia.debug
+      echo :members, Familia.pretty_stack(limit: 1) if Familia.debug
       count -= 1 if count.positive?
       range 0, count
     end
@@ -157,5 +164,6 @@ module Familia
     # end
 
     Familia::DataType.register self, :list
+    Familia::DataType.register self, :listkey
   end
 end

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

@@ -1,7 +1,7 @@
 # lib/familia/data_type/types/lock.rb
 
 module Familia
-  class Lock < String
+  class Lock < StringKey
     def initialize(*args)
       super
       @opts[:default] = nil
@@ -14,9 +14,10 @@ module Familia
     def acquire(token = SecureRandom.uuid, ttl: 10)
       success = setnx(token)
       # Handle both integer (1/0) and boolean (true/false) return values
-      return false unless success == 1 || success == true
+      return false unless [1, true].include?(success)
       return del && false if ttl&.<=(0)
       return del && false if ttl&.positive? && !expire(ttl)
+
       token
     end