quo 0.6.0 → 1.0.0.beta1

data/README.md

@@ -1,330 +1,324 @@
-# Quo
+# Quo: Query Objects for ActiveRecord
 
-Quo query objects can help you abstract ActiveRecord DB queries into reusable and composable objects with a chainable
-interface.
+Quo helps you organize database queries into reusable, composable, and testable objects.
 
-The query object can also abstract over any array-like collection meaning that it is possible for example to cache the
-data from a query and reuse it.
+## Core Features
 
-The core implementation provides the following functionality:
+* Wrap around an underlying ActiveRecord relation or array-like collection
+* Supports pagination for ActiveRecord-based queries and collections that respond to `[]`
+* Support composition with the `+` (`compose`) method to merge multiple query objects
+* Allow transforming results with the `transform` method
+* Offer utility methods that operate on the underlying collection (eg `exists?`)
+* Act as a callable with chainable methods like ActiveRecord
+* Provide a clear separation between query definition and execution with enumerable `Results` objects
+* Type-safe properties with optional default values
 
-* wrap around an underlying ActiveRecord or array-like collection
-* optionally provides paging behaviour to ActiveRecord based queries
-* 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
+## Core Concepts
 
-## Creating a Quo query object
+Query objects encapsulate query logic in dedicated classes, making complex queries more manageable and reusable.
 
-The query object must inherit from `Quo::Query` and provide an implementation for the `query` method.
+Quo provides two main components:
+1. **Query Objects** - Define and configure queries
+2. **Results Objects** - Execute queries and provide access to the results
 
-The `query` method must return either:
+## Creating Query Objects
 
-- an `ActiveRecord::Relation`
-- an Array (an 'eager loaded' query) 
-- or another `Quo::Query` instance.
+### Relation-Backed Queries
 
-Remember that the query object should be useful in composition with other query objects. Thus it should not directly 
-specify things that are not directly needed to fetch the right data for the given context. 
+For queries based on ActiveRecord relations:
 
-For example the ordering of the results is mostly something that is specified when the query object is used, not as
-part of the query itself (as then it would always enforce the ordering on other queries it was composed with).
+```ruby
+class RecentActiveUsers < Quo::RelationBackedQuery
+  # Define typed properties
+  prop :days_ago, Integer, default: -> { 30 }
+  
+  def query
+    User
+      .where(active: true)
+      .where("created_at > ?", days_ago.days.ago)
+  end
+end
 
-## Passing options to queries
+# Create and use the query
+query = RecentActiveUsers.new(days_ago: 7)
+results = query.results
 
-If any parameters are need in `query`, these are provided when instantiating the query object using the `options` hash.
+# Work with results
+results.each { |user| puts user.email }
+puts "Found #{results.count} users"
+```
 
-It is also possible to pass special configuration options to the constructor options hash. 
+### Collection-Backed Queries
 
-Specifically when the underlying collection is a ActiveRecord relation then:
+For queries based on any Enumerable collection:
 
-* `order`: the `order` condition for the relation (eg `:desc`)
-* `includes`: the `includes` condition for the relation (eg `account: {user: :profile}`)
-* `group`: the `group` condition for the relation
-* `page`: the current page number to fetch
-* `page_size`: the number of elements to fetch in the page
+```ruby
+class CachedUsers < Quo::CollectionBackedQuery
+  prop :role, String
+  
+  def collection
+    @cached_users ||= Rails.cache.fetch("all_users", expires_in: 1.hour) do
+      User.all.to_a
+    end.select { |user| user.role == role }
+  end
+end
 
-Note that the above options have no bearing on the query if it is backed by an array-like collection and that some
-options can be configured using the following methods.
+# Use the query
+admins = CachedUsers.new(role: "admin").results
+```
 
-## Configuring queries
+## Quick Queries with Wrap
 
-Note that it is possible to configure a query using chainable methods similar to ActiveRecord:
+Create query objects without subclassing:
 
