quo 1.0.0.beta2 → 2.0.0

data/lib/quo/composing/class_strategy.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "base_strategy"
+
+module Quo
+  module Composing
+    # Base class for class composition strategies
+    class ClassStrategy < BaseStrategy
+      # @rbs left_query_class: Class
+      # @rbs right_query_class: Class
+      # @rbs return: void
+      def validate_query_classes(left_query_class, right_query_class)
+        unless left_query_class.respond_to?(:<) && right_query_class.respond_to?(:<)
+          raise ArgumentError, "Cannot compose #{left_query_class} and #{right_query_class}, are they both classes? If you want to use instances use `.merge_instances`"
+        end
+      end
+
+      # Collect properties that need to be (re)defined on the composed class.
+      # Properties already declared on `chosen_superclass` are inherited via the
+      # normal Ruby/Literal class hierarchy and do not need to be re-registered;
+      # skipping them avoids the per-prop Literal::Property allocation, schema
+      # dup, and `module_eval` of reader/writer source on every Class.new.
+      # @rbs chosen_superclass: Class
+      # @rbs left_query_class: Class
+      # @rbs right_query_class: Class
+      # @rbs return: Hash[Symbol, Literal::Property]
+      def collect_properties(chosen_superclass, left_query_class, right_query_class)
+        existing = chosen_superclass.literal_properties.properties_index
+        props = {}
+        if left_query_class < Quo::Query
+          left_query_class.literal_properties.properties_index.each do |name, property|
+            props[name] = property unless existing.key?(name)
+          end
+        end
+        if right_query_class < Quo::Query
+          right_query_class.literal_properties.properties_index.each do |name, property|
+            props[name] = property unless existing.key?(name)
+          end
+        end
+        props
+      end
+
+      # @rbs chosen_superclass: Class
+      # @rbs props: Hash[Symbol, Literal::Property]
+      # @rbs return: Class & Quo::ComposedQuery
+      def create_composed_class(chosen_superclass, props)
+        Class.new(chosen_superclass) do
+          include Quo::ComposedQuery
+          props.each do |name, property|
+            prop(
+              name,
+              property.type,
+              property.kind,
+              reader: property.reader,
+              writer: property.writer,
+              default: property.default
+            )
+          end
+        end
+      end
+
+      # @rbs klass: Class
+      # @rbs left_query_class: Class
+      # @rbs right_query_class: Class
+      # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]?
+      # @rbs left_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs right_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs return: void
+      def assign_query_metadata(klass, left_query_class, right_query_class, joins, left_spec, right_spec)
+        # merge spec and joins
+        left_joins = left_spec ? left_spec[:joins] : []
+        left_joins = left_joins.is_a?(Array) ? left_joins : [left_joins]
+        joins = joins.is_a?(Array) ? joins : [joins] if joins
+        merge_left_joins = joins ? joins + left_joins : left_joins
+
+        klass.instance_variable_set(:@_composing_joins, merge_left_joins)
+        klass.instance_variable_set(:@_left_specification, left_spec)
+        klass.instance_variable_set(:@_right_specification, right_spec)
+        klass.instance_variable_set(:@_left_query, left_query_class)
+        klass.instance_variable_set(:@_right_query, right_query_class)
+      end
+    end
+  end
+end

data/lib/quo/composing/class_strategy_registry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "query_classes_strategy"
+
+module Quo
+  module Composing
+    # Registry for class composition strategies
+    class ClassStrategyRegistry
+      # @rbs return: Array[Quo::Composing::BaseStrategy]
+      def strategies
+        @strategies ||= [
+          QueryClassesStrategy.new
+          # Add more class strategies as needed
+        ]
+      end
+
+      # @rbs left: Class
+      # @rbs right: Class
+      # @rbs return: Quo::Composing::BaseStrategy
+      def find_strategy(left, right)
+        strategy = strategies.find { |s| s.applicable?(left, right) }
+        unless strategy
+          raise ArgumentError, "No class composition strategy found for #{left.class} and #{right.class}"
+        end
+        strategy
+      end
+    end
+  end
+end

