mongory 0.3.0 → 0.6.0

data/lib/mongory/matchers/abstract_matcher.rb

@@ -7,23 +7,49 @@ module Mongory
     # It defines a common interface (`#match?`) and provides shared behavior
     # such as condition storage, optional conversion handling, and debugging output.
     #
-    # Subclasses are expected to implement `#match(record)` to define their matching logic.
+    # Each matcher is responsible for evaluating a specific type of condition against
+    # a record value. The base class provides infrastructure for:
+    # - Condition validation
+    # - Value conversion
+    # - Debug output
+    # - Proc caching
     #
-    # This class also supports caching of lazily-built matchers via `define_matcher`.
+    # @abstract Subclasses must implement {#match} to define their matching logic
     #
-    # @abstract
+    # @example Basic matcher implementation
+    #   class MyMatcher < AbstractMatcher
+    #     def match(record)
+    #       record == @condition
+    #     end
+    #   end
+    #
+    # @example Using a matcher
+    #   matcher = MyMatcher.build(42)
+    #   matcher.match?(42)  #=> true
+    #   matcher.match?(43)  #=> false
+    #
+    # @see Mongory::Matchers for the full list of available matchers
     class AbstractMatcher
       include Utils
 
       singleton_class.alias_method :build, :new
+
       # Sentinel value used to represent missing keys when traversing nested hashes.
+      # This is used instead of nil to distinguish between missing keys and nil values.
+      #
+      # @api private
       KEY_NOT_FOUND = SingletonBuilder.new('KEY_NOT_FOUND')
 
       # Defines a lazily-evaluated matcher accessor with instance-level caching.
+      # This is used to create cached accessors for submatcher instances.
       #
       # @param name [Symbol] the name of the matcher (e.g., :collection)
       # @yield the block that constructs the matcher instance
       # @return [void]
+      # @example
+      #   define_matcher(:array_matcher) do
+      #     ArrayMatcher.build(@condition)
+      #   end
       def self.define_matcher(name, &block)
         define_instance_cache_method(:"#{name}_matcher", &block)
       end
@@ -31,7 +57,13 @@ module Mongory
       # @return [Object] the raw condition this matcher was initialized with
       attr_reader :condition
 
-      # @return [String] a unique key representing this matcher instance, used for deduplication
+      # @return [Context] the query context containing configuration and current record
+      attr_reader :context
+
+      # Returns a unique key representing this matcher instance.
+      # Used for deduplication in multi-matchers.
+      #
+      # @return [String] a unique key for this matcher instance
       # @see AbstractMultiMatcher#matchers
       def uniq_key
         "#{self.class}:condition:#{@condition.class}:#{@condition}"
@@ -40,56 +72,82 @@ module Mongory
       # Initializes the matcher with a raw condition.
       #
       # @param condition [Object] the condition to match against
-      def initialize(condition)
+      # @param context [Context] the query context containing configuration
+      def initialize(condition, context: Context.new)
         @condition = condition
+        @context = context
 
         check_validity!
       end
 
-      # Performs the actual match logic.
-      # Subclasses must override this method.
-      #
-      # @param record [Object] the input record to test
-      # @return [Boolean] whether the record matches the condition
-      def match(record); end
-
       # Matches the given record against the condition.
+      # This method handles error cases and uses the cached proc for performance.
       #
       # @param record [Object] the input record
-      # @return [Boolean]
+      # @return [Boolean] whether the record matches the condition
       def match?(record)
-        match(record)
+        to_proc.call(record)
       rescue StandardError
         false
       end
 
-      # Provides an alias to `#match?` for internal delegation.
-      alias_method :regular_match, :match?
+      # Converts the matcher into a Proc that can be used for matching.
+      # The Proc is cached for better performance.
+      #
+      # @return [Proc] a Proc that can be used to match records
+      def cached_proc
+        @cached_proc ||= raw_proc
+      end
 
-      # Evaluates the match with debugging output.
-      # Increments indent level and prints visual result with colors.
+      alias_method :to_proc, :cached_proc
+
+      # Creates a debug-enabled version of the matcher proc.
+      # This version includes tracing and error handling.
       #
