mongory 0.3.0 → 0.6.0

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,68 @@ 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.
       #
-      # @return [Symbol] the combining operator method
-      def operator
-        :all?
+      # 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 [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
     end
   end

data/lib/mongory/matchers/in_matcher.rb

@@ -24,17 +24,19 @@ 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)
+            is_present?(condition & record)
+          else
+            condition.include?(record)
+          end
         end
       end
 

data/lib/mongory/matchers/literal_matcher.rb

@@ -2,55 +2,49 @@
 
 module Mongory
   module Matchers
-    # LiteralMatcher is responsible for handling raw literal values in query conditions.
+    # LiteralMatcher handles direct value comparison with special array handling.
     #
-    # This matcher dispatches logic based on the type of the literal value,
-    # such as nil, Array, Regexp, Hash, etc., and delegates to the appropriate specialized matcher.
+    # This matcher is used when a condition is a literal value (not an operator).
+    # It handles both direct equality comparison and array-record scenarios.
     #
-    # It is used when the query condition is a direct literal and not an operator or nested query.
+    # For array records:
+    # - Uses ArrayRecordMatcher to check if any element matches
+    # For non-array records:
+    # - Uses appropriate matcher based on condition type (Hash, Regexp, nil, etc.)
     #
-    # @example Supported usages
-    #   { name: "Alice" }         # String literal
-    #   { age: 18 }               # Numeric literal
-    #   { active: true }          # Boolean literal
-    #   { tags: [1, 2, 3] }       # Array literal → ArrayRecordMatcher
-    #   { email: /@gmail\\.com/i } # Regexp literal → RegexMatcher
-    #   { info: nil }             # nil literal → nil_matcher (matches null or missing)
+    # @example Basic equality matching
+    #   matcher = LiteralMatcher.build(42)
+    #   matcher.match?(42)       #=> true
+    #   matcher.match?([42, 43]) #=> true (array contains 42)
     #
-    # @note This matcher is commonly dispatched from HashConditionMatcher or FieldMatcher
-    #       when the condition is a simple literal value, not an operator hash.
+    # @example Regexp matching
+    #   matcher = LiteralMatcher.build(/foo/)
+    #   matcher.match?("foo")     #=> true
+    #   matcher.match?(["foobar"]) #=> true
     #
-    # === Supported literal types:
-    # - String
-    # - Integer / Float
-    # - Symbol
-    # - TrueClass / FalseClass
-    # - NilClass → delegates to nil_matcher
-    # - Regexp → delegates to RegexMatcher
-    # - Array → delegates to ArrayRecordMatcher
-    # - Hash → delegates to HashConditionMatcher (if treated as sub-query)
-    # - Other unrecognized values → fallback to equality match (==)
+    # @example Hash condition matching
+    #   matcher = LiteralMatcher.build({ '$gt' => 10 })
+    #   matcher.match?(15)        #=> true
+    #   matcher.match?([5, 15])   #=> true
     #
-    # === Excluded types (handled by other matchers):
-    # - Operator hashes like `{ "$gt" => 5 }` → handled by OperatorMatcher
-    # - Nested paths like `"a.b.c"` → handled by FieldMatcher
-    # - Query combinators like `$or`, `$and`, `$not` → handled by corresponding matchers
-    #
-    # @see Mongory::Matchers::RegexMatcher
-    # @see Mongory::Matchers::OrMatcher
-    # @see Mongory::Matchers::ArrayRecordMatcher
-    # @see Mongory::Matchers::HashConditionMatcher
+    # @see AbstractMatcher
+    # @see ArrayRecordMatcher
     class LiteralMatcher < AbstractMatcher
-      # Matches the given record against the condition.
+      # Creates a raw Proc that performs the literal matching operation.
+      # The Proc handles both array and non-array records appropriately.
       #
-      # @param record [Object] the record to be matched
-      # @return [Boolean] whether the record satisfies the condition
-      def match(record)
-        case record
-        when Array
-          array_record_matcher.match?(record)
-        else
-          dispatched_matcher.match?(record)
+      # @return [Proc] a Proc that performs the literal matching operation
+      def raw_proc
+        array_record_proc = nil
+        dispatched_proc = dispatched_matcher.to_proc
+
+        Proc.new do |record|
+          if record.is_a?(Array)
+            array_record_proc ||= array_record_matcher.to_proc
+            array_record_proc.call(record)
+          else
+            dispatched_proc.call(record)
+          end
         end
       end
 
@@ -77,16 +71,16 @@ module Mongory
       define_matcher(:dispatched) do
         case @condition
         when Hash
-          HashConditionMatcher.build(@condition)
+          HashConditionMatcher.build(@condition, context: @context)
         when Regexp
-          RegexMatcher.build(@condition)
+          RegexMatcher.build(@condition, context: @context)
         when nil
           OrMatcher.build([
             { '$exists' => false },
             { '$eq' => nil }
-          ])
+          ], context: @context)
         else
-          EqMatcher.build(@condition)
+          EqMatcher.build(@condition, context: @context)
         end
       end
 
@@ -96,7 +90,7 @@ module Mongory
       # @return [ArrayRecordMatcher] the matcher used to match array-type records
       # @!method array_record_matcher
       define_matcher(:array_record) do
