mongory 0.7.2-arm64-darwin-23

data/lib/generators/mongory/install/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'bundler'
+
+module Mongory
+  module Generators
+    # Generates a Mongory initializer file with suggested configuration
+    # based on detected ORMs (ActiveRecord, Mongoid, Sequel).
+    #
+    # This is intended to be used via:
+    #   rails generate mongory:install
+    #
+    # @example
+    #   # Will generate config/initializers/mongory.rb with appropriate snippets
+    #   rails g mongory:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      # Generates the Mongory initializer under `config/initializers/mongory.rb`.
+      # Dynamically injects converter and registration config based on detected ORMs.
+      #
+      # @return [void]
+      def create_initializer_file
+        @use_ar       = gem_used?('activerecord')
+        @use_mongoid  = gem_used?('mongoid')
+        @use_sequel   = gem_used?('sequel')
+
+        template 'initializer.rb.erb', 'config/initializers/mongory.rb'
+      end
+
+      private
+
+      # Checks whether a specific gem is listed in the locked dependencies.
+      #
+      # @param gem_name [String] the name of the gem to check
+      # @return [Boolean] true if the gem is present in the lockfile
+      def gem_used?(gem_name)
+        Bundler.locked_gems.dependencies.key?(gem_name)
+      end
+    end
+  end
+end

