quo 1.0.0.alpha1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dcdc5faff0797696ddb8db26baebe37f388a020943f7764e4857aaab8ef4c76
-  data.tar.gz: 550da1aaaa2bc4d24d82f3e7f78908f22ccd28913b8d9c6358cbc9bbc6ee8fa3
+  metadata.gz: f3e56abbd1094d91702a10b327e82b05a28d7fc44e491316c438059de2c0c229
+  data.tar.gz: 7ebdcfb6b774c274ae30e7eaff556dae898be1f2a8478c5ee1544cfde41dcd25
 SHA512:
-  metadata.gz: 69a94d4d6c4844e6b27e409a662dd76a9ca0dee26fd229a2e861ad377ef2a247ec8499633565d119aa5bc6adeca8930015f33b6ea69e4673d9609f906a1029e5
-  data.tar.gz: d511d04d2212029428e74b2771407e7a3adf566c193a3075fffee3d1c3de7d3e9c8aaca8d39330198264be2ead5df7e574ebd90581600d27d5576eef8718cd0b
+  metadata.gz: ff1b0856ab186d6adfab0274aac9b94a61a0ece421716726b15c762a097f46d2566bcbe53fb04c589bb6d9eb708d91b65303b5cee419c0ae0cdeab193483089f
+  data.tar.gz: 4befea0da9dcbdb6a71f4e447b871e9f0424738f50908bef479f3fd89a2401a5fc861a7ddf124c36ffbfdec5e871b03a0fd75ffcf2941e861465e0ede1ef0f6e

data/.standard.yml

@@ -1,6 +1,6 @@
 # For available configuration options, see:
 #   https://github.com/testdouble/standard
-ruby_version: 3.1
+ruby_version: 3.4
 ignore:
   - "**/*":
     - "Layout/LeadingCommentSpace"

data/Appraisals

@@ -9,3 +9,7 @@ end
 appraise "rails-7.2" do
   gem "rails", "~> 7.2"
 end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0"
+end

data/Gemfile

@@ -18,5 +18,5 @@ group :development, :test do
 
   gem "steep", require: false
 
-  gem "rbs-inline", "~> 0.8.0", require: false
+  gem "rbs-inline", "~> 0.11.0", require: false
 end

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 8.0"
+
+group :development, :test do
+  gem "sqlite3"
+  gem "rake"
+  gem "minitest"
+  gem "standard"
+  gem "steep"
+end
+
+gemspec path: "../"

data/lib/quo/composed_query.rb

@@ -14,44 +14,12 @@ module Quo
     # @rbs joins: untyped
     # @rbs return: singleton(Quo::ComposedQuery)
     def composer(chosen_superclass, left_query_class, right_query_class, joins: nil)
-      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
-      props = {}
-      props.merge!(left_query_class.literal_properties.properties_index) if left_query_class < Quo::Query
-      props.merge!(right_query_class.literal_properties.properties_index) if right_query_class < Quo::Query
-
-      klass = Class.new(chosen_superclass) do
-        include Quo::ComposedQuery
-
-        class << self
-          attr_reader :_composing_joins, :_left_query, :_right_query
-
-          def inspect
-            left_desc = quo_operand_desc(_left_query)
-            right_desc = quo_operand_desc(_right_query)
-            klass_name = (self < Quo::RelationBackedQuery) ? Quo.relation_backed_query_base_class.name : Quo.collection_backed_query_base_class.name
-            "#{klass_name}<Quo::ComposedQuery>[#{left_desc}, #{right_desc}]"
-          end
+      validate_query_classes(left_query_class, right_query_class)
 
-          # @rbs operand: Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation
-          # @rbs return: String
-          def quo_operand_desc(operand)
-            if operand < Quo::ComposedQuery
-              operand.inspect
-            else
-              operand.name || operand.superclass&.name || "(anonymous)"
-            end
-          end
-        end
+      props = collect_properties(left_query_class, right_query_class)
+      klass = create_composed_class(chosen_superclass, props)
 
-        props.each do |name, property|
-          prop name, property.type, property.kind, reader: property.reader, writer: property.writer, default: property.default
-        end
-      end
-      klass.instance_variable_set(:@_composing_joins, joins)
-      klass.instance_variable_set(:@_left_query, left_query_class)
-      klass.instance_variable_set(:@_right_query, right_query_class)
+      assign_query_metadata(klass, left_query_class, right_query_class, joins)
       klass
     end
     module_function :composer