data/lib/quo/composing/query_classes_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "class_strategy"
+
+module Quo
+  module Composing
+    # Strategy for composing two Query classes
+    class QueryClassesStrategy < ClassStrategy
+      # @rbs override
+      # @rbs left: Class
+      # @rbs right: Class
+      # @rbs return: bool
+      def applicable?(left, right)
+        left.respond_to?(:<) && right.respond_to?(:<) &&
+          (left < Quo::Query || left.is_a?(::ActiveRecord::Relation)) &&
+          (right < Quo::Query || right.is_a?(::ActiveRecord::Relation))
+      end
+
+      # @rbs override
+      # @rbs chosen_superclass: Class
+      # @rbs left_query_class: Class
+      # @rbs right_query_class: Class
+      # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]?
+      # @rbs left_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs right_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs return: Class & Quo::ComposedQuery
+      def compose(chosen_superclass, left_query_class, right_query_class, joins: nil, left_spec: nil, right_spec: nil)
+        validate_query_classes(left_query_class, right_query_class)
+        props = collect_properties(chosen_superclass, left_query_class, right_query_class)
+        klass = create_composed_class(chosen_superclass, props)
+        assign_query_metadata(klass, left_query_class, right_query_class, joins, left_spec, right_spec)
+        klass
+      end
+    end
+  end
+end

data/lib/quo/composing.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require_relative "composing/class_strategy_registry"
+
+module Quo
+  module Composing
+    CLASS_STRATEGY_REGISTRY = ClassStrategyRegistry.new
+
+    class << self
+      # @rbs chosen_superclass: Class
+      # @rbs left_query_class: Class
+      # @rbs right_query_class: Class
+      # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]?
+      # @rbs left_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs right_spec: Quo::RelationBackedQuerySpecification?
+      # @rbs return: Class & Quo::ComposedQuery
+      def composer(chosen_superclass, left_query_class, right_query_class, joins: nil, left_spec: nil, right_spec: nil)
+        strategy = CLASS_STRATEGY_REGISTRY.find_strategy(left_query_class, right_query_class)
+        strategy.compose(chosen_superclass, left_query_class, right_query_class, joins: joins, left_spec: left_spec, right_spec: right_spec)
+      end
+
+      # @rbs left_instance: Quo::Query
+      # @rbs right_instance: Quo::Query | ActiveRecord::Relation | Object & Enumerable[untyped]
+      # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]?
+      # @rbs return: Quo::Query
+      def merge_instances(left_instance, right_instance, joins: nil)
+        page, page_size = inherited_pagination(left_instance, right_instance)
+        transformer = inherited_transformer(left_instance, right_instance)
+
+        opts = {left: left_instance, right: right_instance, merge_joins: joins}
+        opts[:page] = page if page
+        opts[:page_size] = page_size if page_size
+
+        composed = if relation_backed?(left_instance) || relation_backed?(right_instance)
+          Quo::ComposedRelationBackedQuery.new(**opts)
+        else
+          Quo::ComposedCollectionBackedQuery.new(**opts)
+        end
+
+        composed.transform(&transformer) if transformer
+        composed
+      end
+
+      private
+
+      # @rbs operand: untyped
+      # @rbs return: bool
+      def relation_backed?(operand)
+        operand.is_a?(Quo::RelationBackedQuery) || operand.is_a?(::ActiveRecord::Relation)
+      end
+
+      # @rbs left: untyped
+      # @rbs right: untyped
+      # @rbs return: Array[Integer?]
+      def inherited_pagination(left, right)
+        operand = pagination_source(right) || pagination_source(left)
+        return [nil, nil] unless operand
+        [operand.page, operand.page_size]
+      end
+
+      # @rbs operand: untyped
+      # @rbs return: untyped
+      def pagination_source(operand)
+        return nil unless operand.respond_to?(:page) && operand.respond_to?(:page_size)
+        operand.page ? operand : nil
+      end
+
+      # @rbs left: untyped
+      # @rbs right: untyped
+      # @rbs return: Proc?
+      def inherited_transformer(left, right)
+        right_transformer = left_transformer = nil
+        right_transformer = right.send(:transformer) if right.is_a?(Quo::Query) && right.transform?
+        left_transformer = left.send(:transformer) if left.is_a?(Quo::Query) && left.transform?
+        right_transformer || left_transformer
+      end
+    end
+  end
+end

