quo 1.0.0.beta2 → 2.0.0

data/README.md

@@ -1,335 +1,628 @@
-# 'Quo' query objects for ActiveRecord
+<p align="center">
+  <img src="quo.png" alt="Quo" width="160" height="160" />
+</p>
 
-> Note: these docs are for pre-V1 and need updating. I'm working on it!
+# Quo: Query Objects for ActiveRecord & Collections
 
-Quo query objects can help you abstract ActiveRecord DB queries into reusable and composable objects with a chainable
-interface.
+![Coverage](badges/coverage_badge_total.svg)
+![RubyCritic](badges/rubycritic_badge_score.svg)
 
-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.
+Quo helps you organize database and collection queries into reusable, composable, and testable objects.
 
-The core implementation provides the following functionality:
+## Quick Example
 
-* 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
-* acts as a callable which executes the underlying query with `.first`
-* can return an `Enumerable` of results
+```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
 
-`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.
+# Navigate between pages
+page2_query = posts_query.next_page_query
+page2 = page2_query.results
+# => Returns next 10 posts
 
-## Creating a Quo query object
+class CommentNotSpamQuery < Quo::RelationBackedQuery
+  prop :spam_score_threshold, _Float(0..1.0)
 
-The query object must inherit from `Quo::Query` and provide an implementation for the `query` method.
+  def query
+    comments = Comment.arel_table
+    Comment.where(
+      comments[:spam_score].eq(nil).or(comments[:spam_score].lt(spam_score_threshold))
+    )
+  end
+end
 
-The `query` method must return either:
+# Get recent posts (last 10 days) which have comments that are not Spam
+posts_last_10_days = RecentPostsQuery.new(days_ago: 10).joins(:comments)
 
-- an `ActiveRecord::Relation`
-- an Enumerable (like a 'collection backed' query) 
-- or another `Quo::Query` instance.
+# Compose your queries
+query = posts_last_10_days + CommentNotSpamQuery.new(spam_score_threshold: 0.5)
 
-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. 
+# Transform results
+transformed_query = query.transform { |post| PostPresenter.new(post) }
 
-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).
+# Work with result sets
+transformed_query.results.each do |presenter|
+  puts presenter.formatted_title
+end
+```
 
-## Passing options to queries
 
-If any parameters are need in `query`, these are provided when instantiating the query object using the `options` hash.
+## Core Features
 
-It is also possible to pass special configuration options to the constructor options hash. 
+### 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
 
-Specifically when the underlying collection is a ActiveRecord relation then:
+### 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
 
-* `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
+### 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
 
-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.
+### 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)
 
-## Configuring queries
+### 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
 
-Note that it is possible to configure a query using chainable methods similar to ActiveRecord:
 
-* limit
-* order
-* group
-* includes
-* left_outer_joins
-* preload
-* joins
+## Core Concepts
 
-Note that these return a new Quo Query and do not mutate the original instance.
+Query objects encapsulate query logic in dedicated classes, making complex queries more manageable and reusable.
 
-## Composition of queries (merging or combining them)
+Quo provides two main components:
+1. **Query Objects** - Define and configure queries
+2. **Results Objects** - Execute queries and provide access to the results
 
-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.
+## Creating Query Objects
 
-Composing can be done with either 
+### Relation-Backed Queries
 
-- `Quo::Query.compose(left, right)` 
-- or `left.compose(right)` 
-- or more simply with `left + right`
+For queries based on ActiveRecord relations:
 
-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.
+```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
 
-Note that the compose process creates a new query object instance, which is a instance of a `Quo::ComposedQuery`.
+# Create and use the query
+query = RecentActiveUsers.new(days_ago: 7)
+results = query.results
 
-Consider the following cases:
+# Work with results
+results.each { |user| puts user.email }
+puts "Found #{results.count} users"
+```
 
-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
+### Collection-Backed Queries
 
-In case (1) the compose process uses `ActiveRecords::Relation`'s `merge` method to create another query object
-wrapped around a new 'composed' `ActiveRecords::Relation`.
+For queries based on any Enumerable collection:
 
-In case (2) the query object with a `ActiveRecords::Relation` inside is executed, and the result is then concatenated
-to the array-like with `+`
+```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
 
-In case (3) the values contained are concatenated with `+`
+# Use the query
+admins = CachedUsers.new(role: "admin").results
+```
 
-*Note that*
+## Quick Queries with Wrap and to_collection
 
-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.
+### Creating Query Objects with Wrap
 
