mongory 0.3.0

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::AbstractOperatorMatcher
+    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/converters/abstract_converter.rb

@@ -0,0 +1,122 @@
+# 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 = []
+        @fallback = Proc.new { |*| self }
+        execute_once_only!(:default_registrations)
+      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)
+        @registries.each do |registry|
+          next unless target.is_a?(registry.klass)
+
+          return exec_convert(target, other, &registry.exec)
+        end
+
+        exec_convert(target, other, &@fallback)
+      end
+
+      # Internal dispatch logic to apply a matching converter.
+      #
+      # @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)
+        end
+      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
+        super
+        @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))
+        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

@@ -0,0 +1,74 @@
+# 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.
+      #
+      # @param condition [Hash]
+      # @return [Hash] the transformed nested condition
+      def convert(condition)
+        result = {}
+        condition.each_pair do |k, v|
+          converted_value = value_converter.convert(v)
+          converted_pair = key_converter.convert(k, converted_value)
+          result.merge!(converted_pair, &deep_merge_block)
+        end
+        result
+      end
+
+      # Provides a block that merges values for overlapping keys in a deep way.
+      #
+      # @return [Proc]
+      def deep_merge_block
+        @deep_merge_block ||= Proc.new do |_, a, b|
+          if a.is_a?(Hash) && b.is_a?(Hash)
+            a.merge(b, &deep_merge_block)
+          else
+            b
+          end
+        end
+      end
+
+      # @note Singleton instance, not configurable after initialization
+      # Returns the key converter used to transform condition keys.
+      #
+      # @return [AbstractConverter]
+      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
+        deep_merge_block
+        super
+        key_converter.freeze
+        value_converter.freeze
+      end
+
+      undef_method :register, :exec_convert
+    end
+  end
+end

data/lib/mongory/converters/data_converter.rb

@@ -0,0 +1,26 @@
+# 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
+      def default_registrations
+        register(Symbol, :to_s)
+        register(Date, :to_s)
+        register(Time, :iso8601)
+        register(DateTime, :iso8601)
+        register(String, :itself)
+        register(Integer, :itself)
+      end
+    end
+  end
+end

data/lib/mongory/converters/key_converter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # KeyConverter handles transformation of field keys in query conditions.
+    # 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.
+    # Used by ConditionConverter to build query structures from flat input.
+    #
+    # - `"a.b.c" => v` becomes `{ "a" => { "b" => { "c" => v } } }`
+    # - Symbols are stringified and delegated to String logic
+    # - QueryOperator dispatches to internal DSL hook
+    #
+    # @example Convert a dotted string key
+    #   KeyConverter.instance.convert("user.name") #=> { "user" => { "name" => value } }
+    #
+    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
+
+        # - `:"a.b.c" => v` becomes `{ "a" => { "b" => { "c" => v } } }`
+        register(Symbol) do |other|
+          convert_string_key.call(to_s, other)
+        end
+
+        # - `:"a.b.c".present => true` becomes `{ "a" => { "b" => { "c" => { "$present" => true } } } }`
+        register(QueryOperator, :__expr_part__)
+      end
+
+      # Converts a dotted string key into nested hash form.
+      #
+      # @param key [String] the dotted key string, e.g. "a.b.c"
+      # @param value [Object] the value to assign at the deepest level
+      # @return [Hash] nested hash structure
+      def convert_string_key(key, value)
+        ret = {}
+        *sub_keys, last_key = key.split(/(?<!\\)\./)
+        last_hash = sub_keys.reduce(ret) do |res, sub_key|
+          next_res = res[normalize_key(sub_key)] = {}
+          next_res
+        end
+        last_hash[normalize_key(last_key)] = value
+        ret
+      end
+
+      def normalize_key(key)
+        key.gsub(/\\\./, '.')
+      end
+    end
+  end
+end

data/lib/mongory/converters/value_converter.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Converters
+    # ValueConverter transforms query values into a standardized form.
+    # It handles arrays, hashes, regex, and basic types, and delegates
+    # fallback logic to DataConverter.
+    # Used by ConditionConverter to prepare values in nested queries.
+    #
+    # - Arrays are recursively converted
+    # - Hashes are interpreted as nested conditions
+    # - Regex becomes a Mongo-style `$regex` hash
+    # - Strings and Integers are passed through
+    # - Everything else falls back to DataConverter
+    #
+    # @example Convert a regex
+    #   ValueConverter.instance.convert(/foo/) #=> { "$regex" => "foo" }
+    #
+    class ValueConverter < AbstractConverter
+      # Sets a fallback using DataConverter for unsupported types.
+      #
+      # @return [void]
+      def initialize
+        super
+        @fallback = Proc.new do
+          Mongory.data_converter.convert(self)
+        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
+
+        register(String, :itself)
+        register(Integer, :itself)
+      end
+    end
+  end
+end

data/lib/mongory/converters.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'converters/abstract_converter'
+require_relative 'converters/condition_converter'
+require_relative 'converters/data_converter'
+require_relative 'converters/key_converter'
+require_relative 'converters/value_converter'

data/lib/mongory/matchers/README.md

@@ -0,0 +1,57 @@
+# 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;
+```