data/lib/quo/engine.rb

@@ -1,6 +1,7 @@
 # rbs_inline: enabled
 
 module Quo
+  # Rails engine for integrating Quo with Rails applications
   class Engine < ::Rails::Engine
     isolate_namespace Quo
 

data/lib/quo/minitest/helpers.rb

@@ -1,40 +1,30 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "minitest/mock"
 
 require_relative "../testing/collection_backed_fake"
 require_relative "../testing/relation_backed_fake"
+require_relative "../testing/fake_helpers"
 
 module Quo
   module Minitest
+    # Test helpers for stubbing query objects in Minitest
     module Helpers
-      def fake_query(query_class, results: [], total_count: nil, page_count: nil, &block)
-        # make it so that results of instances of this class return a fake Result object
-        # of the right type which returns the results passed in
-        if query_class < Quo::CollectionBackedQuery
-          klass = Class.new(Quo::Testing::CollectionBackedFake) do
-            if query_class < Quo::Preloadable
-              include Quo::Preloadable
+      include Quo::Testing::FakeHelpers
 
-              def query
-                collection
-              end
-            end
-          end
-          query_class.stub(:new, ->(**kwargs) {
-            klass.new(results: results, total_count: total_count, page_count: page_count)
-          }) do
-            yield
-          end
-        elsif query_class < Quo::RelationBackedQuery
-          query_class.stub(:new, ->(**kwargs) {
-            Quo::Testing::RelationBackedFake.new(results: results, total_count: total_count, page_count: page_count)
-          }) do
-            yield
-          end
-        else
+      def fake_query(query_class, results: [], total_count: nil, page_count: nil, &block)
+        unless query_class < Quo::Query
           raise ArgumentError, "Not a Query class: #{query_class}"
         end
+
+        klass = build_fake_class(query_class)
+        query_class.stub(:new, ->(**kwargs) {
+          klass.new(results: results, total_count: total_count, page_count: page_count)
+        }) do
+          yield
+        end
       end
     end
   end

data/lib/quo/preloadable.rb

@@ -3,6 +3,7 @@
 # rbs_inline: enabled
 
 module Quo
+  # Mixin for adding preload/includes support to collection-backed queries
   module Preloadable
     def self.included(base)
       base.prop :_rel_preload, base._Nilable(base._Any), reader: false, writer: false

data/lib/quo/query.rb

@@ -2,24 +2,27 @@
 
 # rbs_inline: enabled
 
-require "literal"
-
 module Quo
+  # Base class for query objects with pagination and composition support
   class Query < Literal::Struct
     include Literal::Types
 
+    # @rbs override
     def self.inspect
       "#{name || "(anonymous)"}<#{superclass}>"
     end
 
+    # @rbs override
     def self.to_s
       inspect
     end
 
+    # @rbs override
     def inspect
       "#{self.class.name || "(anonymous)"}<#{self.class.superclass} #{paged? ? "" : "not "}paginated>#{super}"
     end
 
+    # @rbs override
     def to_s
       inspect
     end
@@ -35,12 +38,26 @@ module Quo
       else
         Quo.relation_backed_query_base_class
       end
-      ComposedQuery.composer(super_class, self, right, joins: joins)
+      Composing.composer(super_class, self, right, joins: joins)
     end
     singleton_class.alias_method :+, :compose
 
+    # Helper method to define properties on a dynamically created class
+    # @rbs klass: Class
+    # @rbs props: Hash[Symbol, untyped]
+    # @rbs return: void
+    def self.define_props_on_class(klass, props)
+      props.each do |name, property|
+        if property.is_a?(Literal::Property)
+          klass.prop name, property.type, property.kind, reader: property.reader, writer: property.writer, default: property.default
+        else
+          klass.prop name, property
+        end
+      end
+    end
+
     COERCE_TO_INT = ->(value) do #: (untyped value) -> Integer?
-      return if value == Literal::Null
+      return if value.equal?(Literal::Undefined)
       value&.to_i
     end
 
@@ -87,7 +104,7 @@ module Quo
     # @rbs joins: untyped
     # @rbs return: Quo::ComposedQuery
     def merge(right, joins: nil)