-### Examples
+Create query objects on the fly without subclassing using the `wrap` class method:
 
 ```ruby
-class CompanyToBeApproved < Quo::RelationBackedQuery
-  def query
-    Registration
-      .left_joins(:approval)
-      .where(approvals: {completed_at: nil})
-  end
+# Relation-backed query from an ActiveRecord relation
+users_query = Quo::RelationBackedQuery.wrap(User.active).new
+active_users = users_query.results
+
+# 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:
+
+```ruby
+class UsersByState < Quo::RelationBackedQuery
+  prop :state, String
+  prop :minimum_age, Integer, default: -> { 18 }
+  prop :active_only, _Boolean, default: -> { true }
 
-class CompanyInUsState < Quo::RelationBackedQuery
   def query
-    Registration
-      .joins(company: :address)
-      .where(addresses: {state: options[:state]})
+    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
 
-query1 = CompanyToBeApproved.new
-query2 = CompanyInUsState.new(state: "California")
-
-# Compose
-composed = query1 + query2 # or Quo::Query.compose(query1, query2) or query1.compose(query2)
-composed.first
+query = UsersByState.new(state: "California", minimum_age: 21)
 ```
 
-This effectively executes:
+## Pagination
 
 ```ruby
-Registration
-  .left_joins(:approval)
-  .joins(company: :address)
-  .where(approvals: {completed_at: nil})
-  .where(addresses: {state: options[:state]})
+query = UsersByState.new(
+  state: "California",
+  page: 2,
+  page_size: 20
+)
+
+# Get paginated results for page 2 with 20 items
+users = query.results
+
+# Navigation to next and previous pages creates new queries
+next_page = query.next_page_query
+prev_page = query.previous_page_query
 ```
 
-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:
+## Composing Queries
+
+Quo provides extensive query composition capabilities, letting you combine multiple query objects:
 
 ```ruby
-class RegistrationToBeApproved < Quo::RelationBackedQuery
+class ActiveUsers < Quo::RelationBackedQuery
+  def query
+    User.where(active: true)
+  end
+end
+
+class PremiumUsers < Quo::RelationBackedQuery
   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)
+    User.where(subscription_tier: "premium")
   end
 end
 
-# A Relation can be composed directly to a Quo::Query
-query = RegistrationToBeApproved.new + Registration.where(blocked: false)
+# Compose queries using the + operator
+active_premium = ActiveUsers.new + PremiumUsers.new
+users = active_premium.results
 ```
 
-Also you can use joins:
+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)`
+
+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 TagByName < Quo::RelationBackedQuery
+# Query for posts
+class PostsQuery < Quo::RelationBackedQuery
   def query
-    Tag.where(name: options[:name])
+    Post.where(published: true)
   end
 end
 
-class CategoryByName < Quo::RelationBackedQuery
+# Query for authors
+class AuthorsQuery < Quo::RelationBackedQuery
   def query
