familia 2.0.0.pre21 → 2.0.0.pre22

data/lib/familia/horreum/management.rb

@@ -383,7 +383,7 @@ module Familia
       #
       def destroy!(identifier, suffix = nil)
         suffix ||= self.suffix
-        return MultiResult.new(false, []) if identifier.to_s.empty?
+        raise Familia::NoIdentifier, "#{self} requires non-empty identifier" if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
@@ -450,22 +450,153 @@ module Familia
       def all(suffix = nil)
         suffix ||= self.suffix
         # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| find_by_key(k) }
+        find_keys(suffix).filter_map { |k| find_by_key(k) }
       end
 
-      def any?(filter = '*')
-        matching_keys_count(filter).positive?
+      # Returns the number of tracked instances (fast, from instances sorted set).
+      #
+      # This method provides O(1) performance by querying the `instances` sorted set,
+      # which is automatically maintained when objects are created/destroyed through
+      # Familia. However, objects deleted outside Familia (e.g., direct Redis commands)
+      # may leave stale entries.
+      #
+      # @return [Integer] Number of instances in the instances sorted set
+      #
+      # @example
+      #   User.create(email: 'test@example.com')
+      #   User.count  #=> 1
+      #
+      # @note For authoritative count, use {#scan_count} (production-safe) or {#keys_count} (blocking)
+      # @see #scan_count Production-safe authoritative count via SCAN
+      # @see #keys_count Blocking authoritative count via KEYS
+      # @see #instances The underlying sorted set
+      #
+      def count
+        instances.count
       end
+      alias size count
+      alias length count
 
-      # Returns the number of dbkeys matching the given filter pattern
-      # @param filter [String] dbkey pattern to match (default: '*')
-      # @return [Integer] Number of matching keys
+      # Returns authoritative count using blocking KEYS command (production-dangerous).
       #
-      def matching_keys_count(filter = '*')
+      # ⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution.
+      # It scans ALL keys in the database and should NEVER be used in production.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Integer] Number of matching keys in Redis
+      #
+      # @example
+      #   User.keys_count       #=> 1  (all User objects)
+      #   User.keys_count('a*') #=> 1  (Users with IDs starting with 'a')
+      #
+      # @note For production-safe authoritative count, use {#scan_count}
+      # @see #scan_count Production-safe alternative using SCAN
+      # @see #count Fast count from instances sorted set
+      #
+      def keys_count(filter = '*')
         dbclient.keys(dbkey(filter)).compact.size
       end
-      alias size matching_keys_count
-      alias length matching_keys_count
+
+      # Returns authoritative count using non-blocking SCAN command (production-safe).
+      #
+      # This method uses cursor-based SCAN iteration to count matching keys without
+      # blocking Redis. Safe for production use as it processes keys in chunks.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Integer] Number of matching keys in Redis
+      #
+      # @example
+      #   User.scan_count       #=> 1  (all User objects)
+      #   User.scan_count('a*') #=> 1  (Users with IDs starting with 'a')
+      #
+      # @note For fast count (potentially stale), use {#count}
+      # @see #count Fast count from instances sorted set
+      # @see #keys_count Blocking alternative (production-dangerous)
+      #
+      def scan_count(filter = '*')
+        pattern = dbkey(filter)
+        count = 0
+        cursor = "0"
+
+        loop do
+          cursor, keys = dbclient.scan(cursor, match: pattern, count: 1000)
+          count += keys.size
+          break if cursor == "0"
+        end
+
+        count
+      end
+      alias count! scan_count
+
+      # Checks if any tracked instances exist (fast, from instances sorted set).
+      #
+      # This method provides O(1) performance by querying the `instances` sorted set.
+      # However, objects deleted outside Familia may leave stale entries.
+      #
+      # @return [Boolean] true if instances sorted set is non-empty
+      #
+      # @example
+      #   User.create(email: 'test@example.com')
+      #   User.any?  #=> true
+      #
+      # @note For authoritative check, use {#scan_any?} (production-safe) or {#keys_any?} (blocking)
+      # @see #scan_any? Production-safe authoritative check via SCAN
+      # @see #keys_any? Blocking authoritative check via KEYS
+      # @see #count Fast count of instances
+      #
+      def any?
+        count.positive?
+      end
+
+      # Checks if any objects exist using blocking KEYS command (production-dangerous).
+      #
+      # ⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution.
+      # It scans ALL keys in the database and should NEVER be used in production.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Boolean] true if any matching keys exist in Redis
+      #
+      # @example
+      #   User.keys_any?       #=> true  (any User objects)
+      #   User.keys_any?('a*') #=> true  (Users with IDs starting with 'a')
+      #
+      # @note For production-safe authoritative check, use {#scan_any?}
+      # @see #scan_any? Production-safe alternative using SCAN
+      # @see #any? Fast existence check from instances sorted set
+      #
+      def keys_any?(filter = '*')
+        keys_count(filter).positive?
+      end
+
+      # Checks if any objects exist using non-blocking SCAN command (production-safe).
+      #
+      # This method uses cursor-based SCAN iteration to check for matching keys without
+      # blocking Redis. Safe for production use and returns early on first match.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Boolean] true if any matching keys exist in Redis
+      #
+      # @example
+      #   User.scan_any?       #=> true  (any User objects)
+      #   User.scan_any?('a*') #=> true  (Users with IDs starting with 'a')
+      #
+      # @note For fast check (potentially stale), use {#any?}
+      # @see #any? Fast existence check from instances sorted set
+      # @see #keys_any? Blocking alternative (production-dangerous)
+      #
+      def scan_any?(filter = '*')
+        pattern = dbkey(filter)
+        cursor = "0"
+
+        loop do
+          cursor, keys = dbclient.scan(cursor, match: pattern, count: 100)
+          return true unless keys.empty?
+          break if cursor == "0"
+        end
+
+        false
+      end
+      alias any! scan_any?
 
       # Instantiates an object from a hash of field values.
       #

