quo 0.5.3 → 1.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71564f3db9d5b4d555d2a21d01f2754ac7db5a650db760f480e6e968343b6994
-  data.tar.gz: 27ba399c9fd255fcff14ca7c2ab419d8547f6f7e2d319c2cb96aeaeed8dbc032
+  metadata.gz: 7dcdc5faff0797696ddb8db26baebe37f388a020943f7764e4857aaab8ef4c76
+  data.tar.gz: 550da1aaaa2bc4d24d82f3e7f78908f22ccd28913b8d9c6358cbc9bbc6ee8fa3
 SHA512:
-  metadata.gz: 6f43fe074d4ddfdbe71f27a5d65600ad014e473131d91c50ed911e541d533a9a2830ebb38420e17aba090657adf2f0f44409e995c5b3fc6666226c083eb1a93f
-  data.tar.gz: 07dcc1701c60ad300e92a67aea0c9b2a61c7edda34bc99aa5a0b9faab7c77a71ace33548822c70006f2965d5cdd3140b7df819d585675d045d92e477c5909871
+  metadata.gz: 69a94d4d6c4844e6b27e409a662dd76a9ca0dee26fd229a2e861ad377ef2a247ec8499633565d119aa5bc6adeca8930015f33b6ea69e4673d9609f906a1029e5
+  data.tar.gz: d511d04d2212029428e74b2771407e7a3adf566c193a3075fffee3d1c3de7d3e9c8aaca8d39330198264be2ead5df7e574ebd90581600d27d5576eef8718cd0b

data/.standard.yml

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

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "rails-7.0" do
+  gem "rails", "~> 7.0"
+end
+
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2"
+end

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 ## [Unreleased]
 
+
+## [1.0.0.rc1] - Unreleased
+
+### Breaking Changes
+
+Nearly everything has had changes. Porting will require some effort.
+
+- Quo now depends on `literal`, meaning attributes (options) to queries are typed and explicit
+- Composing query objects now allows you to compose query classes rather than just instances of query objects
+- `MergedQuery`, `EagerQuery` & `LoadedQuery` have been removed
+- `Query` is now an abstract base class for `RelationBackedQuery` and `CollectionBackedQuery`
+- The API of `Query` has been reduced/simplified significantly
+- `Query` classes only build queries, to actually execute/take actions on them you need to call `#results` and get a `Results` object
+- `preload`ing behaviour is now a separate concern from `Query` and is handled by `Preloadable` module.
+- Drop support for Ruby <= 3.1 and Rails < 7.0
+- Gem is now a Rails engine and relies on autoloading
+
+### Changed
+
+- Update docs, dependencies, and tests
+- Use appraisals for testing
+
+### Added
+
+- Helpers `stub_query` and `mock_query` for Minitest
+
+## [0.5.0] - 2022-12-23
+
+### Changed
+
+- Merged and Wrapped queries should not have factory methods as they are not meant to be constructed directly
+- Create new LoadedQuery which separates the concern of "preloaded" Query from EagerQuery which represents a query which is loaded and memoized
+
+## [0.4.0] - 2022-12-23
+
+### Changed
+
+- Some redundant nil checks (either safe navigation operator or conditionals) to make type check pass
+- Fix for type of transform method which takes optional index as second arg 
+- group_by can take a block
+- Change last and first methods to just take a limit value
+- Add new configuration options for page size limit and default and fix typing for enumerable
+- Rename Enumerator to Results and Query#enumerator to #results
+- Change EagerQuery initializer to take collection as positional param
+
+## [0.3.1] - 2022-12-22
+
+### Changed
+
+- Convenience methods on Query
+- Implement group_by on enumerator to transform values in resulting groups
+- Add WrappedQuery instead of Query taking a scope param
+- Change `initialize` method of MergedQuery
+
+## [0.3.0] - 2022-12-20
+
+### Changed
+
+- Make `joins` on compose a kwarg
+
+## [0.2.0] - 2022-12-20
+
+### Added
+
+- Railtie for rake task
+- Rake task which hackily looks for qo in the app and displays a list
+- Prepare to add RBS types
+
+### Changed
+
+- Gem deps
+- Query interface
+
+### Added
+
+- Test suite and dummy rails app
+- Add Enumerator
+
 ## [0.1.0] - 2022-11-18
 
 - Initial release

data/Gemfile

@@ -5,16 +5,18 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in quo.gemspec
 gemspec
 
+gem "rails", "~> 7.2"
+
 group :development, :test do
   gem "sqlite3"
 
-  gem "rails", ">= 6", "< 8"
-
   gem "rake", "~> 13.0"
 
   gem "minitest", "~> 5.0"
 
-  gem "standard", "~> 1.3"
+  gem "standard", require: false
+
+  gem "steep", require: false
 
-  gem "steep", "~> 1.2"
+  gem "rbs-inline", "~> 0.8.0", require: false
 end

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022 Stephen Ierodiaconou
+Copyright (c) 2022-2024 Stephen Ierodiaconou
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,4 +1,6 @@
-# Quo
+# 'Quo' query objects for ActiveRecord
+
+> Note: these docs are for pre-V1 and need updating. I'm working on it!
 
 Quo query objects can help you abstract ActiveRecord DB queries into reusable and composable objects with a chainable
 interface.
