familia 1.0.0.pre.rc7 → 1.1.0.pre.rc1

data/lib/familia/horreum/serialization.rb

@@ -97,15 +97,8 @@ module Familia
       #   connection. Don't worry, it puts everything back where it found it when it's done.
       #
       def transaction
-        original_redis = self.redis
-
-        begin
-          redis.multi do |conn|
-            self.instance_variable_set(:@redis, conn)
-            yield(conn)
-          end
-        ensure
-          self.redis = original_redis
+        redis.multi do |conn|
+          yield(conn)
         end
       end
 
@@ -130,15 +123,15 @@ module Familia
 
         # Update our object's life story
         self.key ||= self.identifier
-        self.updated = Familia.now.to_i
-        self.created ||= Familia.now.to_i
+        self.created ||= Familia.now.to_i if respond_to?(:created)
+        self.updated = Familia.now.to_i if respond_to?(:updated)
 
         # Commit our tale to the Redis chronicles
         #
         # e.g. `ret`  # => MultiResult.new(true, ["OK", "OK"])
         ret = commit_fields(update_expiration: update_expiration)
 
-        Familia.ld "[save] #{self.class} #{rediskey} #{ret}"
+        Familia.ld "[save] #{self.class} #{rediskey} #{ret} (update_expiration: #{update_expiration})"
 
         # Did Redis accept our offering?
         ret.successful?
@@ -174,6 +167,10 @@ module Familia
       # It executes a transaction that includes setting field values and,
       # if applicable, updating the expiration time.
       #
+      # @param update_expiration [Boolean] Whether to update the expiration time
+      #  of the Redis key. This is true by default, but can be disabled if you
+      #  don't want to mess with the cosmic balance of your key's lifespan.
+      #
       # @return [MultiResult] A mystical object containing:
       #   - success: A boolean indicating if all Redis commands succeeded
       #   - results: An array of strings, cryptic messages from the Redis gods
@@ -213,13 +210,12 @@ module Familia
       def commit_fields update_expiration: true
         Familia.ld "[commit_fields1] #{self.class} #{rediskey} #{to_h} (update_expiration: #{update_expiration})"
         command_return_values = transaction do |conn|
-          hmset
-
-          # Only classes that have the expiration ferature enabled will
-          # actually set an expiration time on their keys. Otherwise
-          # this will be a no-op that simply logs the attempt.
-          self.update_expiration if update_expiration
+          conn.hmset rediskey(suffix), self.to_h # using the prepared connection
         end
+        # Only classes that have the expiration ferature enabled will
+        # actually set an expiration time on their keys. Otherwise
+        # this will be a no-op that simply logs the attempt.
+        self.update_expiration(ttl: nil) if update_expiration
 
         # The acceptable redis command return values are defined in the
         # Horreum class. This is to ensure that all commands return values
@@ -256,6 +252,11 @@ module Familia
       #   rocky.destroy!
       #   # => *poof* Rocky is no more. A moment of silence, please.
       #
+      # This method is part of Familia's high-level object lifecycle management. While `delete!`
+      # operates directly on Redis keys, `destroy!` operates at the object level and is used for
+      # ORM-style operations. Use `destroy!` when removing complete objects from the system, and
+      # `delete!` when working directly with Redis keys.
+      #
       # @note If debugging is enabled, this method will leave a trace of its
       #   destructive path, like breadcrumbs for future data archaeologists.
       #
@@ -276,14 +277,19 @@ module Familia
       # Gone quicker than cake at a hobbit's birthday party. Unsaved spells
       # will definitely be forgotten.
       #
-      # @return What do you get for this daring act of digital amnesia? A shiny
+      # @return [void] What do you get for this daring act of digital amnesia? A shiny
       # list of all the brain bits that got a makeover!
       #
       # Remember: In the game of Redis-Refresh, you win or you... well, you
       # always win, but sometimes you forget why you played in the first place.
       #
+      # @raise [Familia::KeyNotFoundError] If the Redis key does not exist.
+      #
+      # @example
+      #   object.refresh!
       def refresh!
         Familia.trace :REFRESH, redis, redisuri, caller(1..1) if Familia.debug?
