mongory 0.3.0 → 0.6.0

data/lib/mongory/matchers/or_matcher.rb

@@ -5,7 +5,8 @@ module Mongory
     # OrMatcher implements the `$or` logical operator.
     #
     # It evaluates an array of subconditions and returns true
-    # if *any one* of them matches.
+    # 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.
@@ -20,24 +21,52 @@ module Mongory
     #   ])
     #   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!
-      # Constructs a HashConditionMatcher for each subcondition.
-      # Conversion is disabled to avoid double-processing.
-
-      # @see HashConditionMatcher
-      # @param condition [Object] a subcondition to be wrapped
-      # @return [HashConditionMatcher] a matcher for this condition
-      def build_sub_matcher(condition)
-        HashConditionMatcher.build(condition)
+
+      # 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
+        return FALSE_PROC if matchers.empty?
+
+        combine_procs(*matchers.map(&:to_proc))
+      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(proc1, proc2, proc3)
+      #   #=> proc { |record| proc1.call(record) || proc2.call(record) || proc3.call(record) }
+      def combine_procs(left, *rest)
+        return left if rest.empty?
+
+        right = combine_procs(*rest)
+        Proc.new do |record|
+          left.call(record) || right.call(record)
+        end
       end
 
-      # Uses `:any?` to return true if any submatcher passes.
+      # Builds an array of matchers from the subconditions.
+      # Each subcondition is wrapped in a HashConditionMatcher.
       #
-      # @return [Symbol] the combining operator
-      def operator
-        :any?
+      # @return [Array<AbstractMatcher>] array of submatchers
+      define_instance_cache_method(:matchers) do
+        @condition.map do |condition|
+          HashConditionMatcher.build(condition, context: @context)
+        end
       end
 
       # Ensures the condition is an array of hashes.

data/lib/mongory/matchers/present_matcher.rb

@@ -20,22 +20,19 @@ module Mongory
     #   matcher = PresentMatcher.build(false)
     #   matcher.match?(nil)         #=> true
     #
-    # @see AbstractOperatorMatcher
-    class PresentMatcher < AbstractOperatorMatcher
-      # Transforms the record into a boolean presence flag
-      # before applying comparison.
+    # @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.
       #
-      # @param record [Object] the original value
-      # @return [Boolean] whether the value is present
-      def preprocess(record)
-        is_present?(super)
-      end
+      # @return [Proc] A proc that performs presence check
+      def raw_proc
+        condition = @condition
 
-      # Uses Ruby `==` to compare the presence result to the expected boolean.
-      #
-      # @return [Symbol] the equality operator
-      def operator
-        :==
+        Proc.new do |record|
+          record = nil if record == KEY_NOT_FOUND
+          is_present?(record) == condition
+        end
       end
 
       # Ensures that the condition value is a boolean.
@@ -43,7 +40,9 @@ module Mongory
       # @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)
+        return if [true, false].include?(@condition)
+
+        raise TypeError, '$present needs a boolean'
       end
     end
 

data/lib/mongory/matchers/regex_matcher.rb

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

data/lib/mongory/matchers.rb

@@ -153,7 +153,6 @@ 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'

data/lib/mongory/query_builder.rb

@@ -10,12 +10,19 @@ module Mongory
   #
   # Internally it compiles all conditions and invokes `QueryMatcher`.
   #
-  # @example
+  # @example Basic query
   #   records.mongory
   #     .where(:age.gte => 18)
   #     .or({ :name => /J/ }, { :name.eq => 'Bob' })
   #     .limit(2)
   #     .to_a
+  #
+  # @example Complex query
+  #   records.mongory
+  #     .where(:status => 'active')
+  #     .not(:age.lt => 18)
+  #     .any_of({ :role => 'admin' }, { :role => 'moderator' })
+  #     .pluck(:name, :email)
   class QueryBuilder
     include ::Enumerable
     include Utils
@@ -23,44 +30,68 @@ module Mongory
     # Initializes a new query builder with the given record set.
     #
     # @param records [Enumerable] the collection to query against
-    def initialize(records)
+    def initialize(records, context: Utils::Context.new)
       @records = records
+      @context = context
       set_matcher
     end
 
     # Iterates through all records that match the current matcher.
+    # Uses the standard matcher implementation.
     #