-      # @param record [Object] the input record to test
-      # @return [Boolean] whether the match succeeded
-      def debug_match(record)
-        result = nil
-
-        Debugger.instance.with_indent do
-          result = begin
-            match(record)
-          rescue StandardError => e
-            e
+      # @return [Proc] a debug-enabled version of the matcher proc
+      def debug_proc
+        return @debug_proc if defined?(@debug_proc)
+
+        raw_proc = raw_proc()
+        @debug_proc = Proc.new do |record|
+          result = nil
+
+          Debugger.instance.with_indent do
+            result = begin
+              raw_proc.call(record)
+            rescue StandardError => e
+              e
+            end
+
+            debug_display(record, result)
           end
 
-          debug_display(record, result)
+          result.is_a?(Exception) ? false : result
         end
+      end
 
-        result.is_a?(Exception) ? false : result
+      # Creates a raw Proc from the match method.
+      # This is used internally by to_proc and can be overridden by subclasses
+      # to provide custom matching behavior.
+      #
+      # @return [Proc] the raw Proc implementation of the match method
+      def raw_proc
+        method(:match).to_proc
       end
 
+      # Performs the actual match logic.
+      # Subclasses must override this method.
+      #
+      # @abstract
+      # @param record [Object] the input record to test
+      # @return [Boolean] whether the record matches the condition
+      def match(record); end
+
       # Validates the condition (no-op by default).
       # Override in subclasses to raise error if invalid.
       #
+      # @abstract
+      # @raise [TypeError] if the condition is invalid
       # @return [void]
       def check_validity!; end
 
@@ -108,7 +166,7 @@ module Mongory
       # Returns a single-line string representing this matcher in the tree output.
       # Format: `<MatcherType>: <condition.inspect>`
       #
-      # @return [String]
+      # @return [String] a formatted title for tree display
       def tree_title
         matcher_name = self.class.name.split('::').last.sub('Matcher', '')
         "#{matcher_name}: #{@condition.inspect}"
@@ -131,7 +189,7 @@ module Mongory
       # Uses ANSI escape codes to highlight matched vs. mismatched records.
       #
       # @param record [Object] the record being tested
-      # @param result [Boolean] whether the match succeeded
+      # @param result [Boolean, Exception] whether the match succeeded or an error occurred
       # @return [String] the formatted output string
       def debug_display(record, result)
         "#{self.class.name.split('::').last} #{colored_result(result)}, " \
@@ -139,6 +197,10 @@ module Mongory
           "record: #{record.inspect}"
       end
 
+      # Formats the match result with ANSI color codes for terminal output.
+      #
+      # @param result [Boolean, Exception] the match result or error
+      # @return [String] the colored result string
       def colored_result(result)
         if result.is_a?(Exception)
           "\e[45;97m#{result}\e[0m"

data/lib/mongory/matchers/abstract_multi_matcher.rb

@@ -16,6 +16,14 @@ module Mongory
     # @abstract
     # @see AbstractMatcher
     class AbstractMultiMatcher < AbstractMatcher
+      # A Proc that always returns true, used as a default for empty AND conditions
+      # @return [Proc] A proc that always returns true
+      TRUE_PROC = Proc.new { |_| true }
+
+      # A Proc that always returns false, used as a default for empty OR conditions
+      # @return [Proc] A proc that always returns false
+      FALSE_PROC = Proc.new { |_| false }
+
       # Enables auto-unwrap logic.
       # When used, `.build` may unwrap to first matcher if only one is present.
       #
@@ -29,61 +37,24 @@ module Mongory
       private_class_method :enable_unwrap!
 
       # Builds a matcher and conditionally unwraps it.
+      # If unwrapping is enabled and there is only one submatcher,
+      # returns that submatcher instead of the multi-matcher wrapper.
       #
       # @param args [Array] arguments passed to the constructor
