familia 1.0.0.pre.rc7 → 1.2.0

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
 
@@ -128,22 +121,58 @@ 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
-        self.updated = Familia.now.to_i
-        self.created ||= Familia.now.to_i
+        # 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)
 
         # 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?
       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
@@ -174,6 +203,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 +246,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 +288,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.
       #
@@ -266,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
@@ -276,14 +333,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 +365,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,9 +390,11 @@ module Familia
       def to_h
         self.class.fields.inject({}) do |hsh, field|
           val = send(field)
-          prepared = to_redis(val)
-          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared.class}"
-          hsh[field] = prepared
+          prepared = serialize_value(val)
+          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
@@ -351,7 +417,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,19 +458,49 @@ 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)
-          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}#to_redis] 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
@@ -465,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

@@ -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?
@@ -68,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
@@ -77,33 +88,53 @@ 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
         # 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
-      # 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
@@ -199,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.
     #
@@ -214,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
@@ -243,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/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,167 @@
+# 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.to_s, 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.to_s)
+    end
+    alias get []
+
+    def fetch(field, default = nil)
+      ret = self[field.to_s]
+      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.to_s
+    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.to_s
+    end
+    alias remove remove_field # deprecated
+
+    def increment(field, by = 1)
+      redis.hincrby(rediskey, field.to_s, 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
+      string_fields = fields.flatten.compact.map(&:to_s)
+      elements = redis.hmget(rediskey, *string_fields)
+      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