mongory 0.7.3-aarch64-linux-musl

data/lib/mongory/converters/key_converter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # KeyConverter handles transformation of field keys in query conditions.
+    # It normalizes symbol keys into string paths, splits dotted keys,
+    # and delegates to the appropriate converter logic.
+    #
+    # This class inherits from AbstractConverter and provides specialized
+    # handling for different key types:
+    # - String keys with dots are split into nested paths
+    # - Symbol keys are converted to strings
+    # - QueryOperator instances are handled via their DSL hooks
+    # - Other types fall back to the parent converter
+    #
+    # Used by ConditionConverter to build query structures from flat input.
+    #
+    # - `"a.b.c" => v` becomes `{ "a" => { "b" => { "c" => v } } }`
+    # - Symbols are stringified and delegated to String logic
+    # - QueryOperator dispatches to internal DSL hook
+    #
+    # @example Convert a dotted string key
+    #   KeyConverter.instance.convert("user.name", "John")
+    #   # => { "user" => { "name" => "John" } }
+    #
+    # @example Convert a symbol key
+    #   KeyConverter.instance.convert(:status, "active")
+    #   # => { "status" => "active" }
+    #
+    # @see AbstractConverter
+    class KeyConverter < AbstractConverter
+      alias_method :super_convert, :convert
+
+      # Converts a key into its normalized form based on its type.
+      # Handles strings, symbols, and QueryOperator instances.
+      # Falls back to parent converter for other types.
+      #
+      # @param target [Object] the key to convert
+      # @param other [Object] the value associated with the key
+      # @return [Hash] the converted key-value pair
+      def convert(target, other)
+        case target
+        when String
+          convert_string_key(target, other)
+        when Symbol
+          convert_string_key(target.to_s, other)
+        when QueryOperator
+          # Handle special case for QueryOperator
+          convert_string_key(*target.__expr_part__(other).first)
+        else
+          super_convert(target, other)
+        end
+      end
+
+      def fallback(target, other)
+        { target => other }
+      end
+
+      # Converts a dotted string key into nested hash form.
+      # Splits the key on dots and builds a nested structure.
+      # Handles escaped dots in the key.
+      #
+      # @param key [String] the dotted key string, e.g. "a.b.c"
+      # @param value [Object] the value to assign at the deepest level
+      # @return [Hash] nested hash structure
+      def convert_string_key(key, value)
+        ret = {}
+        *sub_keys, last_key = key.split(/(?<!\\)\./)
+        last_hash = sub_keys.reduce(ret) do |res, sub_key|
+          next_res = res[normalize_key(sub_key)] = {}
+          next_res
+        end
+        last_hash[normalize_key(last_key)] = value
+        ret
+      end
+
+      # Normalizes a key by unescaping escaped dots.
+      # This allows for literal dots in field names.
+      #
+      # @param key [String] the key to normalize
+      # @return [String] the normalized key
+      def normalize_key(key)
+        key.gsub(/\\\./, '.')
+      end
+    end
+  end
+end

data/lib/mongory/converters/value_converter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # ValueConverter transforms query values into a standardized form.
+    # It handles arrays, hashes, regex, and basic types, and delegates
+    # fallback logic to DataConverter.
+    # Used by ConditionConverter to prepare values in nested queries.
+    #
+    # - Arrays are recursively converted
+    # - Hashes are interpreted as nested conditions
+    # - Regex becomes a Mongo-style `$regex` hash
+    # - Strings and Integers are passed through
+    # - Everything else falls back to DataConverter
+    #
+    # @example Convert a regex
+    #   ValueConverter.instance.convert(/foo/) #=> { "$regex" => "foo" }
+    #
+    class ValueConverter < AbstractConverter
+      alias_method :super_convert, :convert
+
+      # Converts a value into its standardized form based on its type.
+      # Handles arrays, hashes, regex, and basic types.
+      #
+      # @param target [Object] the value to convert
+      # @return [Object] the converted value
+      def convert(target)
+        case target
+        when String, Integer, Regexp, Converted
+          target
+        when Array
+          Converted::Array.new(target.map { |x| convert(x) })
+        when Hash
+          condition_converter.convert(target)
+        else
+          super_convert(target)
+        end
+      end
+
+      def fallback(target, *)
+        Mongory.data_converter.convert(target)
+      end
+
+      # Returns the condition converter instance.
+      #
+      # @return [ConditionConverter] the condition converter instance
+      def condition_converter
+        @condition_converter ||= Mongory.condition_converter
+      end
+    end
+  end
+end

data/lib/mongory/converters.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'converters/abstract_converter'
+require_relative 'converters/condition_converter'
+require_relative 'converters/data_converter'
+require_relative 'converters/key_converter'
+require_relative 'converters/value_converter'
+require_relative 'converters/converted'

data/lib/mongory/matchers/abstract_matcher.rb

