mongory 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76d9dbc1cf7704258a68da00e955a295c66d6f0c53b1bcfa8becf505315daa14
-  data.tar.gz: 6492e6f3371fc402153abc0bb0368490a15f88f483ccdfce0912dc2249d9efe5
+  metadata.gz: c030da605cb94ba20f4be31a03e37a5b95277b1c2b93b48622080521752acbfa
+  data.tar.gz: 3577f0da8e823b74fa25459bb0a66dcb2609ff1eef366ae0ce08402a22d8c049
 SHA512:
-  metadata.gz: 9a8139f2288b78943b1e4d0f68433d8383d359877bef277dd760e2dc08486fedf3ebccb8d914a243e0f836ff61f7d307d00df8dbd5187e260b57f3cc7eadc0d0
-  data.tar.gz: 6317bad45fcc0ceb4d5b96316319090b6ca72e75db3ae34fd77fd799c8e1d4324d0cbb5a06b413eab2a74c89ca6494e4fc26b4ac082bfc2a2720bad373eb86b4
+  metadata.gz: 723cdce8afcd41e7f69148934890ac3bc133e297bda01e412b69e491ece2fdfe1b8b27c87244c6417ce4905d18fb8d3082b4217c979b2f6ec1e65bcc71ec0091
+  data.tar.gz: eaa426a3780cc094c0dfd0e5e168fbce4c94db61f504fefa1a44efed5d569bc76a6caf348f5170c46c92916b0ceb384105757b72cbb43e96fdc16208abf7715f

data/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [0.6.0] - 2025-04-23
+
+### Major Changes
+- Refactored matcher system to use Proc-based implementation
+- Introduced Context system for better state management
+- Optimized empty condition handling with TRUE_PROC and FALSE_PROC
+
+### Breaking Changes
+- Removed `match` method in favor of `raw_proc`
+- Changed converter behavior to be executed within Proc
+- Modified fallback behavior in converters
+
+### Features
+- Added Context system for better configuration management
+- Improved performance with Proc caching
+- Enhanced error handling in matchers
+- Better support for complex query conditions
+
+### Performance
+- Optimized empty condition handling
+- Reduced memory usage with Proc caching
+- Improved execution speed with Proc-based implementation
+
+### Internal
+- Refactored matcher system architecture
+- Improved code organization and maintainability
+- Enhanced test coverage
+
+## [0.5.0] - 2025-04-22
+
+### Added
+- Added fast mode implementation for optimized query performance
+- Added Proc-based matching for efficient record filtering
+- Added error handling in fast mode execution
+
+### Changed
+- Optimized query execution with compiled Proc objects
+- Improved memory efficiency in record matching
+- Enhanced error handling in query execution
+
+### Fixed
+- Fixed potential performance bottlenecks in record matching
+- Fixed error handling in query execution
+
+## [0.4.0] - 2025-04-20
+
+### ✨ Added
+- Support regex matching in array fields via `ArrayRecordMatcher`.
+  - Example: `tags: /vip/` will now match any element inside an array.
+- Publicize `MatcherGenerator#update_initializer` to allow external CLI or test usage.
+
+### 🧹 Changed
+- Refactored `ValueConverter` to use direct method reference instead of dynamic caching logic.
+
+### 📝 Documentation
+- Improved matcher generator template documentation.
+  - Added usage examples and matcher tree explanation.
+  - Fixed `Mongory::Debugger` references to `Mongory.debugger`.
+
+### 💥 Breaking
+- Renamed gem from `mongory-rb` to `mongory`, affecting gemspec and file references.
+  - `mongory.gemspec` now used in place of `mongory-rb.gemspec`.
+
+# Changelog
+
 ## v0.3.0
 
 ### New Features

data/README.md

@@ -245,6 +245,22 @@ Internally, the query is compiled into a matcher tree using the `QueryMatcher` a
 | `nin` | Checks if a value is not in a set | `nin(age: [18, 19, 20])` |
 | `limit` | Limits the number of records returned. This method executes immediately and affects subsequent conditions. | `limit(2)` |
 | `pluck` | Extracts selected fields from matching records | `pluck(:name)` |