-      # @return [AbstractMatcher]
-      def self.build_or_unwrap(*args)
-        matcher = new(*args)
+      # @param context [Context] the query context
+      # @return [AbstractMatcher] the constructed matcher or its unwrapped submatcher
+      def self.build_or_unwrap(*args, context: Context.new)
+        matcher = new(*args, context: context)
         return matcher unless @enable_unwrap
 
         matcher = matcher.matchers.first if matcher.matchers.count == 1
         matcher
       end
 
-      # Performs matching over all sub-matchers using the specified operator.
-      # The input record may be preprocessed first (e.g., for normalization).
-      #
-      # @param record [Object] the record to match
-      # @return [Boolean] whether the combined result of sub-matchers satisfies the condition
-      def match(record)
-        record = preprocess(record)
-        matchers.send(operator) do |matcher|
-          matcher.match?(record)
-        end
-      end
-
-      # Lazily builds and caches the array of sub-matchers.
-      # Subclasses provide the implementation of `#build_sub_matcher`.
-      # Duplicate matchers (by uniq_key) are removed to avoid redundancy.
-      #
-      # @return [Array<AbstractMatcher>] list of sub-matchers
-      define_instance_cache_method(:matchers) do
-        @condition.map(&method(:build_sub_matcher)).uniq(&:uniq_key)
-      end
-
-      # Optional hook for subclasses to transform the input record before matching.
-      # Default implementation returns the record unchanged.
-      #
-      # @param record [Object] the input record
-      # @return [Object] the transformed or original record
-      def preprocess(record)
-        record
-      end
-
-      # Abstract method to define how each subcondition should be turned into a matcher.
-      #
-      # @param args [Array] the inputs needed to construct a matcher
-      # @return [AbstractMatcher] a matcher instance for the subcondition
-      def build_sub_matcher(*args); end
-
-      # Abstract method to specify the combining operator for sub-matchers.
-      # Must return a valid enumerable method name (e.g., :all?, :any?).
-      #
-      # @return [Symbol] the operator method to apply over matchers
-      def operator; end
-
       # Recursively checks all submatchers for validity.
+      # Raises an error if any submatcher is invalid.
       #
+      # @raise [Mongory::TypeError] if any submatcher is invalid
       # @return [void]
       def check_validity!
         matchers.each(&:check_validity!)

data/lib/mongory/matchers/and_matcher.rb

@@ -5,6 +5,7 @@ module Mongory
     # AndMatcher implements the `$and` logical operator.
     #
     # It evaluates an array of subconditions and returns true only if *all* of them match.
+    # For empty conditions, it returns true (using TRUE_PROC), following MongoDB's behavior.
     #
     # Unlike other matchers, AndMatcher flattens the underlying matcher tree by
     # delegating each subcondition to a `HashConditionMatcher`, and further extracting
@@ -12,39 +13,66 @@ module Mongory
     #
     # This allows the matcher trace (`.explain`) to render as a flat list of independent conditions.
     #
-    # @example
+    # @example Basic usage
     #   matcher = AndMatcher.build([
     #     { age: { :$gte => 18 } },
     #     { name: /foo/ }
     #   ])
     #   matcher.match?(record) #=> true if both match
     #
+    # @example Empty conditions
+    #   matcher = AndMatcher.build([])
+    #   matcher.match?(record) #=> true (uses TRUE_PROC)
+    #
     # @see AbstractMultiMatcher
     class AndMatcher < AbstractMultiMatcher
       # Constructs a HashConditionMatcher for each subcondition.
       # Conversion is disabled to avoid double-processing.
       enable_unwrap!
 