@@ -62,17 +30,18 @@ module Quo
     # @rbs joins: untyped
     # @rbs return: Quo::ComposedQuery
     def merge_instances(left_instance, right_instance, joins: nil)
-      raise ArgumentError, "Cannot merge, left has incompatible type #{left_instance.class}" unless left_instance.is_a?(Quo::Query) || left_instance.is_a?(::ActiveRecord::Relation)
-      raise ArgumentError, "Cannot merge, right has incompatible type #{right_instance.class}" unless right_instance.is_a?(Quo::Query) || right_instance.is_a?(::ActiveRecord::Relation)
+      validate_instances(left_instance, right_instance)
+
       if left_instance.is_a?(Quo::Query) && right_instance.is_a?(::ActiveRecord::Relation)
-        return composer(left_instance.is_a?(Quo::RelationBackedQuery) ? Quo.relation_backed_query_base_class : Quo.collection_backed_query_base_class, left_instance.class, right_instance, joins: joins).new(**left_instance.to_h)
+        return merge_query_and_relation(left_instance, right_instance, joins)
       elsif right_instance.is_a?(Quo::Query) && left_instance.is_a?(::ActiveRecord::Relation)
-        return composer(right_instance.is_a?(Quo::RelationBackedQuery) ? Quo.relation_backed_query_base_class : Quo.collection_backed_query_base_class, left_instance, right_instance.class, joins: joins).new(**right_instance.to_h)
+        return merge_relation_and_query(left_instance, right_instance, joins)
       elsif left_instance.is_a?(Quo::Query) && right_instance.is_a?(Quo::Query)
-        props = left_instance.to_h.merge(right_instance.to_h.compact)
-        return composer((left_instance.is_a?(Quo::RelationBackedQuery) && right_instance.is_a?(Quo::RelationBackedQuery)) ? Quo.relation_backed_query_base_class : Quo.collection_backed_query_base_class, left_instance.class, right_instance.class, joins: joins).new(**props)
+        return merge_query_instances(left_instance, right_instance, joins)
       end
-      composer(Quo.relation_backed_query_base_class, left_instance, right_instance, joins: joins).new # Both are AR relations
+
+      # Both are AR relations
+      composer(Quo.relation_backed_query_base_class, left_instance, right_instance, joins: joins).new
     end
     module_function :merge_instances
 
@@ -87,6 +56,139 @@ module Quo
       "#{klass_name}<Quo::ComposedQuery>[#{self.class.quo_operand_desc(left.class)}, #{self.class.quo_operand_desc(right.class)}](#{super})"
     end
 