-* limit
-* order
-* group
-* includes
-* left_outer_joins
-* preload
-* joins
+```ruby
+# Relation-backed
+users_query = Quo::RelationBackedQuery.wrap(User.active).new
+active_users = users_query.results
 
-Note that these return a new Quo Query and do not mutate the original instance.
+# Collection-backed
+items_query = Quo::CollectionBackedQuery.wrap([1, 2, 3]).new
+items = items_query.results
+```
 
-## Composition of queries (merging or combining them)
+## Type-Safe Properties
 
-Quo query objects are composeability. In `ActiveRecord::Relation` this is acheived using `merge`
-and so under the hood `Quo::Query` uses that when composing relations. However since Queries can also abstract over
-array-like collections (ie enumerable and define a `+` method) compose also handles concating them together.
+Quo uses the `Literal` gem for typed properties:
 
-Composing can be done with either 
+```ruby
+class UsersByState < Quo::RelationBackedQuery
+  prop :state, String
+  prop :minimum_age, Integer, default: -> { 18 }
+  prop :active_only, Boolean, default: -> { true }
 
-- `Quo::Query.compose(left, right)` 
-- or `left.compose(right)` 
-- or more simply with `left + right`
+  def query
+    scope = User.where(state: state)
+    scope = scope.where("age >= ?", minimum_age) if minimum_age.present?
+    scope = scope.where(active: true) if active_only
+    scope
+  end
+end
 
-The composition methods also accept an optional parameter to pass to ActiveRecord relation merges for the `joins`. 
-This allows you to compose together Query objects which return relations which are of different models but still merge 
-them correctly with the appropriate joins. Note with the alias you cant neatly specify optional parameters for joins
-on relations.
+query = UsersByState.new(state: "California", minimum_age: 21)
+```
 
-Note that the compose process creates a new query object instance, which is a instance of a `Quo::MergedQuery`.
+## Fluent API for Building Queries
 
-Consider the following cases:
+```ruby
+query = UsersByState.new(state: "California")
+  .order(created_at: :desc)
+  .includes(:profile)
+  .limit(10)
+  .where(verified: true)
 
-1. compose two query objects which return `ActiveRecord::Relation`s
-2. compose two query objects, one of which returns a `ActiveRecord::Relation`, and the other an array-like
-3. compose two query objects which return array-likes
+users = query.results
+```
 
-In case (1) the compose process uses `ActiveRecords::Relation`'s `merge` method to create another query object
-wrapped around a new 'composed' `ActiveRecords::Relation`.
+Available methods include:
+* `where`
+* `order`
+* `limit`
+* `includes`
+* `preload`
+* `left_outer_joins`
+* `joins`
+* `group`
 
-In case (2) the query object with a `ActiveRecords::Relation` inside is executed, and the result is then concatenated
-to the array-like with `+`
+Each method returns a new query instance without modifying the original.
 
-In case (3) the values contained with each 'eager' query object are concatenated with `+`
+## Pagination
 
-*Note that*
+```ruby
+query = UsersByState.new(
+  state: "California",
+  page: 2,
+  page_size: 20
+)
+
+# Get paginated results
+users = query.results
+
+# Navigation
+next_page = query.next_page_query
+prev_page = query.previous_page_query
+```
 
-with `left.compose(right)`, `left` must obviously be an instance of a `Quo::Query`, and `right` can be either a
-query object or and `ActiveRecord::Relation`. However `Quo::Query.compose(left, right)` also accepts
-`ActiveRecord::Relation`s for left.
+## Composing Queries
 
