mongory 0.3.0

data/lib/mongory/matchers/present_matcher.rb

@@ -0,0 +1,52 @@
+# 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 AbstractOperatorMatcher
+    class PresentMatcher < AbstractOperatorMatcher
+      # Transforms the record into a boolean presence flag
+      # before applying comparison.
+      #
+      # @param record [Object] the original value
+      # @return [Boolean] whether the value is present
+      def preprocess(record)
+        is_present?(super)
+      end
+
+      # Uses Ruby `==` to compare the presence result to the expected boolean.
+      #
+      # @return [Symbol] the equality operator
+      def operator
+        :==
+      end
+
+      # Ensures that the condition value is a boolean.
+      #
+      # @raise [TypeError] if condition is not true or false
+      # @return [void]
+      def check_validity!
+        raise TypeError, '$present needs a boolean' unless BOOLEAN_VALUES.include?(@condition)
+      end
+    end
+
+    register(:present, '$present', PresentMatcher)
+  end
+end

data/lib/mongory/matchers/regex_matcher.rb

@@ -0,0 +1,61 @@
+# 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
+    #   matcher = RegexMatcher.build('^foo')
+    #   matcher.match?('foobar')   #=> true
+    #   matcher.match?('barfoo')   #=> false
+    #
+    # @example Match with explicit regex
+    #   RegexMatcher.build(/admin/i).match?("ADMIN") # => true
+    #
+    # @example Match via LiteralMatcher fallback
+    #   LiteralMatcher.new(/admin/i).match("ADMIN") # => true
+    #
+    # @see LiteralMatcher
+    # @see Mongory::Matchers::AbstractOperatorMatcher
+    class RegexMatcher < AbstractOperatorMatcher
+      # Uses `:match?` as the operator to invoke on the record string.
+      #
+      # @return [Symbol] the match? method symbol
+      def operator
+        :match?
+      end
+
+      # Ensures the record is a string before applying regex.
+      # If not, coerces to empty string to ensure match fails safely.
+      #
+      # @param record [Object] the raw input
+      # @return [String] a safe string to match against
+      def preprocess(record)
+        return '' unless record.is_a?(String)
+
+        record
+      end
+
+      # Ensures the condition is a Regexp (strings are converted during initialization).
+      #
+      # @raise [TypeError] if condition is not a string
+      # @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.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/abstract_operator_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'

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

data/lib/mongory/query_builder.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module Mongory
+  # QueryBuilder provides a Mongo-like in-memory query interface.
+  #
+  # It supports condition chaining (`where`, `or`, `not`),
+  # limiting, and plucking fields.
+  #
+  # Internally it compiles all conditions and invokes `QueryMatcher`.
+  #
+  # @example
+  #   records.mongory
+  #     .where(:age.gte => 18)
+  #     .or({ :name => /J/ }, { :name.eq => 'Bob' })
+  #     .limit(2)
+  #     .to_a
+  class QueryBuilder
+    include ::Enumerable
+    include Utils
+
+    # Initializes a new query builder with the given record set.
+    #
+    # @param records [Enumerable] the collection to query against
+    def initialize(records)
+      @records = records
+      set_matcher
+    end
+
+    # Iterates through all records that match the current matcher.
+    #
+    # @yieldparam record [Object]
+    # @return [Enumerator]
+    def each
+      return to_enum(:each) unless block_given?
+
+      @matcher.prepare_query
+      @records.each do |record|
+        yield record if @matcher.match?(record)
+      end
+    end
+
+    # Adds a condition to filter records using the given condition.
+    #
+    # @param condition [Hash]
+    # @return [QueryBuilder] a new builder instance
+    def where(condition)
+      self.and(condition)
+    end
+
+    # Adds a negated condition to the current query.
+    #
+    # @param condition [Hash]
+    # @return [QueryBuilder]
+    def not(condition)
+      self.and('$not' => condition)
+    end
+
+    # Adds one or more conditions combined with `$and`.
+    #
+    # @param conditions [Array<Hash>]
+    # @return [QueryBuilder]
+    def and(*conditions)
+      dup_instance_exec do
+        add_conditions('$and', conditions)
+      end
+    end
+
+    # Adds one or more conditions combined with `$or`.
+    #
+    # @param conditions [Array<Hash>]
+    # @return [QueryBuilder]
+    def or(*conditions)
+      operator = '$or'
+      dup_instance_exec do
+        if @matcher.condition.each_key.all? { |k| k == operator }
+          add_conditions(operator, conditions)
+        else
+          set_matcher(operator => [@matcher.condition.dup, *conditions])
+        end
+      end
+    end
+
+    # Adds a `$or` query combined inside an `$and` block.
+    # This is a semantic alias for `.and('$or' => [...])`
+    #
+    # @param conditions [Array<Hash>]
+    # @return [QueryBuilder]
+    def any_of(*conditions)
+      self.and('$or' => conditions)
+    end
+
+    def in(condition)
+      self.and(wrap_values_with_key(condition, '$in'))
+    end
+
+    def nin(condition)
+      self.and(wrap_values_with_key(condition, '$nin'))
+    end
+
+    # Limits the number of records returned by the query.
+    #
+    # @param count [Integer]
+    # @return [QueryBuilder]
+    def limit(count)
+      dup_instance_exec do
+        @records = take(count)
+      end
+    end
+
+    # Extracts selected fields from matching records.
+    #
+    # @param field [Symbol, String]
+    # @param fields [Array<Symbol, String>]
+    # @return [Array<Object>, Array<Array<Object>>]
+    def pluck(field, *fields)
+      if fields.empty?
+        map { |record| record[field] }
+      else
+        fields.unshift(field)
+        map { |record| fields.map { |key| record[key] } }
+      end
+    end
+
+    # Returns the raw parsed condition for this query.
+    #
+    # @return [Hash] the raw compiled condition
+    def condition
+      @matcher.condition
+    end
+
+    alias_method :selector, :condition
+
+    # Prints the internal matcher tree structure for the current query.
+    # Will output a human-readable visual tree of matchers.
+    # This is useful for debugging and visualizing complex conditions.
+    #
+    # @return [void]
+    def explain
+      @matcher.match?(@records.first)
+      @matcher.render_tree
+      nil
+    end
+
+    private
+
+    # @private
+    # Duplicates the query and executes the block in context.
+    #
+    # @yieldparam dup [QueryBuilder]
+    # @return [QueryBuilder]
+    def dup_instance_exec(&block)
+      dup.tap do |obj|
+        obj.instance_exec(&block)
+      end
+    end
+
+    # @private
+    # Builds the internal matcher tree from a condition hash.
+    # Used to eagerly parse conditions to improve inspect/debug visibility.
+    #
+    # @param condition [Hash]
+    # @return [void]
+    def set_matcher(condition = {})
+      @matcher = QueryMatcher.new(condition)
+    end
+
+    # @private
+    # Merges additional conditions into the matcher.
+    #
+    # @param key [String, Symbol]
+    # @param conditions [Array<Hash>]
+    def add_conditions(key, conditions)
+      condition_dup = @matcher.condition.dup
+      condition_dup[key] ||= []
+      condition_dup[key] += conditions
+      set_matcher(condition_dup)
+    end
+
+    def wrap_values_with_key(condition, key)
+      condition.transform_values do |sub_condition|
+        { key => sub_condition }
+      end
+    end
+  end
+end