+        raise Familia::KeyNotFoundError, rediskey unless redis.exists(rediskey)
         fields = hgetall
         Familia.ld "[refresh!] #{self.class} #{rediskey} #{fields.keys}"
         optimistic_refresh(**fields)
@@ -303,6 +309,8 @@ module Familia
       # @return [self] Your object, freshly bathed in Redis waters, ready
       #   to dance with more methods in a conga line of Ruby joy!
       #
+      # @raise [Familia::KeyNotFoundError] If the Redis key does not exist.
+      #
       def refresh
         refresh!
         self
@@ -326,7 +334,7 @@ module Familia
       def to_h
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
-          prepared = to_redis(val)
+          prepared = serialize_value(val)
           Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
           hsh[field] = prepared
           hsh
@@ -351,7 +359,7 @@ module Familia
       def to_a
         self.class.fields.map do |field|
           val = send(field)
-          prepared = to_redis(val)
+          prepared = serialize_value(val)
           Familia.ld " [to_a] field: #{field} val: #{val.class} prepared: #{prepared.class}"
           prepared
         end
@@ -392,7 +400,7 @@ module Familia
       #
       # @return [String] The transformed, Redis-ready value.
       #
-      def to_redis(val)
+      def serialize_value(val)
         prepared = Familia.distinguisher(val, strict_values: false)
 
         if prepared.nil? && val.respond_to?(dump_method)
@@ -400,11 +408,12 @@ module Familia
         end
 
         if prepared.nil?
-          Familia.ld "[#{self.class}#to_redis] nil returned for #{self.class}##{name}"
+          Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}##{name}"
         end
 
         prepared
       end
+      alias to_redis serialize_value
 
     end
     # End of Serialization module

data/lib/familia/horreum.rb

@@ -54,6 +54,10 @@ module Familia
     # but not existing instances of the class.
     #
     class << self
+      attr_accessor :parent
+      attr_writer :redis, :dump_method, :load_method
+      attr_reader :has_relations
+
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
@@ -82,7 +86,7 @@ module Familia
         # Define the 'key' field for this class
         # This approach allows flexibility in how identifiers are generated
         # while ensuring each object has a consistent way to be referenced
-        self.class.field :key # , default: -> { identifier }
+        self.class.field :key
       end
 
       # If there are positional arguments, they should be the field

data/lib/familia/redistype/commands.rb

@@ -22,11 +22,14 @@ class Familia::RedisType
       redis.type rediskey
     end
 
+    # Deletes the entire Redis key
+    # @return [Boolean] true if the key was deleted, false otherwise
     def delete!
-      redis.del rediskey
+      Familia.trace :DELETE!, redis, redisuri, caller(1..1) if Familia.debug?
+      ret = redis.del rediskey
+      ret.positive?
     end
     alias clear delete!
-    alias del delete!
 
     def exists?
       redis.exists(rediskey) && !size.zero?

data/lib/familia/redistype/serialization.rb

@@ -17,16 +17,16 @@ class Familia::RedisType
     #   serialization.
     #
     # @example With a class option
-    #   to_redis(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+    #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
     #
     # @example Without a class option
-    #   to_redis(123) #=> "123"
-    #   to_redis("hello") #=> "hello"
+    #   serialize_value(123) #=> "123"
+    #   serialize_value("hello") #=> "hello"
     #
     # @raise [Familia::HighRiskFactor] If serialization fails under strict
     #   mode.
     #
-    def to_redis(val, strict_values: true)
+    def serialize_value(val, strict_values: true)
       prepared = nil
 
       Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}>", caller(1..1) if Familia.debug?
@@ -44,24 +44,26 @@ class Familia::RedisType
 
       Familia.trace :TOREDIS, redis, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
 
-      Familia.warn "[#{self.class}\#to_redis] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
+      Familia.warn "[#{self.class}\#serialize_value] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
       prepared
     end
+    alias to_redis serialize_value
 
     # 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 #multi_from_redis_with_nil
+    # @see #deserialize_values_with_nil
     #
