mongory 0.4.0 → 0.6.1

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,25 +24,33 @@ 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)
+            return true if condition.is_a?(Range)
+
+            is_blank?(condition & record)
+          else
+            !condition.include?(record)
+          end
         end
       end
 
-      # Ensures the condition is a valid array.
+      # Ensures the condition is a valid array or range.
       #
-      # @raise [TypeError] if the condition is not an array
+      # @raise [TypeError] if the condition is not an array nor a range
       # @return [void]
       def check_validity!
-        raise TypeError, '$nin needs an array' unless @condition.is_a?(Array)
+        return if @condition.is_a?(Array)
+        return if @condition.is_a?(Range)
+
+        raise TypeError, '$nin needs an array'
       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
 

data/lib/mongory/matchers/or_matcher.rb

@@ -5,7 +5,8 @@ module Mongory
     # OrMatcher implements the `$or` logical operator.
     #
     # It evaluates an array of subconditions and returns true
-    # if *any one* of them matches.
+    # if *any one* of them matches. For empty conditions, it returns false
+    # (using FALSE_PROC).
     #
     # Each subcondition is handled by a HashConditionMatcher with conversion disabled,
     # since the parent matcher already manages data conversion.
@@ -20,24 +21,52 @@ module Mongory
     #   ])
     #   matcher.match?(record) #=> true if either condition matches
     #
+    # @example Empty conditions
+    #   matcher = OrMatcher.build([])
+    #   matcher.match?(record) #=> false (uses FALSE_PROC)
+    #
     # @see AbstractMultiMatcher
     class OrMatcher < AbstractMultiMatcher
       enable_unwrap!
-      # Constructs a HashConditionMatcher for each subcondition.
-      # Conversion is disabled to avoid double-processing.
-
-      # @see HashConditionMatcher
-      # @param condition [Object] a subcondition to be wrapped
-      # @return [HashConditionMatcher] a matcher for this condition
-      def build_sub_matcher(condition)
-        HashConditionMatcher.build(condition)
+
+      # Creates a raw Proc that performs the or-matching operation.
+      # The Proc combines all submatcher Procs and returns true if any match.
+      # For empty conditions, returns FALSE_PROC.
+      #
+      # @return [Proc] a Proc that performs the or-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
 
-      # Uses `:any?` to return true if any submatcher passes.
+      # Builds an array of matchers from the subconditions.
+      # Each subcondition is wrapped in a HashConditionMatcher.
       #
-      # @return [Symbol] the combining operator
-      def operator
-        :any?
+      # @return [Array<AbstractMatcher>] array of submatchers
+      define_instance_cache_method(:matchers) do
+        @condition.map do |condition|
+          HashConditionMatcher.build(condition, context: @context)
+        end
       end
 
       # Ensures the condition is an array of hashes.

data/lib/mongory/matchers/present_matcher.rb

@@ -20,22 +20,19 @@ module Mongory
     #   matcher = PresentMatcher.build(false)
     #   matcher.match?(nil)         #=> true
     #
-    # @see AbstractOperatorMatcher
-    class PresentMatcher < AbstractOperatorMatcher
-      # Transforms the record into a boolean presence flag
-      # before applying comparison.
+    # @see AbstractMatcher
+    class PresentMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the presence check.
+      # The Proc checks if the record's presence matches the condition.
       #
-      # @param record [Object] the original value
-      # @return [Boolean] whether the value is present
-      def preprocess(record)
-        is_present?(super)
-      end
+      # @return [Proc] A proc that performs presence check
+      def raw_proc
+        condition = @condition
 
-      # Uses Ruby `==` to compare the presence result to the expected boolean.
-      #
-      # @return [Symbol] the equality operator
-      def operator
-        :==
+        Proc.new do |record|
+          record = nil if record == KEY_NOT_FOUND
+          is_present?(record) == condition
+        end
       end
 
       # Ensures that the condition value is a boolean.
@@ -43,7 +40,9 @@ module Mongory
       # @raise [TypeError] if condition is not true or false
       # @return [void]
       def check_validity!
-        raise TypeError, '$present needs a boolean' unless BOOLEAN_VALUES.include?(@condition)
+        return if [true, false].include?(@condition)
+
+        raise TypeError, '$present needs a boolean'
       end
     end
 

data/lib/mongory/matchers/regex_matcher.rb

@@ -12,41 +12,56 @@ module Mongory
     # If a string is provided instead of a Regexp, it will be converted via `Regexp.new(...)`.
     # This ensures consistent behavior for queries like `:field.regex => "foo"` and `:field.regex => /foo/`.
     #
-    # @example
-    #   matcher = RegexMatcher.build('^foo')
+    # @example Basic regex matching
+    #   matcher = RegexMatcher.build(/^foo/)
     #   matcher.match?('foobar')   #=> true
     #   matcher.match?('barfoo')   #=> false
     #