+    class << self
+      private
+
+      # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+      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
+
+      # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+      def collect_properties(left_query_class, right_query_class)
+        props = {}
+        props.merge!(left_query_class.literal_properties.properties_index) if left_query_class < Quo::Query
+        props.merge!(right_query_class.literal_properties.properties_index) if right_query_class < Quo::Query
+        props
+      end
+
+      def create_composed_class(chosen_superclass, props)
+        Class.new(chosen_superclass) do
+          include Quo::ComposedQuery
+
+          class << self
+            attr_reader :_composing_joins, :_left_query, :_right_query
+
+            def inspect
+              left_desc = quo_operand_desc(_left_query)
+              right_desc = quo_operand_desc(_right_query)
+              klass_name = determine_class_name
+              "#{klass_name}<Quo::ComposedQuery>[#{left_desc}, #{right_desc}]"
+            end
+
+            # @rbs operand: Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation
+            # @rbs return: String
+            def quo_operand_desc(operand)
+              if operand < Quo::ComposedQuery
+                operand.inspect
+              else
+                operand.name || operand.superclass&.name || "(anonymous)"
+              end
+            end
+
+            private
+
+            # @rbs return: String
+            def determine_class_name
+              if self < Quo::RelationBackedQuery
+                Quo.relation_backed_query_base_class.name
+              else
+                Quo.collection_backed_query_base_class.name
+              end
+            end
+          end
+
+          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: singleton(Quo::Query | ::ActiveRecord::Relation)
+      # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+      # @rbs joins: untyped
+      def assign_query_metadata(klass, left_query_class, right_query_class, joins)
+        klass.instance_variable_set(:@_composing_joins, joins)
+        klass.instance_variable_set(:@_left_query, left_query_class)
+        klass.instance_variable_set(:@_right_query, right_query_class)
+      end
+
+      # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
+      # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
+      def validate_instances(left_instance, right_instance)
+        unless left_instance.is_a?(Quo::Query) || left_instance.is_a?(::ActiveRecord::Relation)
+          raise ArgumentError, "Cannot merge, left has incompatible type #{left_instance.class}"
+        end
+
+        unless right_instance.is_a?(Quo::Query) || right_instance.is_a?(::ActiveRecord::Relation)
+          raise ArgumentError, "Cannot merge, right has incompatible type #{right_instance.class}"
+        end
+      end
+
+      # @rbs relation: ::ActiveRecord::Relation
+      # @rbs query: Quo::Query
+      # @rbs joins: untyped
+      def merge_query_and_relation(query, relation, joins)
+        base_class = query.is_a?(Quo::RelationBackedQuery) ?
+                    Quo.relation_backed_query_base_class :
+                    Quo.collection_backed_query_base_class
+
+        composer(base_class, query.class, relation, joins: joins).new(**query.to_h)
+      end
+
+      # @rbs relation: ::ActiveRecord::Relation
+      # @rbs query: Quo::Query
+      # @rbs joins: untyped
+      def merge_relation_and_query(relation, query, joins)
+        base_class = query.is_a?(Quo::RelationBackedQuery) ?
+                    Quo.relation_backed_query_base_class :
+                    Quo.collection_backed_query_base_class
+
+        composer(base_class, relation, query.class, joins: joins).new(**query.to_h)
+      end
+
+      # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
+      # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
+      def merge_query_instances(left_query, right_query, joins)
+        props = left_query.to_h.merge(right_query.to_h.compact)
+
+        base_class = determine_base_class_for_queries(left_query, right_query)
+        composer(base_class, left_query.class, right_query.class, joins: joins).new(**props)
+      end
+
+      # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
+      # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
+      def determine_base_class_for_queries(left_query, right_query)
+        both_relation_backed = left_query.is_a?(Quo::RelationBackedQuery) &&
+          right_query.is_a?(Quo::RelationBackedQuery)
+
+        both_relation_backed ? Quo.relation_backed_query_base_class :
+                              Quo.collection_backed_query_base_class
+      end
+    end
+
     private
 
     # @rbs return: Hash[Symbol, untyped]
@@ -118,8 +220,9 @@ module Quo
     def merge_left_and_right
       left_rel = quo_unwrap_unpaginated_query(left)
       right_rel = quo_unwrap_unpaginated_query(right)
+
       if both_relations?(left_rel, right_rel)
-        apply_joins(left_rel).merge(right_rel) # ActiveRecord::Relation
+        merge_active_record_relations(left_rel, right_rel)
       elsif left_relation_right_enumerable?(left_rel, right_rel)
         left_rel.to_a + right_rel
       elsif left_enumerable_right_relation?(left_rel, right_rel) && left_rel.respond_to?(:+)
@@ -131,6 +234,13 @@ module Quo
       end
     end
 
+    # @rbs left_rel: ActiveRecord::Relation
+    # @rbs right_rel: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def merge_active_record_relations(left_rel, right_rel)
+      apply_joins(left_rel).merge(right_rel)
+    end
+
     # @rbs left_rel: ActiveRecord::Relation
     # @rbs return: ActiveRecord::Relation
     def apply_joins(left_rel)

data/lib/quo/query.rb

@@ -91,7 +91,6 @@ module Quo
     end
     alias_method :+, :merge
 
-
     # @rbs @__transformer: nil | ^(untyped, ?Integer) -> untyped
 
     # Set a block used to transform data after query fetching

data/lib/quo/relation_backed_query.rb

@@ -48,82 +48,27 @@ module Quo
       sanitize_sql_for_conditions(["?", value])
     end
 
-    # These store options related to building the underlying query, we don't want to expose these as public properties
+    # The query specification stores all options related to building the query
     # @rbs!
