quo 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61bf7495c0092bf641ff6e85bed8dc0073ea61e15a5292f0825f50eca4348a92
-  data.tar.gz: c10cc10dfe8ce323e4395640604a1c6358333bb7ea26b1c109d43eee67ed2d73
+  metadata.gz: b3c2546945f1bfdd80965174357d5f2246e82a0e5dc7158f2d60944e980899fe
+  data.tar.gz: ac40d8dd995273b4de27102a021741416d9501d5ff1bb6070f917bcac35bf164
 SHA512:
-  metadata.gz: e8e4105330e725058ca4c94f2c58229a0018e9379c38ac189cc2dbd007163468b845dd9632d727f824a35d4bc8cebbb7e40f5d24267277b0c1cbe0b580abb100
-  data.tar.gz: 7180ea2d74f1849628a1635c381685c5d2841c27229868280cd59a580dae759d61cc5236fba06b4044a93b667a23f670f4ba5960720165ccb1a6a103a4d06f37
+  metadata.gz: 825a13e681e234d7679452d837d27e627cf66f1877ae846cb224ad5b83db04714a4a4c15b3ce37de01f733c996226844d892a4975884c4e3926b6f4acf8e23ee
+  data.tar.gz: a2bde21de2adf4e548502c5daed323e043d8fbf7a5d7f07956234bf01c3223b888a5fce77f0a54c6943bb25035aae866d4ed2c10148759ee14384e4e717f8fcc

data/README.md

@@ -201,50 +201,44 @@ Specify extra options to enable pagination:
 * `page`: the current page number to fetch
 * `page_size`: the number of elements to fetch in the page
 
-## 'Eager loaded' Quo::Query objects
+### `Quo::EagerQuery` & `Quo::LoadedQuery` objects
 
-When a query object returns an `Array` from `query` it is assumed as 'eager loaded', ie that the query has actually
-already been executed and the array contains the return values. This can also be used to encapsulate data that doesn't
-actually come from an ActiveRecord query.
-
-For example, the Query below executes the query inside on the first call and memoises the resulting data. Note
-however that this then means that this Query is not reusuable to `merge` with other ActiveRecord queries. If it is
-`compose`d with other Query objects then it will be seen as an array-like, and concatenated to whatever it is being
-joined to.
+`Quo::EagerQuery` is a subclass of `Quo::Query` which can be used to create query objects which are 'eager loaded' by 
+default. This is useful for encapsulating data that doesn't come from an ActiveRecord query or queries that
+execute immediately. Subclass EasyQuery and override `collection` to return the data you want to encapsulate.
 
 ```ruby
-class CachedTags < Quo::Query
-  def query
-    @tags ||= Tag.where(active: true).to_a
+class MyEagerQuery < Quo::EagerQuery
+  def collection
+    [1, 2, 3]
   end
 end
-
-q = CachedTags.new(active: false)
+q = MyEagerQuery.new
 q.eager? # is it 'eager'? Yes it is!
-q.count # array size
+q.count # '3'
 ```
 
-### `Quo::EagerQuery` objects
-
-`Quo::EagerQuery` is a subclass of `Quo::Query` which takes a data value on instantiation and returns it on calls to `query`
+Sometimes it is useful to create similar Queries without needing to create a explicit subclass of your own. For this
+use `Quo::LoadedQuery`:
 
 ```ruby
-q = Quo::EagerQuery.new([1, 2, 3])
+q = Quo::LoadedQuery.new([1, 2, 3])
 q.eager? # is it 'eager'? Yes it is!
 q.count # '3'
 ```
 
-This is useful to create eager loaded Queries without needing to create a explicit subclass of your own.
-
 `Quo::EagerQuery` also uses `total_count` option value as the specified 'total count', useful when the data is
 actually just a page of the data and not the total count.
 
 Example of an EagerQuery used to wrap a page of enumerable data:
 
 ```ruby
-Quo::EagerQuery.new(my_data, total_count: 100, page: current_page)
+Quo::LoadedQuery.new(my_data, total_count: 100, page: current_page)
 ```
 
+If a loaded query is `compose`d with other Query objects then it will be seen as an array-like, and concatenated to whatever 
+results are returned from the other queries. An loaded or eager query will force all other queries to be eager loaded.
+
 ### Composition
 
 Examples of composition of eager loaded queries
@@ -262,7 +256,7 @@ composed.last
 composed.first
 # => #<Tag id: ...>
 
-Quo::EagerQuery.new([3, 4]).compose(Quo::EagerQuery.new([1, 2])).last
+Quo::LoadedQuery.new([3, 4]).compose(Quo::LoadedQuery.new([1, 2])).last
 # => 2
 Quo::Query.compose([1, 2], [3, 4]).last
 # => 4
