quo 0.6.0 → 1.0.0.beta1

data/lib/quo/collection_backed_query.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  class CollectionBackedQuery < Query
+    prop :total_count, _Nilable(Integer), reader: false
+
+    # Wrap an enumerable collection or a block that returns an enumerable collection
+    # @rbs data: untyped, props: Symbol => untyped, block: () -> untyped
+    # @rbs return: Quo::CollectionBackedQuery
+    def self.wrap(data = nil, props: {}, &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
+      end
+      if block
+        klass.define_method(:collection, &block)
+      elsif data
+        klass.define_method(:collection) { data }
+      else
+        raise ArgumentError, "either a query or a block must be provided"
+      end
+      # klass.set_temporary_name = "quo::Wrapper" # Ruby 3.3+
+      klass
+    end
+
+    # @rbs return: Object & Enumerable[untyped]
+    def collection
+      raise NotImplementedError, "Collection backed query objects must define a 'collection' method"
+    end
+
+    # The default implementation of `query` just calls `collection`, however you can also
+    # override this method to return an ActiveRecord::Relation or any other query-like object as usual in a Query object.
+    # @rbs return: Object & Enumerable[untyped]
+    def query
+      collection
+    end
+
+    def results
+      Quo::CollectionResults.new(self, transformer: transformer, total_count: @total_count)
+    end
+
+    # @rbs override
+    def relation?
+      false
+    end
+
+    # @rbs override
+    def collection?
+      true
+    end
+
+    # @rbs override
+    def to_collection
+      self
+    end
+
+    private
+
+    def validated_query
+      query
+    end
+
+    # @rbs return: Object & Enumerable[untyped]
+    def underlying_query
+      validated_query
+    end
+
+    # The configured query is the underlying query with paging
+    def configured_query #: Object & Enumerable[untyped]
+      q = underlying_query
+      return q unless paged?
+
+      if q.respond_to?(:[])
+        q[offset, sanitised_page_size]
+      else
+        q
+      end
+    end
+  end
+end

data/lib/quo/collection_results.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  class CollectionResults < Results
+    # @rbs override
+    def initialize(query, transformer: nil, total_count: nil)
+      raise ArgumentError, "Query must be a CollectionBackedQuery" unless query.is_a?(Quo::CollectionBackedQuery)
+      @total_count = total_count
+      @query = query
+      @configured_query = query.unwrap
+      @transformer = transformer
+    end
+
+    # Are there any results for this query?
+    def exists? #: bool
+      @configured_query.present?
+    end
+
+    def empty? #: bool
+      !exists?
+    end
+
+    # Gets the count of all results ignoring the current page and page size (if set).
+    # Optionally return the `total_count` option if it has been set.
+    # This is useful when the total count is known and not equal to size
+    # of wrapped collection.
+    # @rbs override
+    def total_count #: Integer
+      @total_count || @query.unwrap_unpaginated.size
+    end
+
+    # Gets the actual count of elements in the page of results (assuming paging is being used, otherwise the count of
+    # all results)
+    def page_count #: Integer
+      @configured_query.size
+    end
+
+    # @rbs @query: Quo::CollectionBackedQuery
+    # @rbs @transformer: (^(untyped, ?Integer) -> untyped)?
+    # @rbs @configured_query: Object & Enumerable[untyped]
+  end
+end

data/lib/quo/composed_query.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module ComposedQuery
+    # Combine two Query classes into a new composed query class
+    # Combine two query-like or composeable entities:
+    # These can be Quo::Query, Quo::ComposedQuery, Quo::CollectionBackedQuery and ActiveRecord::Relations.
+    # See the `README.md` docs for more details.
+    # @rbs chosen_superclass: singleton(Quo::RelationBackedQuery | Quo::CollectionBackedQuery)
+    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs joins: untyped
+    # @rbs return: singleton(Quo::ComposedQuery)
+    def composer(chosen_superclass, left_query_class, right_query_class, joins: nil)
+      validate_query_classes(left_query_class, right_query_class)
+
+      props = collect_properties(left_query_class, right_query_class)
+      klass = create_composed_class(chosen_superclass, props)
+
+      assign_query_metadata(klass, left_query_class, right_query_class, joins)
+      klass
+    end
+    module_function :composer
+
+    # 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(left_instance, right_instance, joins: nil)
+      validate_instances(left_instance, right_instance)
+
+      if left_instance.is_a?(Quo::Query) && right_instance.is_a?(::ActiveRecord::Relation)
+        return merge_query_and_relation(left_instance, right_instance, joins)
+      elsif right_instance.is_a?(Quo::Query) && left_instance.is_a?(::ActiveRecord::Relation)
+        return merge_relation_and_query(left_instance, right_instance, joins)
+      elsif left_instance.is_a?(Quo::Query) && right_instance.is_a?(Quo::Query)
+        return merge_query_instances(left_instance, right_instance, joins)
+      end
+
+      # Both are AR relations
+      composer(Quo.relation_backed_query_base_class, left_instance, right_instance, joins: joins).new
+    end
+    module_function :merge_instances
+
+    # @rbs override
+    def query
+      merge_left_and_right
+    end
+
+    # @rbs override
+    def inspect
+      klass_name = is_a?(Quo::RelationBackedQuery) ? Quo::RelationBackedQuery.name : Quo::CollectionBackedQuery.name
+      "#{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]
+    def child_options(query_class)
+      names = property_names(query_class)
+      to_h.slice(*names)
+    end
+
+    # @rbs return: Array[Symbol]
+    def property_names(query_class)
+      query_class.literal_properties.properties_index.keys
+    end
+
+    # @rbs return: Quo::Query | ::ActiveRecord::Relation
+    def left
+      lq = self.class._left_query
+      return lq if is_relation?(lq)
+      lq.new(**child_options(lq))
+    end
+
+    # @rbs return: Quo::Query | ::ActiveRecord::Relation
+    def right
+      rq = self.class._right_query
+      return rq if is_relation?(rq)
+      rq.new(**child_options(rq))
+    end
+
+    # @rbs return: ActiveRecord::Relation | CollectionBackedQuery
+    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)
+        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?(:+)
+        left_rel + right_rel.to_a
+      elsif left_rel.respond_to?(:+)
+        left_rel + right_rel
+      else
+        raise ArgumentError, "Cannot merge #{left.class} with #{right.class}"
+      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)
+      joins = self.class._composing_joins
+      joins.present? ? left_rel.joins(joins) : left_rel
+    end
+
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def is_relation?(rel)
+      rel.is_a?(::ActiveRecord::Relation)
+    end
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def both_relations?(left, right)
+      is_relation?(left) && is_relation?(right)
+    end
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def left_relation_right_enumerable?(left, right)
+      is_relation?(left) && !is_relation?(right)
+    end
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def left_enumerable_right_relation?(left, right)
+      !is_relation?(left) && is_relation?(right)
+    end
+  end
+end