-      ComposedQuery.merge_instances(self, right, joins: joins)
+      Composing.merge_instances(self, right, joins: joins)
     end
     alias_method :+, :merge
 

data/lib/quo/relation_backed_query.rb

@@ -2,26 +2,24 @@
 
 # rbs_inline: enabled
 
-require "literal"
-
 module Quo
+  # Query object backed by ActiveRecord relations
   class RelationBackedQuery < Query
-    # @rbs query: ActiveRecord::Relation | Quo::Query
+    # @rbs query: ActiveRecord::Relation | Quo::RelationBackedQuery
     # @rbs props: Hash[Symbol, untyped]
-    # @rbs &block: () -> ActiveRecord::Relation | Quo::Query | Object & Enumerable[untyped]
+    # @rbs &block: ? () -> (ActiveRecord::Relation | Quo::Query)
     # @rbs return: Quo::RelationBackedQuery
     def self.wrap(query = nil, props: {}, &block)
       raise ArgumentError, "either a query or a block must be provided" unless query || block
 
-      klass = Class.new(self) do
-        props.each do |name, property|
-          if property.is_a?(Literal::Property)
-            prop name, property.type, property.kind, reader: property.reader, writer: property.writer, default: property.default
-          else
-            prop name, property
-          end
-        end
+      if query && !(query.is_a?(::ActiveRecord::Relation) || query.is_a?(Quo::RelationBackedQuery))
+        raise ArgumentError,
+          "Quo::RelationBackedQuery.wrap requires an ActiveRecord::Relation or a Quo::RelationBackedQuery instance; got #{query.class}. " \
+          "Use Quo::CollectionBackedQuery.wrap or Quo::CollectionBackedQuery.from for in-memory collections."
       end
+
+      klass = Class.new(self)
+      define_props_on_class(klass, props)
       if block
         klass.define_method(:query, &block)
       else
@@ -30,6 +28,12 @@ module Quo
       klass
     end
 
+    # @rbs relation: ActiveRecord::Relation
+    # @rbs return: Quo::WrappedRelationBackedQuery
+    def self.from(relation)
+      Quo::WrappedRelationBackedQuery.new(wrapped: relation)
+    end
+
     # @rbs conditions: untyped?
     # @rbs return: String
     def self.sanitize_sql_for_conditions(conditions)
@@ -53,7 +57,6 @@ module Quo
     #   @_specification: Quo::RelationBackedQuerySpecification?
     prop :_specification, _Nilable(Quo::RelationBackedQuerySpecification),
       default: -> { RelationBackedQuerySpecification.blank },
-      reader: false,
       writer: false
 
     # Apply a query specification to this query
@@ -72,10 +75,12 @@ module Quo
     end
 
     # Delegate methods that let us get the model class (available on AR relations)
-    # @rbs def model: () -> (untyped | nil)
-    # @rbs def klass: () -> (untyped | nil)
+    # @rbs!
+    #   def model: () -> (untyped | nil)
+    #   def klass: () -> (untyped | nil)
     delegate :model, :klass, to: :underlying_query
 
+    # @rbs total_count: Integer?
     # @rbs return: Quo::CollectionBackedQuery
     def to_collection(total_count: nil)
       Quo.collection_backed_query_base_class.wrap(results.to_a).new(total_count:)
@@ -86,7 +91,7 @@ module Quo
     end
 
     # Return the SQL string for this query if its a relation type query object
-    def to_sql #: String
+    def to_sql #: String?
       configured_query.to_sql if relation?
     end
 
@@ -115,8 +120,9 @@ module Quo
     # @rbs include_private: bool
     # @rbs return: bool
     def respond_to_missing?(method_name, include_private = false)
-      spec_instance = RelationBackedQuerySpecification.new
-      spec_instance.respond_to?(method_name, include_private) || super
+      # Reuse the memoized blank specification rather than allocating a fresh
+      # instance per probe — ActiveRecord's delegation hits respond_to? heavily.
+      RelationBackedQuerySpecification.blank.respond_to?(method_name, include_private) || super
     end
 
     private

data/lib/quo/relation_backed_query_specification.rb

@@ -17,9 +17,10 @@ module Quo
     end
 
     # Creates a new specification with merged options