-    #   @_rel_group: untyped?
-    #   @_rel_distinct: bool?
-    #   @_rel_order: untyped?
-    #   @_rel_limit: untyped?
-    #   @_rel_preload: untyped?
-    #   @_rel_includes: untyped?
-    #   @_rel_select: untyped?
-    prop :_rel_group, _Nilable(_Any), reader: false, writer: false
-    prop :_rel_distinct, _Nilable(_Boolean), reader: false, writer: false
-    prop :_rel_order, _Nilable(_Any), reader: false, writer: false
-    prop :_rel_limit, _Nilable(_Any), reader: false, writer: false
-    prop :_rel_preload, _Nilable(_Any), reader: false, writer: false
-    prop :_rel_includes, _Nilable(_Any), reader: false, writer: false
-    prop :_rel_select, _Nilable(_Any), reader: false, writer: false
-
-    # Methods to prepare the query
-
-    # SQL 'SELECT' configuration, calls to underlying AR relation
-    # @rbs *options: untyped
+    #   @_specification: Quo::RelationBackedQuerySpecification?
+    prop :_specification, _Nilable(Quo::RelationBackedQuerySpecification),
+      default: -> { RelationBackedQuerySpecification.blank },
+      reader: false,
+      writer: false
+
+    # Apply a query specification to this query
+    # @rbs specification: Quo::RelationBackedQuerySpecification
     # @rbs return: Quo::Query
-    def select(*options)
-      copy(_rel_select: options)
+    def with_specification(specification)
+      copy(_specification: specification)
     end
 
-    # SQL 'LIMIT' configuration, calls to underlying AR relation
-    # @rbs limit: untyped
+    # Apply query options using the specification
+    # @rbs options: Hash[Symbol, untyped]
     # @rbs return: Quo::Query
-    def limit(limit)
-      copy(_rel_limit: limit)
-    end
-
-    # SQL 'ORDER BY' configuration, calls to underlying AR relation
-    # @rbs options: untyped
-    # @rbs return: Quo::Query
-    def order(options)
-      copy(_rel_order: options)
-    end
-
-    # SQL 'GROUP BY' configuration, calls to underlying AR relation
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def group(*options)
-      copy(_rel_group: options)
-    end
-
-    # Configures underlying AR relation to include associations
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def includes(*options)
-      copy(_rel_includes: options)
-    end
-
-    # Configures underlying AR relation to preload associations
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def preload(*options)
-      copy(_rel_preload: options)
-    end
-
-    # Calls to underlying AR distinct method
-    # @rbs enabled: bool
-    # @rbs return: Quo::Query
-    def distinct(enabled = true)
-      copy(_rel_distinct: enabled)
-    end
-
-    # Should these also be exposed? whats the point of exposing AR relation directly?
-    def eager_load
-    end
-
-    def joins
-    end
-
-    def left_outer_joins
+    def with(options = {})
+      spec = @_specification || RelationBackedQuerySpecification.blank
+      with_specification(spec.merge(options))
     end
 
     # Delegate methods that let us get the model class (available on AR relations)
@@ -145,6 +90,35 @@ module Quo
       configured_query.to_sql if relation?
     end
 
+    # Implements a fluent API for query methods
+    # This allows methods to be chained like query.where(...).order(...).limit(...)
+    # @rbs method_name: Symbol
+    # @rbs *args: untyped
+    # @rbs **kwargs: untyped
+    # @rbs &block: untyped
+    # @rbs return: Quo::Query
+    def method_missing(method_name, *args, **kwargs, &block)
+      spec = @_specification || RelationBackedQuerySpecification.blank
+
+      # Check if the method exists in RelationBackedQuerySpecification
+      if spec.respond_to?(method_name)
+        # Call the method on the specification and return a new query with the updated specification
+        updated_spec = spec.method(method_name).call(*args, **kwargs, &block)
+        return with_specification(updated_spec)
+      end
+
+      # Forward to underlying query if method not found in RelationBackedQuerySpecification
+      super
+    end
+
+    # @rbs method_name: Symbol
+    # @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
+    end
+
     private
 
     def validated_query
@@ -157,13 +131,12 @@ module Quo
     def underlying_query #: ActiveRecord::Relation
       rel = quo_unwrap_unpaginated_query(validated_query)
 
-      rel = rel.group(@_rel_group) if @_rel_group.present?
-      rel = rel.distinct if @_rel_distinct
-      rel = rel.order(@_rel_order) if @_rel_order.present?
-      rel = rel.limit(@_rel_limit) if @_rel_limit.present?
-      rel = rel.preload(@_rel_preload) if @_rel_preload.present?
-      rel = rel.includes(@_rel_includes) if @_rel_includes.present?
-      @_rel_select.present? ? rel.select(@_rel_select) : rel
+      # Apply specification if it exists
+      if @_specification
+        @_specification.apply_to(rel)
+      else
+        rel
+      end
     end
 
     # The configured query is the underlying query with paging