-### Examples
+Combine multiple queries:
 
 ```ruby
-class CompanyToBeApproved < Quo::Query
+class ActiveUsers < Quo::RelationBackedQuery
   def query
-    Registration
-      .left_joins(:approval)
-      .where(approvals: {completed_at: nil})
+    User.where(active: true)
   end
 end
 
-class CompanyInUsState < Quo::Query
+class PremiumUsers < Quo::RelationBackedQuery
   def query
-    Registration
-      .joins(company: :address)
-      .where(addresses: {state: options[:state]})
+    User.where(subscription_tier: "premium")
   end
 end
 
-query1 = CompanyToBeApproved.new
-query2 = CompanyInUsState.new(state: "California")
-
-# Compose
-composed = query1 + query2 # or Quo::Query.compose(query1, query2) or query1.compose(query2)
-composed.first
+# Compose queries
+active_premium = ActiveUsers.new + PremiumUsers.new
+users = active_premium.results
 ```
 
-This effectively executes:
-
-```ruby
-Registration
-  .left_joins(:approval)
-  .joins(company: :address)
-  .where(approvals: {completed_at: nil})
-  .where(addresses: {state: options[:state]})
-```
-
-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
-  def query
-    done = Registration.where(step: "complete")
-    approved = CompanyToBeApproved.new
-    # Here we use `.compose` utility method to wrap our Relation in a Query and 
-    # then compose with the other Query
-    Quo::Query.compose(done, approved)
-  end
-end
-
-# A Relation can be composed directly to a Quo::Query
-query = RegistrationToBeApproved.new + Registration.where(blocked: false)
-```
+You can compose queries using:
+* `Quo::Query.compose(left, right)`
+* `left.compose(right)`
+* `left + right`
 
-Also you can use joins:
+### Composing with Joins
 
 ```ruby
-class TagByName < Quo::Query
+class ProductsQuery < Quo::RelationBackedQuery
   def query
-    Tag.where(name: options[:name])
+    Product.where(active: true)
   end
 end
 
-class CategoryByName < Quo::Query
+class CategoriesQuery < Quo::RelationBackedQuery
   def query
-    Category.where(name: options[:name])
+    Category.where(featured: true)
   end
 end
 
-tags = TagByName.new(name: "Intel")
-for_category = CategoryByName.new(name: "CPUs")
-tags.compose(for_category, :category) # perform join on tag association `category`
+# Compose with a join
+products = ProductsQuery.new.compose(CategoriesQuery.new, joins: :category)
 
-# equivalent to Tag.joins(:category).where(name: "Intel").where(categories: {name: "CPUs"})
+# Equivalent to:
+# Product.joins(:category)
+#        .where(products: { active: true })
+#        .where(categories: { featured: true })
 ```
 
-Eager loaded queries can also be composed (see below sections for more details).
-
-### Quo::MergedQuery
-
-The new instance of `Quo::MergedQuery` 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:
+## Transforming Results
 
 ```ruby
-q = FooQuery.new + BarQuery.new
-puts q
-# > "Quo::MergedQuery[FooQuery, BarQuery]"
+query = UsersByState.new(state: "California")
+  .transform { |user| UserPresenter.new(user) }
+
+# Results are automatically transformed
+presenters = query.results.to_a # Array of UserPresenter objects
 ```
 
-## Query Objects & Pagination
+## Custom Association Preloading
 
-Specify extra options to enable pagination:
+```ruby
+class UsersWithOrders < Quo::RelationBackedQuery
+  include Quo::Preloadable
+  
+  def query
+    User.all
+  end
 
-* `page`: the current page number to fetch
-* `page_size`: the number of elements to fetch in the page
+  def preload_associations(collection)
+    # Custom preloading logic
+    ActiveRecord::Associations::Preloader.new(
+      records: collection,
+      associations: [:profile, :orders]
+    ).call
+    
+    collection
+  end
+end
+```
 
-### `Quo::EagerQuery` & `Quo::LoadedQuery` objects
+## Testing Helpers
 
-`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.
+### Minitest
 
 ```ruby
-class MyEagerQuery < Quo::EagerQuery
-  def collection
-    [1, 2, 3]
+class UserQueryTest < ActiveSupport::TestCase
+  include Quo::Minitest::Helpers
+
+  test "filters users by state" do
+    users = [User.new(name: "Alice"), User.new(name: "Bob")]
+    
+    fake_query(UsersByState, results: users) do
+      result = UsersByState.new(state: "California").results.to_a
+      assert_equal users, result
+    end
   end
 end
-q = MyEagerQuery.new
-q.eager? # is it 'eager'? 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`:
+### RSpec
 
 ```ruby
-q = Quo::LoadedQuery.new([1, 2, 3])
-q.eager? # is it 'eager'? Yes it is!
-q.count # '3'
+RSpec.describe UsersByState do
+  include Quo::RSpec::Helpers
+
+  it "filters users by state" do
+    users = [User.new(name: "Alice"), User.new(name: "Bob")]
+    
+    fake_query(UsersByState, results: users) do
+      result = UsersByState.new(state: "California").results.to_a
+      expect(result).to eq(users)
+    end
+  end
+end
 ```
 
