mongory 0.7.3-aarch64-linux

data/lib/mongory/matchers/lt_matcher.rb

@@ -0,0 +1,41 @@
+# 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 AbstractMatcher and uses the `<` operator.
+    #
+    # @example
+    #   matcher = LtMatcher.build(10)
+    #   matcher.match?(9)    #=> true
+    #   matcher.match?(10)   #=> false
+    #   matcher.match?(11)   #=> false
+    #
+    # @see AbstractMatcher
+    class LtMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the less-than comparison.
+      # The Proc uses the `<` operator to compare values.
+      #
+      # @return [Proc] A proc that performs less-than comparison with error handling
+      # @note The proc includes error handling for invalid comparisons
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record < condition
+        rescue StandardError
+          false
+        end
+      end
+
+      def priority
+        3
+      end
+    end
+
+    register(:lt, '$lt', LtMatcher)
+  end
+end

data/lib/mongory/matchers/lte_matcher.rb

@@ -0,0 +1,41 @@
+# 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 AbstractMatcher and uses the `<=` operator.
+    #
+    # @example
+    #   matcher = LteMatcher.build(10)
+    #   matcher.match?(9)    #=> true
+    #   matcher.match?(10)   #=> true
+    #   matcher.match?(11)   #=> false
+    #
+    # @see AbstractMatcher
+    class LteMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the less-than-or-equal comparison.
+      # The Proc uses the `<=` operator to compare values.
+      #
+      # @return [Proc] A proc that performs less-than-or-equal comparison with error handling
+      # @note The proc includes error handling for invalid comparisons
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record <= condition
+        rescue StandardError
+          false
+        end
+      end
+
+      def priority
+        3
+      end
+    end
+
+    register(:lte, '$lte', LteMatcher)
+  end
+end

data/lib/mongory/matchers/ne_matcher.rb

@@ -0,0 +1,38 @@
+# 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 AbstractMatcher
+    # and uses Ruby's `!=` operator for comparison.
+    #
+    # @example
+    #   matcher = NeMatcher.build(42)
+    #   matcher.match?(41)  #=> true
+    #   matcher.match?(42)  #=> false
+    #
+    # @see AbstractMatcher
+    class NeMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the not-equal comparison.
+      # The Proc uses the `!=` operator to compare values.
+      #
+      # @return [Proc] A proc that performs not-equal comparison
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record != condition
+        end
+      end
+
+      def priority
+        1
+      end
+    end
+
+    register(:ne, '$ne', NeMatcher)
+  end
+end

data/lib/mongory/matchers/nin_matcher.rb

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

data/lib/mongory/matchers/not_matcher.rb

@@ -0,0 +1,40 @@
+# 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
+      # Creates a raw Proc that performs the not-matching operation.
+      # The Proc inverts the result of the wrapped matcher.
+      #
+      # @return [Proc] A proc that performs not-matching
+      def raw_proc
+        super_proc = super
+
+        Proc.new do |record|
+          !super_proc.call(record)
+        end
+      end
+
+      def priority
+        1 + super
+      end
+    end
+
+    register(:not, '$not', NotMatcher)
+  end
+end

data/lib/mongory/matchers/or_matcher.rb

@@ -0,0 +1,68 @@
+# 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. For empty conditions, it returns false
+    # (using FALSE_PROC).
+    #
+    # Each subcondition is handled by a HashConditionMatcher with conversion disabled,
+    # since the parent matcher already manages data conversion.
+    #
+    # 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
+    #
+    # @example Empty conditions
+    #   matcher = OrMatcher.build([])
+    #   matcher.match?(record) #=> false (uses FALSE_PROC)
+    #
+    # @see AbstractMultiMatcher
+    class OrMatcher < AbstractMultiMatcher
+      enable_unwrap!
+
+      # Creates a raw Proc that performs the or-matching operation.
+      # The Proc combines all submatcher Procs and returns true if any match.
+      # For empty conditions, returns FALSE_PROC.
+      #
+      # @return [Proc] a Proc that performs the or-matching operation
+      def raw_proc
+        combine_procs_with_or(*matchers.map(&:to_proc))
+      end
+
+      # Builds an array of matchers from the subconditions.
+      # Each subcondition is wrapped in a HashConditionMatcher.
+      #
+      # @return [Array<AbstractMatcher>] array of submatchers
+      define_instance_cache_method(:matchers) do
+        @condition.map do |condition|
+          HashConditionMatcher.build(condition, context: @context)
+        end.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, '$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

