quo 1.0.0.beta1 → 2.0.0

data/README.md

@@ -1,17 +1,94 @@
-# Quo: Query Objects for ActiveRecord
+<p align="center">
+  <img src="quo.png" alt="Quo" width="160" height="160" />
+</p>
+
+# Quo: Query Objects for ActiveRecord & Collections
+
+![Coverage](badges/coverage_badge_total.svg)
+![RubyCritic](badges/rubycritic_badge_score.svg)
+
+Quo helps you organize database and collection queries into reusable, composable, and testable objects.
+
+## Quick Example
+
+```ruby
+# Define query objects to encapsulate query logic
+class RecentPostsQuery < Quo::RelationBackedQuery
+  # Type-safe properties with defaults
+  prop :days_ago, Integer, default: -> { 7 }
+  
+  def query
+    Post.where(Post.arel_table[:created_at].gt(days_ago.days.ago))
+      .order(created_at: :desc)
+  end
+end
+
+# Use queries with pagination
+posts_query = RecentPostsQuery.new(days_ago: 30, page: 1, page_size: 10)
+page1 = posts_query.results
+# => Returns first 10 posts from the last 30 days
+
+# Navigate between pages
+page2_query = posts_query.next_page_query
+page2 = page2_query.results
+# => Returns next 10 posts
+
+class CommentNotSpamQuery < Quo::RelationBackedQuery
+  prop :spam_score_threshold, _Float(0..1.0)
+
+  def query
+    comments = Comment.arel_table
+    Comment.where(
+      comments[:spam_score].eq(nil).or(comments[:spam_score].lt(spam_score_threshold))
+    )
+  end
+end
+
+# Get recent posts (last 10 days) which have comments that are not Spam
+posts_last_10_days = RecentPostsQuery.new(days_ago: 10).joins(:comments)
+
+# Compose your queries
+query = posts_last_10_days + CommentNotSpamQuery.new(spam_score_threshold: 0.5)
+
+# Transform results
+transformed_query = query.transform { |post| PostPresenter.new(post) }
+
+# Work with result sets
+transformed_query.results.each do |presenter|
+  puts presenter.formatted_title
+end
+```
 
-Quo helps you organize database queries into reusable, composable, and testable objects.
 
 ## Core Features
 
-* 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
+### Collections
+* Query objects can wrap either an ActiveRecord relation (`RelationBackedQuery`) or any Enumerable collection (`CollectionBackedQuery`)
+* Built-in pagination that works with both database queries and enumerable collections
+* Flexible interface for creating custom queries or wrapping existing queries
+
+### Configurable
+* Type-safe properties with optional default values using the Literal gem
+* Each query is (kinda) "immutable" - operations return new query instances, mutation is actively frowned upon
+* Configure your own base classes, default page sizes, and more
+
+### Composition and Transformation
+* Combine queries using the `+` operator (alias for `compose` method)
+* Mix and match relation-backed and collection-backed queries
+* Join queries with explicit join conditions using the `joins` parameter
+* Transform results consistently using the `transform` method
+
+### Fluent API
+* Chain methods that mirror ActiveRecord's query interface (where, order, limit, etc.)
+* Access utility methods that work on both relation and collection queries (exists?, empty?, etc.)
+* Navigation helpers for pagination (next_page_query, previous_page_query)
+
+### Query Results
+* Clear separation between query definition and execution with `Results` objects
+* Automatic application of transformations across all result methods
+* Consistent interface regardless of the underlying query type
+* Support for common methods: each, map, first/last, count, exists?, group_by, and more
+
 
 ## Core Concepts
 
@@ -67,20 +144,53 @@ end
 admins = CachedUsers.new(role: "admin").results
 ```
 
-## Quick Queries with Wrap
+## Quick Queries with Wrap and to_collection
+
+### Creating Query Objects with Wrap
 
-Create query objects without subclassing:
+Create query objects on the fly without subclassing using the `wrap` class method:
 
 ```ruby
-# Relation-backed
+# Relation-backed query from an ActiveRecord relation
 users_query = Quo::RelationBackedQuery.wrap(User.active).new
 active_users = users_query.results
 