-    # @yieldparam record [Object]
-    # @return [Enumerator]
+    # @yieldparam record [Object] each matching record
+    # @return [Enumerator] if no block given
+    # @return [void] if block given
     def each
       return to_enum(:each) unless block_given?
 
       @matcher.prepare_query
       @records.each do |record|
+        @context.current_record = record
         yield record if @matcher.match?(record)
       end
     end
 
+    # Iterates through all records that match the current matcher.
+    # Uses a compiled Proc for faster matching.
+    #
+    # @yieldparam record [Object] each matching record
+    # @return [Enumerator] if no block given
+    # @return [void] if block given
+    def fast
+      return to_enum(:fast) unless block_given?
+
+      @context.need_convert = false
+      @matcher.prepare_query
+      matcher_block = @matcher.to_proc
+      @records.each do |record|
+        yield record if matcher_block.call(record)
+      end
+    end
+
     # Adds a condition to filter records using the given condition.
+    # This is an alias for `and`.
     #
-    # @param condition [Hash]
+    # @param condition [Hash] the condition to add
     # @return [QueryBuilder] a new builder instance
     def where(condition)
       self.and(condition)
     end
 
     # Adds a negated condition to the current query.
+    # Wraps the condition in a `$not` operator.
     #
-    # @param condition [Hash]
-    # @return [QueryBuilder]
+    # @param condition [Hash] the condition to negate
+    # @return [QueryBuilder] a new builder instance
     def not(condition)
       self.and('$not' => condition)
     end
 
     # Adds one or more conditions combined with `$and`.
+    # All conditions must match for a record to be included.
     #
-    # @param conditions [Array<Hash>]
-    # @return [QueryBuilder]
+    # @param conditions [Array<Hash>] the conditions to add
+    # @return [QueryBuilder] a new builder instance
     def and(*conditions)
       dup_instance_exec do
         add_conditions('$and', conditions)
@@ -68,9 +99,10 @@ module Mongory
     end
 
     # Adds one or more conditions combined with `$or`.
+    # Any condition can match for a record to be included.
     #
-    # @param conditions [Array<Hash>]
-    # @return [QueryBuilder]
+    # @param conditions [Array<Hash>] the conditions to add
+    # @return [QueryBuilder] a new builder instance
     def or(*conditions)
       operator = '$or'
       dup_instance_exec do
@@ -85,24 +117,34 @@ module Mongory
     # Adds a `$or` query combined inside an `$and` block.
     # This is a semantic alias for `.and('$or' => [...])`
     #
-    # @param conditions [Array<Hash>]
-    # @return [QueryBuilder]
+    # @param conditions [Array<Hash>] the conditions to add
+    # @return [QueryBuilder] a new builder instance
     def any_of(*conditions)
       self.and('$or' => conditions)
     end
 
+    # Adds an `$in` condition to the query.
+    # Matches records where the field value is in the given array.
+    #
+    # @param condition [Hash] the field and values to match
+    # @return [QueryBuilder] a new builder instance
     def in(condition)
       self.and(wrap_values_with_key(condition, '$in'))
     end
 
+    # Adds a `$nin` condition to the query.
+    # Matches records where the field value is not in the given array.
+    #
+    # @param condition [Hash] the field and values to exclude
+    # @return [QueryBuilder] a new builder instance
     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]
+    # @param count [Integer] the maximum number of records to return
+    # @return [QueryBuilder] a new builder instance
     def limit(count)
       dup_instance_exec do
         @records = take(count)
@@ -111,9 +153,10 @@ module Mongory
 
     # Extracts selected fields from matching records.
     #
-    # @param field [Symbol, String]
-    # @param fields [Array<Symbol, String>]
-    # @return [Array<Object>, Array<Array<Object>>]
+    # @param field [Symbol, String] the first field to extract
+    # @param fields [Array<Symbol, String>] additional fields to extract
+    # @return [Array<Object>] array of single field values if one field given
+    # @return [Array<Array<Object>>] array of field value arrays if multiple fields given
     def pluck(field, *fields)
       if fields.empty?
         map { |record| record[field] }
@@ -126,11 +169,24 @@ module Mongory
     # Returns the raw parsed condition for this query.
     #
     # @return [Hash] the raw compiled condition
-    def condition
+    def raw_condition
       @matcher.condition
     end
 
