mongory 0.7.3-aarch64-linux-musl

data/lib/mongory/matchers/elem_match_matcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # ElemMatchMatcher implements the logic for Mongo-style `$elemMatch`.
+    #
+    # It is used to determine if *any* element in an array matches the given condition.
+    #
+    # This matcher delegates element-wise comparison to HashConditionMatcher,
+    # allowing nested conditions to be applied recursively.
+    #
+    # Typically used internally by ArrayRecordMatcher when dealing with
+    # non-indexed hash-style subconditions.
+    #
+    # @example
+    #   matcher = ElemMatchMatcher.build({ status: 'active' })
+    #   matcher.match?([{ status: 'inactive' }, { status: 'active' }]) #=> true
+    #
+    # @see HashConditionMatcher
+    class ElemMatchMatcher < HashConditionMatcher
+      # 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
+
+        Proc.new do |collection|
+          collection.any? do |record|
+            record = data_converter.convert(record) if need_convert
+            super_proc.call(record)
+          end
+        end
+      end
+
+      def priority
+        3 + super
+      end
+
+      # Ensures the condition is a Hash.
+      #
+      # @raise [Mongory::TypeError] if the condition is not a Hash
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$elemMatch needs a Hash.' unless @condition.is_a?(Hash)
+
+        super
+      end
+    end
+
+    register(:elem_match, '$elemMatch', ElemMatchMatcher)
+  end
+end

data/lib/mongory/matchers/eq_matcher.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # EqMatcher matches values using the equality operator `==`.
+    #
+    # It inherits from AbstractMatcher and defines its operator as `:==`.
+    #
+    # Used for conditions like:
+    # - { age: { '$eq' => 30 } }
+    # - { name: "Alice" } (implicit fallback)
+    #
+    # This matcher supports any Ruby object that implements `#==`.
+    #
+    # @example
+    #   matcher = EqMatcher.build(42)
+    #   matcher.match?(42)       #=> true
+    #   matcher.match?("42")     #=> false
+    #
+    # @note This matcher is also used as the fallback for non-operator literal values,
+    #       such as `{ name: "Alice" }`, when no other specialized matcher is applicable.
+    #
+    # @note Equality behavior depends on how `==` is implemented for the given objects.
+    #
+    # @see AbstractMatcher
+    class EqMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the equality check.
+      # The Proc uses the `==` operator to compare values.
+      #
+      # @return [Proc] a Proc that performs the equality check
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record == condition
+        end
+      end
+
+      def priority
+        1
+      end
+    end
+
+    register(:eq, '$eq', EqMatcher)
+  end
+end

data/lib/mongory/matchers/every_matcher.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # EveryMatcher implements the logic for Mongo-style `$every` which is not really support in MongoDB.
+    #
+    # It is used to determine if *all* element in an array matches the given condition.
+    #
+    # This matcher delegates element-wise comparison to HashConditionMatcher,
+    # allowing nested conditions to be applied recursively.
+    #
+    # @example
+    #   matcher = EveryMatcher.build({ status: 'active' })
+    #   matcher.match?([{ status: 'inactive' }, { status: 'active' }]) #=> false
+    #
+    # @see HashConditionMatcher
+    class EveryMatcher < HashConditionMatcher
+      # 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
+
+        Proc.new do |collection|
+          next false unless collection.is_a?(Array)
+          next false if collection.empty?
+
+          collection.all? do |record|
+            record = data_converter.convert(record) if need_convert
+            super_proc.call(record)
+          end
+        end
+      end
+
+      def priority
+        3 + super
+      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)
+
+        super
+      end
+    end
+
+    register(:every, '$every', EveryMatcher)
+  end
+end

data/lib/mongory/matchers/exists_matcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # ExistsMatcher implements the `$exists` operator, which checks whether a key exists.
+    #
+    # It transforms the presence (or absence) of a field into a boolean value,
+    # then compares it to the condition using the `==` operator.
+    #
+    # This matcher ensures the condition is strictly a boolean (`true` or `false`).
+    #
+    # @example
+    #   matcher = ExistsMatcher.build(true)
+    #   matcher.match?(42)              #=> true
+    #   matcher.match?(KEY_NOT_FOUND)   #=> false
+    #
+    #   matcher = ExistsMatcher.build(false)
+    #   matcher.match?(KEY_NOT_FOUND)   #=> true
+    #
+    # @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.
+      #
+      # @return [Proc] A proc that performs existence check with error handling
+      def raw_proc
+        condition = @condition
+
+        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
+
+      def priority
+        2
+      end
+
+      # Ensures that the condition value is a valid boolean.
+      #
+      # @raise [TypeError] if condition is not true or false
+      # @return [void]
+      def check_validity!
+        return if [true, false].include?(@condition)
+
+        raise TypeError, "$exists needs a boolean, but got #{@condition.inspect}"
+      end
+    end
+
+    register(:exists, '$exists', ExistsMatcher)
+  end
+end