-        ArrayRecordMatcher.build(@condition)
+        ArrayRecordMatcher.build(@condition, context: @context)
       end
 
       # Validates the nested condition matcher, if applicable.
@@ -109,8 +103,8 @@ module Mongory
       # Outputs the matcher tree by selecting either collection or condition matcher.
       # Delegates `render_tree` to whichever submatcher was active.
       #
-      # @param prefix [String]
-      # @param is_last [Boolean]
+      # @param prefix [String] the prefix string for tree rendering
+      # @param is_last [Boolean] whether this is the last node in the tree
       # @return [void]
       def render_tree(prefix = '', is_last: true)
         super

data/lib/mongory/matchers/lt_matcher.rb

@@ -6,7 +6,7 @@ module Mongory
     #
     # It returns true if the record is strictly less than the condition value.
     #
-    # This matcher inherits from AbstractOperatorMatcher and uses the `<` operator.
+    # This matcher inherits from AbstractMatcher and uses the `<` operator.
     #
     # @example
     #   matcher = LtMatcher.build(10)
@@ -14,13 +14,21 @@ module Mongory
     #   matcher.match?(10)   #=> false
     #   matcher.match?(11)   #=> false
     #
-    # @see AbstractOperatorMatcher
-    class LtMatcher < AbstractOperatorMatcher
-      # Returns the Ruby `<` operator symbol for comparison.
+    # @see AbstractMatcher
+    class LtMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the less-than comparison.
+      # The Proc uses the `<` operator to compare values.
       #
-      # @return [Symbol] the less-than operator
-      def operator
-        :<
+      # @return [Proc] A proc that performs less-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/lte_matcher.rb

@@ -6,7 +6,7 @@ module Mongory
     #
     # It returns true if the record is less than or equal to the condition value.
     #
-    # This matcher inherits from AbstractOperatorMatcher and uses the `<=` operator.
+    # This matcher inherits from AbstractMatcher and uses the `<=` operator.
     #
     # @example
     #   matcher = LteMatcher.build(10)
@@ -14,13 +14,21 @@ module Mongory
     #   matcher.match?(10)   #=> true
     #   matcher.match?(11)   #=> false
     #
-    # @see AbstractOperatorMatcher
-    class LteMatcher < AbstractOperatorMatcher
-      # Returns the Ruby `<=` operator symbol for comparison.
+    # @see AbstractMatcher
+    class LteMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the less-than-or-equal comparison.
+      # The Proc uses the `<=` operator to compare values.
       #
-      # @return [Symbol] the less-than-or-equal operator
-      def operator
-        :<=
+      # @return [Proc] A proc that performs less-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/ne_matcher.rb

@@ -6,7 +6,7 @@ module Mongory
     #
     # It returns true if the record is *not equal* to the condition.
     #
-    # This matcher inherits its logic from AbstractOperatorMatcher
+    # This matcher inherits its logic from AbstractMatcher
     # and uses Ruby's `!=` operator for comparison.
     #
     # @example
@@ -14,13 +14,18 @@ module Mongory
     #   matcher.match?(41)  #=> true
     #   matcher.match?(42)  #=> false
     #
-    # @see AbstractOperatorMatcher
-    class NeMatcher < AbstractOperatorMatcher
-      # Returns the Ruby `!=` operator symbol for comparison.
+    # @see AbstractMatcher
+    class NeMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the not-equal comparison.
+      # The Proc uses the `!=` operator to compare values.
       #
-      # @return [Symbol] the not-equal operator
-      def operator
-        :!=
+      # @return [Proc] A proc that performs not-equal comparison
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record != condition
+        end
       end
     end
 

data/lib/mongory/matchers/nin_matcher.rb

@@ -24,16 +24,19 @@ module Mongory
     #
     # @see AbstractMatcher
     class NinMatcher < AbstractMatcher
-      # Matches true if the record has no elements in common with the condition array.
+      # Creates a raw Proc that performs the not-in matching operation.
+      # The Proc checks if the record has no elements in common with the condition array.
       #
-      # @param record [Object] the value to be tested
-      # @return [Boolean] whether the record is disjoint from the condition array
-      def match(record)
-        record = normalize(record)
-        if record.is_a?(Array)
-          is_blank?(@condition & record)
-        else
-          !@condition.include?(record)
+      # @return [Proc] A proc that performs not-in matching
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          if record.is_a?(Array)
+            is_blank?(condition & record)
+          else
+            !condition.include?(record)
+          end
         end
       end
 

data/lib/mongory/matchers/not_matcher.rb

@@ -18,12 +18,16 @@ module Mongory
     #
     # @see LiteralMatcher
     class NotMatcher < LiteralMatcher
-      # Inverts the result of LiteralMatcher#match.
+      # Creates a raw Proc that performs the not-matching operation.
+      # The Proc inverts the result of the wrapped matcher.
       #
-      # @param record [Object] the value to test
-      # @return [Boolean] whether the negated condition is satisfied
-      def match(record)
-        !super(record)
+      # @return [Proc] A proc that performs not-matching
+      def raw_proc
+        super_proc = super
+
+        Proc.new do |record|
+          !super_proc.call(record)
+        end
       end
     end