mongory 0.4.0 → 0.6.1

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,24 +215,31 @@ 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 = {}.merge!(@matcher.condition)
       condition_dup[key] ||= []
       condition_dup[key] += conditions
       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
+  class QueryMatcher < Matchers::HashConditionMatcher
+    # 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.4.0'
+  VERSION = '0.6.1'
 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mongory
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.1
 platform: ruby
 authors:
 - koten0224
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-04-20 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies: []
 description: A Mongo-like in-memory query DSL for Ruby
 email:
@@ -26,6 +26,7 @@ files:
 - README.md
 - Rakefile
 - examples/README.md
+- examples/benchmark-rails.rb
 - examples/benchmark.rb
 - lib/generators/mongory/install/install_generator.rb
 - lib/generators/mongory/install/templates/initializer.rb.erb
@@ -36,14 +37,13 @@ files:
 - lib/mongory/converters.rb
 - lib/mongory/converters/abstract_converter.rb
 - lib/mongory/converters/condition_converter.rb
+- lib/mongory/converters/converted.rb
 - lib/mongory/converters/data_converter.rb
 - lib/mongory/converters/key_converter.rb
 - lib/mongory/converters/value_converter.rb
 - lib/mongory/matchers.rb
-- lib/mongory/matchers/README.md
 - lib/mongory/matchers/abstract_matcher.rb
 - lib/mongory/matchers/abstract_multi_matcher.rb
-- lib/mongory/matchers/abstract_operator_matcher.rb
 - lib/mongory/matchers/and_matcher.rb
 - lib/mongory/matchers/array_record_matcher.rb
 - lib/mongory/matchers/elem_match_matcher.rb
@@ -64,27 +64,29 @@ files:
 - lib/mongory/matchers/or_matcher.rb
 - lib/mongory/matchers/present_matcher.rb
 - lib/mongory/matchers/regex_matcher.rb
+- lib/mongory/matchers/size_matcher.rb
 - lib/mongory/mongoid.rb
 - lib/mongory/query_builder.rb
 - lib/mongory/query_matcher.rb
 - lib/mongory/query_operator.rb
 - lib/mongory/rails.rb
 - lib/mongory/utils.rb
+- lib/mongory/utils/context.rb
 - lib/mongory/utils/debugger.rb
 - lib/mongory/utils/rails_patch.rb
 - lib/mongory/utils/singleton_builder.rb
 - lib/mongory/version.rb
 - mongory.gemspec
 - sig/mongory.rbs
-homepage: https://koten0224.github.io/mongory-rb/
+homepage: https://mongoryhq.github.io/mongory-rb/
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-  homepage_uri: https://koten0224.github.io/mongory-rb/
-  source_code_uri: https://github.com/koten0224/mongory-rb
-  changelog_uri: https://github.com/koten0224/mongory-rb/blob/main/CHANGELOG.md
+  homepage_uri: https://mongoryhq.github.io/mongory-rb/
+  source_code_uri: https://github.com/mongoryhq/mongory-rb
+  changelog_uri: https://github.com/mongoryhq/mongory-rb/blob/main/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -100,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: MongoDB-like in-memory query DSL for Ruby

data/lib/mongory/matchers/README.md

@@ -1,57 +0,0 @@
-# Matcher classes inheritance diagram
-
-```mermaid
----
-config:
-  theme: neutral
-  look: classic
----
-
-graph TD
-  %% style blocks
-  classDef abstract fill:#ddd,stroke:#333,stroke-width:1px,color:#000;
-  classDef main fill:#cce5ff,stroke:#339,stroke-width:1px;
-  classDef multi fill:#d4edda,stroke:#282,stroke-width:1px;
-  classDef operator fill:#fff3cd,stroke:#aa8800,stroke-width:1px;
-  classDef leaf fill:#f8f9fa,stroke:#999,stroke-width:1px;
-
-  %% Abstract base classes
-  A[AbstractMatcher]
-  C[AbstractMultiMatcher]
-  D[AbstractOperatorMatcher]
-
-  subgraph MultipleConditions
-    F[HashConditionMatcher]
-    I[AndMatcher]
-    J[OrMatcher]
-    W[ArrayRecordMatcher]
-  end
-
-  subgraph SimpleCompare
-    E[EqMatcher]
-    K[RegexMatcher]
-    L[PresentMatcher]
-    M[ExistsMatcher]
-    O[NeMatcher]
-    Q[GtMatcher]
-    R[GteMatcher]
-    S[LtMatcher]
-    T[LteMatcher]
-  end
-
-  A --> B[LiteralMatcher]
-  A --> U[InMatcher]
-  A --> V[NinMatcher]
-  A --> C --> MultipleConditions
-  A --> D --> SimpleCompare
-  B --> G[FieldMatcher]
-  B --> H[ElemMatchMatcher]
-  B --> N[NotMatcher]
-
-  %% Apply classes
-  class A,C,D abstract;
-  class B main;
-  class F,I,J,W multi;
-  class E,K,L,M,O,Q,R,S,T operator;
-  class G,U,V,H,N leaf;
-```

data/lib/mongory/matchers/abstract_operator_matcher.rb

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