familia 2.0.0.pre14 → 2.0.0.pre16

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
@@ -125,15 +128,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 +151,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 +170,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 +182,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
 

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

@@ -8,6 +8,8 @@ module Familia
       dbclient.zcard dbkey
     end
     alias size element_count
+    alias length element_count
+    alias count element_count
 
     def empty?
       element_count.zero?
@@ -24,14 +26,13 @@ module Familia
     # @return [Integer] Returns 1 if the element is new and added, 0 if the
     #   element already existed and the score was updated.
     #
-    # @example
-    #   sorted_set << "new_element"
+    # @example sorted_set << "new_element"
     #
     # @note This is a non-standard operation for sorted sets as it doesn't allow
     #   specifying a custom score. Use `add` or `[]=` for more control.
     #
     def <<(val)
-      add(Time.now.to_i, val)
+      add(val)
     end
 
     # NOTE: The argument order is the reverse of #add. We do this to
@@ -42,14 +43,24 @@ module Familia
     #     obj.metrics[VALUE]  # => SCORE
     #
     def []=(val, score)
-      add score, val
-    end
-
-    def add(score, val)
+      add val, score
+    end
+
+    def add(val, score = nil)
+      # TODO: Support some or all of the ZADD options.
+      # XX: Only update existing elements. Don't add new ones.
+      # NX: Only add new elements. Don't update existing ones.
+      # LT: Only update if new score < current score. Doesn't prevent adding.
+      # GT: Only update if new score > current score. Doesn't prevent adding.
+      # CH: Return total changed elements (new + updated) instead of just new.
+      # INCR: Acts like ZINCRBY. Only one score-element pair allowed.
+      # Note: GT, LT and NX options are mutually exclusive.
+      score ||= Familia.now
       ret = dbclient.zadd dbkey, score, serialize_value(val)
       update_expiration
       ret
     end
+    alias add_element add
 
     def score(val)
       ret = dbclient.zscore dbkey, serialize_value(val, strict_values: false)
@@ -58,7 +69,7 @@ module Familia
     alias [] score
 
     def member?(val)
-      Familia.trace :MEMBER, dbclient, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+      Familia.trace :MEMBER, nil, "#{val}<#{val.class}>" if Familia.debug?
       !rank(val).nil?
     end
     alias include? member?
@@ -132,7 +143,7 @@ module Familia
     end
 
     def range(sidx, eidx, opts = {})
-      echo :range, caller(1..1).first if Familia.debug
+      echo :range, Familia.pretty_stack(limit: 1) if Familia.debug
       elements = rangeraw(sidx, eidx, opts)
       deserialize_values(*elements)
     end
@@ -149,7 +160,7 @@ module Familia
     end
 
     def revrange(sidx, eidx, opts = {})
-      echo :revrange, caller(1..1).first if Familia.debug
+      echo :revrange, Familia.pretty_stack(limit: 1) if Familia.debug
       elements = revrangeraw(sidx, eidx, opts)
       deserialize_values(*elements)
     end
@@ -160,25 +171,25 @@ module Familia
 
     # e.g. obj.metrics.rangebyscore (now-12.hours), now, :limit => [0, 10]
     def rangebyscore(sscore, escore, opts = {})
-      echo :rangebyscore, caller(1..1).first if Familia.debug
+      echo :rangebyscore, Familia.pretty_stack(limit: 1) if Familia.debug
       elements = rangebyscoreraw(sscore, escore, opts)
       deserialize_values(*elements)
     end
 
     def rangebyscoreraw(sscore, escore, opts = {})
-      echo :rangebyscoreraw, caller(1..1).first if Familia.debug
+      echo :rangebyscoreraw, Familia.pretty_stack(limit: 1) if Familia.debug
       dbclient.zrangebyscore(dbkey, sscore, escore, **opts)
     end
 
     # e.g. obj.metrics.revrangebyscore (now-12.hours), now, :limit => [0, 10]
     def revrangebyscore(sscore, escore, opts = {})