data/lib/familia/horreum/persistence.rb

@@ -396,6 +396,9 @@ module Familia
               obj.delete!
             end
           end
+
+          # Remove from instances collection if available
+          self.class.instances.remove(identifier) if self.class.respond_to?(:instances)
         end
 
         # Structured lifecycle logging and instrumentation

data/lib/familia/identifier_extractor.rb

@@ -29,7 +29,7 @@ module Familia
     # @return [String] The extracted identifier or class name
     # @raise [Familia::NotDistinguishableError] If value is not a Class or Familia::Base
     #
-    def identifier_extractor(value, strict_values: true)
+    def identifier_extractor(value)
       case value
       when ::Symbol, ::String, ::Integer, ::Float
         Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'simple_value' if Familia.debug?

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre21'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre22'.freeze unless defined?(Familia::VERSION)
 end

data/lib/multi_result.rb

@@ -2,25 +2,28 @@
 #
 # frozen_string_literal: true
 
-# Represents the result of a Valkey/Redis transaction operation.
+# Represents the result of a Valkey/Redis transaction or pipeline operation.
 #
-# This class encapsulates the outcome of a Database transaction,
-# providing access to both the success status and the individual
-# command results returned by the transaction.
+# This class encapsulates the outcome of a Database multi-command operation,
+# providing access to both the command results and derived success status
+# based on the presence of errors in the results.
 #
-# @attr_reader success [Boolean] Indicates whether all commands
-#   in the transaction completed successfully.
-# @attr_reader results [Array<String>] Array of return values
-#   from the Database commands executed in the transaction.
+# Success is determined by checking for Exception objects in the results array.
+# When Redis commands fail within a transaction or pipeline, they return
+# exception objects rather than raising them, allowing other commands to
+# continue executing.
+#
+# @attr_reader results [Array] Array of return values from the Database commands.
+#   Values can be strings, integers, booleans, or Exception objects for failed commands.
 #
 # @example Creating a MultiResult instance
-#   result = MultiResult.new(true, ["OK", "OK"])
+#   result = MultiResult.new(["OK", "OK", 1])
 #
 # @example Checking transaction success
 #   if result.successful?
-#     puts "Transaction completed successfully"
+#     puts "All commands completed without errors"
 #   else
-#     puts "Transaction failed"
+#     puts "#{result.errors.size} command(s) failed"
 #   end
 #
 # @example Accessing individual command results
@@ -28,24 +31,55 @@
 #     puts "Command #{index + 1} returned: #{value}"
 #   end
 #
+# @example Inspecting errors
+#   if result.errors?
+#     result.errors.each do |error|
+#       puts "Error: #{error.message}"
+#     end
+#   end
+#
 class MultiResult
-  # @return [Boolean] true if all commands in the transaction succeeded,
-  #   false otherwise
-  attr_reader :success
-
-  # @return [Array<String>] The raw return values from the Database commands
+  # @return [Array] The raw return values from the Database commands
   attr_reader :results
 
   # Creates a new MultiResult instance.
   #
-  # @param success [Boolean] Whether all commands succeeded
-  # @param results [Array<String>] The raw results from Database commands
-  def initialize(success, results)
-    @success = success
+  # @param results [Array] The raw results from Database commands.
+  #   Exception objects in the array indicate command failures.
+  def initialize(results)
     @results = results
   end
 
-  # Returns a tuple representing the result of the transaction.
+  # Returns all Exception objects from the results array.
+  #
+  # This method is memoized for performance when called multiple times
+  # on the same MultiResult instance.
+  #
+  # @return [Array<Exception>] Array of exceptions that occurred during execution
+  def errors
+    @errors ||= results.select { |ret| ret.is_a?(Exception) }
+  end
+
+  # Checks if any errors occurred during execution.
+  #
+  # @return [Boolean] true if at least one command failed, false otherwise
+  def errors?
+    !errors.empty?
+  end
+
+  # Checks if all commands completed successfully (no exceptions).
+  #
+  # This is the primary method for determining if a multi-command
+  # operation completed without errors.
+  #
+  # @return [Boolean] true if no exceptions in results, false otherwise
+  def successful?
+    errors.empty?
+  end
+  alias success? successful?
+  alias areyouhappynow? successful?
+
+  # Returns a tuple representing the result of the operation.
   #
   # @return [Array] A tuple containing the success status and the raw results.
   #   The success status is a boolean indicating if all commands succeeded.
@@ -61,21 +95,15 @@ class MultiResult
 
   # Returns the number of results in the multi-operation.
   #
-  # @return [Integer] The number of individual command results returned by the transaction.
+  # @return [Integer] The number of individual command results returned
   def size
     results.size
   end
 
+  # Returns a hash representation of the result.
+  #
+  # @return [Hash] Hash with :success and :results keys
   def to_h
     { success: successful?, results: results }
   end
-
-  # Convenient method to check if the commit was successful.
-  #
-  # @return [Boolean] true if all commands succeeded, false otherwise
-  def successful?
-    @success
-  end
-  alias success? successful?
-  alias areyouhappynow? successful?
 end