mongory 0.3.0

data/lib/mongory/matchers/abstract_matcher.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # AbstractMatcher is the base class for all matchers in Mongory.
+    #
+    # It defines a common interface (`#match?`) and provides shared behavior
+    # such as condition storage, optional conversion handling, and debugging output.
+    #
+    # Subclasses are expected to implement `#match(record)` to define their matching logic.
+    #
+    # This class also supports caching of lazily-built matchers via `define_matcher`.
+    #
+    # @abstract
+    class AbstractMatcher
+      include Utils
+
+      singleton_class.alias_method :build, :new
+      # Sentinel value used to represent missing keys when traversing nested hashes.
+      KEY_NOT_FOUND = SingletonBuilder.new('KEY_NOT_FOUND')
+
+      # Defines a lazily-evaluated matcher accessor with instance-level caching.
+      #
+      # @param name [Symbol] the name of the matcher (e.g., :collection)
+      # @yield the block that constructs the matcher instance
+      # @return [void]
+      def self.define_matcher(name, &block)
+        define_instance_cache_method(:"#{name}_matcher", &block)
+      end
+
+      # @return [Object] the raw condition this matcher was initialized with
+      attr_reader :condition
+
+      # @return [String] a unique key representing this matcher instance, used for deduplication
+      # @see AbstractMultiMatcher#matchers
+      def uniq_key
+        "#{self.class}:condition:#{@condition.class}:#{@condition}"
+      end
+
+      # Initializes the matcher with a raw condition.
+      #
+      # @param condition [Object] the condition to match against
+      def initialize(condition)
+        @condition = condition
+
+        check_validity!
+      end
+
+      # Performs the actual match logic.
+      # Subclasses must override this method.
+      #
+      # @param record [Object] the input record to test
+      # @return [Boolean] whether the record matches the condition
+      def match(record); end
+
+      # Matches the given record against the condition.
+      #
+      # @param record [Object] the input record
+      # @return [Boolean]
+      def match?(record)
+        match(record)
+      rescue StandardError
+        false
+      end
+
+      # Provides an alias to `#match?` for internal delegation.
+      alias_method :regular_match, :match?
+
+      # Evaluates the match with debugging output.
+      # Increments indent level and prints visual result with colors.
+      #
+      # @param record [Object] the input record to test
+      # @return [Boolean] whether the match succeeded
+      def debug_match(record)
+        result = nil
+
+        Debugger.instance.with_indent do
+          result = begin
+            match(record)
+          rescue StandardError => e
+            e
+          end
+
+          debug_display(record, result)
+        end
+
+        result.is_a?(Exception) ? false : result
+      end
+
+      # Validates the condition (no-op by default).
+      # Override in subclasses to raise error if invalid.
+      #
+      # @return [void]
+      def check_validity!; end
+
+      # Recursively prints the matcher structure into a formatted tree.
+      # Supports indentation and branching layout using prefix symbols.
+      #
+      # @param prefix [String] tree prefix (indentation + lines)
+      # @param is_last [Boolean] whether this node is the last among siblings
+      # @return [void]
+      def render_tree(prefix = '', is_last: true)
+        puts "#{prefix}#{is_last ? '└─ ' : '├─ '}#{tree_title}\n"
+      end
+
+      private
+
+      # Returns a single-line string representing this matcher in the tree output.
+      # Format: `<MatcherType>: <condition.inspect>`
+      #
+      # @return [String]
+      def tree_title
+        matcher_name = self.class.name.split('::').last.sub('Matcher', '')
+        "#{matcher_name}: #{@condition.inspect}"
+      end
+
+      # Normalizes the record before matching.
+      #
+      # If the record is the KEY_NOT_FOUND sentinel (representing a missing field),
+      # it is converted to `nil` so matchers can interpret it consistently.
+      # Other values are returned as-is.
+      #
+      # @param record [Object] the record value to normalize
+      # @return [Object, nil] the normalized record
+      # @see Mongory::KEY_NOT_FOUND
+      def normalize(record)
+        record == KEY_NOT_FOUND ? nil : record
+      end
+
+      # Formats a debug string for match output.
+      # Uses ANSI escape codes to highlight matched vs. mismatched records.
+      #
+      # @param record [Object] the record being tested
+      # @param result [Boolean] whether the match succeeded
+      # @return [String] the formatted output string
+      def debug_display(record, result)
+        "#{self.class.name.split('::').last} #{colored_result(result)}, " \
+          "condition: #{@condition.inspect}, " \
+          "record: #{record.inspect}"
+      end
+
+      def colored_result(result)
+        if result.is_a?(Exception)
+          "\e[45;97m#{result}\e[0m"
+        elsif result
+          "\e[30;42mMatched\e[0m"
+        else
+          "\e[30;41mDismatch\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/mongory/matchers/abstract_multi_matcher.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # AbstractMultiMatcher is an abstract base class for matchers that operate
+    # on multiple subconditions. It provides a generic match loop that applies
+    # a logical operator (e.g., `all?`, `any?`) over a list of sub-matchers.
+    #
+    # Subclasses must define two methods:
+    #   - `#build_sub_matcher`: how to construct a matcher from each condition
+    #   - `#operator`: which enumerator method to use (e.g., :all?, :any?)
+    #
+    # Sub-matchers are cached using `define_instance_cache_method` to prevent
+    # repeated construction.
+    #
+    # @abstract
+    # @see AbstractMatcher
+    class AbstractMultiMatcher < AbstractMatcher
+      # Enables auto-unwrap logic.
+      # When used, `.build` may unwrap to first matcher if only one is present.
+      #
+      # @private
+      # @return [void]
+      def self.enable_unwrap!
+        @enable_unwrap = true
+        singleton_class.alias_method :build, :build_or_unwrap
+      end
+
+      private_class_method :enable_unwrap!
+
+      # Builds a matcher and conditionally unwraps it.
+      #
+      # @param args [Array] arguments passed to the constructor
+      # @return [AbstractMatcher]
+      def self.build_or_unwrap(*args)
+        matcher = new(*args)
+        return matcher unless @enable_unwrap
+
+        matcher = matcher.matchers.first if matcher.matchers.count == 1
+        matcher
+      end
+
+      # Performs matching over all sub-matchers using the specified operator.
+      # The input record may be preprocessed first (e.g., for normalization).
+      #
+      # @param record [Object] the record to match
+      # @return [Boolean] whether the combined result of sub-matchers satisfies the condition
+      def match(record)
+        record = preprocess(record)
+        matchers.send(operator) do |matcher|
+          matcher.match?(record)
+        end
+      end
+
+      # Lazily builds and caches the array of sub-matchers.
+      # Subclasses provide the implementation of `#build_sub_matcher`.
+      # Duplicate matchers (by uniq_key) are removed to avoid redundancy.
+      #
+      # @return [Array<AbstractMatcher>] list of sub-matchers
+      define_instance_cache_method(:matchers) do
+        @condition.map(&method(:build_sub_matcher)).uniq(&:uniq_key)
+      end
+
+      # Optional hook for subclasses to transform the input record before matching.
+      # Default implementation returns the record unchanged.
+      #
+      # @param record [Object] the input record
+      # @return [Object] the transformed or original record
+      def preprocess(record)
+        record
+      end
+
+      # Abstract method to define how each subcondition should be turned into a matcher.
+      #
+      # @param args [Array] the inputs needed to construct a matcher
+      # @return [AbstractMatcher] a matcher instance for the subcondition
+      def build_sub_matcher(*args); end
+
+      # Abstract method to specify the combining operator for sub-matchers.
+      # Must return a valid enumerable method name (e.g., :all?, :any?).
+      #
+      # @return [Symbol] the operator method to apply over matchers
+      def operator; end
+
+      # Recursively checks all submatchers for validity.
+      #
+      # @return [void]
+      def check_validity!
+        matchers.each(&:check_validity!)
+      end
+
+      # Overrides base render_tree to recursively print all submatchers.
+      # Each child matcher will be displayed under this multi-matcher node.
+      #
+      # @param prefix [String] current line prefix for tree alignment
+      # @param is_last [Boolean] whether this node is the last sibling
+      # @return [void]
+      def render_tree(prefix = '', is_last: true)
+        super
+
+        new_prefix = "#{prefix}#{is_last ? '   ' : '│  '}"
+        last_index = matchers.count - 1
+        matchers.each_with_index do |matcher, index|
+          matcher.render_tree(new_prefix, is_last: index == last_index)
+        end
+      end
+    end
+  end
+end