data/lib/mongory/query_matcher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module Mongory
+  # The top-level matcher for compiled query conditions.
+  #
+  # Delegates to {Matchers::LiteralMatcher} after transforming input
+  # via {Converters::ConditionConverter}.
+  #
+  # Typically used internally by `QueryBuilder`.
+  #
+  # Conversion via Mongory.data_converter is applied to the record
+  #
+  # @example
+  #   matcher = QueryMatcher.build({ :age.gte => 18 })
+  #   matcher.match?(record)
+  #
+  # @see Matchers::LiteralMatcher
+  # @see Converters::ConditionConverter
+  class QueryMatcher < Matchers::LiteralMatcher
+    # @param condition [Hash<Symbol, Object>] a query condition using operator-style symbol keys,
+    #   e.g. { :age.gt => 18 }, which will be parsed by `Mongory.condition_converter`.
+    def initialize(condition)
+      super(Mongory.condition_converter.convert(condition))
+    end
+
+    # Matches the given record against the condition.
+    #
+    # @param record [Object] the raw input record (e.g., Hash or model object) to be matched.
+    #   It will be converted internally using `Mongory.data_converter`.
+    # @return [Boolean] whether the record satisfies the condition
+    def match(record)
+      super(Mongory.data_converter.convert(record))
+    end
+
+    # Renders the full matcher tree for the current query.
+    #
+    # This method is intended to be the public entry point for rendering
+    # the matcher tree. It does not accept any arguments and internally
+    # handles rendering via the configured pretty-print logic.
+    #
+    # Subclasses or internal matchers should implement their own
+    # `#render_tree(prefix, is_last:)` for internal recursion.
+    #
+    # @return [void]
+    # @see Matchers::LiteralMatcher#render_tree
+    def render_tree
+      super
+    end
+
+    # Prepares the query for execution by ensuring all necessary matchers are initialized.
+    # This is called before query execution to avoid premature matcher tree construction.
+    #
+    # @return [void]
+    alias_method :prepare_query, :check_validity!
+
+    # Overrides the parent class's check_validity! to prevent premature matcher tree construction.
+    # This matcher does not require validation, so this is a no-op.
+    #
+    # @return [void]
+    def check_validity!
+      # No-op for this matcher
+    end
+  end
+end

data/lib/mongory/query_operator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mongory
+  # Wrapper for symbol-based operator expressions.
+  #
+  # Used to support DSL like `:age.gt => 18` where `gt` maps to `$gt`.
+  # Converts into: `{ "age" => { "$gt" => 18 } }`
+  class QueryOperator
+    # Initializes a new query operator wrapper.
+    #
+    # @param name [String] the original field name
+    # @param operator [String] the Mongo-style operator (e.g., '$gt')
+    def initialize(name, operator)
+      @name = name
+      @operator = operator
+    end
+
+    # Converts the operator and value into a condition hash.
+    #
+    # Typically called by the key converter.
+    #
+    # @param other [Object] the value to match against
+    # @return [Hash] converted query condition
+    def __expr_part__(other, *)
+      Converters::KeyConverter.instance.convert(@name, @operator => other)
+    end
+  end
+end

data/lib/mongory/rails.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails'
+require_relative 'utils/rails_patch'
+
+module Mongory
+  # @see Utils::RailsPatch
+  class Railtie < Rails::Railtie
+    initializer 'mongory.patch_utils' do
+      [Mongory::Utils, *Mongory::Utils.included_classes].each do |klass|
+        klass.prepend(Mongory::Utils::RailsPatch)
+      end
+    end
+  end
+end