-    def multi_from_redis(*values)
+    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.
-      multi_from_redis_with_nil(*values).compact
+      deserialize_values_with_nil(*values).compact
     end
+    alias from_redis deserialize_values
 
     # Deserializes multiple values from Redis, preserving nil values.
     #
@@ -75,11 +77,8 @@ class Familia::RedisType
     #   class's load method. If deserialization fails for a value, it's
     #   replaced with nil.
     #
-    # NOTE: `multi` in this method name refers to multiple values from
-    # redis and not the Redis server MULTI command.
-    #
-    def multi_from_redis_with_nil(*values)
-      Familia.ld "multi_from_redis: (#{@opts}) #{values}"
+    def deserialize_values_with_nil(*values)
+      Familia.ld "deserialize_values: (#{@opts}) #{values}"
       return [] if values.empty?
       return values.flatten unless @opts[:class]
 
@@ -92,7 +91,7 @@ class Familia::RedisType
 
         val = @opts[:class].send load_method, obj
         if val.nil?
-          Familia.ld "[#{self.class}\#multi_from_redis] nil returned for #{@opts[:class]}\##{name}"
+          Familia.ld "[#{self.class}\#deserialize_values] nil returned for #{@opts[:class]}\##{name}"
         end
 
         val
@@ -105,6 +104,7 @@ class Familia::RedisType
 
       values
     end
+    alias from_redis_with_nil deserialize_values_with_nil
 
     # Deserializes a single value from Redis.
     #
@@ -120,13 +120,14 @@ class Familia::RedisType
     # deserialization options that RedisType supports. It uses to_redis
     # for serialization since everything becomes a string in Redis.
     #
-    def from_redis(val)
+    def deserialize_value(val)
       return @opts[:default] if val.nil?
       return val unless @opts[:class]
 
-      ret = multi_from_redis val
+      ret = deserialize_values val
       ret&.first # return the object or nil
     end