data/lib/quo/relation_backed_query_specification.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  # RelationBackedQuerySpecification encapsulates all the options for building a SQL query
+  # This separates the storage of query options from the actual query construction
+  # and provides a cleaner interface for RelationBackedQuery
+  class RelationBackedQuerySpecification
+    # @rbs!
+    #   @options: Hash[Symbol, untyped]
+    attr_reader :options
+
+    # @rbs options: Hash[Symbol, untyped]
+    def initialize(options = {})
+      @options = options
+    end
+
+    # Creates a new specification with merged options
+    # @rbs new_options: Hash[Symbol, untyped]
+    # @rbs return: Quo::QuerySpecification
+    def merge(new_options)
+      self.class.new(options.merge(new_options))
+    end
+
+    # Apply all the specification options to the given ActiveRecord relation
+    # @rbs relation: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def apply_to(relation)
+      rel = relation
+      rel = rel.select(*options[:select]) if options[:select]
+      rel = rel.where(options[:where]) if options[:where]
+      rel = rel.order(options[:order]) if options[:order]
+      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]
+      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]
+      rel = rel.distinct if options[:distinct]
+      rel = rel.reorder(options[:reorder]) if options[:reorder]
+      rel = rel.extending(*options[:extending]) if options[:extending]
+      rel = rel.unscope(options[:unscope]) if options[:unscope]
+      rel
+    end
+
+    # Create helpers for each query option
+
+    # @rbs *fields: untyped
+    # @rbs return: Quo::QuerySpecification
+    def select(*fields)
+      merge(select: fields)
+    end
+
+    # @rbs conditions: untyped
+    # @rbs return: Quo::QuerySpecification
+    def where(conditions)
+      merge(where: conditions)
+    end
+
+    # @rbs order_clause: untyped
+    # @rbs return: Quo::QuerySpecification
+    def order(order_clause)
+      merge(order: order_clause)
+    end
+
+    # @rbs *columns: untyped
+    # @rbs return: Quo::QuerySpecification
+    def group(*columns)
+      merge(group: columns)
+    end
+
+    # @rbs value: Integer
+    # @rbs return: Quo::QuerySpecification
+    def limit(value)
+      merge(limit: value)
+    end
+
+    # @rbs value: Integer
+    # @rbs return: Quo::QuerySpecification
+    def offset(value)
+      merge(offset: value)
+    end
+
+    # @rbs tables: untyped
+    # @rbs return: Quo::QuerySpecification
+    def joins(tables)
+      merge(joins: tables)
+    end
+
+    # @rbs tables: untyped
+    # @rbs return: Quo::QuerySpecification
+    def left_outer_joins(tables)
+      merge(left_outer_joins: tables)
+    end
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def includes(*associations)
+      merge(includes: associations)
+    end
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def preload(*associations)
+      merge(preload: associations)
+    end
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def eager_load(*associations)
+      merge(eager_load: associations)
+    end
+
+    # @rbs enabled: bool
+    # @rbs return: Quo::QuerySpecification
+    def distinct(enabled = true)
+      merge(distinct: enabled)
+    end
+
+    # @rbs order_clause: untyped
+    # @rbs return: Quo::QuerySpecification
+    def reorder(order_clause)
+      merge(reorder: order_clause)
+    end
+
+    # @rbs *modules: untyped
+    # @rbs return: Quo::QuerySpecification
+    def extending(*modules)
+      merge(extending: modules)
+    end
+
+    # @rbs *args: untyped
+    # @rbs return: Quo::QuerySpecification
+    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
+    def self.build(options = {})
+      new(options)
+    end
+
+    # Returns a blank specification
+    # @rbs return: Quo::QuerySpecification
+    def self.blank
+      @blank ||= new
+    end
+  end
+end

data/lib/quo/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Quo
-  VERSION = "1.0.0.alpha1"
+  VERSION = "1.0.0.beta2"
 end

data/lib/quo.rb

@@ -10,6 +10,7 @@ module Quo
 
   autoload :Query
   autoload :Preloadable
+  autoload :RelationBackedQuerySpecification
   autoload :RelationBackedQuery
   autoload :Results
   autoload :RelationResults

data/sig/generated/quo/composed_query.rbs

@@ -11,28 +11,14 @@ module Quo
     # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
     # @rbs joins: untyped
     # @rbs return: singleton(Quo::ComposedQuery)