+      # Creates a raw Proc that performs the AND operation.
+      # The Proc combines all subcondition Procs and returns true only if all match.
+      # For empty conditions, returns TRUE_PROC.
+      #
+      # @return [Proc] a Proc that performs the AND operation
+      def raw_proc
+        return TRUE_PROC if matchers.empty?
+
+        combine_procs(*matchers.map(&:to_proc))
+      end
+
+      # Recursively combines multiple matcher procs with AND logic.
+      # This method optimizes the combination of multiple matchers by building
+      # a balanced tree of AND operations.
+      #
+      # @param left [Proc] The left matcher proc to combine
+      # @param rest [Array<Proc>] The remaining matcher procs to combine
+      # @return [Proc] A new proc that combines all matchers with AND logic
+      # @example
+      #   combine_procs(proc1, proc2, proc3)
+      #   #=> proc { |record| proc1.call(record) && proc2.call(record) && proc3.call(record) }
+      def combine_procs(left, *rest)
+        return left if rest.empty?
+
+        right = combine_procs(*rest)
+        Proc.new do |record|
+          left.call(record) && right.call(record)
+        end
+      end
+
       # Returns the flattened list of all matchers from each subcondition.
       #
       # Each condition is passed to a HashConditionMatcher, then recursively flattened.
       # All matchers are then deduplicated using `uniq_key`.
       #
-      # @return [Array<AbstractMatcher>]
+      # @return [Array<AbstractMatcher>] A flattened, deduplicated list of matchers
       # @see AbstractMatcher#uniq_key
       define_instance_cache_method(:matchers) do
         @condition.flat_map do |condition|
-          HashConditionMatcher.new(condition).matchers
+          HashConditionMatcher.new(condition, context: @context).matchers
         end.uniq(&:uniq_key)
       end
 
-      # Combines submatcher results using `:all?`.
-      #
-      # @return [Symbol]
-      def operator
-        :all?
-      end
-
       # Ensures the condition is an array of hashes.
       #
       # @raise [Mongory::TypeError] if not valid

data/lib/mongory/matchers/array_record_matcher.rb

@@ -2,29 +2,62 @@
 
 module Mongory
   module Matchers
-    # ArrayRecordMatcher matches records where the record itself is an Array.
+    # ArrayRecordMatcher handles matching against array-type records.
     #
-    # This matcher checks whether any element of the record array satisfies the expected condition.
-    # It is typically used when the record is a collection of values, and the query condition
-    # is either a scalar value or a subcondition matcher.
+    # This matcher is used when a field value is an array and needs to be matched
+    # against a condition. It supports both exact array matching and element-wise
+    # comparison through `$elemMatch`.
     #
-    # @example Match when any element equals the expected value
-    #   matcher = ArrayRecordMatcher.build(42)
-    #   matcher.match?([10, 42, 99])    #=> true
+    # For empty conditions, it returns false (using FALSE_PROC).
     #
-    # @example Match using a nested matcher (e.g. condition is a hash)
-    #   matcher = ArrayRecordMatcher.build({ '$gt' => 10 })
-    #   matcher.match?([5, 20, 3])      #=> true
+    # @example Match exact array
+    #   matcher = ArrayRecordMatcher.build([1, 2, 3])
+    #   matcher.match?([1, 2, 3])  #=> true
+    #   matcher.match?([1, 2])     #=> false
     #
-    # This matcher is automatically invoked by LiteralMatcher when the record value is an array.
+    # @example Match with hash condition
+    #   matcher = ArrayRecordMatcher.build({ '$gt' => 5 })
+    #   matcher.match?([3, 6, 9])  #=> true (6 and 9 match)
+    #   matcher.match?([1, 2, 3])  #=> false
     #
-    # @note This is distinct from `$in` or `$nin`, where the **condition** is an array.
-    #       Here, the **record** is the array being matched against.
+    # @example Empty conditions
+    #   matcher = ArrayRecordMatcher.build([])
+    #   matcher.match?(record) #=> false (uses FALSE_PROC)
     #
-    # @see Mongory::Matchers::InMatcher
-    # @see Mongory::Matchers::LiteralMatcher
+    # @see AbstractMultiMatcher
     class ArrayRecordMatcher < AbstractMultiMatcher
       enable_unwrap!
