mongory 0.7.3-x86_64-linux-musl

data/lib/mongory/query_builder.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module Mongory
+  # QueryBuilder provides a Mongo-like in-memory query interface.
+  #
+  # It supports condition chaining (`where`, `or`, `not`),
+  # limiting, and plucking fields.
+  #
+  # Internally it compiles all conditions and invokes `QueryMatcher`.
+  #
+  # @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
+
+    # Initializes a new query builder with the given record set.
+    #
+    # @param records [Enumerable] the collection to query against
+    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] 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] 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] 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>] the conditions to add
+    # @return [QueryBuilder] a new builder instance
+    def and(*conditions)
+      dup_instance_exec do
+        add_conditions('$and', conditions)
+      end
+    end
+
+    # Adds one or more conditions combined with `$or`.
+    # Any condition can match for a record to be included.
+    #
+    # @param conditions [Array<Hash>] the conditions to add
+    # @return [QueryBuilder] a new builder instance
+    def or(*conditions)
+      operator = '$or'
+      dup_instance_exec do
+        if @matcher.condition.each_key.all? { |k| k == operator }
+          add_conditions(operator, conditions)
+        else
+          set_matcher(operator => [@matcher.condition.dup, *conditions])
+        end
+      end
+    end
+
+    # Adds a `$or` query combined inside an `$and` block.
+    # This is a semantic alias for `.and('$or' => [...])`
+    #
+    # @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] the maximum number of records to return
+    # @return [QueryBuilder] a new builder instance
+    def limit(count)
+      dup_instance_exec do
+        @records = take(count)
+      end
+    end
+
+    # Extracts selected fields from matching records.
+    #
+    # @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] }
+      else
+        fields.unshift(field)
+        map { |record| fields.map { |key| record[key] } }
+      end
+    end
+
+    # Returns the raw parsed condition for this query.
+    #
+    # @return [Hash] the raw compiled condition
+    def raw_condition
+      @matcher.condition
+    end
+
+    # 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.
+    # This is useful for debugging and visualizing complex conditions.
+    #
+    # @return [void]
+    def explain
+      @matcher.match?(@records.first)
+      @matcher.render_tree
+      nil
+    end
+
+    def c
+      return self unless defined?(Mongory::CMatcher)
+
+      c_builder = CQueryBuilder.new(@records, context: @context)
+      c_builder.send(:set_matcher, @matcher.condition)
+      c_builder
+    end
+
+    private
+
+    # @private
+    # Duplicates the query and executes the block in context.
+    #
+    # @return [QueryBuilder] the modified duplicate
+    def dup_instance_exec(&block)
+      dup.tap do |obj|
+        obj.instance_exec(&block)
+      end
+    end
+
+    # @private
+    # Builds the internal matcher tree from a condition hash.
+    # Used to eagerly parse conditions to improve inspect/debug visibility.
+    #
+    # @param condition [Hash] the condition to build the matcher from
+    # @return [void]
+    def set_matcher(condition = {})
+      @matcher = QueryMatcher.new(condition, context: @context)
+    end
+
+    # @private
+    # Merges additional conditions into the matcher.
+    #
+    # @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 = {}.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 }
+      end
+    end
+  end
+end

data/lib/mongory/query_matcher.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module Mongory
+  # The top-level matcher for compiled query conditions.
+  #
+  # Delegates to {Matchers::LiteralMatcher} after transforming input
+  # via {Converters::ConditionConverter}.
+  #
+  # Typically used internally by `QueryBuilder`.
+  #
+  # Conversion via Mongory.data_converter is applied to the record
+  # before matching to ensure consistent data types.
+  #
+  # @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::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`.
+    # @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
+
+    # 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.
+    #
+    # @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.
+    #
+    # Subclasses or internal matchers should implement their own
+    # `#render_tree(prefix, is_last:)` for internal recursion.
+    #
+    # @return [void]
+    # @see Matchers::LiteralMatcher#render_tree
+    def render_tree
+      super
+    end
+
+    # Prepares the query for execution by ensuring all necessary matchers are initialized.
+    # This is called before query execution to avoid premature matcher tree construction.
+    #
+    # @return [void]
+    alias_method :prepare_query, :check_validity!
+
+    # Overrides the parent class's check_validity! to prevent premature matcher tree construction.
+    # This matcher does not require validation, so this is a no-op.
+    #
+    # @return [void]
+    def check_validity!
+      # No-op for this matcher
+    end
+  end
+end

data/lib/mongory/query_operator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mongory
+  # Wrapper for symbol-based operator expressions.
+  #
+  # Used to support DSL like `:age.gt => 18` where `gt` maps to `$gt`.
+  # Converts into: `{ "age" => { "$gt" => 18 } }`
+  class QueryOperator
+    # Initializes a new query operator wrapper.
+    #
+    # @param name [String] the original field name
+    # @param operator [String] the Mongo-style operator (e.g., '$gt')
+    def initialize(name, operator)
+      @name = name
+      @operator = operator
+    end
+
+    # Converts the operator and value into a condition hash.
+    #
+    # Typically called by the key converter.
+    #
+    # @param other [Object] the value to match against
+    # @return [Hash] converted query condition
+    def __expr_part__(other, *)
+      { @name => { @operator => other } }
+    end
+  end
+end

data/lib/mongory/rails.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails'
+require_relative 'utils/rails_patch'
+
+module Mongory
+  # @see Utils::RailsPatch
+  class Railtie < Rails::Railtie
+    initializer 'mongory.patch_utils' do
+      [Mongory::Utils, *Mongory::Utils.included_classes].each do |klass|
+        klass.prepend(Mongory::Utils::RailsPatch)
+      end
+    end
+  end
+end

data/lib/mongory/utils/context.rb

@@ -0,0 +1,48 @@
+# 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
+
+      def to_hash
+        {
+          config: @config,
+          need_convert: @need_convert
+        }
+      end
+    end
+  end
+end

data/lib/mongory/utils/debugger.rb

@@ -0,0 +1,125 @@
+# 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 `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 :to_proc, :debug_proc
+      end
+
+      # 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 :to_proc, :cached_proc
+      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,76 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'utils/singleton_builder'
+require_relative 'utils/debugger'
+require_relative 'utils/context'
+
+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, Set
+        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