+| `with_context` | Sets a custom context for the query. Useful for controlling data conversion and sharing configuration across matchers. | `with_context(merchant: merchant)` |
+
+#### Context Configuration
+
+The `with_context` method allows you to customize the query execution environment:
+
+```ruby
+# Share configuration across matchers
+records.mongory
+  .with_context(custom_option: true)
+  .where(:status => 'active')
+  .where(:age.gte => 18)
+```
+
+This will share a mutatable, but stable context object to all matchers in matcher tree.
+To get your custom option, using `@context.config` in your custom matcher.
 
 ### Debugging Queries
 
@@ -313,30 +329,37 @@ The debug output includes:
 1. **Memory Usage**
    - Mongory operates entirely in memory
    - Consider your data size and memory constraints
+   - Proc-based implementation reduces memory usage
+   - Context system provides better memory management
 
 2. **Query Optimization**
    - Complex conditions are evaluated in sequence
    - Use `explain` to analyze query performance
+   - Empty conditions are optimized with cached Procs
+   - Context system allows fine-grained control over conversion
 
 3. **Benchmarks**
   ```ruby
     # Simple query (1000 records)
-    records.mongory.where(:age.gte => 18) # ~2.5ms
+    records.mongory.where(:age.gte => 18) # ~0.8ms
 
     # Complex query (1000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~3.2ms
+    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~0.9ms
 
     # Simple query (10000 records)
-    records.mongory.where(:age.gte => 18) # ~24.5ms
+    records.mongory.where(:age.gte => 18) # ~6.5ms
 
     # Complex query (10000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~31.5ms
+    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~7.5ms
 
     # Simple query (100000 records)
-    records.mongory.where(:age.gte => 18) # ~242.5ms
+    records.mongory.where(:age.gte => 18) # ~64.7ms
 
     # Complex query (100000 records)
-    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~323.0ms
+    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]) # ~75.0ms
+
+    # Complex query with fast mode (100000 records)
+    records.mongory.where(:$or => [{:age.gte => 18}, {:status => 'active'}]).fast # ~42.8ms, about 3x of plain ruby
   ```
 
    Note: Performance varies based on:
@@ -435,6 +458,9 @@ end
     # Use limit to restrict result set
     records.mongory.limit(100).where(:age.gte => 18)
 
+    # Use fast mode for better performance
+    records.mongory.where(:age.gte => 18).fast
+
     # Use explain to analyze complex queries
     query = records.mongory.where(:$or => [...])
     query.explain
@@ -457,10 +483,14 @@ end
 1. **Data Size**
    - Suitable for small to medium datasets
    - Large datasets may impact performance
+   - Proc-based implementation helps with memory usage
+   - Context system provides better resource management
 
 2. **Query Complexity**
    - Complex queries may affect performance
    - Not all MongoDB operators are supported
+   - Proc-based implementation improves complex query performance
+   - Context system allows better control over query execution
 
 3. **Memory Usage**
    - All operations are performed in memory
@@ -510,7 +540,7 @@ Please ensure your code adheres to the project's style guide and that all tests
 
 ## Code of Conduct
 
-Everyone interacting in the Mongory-rb project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/koten0224/mongory-rb/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Mongory-rb project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/mongoryhq/mongory-rb/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/examples/benchmark-rails.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+require 'benchmark'
+
+puts 'Ruby String#empty?'
+result = Benchmark.measure do
+  1_000_000.times do
+    ''.empty?
+  end
+end
+puts result
+
+puts 'Rails String#blank?'
+result = Benchmark.measure do
+  1_000_000.times do
+    ''.blank?
+  end
+end
+puts result
+
+puts 'Ruby Array#empty?'
+result = Benchmark.measure do
+  1_000_000.times do
+    [].empty?
+  end
+end
+puts result
+
+puts 'Rails Array#blank?'
+result = Benchmark.measure do
+  1_000_000.times do
+    [].blank?
+  end
+end
+puts result
+
+puts 'Ruby Hash#empty?'
+result = Benchmark.measure do
+  1_000_000.times do
+    {}.empty?
+  end
+end
+puts result
+
+puts 'Rails Hash#blank?'
+result = Benchmark.measure do
+  1_000_000.times do
+    {}.blank?
+  end
+end
+puts result