data/lib/mongory/matchers/present_matcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # PresentMatcher implements the `$present` operator.
+    #
+    # It returns true if the record value is considered "present"
+    # (i.e., not nil, not empty, not KEY_NOT_FOUND), and matches
+    # the expected boolean condition.
+    #
+    # This is similar to `$exists`, but evaluates truthiness
+    # of the value instead of mere existence.
+    #
+    # @example
+    #   matcher = PresentMatcher.build(true)
+    #   matcher.match?('hello')     #=> true
+    #   matcher.match?(nil)         #=> false
+    #   matcher.match?([])          #=> false
+    #
+    #   matcher = PresentMatcher.build(false)
+    #   matcher.match?(nil)         #=> true
+    #
+    # @see AbstractMatcher
+    class PresentMatcher < AbstractMatcher
+      # Creates a raw Proc that performs the presence check.
+      # The Proc checks if the record's presence matches the condition.
+      #
+      # @return [Proc] A proc that performs presence check
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          record = nil if record == KEY_NOT_FOUND
+          is_present?(record) == condition
+        end
+      end
+
+      def priority
+        2
+      end
+
+      # Ensures that the condition value is a boolean.
+      #
+      # @raise [TypeError] if condition is not true or false
+      # @return [void]
+      def check_validity!
+        return if [true, false].include?(@condition)
+
+        raise TypeError, '$present needs a boolean'
+      end
+    end
+
+    register(:present, '$present', PresentMatcher)
+  end
+end

data/lib/mongory/matchers/regex_matcher.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Matchers
+    # RegexMatcher implements the `$regex` operator and also handles raw Regexp values.
+    #
+    # This matcher checks whether a string record matches a regular expression.
+    # It supports both:
+    # - Explicit queries using `:field.regex => /pattern/i`
+    # - Implicit literal Regexp values like `{ field: /pattern/i }`
+    #
+    # If a string is provided instead of a Regexp, it will be converted via `Regexp.new(...)`.
+    # This ensures consistent behavior for queries like `:field.regex => "foo"` and `:field.regex => /foo/`.
+    #
+    # @example Basic regex matching
+    #   matcher = RegexMatcher.build(/^foo/)
+    #   matcher.match?('foobar')   #=> true
+    #   matcher.match?('barfoo')   #=> false
+    #
+    # @example Case-insensitive matching
+    #   matcher = RegexMatcher.build(/admin/i)
+    #   matcher.match?("ADMIN")    #=> true
+    #
+    # @example String pattern
+    #   matcher = RegexMatcher.build("^foo")
+    #   matcher.match?("foobar")   #=> true
+    #
+    # @example Non-string input
+    #   matcher = RegexMatcher.build(/\d+/)
+    #   matcher.match?(123)        #=> false (not a string)
+    #
+    # @see AbstractMatcher
+    class RegexMatcher < AbstractMatcher
+      # Initializes the matcher with a regex pattern.
+      # Converts string patterns to Regexp objects.
+      #
+      # @param condition [String, Regexp] the regex pattern to match against
+      # @param context [Context] the query context
+      # @raise [TypeError] if condition is not a string or Regexp
+      def initialize(condition, context: Context.new)
+        super
+        @condition = Regexp.new(condition) if condition.is_a?(String)
+      end
+
+      # Creates a raw Proc that performs the regex matching operation.
+      # The Proc checks if the record is a string that matches the pattern.
+      # Returns false for non-string inputs or if the match fails.
+      #
+      # @return [Proc] a Proc that performs regex matching
+      def raw_proc
+        condition = @condition
+
+        Proc.new do |record|
+          next false unless record.is_a?(String)
+
+          record.match?(condition)
+        rescue StandardError
+          false
+        end
+      end
+
+      def priority
+        @condition.source.start_with?('^') ? 8 : 20
+      end
+
+      # Ensures the condition is a valid regex pattern (Regexp or String).
+      #
+      # @raise [TypeError] if condition is not a string or Regexp
+      # @return [void]
+      def check_validity!
+        return if @condition.is_a?(Regexp)
+        return if @condition.is_a?(String)
+
+        raise TypeError, '$regex needs a Regexp or string'
+      end
+    end
+
+    register(:regex, '$regex', RegexMatcher)
+  end
+end

