mongory 0.3.0

data/lib/mongory/utils/debugger.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Utils
+    # Debugger provides an internal tracing system for query matching.
+    # It tracks matcher evaluation in a tree structure and provides tree-like format output.
+    #
+    # It captures each matcher evaluation with indentation and visualizes the hierarchy,
+    # helping developers understand nested matcher flows (e.g. `$and`, `$or`, etc).
+    #
+    # Usage:
+    #   Debugger.instance.with_indent { ... } # wraps around matcher logic
+    #   Debugger.instance.display        # prints trace tree after execution
+    #
+    # Note:
+    # The trace is recorded in post-order (leaf nodes enter first),
+    # and `reorder_traces_for_display` is used to transform it into a
+    # pre-order format suitable for display.
+    #
+    # This class is a singleton and should be accessed via `Debugger.instance`.
+    #
+    # @example Enable debugging
+    #   Debugger.instance.enable
+    #   Mongory::QueryBuilder.new(...).filter(...)
+    #
+    class Debugger < SingletonBuilder
+      include Singleton
+
+      def initialize
+        super(self.class.name)
+        @indent_level = -1
+        @trace_entries = []
+      end
+
+      # Enables debug mode by aliasing `match?` to `debug_match`.
+      # @return [void]
+      def enable
+        Matchers::AbstractMatcher.alias_method :match?, :debug_match
+      end
+
+      # Disables debug mode by restoring `match?` to `regular_match`.
+      # @return [void]
+      def disable
+        Matchers::AbstractMatcher.alias_method :match?, :regular_match
+      end
+
+      # Wraps a matcher evaluation block with indentation control.
+      #
+      # It increments the internal indent level before the block,
+      # and decrements it after. The yielded block's return value
+      # is used as trace content and pushed onto the trace_entries.
+      #
+      # @yieldreturn [String] the trace content to log
+      # @return [Object] the result of the block
+      def with_indent
+        @indent_level += 1
+        display_string = yield
+        @trace_entries << TraceEntry.new(display_string, @indent_level)
+      ensure
+        @indent_level -= 1
+      end
+
+      # Prints the visualized trace tree to STDOUT.
+      #
+      # This processes the internal trace_entries (post-order) into
+      # a structured pre-order list that represents nested matcher evaluation.
+      # @return [void]
+      def display
+        reorder_traces_for_display(@trace_entries).each do |trace|
+          puts trace.formatted
+        end
+
+        @trace_entries.clear
+        nil
+      end
+
+      # Recursively reorders trace lines by indentation level to produce a
+      # display-friendly structure where parents precede children.
+      #
+      # The original trace is built in post-order (leaf first), and this method
+      # transforms it into a pre-order structure suitable for tree display.
+      #
+      # @param traces [Array<TraceEntry>] the raw trace lines (leaf-first)
+      # @param level [Integer] current processing level
+      # @return [Array<TraceEntry>] reordered trace lines for display
+      def reorder_traces_for_display(traces, level = 0)
+        result = []
+        group = []
+        traces.each do |trace|
+          if trace.level == level
+            result << trace
+            result.concat reorder_traces_for_display(group, level + 1)
+            group = []
+          else
+            group << trace
+          end
+        end
+
+        result
+      end
+
+      def clear
+        # Clears the internal trace buffer.
+        # This is useful when re-running a query and avoiding stale trace output.
+        # @return [void]
+        @trace_entries.clear
+      end
+
+      # @private
+      # A trace entry representing a single matcher output at a given indentation level.
+      #
+      # @!attribute text
+      #   @return [String] the string to be printed
+      # @!attribute level
+      #   @return [Integer] the indentation level of this entry
+      TraceEntry = Struct.new(:text, :level) do
+        def formatted
+          "#{'  ' * level}#{text}"
+        end
+      end
+    end
+  end
+end

data/lib/mongory/utils/rails_patch.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Utils
+    # Only loaded when Rails is present
+    module RailsPatch
+      # Use Object#present? which defined in Rails.
+      # @param target[Object]
+      # @return [Boolean]
+      def is_present?(target)
+        target.present?
+      end
+
+      # Use Object#blank? which defined in Rails.
+      # @param target[Object]
+      # @return [Boolean]
+      def is_blank?(target)
+        target.blank?
+      end
+    end
+  end
+end

