familia 2.0.0.pre18 → 2.0.0.pre21

data/lib/familia/horreum/definition.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/definition.rb
+#
+# frozen_string_literal: true
 
 require_relative 'settings'
 
@@ -98,7 +100,7 @@ module Familia
             @current_field_group = nil
           end
         else
-          Familia.ld "[field_group] Created field group :#{name} but no block given" if Familia.debug?
+          Familia.debug "[field_group] Created field group :#{name} but no block given"
         end
 
         field_groups[name.to_sym]
@@ -124,7 +126,10 @@ module Familia
       #   ]
       #
       def field_groups
-        @field_groups ||= {}
+        @field_groups_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('field_groups')
+        @field_groups || @field_groups_mutex.synchronize do
+          @field_groups ||= {}
+        end
       end
 
       # Sets or retrieves the unique identifier field for the class.
@@ -215,8 +220,10 @@ module Familia
       # Returns the list of field names defined for the class in the order
       # that they were defined. i.e. `field :a; field :b; fields => [:a, :b]`.
       def fields
-        @fields ||= []
-        @fields
+        @fields_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('fields')
+        @fields || @fields_mutex.synchronize do
+          @fields ||= []
+        end
       end
 
       def class_related_fields
@@ -235,7 +242,10 @@ module Familia
 
       # Storage for field type instances
       def field_types
-        @field_types ||= {}
+        @field_types_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('field_types')
+        @field_types || @field_types_mutex.synchronize do
+          @field_types ||= {}
+        end
       end
 
       # Returns a hash mapping field names to method names for backward compatibility
@@ -467,7 +477,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.
@@ -475,7 +486,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.debug "[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

@@ -1,4 +1,6 @@
 # lib/familia/horreum/management.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Horreum
@@ -23,7 +25,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 +37,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 +54,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
@@ -101,56 +106,71 @@ module Familia
       # key.
       #
       # @param objkey [String] The full dbkey for the object.
+      # @param check_exists [Boolean] Whether to check key existence before HGETALL
+      #   (default: true). When false, skips EXISTS check for better performance
+      #   but still returns nil for non-existent keys (detected via empty hash).
       # @return [Object, nil] An instance of the class if the key exists, nil
       #   otherwise.
       # @raise [ArgumentError] If the provided key is empty.
       #
-      # This method performs a two-step process to safely retrieve and
-      # instantiate objects:
+      # This method can operate in two modes:
       #
-      # 1. It first checks if the key exists in the database. This is crucial because:
-      #    - It provides a definitive answer about the object's existence.
-      #    - It prevents ambiguity that could arise from `hgetall` returning an
-      #      empty hash for non-existent keys, which could lead to the creation
-      #      of "empty" objects.
+      # **Safe mode (check_exists: true, default):**
+      # 1. First checks if the key exists with EXISTS command
+      # 2. Returns nil immediately if key doesn't exist
+      # 3. If exists, retrieves data with HGETALL and instantiates object
+      # - Best for: Single object lookups, defensive code
+      # - Commands: 2 per object (EXISTS + HGETALL)
       #
-      # 2. If the key exists, it retrieves the object's data and instantiates
-      #    it.
+      # **Optimized mode (check_exists: false):**
+      # 1. Directly calls HGETALL without EXISTS check
+      # 2. Returns nil if HGETALL returns empty hash (key doesn't exist)
+      # 3. Otherwise instantiates object with returned data
+      # - Best for: Bulk operations, performance-critical paths, when keys likely exist
+      # - Commands: 1 per object (HGETALL only)
+      # - Reduction: 50% fewer Redis commands
       #
-      # This approach ensures that we only attempt to instantiate objects that
-      # actually exist in Valkey/Redis, improving reliability and simplifying
-      # debugging.
+      # @example Safe mode (default)
+      #   User.find_by_key("user:123")  # 2 commands: EXISTS + HGETALL
       #
-      # @example
-      #   User.find_by_key("user:123")  # Returns a User instance if it exists,
-      #   nil otherwise
+      # @example Optimized mode (skip existence check)
+      #   User.find_by_key("user:123", check_exists: false)  # 1 command: HGETALL
+      #
+      # @note When check_exists: false, HGETALL on non-existent keys returns {}
+      #   which we detect and return nil (not an empty object instance).
       #