data/lib/mongory/matchers/field_matcher.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # FieldMatcher handles field-level matching by extracting and comparing field values.
+    #
+    # 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
+    #
+    # It supports:
+    # - Hash records with string/symbol keys
+    # - Array records with numeric indices
+    # - Objects that respond to `[]`
+    #
+    # @example Basic field matching
+    #   matcher = FieldMatcher.build('age', 30)
+    #   matcher.match?({ 'age' => 30 })  #=> true
+    #   matcher.match?({ age: 30 })      #=> 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 a new field matcher.
+      #
+      # @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, context: context)
+      end
+
+      # 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
+      # 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.
+      #
+      # @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
+
+      # 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?(:[])
+
+              record[field]
+            end
+
+          sub_record = data_converter.convert(sub_record) if need_convert
+          super_proc.call(sub_record)
+        end
+      end
+
+      def priority
+        1 + super
+      end
+
+      # 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}"
+      end
+
+      private
+
+      # Returns a single-line summary of the field matcher including the field and condition.
+      #
+      # @return [String] a formatted title for tree display
+      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 with highlighted field
+      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,41 @@
+# 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 AbstractMatcher, including
+    # error handling and optional preprocessing.
+    #
+    # @example
+    #   matcher = GtMatcher.build(10)
+    #   matcher.match?(15)  #=> true
+    #   matcher.match?(10)  #=> false
+    #
+    # @see AbstractMatcher
+    class GtMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the greater-than comparison.
+      # The Proc uses the `>` operator to compare values.
+      #
+      # @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
+
+      def priority
+        3
+      end
+    end
+
+    register(:gt, '$gt', GtMatcher)
+  end
+end

data/lib/mongory/matchers/gte_matcher.rb

@@ -0,0 +1,41 @@
+# 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 AbstractMatcher.
+    #
+    # @example
+    #   matcher = GteMatcher.build(10)
+    #   matcher.match?(10)  #=> true
+    #   matcher.match?(11)  #=> true
+    #   matcher.match?(9)   #=> false
+    #
+    # @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 [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
+
+      def priority
+        3
+      end
+    end
+
+    register(:gte, '$gte', GteMatcher)
+  end
+end

data/lib/mongory/matchers/hash_condition_matcher.rb

@@ -0,0 +1,62 @@
+# 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.
+    # 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 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!
+
+      # 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
+        combine_procs_with_and(*matchers.map(&:to_proc))
+      end
+
+      # 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 [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.sort_by(&:priority)
+      end
+
+      def check_validity!
+        return super if @condition.is_a?(Hash)
+
+        raise TypeError, 'condition needs a Hash.'
+      end
+    end
+  end
+end

data/lib/mongory/matchers/in_matcher.rb

@@ -0,0 +1,68 @@
+# 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
+      def self.build(condition, *args)
+        return super unless condition.is_a?(Range)
+
+        end_op = condition.exclude_end? ? '$lt' : '$lte'
+        head, tail = [condition.first, condition.last].sort
+        AndMatcher.build([{ '$gte' => head }, { end_op => tail }], *args)
+      end
+
+      # Creates a raw Proc that performs the in-matching operation.
+      # The Proc checks if any element of the record is in the condition array.
+      #
+      # @return [Proc] a Proc that performs the in-matching operation
+      def raw_proc
+        condition = Set.new(@condition)
+
+        Proc.new do |record|
+          if record.is_a?(Array)
+            is_present?(condition & record)
+          else
+            condition.include?(record)
+          end
+        end
+      end
+
+      def priority
+        1 + Math.log(@condition.size + 1, 1.5)
+      end
+
+      # Ensures the condition is an array or range.
+      #
+      # @raise [TypeError] if condition is not an array nor a range
+      # @return [void]
+      def check_validity!
+        return if @condition.is_a?(Array)
+
+        raise TypeError, '$in needs an array or range'
+      end
+    end
+
+    register(:in, '$in', InMatcher)
+  end
+end

data/lib/mongory/matchers/literal_matcher.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # LiteralMatcher handles direct value comparison with special array handling.
+    #
+    # This matcher is used when a condition is a literal value (not an operator).
+    # It handles both direct equality comparison and array-record scenarios.
+    #
+    # 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 Basic equality matching
+    #   matcher = LiteralMatcher.build(42)
+    #   matcher.match?(42)       #=> true
+    #   matcher.match?([42, 43]) #=> true (array contains 42)
+    #
+    # @example Regexp matching
+    #   matcher = LiteralMatcher.build(/foo/)
+    #   matcher.match?("foo")     #=> true
+    #   matcher.match?(["foobar"]) #=> true
+    #
+    # @example Hash condition matching
+    #   matcher = LiteralMatcher.build({ '$gt' => 10 })
+    #   matcher.match?(15)        #=> true
+    #   matcher.match?([5, 15])   #=> true
+    #
+    # @see AbstractMatcher
+    # @see ArrayRecordMatcher
+    class LiteralMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the literal matching operation.
+      # The Proc handles both array and non-array records appropriately.
+      #
+      # @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
+
+      def priority
+        1 + dispatched_matcher.priority
+      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, context: @context)
+        when Regexp
+          RegexMatcher.build(@condition, context: @context)
+        when nil
+          OrMatcher.build([
+            { '$exists' => false },
+            { '$eq' => nil }
+          ], context: @context)
+        else
+          EqMatcher.build(@condition, context: @context)
+        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, context: @context)
+      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] 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
+
+        target_matcher = @array_record_matcher || dispatched_matcher
+        target_matcher.render_tree("#{prefix}#{is_last ? '   ' : '│  '}", is_last: true)
+      end
+    end
+  end
+end