@@ -13,10 +15,12 @@ The core implementation provides the following functionality:
 * provides a number of utility methods that operate on the underlying collection (eg `exists?`)
 * provides a `+` (`compose`) method which merges two query object instances (see section below for details!)
 * can specify a mapping or transform method to `transform` to perform on results
-* in development outputs the callstack that led to the execution of the query
 * acts as a callable which executes the underlying query with `.first`
 * can return an `Enumerable` of results
 
+
+`Quo::Query` subclasses are the builders, they retain configuration of the queries, and prepare the underlying query or data collections. Query objects then return `Quo::Results` which take the built queries and then take action on them, such as to fetch data or to count records.
+
 ## Creating a Quo query object
 
 The query object must inherit from `Quo::Query` and provide an implementation for the `query` method.
@@ -24,7 +28,7 @@ The query object must inherit from `Quo::Query` and provide an implementation fo
 The `query` method must return either:
 
 - an `ActiveRecord::Relation`
-- an Array (an 'eager loaded' query) 
+- an Enumerable (like a 'collection backed' query) 
 - or another `Quo::Query` instance.
 
 Remember that the query object should be useful in composition with other query objects. Thus it should not directly 
@@ -81,7 +85,7 @@ This allows you to compose together Query objects which return relations which a
 them correctly with the appropriate joins. Note with the alias you cant neatly specify optional parameters for joins
 on relations.
 
-Note that the compose process creates a new query object instance, which is a instance of a `Quo::MergedQuery`.
+Note that the compose process creates a new query object instance, which is a instance of a `Quo::ComposedQuery`.
 
 Consider the following cases:
 
@@ -95,7 +99,7 @@ wrapped around a new 'composed' `ActiveRecords::Relation`.
 In case (2) the query object with a `ActiveRecords::Relation` inside is executed, and the result is then concatenated
 to the array-like with `+`
 
-In case (3) the values contained with each 'eager' query object are concatenated with `+`
+In case (3) the values contained are concatenated with `+`
 
 *Note that*
 
@@ -106,7 +110,7 @@ query object or and `ActiveRecord::Relation`. However `Quo::Query.compose(left,
 ### Examples
 
 ```ruby
-class CompanyToBeApproved < Quo::Query
+class CompanyToBeApproved < Quo::RelationBackedQuery
   def query
     Registration
       .left_joins(:approval)
@@ -114,7 +118,7 @@ class CompanyToBeApproved < Quo::Query
   end
 end
 
-class CompanyInUsState < Quo::Query
+class CompanyInUsState < Quo::RelationBackedQuery
   def query
     Registration
       .joins(company: :address)
@@ -130,38 +134,6 @@ composed = query1 + query2 # or Quo::Query.compose(query1, query2) or query1.com
 composed.first
 ```
 
-```ruby
-class CompanyToBeApproved < Quo::TypedQuery
-  def query
-    Registration
-      .left_joins(:approval)
-      .where(approvals: {completed_at: nil})
-  end
-end
-
-class CompanyInUsCityAndState < Quo::TypedQuery
-  param :state, Literal::Union[String, Array[String]]
-  param :city, optional(Literal::Union[String, Array[String]])
-
-  def query
-    q = Registration
-      .joins(company: :address)
-      .where(addresses: {state: state})
-    q = q.where(addresses: {city: city}) if city
-    q
-  end
-end
-
-
-query1 = CompanyToBeApproved.new
-query_partialy_applied = CompanyInUsState.with(state: "California")
-query2 = query_partialy_applied.with(city: ["San Francisco", "Los Angeles"]).operation
-
-composed = query1 + query2
-# '+' composes the queries and returns a new prepared query
-composed.first
-```
-
 This effectively executes:
 
 ```ruby
@@ -170,14 +142,13 @@ Registration
   .joins(company: :address)
   .where(approvals: {completed_at: nil})
   .where(addresses: {state: options[:state]})
-  .limit(1)
 ```
 
 It is also possible to compose with an `ActiveRecord::Relation`. This can be useful in a Query object itself to help
 build up the `query` relation. For example:
 
 ```ruby
-class RegistrationToBeApproved < Quo::Query
+class RegistrationToBeApproved < Quo::RelationBackedQuery
   def query
     done = Registration.where(step: "complete")
     approved = CompanyToBeApproved.new
@@ -194,13 +165,13 @@ query = RegistrationToBeApproved.new + Registration.where(blocked: false)
 Also you can use joins:
 
 ```ruby
-class TagByName < Quo::Query
+class TagByName < Quo::RelationBackedQuery
   def query
     Tag.where(name: options[:name])
   end
 end
 
-class CategoryByName < Quo::Query
+class CategoryByName < Quo::RelationBackedQuery
   def query
     Category.where(name: options[:name])
   end
@@ -213,18 +184,18 @@ tags.compose(for_category, :category) # perform join on tag association `categor
 # equivalent to Tag.joins(:category).where(name: "Intel").where(categories: {name: "CPUs"})
 ```
 
-Eager loaded queries can also be composed (see below sections for more details).
+Collection backed queries can also be composed (see below sections for more details).
 
-### Quo::MergedQuery
+### Quo::ComposedQuery
 
-The new instance of `Quo::MergedQuery` from a compose process, retains references to the original entities that were
+The new instance of `Quo::ComposedQuery` from a compose process, retains references to the original entities that were
 composed. These are then used to create a more useful output from `to_s`, so that it is easier to understand what the
 merged query is actually made up of:
 
 ```ruby
 q = FooQuery.new + BarQuery.new
 puts q