-    alias_method :selector, :condition
+    # Creates a new query builder with additional context configuration.
+    #
+    # @param addon_context [Hash] Additional context configuration to merge
+    # @return [QueryBuilder] A new query builder instance with merged context
+    # @note Creates a new query builder with the current matcher's condition and merged context
+    # @example
+    #   query.with_context(need_convert: false) #=> Returns a new query builder with conversion disabled
+    def with_context(addon_context = {})
+      dup_instance_exec do
+        @context = @context.dup
+        @context.config.merge!(addon_context)
+        set_matcher(@matcher.condition)
+      end
+    end
 
     # Prints the internal matcher tree structure for the current query.
     # Will output a human-readable visual tree of matchers.
@@ -148,8 +204,7 @@ module Mongory
     # @private
     # Duplicates the query and executes the block in context.
     #
-    # @yieldparam dup [QueryBuilder]
-    # @return [QueryBuilder]
+    # @return [QueryBuilder] the modified duplicate
     def dup_instance_exec(&block)
       dup.tap do |obj|
         obj.instance_exec(&block)
@@ -160,17 +215,18 @@ module Mongory
     # Builds the internal matcher tree from a condition hash.
     # Used to eagerly parse conditions to improve inspect/debug visibility.
     #
-    # @param condition [Hash]
+    # @param condition [Hash] the condition to build the matcher from
     # @return [void]
     def set_matcher(condition = {})
-      @matcher = QueryMatcher.new(condition)
+      @matcher = QueryMatcher.new(condition, context: @context)
     end
 
     # @private
     # Merges additional conditions into the matcher.
     #
-    # @param key [String, Symbol]
-    # @param conditions [Array<Hash>]
+    # @param key [String, Symbol] the operator key (e.g. '$and', '$or')
+    # @param conditions [Array<Hash>] the conditions to add
+    # @return [void]
     def add_conditions(key, conditions)
       condition_dup = @matcher.condition.dup
       condition_dup[key] ||= []
@@ -178,6 +234,12 @@ module Mongory
       set_matcher(condition_dup)
     end
 
+    # @private
+    # Wraps values in a condition hash with a given operator key.
+    #
+    # @param condition [Hash] the condition to transform
+    # @param key [String] the operator key to wrap with
+    # @return [Hash] the transformed condition
     def wrap_values_with_key(condition, key)
       condition.transform_values do |sub_condition|
         { key => sub_condition }

data/lib/mongory/query_matcher.rb

@@ -11,31 +11,58 @@ module Mongory
   # Typically used internally by `QueryBuilder`.
   #
   # Conversion via Mongory.data_converter is applied to the record
+  # before matching to ensure consistent data types.
   #
-  # @example
-  #   matcher = QueryMatcher.build({ :age.gte => 18 })
-  #   matcher.match?(record)
+  # @example Basic matching
+  #   matcher = QueryMatcher.new({ :age.gte => 18 })
+  #   matcher.match?(record) # => true/false
+  #
+  # @example Complex condition
+  #   matcher = QueryMatcher.new({
+  #     :age.gte => 18,
+  #     :$or => [
+  #       { :name => /J/ },
+  #       { :name.eq => 'Bob' }
+  #     ]
+  #   })
   #
   # @see Matchers::LiteralMatcher
   # @see Converters::ConditionConverter
   class QueryMatcher < Matchers::LiteralMatcher
+    # Initializes a new query matcher with the given condition.
+    # The condition is converted using Mongory.condition_converter
+    # before being passed to the parent matcher.
+    #
     # @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))
+    # @param context [Context] The query context containing configuration and current record
+    # @option context [Hash] :config The query configuration
+    # @option context [Object] :current_record The current record being processed
+    # @option context [Boolean] :need_convert Whether the record needs to be converted
+    def initialize(condition, context: Utils::Context.new)
+      super(Mongory.condition_converter.convert(condition), context: context)
     end
 
-    # Matches the given record against the condition.
+    # Returns a Proc that can be used for fast matching.
+    # The Proc converts the record using Mongory.data_converter
+    # and delegates to the superclass's raw_proc.
     #
-    # @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))
+    # @return [Proc] A proc that performs query 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 |record|
+        record = data_converter.convert(record) if need_convert
+        super_proc.call(record)
+      rescue StandardError
+        false
+      end
     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.

data/lib/mongory/query_operator.rb

@@ -22,7 +22,7 @@ module Mongory
     # @param other [Object] the value to match against
     # @return [Hash] converted query condition
     def __expr_part__(other, *)
