quo 0.6.0 → 1.0.0.alpha1

data/lib/quo/relation_backed_query.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "literal"
+
+module Quo
+  class RelationBackedQuery < Query
+    # @rbs query: ActiveRecord::Relation | Quo::Query
+    # @rbs props: Hash[Symbol, untyped]
+    # @rbs &block: () -> ActiveRecord::Relation | Quo::Query | Object & Enumerable[untyped]
+    # @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
+      end
+      if block
+        klass.define_method(:query, &block)
+      else
+        klass.define_method(:query) { query }
+      end
+      klass
+    end
+
+    # @rbs conditions: untyped?
+    # @rbs return: String
+    def self.sanitize_sql_for_conditions(conditions)
+      ActiveRecord::Base.sanitize_sql_for_conditions(conditions)
+    end
+
+    # @rbs string: String
+    # @rbs return: String
+    def self.sanitize_sql_string(string)
+      sanitize_sql_for_conditions(["'%s'", string])
+    end
+
+    # @rbs value: untyped
+    # @rbs return: String
+    def self.sanitize_sql_parameter(value)
+      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
+    # @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
+    # @rbs return: Quo::Query
+    def select(*options)
+      copy(_rel_select: options)
+    end
+
+    # SQL 'LIMIT' configuration, calls to underlying AR relation
+    # @rbs limit: 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
+    end
+
+    # Delegate methods that let us get the model class (available on AR relations)
+    # @rbs def model: () -> (untyped | nil)
+    # @rbs def klass: () -> (untyped | nil)
+    delegate :model, :klass, to: :underlying_query
+
+    # @rbs return: Quo::CollectionBackedQuery
+    def to_collection(total_count: nil)
+      Quo.collection_backed_query_base_class.wrap(results.to_a).new(total_count:)
+    end
+
+    def results #: Quo::Results
+      Quo::RelationResults.new(self, transformer: transformer)
+    end
+
+    # Return the SQL string for this query if its a relation type query object
+    def to_sql #: String
+      configured_query.to_sql if relation?
+    end
+
+    private
+
+    def validated_query
+      query.tap do |q|
+        raise ArgumentError, "#query must return an ActiveRecord Relation or a Quo::Query instance" unless query.nil? || q.is_a?(::ActiveRecord::Relation) || q.is_a?(Quo::Query)
+      end
+    end
+
+    # The underlying query is essentially the configured query with optional extras setup
+    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
+    end
+
+    # The configured query is the underlying query with paging
+    def configured_query #: ActiveRecord::Relation
+      q = underlying_query
+      return q unless paged?
+
+      q.offset(offset).limit(sanitised_page_size)
+    end
+  end
+end

data/lib/quo/relation_results.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  class RelationResults < Results
+    # @rbs query: Quo::Query
+    # @rbs transformer: (^(untyped, ?Integer) -> untyped)?
+    # @rbs return: void
+    def initialize(query, transformer: nil)
+      raise ArgumentError, "Query must be a RelationBackedQuery" unless query.is_a?(Quo::RelationBackedQuery)
+      @query = query
+      @configured_query = query.unwrap
+      @transformer = transformer
+    end
+
+    # Are there any results for this query?
+    def exists? #: bool
+      return @configured_query.exists? if @query.relation?
+      @configured_query.present?
+    end
+
+    # Gets the count of all results ignoring the current page and page size (if set).
+    def total_count #: Integer
+      count_query(@query.unwrap_unpaginated)
+    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
+      count_query(@configured_query)
+    end
+
+    private
+
+    # @rbs @query: Quo::RelationBackedQuery
+    # @rbs @configured_query: ActiveRecord::Relation
+
+    # Note we reselect the query as this prevents query errors if the SELECT clause is not compatible with COUNT
+    # (SQLException: wrong number of arguments to function COUNT()). We do this in two ways, either with the primary key
+    # or with Arel.star. The primary key is the most compatible way to count, but if the query does not have a primary
+    # we fallback. The fallback "*" wont work in certain situations though, specifically if we have a limit() on the query
+    # which Arel constructs as a subquery. In this case we will get a SQL error as the generated SQL contains
+    # `SELECT COUNT(count_column) FROM (SELECT * AS count_column FROM ...) subquery_for_count` where the error is:
+    # `ActiveRecord::StatementInvalid: SQLite3::SQLException: near "AS": syntax error`
+    # Either way DB engines know how to count efficiently.
+    # @rbs query: ActiveRecord::Relation
+    # @rbs return: Integer
+    def count_query(query)
+      pk = query.model.primary_key
+      if pk
+        query.reselect(pk).count
+      else
+        query.reselect(Arel.star).count
+      end
+    end
+  end
+end

data/lib/quo/results.rb

@@ -1,85 +1,89 @@
 # frozen_string_literal: true
 
-require "forwardable"
-require_relative "./utilities/callstack"
+# rbs_inline: enabled
 
 module Quo
   class Results
-    extend Forwardable
-    include Quo::Utilities::Callstack
+    def empty? #: bool
+      !exists?
+    end
 