-      echo :revrangebyscore, caller(1..1).first if Familia.debug
+      echo :revrangebyscore, Familia.pretty_stack(limit: 1) if Familia.debug
       elements = revrangebyscoreraw(sscore, escore, opts)
       deserialize_values(*elements)
     end
 
     def revrangebyscoreraw(sscore, escore, opts = {})
-      echo :revrangebyscoreraw, caller(1..1).first if Familia.debug
+      echo :revrangebyscoreraw, Familia.pretty_stack(limit: 1) if Familia.debug
       opts[:with_scores] = true if opts[:withscores]
       dbclient.zrevrangebyscore(dbkey, sscore, escore, opts)
     end
@@ -207,7 +218,7 @@ module Familia
     # @param value The value to remove from the sorted set
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
-      Familia.trace :REMOVE_ELEMENT, dbclient, "#{value}<#{value.class}>", caller(1..1) if Familia.debug?
+      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

data/lib/familia/data_type/types/{string.rb → stringkey.rb}

@@ -1,7 +1,7 @@
-# lib/familia/data_type/types/string.rb
+# lib/familia/data_type/types/stringkey.rb
 
 module Familia
-  class String < DataType
+  class StringKey < DataType
     def init; end
 
     # Returns the number of elements in the list
@@ -10,13 +10,14 @@ module Familia
       to_s.size
     end
     alias size char_count
+    alias length char_count
 
     def empty?
       char_count.zero?
     end
 
     def value
-      echo :value, caller(0..0) if Familia.debug
+      echo :value, Familia.pretty_stack(limit: 1) if Familia.debug
       dbclient.setnx dbkey, @opts[:default] if @opts[:default]
       deserialize_value dbclient.get(dbkey)
     end
@@ -30,7 +31,7 @@ module Familia
     end
 
     def to_i
-      value&.to_i || 0
+      value.to_i
     end
 
     def value=(val)
@@ -118,9 +119,10 @@ module Familia
     end
 
     Familia::DataType.register self, :string
+    Familia::DataType.register self, :stringkey
   end
 end
 
-# Both subclass String
+# Both subclass StringKey
 require_relative 'lock'
 require_relative 'counter'

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

@@ -1,13 +1,17 @@
 # lib/familia/data_type/types/unsorted_set.rb
 
 module Familia
-  class Set < DataType
+  # Familia::UnsortedSet
+  #
+  class UnsortedSet < DataType
     # Returns the number of elements in the unsorted set
     # @return [Integer] number of elements
     def element_count
       dbclient.scard dbkey
     end
     alias size element_count
+    alias length element_count
+    alias count element_count
 
     def empty?
       element_count.zero?
@@ -18,13 +22,14 @@ module Familia
       update_expiration
       self
     end
+    alias add_element add
 
     def <<(v)
       add v
     end
 
     def members
-      echo :members, caller(1..1).first if Familia.debug
+      echo :members, Familia.pretty_stack(limit: 1) if Familia.debug
       elements = membersraw
       deserialize_values(*elements)
     end
@@ -92,35 +97,23 @@ module Familia
       dbclient.smove dbkey, dstkey, val
     end
 
-    def random
-      deserialize_value randomraw
+    # Get one or more random members from the set
+    # @param count [Integer] Number of random members to return (default: 1)
+    # @return [Array] Array of deserialized random members
+    def sample(count = 1)
+      deserialize_values(*sampleraw(count))
     end
+    alias random sample
 
-    def randomraw
-      dbclient.srandmember(dbkey)
+    # Get one or more random members from the set without deserialization
+    # @param count [Integer] Number of random members to return (default: 1)
+    # @return [Array] Array of raw random members
+    def sampleraw(count = 1)
+      dbclient.srandmember(dbkey, count) || []
     end