-      def find_by_dbkey(objkey)
+      def find_by_dbkey(objkey, check_exists: true)
         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 :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
-        # doesn't, we return nil. If it does, we proceed to load the object.
-        # Otherwise, hgetall will return an empty hash, which will be passed to
-        # the constructor, which will then be annoying to debug.
-        return unless does_exist
+        if check_exists
+          # Safe mode: Check existence first (original behavior)
+          # 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.debug "[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
+          # doesn't, we return nil. If it does, we proceed to load the object.
+          # Otherwise, hgetall will return an empty hash, which will be passed to
+          # the constructor, which will then be annoying to debug.
+          return unless does_exist
+        else
+          # Optimized mode: Skip existence check
+          Familia.debug "[find_by_key] #{self} from key #{objkey} (check_exists: false)"
+          Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
+        end
 
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
         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
+        # If we skipped existence check and got empty hash, key doesn't exist
+        return nil if !check_exists && obj.empty?
+
+        # Create instance and deserialize fields using shared helper method
+        instantiate_from_hash(obj)
       end
       alias find_by_key find_by_dbkey
 
@@ -158,8 +178,10 @@ module Familia
       #
       # @param identifier [String, Integer] The unique identifier for the
       #   object.
-      # @param suffix [Symbol] The suffix to use in the dbkey (default:
-      #   :object).
+      # @param suffix [Symbol, nil] The suffix to use in the dbkey (default:
+      #   class suffix). Keyword parameter for consistency with check_exists.
+      # @param check_exists [Boolean] Whether to check key existence before HGETALL
+      #   (default: true). See find_by_dbkey for details.
       # @return [Object, nil] An instance of the class if found, nil otherwise.
       #
       # This method constructs the full dbkey using the provided identifier
@@ -170,23 +192,153 @@ module Familia
       # making it easier to retrieve objects when you only have their
       # identifier.
       #
-      # @example
-      #   User.find_by_id(123)  # Equivalent to User.find_by_key("user:123:object")
+      # @example Safe mode (default)
+      #   User.find_by_id(123)  # 2 commands: EXISTS + HGETALL
+      #
+      # @example Optimized mode
+      #   User.find_by_id(123, check_exists: false)  # 1 command: HGETALL
       #
-      def find_by_identifier(identifier, suffix = nil)
+      # @example Custom suffix
+      #   Session.find_by_id('abc', suffix: :session)
+      #
+      def find_by_identifier(identifier, suffix: nil, check_exists: true)
         suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
         objkey = dbkey(identifier, suffix)
 
-        Familia.ld "[find_by_id] #{self} from key #{objkey})"
+        Familia.debug "[find_by_id] #{self} from key #{objkey})"
         Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
-        find_by_dbkey objkey
+        find_by_dbkey objkey, check_exists: check_exists
       end
       alias find_by_id find_by_identifier
       alias find find_by_id
       alias load find_by_id
 