-# Collection-backed
+# Relation-backed query with a block
+posts_query = Quo::RelationBackedQuery.wrap(props: {tag: String}) do
+  Post.where(published: true).where("title LIKE ?", "%#{tag}%")
+end
+tagged_posts = posts_query.new(tag: "ruby").results
+
+# Collection-backed query from an array
 items_query = Quo::CollectionBackedQuery.wrap([1, 2, 3]).new
 items = items_query.results
+
+# Collection-backed query with properties and a block
+filtered_query = Quo::CollectionBackedQuery.wrap(props: {min: Integer}) do
+  [1, 2, 3, 4, 5].select { |n| n >= min }
+end
+result = filtered_query.new(min: 3).results # [3, 4, 5]
 ```
 
+### Converting Between Query Types
+
+Convert a relation-backed query to a collection-backed query using `to_collection`:
+
+```ruby
+# Start with a relation-backed query
+relation_query = UsersByState.new(state: "California")
+
+# Convert to a collection-backed query (executes the query)
+collection_query = relation_query.to_collection
+collection_query.collection? # => true
+collection_query.relation? # => false
+
+# You can optionally specify a total count (useful for pagination)
+collection_query = relation_query.to_collection(total_count: 100)
+```
+
+This is useful when you want to convert an ActiveRecord relation to an enumerable collection while preserving the query interface.
+
 ## Type-Safe Properties
 
 Quo uses the `Literal` gem for typed properties:
@@ -89,7 +199,7 @@ Quo uses the `Literal` gem for typed properties:
 class UsersByState < Quo::RelationBackedQuery
   prop :state, String
   prop :minimum_age, Integer, default: -> { 18 }
-  prop :active_only, Boolean, default: -> { true }
+  prop :active_only, _Boolean, default: -> { true }
 
   def query
     scope = User.where(state: state)
@@ -102,30 +212,6 @@ end
 query = UsersByState.new(state: "California", minimum_age: 21)
 ```
 
-## Fluent API for Building Queries
-
-```ruby
-query = UsersByState.new(state: "California")
-  .order(created_at: :desc)
-  .includes(:profile)
-  .limit(10)
-  .where(verified: true)
-
-users = query.results
-```
-
-Available methods include:
-* `where`
-* `order`
-* `limit`
-* `includes`
-* `preload`
-* `left_outer_joins`
-* `joins`
-* `group`
-
-Each method returns a new query instance without modifying the original.
-
 ## Pagination
 
 ```ruby
@@ -135,17 +221,17 @@ query = UsersByState.new(
   page_size: 20
 )
 
-# Get paginated results
+# Get paginated results for page 2 with 20 items
 users = query.results
 
-# Navigation
+# Navigation to next and previous pages creates new queries
 next_page = query.next_page_query
 prev_page = query.previous_page_query
 ```
 
 ## Composing Queries
 
-Combine multiple queries:
+Quo provides extensive query composition capabilities, letting you combine multiple query objects:
 
 ```ruby
 class ActiveUsers < Quo::RelationBackedQuery
@@ -160,38 +246,73 @@ class PremiumUsers < Quo::RelationBackedQuery
   end
 end
 
-# Compose queries
+# Compose queries using the + operator
 active_premium = ActiveUsers.new + PremiumUsers.new
 users = active_premium.results
 ```
 
-You can compose queries using:
-* `Quo::Query.compose(left, right)`
-* `left.compose(right)`
-* `left + right`
+You can compose queries in several ways:
+* At the class level: `ActiveUsers.compose(PremiumUsers)` or `ActiveUsers + PremiumUsers`
+* At the instance level: `active_query.merge(premium_query)` or `active_query + premium_query`
+* With joins: `active_query.merge(premium_query, joins: :some_association)`
 