-    def initialize(query, transformer: nil)
-      @query = query
-      @unwrapped = query.unwrap
-      @transformer = transformer
+    # Alias for total_count
+    def count #: Integer
+      total_count
     end
 
-    def_delegators :unwrapped,
-      :include?,
-      :member?,
-      :all?,
-      :any?,
-      :none?,
-      :one?,
-      :count
+    # Alias for total_count
+    def size #: Integer
+      total_count
+    end
 
+    # Alias for page_count
+    def page_size #: Integer
+      page_count
+    end
+
+    # @rbs &block: (untyped, *untyped) -> untyped
+    # @rbs return: Hash[untyped, Array[untyped]]
     def group_by(&block)
-      debug_callstack
-      grouped = unwrapped.group_by do |*block_args|
+      grouped = @configured_query.group_by do |*block_args|
         x = block_args.first
-        transformed = transformer ? transformer.call(x) : x
+        transformed = transform? ? @transformer.call(x) : x
         block ? block.call(transformed, *(block_args[1..] || [])) : transformed
       end
 
       grouped.tap do |groups|
         groups.transform_values! do |values|
-          transformer ? values.map { |x| transformer.call(x) } : values
+          @transformer ? values.map { |x| @transformer.call(x) } : values
         end
       end
     end
 
     # Delegate other enumerable methods to underlying collection but also transform
+    # @rbs override
     def method_missing(method, *args, **kwargs, &block)
-      if unwrapped.respond_to?(method)
-        debug_callstack
-        if block
-          unwrapped.send(method, *args, **kwargs) do |*block_args|
-            x = block_args.first
-            transformed = transformer ? transformer.call(x) : x
-            other_args = block_args[1..] || []
-            block.call(transformed, *other_args)
-          end
-        else
-          raw = unwrapped.send(method, *args, **kwargs)
-          # FIXME: consider how to handle applying a transformer to a Enumerator...
-          return raw if raw.is_a?(Quo::Results) || raw.is_a?(::Enumerator)
-          transform_results(raw)
+      return super unless respond_to_missing?(method)
+
+      if block
+        @configured_query.send(method, *args, **kwargs) do |*block_args|
+          x = block_args.first
+          transformed = transform? ? @transformer.call(x) : x
+          other_args = block_args[1..] || []
+          block.call(transformed, *other_args)
         end
       else
-        super
+        raw = @configured_query.send(method, *args, **kwargs)
+        # FIXME: consider how to handle applying a transformer to a Enumerator...
+        return raw if raw.is_a?(Quo::RelationResults) || raw.is_a?(::Enumerator)
+        transform_results(raw)
       end
     end
 
+    # @rbs name: Symbol
+    # @rbs include_private: bool
+    # @rbs return: bool
     def respond_to_missing?(name, include_private = false)
-      enumerable_methods_supported.include?(name)
+      @configured_query.respond_to?(name, include_private)
+    end
+
+    def transform? #: bool
+      @transformer.present?
     end
 
     private
 
-    attr_reader :transformer, :unwrapped
+    # @rbs @transformer: (^(untyped, ?Integer) -> untyped)?
 
+    # @rbs results: untyped
+    # @rbs return: untyped
     def transform_results(results)
-      return results unless transformer
+      return results unless transform?
 
       if results.is_a?(Enumerable)
-        results.map.with_index { |item, i| transformer.call(item, i) }
+        results.map.with_index { |item, i| @transformer.call(item, i) }
       else
-        transformer.call(results)
+        @transformer.call(results)
       end
     end
-
-    def enumerable_methods_supported
-      [:find_each] + Enumerable.instance_methods
-    end
   end
 end

data/lib/quo/rspec/helpers.rb

@@ -1,18 +1,40 @@
 # frozen_string_literal: true
 
+require_relative "../testing/collection_backed_fake"
+require_relative "../testing/relation_backed_fake"
+
 module Quo
   module Rspec
     module Helpers