data/lib/mongory/matchers/abstract_operator_matcher.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # AbstractOperatorMatcher is a base class for matchers that apply a binary
+    # operator (e.g., `==`, `<`, `>` etc.) between the record and the condition.
+    #
+    # This class assumes that the match logic consists of:
+    #   preprocess(record).send(operator, condition)
+    # and provides a fallback behavior for invalid comparisons.
+    #
+    # Subclasses must implement `#operator` and may override `#preprocess`
+    # to normalize or cast the record before comparison.
+    #
+    # @abstract
+    # @see AbstractMatcher
+    class AbstractOperatorMatcher < AbstractMatcher
+      # A list of Boolean values used for type guarding in some subclasses.
+      BOOLEAN_VALUES = [true, false].freeze
+
+      # Applies the binary operator to the preprocessed record and condition.
+      # If an error is raised (e.g., undefined comparison), the match fails.
+      #
+      # @param record [Object] the input record to test
+      # @return [Boolean] the result of record <operator> condition
+      def match(record)
+        preprocess(record).send(operator, @condition)
+      end
+
+      # Hook for subclasses to transform the record before comparison.
+      # Default behavior normalizes KEY_NOT_FOUND to nil.
+      #
+      # @param record [Object] the raw record value
+      # @return [Object] the transformed value
+      def preprocess(record)
+        normalize(record)
+      end
+
+      # Returns the Ruby operator symbol to be used in comparison.
+      # Must be implemented by subclasses (e.g., :==, :<, :>=)
+      #
+      # @return [Symbol] the comparison operator
+      def operator; end
+    end
+  end
+end