-    # @example Match with explicit regex
-    #   RegexMatcher.build(/admin/i).match?("ADMIN") # => true
+    # @example Case-insensitive matching
+    #   matcher = RegexMatcher.build(/admin/i)
+    #   matcher.match?("ADMIN")    #=> true
     #
-    # @example Match via LiteralMatcher fallback
-    #   LiteralMatcher.new(/admin/i).match("ADMIN") # => true
+    # @example String pattern
+    #   matcher = RegexMatcher.build("^foo")
+    #   matcher.match?("foobar")   #=> true
     #
-    # @see LiteralMatcher
-    # @see Mongory::Matchers::AbstractOperatorMatcher
-    class RegexMatcher < AbstractOperatorMatcher
-      # Uses `:match?` as the operator to invoke on the record string.
+    # @example Non-string input
+    #   matcher = RegexMatcher.build(/\d+/)
+    #   matcher.match?(123)        #=> false (not a string)
+    #
+    # @see AbstractMatcher
+    class RegexMatcher < AbstractMatcher
+      # Initializes the matcher with a regex pattern.
+      # Converts string patterns to Regexp objects.
       #
-      # @return [Symbol] the match? method symbol
-      def operator
-        :match?
+      # @param condition [String, Regexp] the regex pattern to match against
+      # @param context [Context] the query context
+      # @raise [TypeError] if condition is not a string or Regexp
+      def initialize(condition, context: Context.new)
+        super
+        @condition = Regexp.new(condition) if condition.is_a?(String)
       end
 
-      # Ensures the record is a string before applying regex.
-      # If not, coerces to empty string to ensure match fails safely.
+      # Creates a raw Proc that performs the regex matching operation.
+      # The Proc checks if the record is a string that matches the pattern.
+      # Returns false for non-string inputs or if the match fails.
       #
-      # @param record [Object] the raw input
-      # @return [String] a safe string to match against
-      def preprocess(record)
-        return '' unless record.is_a?(String)
+      # @return [Proc] a Proc that performs regex matching
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          next false unless record.is_a?(String)
 
-        record
+          record.match?(condition)
+        rescue StandardError
+          false
+        end
       end
 
-      # Ensures the condition is a Regexp (strings are converted during initialization).
+      # Ensures the condition is a valid regex pattern (Regexp or String).
       #
-      # @raise [TypeError] if condition is not a string
+      # @raise [TypeError] if condition is not a string or Regexp
       # @return [void]
       def check_validity!
         return if @condition.is_a?(Regexp)

data/lib/mongory/matchers/size_matcher.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # Matcher for the `$size` operator.
+    #
+    # This matcher expects the input to be an array, and delegates the comparison
+    # to a literal matcher using the array's size as the value.
+    #
+    # For example, the condition `{ tags: { '$size' => 3 } }` will match any
+    # document where `tags` is an array of length 3.
+    #
+    # ### Supported compound usages:
+    #
+    # ```ruby
+    # Mongory.where(tags: { '$size' => 3 })                       # exactly 3 elements
+    # Mongory.where(tags: { '$size' => { '$gt' => 1 } })          # more than 1
+    # Mongory.where(comments: { '$size' => { '$gt' => 1, '$lte' => 5 } })     # more than 1, up to 5 elements
+    # Mongory.where(tags: { '$size' => { '$in' => [1, 2, 3] } })  # 1, 2, or 3 elements
+    # ```
+    #
+    # @see LiteralMatcher
+    #
+    # @note Ruby's Symbol class already defines a `#size` method,
+    #       that will return the size of the symbol object.
+    #       So, this is the only operator that cannot be used with
+    #       the symbol snippet syntax (e.g. `:tags.size`).
+    #
+    #       Use string key syntax instead: `:"tags.$size" => ...`
+    class SizeMatcher < LiteralMatcher
+      # Creates a raw Proc that performs the size matching operation.
+      #
+      # The returned Proc checks if the input is an Array. If so, it calculates
+      # the array's size and passes it to the wrapped literal matcher Proc.
+      #
+      # @return [Proc] A proc that performs size-based matching
+      def raw_proc
+        super_proc = super
+
+        Proc.new do |record|
+          next false unless record.is_a?(Array)
+
+          super_proc.call(record.size)
+        end
+      end
+    end
+
+    register(:size, '$size', SizeMatcher)
+  end
+end

data/lib/mongory/matchers.rb

@@ -153,7 +153,6 @@ end
 
 require_relative 'matchers/abstract_matcher'
 require_relative 'matchers/abstract_multi_matcher'
-require_relative 'matchers/abstract_operator_matcher'
 require_relative 'matchers/literal_matcher'
 require_relative 'matchers/hash_condition_matcher'
 require_relative 'matchers/and_matcher'
@@ -174,3 +173,4 @@ require_relative 'matchers/not_matcher'
 require_relative 'matchers/or_matcher'
 require_relative 'matchers/present_matcher'
 require_relative 'matchers/regex_matcher'
+require_relative 'matchers/size_matcher'