-### Composing with Joins
+Quo handles different composition scenarios automatically:
+* Relation + Relation: Uses ActiveRecord's merge capabilities
+* Relation + Collection: Combines the results of both
+* Collection + Collection: Concatenates the collections
+
+For example, to compose query objects with proper joins:
 
 ```ruby
-class ProductsQuery < Quo::RelationBackedQuery
+# Query for posts
+class PostsQuery < Quo::RelationBackedQuery
   def query
-    Product.where(active: true)
+    Post.where(published: true)
   end
 end
 
-class CategoriesQuery < Quo::RelationBackedQuery
+# Query for authors
+class AuthorsQuery < Quo::RelationBackedQuery
   def query
-    Category.where(featured: true)
+    Author.where(active: true)
   end
 end
 
-# Compose with a join
-products = ProductsQuery.new.compose(CategoriesQuery.new, joins: :category)
+# Compose with a joins parameter to specify the relationship
+composed_query = PostsQuery.new.merge(AuthorsQuery.new, joins: :author)
+# You can also use this equivalent form:
+# composed_query = PostsQuery.new.joins(:author) + AuthorsQuery.new
 
-# Equivalent to:
-# Product.joins(:category)
-#        .where(products: { active: true })
-#        .where(categories: { featured: true })
+# Returns published posts by active authors
+results = composed_query.results
+```
+
+
+## Utility Methods
+
+Quo query objects provide several utility methods to help you work with them:
+
+```ruby
+query = UsersByState.new(state: "California")
+
+# Check query type
+query.relation?   # => true if backed by an ActiveRecord relation
+query.collection? # => true if backed by a collection
+
+# Check pagination status
+query.paged?      # => true if pagination is enabled (page is set)
+
+# Check transformation status
+query.transform?  # => true if a transformer is set
+
+# Get the raw underlying query without pagination
+raw_query = query.unwrap_unpaginated  # => The ActiveRecord relation or collection
+
+# Get the configured query with pagination
+configured_query = query.unwrap  # => The query with pagination applied
+
+# For RelationBackedQuery, get SQL representation
+puts query.to_sql  # => "SELECT users.* FROM users WHERE users.state = 'California'"
 ```
 
 ## Transforming Results
@@ -204,42 +325,190 @@ query = UsersByState.new(state: "California")
 presenters = query.results.to_a # Array of UserPresenter objects
 ```
 
-## Custom Association Preloading
+## Working with Results Objects
+
+When you call `.results` on a query object, you get a `Results` object that wraps the underlying collection and ensures consistent application of transformations.
+
+```ruby
+# Create a query with a transformer
+users_query = UsersByState.new(state: "California")
+  .transform { |user| UserPresenter.new(user) }
+
+# Get results - transformations are applied consistently
+results = users_query.results
+
+# Existence checks
+results.exists?  # => true/false
+results.empty?   # => false/true
+
+# Count methods
+results.count        # Total count of results (ignoring pagination)
+results.total_count  # Same as count
+results.size         # Same as count
+results.page_count   # Count of items on current page (respects pagination)
+results.page_size    # Same as page_count
+
+# Enumerable methods - all respect transformations
+results.each { |presenter| puts presenter.formatted_name }
+results.map { |presenter| presenter.email }
+results.select { |presenter| presenter.active? }
+results.reject { |presenter| presenter.inactive? }
+results.first  # Returns the first transformed item
+results.last   # Returns the last transformed item
+results.first(3)  # Returns the first 3 transformed items
+results.to_a  # Returns all transformed items as an array
+
+# ActiveRecord extensions (for RelationResults)
+results.find(123)  # Find by id and transform
+results.find_by(email: "user@example.com")  # Find by attributes and transform
+results.where(active: true)  # Returns a new Results with the condition applied
+
+# Methods are delegated to the underlying collection
+# and transformations are applied consistently
+results.group_by(&:role)  # Groups transformed objects by role
+```
+
+Quo provides two types of Results objects:
+- `RelationResults` - For ActiveRecord-based queries, delegates to the underlying relation
+- `CollectionResults` - For collection-based queries, delegates to the enumerable collection
+
+## Fluent API for Building Queries
+
+Quo implements a fluent API that mirrors ActiveRecord's query interface, allowing you to chain methods that build up your query:
+
+```ruby
+# Start with a base query
+query = UsersByState.new(state: "California")
+
+# Chain method calls to build your query
+refined_query = query
+  .order(created_at: :desc)    # Order results
+  .includes(:profile, :posts)  # Eager load associations
+  .joins(:posts)               # Join with posts
+  .where(verified: true)       # Add conditions
+  .limit(10)                   # Limit results
+  .group("users.role")         # Group results
+  
+# Original query remains unchanged
+original_results = query.results
+refined_results = refined_query.results
+
+# You can further refine as needed
+admin_query = refined_query.where(role: "admin")
+```
+
+Available methods for relation-backed queries include:
+* `where` - Add conditions to the query
+* `not` - Negate conditions
+* `or` - Add OR conditions
+* `order` - Set the order of results
+* `reorder` - Replace existing order
+* `limit` - Limit the number of results
+* `offset` - Set an offset for results
+* `includes` - Eager load associations
+* `preload` - Preload associations
+* `eager_load` - Eager load with LEFT OUTER JOIN
+* `joins` - Add inner joins
+* `left_outer_joins` - Add left outer joins
+* `group` - Group results
+* `select` - Specify columns to select
+* `distinct` - Return distinct results
+
+Each method returns a new query instance without modifying the original, ensuring queries are immutable and can be safely composed.
+
+## Association Preloading in Collection-Backed Queries
+
+When working with enumerable collections of ActiveRecord models, you can still preload associations to avoid N+1 queries. This is particularly useful when you have collections that don't come directly from the database but still need efficient association loading.
+
+Include the `Quo::Preloadable` module in your collection-backed query and use the `includes` or `preload` methods:
 
 ```ruby