+
+      # Creates a raw Proc that performs the array matching operation.
+      # The Proc checks if any element in the array matches the condition.
+      # For empty conditions, returns FALSE_PROC.
+      #
+      # @return [Proc] a Proc that performs the array matching operation
+      def raw_proc
+        return FALSE_PROC if matchers.empty?
+
+        combine_procs(*matchers.map(&:to_proc))
+      end
+
+      # Recursively combines multiple matcher procs with OR logic.
+      # This method optimizes the combination of multiple matchers by building
+      # a balanced tree of OR operations.
+      #
+      # @param left [Proc] The left matcher proc to combine
+      # @param rest [Array<Proc>] The remaining matcher procs to combine
+      # @return [Proc] A new proc that combines all matchers with OR logic
+      # @example
+      #   combine_procs(proc1, proc2, proc3)
+      #   #=> proc { |record| proc1.call(record) || proc2.call(record) || proc3.call(record) }
+      def combine_procs(left, *rest)
+        return left if rest.empty?
+
+        right = combine_procs(*rest)
+        Proc.new do |record|
+          left.call(record) || right.call(record)
+        end
+      end
+
       # Builds an array of matchers to evaluate the given condition against an array record.
       #
       # This method returns multiple matchers that will be evaluated using `:any?` logic:
@@ -32,28 +65,21 @@ module Mongory
       # - A hash condition matcher if the condition is a hash
       # - An `$elemMatch` matcher for element-wise comparison
       #
-      # @return [Array<Mongory::Matchers::AbstractMatcher>] an array of matcher instances
+      # @return [Array<AbstractMatcher>] An array of matcher instances
       define_instance_cache_method(:matchers) do
         result = []
-        result << EqMatcher.build(@condition) if @condition.is_a?(Array)
+        result << EqMatcher.build(@condition, context: @context) if @condition.is_a?(Array)
         result << case @condition
                   when Hash
-                    HashConditionMatcher.build(parsed_condition)
+                    HashConditionMatcher.build(parsed_condition, context: @context)
                   when Regexp
-                    ElemMatchMatcher.build('$regex' => @condition)
+                    ElemMatchMatcher.build({ '$regex' => @condition }, context: @context)
                   else
-                    ElemMatchMatcher.build('$eq' => @condition)
+                    ElemMatchMatcher.build({ '$eq' => @condition }, context: @context)
                   end
         result
       end
 
-      # Combines results using `:any?` for multi-match logic.
-      #
-      # @return [Symbol]
-      def operator
-        :any?
-      end
-
       private
 
       # Parses the original condition hash into a normalized structure suitable for HashConditionMatcher.
@@ -63,7 +89,7 @@ module Mongory
       # - Operator keys (e.g., `$size`, `$type`): retained at the top level
       # - All other keys: grouped under a `$elemMatch` clause for element-wise comparison
       #
-      # @return [Hash] a normalized condition hash, potentially containing `$elemMatch`
+      # @return [Hash] A normalized condition hash, potentially containing `$elemMatch`
       def parsed_condition
         h_parsed = {}
         h_elem_match = {}

data/lib/mongory/matchers/elem_match_matcher.rb

@@ -18,16 +18,20 @@ module Mongory
     #
     # @see HashConditionMatcher
     class ElemMatchMatcher < HashConditionMatcher
-      # Matches true if any element in the array satisfies the condition.
-      # Falls back to false if the input is not an array.
-
-      # @param collection [Object] the input to be tested
-      # @return [Boolean] whether any element matches
-      def match(collection)
-        return false unless collection.is_a?(Array)
+      # Creates a raw Proc that performs the element matching operation.
+      # The Proc checks if any element in the array matches the condition.
+      #
+      # @return [Proc] a Proc that performs the element matching operation
+      def raw_proc
+        super_proc = super
+        need_convert = @context.need_convert
+        data_converter = Mongory.data_converter
 
-        collection.any? do |record|
-          super(Mongory.data_converter.convert(record))
+        Proc.new do |collection|
+          collection.any? do |record|
+            record = data_converter.convert(record) if need_convert
+            super_proc.call(record)
+          end
         end
       end
 

data/lib/mongory/matchers/eq_matcher.rb

@@ -4,7 +4,7 @@ module Mongory
   module Matchers
     # EqMatcher matches values using the equality operator `==`.
     #