data/lib/quo/engine.rb

@@ -0,0 +1,11 @@
+# rbs_inline: enabled
+
+module Quo
+  class Engine < ::Rails::Engine
+    isolate_namespace Quo
+
+    rake_tasks do
+      load "tasks/quo.rake"
+    end
+  end
+end

data/lib/quo/minitest/helpers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "minitest/mock"
+
+require_relative "../testing/collection_backed_fake"
+require_relative "../testing/relation_backed_fake"
+
+module Quo
+  module 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
+
+              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
+          raise ArgumentError, "Not a Query class: #{query_class}"
+        end
+      end
+    end
+  end
+end

data/lib/quo/preloadable.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module Preloadable
+    def self.included(base)
+      base.prop :_rel_preload, base._Nilable(base._Any), reader: false, writer: false
+    end
+
+    # This implementation of `query` calls `collection` and preloads the includes.
+    # @rbs return: Object & Enumerable[untyped]
+    def query
+      records = collection
+      preload_includes(records) if @_rel_preload
+      records
+    end
+
+    # For use with collections of ActiveRecord models.
+    # Configures ActiveRecord::Associations::Preloader to load associations of models in the collection
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def preload(*options)
+      copy(_rel_preload: options)
+    end
+
+    # Alias for `preload`
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def includes(*options)
+      preload(*options)
+    end
+
+    private
+
+    # @rbs @_rel_preload: untyped?
+
+    # @rbs (untyped records, ?untyped? preload) -> untyped
+    def preload_includes(records, preload = nil)
+      ::ActiveRecord::Associations::Preloader.new(
+        records: records,
+        associations: preload || @_rel_preload
+      ).call
+    end
+  end
+end