quo 0.5.3 → 1.0.0.alpha1

data/lib/quo/composed_query.rb

@@ -0,0 +1,168 @@
+# 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)
+      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
+
+          # @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.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)
+      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)
+      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)
+      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)
+      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)
+      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)
+      end
+      composer(Quo.relation_backed_query_base_class, left_instance, right_instance, joins: joins).new # Both are AR relations
+    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
+
+    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)
+        apply_joins(left_rel).merge(right_rel) # ActiveRecord::Relation
+      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 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

data/lib/quo/query.rb

@@ -1,297 +1,185 @@
 # frozen_string_literal: true
 
-require_relative "./utilities/callstack"
-require_relative "./utilities/compose"
-require_relative "./utilities/sanitize"
-require_relative "./utilities/wrap"
+# rbs_inline: enabled
 
-module Quo
-  class Query
-    include Quo::Utilities::Callstack
-
-    extend Quo::Utilities::Compose
-    extend Quo::Utilities::Sanitize
-    extend Quo::Utilities::Wrap
-
-    class << self
-      def call(**options)
-        new(**options).first
-      end
-
-      def call!(**options)
-        new(**options).first!
-      end
-    end
-
-    attr_reader :current_page, :page_size, :options
+require "literal"
 
-    def initialize(**options)
-      @options = options
-      @current_page = options[:page]&.to_i || options[:current_page]&.to_i
-      @page_size = options[:page_size]&.to_i || Quo.configuration.default_page_size || 20
-    end
-
-    # Returns a active record query, or a Quo::Query instance
-    def query
-      raise NotImplementedError, "Query objects must define a 'query' method"
-    end
+module Quo
+  class Query < Literal::Struct
+    include Literal::Types
 
-    # Combine (compose) this query object with another composeable entity, see notes for `.compose` above.
-    # Compose is aliased as `+`. Can optionally take `joins()` parameters to perform a joins before the merge
-    def compose(right, joins: nil)
-      Quo::QueryComposer.new(self, right, joins).compose
+    def self.inspect
+      "#{name || "(anonymous)"}<#{superclass}>"
     end
 
-    alias_method :+, :compose
-
-    def copy(**options)
-      self.class.new(**@options.merge(options))
+    def self.to_s
+      inspect
     end
 
-    # Methods to prepare the query
-    def limit(limit)
-      copy(limit: limit)
+    def inspect
+      "#{self.class.name || "(anonymous)"}<#{self.class.superclass} #{paged? ? "" : "not "}paginated>#{super}"
     end
 
-    def order(options)
-      copy(order: options)
+    def to_s
+      inspect
     end
 
-    def group(*options)
-      copy(group: options)
+    # TODO: put this in a module with the composer and merge_instances methods
+    # Compose is aliased as `+`. Can optionally take `joins` parameters to add joins on merged relation.
+    # @rbs right: Quo::Query | ActiveRecord::Relation | Object & Enumerable[untyped]
+    # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]
+    # @rbs return: Quo::Query & Quo::ComposedQuery
+    def self.compose(right, joins: nil)
+      super_class = if self < Quo::CollectionBackedQuery || right < Quo::CollectionBackedQuery
+        Quo.collection_backed_query_base_class
+      else
+        Quo.relation_backed_query_base_class
+      end
+      ComposedQuery.composer(super_class, self, right, joins: joins)
     end
+    singleton_class.alias_method :+, :compose
 
-    def includes(*options)
-      copy(includes: options)
+    COERCE_TO_INT = ->(value) do #: (untyped value) -> Integer?
+      return if value == Literal::Null
+      value&.to_i
     end
 
-    def preload(*options)
-      copy(preload: options)
-    end
+    # @rbs!
+    #   attr_accessor page (): Integer?
+    #   attr_accessor page_size (): Integer?
+    #   @current_page: Integer?
+    prop :page, _Nilable(Integer), &COERCE_TO_INT
+    prop(:page_size, _Nilable(Integer), default: -> { Quo.default_page_size || 20 }, &COERCE_TO_INT)
 
-    def select(*options)
-      copy(select: options)
+    def next_page_query #: Quo::Query
+      copy(page: page + 1)
     end
 