@@ -292,7 +286,7 @@ maybe desirable.
 
 The spec helper method `stub_query(query_class, {results: ..., with: ...})` can do this for you.
 
-It stubs `.new` on the Query object and returns instances of `EagerQuery` instead with the given `results`. 
+It stubs `.new` on the Query object and returns instances of `LoadedQuery` instead with the given `results`. 
 The `with` option is passed to the Query object on initialisation and used when setting up the method stub on the 
 query class.
 

data/lib/quo/eager_query.rb

@@ -2,45 +2,22 @@
 
 module Quo
   class EagerQuery < Quo::Query
-    class << self
-      def call(**options)
-        build_from_options(options).first
-      end
-
-      def call!(**options)
-        build_from_options(options).first!
-      end
-
-      def build_from_options(options)
-        collection = options[:collection]
-        raise ArgumentError, "EagerQuery needs a collection" unless collection
-        new(collection, **options.except(:collection))
-      end
-    end
-
-    def initialize(collection, **options)
-      @collection = Array.wrap(collection)
-      super(**options)
-    end
-
-    def copy(**options)
-      self.class.new(@collection, **@options.merge(options))
-    end
-
     # 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.
     def count
       options[:total_count] || super
     end
-    alias_method :total_count, :count
-    alias_method :size, :count
 
     # Is this query object paged? (when no total count)
     def paged?
       options[:total_count].nil? && current_page.present?
     end
 
+    def collection
+      raise NotImplementedError, "EagerQuery objects must define a 'collection' method"
+    end
+
     def query
       preload_includes(collection) if options[:includes]
       collection
@@ -56,13 +33,19 @@ module Quo
 
     private
 
-    attr_reader :collection
+    def underlying_query
+      unwrap_relation(query)
+    end
+
+    def unwrap_relation(query)
+      query.is_a?(Quo::Query) ? query.unwrap : query
+    end
 
     def preload_includes(records, preload = nil)
       ::ActiveRecord::Associations::Preloader.new(
         records: records,
         associations: preload || options[:includes]
-      )
+      ).call
     end
   end
 end

data/lib/quo/loaded_query.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Quo
+  class LoadedQuery < Quo::EagerQuery
+    def initialize(collection, **options)
+      @collection = collection
+      super(**options)
+    end
+
+    def copy(**options)
+      self.class.new(@collection, **@options.merge(options))
+    end
+
+    private
+
+    attr_reader :collection
+  end
+end

data/lib/quo/merged_query.rb

@@ -2,24 +2,6 @@
 
 module Quo
   class MergedQuery < Quo::Query
-    class << self
-      def call(**options)
-        build_from_options(options).first
-      end
-
-      def call!(**options)
-        build_from_options(options).first!
-      end
-
-      def build_from_options(options)
-        merged_query = options[:merged_query]
-        left = options[:left]
-        right = options[:right]
-        raise ArgumentError, "MergedQuery needs the merged result and operands" unless merged_query && left && right
-        new(merged_query, left, right, **options)
-      end
-    end
-
     def initialize(merged_query, left, right, **options)
       @merged_query = merged_query
       @left = left

data/lib/quo/query.rb

@@ -101,8 +101,11 @@ module Quo
         elsif !res.nil?
           transformer&.call(query_with_logging.first(limit))
         end
-      else
+      elsif limit
         query_with_logging.first(limit)
+      else
+        # Array#first will not take nil as a limit
+        query_with_logging.first
       end
     end
 
@@ -121,8 +124,10 @@ module Quo
         elsif !res.nil?
           transformer&.call(res)
         end
-      else
+      elsif limit
         query_with_logging.last(limit)
+      else
+        query_with_logging.last
       end
     end
 
@@ -132,9 +137,8 @@ module Quo
       transform? ? arr.map.with_index { |r, i| transformer&.call(r, i) } : arr
     end
 
-    # Convert to EagerQuery, and load all data
     def to_eager(more_opts = {})
-      Quo::EagerQuery.new(to_a, **options.merge(more_opts))
+      Quo::LoadedQuery.new(to_a, **options.merge(more_opts))
     end
     alias_method :load, :to_eager
 
@@ -282,7 +286,7 @@ module Quo
     end
 
     def test_eager(rel)
-      rel.is_a?(Enumerable) && !test_relation(rel)
+      rel.is_a?(Quo::LoadedQuery) || (rel.is_a?(Enumerable) && !test_relation(rel))
     end
 
     def test_relation(rel)

data/lib/quo/query_composer.rb

@@ -39,10 +39,12 @@ module Quo
         apply_joins(unwrapped_left, joins).merge(unwrapped_right)
       elsif left_relation_right_enumerable?
         unwrapped_left.to_a + unwrapped_right