data/lib/mongory/matchers/size_matcher.rb

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

data/lib/mongory/matchers.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Mongory
+  # Provides matcher registration and operator-to-class lookup for query evaluation.
+  #
+  # This module is responsible for:
+  # - Mapping Mongo-style operators like "$gt" to matcher classes
+  # - Dynamically extending Symbol with query operator snippets (e.g., :age.gt)
+  # - Safely isolating symbol extension behind an explicit opt-in flag
+  #
+  # Matchers are registered using `Matchers.registry(method_sym, operator, klass)`
+  # and can be looked up via `Matchers.lookup(operator)`.
+  #
+  # Symbol snippets are only enabled if `Matchers.enable_symbol_snippets!` is called,
+  # preventing namespace pollution unless explicitly requested.
+  module Matchers
+    @operator_mapping = {}
+    @registries = []
+
+    # Registers a matcher class for a given operator and method symbol.
+    #
+    # @param method_sym [Symbol] the method name to be added to Symbol (e.g., :gt)
+    # @param operator [String] the Mongo-style operator (e.g., "$gt")
+    # @param klass [Class] the matcher class to associate with the operator
+    # @return [void]
+    # @raise [ArgumentError] if validations fail
+    def self.register(method_sym, operator, klass)
+      Validator.validate_method(method_sym)
+      Validator.validate_operator(operator)
+      Validator.validate_class(klass)
+
+      @operator_mapping[operator] = klass
+      registry = Registry.new(method_sym, operator)
+      @registries << registry
+      return unless @enable_symbol_snippets
+
+      registry.apply!
+    end
+
+    # Enables dynamic symbol snippet generation for registered operators.
+    # This defines methods like `:age.gt => QueryOperator.new(...)`.
+    #
+    # @return [void]
+    def self.enable_symbol_snippets!
+      @enable_symbol_snippets = true
+      @registries.each(&:apply!)
+    end
+
+    # Retrieves the matcher class associated with a Mongo-style operator.
+    #
+    # @param operator [String]
+    # @return [Class, nil] the registered matcher class or nil if not found
+    def self.lookup(operator)
+      @operator_mapping[operator]
+    end
+
+    # Returns all registered operator keys.
+    #
+    # @return [Array<String>]
+    def self.operators
+      @operator_mapping.keys
+    end
+
+    def self.freeze
+      super
+      @operator_mapping.freeze
+      @registries.freeze
+    end
+
+    # @private
+    #
+    # Internal helper module used by `Matchers.registry` to validate matcher registration parameters.
+    #
+    # This includes:
+    # - Ensuring operators are valid Mongo-style strings (e.g., "$gt")
+    # - Verifying matcher class inheritance
+    # - Enforcing naming rules for symbol snippets (e.g., :gt, :not_match)
+    #
+    # These validations protect against incorrect matcher setup and prevent unsafe symbol definitions.
+    #
+    # @see Matchers.registry
+    module Validator
+      # Validates the given operator string.
+      # Ensures it matches the Mongo-style format like "$gt".
+      # Warns on duplicate registration.
+      #
+      # @param operator [String]
+      # @return [void]
+      # @raise [Mongory::TypeError] if operator format is invalid
+      def self.validate_operator(operator)
+        if Matchers.lookup(operator)
+          warn "Duplicate operator registration: #{operator} (#{Matchers.lookup(operator)} vs #{klass})"
+        end
+
+        return if operator.is_a?(String) && operator.match?(/^\$[a-z]+([A-Z][a-z]+)*$/)
+
+        raise Mongory::TypeError, "Operator must match /^\$[a-z]+([A-Z][a-z]*)*$/, but got #{operator.inspect}"
+      end
+
+      # Validates the matcher class to ensure it is a subclass of AbstractMatcher.
+      #
+      # @param klass [Class]
+      # @return [void]
+      # @raise [Mongory::TypeError] if class is not valid
+      def self.validate_class(klass)
+        return if klass.is_a?(Class) && klass < AbstractMatcher
+
+        raise Mongory::TypeError, "Matcher class must be a subclass of AbstractMatcher, but got #{klass}"
+      end
+
+      # Validates the method symbol to ensure it is a valid lowercase underscore symbol (e.g., :gt, :not_match).
+      #
+      # @param method_sym [Symbol]
+      # @return [void]
+      # @raise [Mongory::TypeError] if symbol format is invalid
+      def self.validate_method(method_sym)
+        return if method_sym.is_a?(Symbol) && method_sym.match?(/^([a-z]+_)*[a-z]+$/)
+
+        raise Mongory::TypeError, "Method symbol must match /^([a-z]+_)*[a-z]+$/, but got #{method_sym.inspect}"
+      end
+    end
+
+    # @private
+    #
+    # Internal helper representing a registration of an operator and its associated symbol snippet method.
+    # Used to delay method definition on Symbol until explicitly enabled.
+    #
+    # Each instance holds:
+    # - the method symbol (e.g., `:gt`)
+    # - the corresponding Mongo-style operator (e.g., `"$gt"`)
+    #
+    # These instances are collected and replayed upon calling `Matchers.enable_symbol_snippets!`.
+    #
+    # @!attribute method_sym
+    #   @return [Symbol] the symbol method name (e.g., :in, :gt, :exists)
+    # @!attribute operator
+    #   @return [String] the Mongo-style operator this snippet maps to (e.g., "$in")
+    Registry = Struct.new(:method_sym, :operator) do
+      # Defines a method on Symbol to support operator snippet expansion.
+      #
+      # @return [void]
+      def apply!
+        return if Symbol.method_defined?(method_sym)
+
+        operator = operator()
+        Symbol.define_method(method_sym) do
+          Mongory::QueryOperator.new(to_s, operator)
+        end
+      end
+    end
+  end
+end
+
+require_relative 'matchers/abstract_matcher'
+require_relative 'matchers/abstract_multi_matcher'
+require_relative 'matchers/literal_matcher'
+require_relative 'matchers/hash_condition_matcher'
+require_relative 'matchers/and_matcher'
+require_relative 'matchers/array_record_matcher'
+require_relative 'matchers/elem_match_matcher'
+require_relative 'matchers/every_matcher'
+require_relative 'matchers/eq_matcher'
+require_relative 'matchers/exists_matcher'
+require_relative 'matchers/gt_matcher'
+require_relative 'matchers/gte_matcher'
+require_relative 'matchers/in_matcher'
+require_relative 'matchers/field_matcher'
+require_relative 'matchers/lt_matcher'
+require_relative 'matchers/lte_matcher'
+require_relative 'matchers/ne_matcher'
+require_relative 'matchers/nin_matcher'
+require_relative 'matchers/not_matcher'
+require_relative 'matchers/or_matcher'
+require_relative 'matchers/present_matcher'
+require_relative 'matchers/regex_matcher'
+require_relative 'matchers/size_matcher'

data/lib/mongory/mongoid.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mongory
+  # Only loaded when Mongoid is present
+  module MongoidPatch
+    # Regist Mongoid operator key object into KeyConverter
+    # @see Converters::KeyConverter
+    # @return [void]
+    def self.patch!
+      kc = Mongory::Converters::KeyConverter.instance
+      # It's Mongoid built-in key operator that born from `:key.gt`
+      kc.register(::Mongoid::Criteria::Queryable::Key) do |v|
+        kc.convert(@name.to_s, @operator => v)
+      end
+    end
+
+    patch!
+  end
+end