-    def composer: (untyped chosen_superclass, untyped left_query_class, untyped right_query_class, ?joins: untyped) -> singleton(Quo::ComposedQuery)
-
-    include Quo::ComposedQuery
-
-    attr_reader _composing_joins: untyped
-
-    attr_reader _left_query: untyped
-
-    attr_reader _right_query: untyped
-
-    def self.inspect: () -> untyped
-
-    # @rbs operand: Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation
-    # @rbs return: String
-    def self.quo_operand_desc: (Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation operand) -> String
+    def self?.composer: (untyped chosen_superclass, untyped left_query_class, untyped right_query_class, ?joins: untyped) -> singleton(Quo::ComposedQuery)
 
     # We can also merge instance of prepared queries
     # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
     # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
     # @rbs joins: untyped
     # @rbs return: Quo::ComposedQuery
-    def merge_instances: (Quo::Query | ::ActiveRecord::Relation left_instance, Quo::Query | ::ActiveRecord::Relation right_instance, ?joins: untyped) -> Quo::ComposedQuery
+    def self?.merge_instances: (Quo::Query | ::ActiveRecord::Relation left_instance, Quo::Query | ::ActiveRecord::Relation right_instance, ?joins: untyped) -> Quo::ComposedQuery
 
     # @rbs override
     def query: ...
@@ -40,6 +26,44 @@ module Quo
     # @rbs override
     def inspect: ...
 
+    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    private def self.validate_query_classes: (untyped left_query_class, untyped right_query_class) -> untyped
+
+    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    private def self.collect_properties: (untyped left_query_class, untyped right_query_class) -> untyped
+
+    private def self.create_composed_class: (untyped chosen_superclass, untyped props) -> untyped
+
+    # @rbs klass: Class
+    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs joins: untyped
+    private def self.assign_query_metadata: (Class klass, untyped left_query_class, untyped right_query_class, untyped joins) -> untyped
+
+    # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
+    # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
+    private def self.validate_instances: (Quo::Query | ::ActiveRecord::Relation left_instance, Quo::Query | ::ActiveRecord::Relation right_instance) -> untyped
+
+    # @rbs relation: ::ActiveRecord::Relation
+    # @rbs query: Quo::Query
+    # @rbs joins: untyped
+    private def self.merge_query_and_relation: (Quo::Query query, ::ActiveRecord::Relation relation, untyped joins) -> untyped
+
+    # @rbs relation: ::ActiveRecord::Relation
+    # @rbs query: Quo::Query
+    # @rbs joins: untyped
+    private def self.merge_relation_and_query: (::ActiveRecord::Relation relation, Quo::Query query, untyped joins) -> untyped
+
+    # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
+    # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
+    private def self.merge_query_instances: (Quo::Query | ::ActiveRecord::Relation left_query, Quo::Query | ::ActiveRecord::Relation right_query, untyped joins) -> untyped
+
+    # @rbs left_query: Quo::Query | ::ActiveRecord::Relation
+    # @rbs right_query: Quo::Query | ::ActiveRecord::Relation
+    private def self.determine_base_class_for_queries: (Quo::Query | ::ActiveRecord::Relation left_query, Quo::Query | ::ActiveRecord::Relation right_query) -> untyped
+
     private
 
     # @rbs return: Hash[Symbol, untyped]
@@ -57,6 +81,11 @@ module Quo
     # @rbs return: ActiveRecord::Relation | CollectionBackedQuery
     def merge_left_and_right: () -> (ActiveRecord::Relation | CollectionBackedQuery)
 
+    # @rbs left_rel: ActiveRecord::Relation
+    # @rbs right_rel: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def merge_active_record_relations: (ActiveRecord::Relation left_rel, ActiveRecord::Relation right_rel) -> ActiveRecord::Relation
+
     # @rbs left_rel: ActiveRecord::Relation
     # @rbs return: ActiveRecord::Relation
     def apply_joins: (ActiveRecord::Relation left_rel) -> ActiveRecord::Relation

data/sig/generated/quo/relation_backed_query.rbs

@@ -20,54 +20,17 @@ module Quo
     # @rbs return: String
     def self.sanitize_sql_parameter: (untyped value) -> String
 
-    @_rel_group: untyped?
+    @_specification: Quo::RelationBackedQuerySpecification?
 
