familia 2.0.0.pre17 → 2.0.0.pre19

data/lib/familia/horreum/connection.rb

@@ -6,40 +6,16 @@ module Familia
     # Provides connection handling, transactions, and URI normalization for both
     # class-level operations (e.g., Customer.dbclient) and instance-level operations
     # (e.g., customer.dbclient)
+    #
+    # Includes shared connection behavior from Familia::Connection::Behavior, providing:
+    # - URI normalization (normalize_uri)
+    # - Connection creation (create_dbclient)
+    # - Transaction method signatures
+    # - Pipeline method signatures
     module Connection
-      attr_reader :uri
-
-      # Normalizes various URI formats to a consistent URI object
-      # Considers the class/instance logical_database when uri is nil or Integer
-      def normalize_uri(uri)
-        case uri
-        when Integer
-          new_uri = Familia.uri.dup
-          new_uri.db = uri
-          new_uri
-        when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) }
-          URI.parse(uri)
-        when URI
-          uri
-        when nil
-          # Use logical_database if available, otherwise fall back to Familia.uri
-          if respond_to?(:logical_database) && logical_database
-            new_uri = Familia.uri.dup
-            new_uri.db = logical_database
-            new_uri
-          else
-            Familia.uri
-          end
-        else
-          raise ArgumentError, "Invalid URI type: #{uri.class.name}"
-        end
-      end
+      include Familia::Connection::Behavior
 
-      # Creates a new Database connection instance using the class/instance configuration
-      def create_dbclient(uri = nil)
-        parsed_uri = normalize_uri(uri)
-        Familia.create_dbclient(parsed_uri)
-      end
+      attr_reader :uri
 
       # Returns the Database connection for the class using Chain of Responsibility pattern.
       #
@@ -277,9 +253,9 @@ module Familia
         @provider_connection_handler ||= Familia::Connection::ProviderConnectionHandler.new
 
         # Determine the appropriate class context
-        # When called from instance: self is instance, self.class is the model class
-        # When called from class: self is the model class
-        klass = self.is_a?(Class) ? self : self.class
+        # When called from instance: self is instance, use the model class connection
+        # When called from class: we'll use our own connection
+        klass = is_a?(Class) ? self : self.class
 
         # Always check class first for @dbclient since instance-level connections were removed
         @cached_connection_handler ||= Familia::Connection::CachedConnectionHandler.new(klass)

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
+        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

@@ -2,6 +2,8 @@
 
 require_relative 'settings'
 
+require_relative '../field_type'
+
 module Familia
   VALID_STRATEGIES = %i[raise skip ignore warn overwrite].freeze
 
@@ -27,10 +29,6 @@ module Familia
     @related_fields = nil
     @default_expiration = nil
 
-    # Serialization settings
-    @dump_method = nil
-    @load_method = nil
-
     # Field groups
     @field_groups = nil
     @current_field_group = nil
@@ -171,30 +169,9 @@ module Familia
       #   - :skip - skip definition if method exists
       #   - :warn - warn but proceed (may overwrite)
       #   - :ignore - proceed silently (may overwrite)
-      # @param category [Symbol, nil] field category for special handling:
-      #   - nil - regular field (default)
-      #   - :encrypted - field contains encrypted data
-      #   - :transient - field is not persisted
-      #   - Others, depending on features available
-      #
-      def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
-        # Use field type system for consistency
-        require_relative '../field_type'
-
-        # Create appropriate field type based on category
-        field_type = if category == :transient
-          require_relative '../features/transient_fields/transient_field_type'
-          TransientFieldType.new(name, as: as, fast_method: false, on_conflict: on_conflict)
-        else
-          # For regular fields and other categories, create custom field type with category override
-          custom_field_type = Class.new(FieldType) do
-            define_method :category do
-              category || :field
-            end
-          end
-          custom_field_type.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
-        end
-
+      #
+      def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise)
+        field_type = FieldType.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
         register_field_type(field_type)
       end
 
@@ -256,14 +233,6 @@ module Familia
         @has_related_fields ||= false
       end
 
-      def dump_method
-        @dump_method || :to_json # Familia.dump_method
-      end
-
-      def load_method
-        @load_method || :from_json # Familia.load_method
-      end
-
       # Storage for field type instances
       def field_types
         @field_types ||= {}
@@ -498,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.
@@ -506,7 +476,7 @@ module Familia
 
               # Convert the provided value to a format suitable for Database storage.
               prepared = serialize_value(val)
-              Familia.ld "[.define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+              Familia.ld "[define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
 
               # Use the existing accessor method to set the attribute value.
               send :"#{method_name}=", val

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
@@ -125,15 +128,15 @@ module Familia
       #   User.find_by_key("user:123")  # Returns a User instance if it exists,
       #   nil otherwise
       #
-      def find_by_key(objkey)
+      def find_by_dbkey(objkey)
         raise ArgumentError, 'Empty key' if objkey.to_s.empty?
 
         # We use a lower-level method here b/c we're working with the
         # full key and not just the identifier.
         does_exist = dbclient.exists(objkey).positive?
 
-        Familia.ld "[.find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :FROM_KEY, nil, objkey if Familia.debug?
+        Familia.ld "[find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
+        Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
 
         # This is the reason for calling exists first. We want to definitively
         # and without any ambiguity know if the object exists in the database. If it
@@ -143,11 +146,16 @@ module Familia
         return unless does_exist
 
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
-        Familia.trace :FROM_KEY2, nil, "#{objkey}: #{obj.inspect}" if Familia.debug?
-
-        new(**obj)
+        Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{objkey}: #{obj.inspect}"
+
+        # Create instance and deserialize fields using existing helper method
+        # This avoids duplicating deserialization logic and keeps field-by-field processing
+        instance = allocate
+        instance.send(:initialize_relatives)
+        instance.send(:initialize_with_keyword_args_deserialize_value, **obj)
+        instance
       end
-      alias from_dbkey find_by_key # deprecated
+      alias find_by_key find_by_dbkey
 
       # Retrieves and instantiates an object from Database using its identifier.
       #
@@ -168,19 +176,19 @@ module Familia
       # @example
       #   User.find_by_id(123)  # Equivalent to User.find_by_key("user:123:object")
       #
-      def find_by_id(identifier, suffix = nil)
+      def find_by_identifier(identifier, suffix = nil)
         suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
         objkey = dbkey(identifier, suffix)
 
-        Familia.ld "[.find_by_id] #{self} from key #{objkey})"
+        Familia.ld "[find_by_id] #{self} from key #{objkey})"
         Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
-        find_by_key objkey
+        find_by_dbkey objkey
       end
+      alias find_by_id find_by_identifier
       alias find find_by_id
-      alias load find_by_id # deprecated
-      alias from_identifier find_by_id # deprecated
+      alias load find_by_id
 
       # Checks if an object with the given identifier exists in the database.
       #
@@ -204,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