-class UsersWithOrders < Quo::RelationBackedQuery
+class FirstAndLastUsers < Quo::CollectionBackedQuery
   include Quo::Preloadable
   
+  def collection
+    [User.first, User.last] # These users come from separate queries
+  end
+end
+
+# Preload the profiles and posts for both users in a single efficient query
+query = FirstAndLastUsers.new.includes(:profile, :posts)
+
+# Check that the association is loaded
+query.results.first.profile.loaded? # => true
+query.results.last.posts.loaded? # => true
+
+# Access the preloaded associations without triggering additional queries
+query.results.each do |user|
+  puts "#{user.name} has #{user.posts.size} posts"
+end
+```
+
+The `Preloadable` module overrides the `query` method to apply ActiveRecord's preloader to your collection.
+
+### Composing with Joins
+
+```ruby
+class ProductsQuery < Quo::RelationBackedQuery
   def query
-    User.all
+    Product.where(active: true)
   end
+end
 
-  def preload_associations(collection)
-    # Custom preloading logic
-    ActiveRecord::Associations::Preloader.new(
-      records: collection,
-      associations: [:profile, :orders]
-    ).call
-    
-    collection
+class CategoriesQuery < Quo::RelationBackedQuery
+  def query
+    Category.where(featured: true)
   end
 end
+
+# Compose with a join
+products = ProductsQuery.new.merge(CategoriesQuery.new, joins: :category)
+
+# Equivalent to:
+# Product.joins(:category)
+#        .where(products: { active: true })
+#        .where(categories: { featured: true })
 ```
 
 ## Testing Helpers
 
+Quo provides testing helpers for both Minitest and RSpec to make your query objects easy to test in isolation.
+
 ### Minitest
 
+The `Quo::Minitest::Helpers` module includes the `fake_query` method that lets you mock query results without hitting the database:
+
 ```ruby
 class UserQueryTest < ActiveSupport::TestCase
   include Quo::Minitest::Helpers
 
   test "filters users by state" do
+    # Create test data
     users = [User.new(name: "Alice"), User.new(name: "Bob")]
     
+    # Mock the query results within the block
     fake_query(UsersByState, results: users) do
+      # Any instance of UsersByState created inside this block
+      # will return the mocked results regardless of query parameters
       result = UsersByState.new(state: "California").results.to_a
       assert_equal users, result
+      
+      # You can create multiple instances with different parameters
+      other_result = UsersByState.new(state: "New York").results.to_a
+      assert_equal users, other_result
+    end
+    
+    # After the block, normal behavior resumes
+  end
+  
+  test "works with pagination" do
+    users = (1..10).map { |i| User.new(name: "User #{i}") }
+    
+    fake_query(UsersByState, results: users) do
+      # Pagination still works with fake query results
+      paginated = UsersByState.new(state: "California", page: 1, page_size: 5).results
+      assert_equal 5, paginated.page_count
+      assert_equal 10, paginated.total_count
     end
   end
 end
@@ -247,9 +516,11 @@ end
 
 ### RSpec
 