-    # The following methods actually execute the underlying query
-
-    # Delegate SQL calculation methods to the underlying query
-    delegate :sum, :average, :minimum, :maximum, to: :query_with_logging
-
-    # Gets the count of all results ignoring the current page and page size (if set)
-    delegate :count, to: :underlying_query
-    alias_method :total_count, :count
-    alias_method :size, :count
-
-    # 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
-      query_with_logging.count
+    def previous_page_query #: Quo::Query
+      copy(page: [page - 1, 1].max)
     end
 
-    # Delegate methods that let us get the model class (available on AR relations)
-    delegate :model, :klass, to: :underlying_query
-
-    # Get first elements
-    def first(limit = nil)
-      if transform?
-        res = query_with_logging.first(limit)
-        if res.is_a? Array
-          res.map.with_index { |r, i| transformer&.call(r, i) }
-        elsif !res.nil?
-          transformer&.call(query_with_logging.first(limit))
-        end
-      elsif limit
-        query_with_logging.first(limit)
+    def offset #: Integer
+      per_page = sanitised_page_size
+      page_with_default = if page&.positive?
+        page
       else
-        # Array#first will not take nil as a limit
-        query_with_logging.first
+        1
       end
+      per_page * (page_with_default - 1)
     end
 
-    def first!(limit = nil)
-      item = first(limit)
-      raise ActiveRecord::RecordNotFound, "No item could be found!" unless item
-      item
+    # Returns a active record query, or a Quo::Query instance
+    def query #: Quo::Query | ::ActiveRecord::Relation
+      raise NotImplementedError, "Query objects must define a 'query' method"
     end
 
-    # Get last elements
-    def last(limit = nil)
-      if transform?
-        res = query_with_logging.last(limit)
-        if res.is_a? Array
-          res.map.with_index { |r, i| transformer&.call(r, i) }
-        elsif !res.nil?
-          transformer&.call(res)
-        end
-      elsif limit
-        query_with_logging.last(limit)
-      else
-        query_with_logging.last
+    # @rbs **overrides: untyped
+    # @rbs return: Quo::Query
+    def copy(**overrides)
+      self.class.new(**to_h.merge(overrides)).tap do |q|
+        q.instance_variable_set(:@__transformer, transformer)
       end
     end
 
-    # Convert to array
-    def to_a
-      arr = query_with_logging.to_a
-      transform? ? arr.map.with_index { |r, i| transformer&.call(r, i) } : arr
-    end
-
-    def to_eager(more_opts = {})
-      Quo::LoadedQuery.new(to_a, **options.merge(more_opts))
+    # Compose is aliased as `+`. Can optionally take `joins` parameters to add joins on merged relation.
+    # @rbs right: Quo::Query | ::ActiveRecord::Relation
+    # @rbs joins: untyped
+    # @rbs return: Quo::ComposedQuery
+    def merge(right, joins: nil)
+      ComposedQuery.merge_instances(self, right, joins: joins)
     end
-    alias_method :load, :to_eager
+    alias_method :+, :merge
 
-    def results
-      Quo::Results.new(self, transformer: transformer)
-    end
 
-    # Some convenience methods for working with results
-    delegate :each,
-      :find_each,
-      :map,
-      :flat_map,
-      :reduce,
-      :reject,
-      :filter,
-      :find,
-      :include?,
-      :each_with_object,
-      to: :results
+    # @rbs @__transformer: nil | ^(untyped, ?Integer) -> untyped
 
     # Set a block used to transform data after query fetching
+    # @rbs block: ^(untyped, ?Integer) -> untyped
+    # @rbs return: self
     def transform(&block)
-      @options[:__transformer] = block
+      @__transformer = block
       self
     end
 
-    # Are there any results for this query?
-    def exists?
-      return query_with_logging.exists? if relation?
-      query_with_logging.present?
-    end
-
-    # Are there no results for this query?
-    def none?
-      !exists?
-    end
-    alias_method :empty?, :none?
-
-    # Is this query object a relation under the hood? (ie not eager loaded)
-    def relation?
+    # Is this query object a ActiveRecord relation under the hood?
+    def relation? #: bool
       test_relation(configured_query)
     end
 