-`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.
+## Project Organization
 
-Example of an EagerQuery used to wrap a page of enumerable data:
+Suggested directory structure:
 
-```ruby
-Quo::LoadedQuery.new(my_data, total_count: 100, page: current_page)
+```
+app/
+  queries/
+    application_query.rb
+    users/
+      active_users_query.rb
+      by_state_query.rb
+    products/
+      featured_products_query.rb
 ```
 
-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
+Base classes:
 
 ```ruby
-class CachedTags < Quo::Query
-  def query
-    @tags ||= Tag.where(active: true).to_a
-  end
+# app/queries/application_query.rb
+class ApplicationQuery < Quo::RelationBackedQuery
+  # Common functionality
 end
 
-composed = CachedTags.new(active: false) + [1, 2]
-composed.last
-# => 2
-composed.first
-# => #<Tag id: ...>
-
-Quo::LoadedQuery.new([3, 4]).compose(Quo::LoadedQuery.new([1, 2])).last
-# => 2
-Quo::Query.compose([1, 2], [3, 4]).last
-# => 4
+# app/queries/application_collection_query.rb
+class ApplicationCollectionQuery < Quo::CollectionBackedQuery
+  # Common functionality
+end
 ```
 
-## Transforming results
-
-Sometimes you want to specify a block to execute on each result for any method that returns results, such as `first`,
-`last` and `each`.
+## Installation
 
-This can be specified using the `transform(&block)` instance method. For example:
+Add to your Gemfile:
 
 ```ruby
-TagsQuery.new(
-  active: [true, false],
-  page: 1,
-  page_size: 30,
-).transform { |tag| TagPresenter.new(tag) }
- .first
-# => #<TagPresenter ...>
+gem "quo"
 ```
 
-## Tests & stubbing
+Then execute:
 
-Tests for Query objects themselves should exercise the actual underlying query. But in other code stubbing the query
-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`. 
-The `with` option is passed to the Query object on initialisation and used when setting up the method stub on the 
-query class.
+```
+$ bundle install
+```
 
-For example:
+## Configuration
 
 ```ruby
-stub_query(TagQuery, with: {name: "Something"}, results: [t1, t2])
-expect(TagQuery.new(name: "Something").first).to eql t1
+# config/initializers/quo.rb
+Quo.default_page_size = 25
+Quo.max_page_size = 100
+Quo.relation_backed_query_base_class = "ApplicationQuery"
+Quo.collection_backed_query_base_class = "ApplicationCollectionQuery"
 ```
 
-*Note that*
-
-This returns an instance of EagerQuery, 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
-nicer in future.
-
-## Other reading
-
-See:
-* [Includes vs preload vs eager_load](http://blog.scoutapp.com/articles/2017/01/24/activerecord-includes-vs-joins-vs-preload-vs-eager_load-when-and-where)
-* [Objects on Rails](http://objectsonrails.com/#sec-14)
-
+## Requirements
 
-## Installation
-
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add quo
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    $ gem install quo
-
-## Usage
-
-TODO: Write usage instructions here
+- Ruby 3.1+
+- Rails 7.0+
 
 ## Development
 
@@ -338,11 +332,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.
+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/gemfiles/rails_8.0.gemfile

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