data/lib/generators/mongory/install/templates/initializer.rb.erb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Mongory initializer
+#
+# Mongory.configure do ... will lock all configuration after execution.
+# After the block ends, further modification is forbidden for safety.
+# It is recommended to register all data/key/value converters within this block.
+#
+# === Converter Notes ===
+#
+# Data converter:
+#   - Responsible for normalizing data records (e.g., model instances) into Hashes with string keys.
+#   - Expected output should be either a Hash with string keys or a primitive type (Array, String, Number, etc.).
+#   - Registered method or block should take no arguments.
+#
+# Key converter:
+#   - Responsible for transforming condition keys (e.g., :age.gt) into query fragments.
+#   - Output must be a string-keyed Hash.
+#   - Registered method or block should accept one parameter (the condition value), and return a key-value pair.
+#
+# Value converter:
+#   - Responsible for transforming condition values before matching.
+#   - Registered method or block should take no arguments.
+#
+# All converters may support recursive conversion if needed.
+
+Mongory.configure do |mc|
+  # Here to let you use query snippet like `:age.gt => 18`
+  # Or just disable it, and use `"age.$gt" => 18` instead.
+  # NOTE: This method will NOT override existing Symbol methods like :gt or :in.
+  #       It only defines missing ones, and is safe to use with Mongoid or other libraries.
+  mc.enable_symbol_snippets!
+
+  # Here to let you use `some_collection.mongory.where(...)` to build mongory query filter.
+  # Or disable it, and use `Mongory.build_query(some_collection).where(...)` instead.
+  mc.register(Array)
+<% if @use_ar -%>
+  mc.register(ActiveRecord::Relation)
+<% end -%>
+<% if @use_mongoid -%>
+  mc.register(Mongoid::Criteria)
+<% end -%>
+<% if @use_sequel -%>
+  mc.register(Sequel::Dataset)
+<% end -%>
+
+  mc.data_converter.configure do |dc|
+    # Here to let you customize how to normalizing your ORM object or custom class into comparable format.
+    # Example:
+    # dc.register(ActiveRecord::Base, :attributes)
+    # NOTE: If your model overrides `attributes`, or includes virtual fields,
+    #       consider defining a custom method to ensure consistency.
+<% if @use_ar -%>
+    dc.register(ActiveRecord::Base, :attributes)
+<% end -%>
+<% if @use_mongoid -%>
+    dc.register(Mongoid::Document, :as_document)
+    dc.register(BSON::ObjectId, :to_s)
+<% end -%>
+<% if @use_sequel -%>
+    dc.register(Sequel::Model) { values.transform_keys(&:to_s) }
+<% end -%>
+  end
+
+  mc.condition_converter.configure do |cc|
+    cc.key_converter.configure do |kc|
+      # You may register condition key converters here.
+      # Example:
+      # kc.register(MyKeyObject, :trans_to_string_key_pair)
+      # kc.register(MyEnumKey, ->(val) { { "my_enum" => val.to_s } })
+    end
+
+    cc.value_converter.configure do |vc|
+      # You may register condition value converters here.
+      # Example:
+      # vc.register(MyCollectionType) { map { |v| vc.convert(v) } }
+      # vc.register(MyWrapperType) { unwrap_and_return_value }
+<% if @use_mongoid -%>
+      vc.register(BSON::ObjectId, :to_s)
+<% end -%>
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require_relative '../install/install_generator'
+
+module Mongory
+  module Generators
+    # Generates a new Mongory matcher.
+    #
+    # @example
+    #   rails g mongory:matcher class_in
+    #   # Creates:
+    #   #   lib/mongory/matchers/class_in_matcher.rb
+    #   #   spec/mongory/matchers/class_in_matcher_spec.rb
+    #   #   config/initializers/mongory.rb (if not exists)
+    #
+    # @see Mongory::Matchers::AbstractMatcher
+    class MatcherGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      # Generates the matcher files and updates the initializer.
+      #
+      # @return [void]
+      def create_matcher
+        @matcher_name = "#{class_name}Matcher"
+        @operator_name = name.underscore
+        @mongo_operator = "$#{name.camelize(:lower)}"
+
+        template 'matcher.rb.erb', "lib/mongory/matchers/#{file_name}_matcher.rb"
+        template 'matcher_spec.rb.erb', "spec/mongory/matchers/#{file_name}_matcher_spec.rb"
+      end
+
+      # Updates or creates the Mongory initializer.
+      #
+      # @return [void]
+      def update_initializer
+        initializer_path = 'config/initializers/mongory.rb'
+        inject_line = "require \"#\{Rails.root\}/lib/mongory/matchers/#{file_name}_matcher\""
+        front_line = '# frozen_string_literal: true'
+
+        Mongory::Generators::InstallGenerator.start unless File.exist?(initializer_path)
+        content = File.read(initializer_path)
+        return if content.include?(inject_line)
+
+        required_file_lines = content.scan(/.*require\s+["'].*_matcher["'].*/)
+        if required_file_lines.empty?
+          inject_line = "\n#{inject_line}"
+        else
+          front_line = required_file_lines.last
+        end
+
+        inject_into_file initializer_path, "#{inject_line}\n", after: "#{front_line}\n"
+      end
+    end
+  end
+end

data/lib/generators/mongory/matcher/templates/matcher.rb.erb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# <%= @matcher_name %> implements the Mongo-style `<%= @mongo_operator %>` operator.
+#
+# Instance Variables:
+# - @condition: The raw condition value passed to this matcher during initialization.
+#   This value is used for matching logic and should be validated in check_validity!.
+#
+# Condition Examples:
+#   # When query is: { field: { "<%= @mongo_operator %>" => your_condition } }
+#   # @condition will be: your_condition
+#
+#   # When query is: { field: { "<%= @mongo_operator %>" => { key: value } } }
+#   # @condition will be: { key: value }
+#
+#   # When query is: { field: { "<%= @mongo_operator %>" => [value1, value2] } }
+#   # @condition will be: [value1, value2]
+#
+# Matcher Tree Integration:
+# When this matcher is created as part of a matcher tree:
+# 1. It receives its @condition during initialization
+# 2. The @condition is validated via check_validity!
+# 3. The match method is called with normalized values
+# 4. The matcher can use normalize(record) to handle KEY_NOT_FOUND values
+#
+# This matcher typically serves as a leaf node in the matcher tree,
+# responsible for evaluating a single condition against a value.
+# It may be combined with other matchers through logical operators
+# like $and, $or, or $not to form complex conditions.
+#
+# Usage Examples:
+#   # Basic usage
+#   matcher = <%= @matcher_name %>.build(condition)
+#   matcher.match?(value) #=> true/false
+#
+#   # Usage in queries:
+#   # 1. Field-specific condition (MongoDB style)
+#   records.mongory.where(field: { "<%= @mongo_operator %>" => your_condition })
+#
+#   # 2. Field-specific condition (Ruby DSL style)
+#   records.mongory.where(:field.<%= @operator_name %> => your_condition)
+#
+#   # 3. Global condition (applies to all fields)
+#   records.mongory.where("<%= @mongo_operator %>" => your_condition)
+#
+# Implementation Notes:
+# 1. The match method should implement the specific operator logic
+# 2. Use normalize(subject) to handle KEY_NOT_FOUND values consistently
+# 3. The condition is available via @condition
+# 4. check_validity! should validate the format of @condition
+#
+# Interface Design:
+# This matcher provides two levels of matching interface:
+#
+# 1. Public Interface (match?):
+#    - Provides error handling
+#    - Ensures safe matching process
+#    - Suitable for external calls
+#    - Can be tracked by Mongory.debugger
+#    - Used for internal calls and debugging
+#
+# 2. Internal Interface (match):
+#    - Implements the actual matching logic
+#
+# Debugging Support:
+# The match method can be tracked by Mongory.debugger to:
+# - Visualize the matching process
+# - Diagnose matching issues
+# - Provide detailed debugging information
+#
+# @see Mongory::Matchers::AbstractMatcher
+class <%= @matcher_name %> < Mongory::Matchers::AbstractMatcher
+  # Matches the subject against the condition.
+  # This is the internal interface that implements the actual matching logic.
+  # It can be tracked by Mongory.debugger for debugging purposes.
+  #
+  # @param subject [Object] the value to be tested
+  # @return [Boolean] whether the value matches
+  def match(subject)
+    # Implement your matching logic here
+  end
+
+  # Validates the condition value.
+  #
+  # @raise [TypeError] if condition is invalid
+  # @return [void]
+  def check_validity!
+    # Implement your validation logic here
+  end
+end
+
+Mongory::Matchers.register(:<%= @operator_name %>, '<%= @mongo_operator %>', <%= @matcher_name %>)

data/lib/generators/mongory/matcher/templates/matcher_spec.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe <%= @matcher_name %> do
+  describe '#match?' do
+    it 'matches the condition' do
+      # Implement your test here
+    end
+  end
+
+  describe '#check_validity!' do
+    it 'validates the condition' do
+      # Implement your test here
+    end
+  end
+end

data/lib/mongory/c_query_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'query_builder'
+
+module Mongory
+  # Mongory::CQueryBuilder is a query builder for Mongory::CMatcher.
+  # It is used to build a query for a Mongory::CMatcher.
+  class CQueryBuilder < QueryBuilder
+    def each
+      return to_enum(:each) unless block_given?
+
+      @records.each do |record|
+        @context.current_record = record
+        yield record if @matcher.match?(record)
+      end
+    end
+
+    alias_method :fast, :each
+
+    def explain
+      @matcher.match?(@records.first)
+      @matcher.explain
+    end
+
+    def trace
+      return to_enum(:trace) unless block_given?
+
+      @matcher.enable_trace
+      @records.each do |record|
+        @context.current_record = record
+        yield record if @matcher.match?(record)
+      end
+    ensure
+      @matcher.print_trace
+      @matcher.disable_trace
+    end
+
+    private
+
+    def set_matcher(condition = {})
+      @matcher = CMatcher.new(condition, context: @context)
+    end
+  end
+end

data/lib/mongory/converters/abstract_converter.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # AbstractConverter provides a flexible DSL-style mechanism
+    # for dynamically converting objects based on their class.
+    #
+    # It allows you to register conversion rules for specific classes,
+    # with optional fallback behavior.
+    #
+    # @example Basic usage
+    #   converter = AbstractConverter.instance
+    #   converter.register(String) { |v| v.upcase }
+    #   converter.convert("hello") #=> "HELLO"
+    #
+    class AbstractConverter < Utils::SingletonBuilder
+      include Singleton
+
+      # @private
+      # A registry entry storing a conversion rule.
+      #
+      # @!attribute klass
+      #   @return [Class] the class this rule applies to
+      # @!attribute exec
+      #   @return [Proc] the block used to convert the object
+      Registry = Struct.new(:klass, :exec)
+
+      # @private
+      # A sentinel value used to indicate absence of a secondary argument.
+      NOTHING = Utils::SingletonBuilder.new('NOTHING')
+
+      # Initializes the builder with a label and optional configuration block.
+      def initialize
+        super(self.class.to_s)
+        @registries = []
+        @convert_strategy_map = {}.compare_by_identity
+      end
+
+      # Applies the registered conversion to the given target object.
+      #
+      # @param target [Object] the object to convert
+      # @param other [Object] optional secondary value
+      # @return [Object] converted result
+      def convert(target, other = NOTHING)
+        convert_strategy = @convert_strategy_map[target.class] ||= find_strategy(target)
+
+        return fallback(target, other) if convert_strategy == NOTHING
+        return target.instance_exec(&convert_strategy) if other == NOTHING
+
+        target.instance_exec(other, &convert_strategy)
+      end
+
+      def fallback(target, _)
+        target
+      end
+
+      # 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 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.
+      #
+      # @yield DSL block to configure more rules
+      # @return [void]
+      def configure
+        yield self
+        freeze
+      end
+
+      # Freezes all internal registries.
+      #
+      # @return [void]
+      def freeze
+        @registries.freeze
+      end
+
+      # Registers a conversion rule for a given class.
+      #
+      # @param klass [Class, Module] the target class
+      # @param converter [Symbol, nil] method name to call as a conversion
+      # @yield [*args] block that performs the conversion
+      # @return [void]
+      # @raise [RuntimeError] if input is invalid
+      def register(klass, converter = nil, &block)
+        raise 'converter or block is required.' if [converter, block].compact.empty?
+        raise 'A class or module is reuqired.' unless klass.is_a?(Module)
+
+        if converter.is_a?(Symbol)
+          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
+    end
+  end
+end

data/lib/mongory/converters/condition_converter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # ConditionConverter transforms a flat condition hash into nested hash form.
+    # This is used internally by ValueConverter to normalize condition structures
+    # like { "foo.bar" => 1, "foo.baz" => 2 } into nested Mongo-style conditions.
+    # Used by QueryMatcher to normalize condition input for internal matching.
+    #
+    # Combines key transformation (via KeyConverter) and
+    # value normalization (via ValueConverter), and merges overlapping keys.
+    #
+    # @example Convert condition hash
+    #   ConditionConverter.instance.convert({ "a.b" => 1, "a.c" => 2 })
+    #   # => { "a" => { "b" => 1, "c" => 2 } }
+    #
+    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] the flat condition hash to convert
+      # @return [Hash] the transformed nested condition
+      def convert(condition)
+        return condition if condition.is_a?(Converted)
+
+        result = Converted::Hash.new
+        condition.each_pair do |k, v|
+          converted_value = value_converter.convert(v)
+          converted_pair = key_converter.convert(k, converted_value)
+          result.deep_merge!(converted_pair)
+        end
+
+        result
+      end
+
+      # @note Singleton instance, not configurable after initialization
+      # Returns the key converter used to transform condition keys.
+      #
+      # @return [AbstractConverter] the key converter instance
+      def key_converter
+        KeyConverter.instance
+      end
+
+      # @note Singleton instance, not configurable after initialization
+      # Returns the value converter used to transform condition values.
+      #
+      # @return [AbstractConverter]
+      def value_converter
+        ValueConverter.instance
+      end
+
+      # Freezes internal converters to prevent further modification.
+      #
+      # @return [void]
+      def freeze
+        super
+        key_converter.freeze
+        value_converter.freeze
+      end
+
+      undef_method :register
+    end
+  end
+end

data/lib/mongory/converters/converted.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # Converted is a module that provides conversion structures marked as
+    # Converted. It is used to convert various types of data into a
+    # standardized form for MongoDB queries. The module includes
+    # classes for converting hashes and arrays into nested structures.
+    # It is used internally by the ConditionConverter and ValueConverter
+    # to handle the conversion of complex data types into a format
+    # suitable for MongoDB queries.
+    module Converted
+      def instance_convert(other)
+        return other if other.is_a?(Converted)
+
+        case other
+        when ::Hash
+          Converted::Hash.new(other)
+        when ::Array
+          Converted::Array.new(other)
+        else
+          other
+        end
+      end
+
+      # Converts a flat condition hash into a nested structure.
+      # Applies value conversion to each element.
+      # This is used for conditions that are hashes of values.
+      # It is used internally by the ConditionConverter and ValueConverter
+      # to handle the conversion of complex data types into a format
+      # suitable for MongoDB queries.
+      class Hash < ::Hash
+        include Converted
+
+        def initialize(other = {})
+          super()
+          other.each_pair do |k, v|
+            self[k] = instance_convert(v)
+          end
+        end
+
+        def deep_merge(other)
+          dup.deep_merge!(Hash.new(other))
+        end
+
+        def deep_merge!(other)
+          _deep_merge!(self, Hash.new(other))
+        end
+
+        private
+
+        def _deep_merge!(left, right)
+          left.merge!(right) do |_, a, b|
+            if a.is_a?(::Hash) && b.is_a?(::Hash)
+              _deep_merge!(a.dup, b)
+            else
+              b
+            end
+          end
+        end
+      end
+
+      # Converts a flat condition array into a nested structure.
+      # Applies value conversion to each element.
+      # This is used for conditions that are arrays of values.
+      # It is used internally by the ConditionConverter and ValueConverter
+      # to handle the conversion of complex data types into a format
+      # suitable for MongoDB queries.
+      class Array < ::Array
+        include Converted
+
+        def initialize(other)
+          super()
+          other.each do |v|
+            self << instance_convert(v)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongory/converters/data_converter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # DataConverter handles automatic transformation of raw query values.
+    # This class inherits from AbstractConverter and provides predefined conversions for
+    # common primitive types like Symbol, Date, Time, etc.
+    # - Symbols and Date objects are converted to string
+    # - Time and DateTime objects are ISO8601-encoded
+    # - Strings and Integers are passed through as-is
+    #
+    # @example Convert a symbol
+    #   DataConverter.instance.convert(:status) #=> "status"
+    #
+    class DataConverter < AbstractConverter
+      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
+end