-      elsif left_enumerable_right_relation?
+      elsif left_enumerable_right_relation? && unwrapped_left.respond_to?(:+)
         unwrapped_left + unwrapped_right.to_a
-      else
+      elsif unwrapped_left.respond_to?(:+)
         unwrapped_left + unwrapped_right
+      else
+        raise ArgumentError, "Cannot merge #{left.class} with #{right.class}"
       end
     end
 

data/lib/quo/results.rb

@@ -3,6 +3,9 @@
 require "forwardable"
 require_relative "./utilities/callstack"
 
+# TODO: can the results be more like a monad, so we can provide success vs failure ... or
+# maybe it is a enumerable-like but it can also be pattern matched?
+
 module Quo
   class Results
     extend Forwardable

data/lib/quo/rspec/helpers.rb

@@ -9,10 +9,10 @@ module Quo
         unless with.nil?
           return(
             allow(query_class).to receive(:new)
-                                    .with(with) { ::Quo::EagerQuery.new(results) }
+                                    .with(with) { ::Quo::LoadedQuery.new(results) }
           )
         end
-        allow(query_class).to receive(:new) { ::Quo::EagerQuery.new(results) }
+        allow(query_class).to receive(:new) { ::Quo::LoadedQuery.new(results) }
       end
     end
   end

data/lib/quo/utilities/wrap.rb

@@ -15,7 +15,7 @@ module Quo
         if query_rel_or_data.is_a? ActiveRecord::Relation
           Quo::WrappedQuery.new(query_rel_or_data, **options)
         else
-          Quo::EagerQuery.new(query_rel_or_data, **options)
+          Quo::LoadedQuery.new(query_rel_or_data, **options)
         end
       end
     end

data/lib/quo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quo
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/quo/wrapped_query.rb

@@ -2,27 +2,15 @@
 
 module Quo
   class WrappedQuery < Quo::Query
-    class << self
-      def call(**options)
-        build_from_options(**options).first
-      end
-
-      def call!(**options)
-        build_from_options(**options).first!
-      end
-
-      def build_from_options(**options)
-        query = options[:wrapped_query]
-        raise ArgumentError, "WrappedQuery needs a scope" unless query
-        new(query, **options)
-      end
-    end
-
     def initialize(wrapped_query, **options)
       @wrapped_query = wrapped_query
       super(**options)
     end
 
+    def copy(**options)
+      self.class.new(query, **@options.merge(options))
+    end
+
     def query
       @wrapped_query
     end

data/lib/quo.rb

@@ -4,6 +4,7 @@ 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"

data/sig/quo/eager_query.rbs

@@ -1,18 +1,15 @@
 module Quo
   class EagerQuery < Quo::Query
-    def self.call: (**untyped) -> untyped
-    def self.call!: (**untyped) -> untyped
-    def self.build_from_options: (queryOptions) -> EagerQuery
+    def collection: () -> loadedQueryOrEnumerable
+    def query: () -> loadedQueryOrEnumerable
 
-    def initialize: (enumerable, **untyped options) -> void
-    def query: () -> enumerable
     def relation?: () -> false
     def eager?: () -> true
 
     private
 
-    attr_reader collection: enumerable
-
     def preload_includes: (untyped records, ?untyped? preload) -> untyped
+    def underlying_query: () -> enumerable
+    def unwrap_relation: (loadedQueryOrEnumerable collection) -> enumerable
   end
 end

data/sig/quo/loaded_query.rbs

@@ -0,0 +1,7 @@
+module Quo
+  class LoadedQuery < Quo::EagerQuery
+    @collection: enumerable
+
+    def initialize: (enumerable, **untyped options) -> void
+  end
+end

data/sig/quo.rbs

@@ -13,6 +13,7 @@ module Quo
   type queryOrRel = query | ActiveRecord::Relation
   type enumerable = Object & Enumerable[untyped]
   type relOrEnumerable = ActiveRecord::Relation | enumerable
+  type loadedQueryOrEnumerable = LoadedQuery | EagerQuery | enumerable
   type composable = query | relOrEnumerable
 
   # TODO: how can we do the known options, eg `page` and then allow anything else?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-23 00:00:00.000000000 Z
+date: 2023-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -66,6 +66,7 @@ files:
 - Steepfile
 - lib/quo.rb
 - lib/quo/eager_query.rb
+- lib/quo/loaded_query.rb
 - lib/quo/merged_query.rb
 - lib/quo/query.rb
 - lib/quo/query_composer.rb
@@ -82,6 +83,7 @@ files:
 - rbs_collection.yaml
 - sig/quo.rbs
 - sig/quo/eager_query.rbs
+- sig/quo/loaded_query.rbs
 - sig/quo/merged_query.rbs
 - sig/quo/query.rbs
 - sig/quo/query_composer.rbs
@@ -112,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Quo is a query object gem for Rails