+    alias from_redis deserialize_value
   end
 
 end

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Familia
+  class HashKey < RedisType
+    # Returns the number of fields in the hash
+    # @return [Integer] number of fields
+    def field_count
+      redis.hlen rediskey
+    end
+    alias size field_count
+
+    def empty?
+      field_count.zero?
+    end
+
+    # +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)
+      update_expiration
+      ret
+    rescue TypeError => e
+      Familia.le "[hset]= #{e.message}"
+      Familia.ld "[hset]= #{rediskey} #{field}=#{val}" if Familia.debug
+      echo :hset, caller(1..1).first if Familia.debug # logs via echo to redis and back
+      klass = val.class
+      msg = "Cannot store #{field} => #{val.inspect} (#{klass}) in #{rediskey}"
+      raise e.class, msg
+    end
+    alias put []=
+    alias store []=
+
+    def [](field)
+      deserialize_value redis.hget(rediskey, field)
+    end
+    alias get []
+
+    def fetch(field, default = nil)
+      ret = self[field]
+      if ret.nil?
+        raise IndexError, "No such index for: #{field}" if default.nil?
+
+        default
+      else
+        ret
+      end
+    end
+
+    def keys
+      redis.hkeys rediskey
+    end
+
+    def values
+      redis.hvals(rediskey).map { |v| deserialize_value v }
+    end
+
+    def hgetall
+      redis.hgetall(rediskey).each_with_object({}) do |(k,v), ret|
+        ret[k] = deserialize_value v
+      end
+    end
+    alias all hgetall
+
+    def key?(field)
+      redis.hexists rediskey, field
+    end
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    # Removes a field from the hash
+    # @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
+    end
+    alias remove remove_field # deprecated
+
+    def increment(field, by = 1)
+      redis.hincrby(rediskey, field, by).to_i
+    end
+    alias incr increment
+    alias incrby increment
+
+    def decrement(field, by = 1)
+      increment field, -by
+    end
+    alias decr decrement
+    alias decrby decrement
+
+    def update(hsh = {})
+      raise ArgumentError, 'Argument to bulk_set must be a hash' unless hsh.is_a?(Hash)
+
+      data = hsh.inject([]) { |ret, pair| ret << [pair[0], serialize_value(pair[1])] }.flatten
+
+      ret = redis.hmset(rediskey, *data)
+      update_expiration
+      ret
+    end
+    alias merge! update
+
+    def values_at *fields
+      elements = redis.hmget(rediskey, *fields.flatten.compact)
+      deserialize_values(*elements)
+    end
+
+    # The Great Redis Refresh-o-matic 3000 for HashKey!
+    #
+    # This method performs a complete refresh of the hash's state from Redis.
+    # It's like giving your hash a memory transfusion - out with the old state,
+    # in with the fresh data straight from 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.
+    #
+    # @raise [Familia::KeyNotFoundError] If the Redis key for this hash no
+    #   longer exists. Time travelers beware!
+    #
+    # @example Basic usage
+    #   my_hash.refresh!  # ZAP! Fresh data loaded
+    #
+    # @example With error handling
+    #   begin
+    #     my_hash.refresh!
+    #   rescue Familia::KeyNotFoundError
+    #     puts "Oops! Our hash seems to have vanished into the Redis void!"
+    #   end
+    def refresh!
+      Familia.trace :REFRESH, redis, redisuri, caller(1..1) if Familia.debug?
+      raise Familia::KeyNotFoundError, rediskey unless redis.exists(rediskey)
+
+      fields = hgetall
+      Familia.ld "[refresh!] #{self.class} #{rediskey} #{fields.keys}"
+
+      # For HashKey, we update by merging the fresh data
+      update(fields)
+    end
+
+    # The friendly neighborhood refresh method!
+    #
+    # This method is like refresh! but with better manners - it returns self
+    # so you can chain it with other methods. It's perfect for when you want
+    # to refresh your hash and immediately do something with it.
+    #
+    # @return [self] Returns the refreshed hash, ready for more adventures!
+    #
+    # @raise [Familia::KeyNotFoundError] If the Redis key does not exist.
+    #   The hash must exist in Redis-land for this to work!
+    #
+    # @example Refresh and chain
+    #   my_hash.refresh.keys  # Refresh and get all keys
+    #   my_hash.refresh['field']  # Refresh and get a specific field
+    #
+    # @see #refresh! For the heavy lifting behind the scenes
+    def refresh
+      refresh!
+      self
+    end
+
+    Familia::RedisType.register self, :hash # legacy, deprecated
+    Familia::RedisType.register self, :hashkey
+  end
+end

data/lib/familia/{types → redistype/types}/list.rb

@@ -2,18 +2,21 @@
 
 module Familia
   class List < RedisType
-    def size
+
+    # Returns the number of elements in the list
+    # @return [Integer] number of elements
+    def element_count
       redis.llen rediskey
     end
-    alias length size
+    alias size element_count
 
     def empty?
-      size.zero?
+      element_count.zero?
     end
 
     def push *values
       echo :push, caller(1..1).first if Familia.debug
-      values.flatten.compact.each { |v| redis.rpush rediskey, to_redis(v) }
+      values.flatten.compact.each { |v| redis.rpush rediskey, serialize_value(v) }
       redis.ltrim rediskey, -@opts[:maxlength], -1 if @opts[:maxlength]
       update_expiration
       self
@@ -26,7 +29,7 @@ module Familia
     alias add <<
 
     def unshift *values
-      values.flatten.compact.each { |v| redis.lpush rediskey, to_redis(v) }
+      values.flatten.compact.each { |v| redis.lpush rediskey, serialize_value(v) }
       # TODO: test maxlength
       redis.ltrim rediskey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
       update_expiration
@@ -35,11 +38,11 @@ module Familia
     alias prepend unshift
 
     def pop
-      from_redis redis.rpop(rediskey)
+      deserialize_value redis.rpop(rediskey)
     end
 
     def shift
-      from_redis redis.lpop(rediskey)
+      deserialize_value redis.lpop(rediskey)
     end
 
     def [](idx, count = nil)
@@ -57,16 +60,18 @@ module Familia
     end
     alias slice []
 
-    def delete(v, count = 0)
-      redis.lrem rediskey, count, to_redis(v)
+    # 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)
+    # @return [Integer] The number of removed elements
+    def remove_element(value, count = 0)
+      redis.lrem rediskey, count, serialize_value(value)
     end