data/lib/mongory/matchers/and_matcher.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # AndMatcher implements the `$and` logical operator.
+    #
+    # It evaluates an array of subconditions and returns true only if *all* of them match.
+    #
+    # Unlike other matchers, AndMatcher flattens the underlying matcher tree by
+    # delegating each subcondition to a `HashConditionMatcher`, and further extracting
+    # all inner matchers. Duplicate matchers are deduplicated by `uniq_key`.
+    #
+    # This allows the matcher trace (`.explain`) to render as a flat list of independent conditions.
+    #
+    # @example
+    #   matcher = AndMatcher.build([
+    #     { age: { :$gte => 18 } },
+    #     { name: /foo/ }
+    #   ])
+    #   matcher.match?(record) #=> true if both match
+    #
+    # @see AbstractMultiMatcher
+    class AndMatcher < AbstractMultiMatcher
+      # Constructs a HashConditionMatcher for each subcondition.
+      # Conversion is disabled to avoid double-processing.
+      enable_unwrap!
+
+      # Returns the flattened list of all matchers from each subcondition.
+      #
+      # Each condition is passed to a HashConditionMatcher, then recursively flattened.
+      # All matchers are then deduplicated using `uniq_key`.
+      #
+      # @return [Array<AbstractMatcher>]
+      # @see AbstractMatcher#uniq_key
+      define_instance_cache_method(:matchers) do
+        @condition.flat_map do |condition|
+          HashConditionMatcher.new(condition).matchers
+        end.uniq(&:uniq_key)
+      end
+
+      # Combines submatcher results using `:all?`.
+      #
+      # @return [Symbol]
+      def operator
+        :all?
+      end
+
+      # Ensures the condition is an array of hashes.
+      #
+      # @raise [Mongory::TypeError] if not valid
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$and needs an array' unless @condition.is_a?(Array)
+
+        @condition.each do |sub_condition|
+          raise TypeError, '$and needs an array of hash' unless sub_condition.is_a?(Hash)
+        end
+
+        super
+      end
+    end
+
+    register(:and, '$and', AndMatcher)
+  end
+end