data/lib/mongory/utils/singleton_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mongory
+  module Utils
+    # A singleton placeholder object used to represent special sentinel values.
+    #
+    # Used in situations where `nil` is a valid value and cannot be used as a marker.
+    # Typically used for internal constants like `NOTHING` or `KEY_NOT_FOUND`.
+    #
+    # @example
+    #   NOTHING = SingletonBuilder.new('NOTHING')
+    #   value == NOTHING  # => true if placeholder
+    class SingletonBuilder
+      # @param label [String] a human-readable label for the marker
+      def initialize(label, &block)
+        @label = label
+        instance_eval(&block) if block_given?
+      end
+
+      # @return [String] formatted label
+      def inspect
+        "#<#{@label}>"
+      end
+
+      # @return [String] formatted label
+      def to_s
+        "#<#{@label}>"
+      end
+    end
+  end
+end

data/lib/mongory/utils.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'utils/singleton_builder'
+require_relative 'utils/debugger'
+
+module Mongory
+  # Utility helpers shared across Mongory internals.
+  #
+  # Includes blank checking, present checking,
+  # and class-level instance method caching.
+  module Utils
+    # When included, also extends the including class with ClassMethods.
+    # And record which class include this module.
+    #
+    # @param base [Class, Module]
+    def self.included(base)
+      base.extend(ClassMethods)
+      super
+      included_classes << base
+    end
+
+    # Where to record classes that include Utils.
+    #
+    # @return [Array]
+    def self.included_classes
+      @included_classes ||= []
+    end
+
+    # Checks if an object is "present".
+    # Inverse of {#is_blank?}.
+    #
+    # @param obj [Object]
+    # @return [Boolean]
+    def is_present?(obj)
+      !is_blank?(obj)
+    end
+
+    # Determines whether an object is considered "blank".
+    # Nil, false, empty string/array/hash are blank.
+    #
+    # @param obj [Object]
+    # @return [Boolean]
+    def is_blank?(obj)
+      case obj
+      when false, nil
+        true
+      when Hash, Array, String
+        obj.empty?
+      else
+        false
+      end
+    end
+
+    # Class-level methods injected via Utils.
+    module ClassMethods
+      # Defines a lazily-evaluated, memoized instance method.
+      #
+      # @param name [Symbol] the method name
+      # @yield block to compute the value
+      # @return [void]
+      #
+      # @example
+      #   define_instance_cache_method(:expensive_thing) { compute_something }
+      def define_instance_cache_method(name, &block)
+        instance_key = :"@#{name}"
+        define_method(name) do
+          return instance_variable_get(instance_key) if instance_variable_defined?(instance_key)
+
+          instance_variable_set(instance_key, instance_exec(&block))
+        end
+      end
+    end
+  end
+end

data/lib/mongory/version.rb

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

data/lib/mongory-rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'mongory'