-# > "Quo::MergedQuery[FooQuery, BarQuery]"
+# > "Quo::ComposedQuery[FooQuery, BarQuery]"
 ```
 
 ## Query Objects & Pagination
@@ -234,39 +205,40 @@ Specify extra options to enable pagination:
 * `page`: the current page number to fetch
 * `page_size`: the number of elements to fetch in the page
 
-### `Quo::EagerQuery` & `Quo::LoadedQuery` objects
+### `Quo::CollectionBackedQuery` & `Quo::CollectionBackedQuery` objects
 
-`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.
+`Quo::CollectionBackedQuery` is a subclass of `Quo::Query` which can be used to create query objects which are backed 
+by a collection (ie an enumerable such as an Array). This is useful for encapsulating data that doesn't come from an 
+ActiveRecord query or queries that execute immediately. Subclass this and override `collection` to return the data you 
+want to encapsulate.
 
 ```ruby
-class MyEagerQuery < Quo::EagerQuery
+class MyCollectionBackedQuery < Quo::CollectionBackedQuery
   def collection
     [1, 2, 3]
   end
 end
-q = MyEagerQuery.new
-q.eager? # is it 'eager'? Yes it is!
+q = MyCollectionBackedQuery.new
+q.collection? # is it a collection under the hood? Yes it is!
 q.count # '3'
 ```
 
 Sometimes it is useful to create similar Queries without needing to create a explicit subclass of your own. For this
-use `Quo::LoadedQuery`:
+use `Quo::CollectionBackedQuery`:
 
 ```ruby
-q = Quo::LoadedQuery.new([1, 2, 3])
-q.eager? # is it 'eager'? Yes it is!
+q = Quo::CollectionBackedQuery.wrap([1, 2, 3])
+q.collection? # true
 q.count # '3'
 ```
 
-`Quo::EagerQuery` also uses `total_count` option value as the specified 'total count', useful when the data is
+`Quo::CollectionBackedQuery` 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:
+Example of an CollectionBackedQuery used to wrap a page of enumerable data:
 
 ```ruby
-Quo::LoadedQuery.new(my_data, total_count: 100, page: current_page)
+Quo::CollectionBackedQuery.wrap(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 
@@ -277,7 +249,7 @@ results are returned from the other queries. An loaded or eager query will force
 Examples of composition of eager loaded queries
 
 ```ruby
-class CachedTags < Quo::Query
+class CachedTags < Quo::RelationBackedQuery
   def query
     @tags ||= Tag.where(active: true).to_a
   end
@@ -289,7 +261,7 @@ composed.last
 composed.first
 # => #<Tag id: ...>
 
-Quo::LoadedQuery.new([3, 4]).compose(Quo::LoadedQuery.new([1, 2])).last
+Quo::CollectionBackedQuery.new([3, 4]).compose(Quo::CollectionBackedQuery.new([1, 2])).last
 # => 2
 Quo::Query.compose([1, 2], [3, 4]).last
 # => 4
@@ -319,7 +291,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 `LoadedQuery` instead with the given `results`. 
+It stubs `.new` on the Query object and returns instances of `CollectionBackedQuery` 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.
 
@@ -332,7 +304,7 @@ expect(TagQuery.new(name: "Something").first).to eql t1
 
 *Note that*
 
-This returns an instance of EagerQuery, so will not work for cases were the actual type of the query instance is
+This returns an instance of CollectionBackedQuery, so will not work for cases were the actual type of the query instance is
 important or where you are doing a composition of queries backed by relations!
 
 If `compose` will be used then `Quo::Query.compose` needs to be stubbed. Something might be possible to make this
@@ -371,11 +343,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/steveg
 
 ## Inspired by `rectify`
 
-Note this implementation is loosely based on that in the `Rectify` gem; https://github.com/andypike/rectify.
-
-See https://github.com/andypike/rectify#query-objects for more information.
-
-Thanks to Andy Pike for the inspiration.
+Note this implementation is inspired by the `Rectify` gem; https://github.com/andypike/rectify. Thanks to Andy Pike for the inspiration.
 
 ## License
 

data/Steepfile

@@ -32,6 +32,4 @@ target :lib do
   ignore "lib/quo/rspec/*.rb"
   ignore "lib/tasks/*"
   ignore "lib/quo/railtie.rb"
-
-  library "forwardable"
 end

data/gemfiles/rails_7.0.gemfile

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

data/gemfiles/rails_7.1.gemfile

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

data/gemfiles/rails_7.2.gemfile

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

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