@@ -0,0 +1,219 @@
+# 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.
+    #
+    # Each matcher is responsible for evaluating a specific type of condition against
+    # a record value. The base class provides infrastructure for:
+    # - Condition validation
+    # - Value conversion
+    # - Debug output
+    # - Proc caching
+    #
+    # @abstract Subclasses must implement {#match} to define their matching logic
+    #
+    # @example Basic matcher implementation
+    #   class MyMatcher < AbstractMatcher
+    #     def match(record)
+    #       record == @condition
+    #     end
+    #   end
+    #
+    # @example Using a matcher
+    #   matcher = MyMatcher.build(42)
+    #   matcher.match?(42)  #=> true
+    #   matcher.match?(43)  #=> false
+    #
+    # @see Mongory::Matchers for the full list of available matchers
+    class AbstractMatcher
+      include Utils
+
+      singleton_class.alias_method :build, :new
+
+      # Sentinel value used to represent missing keys when traversing nested hashes.
+      # This is used instead of nil to distinguish between missing keys and nil values.
+      #
+      # @api private
+      KEY_NOT_FOUND = SingletonBuilder.new('KEY_NOT_FOUND')
+
+      # Defines a lazily-evaluated matcher accessor with instance-level caching.
+      # This is used to create cached accessors for submatcher instances.
+      #
+      # @param name [Symbol] the name of the matcher (e.g., :collection)
+      # @yield the block that constructs the matcher instance
+      # @return [void]
+      # @example
+      #   define_matcher(:array_matcher) do
+      #     ArrayMatcher.build(@condition)
+      #   end
+      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 [Context] the query context containing configuration and current record
+      attr_reader :context
+
+      # Returns a unique key representing this matcher instance.
+      # Used for deduplication in multi-matchers.
+      #
+      # @return [String] a unique key for this matcher instance
+      # @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
+      # @param context [Context] the query context containing configuration
+      def initialize(condition, context: Context.new)
+        @condition = condition
+        @context = context
+
+        check_validity!
+      end
+
+      # Matches the given record against the condition.
+      # This method handles error cases and uses the cached proc for performance.
+      #
+      # @param record [Object] the input record
+      # @return [Boolean] whether the record matches the condition
+      def match?(record)
+        to_proc.call(record)
+      rescue StandardError
+        false
+      end
+
+      # Converts the matcher into a Proc that can be used for matching.
+      # The Proc is cached for better performance.
+      #
+      # @return [Proc] a Proc that can be used to match records
+      def cached_proc
+        @cached_proc ||= raw_proc
+      end
+
+      alias_method :to_proc, :cached_proc
+
+      # Creates a debug-enabled version of the matcher proc.
+      # This version includes tracing and error handling.
+      #
+      # @return [Proc] a debug-enabled version of the matcher proc
+      def debug_proc
+        return @debug_proc if defined?(@debug_proc)
+
+        raw_proc = raw_proc()
+        @debug_proc = Proc.new do |record|
+          result = nil
+
+          Debugger.instance.with_indent do
+            result = begin
+              raw_proc.call(record)
+            rescue StandardError => e
+              e
+            end
+
+            debug_display(record, result)
+          end
+
+          result.is_a?(Exception) ? false : result
+        end
+      end
+
+      # Creates a raw Proc from the match method.
+      # This is used internally by to_proc and can be overridden by subclasses
+      # to provide custom matching behavior.
+      #
+      # @return [Proc] the raw Proc implementation of the match method
+      def raw_proc
+        method(:match).to_proc
+      end
+
+      # Performs the actual match logic.
+      # Subclasses must override this method.
+      #
+      # @abstract
+      # @param record [Object] the input record to test
+      # @return [Boolean] whether the record matches the condition
+      def match(record); end
+
+      # Validates the condition (no-op by default).
+      # Override in subclasses to raise error if invalid.
+      #
+      # @abstract
+      # @raise [TypeError] if the condition is 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
+
+      def priority
+        20
+      end
+
+      private
+
+      # Returns a single-line string representing this matcher in the tree output.
+      # Format: `<MatcherType>: <condition.inspect>`
+      #
+      # @return [String] a formatted title for tree display
+      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, Exception] whether the match succeeded or an error occurred
+      # @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
+
+      # Formats the match result with ANSI color codes for terminal output.
+      #
+      # @param result [Boolean, Exception] the match result or error
+      # @return [String] the colored result string
+      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,124 @@
+# 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
+      # A Proc that always returns true, used as a default for empty AND conditions
+      # @return [Proc] A proc that always returns true
+      TRUE_PROC = Proc.new { |_| true }
+
+      # A Proc that always returns false, used as a default for empty OR conditions
+      # @return [Proc] A proc that always returns false
+      FALSE_PROC = Proc.new { |_| false }
+
+      # 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.
+      # If unwrapping is enabled and there is only one submatcher,
+      # returns that submatcher instead of the multi-matcher wrapper.
+      #
+      # @param args [Array] arguments passed to the constructor
+      # @param context [Context] the query context
+      # @return [AbstractMatcher] the constructed matcher or its unwrapped submatcher
+      def self.build_or_unwrap(*args, context: Context.new)
+        matcher = new(*args, context: context)
+        return matcher unless @enable_unwrap
+
+        matcher = matcher.matchers.first if matcher.matchers.count == 1
+        matcher
+      end
+
+      # Recursively checks all submatchers for validity.
+      # Raises an error if any submatcher is invalid.
+      #
+      # @raise [Mongory::TypeError] if any submatcher is invalid
+      # @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
+
+      def priority
+        1 + matchers.sum(&:priority)
+      end
+
+      private
+
+      # Recursively combines multiple matcher procs with AND logic.
+      # This method optimizes the combination of multiple matchers by building
+      # a balanced tree of AND operations.
+      #
+      # @param left [Proc] The left matcher proc to combine
+      # @param rest [Array<Proc>] The remaining matcher procs to combine
+      # @return [Proc] A new proc that combines all matchers with AND logic
+      # @example
+      #   combine_procs_with_and(proc1, proc2, proc3)
+      #   #=> proc { |record| proc1.call(record) && proc2.call(record) && proc3.call(record) }
+      def combine_procs_with_and(left = TRUE_PROC, *rest)
+        return left if rest.empty?
+
+        right = combine_procs_with_and(*rest)
+        Proc.new do |record|
+          left.call(record) && right.call(record)
+        end
+      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_with_or(proc1, proc2, proc3)
+      #   #=> proc { |record| proc1.call(record) || proc2.call(record) || proc3.call(record) }
+      def combine_procs_with_or(left = FALSE_PROC, *rest)
+        return left if rest.empty?
+
+        right = combine_procs_with_or(*rest)
+        Proc.new do |record|
+          left.call(record) || right.call(record)
+        end
+      end
+    end
+  end
+end