-      def stub_query(query_class, options = {})
-        results = options.fetch(:results, [])
-        with = options[:with]
-        unless with.nil?
-          return(
-            allow(query_class).to receive(:new)
-                                    .with(with) { ::Quo::LoadedQuery.new(results) }
-          )
+      def fake_query(query_class, with: nil, 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
+          fake = ->(*kwargs) {
+            klass.new(results: results, total_count: total_count, page_count: page_count)
+          }
+          expectation = allow(query_class).to receive(:new)
+          expectation = expectation.with(with) if with
+          expectation.and_invoke(fake)
+        elsif query_class < Quo::RelationBackedQuery
+          fake = ->(*kwargs) {
+            Quo::Testing::RelationBackedFake.new(results: results, total_count: total_count, page_count: page_count)
+          }
+          expectation = allow(query_class).to receive(:new)
+          expectation = expectation.with(with) if with
+          expectation.and_invoke(fake)
+        else
+          raise ArgumentError, "Not a Query class: #{query_class}"
         end
-        allow(query_class).to receive(:new) { ::Quo::LoadedQuery.new(results) }
       end
     end
   end

data/lib/quo/testing/collection_backed_fake.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module Testing
+    class CollectionBackedFake < Quo.collection_backed_query_base_class
+      prop :results, _Any, reader: false
+      prop :page_count, _Nilable(Integer), reader: false
+
+      def collection
+        @results
+      end
+
+      def results
+        klass = Class.new(CollectionResults) do
+          def page_count
+            @query.page_count
+          end
+        end
+        klass.new(self)
+      end
+
+      def page_count
+        @page_count || validated_query.size
+      end
+    end
+  end
+end

data/lib/quo/testing/relation_backed_fake.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Quo
+  module Testing
+    class RelationBackedFake < Quo.relation_backed_query_base_class
+      prop :results, _Any, reader: false
+      prop :page_count, _Nilable(Integer), reader: false
+      prop :total_count, _Nilable(Integer), reader: false
+
+      def query
+        @results
+      end
+
+      def results
+        klass = Class.new(RelationResults) do
+          def page_count
+            @query.page_count
+          end
+
+          def total_count
+            @query.total_count
+          end
+        end
+        klass.new(self)
+      end
+
+      def page_count
+        @page_count || validated_query.size
+      end
+
+      def total_count
+        @total_count || validated_query.size
+      end
+
+      private
+
+      def validated_query
+        query
+      end
+
+      def underlying_query
+        validated_query
+      end
+
+      def configured_query
+        validated_query
+      end
+    end
+  end
+end

data/lib/quo/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Quo
-  VERSION = "0.6.0"
+  VERSION = "1.0.0.alpha1"
 end

data/lib/quo.rb

@@ -1,40 +1,32 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require_relative "quo/version"
-require_relative "quo/railtie" if defined?(Rails)
-require_relative "quo/query"
-require_relative "quo/eager_query"
-require_relative "quo/loaded_query"
-require_relative "quo/merged_query"
-require_relative "quo/wrapped_query"
-require_relative "quo/query_composer"
-require_relative "quo/results"
+require "quo/engine"
 
 module Quo
-  class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
+  extend ActiveSupport::Autoload
 
-    def configure
-      yield(configuration) if block_given?
-      configuration
-    end
-  end
+  autoload :Query
+  autoload :Preloadable
+  autoload :RelationBackedQuery
+  autoload :Results
+  autoload :RelationResults
+  autoload :CollectionResults
+  autoload :ComposedQuery
+  autoload :CollectionBackedQuery
 
-  class Configuration
-    attr_accessor :formatted_query_log,
-      :query_show_callstack_size,
-      :logger,
-      :max_page_size,
-      :default_page_size
+  mattr_accessor :relation_backed_query_base_class, default: "Quo::RelationBackedQuery"
+  mattr_accessor :collection_backed_query_base_class, default: "Quo::CollectionBackedQuery"
+  mattr_accessor :max_page_size, default: 200
+  mattr_accessor :default_page_size, default: 20
+
+  def self.relation_backed_query_base_class #: Quo::RelationBackedQuery
+    @@relation_backed_query_base_class.constantize
+  end
 
-    def initialize
-      @formatted_query_log = true
-      @query_show_callstack_size = 10
-      @logger = nil
-      @max_page_size = 200
-      @default_page_size = 20
-    end
+  def self.collection_backed_query_base_class #: Quo::CollectionBackedQuery
+    @@collection_backed_query_base_class.constantize
   end
 end

data/rbs_collection.yaml

@@ -9,8 +9,6 @@ sources:
 path: .gem_rbs_collection
 
 gems:
-  - name: quo
-    ignore: true
   - name: forwardable
   # Skip loading rbs gem's RBS.
   # It's unnecessary if you don't use rbs as a library.

data/sig/generated/quo/collection_backed_query.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/quo/collection_backed_query.rb with RBS::Inline
+
+module Quo
+  class CollectionBackedQuery < Query
+    # 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: (?untyped data, ?props: untyped) ?{ (?) -> untyped } -> Quo::CollectionBackedQuery
+
+    # @rbs return: Object & Enumerable[untyped]
+    def collection: () -> (Object & Enumerable[untyped])
+
+    # 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: () -> (Object & Enumerable[untyped])
+
+    def results: () -> untyped
+
+    # @rbs override
+    def relation?: ...
+
+    # @rbs override
+    def collection?: ...
+
+    # @rbs override
+    def to_collection: ...
+
+    private
+
+    def validated_query: () -> untyped
+
+    # @rbs return: Object & Enumerable[untyped]
+    def underlying_query: () -> (Object & Enumerable[untyped])
+
+    # The configured query is the underlying query with paging
+    def configured_query: () -> (Object & Enumerable[untyped])
+  end
+end

data/sig/generated/quo/collection_results.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/quo/collection_results.rb with RBS::Inline
+
+module Quo
+  class CollectionResults < Results
+    # @rbs override
+    def initialize: ...
+
+    # Are there any results for this query?
+    def exists?: () -> bool
+
+    def empty?: () -> bool
+
+    # 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: ...
+
+    # 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
+
+    @query: Quo::CollectionBackedQuery
+
+    @transformer: (^(untyped, ?Integer) -> untyped)?
+
+    @configured_query: Object & Enumerable[untyped]
+  end
+end