-    alias remove delete
-    alias rem delete
-    alias del delete
+    alias remove remove_element
 
     def range(sidx = 0, eidx = -1)
       elements = rangeraw sidx, eidx
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangeraw(sidx = 0, eidx = -1)
@@ -119,7 +124,7 @@ module Familia
     end
 
     def at(idx)
-      from_redis redis.lindex(rediskey, idx)
+      deserialize_value redis.lindex(rediskey, idx)
     end
 
     def first

data/lib/familia/{types → redistype/types}/sorted_set.rb

@@ -2,13 +2,16 @@
 
 module Familia
   class SortedSet < RedisType
-    def size
+
+    # Returns the number of elements in the sorted set
+    # @return [Integer] number of elements
+    def element_count
       redis.zcard rediskey
     end
-    alias length size
+    alias size element_count
 
     def empty?
-      size.zero?
+      element_count.zero?
     end
 
     # Adds a new element to the sorted set with the current timestamp as the
@@ -44,13 +47,13 @@ module Familia
     end
 
     def add(score, val)
-      ret = redis.zadd rediskey, score, to_redis(val)
+      ret = redis.zadd rediskey, score, serialize_value(val)
       update_expiration
       ret
     end
 
     def score(val)
-      ret = redis.zscore rediskey, to_redis(val, strict_values: false)
+      ret = redis.zscore rediskey, serialize_value(val, strict_values: false)
       ret&.to_f
     end
     alias [] score
@@ -63,20 +66,20 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = redis.zrank rediskey, to_redis(v, strict_values: false)
+      ret = redis.zrank rediskey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = redis.zrevrank rediskey, to_redis(v, strict_values: false)
+      ret = redis.zrevrank rediskey, serialize_value(v, strict_values: false)
       ret&.to_i
     end
 
     def members(count = -1, opts = {})
       count -= 1 if count.positive?
       elements = membersraw count, opts
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
     alias to_a members
     alias all members
@@ -89,7 +92,7 @@ module Familia
     def revmembers(count = -1, opts = {})
       count -= 1 if count.positive?
       elements = revmembersraw count, opts
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revmembersraw(count = -1, opts = {})
@@ -132,7 +135,7 @@ module Familia
     def range(sidx, eidx, opts = {})
       echo :range, caller(1..1).first if Familia.debug
       elements = rangeraw(sidx, eidx, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangeraw(sidx, eidx, opts = {})
@@ -149,7 +152,7 @@ module Familia
     def revrange(sidx, eidx, opts = {})
       echo :revrange, caller(1..1).first if Familia.debug
       elements = revrangeraw(sidx, eidx, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revrangeraw(sidx, eidx, opts = {})
@@ -160,7 +163,7 @@ module Familia
     def rangebyscore(sscore, escore, opts = {})
       echo :rangebyscore, caller(1..1).first if Familia.debug
       elements = rangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def rangebyscoreraw(sscore, escore, opts = {})
@@ -172,7 +175,7 @@ module Familia
     def revrangebyscore(sscore, escore, opts = {})
       echo :revrangebyscore, caller(1..1).first if Familia.debug
       elements = revrangebyscoreraw(sscore, escore, opts)
-      multi_from_redis(*elements)
+      deserialize_values(*elements)
     end
 
     def revrangebyscoreraw(sscore, escore, opts = {})
@@ -201,18 +204,19 @@ module Familia
     alias decr decrement
     alias decrby decrement
 
-    def delete(val)
-      Familia.trace :DELETE, redis, "#{val}<#{val.class}>", caller(1..1) if Familia.debug?
+    # Removes a member from the sorted set
+    # @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, redis, "#{value}<#{value.class}>", caller(1..1) 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.
-      redis.zrem rediskey, to_redis(val, strict_values: false)
+      redis.zrem rediskey, serialize_value(value, strict_values: false)
     end
-    alias remove delete
-    alias rem delete
-    alias del delete
+    alias remove remove_element # deprecated
 
     def at(idx)
       range(idx, idx).first