-    # Is this query object eager loaded data under the hood? (ie not a relation)
-    def eager?
-      test_eager(configured_query)
+    # Is this query object loaded data/collection under the hood? (ie not a AR relation)
+    def collection? #: bool
+      is_collection?(configured_query)
     end
 
     # Is this query object paged? (ie is paging enabled)
-    def paged?
-      current_page.present?
+    def paged? #: bool
+      page.present?
     end
 
     # Is this query object transforming results?
-    def transform?
+    def transform? #: bool
       transformer.present?
     end
 
-    # Return the SQL string for this query if its a relation type query object
-    def to_sql
-      configured_query.to_sql if relation?
-    end
-
-    # Unwrap the underlying query
-    def unwrap
+    # Unwrap the paginated query
+    def unwrap #: ActiveRecord::Relation
       configured_query
     end
 
-    delegate :distinct, to: :configured_query
-
-    private
-
-    def formatted_queries?
-      !!Quo.configuration.formatted_query_log
+    # Unwrap the un-paginated query
+    def unwrap_unpaginated #: ActiveRecord::Relation
+      underlying_query
     end
 
-    # 'trim' a query, ie remove comments and remove newlines
-    # This will remove dashes from inside strings too
-    def trim_query(sql)
-      sql.gsub(/--[^\n'"]*\n/m, " ").tr("\n", " ").strip
-    end
+    private
 
-    def format_query(sql_str)
-      formatted_queries? ? sql_str : trim_query(sql_str)
+    def transformer
+      @__transformer
     end
 
-    def transformer
-      options[:__transformer]
+    def validated_query
+      raise NoMethodError, "Query objects must define a 'validated_query' method"
     end
 
-    def offset
-      per_page = sanitised_page_size
-      page = if current_page && current_page&.positive?
-        current_page
-      else
-        1
-      end
-      per_page * (page - 1)
+    # The underlying query is essentially the configured query with optional extras setup
+    def underlying_query #: void
+      raise NoMethodError, "Query objects must define a 'underlying_query' method"
     end
 
     # The configured query is the underlying query with paging
-    def configured_query
-      q = underlying_query
-      return q unless paged? && q.is_a?(ActiveRecord::Relation)
-      q.offset(offset).limit(sanitised_page_size)
+    def configured_query #: void
+      raise NoMethodError, "Query objects must define a 'configured_query' method"
     end
 
-    def sanitised_page_size
-      if page_size && page_size.positive?
+    def sanitised_page_size #: Integer
+      if page_size&.positive?
         given_size = page_size.to_i
-        max_page_size = Quo.configuration.max_page_size || 200
+        max_page_size = Quo.max_page_size || 200
         if given_size > max_page_size
           max_page_size
         else
           given_size
         end
       else
-        Quo.configuration.default_page_size || 20
+        Quo.default_page_size || 20
       end
     end
 
-    def query_with_logging
-      debug_callstack
-      configured_query
-    end
-
-    # The underlying query is essentially the configured query with optional extras setup
-    def underlying_query
-      @underlying_query ||=
-        begin
-          rel = unwrap_relation(query)
-          unless test_eager(rel)
-            rel = rel.group(@options[:group]) if @options[:group].present?
-            rel = rel.order(@options[:order]) if @options[:order].present?
-            rel = rel.limit(@options[:limit]) if @options[:limit].present?
-            rel = rel.preload(@options[:preload]) if @options[:preload].present?
-            rel = rel.includes(@options[:includes]) if @options[:includes].present?
-            rel = rel.select(@options[:select]) if @options[:select].present?
-          end
-          rel
-        end
-    end
-
-    def unwrap_relation(query)
-      query.is_a?(Quo::Query) ? query.unwrap : query
-    end
-
-    def test_eager(rel)
-      rel.is_a?(Quo::LoadedQuery) || (rel.is_a?(Enumerable) && !test_relation(rel))
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def is_collection?(rel)
+      rel.is_a?(Quo::CollectionBackedQuery) || (rel.is_a?(Enumerable) && !test_relation(rel))
     end
 
+    # @rbs rel: untyped
+    # @rbs return: bool
     def test_relation(rel)
       rel.is_a?(ActiveRecord::Relation)
     end
+
+    def quo_unwrap_unpaginated_query(q)
+      q.is_a?(Quo::Query) ? q.unwrap_unpaginated : q
+    end
   end
 end