data/examples/benchmark.rb

@@ -7,8 +7,23 @@ require 'benchmark'
 Mongory.register(Array)
 Mongory.enable_symbol_snippets!
 
+def gc_handler
+  # GC.disable
+  before = GC.stat
+  yield
+  after = GC.stat
+  # GC.enable
+
+  created = after[:total_allocated_objects] - before[:total_allocated_objects]
+  freed   = after[:total_freed_objects] - before[:total_freed_objects]
+  alive   = after[:heap_live_slots] - before[:heap_live_slots]
+
+  puts "Created: #{created}"    # 分配了幾個 object
+  puts "Freed: #{freed}"        # 中途 GC 掃掉幾個（若 GC 有觸發）
+  puts "Net alive: #{alive}"    # 最後還活著的物件數
+end
 # Test with different data sizes
-[1000, 10_000, 100_000].each do |size|
+[20, 1000, 10_000, 100_000].each do |size|
   puts "\nTesting with #{size} records:"
 
   # Generate test data
@@ -19,26 +34,72 @@ Mongory.enable_symbol_snippets!
     }
   end
 
-  # Simple query test
-  puts "\nSimple query (#{size} records):"
-  5.times do
-    result = Benchmark.measure do
-      records.mongory.where(:age.gte => 18).to_a
+  # Simple query (Plain Ruby) test
+  puts "\nSimple query (Plain Ruby) (#{size} records):"
+  gc_handler do
+    5.times do
+      result = Benchmark.measure do
+        records.select { |r| r.key?('age') && r['age'] >= 18 }
+      end
+      puts result
+    end
+  end
+
+  # Simple query (Mongory) test
+  puts "\nSimple query (Mongory) (#{size} records):"
+  gc_handler do
+    5.times do
+      result = Benchmark.measure do
+        records.mongory.where(:age.gte => 18).to_a
+      end
+      puts result
+    end
+  end
+
+  # Complex query (Plain Ruby) test
+  puts "\nComplex query (Plain Ruby) (#{size} records):"
+  gc_handler do
+    5.times do
+      result = Benchmark.measure do
+        records.select do |r|
+          next false unless r.key?('age') && r.key?('status')
+
+          r['age'] >= 18 || r['status'] == 'active'
+        end
+      end
+      puts result
+    end
+  end
+
+  # Complex query (Mongory) test
+  puts "\nComplex query (Mongory) (#{size} records):"
+  gc_handler do
+    5.times do
+      result = Benchmark.measure do
+        records.mongory.where(
+          :$or => [
+            { :age.gte => 18 },
+            { status: 'active' }
+          ]
+        ).to_a
+      end
+      puts result
     end
-    puts result
   end
 
-  # Complex query test
-  puts "\nComplex query (#{size} records):"
-  5.times do
-    result = Benchmark.measure do
-      records.mongory.where(
-        :$or => [
-          { :age.gte => 18 },
-          { status: 'active' }
-        ]
-      ).to_a
+  # Complex query (Mongory) test
+  puts "\nComplex query (Mongory) fast mode (#{size} records):"
+  gc_handler do
+    5.times do
+      result = Benchmark.measure do
+        records.mongory.where(
+          :$or => [
+            { :age.gte => 18 },
+            { status: 'active' }
+          ]
+        ).fast.to_a
+      end
+      puts result
     end
-    puts result
   end
 end

data/lib/generators/mongory/matcher/matcher_generator.rb

@@ -14,7 +14,7 @@ module Mongory
     #   #   spec/mongory/matchers/class_in_matcher_spec.rb
     #   #   config/initializers/mongory.rb (if not exists)
     #
-    # @see Mongory::Matchers::AbstractOperatorMatcher
+    # @see Mongory::Matchers::AbstractMatcher
     class MatcherGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('templates', __dir__)
 