+      # Loads multiple objects by their identifiers using pipelined HGETALL commands.
+      #
+      # This method provides significant performance improvements for bulk loading by:
+      # 1. Batching all HGETALL commands into a single Redis pipeline
+      # 2. Eliminating network round-trip overhead
+      # 3. Skipping individual EXISTS checks (like check_exists: false)
+      #
+      # @param identifiers [Array<String, Integer>] Array of identifiers to load
+      # @param suffix [Symbol, nil] The suffix to use in dbkeys (default: class suffix)
+      # @return [Array<Object>] Array of instantiated objects (nils for non-existent)
+      #
+      # Performance characteristics:
+      # - Standard approach: N objects × 2 commands (EXISTS + HGETALL) = 2N round trips
+      # - check_exists: false: N objects × 1 command (HGETALL) = N round trips
+      # - load_multi: 1 pipeline with N commands = 1 round trip
+      # - Improvement: Up to 2N× faster for bulk operations
+      #
+      # @example Load multiple users efficiently
+      #   users = User.load_multi([123, 456, 789])
+      #   # 1 pipeline with 3 HGETALL commands instead of 6 individual commands
+      #
+      # @example Filter out nils
+      #   existing_users = User.load_multi(ids).compact
+      #
+      # @note Returns nil for non-existent keys (maintains same contract as find_by_id)
+      # @note Objects are returned in the same order as input identifiers
+      # @note Empty/nil identifiers are skipped and return nil in result array
+      #
+      def load_multi(identifiers, suffix = nil)
+        suffix ||= self.suffix
+        return [] if identifiers.empty?
+
+        # Build list of valid keys and track their original positions
+        valid_keys = []
+        valid_positions = []
+
+        identifiers.each_with_index do |identifier, idx|
+          next if identifier.to_s.empty?
+
+          valid_keys << dbkey(identifier, suffix)
+          valid_positions << idx
+        end
+
+        Familia.trace :LOAD_MULTI, nil, "Loading #{identifiers.size} objects" if Familia.debug?
+
+        # Pipeline all HGETALL commands
+        multi_result = pipelined do |pipeline|
+          valid_keys.each do |objkey|
+            pipeline.hgetall(objkey)
+          end
+        end
+
+        # Extract results array from MultiResult
+        results = multi_result.results
+
+        # Map results back to original positions
+        objects = Array.new(identifiers.size)
+        valid_positions.each_with_index do |pos, result_idx|
+          obj_hash = results[result_idx]
+
+          # Skip empty hashes (non-existent keys)
+          next if obj_hash.nil? || obj_hash.empty?
+
+          # Instantiate object using shared helper method
+          objects[pos] = instantiate_from_hash(obj_hash)
+        end
+
+        objects
+      end
+      alias load_batch load_multi
+
+      # Loads multiple objects by their full dbkeys using pipelined HGETALL commands.
+      #
+      # This is a lower-level variant of load_multi that works directly with dbkeys
+      # instead of identifiers. Useful when you already have the full keys.
+      #
+      # @param objkeys [Array<String>] Array of full dbkeys to load
+      # @return [Array<Object>] Array of instantiated objects (nils for non-existent)
+      #
+      # @example Load objects by full keys
+      #   keys = ["user:123:object", "user:456:object"]
+      #   users = User.load_multi_by_keys(keys)
+      #
+      # @note Returns nil for empty/nil keys, maintaining position alignment with input array
+      #
+      # @see load_multi For loading by identifiers
+      #
+      def load_multi_by_keys(objkeys)
+        return [] if objkeys.empty?
+
+        Familia.trace :LOAD_MULTI_BY_KEYS, nil, "Loading #{objkeys.size} objects" if Familia.debug?
+
+        # Track which positions have valid keys to maintain result array alignment
+        valid_positions = []
+        objkeys.each_with_index do |objkey, idx|
+          valid_positions << idx unless objkey.to_s.empty?
+        end
+
+        # Pipeline all HGETALL commands for valid keys
+        multi_result = pipelined do |pipeline|
+          objkeys.each do |objkey|
+            next if objkey.to_s.empty?
+            pipeline.hgetall(objkey)
+          end
+        end
+
+        # Extract results array from MultiResult
+        results = multi_result.results
+
+        # Map results back to original positions
+        objects = Array.new(objkeys.size)
+        valid_positions.each_with_index do |pos, result_idx|
+          obj_hash = results[result_idx]
+
+          # Skip empty hashes (non-existent keys)
+          next if obj_hash.nil? || obj_hash.empty?
+
+          # Instantiate object using shared helper method
+          objects[pos] = instantiate_from_hash(obj_hash)
+        end
+
+        objects
+      end
+
       # Checks if an object with the given identifier exists in the database.
       #
       # @param identifier [String, Integer] The unique identifier for the object.
@@ -209,6 +361,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
 
@@ -311,6 +466,27 @@ module Familia
       end
       alias size matching_keys_count
       alias length matching_keys_count
+
+      # Instantiates an object from a hash of field values.
+      #
+      # This is an internal helper method used by find_by_dbkey, load_multi, and
+      # load_multi_by_keys to eliminate code duplication. Not intended for direct use.
+      #
+      # @param obj_hash [Hash] Hash of field names to serialized values from Redis
+      # @return [Object] Instantiated object with deserialized fields
+      #
+      # @note This method:
+      #   1. Allocates a new instance without calling initialize
+      #   2. Initializes related DataType fields
+      #   3. Deserializes and assigns field values from the hash
+      #
+      # @api private
+      def instantiate_from_hash(obj_hash)
+        instance = allocate
+        instance.send(:initialize_relatives)
+        instance.send(:initialize_with_keyword_args_deserialize_value, **obj_hash)
+        instance
+      end
     end
   end
 end