mongory 0.4.0 → 0.6.1

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
 

data/lib/mongory/matchers/field_matcher.rb

@@ -2,18 +2,22 @@
 
 module Mongory
   module Matchers
-    # FieldMatcher is responsible for extracting a value from a record
-    # using a field (or index) and then delegating the match to LiteralMatcher logic.
+    # FieldMatcher handles field-level matching by extracting and comparing field values.
     #
-    # It handles nested access in structures like Hashes or Arrays, and guards
-    # against types that should not be dig into (e.g., String, Symbol, Proc).
+    # This matcher is responsible for:
+    # 1. Extracting field values from records using dot notation
+    # 2. Converting extracted values if needed
+    # 3. Delegating the actual comparison to a submatcher
     #
-    # This matcher is typically used when the query refers to a specific field,
-    # like `{ age: { :$gte => 18 } }` where `:age` is passed as the dig field.
+    # It supports:
+    # - Hash records with string/symbol keys
+    # - Array records with numeric indices
+    # - Objects that respond to `[]`
     #
-    # @example
-    #   matcher = FieldMatcher.build(:age, { :$gte => 18 })
-    #   matcher.match?({ age: 20 }) #=> true
+    # @example Basic field matching
+    #   matcher = FieldMatcher.build('age', 30)
+    #   matcher.match?({ 'age' => 30 })  #=> true
+    #   matcher.match?({ age: 30 })      #=> true
     #
     # @see LiteralMatcher
     class FieldMatcher < LiteralMatcher
@@ -29,16 +33,18 @@ module Mongory
         ::Symbol
       ].freeze
 
-      # Initializes the matcher with a target field and condition.
+      # Initializes a new field matcher.
       #
-      # @param field [Object] the field (or index) used to dig into the record
-      # @param condition [Object] the condition to match against the extracted value
-      def initialize(field, condition)
+      # @param field [String, Symbol] the field to match against
+      # @param condition [Object] the condition to match with
+      # @param context [Context] the query context
+      def initialize(field, condition, context: Context.new)
         @field = field
-        super(condition)
+        super(condition, context: context)
       end
 
-      # Performs field-based matching against the given record.
+      # Creates a raw Proc that performs the field matching operation.
+      # The Proc extracts the field value and delegates to the submatcher.
       #
       # This method first ensures the record is structurally eligible for field extraction—
       # it must be a Hash, Array, or respond to `[]`. If the structure does not allow for
@@ -54,9 +60,6 @@ module Mongory
       # Once the value is extracted, it is passed through the data converter
       # and matched against the condition via the superclass.
       #
-      # @param record [Object] the input data structure to be matched
-      # @return [Boolean] true if the extracted field value matches the condition; false otherwise
-      #
       # @example Matching a Hash with a nil field value
       #   matcher = Mongory::QueryMatcher.new(a: nil)
       #   matcher.match?({ a: nil }) # => true
@@ -72,27 +75,44 @@ module Mongory
       # @example Hash with symbol key, matcher uses string key
       #   matcher = Mongory::QueryMatcher.new('a' => 123)
       #   matcher.match?({ a: 123 }) # => true
-      def match(record)
-        sub_record =
-          case record
-          when Hash
-            record.fetch(@field) do
-              record.fetch(@field.to_sym, KEY_NOT_FOUND)
-            end
-          when Array
-            record.fetch(@field, KEY_NOT_FOUND)
-          when KEY_NOT_FOUND, *CLASSES_NOT_ALLOW_TO_DIG
-            return false
-          else
-            return false unless record.respond_to?(:[])
 
-            record[@field]
-          end
+      # Creates a raw Proc that performs the field-based matching operation.
+      # The Proc extracts the field value and delegates matching to the superclass.
+      #
+      # @return [Proc] A proc that performs field-based matching with context awareness
+      # @note The proc handles field extraction and delegates matching to the superclass
+      def raw_proc
+        super_proc = super
+        field = @field
+        need_convert = @context.need_convert
+        data_converter = Mongory.data_converter
+
+        Proc.new do |record|
+          sub_record =
+            case record
+            when Hash
+              record.fetch(field) do
+                record.fetch(field.to_sym, KEY_NOT_FOUND)
+              end
+            when Array
+              record.fetch(field, KEY_NOT_FOUND)
+            when KEY_NOT_FOUND, *CLASSES_NOT_ALLOW_TO_DIG
+              next false
+            else
+              next false unless record.respond_to?(:[])
 