-    # It inherits from AbstractOperatorMatcher and defines its operator as `:==`.
+    # It inherits from AbstractMatcher and defines its operator as `:==`.
     #
     # Used for conditions like:
     # - { age: { '$eq' => 30 } }
@@ -22,13 +22,18 @@ module Mongory
     #
     # @note Equality behavior depends on how `==` is implemented for the given objects.
     #
-    # @see AbstractOperatorMatcher
-    class EqMatcher < AbstractOperatorMatcher
-      # Returns the Ruby equality operator to be used in matching.
+    # @see AbstractMatcher
+    class EqMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the equality check.
+      # The Proc uses the `==` operator to compare values.
       #
-      # @return [Symbol] the equality operator symbol
-      def operator
-        :==
+      # @return [Proc] a Proc that performs the equality check
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record == condition
+        end
       end
     end
 

data/lib/mongory/matchers/every_matcher.rb

@@ -15,20 +15,31 @@ module Mongory
     #
     # @see HashConditionMatcher
     class EveryMatcher < HashConditionMatcher
-      # Matches true if all element in the array satisfies the condition.
-      # Falls back to false if the input is not an array.
+      # Creates a raw Proc that performs the element matching operation.
+      # The Proc checks if all elements in the array match the condition.
+      #
+      # @return [Proc] A proc that performs element matching with context awareness
+      # @note The proc includes error handling and context-based record conversion
+      def raw_proc
+        super_proc = super
+        need_convert = @context.need_convert
+        data_converter = Mongory.data_converter
 
-      # @param collection [Object] the input to be tested
-      # @return [Boolean] whether all element matches
-      def match(collection)
-        return false unless collection.is_a?(Array)
-        return false if collection.empty?
+        Proc.new do |collection|
+          next false unless collection.is_a?(Array)
+          next false if collection.empty?
 
-        collection.all? do |record|
-          super(Mongory.data_converter.convert(record))
+          collection.all? do |record|
+            record = data_converter.convert(record) if need_convert
+            super_proc.call(record)
+          end
         end
       end
 
+      # Ensures the condition is a Hash.
+      #
+      # @raise [Mongory::TypeError] if the condition is not a Hash
+      # @return [void]
       def check_validity!
         raise TypeError, '$every needs a Hash.' unless @condition.is_a?(Hash)
 

data/lib/mongory/matchers/exists_matcher.rb

@@ -17,21 +17,20 @@ module Mongory
     #   matcher = ExistsMatcher.build(false)
     #   matcher.match?(KEY_NOT_FOUND)   #=> true
     #
-    # @see AbstractOperatorMatcher
-    class ExistsMatcher < AbstractOperatorMatcher
-      # Converts the raw record value into a boolean indicating presence.
+    # @see AbstractMatcher
+    class ExistsMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the existence check.
+      # The Proc checks if the record exists and compares it to the condition.
       #
-      # @param record [Object] the value associated with the field
-      # @return [Boolean] true if the key exists, false otherwise
-      def preprocess(record)
-        record != KEY_NOT_FOUND
-      end
+      # @return [Proc] A proc that performs existence check with error handling
+      def raw_proc
+        condition = @condition
 
-      # Uses Ruby's equality operator to compare presence against expected boolean.
-      #
-      # @return [Symbol] the comparison operator
-      def operator
-        :==
+        Proc.new do |record|
+          # Check if the record is nil or KEY_NOT_FOUND
+          # and compare it to the condition.
+          (record != KEY_NOT_FOUND) == condition
+        end
       end
 
       # Ensures that the condition value is a valid boolean.
@@ -39,7 +38,9 @@ module Mongory
       # @raise [TypeError] if condition is not true or false
       # @return [void]
       def check_validity!
-        raise TypeError, '$exists needs a boolean' unless BOOLEAN_VALUES.include?(@condition)
+        return if [true, false].include?(@condition)
+
+        raise TypeError, "$exists needs a boolean, but got #{@condition.inspect}"
       end
     end