familia 2.0.0.pre18 → 2.0.0.pre19

data/lib/familia/horreum/database_commands.rb

@@ -16,6 +16,10 @@ module Familia
     # just load the object again.
     #
     module DatabaseCommands
+      # Moves the object's key to a different logical database.
+      #
+      # @param logical_database [Integer] The target database number
+      # @return [Boolean] true if the key was moved successfully
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end
@@ -40,7 +44,18 @@ module Familia
         key_exists = self.class.exists?(identifier)
         return key_exists unless check_size
 
-        key_exists && !size.zero?
+        # Handle Redis::Future in transactions - skip size check
+        if key_exists.is_a?(Redis::Future)
+          return key_exists
+        end
+
+        current_size = size
+        # Handle Redis::Future from size call too
+        if current_size.is_a?(Redis::Future)
+          return current_size
+        end
+
+        key_exists && !current_size.zero?
       end
 
       # Returns the number of fields in the main object hash
@@ -55,6 +70,8 @@ module Familia
       # automatically be deleted. Returns 1 if the timeout was set, 0 if key
       # does not exist or the timeout could not be set.
       #
+      # @param default_expiration [Integer] TTL in seconds (uses class default if nil)
+      # @return [Integer] 1 if timeout was set, 0 otherwise
       def expire(default_expiration = nil)
         default_expiration ||= self.class.default_expiration
         Familia.trace :EXPIRE, nil, default_expiration if Familia.debug?
@@ -69,7 +86,7 @@ module Familia
       # @return [Integer] The TTL of the key in seconds. Returns -1 if the key does not exist
       #   or has no associated expire time.
       def current_expiration
-        Familia.trace :CURRENT_EXPIRATION, nil, uri if Familia.debug?
+        Familia.trace :CURRENT_EXPIRATION, nil, self.class.uri if Familia.debug?
         dbclient.ttl dbkey
       end
 
@@ -83,24 +100,38 @@ module Familia
       end
       alias remove remove_field # deprecated
 
+      # Returns the Redis data type of the key.
+      #
+      # @return [String] The data type (e.g., 'hash', 'string', 'list')
       def data_type
-        Familia.trace :DATATYPE, nil, uri if Familia.debug?
+        Familia.trace :DATATYPE, nil, self.class.uri if Familia.debug?
         dbclient.type dbkey(suffix)
       end
 
-      # For parity with DataType#hgetall
+      # Returns all fields and values in the hash.
+      #
+      # @return [Hash] All field-value pairs in the hash
+      # @note For parity with DataType#hgetall
       def hgetall
-        Familia.trace :HGETALL, nil, uri if Familia.debug?
+        Familia.trace :HGETALL, nil, self.class.uri if Familia.debug?
         dbclient.hgetall dbkey(suffix)
       end
       alias all hgetall
 
+      # Gets the value of a hash field.
+      #
+      # @param field [String] The field name
+      # @return [String, nil] The value of the field, or nil if field doesn't exist
       def hget(field)
         Familia.trace :HGET, nil, field if Familia.debug?
         dbclient.hget dbkey(suffix), field
       end
 
-      # @return The number of fields that were added to the hash. If the
+      # Sets the value of a hash field.
+      #
+      # @param field [String] The field name
+      # @param value [String] The value to set
+      # @return [Integer] The number of fields that were added to the hash. If the
       #  field already exists, this will return 0.
       def hset(field, value)
         Familia.trace :HSET, nil, field if Familia.debug?
@@ -120,51 +151,92 @@ module Familia
         dbclient.hsetnx dbkey, field, value
       end
 
+      # Sets multiple hash fields to multiple values.
+      #
+      # @param hsh [Hash] Hash of field-value pairs to set
+      # @return [String] 'OK' on success
       def hmset(hsh = {})
         hsh ||= to_h_for_storage
         Familia.trace :HMSET, nil, hsh if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end
 
+      # Returns all field names in the hash.
+      #
+      # @return [Array<String>] Array of field names
       def hkeys
-        Familia.trace :HKEYS, nil, 'uri' if Familia.debug?
+        Familia.trace :HKEYS, nil, self.class.uri if Familia.debug?
         dbclient.hkeys dbkey(suffix)
       end
 
+      # Returns all values in the hash.
+      #
+      # @return [Array<String>] Array of values
       def hvals
         dbclient.hvals dbkey(suffix)
       end
 
+      # Increments the integer value of a hash field by 1.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The value after incrementing
       def incr(field)
         dbclient.hincrby dbkey(suffix), field, 1
       end
       alias increment incr
 
+      # Increments the integer value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param increment [Integer] The increment value
+      # @return [Integer] The value after incrementing
       def incrby(field, increment)
         dbclient.hincrby dbkey(suffix), field, increment
       end
       alias incrementby incrby
 
+      # Increments the float value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param increment [Float] The increment value
+      # @return [Float] The value after incrementing
       def incrbyfloat(field, increment)
         dbclient.hincrbyfloat dbkey(suffix), field, increment
       end
       alias incrementbyfloat incrbyfloat
 
+      # Decrements the integer value of a hash field by the given amount.
+      #
+      # @param field [String] The field name
+      # @param decrement [Integer] The decrement value
+      # @return [Integer] The value after decrementing
       def decrby(field, decrement)
         dbclient.decrby dbkey(suffix), field, decrement
       end
       alias decrementby decrby
 
+      # Decrements the integer value of a hash field by 1.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The value after decrementing
       def decr(field)
         dbclient.hdecr field
       end
       alias decrement decr
 
+      # Returns the string length of the value associated with field in the hash.
+      #
+      # @param field [String] The field name
+      # @return [Integer] The string length of the field value, or 0 if field doesn't exist
       def hstrlen(field)
         dbclient.hstrlen dbkey(suffix), field
       end
       alias hstrlength hstrlen
 