data/lib/mongory/matchers/and_matcher.rb

@@ -0,0 +1,72 @@
+# 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.
+    # For empty conditions, it returns true (using TRUE_PROC), following MongoDB's behavior.
+    #
+    # 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 Basic usage
+    #   matcher = AndMatcher.build([
+    #     { age: { :$gte => 18 } },
+    #     { name: /foo/ }
+    #   ])
+    #   matcher.match?(record) #=> true if both match
+    #
+    # @example Empty conditions
+    #   matcher = AndMatcher.build([])
+    #   matcher.match?(record) #=> true (uses TRUE_PROC)
+    #
+    # @see AbstractMultiMatcher
+    class AndMatcher < AbstractMultiMatcher
+      # Constructs a HashConditionMatcher for each subcondition.
+      # Conversion is disabled to avoid double-processing.
+      enable_unwrap!
+
+      # Creates a raw Proc that performs the AND operation.
+      # The Proc combines all subcondition Procs and returns true only if all match.
+      # For empty conditions, returns TRUE_PROC.
+      #
+      # @return [Proc] a Proc that performs the AND operation
+      def raw_proc
+        combine_procs_with_and(*matchers.map(&:to_proc))
+      end
+
+      # 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>] A flattened, deduplicated list of matchers
+      # @see AbstractMatcher#uniq_key
+      define_instance_cache_method(:matchers) do
+        @condition.flat_map do |condition|
+          HashConditionMatcher.new(condition, context: @context).matchers
+        end.uniq(&:uniq_key).sort_by(&:priority)
+      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,93 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # ArrayRecordMatcher handles matching against array-type records.
+    #
+    # This matcher is used when a field value is an array and needs to be matched
+    # against a condition. It supports both exact array matching and element-wise
+    # comparison through `$elemMatch`.
+    #
+    # For empty conditions, it returns false (using FALSE_PROC).
+    #
+    # @example Match exact array
+    #   matcher = ArrayRecordMatcher.build([1, 2, 3])
+    #   matcher.match?([1, 2, 3])  #=> true
+    #   matcher.match?([1, 2])     #=> false
+    #
+    # @example Match with hash condition
+    #   matcher = ArrayRecordMatcher.build({ '$gt' => 5 })
+    #   matcher.match?([3, 6, 9])  #=> true (6 and 9 match)
+    #   matcher.match?([1, 2, 3])  #=> false
+    #
+    # @example Empty conditions
+    #   matcher = ArrayRecordMatcher.build([])
+    #   matcher.match?(record) #=> false (uses FALSE_PROC)
+    #
+    # @see AbstractMultiMatcher
+    class ArrayRecordMatcher < AbstractMultiMatcher
+      enable_unwrap!
+
+      # Creates a raw Proc that performs the array matching operation.
+      # The Proc checks if any element in the array matches the condition.
+      # For empty conditions, returns FALSE_PROC.
+      #
+      # @return [Proc] a Proc that performs the array matching operation
+      def raw_proc
+        combine_procs_with_or(*matchers.map(&:to_proc))
+      end
+
+      # 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<AbstractMatcher>] An array of matcher instances
+      define_instance_cache_method(:matchers) do
+        result = []
+        result << EqMatcher.build(@condition, context: @context) if @condition.is_a?(Array)
+        result << case @condition
+                  when Hash
+                    HashConditionMatcher.build(parsed_condition, context: @context)
+                  when Regexp
+                    ElemMatchMatcher.build({ '$regex' => @condition }, context: @context)
+                  else
+                    ElemMatchMatcher.build({ '$eq' => @condition }, context: @context)
+                  end
+        result.sort_by(&:priority)
+      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