data/lib/mongory.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+require 'singleton'
+require_relative 'mongory/version'
+require_relative 'mongory/utils'
+require_relative 'mongory/matchers'
+require_relative 'mongory/query_matcher'
+require_relative 'mongory/query_builder'
+require_relative 'mongory/query_operator'
+require_relative 'mongory/converters'
+require_relative 'mongory/rails' if defined?(Rails::Railtie)
+require_relative 'mongory/mongoid' if defined?(Mongoid)
+
+# Main namespace for Mongory DSL and configuration.
+#
+# Provides access to core converters, query construction, and optional
+# integrations with frameworks like Rails or Mongoid.
+#
+# @example Basic usage
+#   Mongory.build_query(records).where(age: { :$gt => 18 })
+#
+# @example Enabling DSL snippets
+#   Mongory.enable_symbol_snippets!
+#   Mongory.register(Array)
+module Mongory
+  class Error < StandardError; end
+  class TypeError < Error; end
+
+  # Yields Mongory for configuration and freezes key components.
+  #
+  # @example Configure converters
+  #   Mongory.configure do |mc|
+  #     mc.data_converter.configure do |dc|
+  #       dc.register(MyType) { transform(self) }
+  #     end
+  #
+  #     mc.condition_converter.key_converter.configure do |kc|
+  #       kc.register(MyKeyType) { normalize_key(self) }
+  #     end
+  #
+  #     mc.condition_converter.value_converter.configure do |vc|
+  #       vc.register(MyValueType) { cast_value(self) }
+  #     end
+  #   end
+  #
+  # @yieldparam self [Mongory]
+  # @return [void]
+  def self.configure
+    yield self
+    data_converter.freeze
+    condition_converter.freeze
+    Matchers.freeze
+  end
+
+  # Returns the data converter instance.
+  #
+  # @return [Converters::DataConverter]
+  def self.data_converter
+    Converters::DataConverter.instance
+  end
+
+  # Returns the condition converter instance.
+  #
+  # @return [Converters::ConditionConverter]
+  def self.condition_converter
+    Converters::ConditionConverter.instance
+  end
+
+  # Returns the debugger instance.
+  #
+  # @return [Utils::Debugger]
+  def self.debugger
+    Utils::Debugger.instance
+  end
+
+  # Builds a new query over the given record set.
+  #
+  # @param records [Enumerable] any enumerable object (Array, AR::Relation, etc.)
+  # @return [QueryBuilder] a new query builder
+  def self.build_query(records)
+    QueryBuilder.new(records)
+  end
+
+  # Registers a class to support `.mongory` query DSL.
+  # This injects a `#mongory` method into the given class.
+  #
+  # @param klass [Class] the class to register (e.g., Array, ActiveRecord::Relation)
+  # @return [void]
+  def self.register(klass)
+    klass.include(ClassExtention)
+  end
+
+  # Enables symbol snippets like `:age.gte` or `:name.regex`
+  # by dynamically defining methods on `Symbol` for query operators.
+  #
+  # Skips operators that already exist to avoid patching Mongoid or other gems.
+  #
+  # @return [void]
+  def self.enable_symbol_snippets!
+    Matchers.enable_symbol_snippets!
+  end
+
+  # Adds a `#mongory` method to the target class via inclusion.
+  #
+  # Typically used internally by `Mongory.register(...)`.
+  module ClassExtention
+    # Returns a query builder scoped to `self`.
+    #
+    # @return [QueryBuilder]
+    def mongory
+      Mongory::QueryBuilder.new(self)
+    end
+  end
+end

data/mongory.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'lib/mongory/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'mongory'
+  spec.version = Mongory::VERSION
+  spec.authors = ['koten0224']
+  spec.email = ['koten0224@gmail.com']
+
+  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.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'
+
+  # 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.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w(bin/ test/ spec/ features/ .git .github appveyor Gemfile))
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency 'example-gem', '~> 1.0'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/mongory.rbs

@@ -0,0 +1,4 @@
+module Mongory
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: mongory
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- koten0224
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-04-19 00:00:00.000000000 Z
+dependencies: []
+description: A Mongo-like in-memory query DSL for Ruby
+email:
+- koten0224@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/README.md
+- examples/benchmark.rb
+- lib/generators/mongory/install/install_generator.rb
+- lib/generators/mongory/install/templates/initializer.rb.erb
+- lib/generators/mongory/matcher/matcher_generator.rb
+- lib/generators/mongory/matcher/templates/matcher.rb.erb
+- lib/generators/mongory/matcher/templates/matcher_spec.rb.erb
+- lib/mongory-rb.rb
+- lib/mongory.rb
+- lib/mongory/converters.rb
+- lib/mongory/converters/abstract_converter.rb
+- lib/mongory/converters/condition_converter.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
+- lib/mongory/matchers/eq_matcher.rb
+- lib/mongory/matchers/every_matcher.rb
+- lib/mongory/matchers/exists_matcher.rb
+- lib/mongory/matchers/field_matcher.rb
+- lib/mongory/matchers/gt_matcher.rb
+- lib/mongory/matchers/gte_matcher.rb
+- lib/mongory/matchers/hash_condition_matcher.rb
+- lib/mongory/matchers/in_matcher.rb
+- lib/mongory/matchers/literal_matcher.rb
+- lib/mongory/matchers/lt_matcher.rb
+- lib/mongory/matchers/lte_matcher.rb
+- lib/mongory/matchers/ne_matcher.rb
+- lib/mongory/matchers/nin_matcher.rb
+- lib/mongory/matchers/not_matcher.rb
+- lib/mongory/matchers/or_matcher.rb
+- lib/mongory/matchers/present_matcher.rb
+- lib/mongory/matchers/regex_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/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/
+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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: MongoDB-like in-memory query DSL for Ruby
+test_files: []