-    # @rbs new_options: Hash[Symbol, untyped]
-    # @rbs return: Quo::QuerySpecification
+    # @rbs new_options: Hash[Symbol, untyped] | RelationBackedQuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def merge(new_options)
+      new_options = new_options.options if new_options.is_a?(self.class)
       self.class.new(options.merge(new_options))
     end
 
@@ -34,8 +35,12 @@ module Quo
       rel = rel.group(*options[:group]) if options[:group]
       rel = rel.limit(options[:limit]) if options[:limit]
       rel = rel.offset(options[:offset]) if options[:offset]
-      rel = rel.joins(options[:joins]) if options[:joins]
-      rel = rel.left_outer_joins(options[:left_outer_joins]) if options[:left_outer_joins]
+      if (joins = options[:joins])
+        rel = joins.is_a?(Array) ? rel.joins(*joins) : rel.joins(joins)
+      end
+      if (left_outer_joins = options[:left_outer_joins])
+        rel = left_outer_joins.is_a?(Array) ? rel.left_outer_joins(*left_outer_joins) : rel.left_outer_joins(left_outer_joins)
+      end
       rel = rel.includes(*options[:includes]) if options[:includes]
       rel = rel.preload(*options[:preload]) if options[:preload]
       rel = rel.eager_load(*options[:eager_load]) if options[:eager_load]
@@ -46,107 +51,121 @@ module Quo
       rel
     end
 
+    # Introspection
+
+    # @rbs key: Symbol
+    # @rbs return: bool
+    def has?(key)
+      options.key?(key)
+    end
+
+    # @rbs key: Symbol
+    # @rbs return: untyped
+    def [](key)
+      options[key]
+    end
+
     # Create helpers for each query option
 
     # @rbs *fields: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def select(*fields)
       merge(select: fields)
     end
 
     # @rbs conditions: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def where(conditions)
       merge(where: conditions)
     end
 
     # @rbs order_clause: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def order(order_clause)
       merge(order: order_clause)
     end
 
     # @rbs *columns: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def group(*columns)
       merge(group: columns)
     end
 
     # @rbs value: Integer
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def limit(value)
       merge(limit: value)
     end
 
     # @rbs value: Integer
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def offset(value)
       merge(offset: value)
     end
 
-    # @rbs tables: untyped
-    # @rbs return: Quo::QuerySpecification
-    def joins(tables)
+    # @rbs *tables: untyped
+    # @rbs return: Quo::RelationBackedQuerySpecification
+    def joins(*tables)
       merge(joins: tables)
     end
 
-    # @rbs tables: untyped
-    # @rbs return: Quo::QuerySpecification
-    def left_outer_joins(tables)
+    # @rbs *tables: untyped
+    # @rbs return: Quo::RelationBackedQuerySpecification
+    def left_outer_joins(*tables)
       merge(left_outer_joins: tables)
     end
 
     # @rbs *associations: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def includes(*associations)
       merge(includes: associations)
     end
 
     # @rbs *associations: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def preload(*associations)
       merge(preload: associations)
     end
 
     # @rbs *associations: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def eager_load(*associations)
       merge(eager_load: associations)
     end
 
     # @rbs enabled: bool
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def distinct(enabled = true)
       merge(distinct: enabled)
     end
 
     # @rbs order_clause: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def reorder(order_clause)
       merge(reorder: order_clause)
     end
 
     # @rbs *modules: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def extending(*modules)
       merge(extending: modules)
     end
 
     # @rbs *args: untyped
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def unscope(*args)
       merge(unscope: args)
     end
 
     # Builds a new specification from a hash of options
     # @rbs options: Hash[Symbol, untyped]
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def self.build(options = {})
       new(options)
     end
 
     # Returns a blank specification
-    # @rbs return: Quo::QuerySpecification
+    # @rbs return: Quo::RelationBackedQuerySpecification
     def self.blank
       @blank ||= new
     end

data/lib/quo/relation_results.rb

@@ -3,6 +3,7 @@
 # rbs_inline: enabled
 
 module Quo
+  # Results wrapper for relation-backed queries providing pagination and counting
   class RelationResults < Results
     # @rbs query: Quo::Query
     # @rbs transformer: (^(untyped, ?Integer) -> untyped)?