data/lib/mongory/matchers/array_record_matcher.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # ArrayRecordMatcher matches records where the record itself is an Array.
+    #
+    # This matcher checks whether any element of the record array satisfies the expected condition.
+    # It is typically used when the record is a collection of values, and the query condition
+    # is either a scalar value or a subcondition matcher.
+    #
+    # @example Match when any element equals the expected value
+    #   matcher = ArrayRecordMatcher.build(42)
+    #   matcher.match?([10, 42, 99])    #=> true
+    #
+    # @example Match using a nested matcher (e.g. condition is a hash)
+    #   matcher = ArrayRecordMatcher.build({ '$gt' => 10 })
+    #   matcher.match?([5, 20, 3])      #=> true
+    #
+    # This matcher is automatically invoked by LiteralMatcher when the record value is an array.
+    #
+    # @note This is distinct from `$in` or `$nin`, where the **condition** is an array.
+    #       Here, the **record** is the array being matched against.
+    #
+    # @see Mongory::Matchers::InMatcher
+    # @see Mongory::Matchers::LiteralMatcher
+    class ArrayRecordMatcher < AbstractMultiMatcher
+      enable_unwrap!
+      # Builds an array of matchers to evaluate the given condition against an array record.
+      #
+      # This method returns multiple matchers that will be evaluated using `:any?` logic:
+      # - An equality matcher for exact array match
+      # - A hash condition matcher if the condition is a hash
+      # - An `$elemMatch` matcher for element-wise comparison
+      #
+      # @return [Array<Mongory::Matchers::AbstractMatcher>] an array of matcher instances
+      define_instance_cache_method(:matchers) do
+        result = []
+        result << EqMatcher.build(@condition) if @condition.is_a?(Array)
+        result << case @condition
+                  when Hash
+                    HashConditionMatcher.build(parsed_condition)
+                  when Regexp
+                    ElemMatchMatcher.build('$regex' => @condition)
+                  else
+                    ElemMatchMatcher.build('$eq' => @condition)
+                  end
+        result
+      end
+
+      # Combines results using `:any?` for multi-match logic.
+      #
+      # @return [Symbol]
+      def operator
+        :any?
+      end
+
+      private
+
+      # Parses the original condition hash into a normalized structure suitable for HashConditionMatcher.
+      #
+      # This method classifies keys in the condition hash as:
+      # - Numeric (integers or numeric strings): treated as index-based field matchers
+      # - Operator keys (e.g., `$size`, `$type`): retained at the top level
+      # - All other keys: grouped under a `$elemMatch` clause for element-wise comparison
+      #
+      # @return [Hash] a normalized condition hash, potentially containing `$elemMatch`
+      def parsed_condition
+        h_parsed = {}
+        h_elem_match = {}
+        @condition.each_pair do |key, value|
+          case key
+          when Integer, /^-?\d+$/
+            h_parsed[key.to_i] = value
+          when '$elemMatch'
+            h_elem_match.merge!(value)
+          when *Matchers.operators
+            h_parsed[key] = value
+          else
+            h_elem_match[key] = value
+          end
+        end
+
+        h_parsed['$elemMatch'] = h_elem_match if is_present?(h_elem_match)
+        h_parsed
+      end
+    end
+  end
+end

data/lib/mongory/matchers/elem_match_matcher.rb

@@ -0,0 +1,47 @@
+# 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
+      # Matches true if any element in the array satisfies the condition.
+      # Falls back to false if the input is not an array.
+
+      # @param collection [Object] the input to be tested
+      # @return [Boolean] whether any element matches
+      def match(collection)
+        return false unless collection.is_a?(Array)
+
+        collection.any? do |record|
+          super(Mongory.data_converter.convert(record))
+        end
+      end
+
+      # Ensures the condition is a Hash.
+      #
+      # @raise [Mongory::TypeError] if the condition is not a Hash
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$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,37 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # EqMatcher matches values using the equality operator `==`.
+    #
+    # It inherits from AbstractOperatorMatcher 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 AbstractOperatorMatcher
+    class EqMatcher < AbstractOperatorMatcher
+      # Returns the Ruby equality operator to be used in matching.
+      #
+      # @return [Symbol] the equality operator symbol
+      def operator
+        :==
+      end
+    end
+
+    register(:eq, '$eq', EqMatcher)
+  end
+end

data/lib/mongory/matchers/every_matcher.rb

@@ -0,0 +1,41 @@
+# 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
+      # Matches true if all element in the array satisfies the condition.
+      # Falls back to false if the input is not an array.
+
+      # @param collection [Object] the input to be tested
+      # @return [Boolean] whether all element matches
+      def match(collection)
+        return false unless collection.is_a?(Array)
+        return false if collection.empty?
+
+        collection.all? do |record|
+          super(Mongory.data_converter.convert(record))
+        end
+      end
+
+      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,48 @@
+# 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 AbstractOperatorMatcher
+    class ExistsMatcher < AbstractOperatorMatcher
+      # Converts the raw record value into a boolean indicating presence.
+      #
+      # @param record [Object] the value associated with the field
+      # @return [Boolean] true if the key exists, false otherwise
+      def preprocess(record)
+        record != KEY_NOT_FOUND
+      end
+
+      # Uses Ruby's equality operator to compare presence against expected boolean.
+      #
+      # @return [Symbol] the comparison operator
+      def operator
+        :==
+      end
+
+      # Ensures that the condition value is a valid boolean.
+      #
+      # @raise [TypeError] if condition is not true or false
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$exists needs a boolean' unless BOOLEAN_VALUES.include?(@condition)
+      end
+    end
+
+    register(:exists, '$exists', ExistsMatcher)
+  end
+end