-    @_rel_distinct: bool?
-
-    @_rel_order: untyped?
-
-    @_rel_limit: untyped?
-
-    @_rel_preload: untyped?
-
-    @_rel_includes: untyped?
-
-    @_rel_select: untyped?
-
-    # SQL 'SELECT' configuration, calls to underlying AR relation
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def select: (*untyped options) -> Quo::Query
-
-    # SQL 'LIMIT' configuration, calls to underlying AR relation
-    # @rbs limit: untyped
-    # @rbs return: Quo::Query
-    def limit: (untyped limit) -> Quo::Query
-
-    # SQL 'ORDER BY' configuration, calls to underlying AR relation
-    # @rbs options: untyped
+    # Apply a query specification to this query
+    # @rbs specification: Quo::RelationBackedQuerySpecification
     # @rbs return: Quo::Query
-    def order: (untyped options) -> Quo::Query
+    def with_specification: (Quo::RelationBackedQuerySpecification specification) -> Quo::Query
 
-    # SQL 'GROUP BY' configuration, calls to underlying AR relation
-    # @rbs *options: untyped
+    # Apply query options using the specification
+    # @rbs options: Hash[Symbol, untyped]
     # @rbs return: Quo::Query
-    def group: (*untyped options) -> Quo::Query
-
-    # Configures underlying AR relation to include associations
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def includes: (*untyped options) -> Quo::Query
-
-    # Configures underlying AR relation to preload associations
-    # @rbs *options: untyped
-    # @rbs return: Quo::Query
-    def preload: (*untyped options) -> Quo::Query
-
-    # Calls to underlying AR distinct method
-    # @rbs enabled: bool
-    # @rbs return: Quo::Query
-    def distinct: (?bool enabled) -> Quo::Query
+    def with: (?Hash[Symbol, untyped] options) -> Quo::Query
 
     # @rbs return: Quo::CollectionBackedQuery
     def to_collection: (?total_count: untyped) -> Quo::CollectionBackedQuery
@@ -77,6 +40,20 @@ module Quo
     # Return the SQL string for this query if its a relation type query object
     def to_sql: () -> String
 
+    # Implements a fluent API for query methods
+    # This allows methods to be chained like query.where(...).order(...).limit(...)
+    # @rbs method_name: Symbol
+    # @rbs *args: untyped
+    # @rbs **kwargs: untyped
+    # @rbs &block: untyped
+    # @rbs return: Quo::Query
+    def method_missing: (Symbol method_name, *untyped args, **untyped kwargs) ?{ (?) -> untyped } -> Quo::Query
+
+    # @rbs method_name: Symbol
+    # @rbs include_private: bool
+    # @rbs return: bool
+    def respond_to_missing?: (Symbol method_name, ?bool include_private) -> bool
+
     private
 
     def validated_query: () -> untyped

data/sig/generated/quo/relation_backed_query_specification.rbs

@@ -0,0 +1,94 @@
+# Generated from lib/quo/relation_backed_query_specification.rb with RBS::Inline
+
+module Quo
+  # RelationBackedQuerySpecification encapsulates all the options for building a SQL query
+  # This separates the storage of query options from the actual query construction
+  # and provides a cleaner interface for RelationBackedQuery
+  class RelationBackedQuerySpecification
+    # @rbs!
+    #   @options: Hash[Symbol, untyped]
+    attr_reader options: untyped
+
+    # @rbs options: Hash[Symbol, untyped]
+    def initialize: (?Hash[Symbol, untyped] options) -> untyped
+
+    # Creates a new specification with merged options
+    # @rbs new_options: Hash[Symbol, untyped]
+    # @rbs return: Quo::QuerySpecification
+    def merge: (Hash[Symbol, untyped] new_options) -> Quo::QuerySpecification
+
+    # Apply all the specification options to the given ActiveRecord relation
+    # @rbs relation: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def apply_to: (ActiveRecord::Relation relation) -> ActiveRecord::Relation
+
+    # @rbs *fields: untyped
+    # @rbs return: Quo::QuerySpecification
+    def select: (*untyped fields) -> Quo::QuerySpecification
+
+    # @rbs conditions: untyped
+    # @rbs return: Quo::QuerySpecification
+    def where: (untyped conditions) -> Quo::QuerySpecification
+
+    # @rbs order_clause: untyped
+    # @rbs return: Quo::QuerySpecification
+    def order: (untyped order_clause) -> Quo::QuerySpecification
+
+    # @rbs *columns: untyped
+    # @rbs return: Quo::QuerySpecification
+    def group: (*untyped columns) -> Quo::QuerySpecification
+
+    # @rbs value: Integer
+    # @rbs return: Quo::QuerySpecification
+    def limit: (Integer value) -> Quo::QuerySpecification
+
+    # @rbs value: Integer
+    # @rbs return: Quo::QuerySpecification
+    def offset: (Integer value) -> Quo::QuerySpecification
+
+    # @rbs tables: untyped
+    # @rbs return: Quo::QuerySpecification
+    def joins: (untyped tables) -> Quo::QuerySpecification
+
+    # @rbs tables: untyped
+    # @rbs return: Quo::QuerySpecification
+    def left_outer_joins: (untyped tables) -> Quo::QuerySpecification
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def includes: (*untyped associations) -> Quo::QuerySpecification
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def preload: (*untyped associations) -> Quo::QuerySpecification
+
+    # @rbs *associations: untyped
+    # @rbs return: Quo::QuerySpecification
+    def eager_load: (*untyped associations) -> Quo::QuerySpecification
+
+    # @rbs enabled: bool
+    # @rbs return: Quo::QuerySpecification
+    def distinct: (?bool enabled) -> Quo::QuerySpecification
+
+    # @rbs order_clause: untyped
+    # @rbs return: Quo::QuerySpecification
+    def reorder: (untyped order_clause) -> Quo::QuerySpecification
+
+    # @rbs *modules: untyped
+    # @rbs return: Quo::QuerySpecification
+    def extending: (*untyped modules) -> Quo::QuerySpecification
+
+    # @rbs *args: untyped
+    # @rbs return: Quo::QuerySpecification
+    def unscope: (*untyped args) -> Quo::QuerySpecification
+
+    # Builds a new specification from a hash of options
+    # @rbs options: Hash[Symbol, untyped]
+    # @rbs return: Quo::QuerySpecification
+    def self.build: (?Hash[Symbol, untyped] options) -> Quo::QuerySpecification
+
+    # Returns a blank specification
+    # @rbs return: Quo::QuerySpecification
+    def self.blank: () -> Quo::QuerySpecification
+  end
+end

