mongory 0.3.0

data/lib/mongory/matchers/field_matcher.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # 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 typically used when the query refers to a specific field,
+    # like `{ age: { :$gte => 18 } }` where `:age` is passed as the dig field.
+    #
+    # @example
+    #   matcher = FieldMatcher.build(:age, { :$gte => 18 })
+    #   matcher.match?({ age: 20 }) #=> true
+    #
+    # @see LiteralMatcher
+    class FieldMatcher < LiteralMatcher
+      # A list of classes that should never be used for value digging.
+      # These typically respond to `#[]` but are semantically invalid for this context.
+      CLASSES_NOT_ALLOW_TO_DIG = [
+        ::String,
+        ::Integer,
+        ::Proc,
+        ::Method,
+        ::MatchData,
+        ::Thread,
+        ::Symbol
+      ].freeze
+
+      # Initializes the matcher with a target field and condition.
+      #
+      # @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)
+        @field = field
+        super(condition)
+      end
+
+      # Performs field-based matching against the given record.
+      #
+      # 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
+      # field access (e.g., nil, primitive values, or unsupported types), the match returns false.
+      #
+      # The field value is then extracted using the following rules:
+      # - If the record is a Hash, it attempts to fetch using the field key,
+      #   falling back to symbolized key if needed.
+      # - If the record is an Array, it fetches by index.
+      # - If the record does not support `[]` or is disallowed for dig operations,
+      #   the match returns false immediately.
+      #
+      # 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
+      #
+      # @example Record is nil (structure not diggable)
+      #   matcher = Mongory::QueryMatcher.new(a: nil)
+      #   matcher.match?(nil) # => false
+      #
+      # @example Matching against an Array by index
+      #   matcher = Mongory::QueryMatcher.new(0 => /abc/)
+      #   matcher.match?(['abcdef']) # => true
+      #
+      # @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
+
+        super(Mongory.data_converter.convert(sub_record))
+      end
+
+      # @return [String] a deduplication field used for matchers inside multi-match constructs
+      # @see AbstractMultiMatcher#matchers
+      def uniq_key
+        super + "field:#{@field}"
+      end
+
+      private
+
+      # Returns a single-line summary of the dig matcher including the field and condition.
+      #
+      # @return [String]
+      def tree_title
+        "Field: #{@field.inspect} to match: #{@condition.inspect}"
+      end
+
+      # Custom display logic for debugging, including colored field highlighting.
+      #
+      # @param record [Object] the input record
+      # @param result [Boolean] match result
+      # @return [String] formatted debug string
+      def debug_display(record, result)
+        "#{self.class.name.split('::').last} #{colored_result(result)}, " \
+          "condition: #{@condition.inspect}, " \
+          "\e[30;47mfield: #{@field.inspect}\e[0m, " \
+          "record: #{record.inspect.gsub(@field.inspect, "\e[30;47m#{@field.inspect}\e[0m")}"
+      end
+    end
+  end
+end

data/lib/mongory/matchers/gt_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # GtMatcher implements the `$gt` (greater than) operator.
+    #
+    # It returns true if the record is strictly greater than the condition.
+    #
+    # Inherits core logic from AbstractOperatorMatcher, including
+    # error handling and optional preprocessing.
+    #
+    # @example
+    #   matcher = GtMatcher.build(10)
+    #   matcher.match?(15)  #=> true
+    #   matcher.match?(10)  #=> false
+    #
+    # @see AbstractOperatorMatcher
+    class GtMatcher < AbstractOperatorMatcher
+      # Returns the Ruby `>` operator symbol for comparison.
+      #
+      # @return [Symbol] the greater-than operator
+      def operator
+        :>
+      end
+    end
+
+    register(:gt, '$gt', GtMatcher)
+  end
+end

data/lib/mongory/matchers/gte_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # GteMatcher implements the `$gte` (greater than or equal) operator.
+    #
+    # It returns true if the record is greater than or equal to the condition value.
+    #
+    # Inherits comparison logic and error safety from AbstractOperatorMatcher.
+    #
+    # @example
+    #   matcher = GteMatcher.build(10)
+    #   matcher.match?(10)  #=> true
+    #   matcher.match?(11)  #=> true
+    #   matcher.match?(9)   #=> false
+    #
+    # @see AbstractOperatorMatcher
+    class GteMatcher < AbstractOperatorMatcher
+      # Returns the Ruby `>=` operator symbol for comparison.
+      #
+      # @return [Symbol] the greater-than-or-equal operator
+      def operator
+        :>=
+      end
+    end
+
+    register(:gte, '$gte', GteMatcher)
+  end
+end

data/lib/mongory/matchers/hash_condition_matcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # HashConditionMatcher is responsible for handling field-level query conditions.
+    #
+    # It receives a Hash of key-value pairs and delegates each one to an appropriate matcher
+    # based on whether the key is a recognized operator or a data field path.
+    #
+    # Each subcondition is matched independently using the `:all?` strategy, meaning
+    # all subconditions must match for the entire HashConditionMatcher to succeed.
+    #
+    # This matcher plays a central role in dispatching symbolic query conditions
+    # to the appropriate field or operator matcher.
+    #
+    # @example
+    #   matcher = HashConditionMatcher.build({ age: { :$gt => 30 }, active: true })
+    #   matcher.match?(record) #=> true only if all subconditions match
+    #
+    # @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)
+        end
+      end
+
+      # Specifies the matching strategy for all subconditions.
+      # Uses `:all?`, meaning all conditions must be satisfied.
+      #
+      # @return [Symbol] the combining operator method
+      def operator
+        :all?
+      end
+    end
+  end
+end

data/lib/mongory/matchers/in_matcher.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # InMatcher implements the `$in` operator.
+    #
+    # It checks whether the record matches any value in the condition array.
+    # If the record is an array, it succeeds if any item overlaps with the condition.
+    # If the record is a single value (including `nil`), it matches if it is included in the condition.
+    #
+    # @example Match single value
+    #   matcher = InMatcher.build([1, 2, 3])
+    #   matcher.match?(2)        #=> true
+    #   matcher.match?(5)        #=> false
+    #
+    # @example Match nil
+    #   matcher = InMatcher.build([nil])
+    #   matcher.match?(nil)      #=> true
+    #
+    # @example Match with array
+    #   matcher = InMatcher.build([2, 4])
+    #   matcher.match?([1, 2, 3])  #=> true
+    #   matcher.match?([5, 6])     #=> false
+    #
+    # @see AbstractMatcher
+    class InMatcher < AbstractMatcher
+      # Matches if any element of the record appears in the condition array.
+      # Converts record to an array before intersecting.
+      #
+      # @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)
+        end
+      end
+
+      # Ensures the condition is an array.
+      #
+      # @raise [TypeError] if condition is not an array
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$in needs an array' unless @condition.is_a?(Array)
+      end
+    end
+
+    register(:in, '$in', InMatcher)
+  end
+end

data/lib/mongory/matchers/literal_matcher.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # LiteralMatcher is responsible for handling raw literal values in query conditions.
+    #
+    # 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.
+    #
+    # It is used when the query condition is a direct literal and not an operator or nested query.
+    #
+    # @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)
+    #
+    # @note This matcher is commonly dispatched from HashConditionMatcher or FieldMatcher
+    #       when the condition is a simple literal value, not an operator hash.
+    #
+    # === 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 (==)
+    #
+    # === 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
+    class LiteralMatcher < AbstractMatcher
+      # Matches the given record against the condition.
+      #
+      # @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)
+        end
+      end
+
+      # Selects and returns the appropriate matcher instance for a given literal condition.
+      #
+      # This method analyzes the type of the raw condition (e.g., Hash, Regexp, nil)
+      # and returns a dedicated matcher instance accordingly:
+      #
+      # - Hash → dispatches to `HashConditionMatcher`
+      # - Regexp → dispatches to `RegexMatcher`
+      # - nil → dispatches to an `OrMatcher` that emulates MongoDB's `{ field: nil }` behavior
+      #
+      # For all other literal types, this method returns `EqMatcher`, and fallback equality matching will be used.
+      #
+      # This matcher is cached after the first invocation using `define_instance_cache_method`
+      # to avoid unnecessary re-instantiation.
+      #
+      # @see Mongory::Matchers::HashConditionMatcher
+      # @see Mongory::Matchers::RegexMatcher
+      # @see Mongory::Matchers::OrMatcher
+      # @see Mongory::Matchers::EqMatcher
+      # @return [AbstractMatcher] the matcher used for non-array literal values
+      # @!method dispatched_matcher
+      define_matcher(:dispatched) do
+        case @condition
+        when Hash
+          HashConditionMatcher.build(@condition)
+        when Regexp
+          RegexMatcher.build(@condition)
+        when nil
+          OrMatcher.build([
+            { '$exists' => false },
+            { '$eq' => nil }
+          ])
+        else
+          EqMatcher.build(@condition)
+        end
+      end
+
+      # Lazily defines the collection matcher for array records.
+      #
+      # @see ArrayRecordMatcher
+      # @return [ArrayRecordMatcher] the matcher used to match array-type records
+      # @!method array_record_matcher
+      define_matcher(:array_record) do
+        ArrayRecordMatcher.build(@condition)
+      end
+
+      # Validates the nested condition matcher, if applicable.
+      #
+      # @return [void]
+      def check_validity!
+        dispatched_matcher.check_validity!
+      end
+
+      # 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]
+      # @return [void]
+      def render_tree(prefix = '', is_last: true)
+        super
+
+        target_matcher = @array_record_matcher || dispatched_matcher
+        target_matcher.render_tree("#{prefix}#{is_last ? '   ' : '│  '}", is_last: true)
+      end
+    end
+  end
+end

data/lib/mongory/matchers/lt_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # LtMatcher implements the `$lt` (less than) operator.
+    #
+    # It returns true if the record is strictly less than the condition value.
+    #
+    # This matcher inherits from AbstractOperatorMatcher and uses the `<` operator.
+    #
+    # @example
+    #   matcher = LtMatcher.build(10)
+    #   matcher.match?(9)    #=> true
+    #   matcher.match?(10)   #=> false
+    #   matcher.match?(11)   #=> false
+    #
+    # @see AbstractOperatorMatcher
+    class LtMatcher < AbstractOperatorMatcher
+      # Returns the Ruby `<` operator symbol for comparison.
+      #
+      # @return [Symbol] the less-than operator
+      def operator
+        :<
+      end
+    end
+
+    register(:lt, '$lt', LtMatcher)
+  end
+end

data/lib/mongory/matchers/lte_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # LteMatcher implements the `$lte` (less than or equal to) operator.
+    #
+    # It returns true if the record is less than or equal to the condition value.
+    #
+    # This matcher inherits from AbstractOperatorMatcher and uses the `<=` operator.
+    #
+    # @example
+    #   matcher = LteMatcher.build(10)
+    #   matcher.match?(9)    #=> true
+    #   matcher.match?(10)   #=> true
+    #   matcher.match?(11)   #=> false
+    #
+    # @see AbstractOperatorMatcher
+    class LteMatcher < AbstractOperatorMatcher
+      # Returns the Ruby `<=` operator symbol for comparison.
+      #
+      # @return [Symbol] the less-than-or-equal operator
+      def operator
+        :<=
+      end
+    end
+
+    register(:lte, '$lte', LteMatcher)
+  end
+end

data/lib/mongory/matchers/ne_matcher.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # NeMatcher implements the `$ne` (not equal) operator.
+    #
+    # It returns true if the record is *not equal* to the condition.
+    #
+    # This matcher inherits its logic from AbstractOperatorMatcher
+    # and uses Ruby's `!=` operator for comparison.
+    #
+    # @example
+    #   matcher = NeMatcher.build(42)
+    #   matcher.match?(41)  #=> true
+    #   matcher.match?(42)  #=> false
+    #
+    # @see AbstractOperatorMatcher
+    class NeMatcher < AbstractOperatorMatcher
+      # Returns the Ruby `!=` operator symbol for comparison.
+      #
+      # @return [Symbol] the not-equal operator
+      def operator
+        :!=
+      end
+    end
+
+    register(:ne, '$ne', NeMatcher)
+  end
+end

data/lib/mongory/matchers/nin_matcher.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # NinMatcher implements the `$nin` (not in) operator.
+    #
+    # It succeeds only if the record does not match any value in the condition array.
+    # If the record is an array, it fails if any element overlaps with the condition.
+    # If the record is a single value (including `nil`), it fails if it is included in the condition.
+    #
+    # @example Match single value
+    #   matcher = NinMatcher.build([1, 2, 3])
+    #   matcher.match?(4)        #=> true
+    #   matcher.match?(2)        #=> false
+    #
+    # @example Match nil
+    #   matcher = NinMatcher.build([nil])
+    #   matcher.match?(nil)      #=> false
+    #
+    # @example Match with array
+    #   matcher = NinMatcher.build([2, 4])
+    #   matcher.match?([1, 3, 5])  #=> true
+    #   matcher.match?([4, 5])     #=> false
+    #
+    # @see AbstractMatcher
+    class NinMatcher < AbstractMatcher
+      # Matches true 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)
+        end
+      end
+
+      # Ensures the condition is a valid array.
+      #
+      # @raise [TypeError] if the condition is not an array
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$nin needs an array' unless @condition.is_a?(Array)
+      end
+    end
+
+    register(:nin, '$nin', NinMatcher)
+  end
+end

data/lib/mongory/matchers/not_matcher.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # NotMatcher implements the `$not` logical operator.
+    #
+    # It returns true if the wrapped matcher fails, effectively inverting the result.
+    #
+    # It delegates to LiteralMatcher and simply negates the outcome.
+    #
+    # This allows constructs like:
+    #   { age: { :$not => { :$gte => 30 } } }
+    #
+    # @example
+    #   matcher = NotMatcher.build({ :$gte => 10 })
+    #   matcher.match?(5)    #=> true
+    #   matcher.match?(15)   #=> false
+    #
+    # @see LiteralMatcher
+    class NotMatcher < LiteralMatcher
+      # Inverts the result of LiteralMatcher#match.
+      #
+      # @param record [Object] the value to test
+      # @return [Boolean] whether the negated condition is satisfied
+      def match(record)
+        !super(record)
+      end
+    end
+
+    register(:not, '$not', NotMatcher)
+  end
+end

data/lib/mongory/matchers/or_matcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # OrMatcher implements the `$or` logical operator.
+    #
+    # It evaluates an array of subconditions and returns true
+    # if *any one* of them matches.
+    #
+    # Each subcondition is handled by a HashConditionMatcher with conversion disabled,
+    # since the parent matcher already manages data conversion.
+    #
+    # This matcher inherits submatcher dispatch and evaluation logic
+    # from AbstractMultiMatcher.
+    #
+    # @example
+    #   matcher = OrMatcher.build([
+    #     { age: { :$lt => 18 } },
+    #     { admin: true }
+    #   ])
+    #   matcher.match?(record) #=> true if either condition matches
+    #
+    # @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)
+      end
+
+      # Uses `:any?` to return true if any submatcher passes.
+      #
+      # @return [Symbol] the combining operator
+      def operator
+        :any?
+      end
+
+      # Ensures the condition is an array of hashes.
+      #
+      # @raise [Mongory::TypeError] if not valid
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$or needs an array' unless @condition.is_a?(Array)
+
+        @condition.each do |sub_condition|
+          raise TypeError, '$or needs an array of hash' unless sub_condition.is_a?(Hash)
+        end
+
+        super
+      end
+    end
+
+    register(:or, '$or', OrMatcher)
+  end
+end