-    Category.where(name: options[:name])
+    Author.where(active: 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 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 Tag.joins(:category).where(name: "Intel").where(categories: {name: "CPUs"})
+# Returns published posts by active authors
+results = composed_query.results
 ```
 
-Collection backed queries can also be composed (see below sections for more details).
 
-### Quo::ComposedQuery
+## Utility Methods
 
-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:
+Quo query objects provide several utility methods to help you work with them:
 
 ```ruby
-q = FooQuery.new + BarQuery.new
-puts q
-# > "Quo::ComposedQuery[FooQuery, BarQuery]"
-```
+query = UsersByState.new(state: "California")
 
-## Query Objects & Pagination
+# Check query type
+query.relation?   # => true if backed by an ActiveRecord relation
+query.collection? # => true if backed by a collection
 
-Specify extra options to enable pagination:
+# Check pagination status
+query.paged?      # => true if pagination is enabled (page is set)
 
-* `page`: the current page number to fetch
-* `page_size`: the number of elements to fetch in the page
+# Check transformation status
+query.transform?  # => true if a transformer is set
 
-### `Quo::CollectionBackedQuery` & `Quo::CollectionBackedQuery` objects
+# 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'"
+```
 
-`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.
+## Transforming Results
 
 ```ruby
-class MyCollectionBackedQuery < Quo::CollectionBackedQuery
-  def collection
-    [1, 2, 3]
-  end
-end
-q = MyCollectionBackedQuery.new
-q.collection? # is it a collection under the hood? Yes it is!
-q.count # '3'
+query = UsersByState.new(state: "California")
+  .transform { |user| UserPresenter.new(user) }
+
+# Results are automatically transformed
+presenters = query.results.to_a # Array of UserPresenter objects
 ```
 
-Sometimes it is useful to create similar Queries without needing to create a explicit subclass of your own. For this
-use `Quo::CollectionBackedQuery`:
+## 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
-q = Quo::CollectionBackedQuery.wrap([1, 2, 3])
-q.collection? # true
-q.count # '3'
+# 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::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.
+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
 
-Example of an CollectionBackedQuery used to wrap a page of enumerable data:
+Quo implements a fluent API that mirrors ActiveRecord's query interface, allowing you to chain methods that build up your query:
 
 ```ruby
-Quo::CollectionBackedQuery.wrap(my_data, total_count: 100, page: current_page)
+# 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")
 ```
 
-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.
+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.
 
-### Composition
+## Association Preloading in Collection-Backed Queries
 
-Examples of composition of eager loaded 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 CachedTags < Quo::RelationBackedQuery
-  def query
-    @tags ||= Tag.where(active: true).to_a
+class FirstAndLastUsers < Quo::CollectionBackedQuery
+  include Quo::Preloadable
+  
+  def collection
+    [User.first, User.last] # These users come from separate queries
   end
 end
 
-composed = CachedTags.new(active: false) + [1, 2]
-composed.last
-# => 2
-composed.first
-# => #<Tag id: ...>
+# Preload the profiles and posts for both users in a single efficient query
+query = FirstAndLastUsers.new.includes(:profile, :posts)
 
-Quo::CollectionBackedQuery.new([3, 4]).compose(Quo::CollectionBackedQuery.new([1, 2])).last
-# => 2
-Quo::Query.compose([1, 2], [3, 4]).last
-# => 4
-```
+# Check that the association is loaded
+query.results.first.profile.loaded? # => true
+query.results.last.posts.loaded? # => true
 
-## Transforming results
+# Access the preloaded associations without triggering additional queries
+query.results.each do |user|
+  puts "#{user.name} has #{user.posts.size} posts"
+end
+```
 
-Sometimes you want to specify a block to execute on each result for any method that returns results, such as `first`,
-`last` and `each`.
+The `Preloadable` module overrides the `query` method to apply ActiveRecord's preloader to your collection.
 
-This can be specified using the `transform(&block)` instance method. For example:
+### Composing with Joins
 
 ```ruby
-TagsQuery.new(
-  active: [true, false],
-  page: 1,
-  page_size: 30,
-).transform { |tag| TagPresenter.new(tag) }
- .first
-# => #<TagPresenter ...>
+class ProductsQuery < Quo::RelationBackedQuery
+  def query
+    Product.where(active: true)
+  end
+end
+
+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 })
 ```
 
-## Tests & stubbing
+## Testing Helpers
 
-Tests for Query objects themselves should exercise the actual underlying query. But in other code stubbing the query
-maybe desirable.
+Quo provides testing helpers for both Minitest and RSpec to make your query objects easy to test in isolation.
 
-The spec helper method `stub_query(query_class, {results: ..., with: ...})` can do this for you.
+### Minitest
 
-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.
+The `Quo::Minitest::Helpers` module includes the `fake_query` method that lets you mock query results without hitting the database:
 
-For example:
+```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
+```
+
+### RSpec
+
+The same functionality is available for RSpec through the `Quo::Rspec::Helpers` module:
 
 ```ruby
-stub_query(TagQuery, with: {name: "Something"}, results: [t1, t2])
-expect(TagQuery.new(name: "Something").first).to eql t1
+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)
+      
+      # 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
 ```
 
-*Note that*
+## Project Organization
 
-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!
+Suggested directory structure:
 
-If `compose` will be used then `Quo::Query.compose` needs to be stubbed. Something might be possible to make this
-nicer in future.
+```
+app/
+  queries/
+    application_query.rb
+    users/
+      active_users_query.rb
+      by_state_query.rb
+    products/
+      featured_products_query.rb
+```
 
-## Other reading
+Base classes:
 
-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)
+```ruby
+# app/queries/application_query.rb
+class ApplicationQuery < Quo::RelationBackedQuery
+  # Common functionality
+end
 
+# app/queries/application_collection_query.rb
+class ApplicationCollectionQuery < Quo::CollectionBackedQuery
+  # Common functionality
+end
+```
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add to your Gemfile:
+
+```ruby
+gem "quo"
+```
+
+Then execute:
+
+```
+$ bundle install
+```
+
+## Configuration
 
-    $ bundle add quo
+Quo provides several configuration options to customize its behavior to your needs. Configure these in an initializer:
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```ruby
+# config/initializers/quo.rb
+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
+```
 
-    $ gem install quo
+Using custom base classes lets you add functionality that's shared across all your query objects in your application.
 
-## Usage
+## Requirements
 
-TODO: Write usage instructions here
+- Ruby 3.1+
+- Rails 7.0+, 8.0+
 
 ## Development
 
@@ -343,7 +636,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/steveg
 
 ## Inspired by `rectify`
 
-Note this implementation is inspired by the `Rectify` gem; https://github.com/andypike/rectify. 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