data/sig/generated/quo/testing/collection_backed_fake.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/quo/testing/collection_backed_fake.rb with RBS::Inline
+
+module Quo
+  module Testing
+    class CollectionBackedFake
+      def collection: () -> untyped
+
+      def results: () -> untyped
+
+      def page_count: () -> untyped
+    end
+  end
+end

data/sig/generated/quo/testing/relation_backed_fake.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/quo/testing/relation_backed_fake.rb with RBS::Inline
+
+module Quo
+  module Testing
+    class RelationBackedFake
+      def query: () -> untyped
+
+      def results: () -> untyped
+
+      def page_count: () -> untyped
+
+      def total_count: () -> untyped
+
+      private
+
+      def validated_query: () -> untyped
+
+      def underlying_query: () -> untyped
+
+      def configured_query: () -> untyped
+    end
+  end
+end

data/sig/literal.rbs

@@ -0,0 +1,7 @@
+module Literal
+  class Struct
+  end
+
+  module Types
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Stephen Ierodiaconou
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-16 00:00:00.000000000 Z
+date: 2025-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +18,7 @@ dependencies:
         version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +28,7 @@ dependencies:
         version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +38,7 @@ dependencies:
         version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,14 +48,14 @@ dependencies:
         version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: literal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 1.6.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -66,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 1.6.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -102,6 +101,7 @@ files:
 - gemfiles/rails_7.0.gemfile
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
 - lib/quo.rb
 - lib/quo/collection_backed_query.rb
 - lib/quo/collection_results.rb
@@ -111,6 +111,7 @@ files:
 - lib/quo/preloadable.rb
 - lib/quo/query.rb
 - lib/quo/relation_backed_query.rb
+- lib/quo/relation_backed_query_specification.rb
 - lib/quo/relation_results.rb
 - lib/quo/results.rb
 - lib/quo/rspec/helpers.rb
@@ -127,16 +128,19 @@ files:
 - sig/generated/quo/preloadable.rbs
 - sig/generated/quo/query.rbs
 - sig/generated/quo/relation_backed_query.rbs
+- sig/generated/quo/relation_backed_query_specification.rbs
 - sig/generated/quo/relation_results.rbs
 - sig/generated/quo/results.rbs
+- sig/generated/quo/testing/collection_backed_fake.rbs
+- sig/generated/quo/testing/relation_backed_fake.rbs
 - sig/generated/quo/version.rbs
+- sig/literal.rbs
 homepage: https://github.com/stevegeek/quo
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/stevegeek/quo
   source_code_uri: https://github.com/stevegeek/quo
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -151,8 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Quo is a query object gem for Rails
 test_files: []