-        super(Mongory.data_converter.convert(sub_record))
+              record[field]
+            end
+
+          sub_record = data_converter.convert(sub_record) if need_convert
+          super_proc.call(sub_record)
+        end
       end
 
-      # @return [String] a deduplication field used for matchers inside multi-match constructs
+      # Returns a unique key for this matcher, including the field name.
+      # Used for deduplication in multi-matchers.
+      #
+      # @return [String] a unique key for this matcher
       # @see AbstractMultiMatcher#matchers
       def uniq_key
         super + "field:#{@field}"
@@ -100,9 +120,9 @@ module Mongory
 
       private
 
-      # Returns a single-line summary of the dig matcher including the field and condition.
+      # Returns a single-line summary of the field matcher including the field and condition.
       #
-      # @return [String]
+      # @return [String] a formatted title for tree display
       def tree_title
         "Field: #{@field.inspect} to match: #{@condition.inspect}"
       end
@@ -111,7 +131,7 @@ module Mongory
       #
       # @param record [Object] the input record
       # @param result [Boolean] match result
-      # @return [String] formatted debug string
+      # @return [String] formatted debug string with highlighted field
       def debug_display(record, result)
         "#{self.class.name.split('::').last} #{colored_result(result)}, " \
           "condition: #{@condition.inspect}, " \

data/lib/mongory/matchers/gt_matcher.rb

@@ -6,7 +6,7 @@ module Mongory
     #
     # It returns true if the record is strictly greater than the condition.
     #
-    # Inherits core logic from AbstractOperatorMatcher, including
+    # Inherits core logic from AbstractMatcher, including
     # error handling and optional preprocessing.
     #
     # @example
@@ -14,13 +14,21 @@ module Mongory
     #   matcher.match?(15)  #=> true
     #   matcher.match?(10)  #=> false
     #
-    # @see AbstractOperatorMatcher
-    class GtMatcher < AbstractOperatorMatcher
-      # Returns the Ruby `>` operator symbol for comparison.
+    # @see AbstractMatcher
+    class GtMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the greater-than comparison.
+      # The Proc uses the `>` operator to compare values.
       #
-      # @return [Symbol] the greater-than operator
-      def operator
-        :>
+      # @return [Proc] A proc that performs greater-than comparison with error handling
+      # @note The proc includes error handling for invalid comparisons
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record > condition
+        rescue StandardError
+          false
+        end
       end
     end
 

data/lib/mongory/matchers/gte_matcher.rb

@@ -6,7 +6,7 @@ module Mongory
     #
     # It returns true if the record is greater than or equal to the condition value.
     #
-    # Inherits comparison logic and error safety from AbstractOperatorMatcher.
+    # Inherits comparison logic and error safety from AbstractMatcher.
     #
     # @example
     #   matcher = GteMatcher.build(10)
@@ -14,13 +14,21 @@ module Mongory
     #   matcher.match?(11)  #=> true
     #   matcher.match?(9)   #=> false
     #
-    # @see AbstractOperatorMatcher
-    class GteMatcher < AbstractOperatorMatcher
-      # Returns the Ruby `>=` operator symbol for comparison.
+    # @see AbstractMatcher
+    class GteMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the greater-than-or-equal comparison.
+      # The Proc uses the `>=` operator to compare values.
       #
-      # @return [Symbol] the greater-than-or-equal operator
-      def operator
-        :>=
+      # @return [Proc] A proc that performs greater-than-or-equal comparison with error handling
+      # @note The proc includes error handling for invalid comparisons
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record >= condition
+        rescue StandardError
+          false
+        end
       end
     end
 

data/lib/mongory/matchers/hash_condition_matcher.rb

@@ -9,46 +9,74 @@ module Mongory
     #
     # Each subcondition is matched independently using the `:all?` strategy, meaning
     # all subconditions must match for the entire HashConditionMatcher to succeed.