-      Converters::KeyConverter.instance.convert(@name, @operator => other)
+      { @name => { @operator => other } }
     end
   end
 end

data/lib/mongory/utils/context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Utils
+    # Context is a utility class that provides a stable but mutatable
+    # shared context for the Mongory query builder. It holds the configuration
+    # and the current record being matcher tree processed.
+    #
+    # @example
+    #   context = Mongory::Utils::Context.new(config)
+    #   context.current_record = record
+    #   context.config = new_config
+    #
+    # @attr [Config] config The configuration object for the context
+    # @attr [Record] current_record The current record being processed in the matcher tree
+    # @attr [Boolean] need_convert Whether the record needs to be converted before matching
+    class Context
+      attr_accessor :config, :current_record, :need_convert
+
+      # Initializes a new Context instance with the given configuration.
+      #
+      # @param config [Config] The configuration object for the context.
+      # @return [Context] A new Context instance.
+      def initialize(config = {})
+        @config = config
+        @current_record = nil
+        @need_convert = true
+      end
+
+      # Creates a duplicate of the context with its own configuration.
+      #
+      # @return [Context] A new context instance with duplicated configuration
+      # @note The new context shares the same configuration object but has its own state
+      def dup
+        new_context = super
+        new_context.config = @config.dup
+        new_context
+      end
+    end
+  end
+end

data/lib/mongory/utils/debugger.rb

@@ -32,16 +32,18 @@ module Mongory
         @trace_entries = []
       end
 
-      # Enables debug mode by aliasing `match?` to `debug_match`.
+      # Enables debug mode by aliasing `to_proc` to `debug_proc`.
       # @return [void]
+      # @note Changes the behavior of to_proc to use debug_proc instead of cached_proc
       def enable
-        Matchers::AbstractMatcher.alias_method :match?, :debug_match
+        Matchers::AbstractMatcher.alias_method :to_proc, :debug_proc
       end
 
-      # Disables debug mode by restoring `match?` to `regular_match`.
+      # Disables debug mode by restoring `to_proc` to `cached_proc`.
       # @return [void]
+      # @note Restores the original behavior of to_proc
       def disable
-        Matchers::AbstractMatcher.alias_method :match?, :regular_match
+        Matchers::AbstractMatcher.alias_method :to_proc, :cached_proc
       end
 
       # Wraps a matcher evaluation block with indentation control.

data/lib/mongory/utils.rb

@@ -3,6 +3,7 @@
 require 'date'
 require_relative 'utils/singleton_builder'
 require_relative 'utils/debugger'
+require_relative 'utils/context'
 
 module Mongory
   # Utility helpers shared across Mongory internals.

data/lib/mongory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mongory
-  VERSION = '0.3.0'
+  VERSION = '0.6.0'
 end

data/lib/mongory.rb

@@ -58,21 +58,21 @@ module Mongory
   #
   # @return [Converters::DataConverter]
   def self.data_converter
-    Converters::DataConverter.instance
+    @data_converter ||= Converters::DataConverter.instance
   end
 
   # Returns the condition converter instance.
   #
   # @return [Converters::ConditionConverter]
   def self.condition_converter
-    Converters::ConditionConverter.instance
+    @condition_converter ||= Converters::ConditionConverter.instance
   end
 
   # Returns the debugger instance.
   #
   # @return [Utils::Debugger]
   def self.debugger
-    Utils::Debugger.instance
+    @debugger ||= Utils::Debugger.instance
   end
 
   # Builds a new query over the given record set.

data/mongory.gemspec

@@ -10,15 +10,15 @@ Gem::Specification.new do |spec|
 
   spec.summary = 'MongoDB-like in-memory query DSL for Ruby'
   spec.description = 'A Mongo-like in-memory query DSL for Ruby'
-  spec.homepage = 'https://koten0224.github.io/mongory-rb/'
+  spec.homepage = 'https://mongoryhq.github.io/mongory-rb/'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.6.0'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['rubygems_mfa_required'] = 'true'
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/koten0224/mongory-rb'
-  spec.metadata['changelog_uri'] = 'https://github.com/koten0224/mongory-rb/blob/main/CHANGELOG.md'
+  spec.metadata['source_code_uri'] = 'https://github.com/mongoryhq/mongory-rb'
+  spec.metadata['changelog_uri'] = 'https://github.com/mongoryhq/mongory-rb/blob/main/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.