-
-    ## Make the value stored at KEY identical to the given list
-    # define_method :"#{name}_sync" do |*latest|
-    #  latest = latest.flatten.compact
-    #  # Do nothing if we're given an empty Array.
-    #  # Otherwise this would clear all current values
-    #  if latest.empty?
-    #    false
-    #  else
-    #    # Convert to a list of index values if we got the actual objects
-    #    latest = latest.collect { |obj| obj.index } if klass === latest.first
-    #    current = send("#{name_plural}raw")
-    #    added = latest-current
-    #    removed = current-latest
-    #    #Familia.info "#{self.index}: adding: #{added}"
-    #    added.each { |v| self.send("add_#{name_singular}", v) }
-    #    #Familia.info "#{self.index}: removing: #{removed}"
-    #    removed.each { |v| self.send("remove_#{name_singular}", v) }
-    #    true
-    #  end
-    # end
+    alias random sampleraw
 
     Familia::DataType.register self, :set
+    Familia::DataType.register self, :unsorted_set
   end
 end

data/lib/familia/data_type.rb

@@ -9,7 +9,7 @@ module Familia
   # DataType - Base class for Database data type wrappers
   #
   # This class provides common functionality for various Database data types
-  # such as String, List, Set, SortedSet, and HashKey.
+  # such as String, List, UnsortedSet, SortedSet, and HashKey.
   #
   # @abstract Subclass and implement Database data type specific methods
   class DataType
@@ -19,30 +19,38 @@ module Familia
     using Familia::Refinements::TimeLiterals
 
     @registered_types = {}
-    @valid_options = %i[class parent default_expiration default logical_database dbkey dbclient suffix prefix]
+    @valid_options = %i[class parent default_expiration default logical_database dbkey dbclient suffix prefix].freeze
     @logical_database = nil
 
     feature :expiration
     feature :quantization
 
     class << self
-      attr_reader :registered_types, :valid_options, :has_relations
-      attr_accessor :parent
-      attr_writer :logical_database, :uri
+      attr_reader :registered_types, :valid_options, :has_related_fields
     end
 
     # DataType::ClassMethods
     #
     module ClassMethods
+      attr_accessor :parent, :suffix, :prefix, :uri
+      attr_writer :logical_database
+
       # To be called inside every class that inherits DataType
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
       def register(klass, methname)
-        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}", caller(1..1) if Familia.debug?
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}" if Familia.debug?
 
         @registered_types[methname] = klass
       end
 
+      # Get the registered type class from a given method name
+      # +methname+ is the method name used to register the class (e.g. :set, :list, etc)
+      # Returns the registered class or nil if not found
+      def registered_type(methname)
+        @registered_types[methname]
+      end
+
       def logical_database(val = nil)
         @logical_database = val unless val.nil?
         @logical_database || parent&.logical_database
@@ -54,11 +62,10 @@ module Familia
       end
 
       def inherited(obj)
-        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type", caller(1..1) if Familia.debug?
+        Familia.trace :DATATYPE, nil, "#{obj} is my kinda type" if Familia.debug?
         obj.logical_database = logical_database
         obj.default_expiration = default_expiration # method added via Features::Expiration
         obj.uri = uri
-        obj.parent = self
         super
       end
 
@@ -67,13 +74,14 @@ module Familia
       end
 
       def relations?
-        @has_relations ||= false # rubocop:disable ThreadSafety/ClassInstanceVariable
+        @has_related_fields ||= false
       end
     end
     extend ClassMethods
 
-    attr_reader :keystring, :opts
-    attr_writer :dump_method, :load_method
+    attr_reader :keystring, :opts, :uri, :logical_database
+
+    alias url uri
 
     # +keystring+: If parent is set, this will be used as the suffix
     # for dbkey. Otherwise this becomes the value of the key.
@@ -94,10 +102,6 @@ module Familia
     #
     # :default => the default value (String-only)
     #