+    # For empty conditions, it returns true (using TRUE_PROC).
     #
     # This matcher plays a central role in dispatching symbolic query conditions
     # to the appropriate field or operator matcher.
     #
-    # @example
+    # @example Basic field matching
     #   matcher = HashConditionMatcher.build({ age: { :$gt => 30 }, active: true })
     #   matcher.match?(record) #=> true only if all subconditions match
     #
+    # @example Empty conditions
+    #   matcher = HashConditionMatcher.build({})
+    #   matcher.match?(record) #=> true (uses TRUE_PROC)
+    #
     # @see AbstractMultiMatcher
     class HashConditionMatcher < AbstractMultiMatcher
       enable_unwrap!
-      # Constructs the appropriate submatcher for a key-value pair.
-      # If the key is a registered operator, dispatches to the corresponding matcher.
-      # Otherwise, assumes the key is a field path and uses FieldMatcher.
-
-      # @see FieldMatcher
-      # @see Matchers.lookup
-      # @param key [String] the condition key (either an operator or field name)
-      # @param value [Object] the condition value
-      # @return [AbstractMatcher] a matcher instance
-      def build_sub_matcher(key, value)
-        case key
-        when *Matchers.operators
-          # If the key is a recognized operator, use the corresponding matcher
-          # to handle the value.
-          # This allows for nested conditions like { :$and => [{ age: { :$gt => 30 } }] }
-          # or { :$or => [{ name: 'John' }, { age: { :$lt => 25 } }] }
-          # The operator matcher is built using the value.
-          Matchers.lookup(key).build(value)
-        else
-          FieldMatcher.build(key, value)
+
+      # Creates a raw Proc that performs the hash condition matching operation.
+      # The Proc combines all submatcher Procs and returns true only if all match.
+      # For empty conditions, returns TRUE_PROC.
+      #
+      # @return [Proc] a Proc that performs the hash condition matching 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
 
-      # Specifies the matching strategy for all subconditions.
-      # Uses `:all?`, meaning all conditions must be satisfied.
+      # Returns the list of matchers for each key-value pair in the condition.
+      #
+      # For each pair:
+      # - If the key is a registered operator, uses the corresponding matcher
+      # - Otherwise, wraps the value in a FieldMatcher for field path matching
       #
-      # @return [Symbol] the combining operator method
-      def operator
-        :all?
+      # @return [Array<AbstractMatcher>] List of matchers for each condition
+      define_instance_cache_method(:matchers) do
+        @condition.map do |key, value|
+          if (matcher_class = Matchers.lookup(key))
+            matcher_class.build(value, context: @context)
+          else
+            FieldMatcher.build(key, value, context: @context)
+          end
+        end
+      end
+
+      def check_validity!
+        return super if @condition.is_a?(Hash)
+
+        raise TypeError, 'condition needs a Hash.'
       end
     end
   end

data/lib/mongory/matchers/in_matcher.rb

@@ -24,26 +24,33 @@ module Mongory
     #
     # @see AbstractMatcher
     class InMatcher < AbstractMatcher
-      # Matches if any element of the record appears in the condition array.
-      # Converts record to an array before intersecting.
+      # Creates a raw Proc that performs the in-matching operation.
+      # The Proc checks if any element of the record is in the condition array.
       #
-      # @param record [Object] the record value to test
-      # @return [Boolean] whether any values intersect
-      def match(record)
-        record = normalize(record)
-        if record.is_a?(Array)
-          is_present?(@condition & record)
-        else
-          @condition.include?(record)
+      # @return [Proc] a Proc that performs the in-matching operation
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          if record.is_a?(Array)
+            return false if condition.is_a?(Range)
+
+            is_present?(condition & record)
+          else
+            condition.include?(record)
+          end
         end
       end
 
-      # Ensures the condition is an array.
+      # Ensures the condition is an array or range.
       #
-      # @raise [TypeError] if condition is not an array
+      # @raise [TypeError] if condition is not an array nor a range
       # @return [void]
       def check_validity!
-        raise TypeError, '$in needs an array' unless @condition.is_a?(Array)
+        return if @condition.is_a?(Array)
+        return if @condition.is_a?(Range)
+
+        raise TypeError, '$in needs an array or range'
       end
     end