+      # Determines if a hash field exists.
+      #
+      # @param field [String] The field name
+      # @return [Boolean] true if the field exists, false otherwise
       def key?(field)
         dbclient.hexists dbkey(suffix), field
       end
@@ -176,14 +248,61 @@ module Familia
       #
       # @return [Boolean] true if the key was deleted, false otherwise
       def delete!
-        Familia.trace :DELETE!, nil, uri if Familia.debug?
+        Familia.trace :DELETE!, nil, self.class.uri if Familia.debug?
 
         # Delete the main object key
-        ret = dbclient.del dbkey
-        ret.positive?
+        dbclient.del dbkey
       end
       alias clear delete!
 
+      # Watches the key for changes during a MULTI/EXEC transaction.
+      #
+      # Decision Matrix:
+      #
+      #   | Scenario | Use | Why |
+      #   |----------|-----|-----|
+      #   | Check if exists, then create | WATCH | Must prevent duplicate creation |
+      #   | Read value, update conditionally | WATCH | Decision depends on current state |
+      #   | Compare-and-swap operations | WATCH | Need optimistic locking |
+      #   | Version-based updates | WATCH | Must detect concurrent changes |
+      #   | Batch field updates | MULTI only | No conditional logic |
+      #   | Increment + timestamp together | MULTI only | Concurrent increments OK |
+      #   | Save object atomically | MULTI only | Just need atomicity |
+      #   | Update indexes with save | MULTI only | No state checking needed |
+      #
+      # @param suffix_override [String, nil] Optional suffix override
+      # @return [String] 'OK' on success
+      def watch(...)
+        raise ArgumentError, 'Block required' unless block_given?
+
+        # Forward all arguments including the block to the watch command
+        dbclient.watch(dbkey, ...)
+
+      rescue Redis::BaseError => e
+        raise OptimisticLockError, "Redis error: #{e.message}"
+      end
+
+      # Flushes all the previously watched keys for a transaction.
+      #
+      # If a transaction completes successfully or discard is called, there's
+      # no need to manually call unwatch.
+      #
+      # NOTE: This command operates on the connection itself; not a specific key
+      #
+      # @return [String] 'OK' always, regardless of whether the key was watched or not
+      def unwatch(...) = dbclient.unwatch(...)
+
+      # Flushes all previously queued commands in a transaction and all watched keys
+      #
+      # NOTE: This command operates on the connection itself; not a specific key
+      #
+      # @return [String] 'OK' always
+      def discard(...) = dbclient.discard(...)
+
+      # Echoes a message through the Redis connection.
+      #
+      # @param args [Array] Arguments to join and echo
+      # @return [String] The echoed message
       def echo(*args)
         dbclient.echo "[#{self.class}] #{args.join(' ')}"
       end

data/lib/familia/horreum/definition.rb

@@ -467,7 +467,8 @@ module Familia
 
             # If no value is provided to this fast attribute method, make a call
             # to the db to return the current stored value of the hash field.
-            return hget field_name if val.nil?
+            # Handle Redis::Future objects during transactions
+            return hget field_name if val.nil? || val.is_a?(Redis::Future)
 
             begin
               # Trace the operation if debugging is enabled.

data/lib/familia/horreum/management.rb

@@ -23,7 +23,7 @@ module Familia
       #   to the constructor.
       # @param kwargs [Hash] Keyword arguments to be passed to the constructor.
       # @return [Object] The newly created and persisted instance.
-      # @raise [Familia::Problem] If an instance with the same identifier already
+      # @raise [Familia::RecordExistsError] If an instance with the same identifier already
       #   exists.
       #
       # This method serves as a factory method for creating and persisting new
@@ -35,7 +35,7 @@ module Familia
       # - Keyword arguments (**kwargs) are passed as a hash to the constructor.
       #
       # After instantiation, the method checks if an object with the same
-      # identifier already exists. If it does, a Familia::Problem exception is
+      # identifier already exists. If it does, a Familia::RecordExistsError exception is
       # raised to prevent overwriting existing data.
       #
       # Finally, the method saves the new instance returns it.
@@ -52,24 +52,27 @@ module Familia
       # @see #new
       # @see #exists?
       # @see #save
-      #
-      def create(*, **)
-        fobj = new(*, **)
-        fobj.save_if_not_exists
-        fobj
+      def create!(...)
+        hobj = new(...)
+        hobj.save_if_not_exists!
+
+        # If a block is given, yield the created object
+        # This allows for additional operations on successful creation
+        yield hobj if block_given?
+
+        hobj
       end
 
-      def multiget(*ids)
-        ids = rawmultiget(*ids)
-        ids.filter_map { |json| from_json(json) }
+      def multiget(...)
+        rawmultiget(...).filter_map { |json| Familia::JsonSerializer.parse(json) }
       end
 
-      def rawmultiget(*ids)
-        ids.collect! { |objid| dbkey(objid) }
-        return [] if ids.compact.empty?
+      def rawmultiget(*hids)
+        hids.collect! { |hobjid| dbkey(hobjid) }
+        return [] if hids.compact.empty?
 
-        Familia.trace :MULTIGET, nil, "#{ids.size}: #{ids}" if Familia.debug?
-        dbclient.mget(*ids)
+        Familia.trace :MULTIGET, nil, "#{hids.size}: #{hids}" if Familia.debug?
+        dbclient.mget(*hids)
       end
 
       # Converts the class name into a string that can be used to look up
@@ -209,6 +212,9 @@ module Familia
         ret = dbclient.exists objkey
         Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug?
 
+        # Handle Redis::Future objects during transactions
+        return ret if ret.is_a?(Redis::Future)
+
         ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method.
       end