data/lib/mongory/converters/abstract_converter.rb

@@ -33,8 +33,7 @@ module Mongory
       def initialize
         super(self.class.to_s)
         @registries = []
-        @fallback = Proc.new { |*| self }
-        execute_once_only!(:default_registrations)
+        @convert_strategy_map = {}.compare_by_identity
       end
 
       # Applies the registered conversion to the given target object.
@@ -43,27 +42,32 @@ module Mongory
       # @param other [Object] optional secondary value
       # @return [Object] converted result
       def convert(target, other = NOTHING)
-        @registries.each do |registry|
-          next unless target.is_a?(registry.klass)
+        convert_strategy = @convert_strategy_map[target.class] ||= find_strategy(target)
 
-          return exec_convert(target, other, &registry.exec)
-        end
+        return fallback(target, other) if convert_strategy == NOTHING
+        return target.instance_exec(&convert_strategy) if other == NOTHING
+
+        target.instance_exec(other, &convert_strategy)
+      end
 
-        exec_convert(target, other, &@fallback)
+      def fallback(target, _)
+        target
       end
 
-      # Internal dispatch logic to apply a matching converter.
+      # Finds the appropriate conversion strategy for the target object.
+      # Searches through registered rules and returns the first matching one,
+      # or the fallback strategy if no match is found.
       #
-      # @param target [Object] the object to match
-      # @param other [Object] optional extra data
-      # @yield fallback block if no converter is found
-      # @return [Object]
-      def exec_convert(target, other, &block)
-        if other == NOTHING
-          target.instance_exec(&block)
-        else
-          target.instance_exec(other, &block)
+      # @param target [Object] the object to find a strategy for
+      # @return [Proc] the conversion strategy to use
+      def find_strategy(target)
+        @registries.each do |registry|
+          next unless target.is_a?(registry.klass)
+
+          return registry.exec
         end
+
+        NOTHING
       end
 
       # Opens a configuration block to register more converters.
@@ -98,25 +102,11 @@ module Mongory
           register(klass) { |*args, &bl| send(converter, *args, &bl) }
         elsif block.is_a?(Proc)
           @registries.unshift(Registry.new(klass, block))
+          @convert_strategy_map[klass] = block
         else
           raise 'Support Symbol and block only.'
         end
       end
-
-      # Executes the given method only once by undefining it after execution.
-      #
-      # @param method_sym [Symbol] method name to execute once
-      # @return [void]
-      def execute_once_only!(method_sym)
-        send(method_sym)
-        singleton_class.undef_method(method_sym)
-      end
-
-      # Defines default class-to-converter registrations.
-      # Should be overridden by subclasses.
-      #
-      # @return [void]
-      def default_registrations; end
     end
   end
 end

data/lib/mongory/converters/condition_converter.rb

@@ -16,8 +16,9 @@ module Mongory
     #
     class ConditionConverter < AbstractConverter
       # Converts a flat condition hash into a nested structure.
+      # Applies both key and value conversion, and merges overlapping keys.
       #
-      # @param condition [Hash]
+      # @param condition [Hash] the flat condition hash to convert
       # @return [Hash] the transformed nested condition
       def convert(condition)
         result = {}
@@ -30,8 +31,10 @@ module Mongory
       end
 
       # Provides a block that merges values for overlapping keys in a deep way.
+      # When both values are hashes, recursively merges them.
+      # Otherwise, uses the second value.
       #
-      # @return [Proc]
+      # @return [Proc] a block for deep merging hash values
       def deep_merge_block
         @deep_merge_block ||= Proc.new do |_, a, b|
           if a.is_a?(Hash) && b.is_a?(Hash)
@@ -45,7 +48,7 @@ module Mongory
       # @note Singleton instance, not configurable after initialization
       # Returns the key converter used to transform condition keys.
       #
-      # @return [AbstractConverter]
+      # @return [AbstractConverter] the key converter instance
       def key_converter
         KeyConverter.instance
       end
@@ -68,7 +71,7 @@ module Mongory
         value_converter.freeze
       end
 