-    # :logical_database => the logical database index to use (ignored if :dbclient is used).
-    #
-    # :dbclient => an instance of database client.
-    #
     # :dbkey => a hardcoded key to use instead of the deriving the from
     # the name and parent (e.g. a derived key: customer:custid:secret_counter).
     #
@@ -111,28 +115,23 @@ module Familia
       @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
 
       # Remove all keys from the opts that are not in the allowed list
-      @opts = opts || {}
-      @opts = DataType.valid_keys_only(@opts)
+      @opts = DataType.valid_keys_only(opts || {})
 
       # Apply the options to instance method setters of the same name
       @opts.each do |k, v|
-        # Bewarde logging :parent instance here implicitly calls #to_s which for
-        # some classes could include the identifier which could still be nil at
-        # this point. This would result in a Familia::Problem being raised. So
-        # to be on the safe-side here until we have a better understanding of
-        # the issue, we'll just log the class name for each key-value pair.
-        Familia.trace :SETTING, nil, " [setting] #{k} #{v.class}", caller(1..1) if Familia.debug?
         send(:"#{k}=", v) if respond_to? :"#{k}="
       end
 
       init if respond_to? :init
     end
 
+    # TODO: Replace with Chain of Responsibility pattern
     def dbclient
       return Fiber[:familia_transaction] if Fiber[:familia_transaction]
       return @dbclient if @dbclient
 
-      parent? ? parent.dbclient : Familia.dbclient(opts[:logical_database])
+      # Delegate to parent if present, otherwise fall back to Familia
+      parent ? parent.dbclient : Familia.dbclient(opts[:logical_database])
     end
 
     # Produces the full dbkey for this object.
@@ -189,12 +188,19 @@ module Familia
       !@opts[:class].to_s.empty? && @opts[:class].is_a?(Familia)
     end
 
+    # Provides a structured way to "gear down" to run db commands that are
+    # not implemented in our DataType classes since we intentionally don't
+    # have a method_missing method.
+    def direct_access
+      yield(dbclient, dbkey)
+    end
+
     def parent_instance?
-      parent.is_a?(Familia::Horreum)
+      parent&.is_a?(Horreum::ParentDefinition)
     end
 
     def parent_class?
-      parent.is_a?(Class) && parent <= Familia::Horreum
+      parent.is_a?(Class) && parent.ancestors.include?(Familia::Horreum)
     end
 
     def parent?
@@ -202,47 +208,69 @@ module Familia
     end
 
     def parent
-      @opts[:parent]
-    end
+      # Return cached ParentDefinition if available
+      return @parent if @parent
 
+      # Return class-level parent if no instance parent
+      return self.class.parent unless @parent_ref
 
-    def logical_database
-      @opts[:logical_database] || self.class.logical_database
+      # 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
-      # If a specific URI is set in opts, use it
-      return @opts[:uri] if @opts[:uri]
-
-      # If parent has a DB set, create a URI with that DB
-      if parent? && parent.respond_to?(:logical_database) && parent.logical_database
-        base_uri = self.class.uri || Familia.uri
-        if base_uri
-          uri_with_db = base_uri.dup
-          uri_with_db.db = parent.logical_database
-          return uri_with_db
-        end
+      # 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
 
-      # Otherwise fall back to class URI
-      self.class.uri
+    def uri=(value)
+      @uri = value
     end
 
     def dump_method
-      @dump_method || self.class.dump_method
+      self.class.dump_method
     end
 
     def load_method
-      @load_method || self.class.load_method
+      self.class.load_method
     end
 
     include Commands
     include Serialization
   end
 
-  require_relative 'data_type/types/list'
+  require_relative 'data_type/types/listkey'
   require_relative 'data_type/types/unsorted_set'
   require_relative 'data_type/types/sorted_set'
   require_relative 'data_type/types/hashkey'
-  require_relative 'data_type/types/string'
+  require_relative 'data_type/types/stringkey'
 end