+The same functionality is available for RSpec through the `Quo::Rspec::Helpers` module:
+
 ```ruby
 RSpec.describe UsersByState do
-  include Quo::RSpec::Helpers
+  include Quo::Rspec::Helpers
 
   it "filters users by state" do
     users = [User.new(name: "Alice"), User.new(name: "Bob")]
@@ -257,6 +528,26 @@ RSpec.describe UsersByState do
     fake_query(UsersByState, results: users) do
       result = UsersByState.new(state: "California").results.to_a
       expect(result).to eq(users)
+      
+      # Test that transformations still work
+      transformed = UsersByState.new(state: "California")
+        .transform { |user| user.name.upcase }
+        .results
+        
+      expect(transformed.first).to eq("ALICE")
+    end
+  end
+  
+  it "can be nested for testing composed queries" do
+    users = [User.new(name: "Alice", active: true)]
+    premium_users = [User.new(name: "Bob", subscription: "premium")]
+    
+    # Nested fake_query calls for testing composition
+    fake_query(ActiveUsers, results: users) do
+      fake_query(PremiumUsers, results: premium_users) do
+        composed = ActiveUsers.new + PremiumUsers.new
+        expect(composed.results.count).to eq(2)
+      end
     end
   end
 end
@@ -307,18 +598,31 @@ $ bundle install
 
 ## Configuration
 
+Quo provides several configuration options to customize its behavior to your needs. Configure these in an initializer:
+
 ```ruby
 # 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"
+module Quo
+  # Set the default number of items per page (default: 20)
+  self.default_page_size = 25
+  
+  # Set the maximum allowed page size to prevent excessive resource usage (default: 200)
+  self.max_page_size = 100
+  
+  # Set custom base classes for your queries
+  # These must be string names of constantizable classes that inherit from 
+  # Quo::RelationBackedQuery and Quo::CollectionBackedQuery respectively
+  self.relation_backed_query_base_class = "ApplicationQuery"
+  self.collection_backed_query_base_class = "ApplicationCollectionQuery"
+end
 ```
 
+Using custom base classes lets you add functionality that's shared across all your query objects in your application.
+
 ## Requirements
 
 - Ruby 3.1+
-- Rails 7.0+
+- Rails 7.0+, 8.0+
 
 ## Development
 

data/Rakefile

@@ -1,14 +1,74 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+desc "Run tests"
+task :test do
+  sh "bin/test"
 end
 
 require "standard/rake"
 
 task default: %i[test standard]
+
+# Add RubyCritic task with badge generation
+begin
+  require "rubycritic_small_badge"
+  require "rubycritic/rake_task"
+
+  RubyCriticSmallBadge.configure do |config|
+    config.minimum_score = 90
+  end
+
+  RubyCritic::RakeTask.new do |task|
+    task.paths = FileList["lib/**/*.rb"]
+
+    task.options = %(--custom-format RubyCriticSmallBadge::Report
+      --minimum-score #{RubyCriticSmallBadge.config.minimum_score}
+      --coverage-path coverage/.resultset.json
+      --no-browser)
+  end
+
+  desc "Run tests with coverage and then RubyCritic"
+  task rubycritic_with_coverage: [:coverage, :rubycritic]
+rescue LoadError
+  desc "Run RubyCritic (not available)"
+  task :rubycritic do
+    puts "RubyCritic is not available"
+  end
+end
+
+desc "Run code coverage"
+task :coverage do
+  ENV["COVERAGE"] = "1"
+  Rake::Task["test"].invoke
+end
+
+namespace :website do
+  desc "Build the documentation website"
+  task :build do
+    Dir.chdir("website") do
+      puts "Building documentation website..."
+      system "bundle install"
+      system "bundle exec jekyll build"
+      puts "Website built in website/_site/"
+    end
+  end
+
+  desc "Serve the documentation website locally"
+  task :serve do
+    Dir.chdir("website") do
+      puts "Starting local documentation server..."
+      puts "View the website at http://localhost:4000/"
+      system "bundle install"
+      system "bundle exec jekyll serve"
+    end
+  end
+
+  desc "Clean the documentation website build"
+  task :clean do
+    Dir.chdir("website") do
+      puts "Cleaning website build..."
+      system "bundle exec jekyll clean"
+    end
+  end
+end