-      undef_method :register, :exec_convert
+      undef_method :register
     end
   end
 end

data/lib/mongory/converters/data_converter.rb

@@ -13,13 +13,24 @@ module Mongory
     #   DataConverter.instance.convert(:status) #=> "status"
     #
     class DataConverter < AbstractConverter
-      def default_registrations
-        register(Symbol, :to_s)
-        register(Date, :to_s)
-        register(Time, :iso8601)
-        register(DateTime, :iso8601)
-        register(String, :itself)
-        register(Integer, :itself)
+      alias_method :super_convert, :convert
+
+      # Converts a value into its standardized form based on its type.
+      # Handles common primitive types with predefined conversion rules.
+      #
+      # @param target [Object] the value to convert
+      # @return [Object] the converted value
+      def convert(target)
+        case target
+        when String, Integer, Hash, Array
+          target
+        when Symbol, Date
+          target.to_s
+        when Time, DateTime
+          target.iso8601
+        else
+          super_convert(target)
+        end
       end
     end
   end

data/lib/mongory/converters/key_converter.rb

@@ -6,8 +6,13 @@ module Mongory
     # It normalizes symbol keys into string paths, splits dotted keys,
     # and delegates to the appropriate converter logic.
     #
-    # This class inherits from AbstractConverter and registers rules for
-    # strings, symbols, and includes a fallback handler.
+    # 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 } } }`
@@ -15,31 +20,45 @@ module Mongory
     # - QueryOperator dispatches to internal DSL hook
     #
     # @example Convert a dotted string key
-    #   KeyConverter.instance.convert("user.name") #=> { "user" => { "name" => value } }
+    #   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
-      # fallback if key type is unknown — returns { self => value }
-      def initialize
-        super
-        @fallback = ->(x) { { self => x } }
-      end
-
-      def default_registrations
-        convert_string_key = method(:convert_string_key)
-        register(String) do |value|
-          convert_string_key.call(self, value)
-        end
+      alias_method :super_convert, :convert
 
-        # - `:"a.b.c" => v` becomes `{ "a" => { "b" => { "c" => v } } }`
-        register(Symbol) do |other|
-          convert_string_key.call(to_s, other)
+      # 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
 
-        # - `:"a.b.c".present => true` becomes `{ "a" => { "b" => { "c" => { "$present" => true } } } }`
-        register(QueryOperator, :__expr_part__)
+      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
@@ -55,6 +74,11 @@ module Mongory
         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

data/lib/mongory/converters/value_converter.rb

@@ -17,30 +17,35 @@ module Mongory
     #   ValueConverter.instance.convert(/foo/) #=> { "$regex" => "foo" }
     #
     class ValueConverter < AbstractConverter
-      # Sets a fallback using DataConverter for unsupported types.
+      alias_method :super_convert, :convert
+
+      # Converts a value into its standardized form based on its type.
+      # Handles arrays, hashes, regex, and basic types.
       #
-      # @return [void]
-      def initialize
-        super
-        @fallback = Proc.new do
-          Mongory.data_converter.convert(self)
+      # @param target [Object] the value to convert
+      # @return [Object] the converted value
+      def convert(target)
+        case target
+        when String, Integer, Regexp
+          target
+        when Array
+          target.map { |x| convert(x) }
+        when Hash
+          condition_converter.convert(target)
+        else
+          super_convert(target)
         end
       end
 
-      def default_registrations
-        v_convert = method(:convert)
-        register(Array) do
-          map { |x| v_convert.call(x) }
-        end
-
-        # - Hashes are interpreted as nested condition trees
-        #   using ConditionConverter
-        register(Hash) do
-          Mongory.condition_converter.convert(self)
-        end
+      def fallback(target, *)
+        Mongory.data_converter.convert(target)
+      end
 
-        register(String, :itself)
-        register(Integer, :itself)
+      # Returns the condition converter instance.
+      #
+      # @return [ConditionConverter] the condition converter instance
+      def condition_converter
+        @condition_converter ||= Mongory.condition_converter
       end
     end
   end