quo 1.0.0.beta2 → 2.0.0

data/website/_docs/api.md

@@ -0,0 +1,261 @@
+---
+title: API Reference
+nav_order: 3
+---
+
+# API Reference
+
+## Query Object Classes
+
+### Quo::RelationBackedQuery
+
+Base class for queries that work with ActiveRecord relations.
+
+```ruby
+class MyQuery < Quo::RelationBackedQuery
+  prop :some_filter, String
+
+  def query
+    MyModel.where(column: some_filter)
+  end
+end
+```
+
+**Key Methods:**
+- `query` - Must be implemented to return an ActiveRecord relation
+- `results` - Returns a Results object with the query results
+- `unwrap` - Returns the underlying relation with pagination applied
+- `unwrap_unpaginated` - Returns the underlying relation without pagination
+- `to_sql` - Returns the SQL representation of the query
+
+### Quo::CollectionBackedQuery
+
+Base class for queries that work with any Enumerable collection.
+
+```ruby
+class MyCollectionQuery < Quo::CollectionBackedQuery
+  prop :filter_value, String
+
+  def collection
+    [1, 2, 3, 4, 5].select { |n| n > filter_value.to_i }
+  end
+end
+```
+
+**Key Methods:**
+- `collection` - Must be implemented to return an Enumerable
+- `results` - Returns a Results object with the collection results
+- `unwrap` - Returns the underlying collection with pagination applied
+- `unwrap_unpaginated` - Returns the underlying collection without pagination
+
+## Common Query Methods
+
+Both query types support these methods:
+
+### Property Definition
+
+```ruby
+prop :property_name, Type, default: -> { default_value }
+```
+
+Define typed properties using [Literal types](https://github.com/joeldrapper/literal). Common examples:
+
+```ruby
+# Basic types
+prop :name, String
+prop :age, Integer
+prop :active, _Boolean  # Use _Boolean for true/false
+
+# Optional types
+prop :email, String | nil
+
+# Collections
+prop :tags, _Array(String)
+prop :metadata, _Hash(Symbol, String)
+```
+
+### Pagination
+
+```ruby
+MyQuery.new(page: 1, page_size: 20)
+query.next_page_query
+query.previous_page_query
+query.paged? # => true/false
+```
+
+### Composition
+
+```ruby
+# Instance-level: Merge query instances
+query1 + query2                              # Returns a new query instance
+query1.merge(query2)                         # Returns a new query instance
+query1.merge(query2, joins: :association)    # Returns a new query instance
+
+# Class-level: Compose query classes
+ComposedQuery = Query1 + Query2              # Returns a new query CLASS
+ComposedQuery = Query1.compose(Query2)       # Returns a new query CLASS
+ComposedQuery.new                            # Create an instance of composed class
+```
+
+### Transformation
+
+```ruby
+# Transform results with a block
+query.transform { |item| ItemPresenter.new(item) }
+query.transform { |item, index| ItemPresenter.new(item, position: index) }
+query.transform? # => true/false
+```
+
+### Fluent API (RelationBackedQuery)
+
+Chain ActiveRecord methods to build complex queries:
+
+```ruby
+# Filtering, ordering, and associations
+query.where(column: value)
+query.select(:column1, :column2)
+query.order(created_at: :desc)
+query.reorder(updated_at: :asc)
+query.joins(:association)
+query.left_outer_joins(:association)
+query.includes(:profile, :posts)  # Alias for preload (not ActiveRecord's includes)
+query.preload(:comments)
+query.eager_load(:tags)
+
+# Limiting and grouping
+query.limit(10).offset(5)
+query.group(:category).distinct
+
+# Advanced
+query.extending(MyQueryExtension)
+query.unscope(:order, :limit)
+```
+
+### Query Helpers
+
+```ruby
+# Check query type
+query.relation?   # => true if backed by ActiveRecord relation
+query.collection? # => true if backed by a collection
+
+# Create a query class from a relation or collection
+# IMPORTANT: wrap returns a new query CLASS, not an instance!
+MyQuery = Quo::RelationBackedQuery.wrap(User.active)
+instance = MyQuery.new  # Must call .new to create an instance
+
+# With dynamic properties - still returns a CLASS
+MyQuery = Quo::RelationBackedQuery.wrap(props: {role: String}) { User.where(role: role) }
+instance = MyQuery.new(role: "admin")  # Must call .new with props
+
+# Convert a RelationBackedQuery to CollectionBackedQuery (executes the query)
+collection_query = query.to_collection
+collection_query = query.to_collection(total_count: 100)  # Optional total count
+```
+
+## Results Objects
+
+### RelationResults
+
+Returned by `RelationBackedQuery#results`.
+
+**Methods:**
+- `each`, `map`, `select`, `reject` - Enumerable methods with transformation support
+- `first`, `last`, `first(n)`, `last(n)` - Access specific items
+- `count`, `total_count`, `size` - Total count of ALL results (ignores pagination)
+- `page_count`, `page_size` - Count of items on CURRENT page only
+- `exists?`, `empty?` - Existence checks
+- `to_a` - Convert to array
+- `find(id)`, `find_by(attributes)` - ActiveRecord finder methods
+
+**Note:** Transformations are applied to all items returned by result methods.
+
+### CollectionResults
+
+Returned by `CollectionBackedQuery#results`.
+
+**Methods:**
+- Same as RelationResults, except ActiveRecord-specific methods like `find` and `find_by`
+
+## Configuration
+
+```ruby
+module Quo
+  # Set custom base classes
+  self.relation_backed_query_base_class = "ApplicationQuery"
+  self.collection_backed_query_base_class = "ApplicationCollectionQuery"
+
+  # Configure pagination defaults
+  self.default_page_size = 25  # Default: 20
+  self.max_page_size = 100     # Default: 200
+end
+```
+
+## Preloading Associations (CollectionBackedQuery)
+
+Preload associations for CollectionBackedQuery objects containing ActiveRecord models:
+
+```ruby
+class FirstAndLastPosts < Quo::CollectionBackedQuery
+  include Quo::Preloadable
+
+  def collection
+    [Post.first, Post.last]
+  end
+end
+
+# Preload associations to avoid N+1 queries
+query = FirstAndLastPosts.new.includes(:author, :comments)
+
+# Access preloaded data without additional queries
+query.results.each do |post|
+  puts "#{post.title} by #{post.author.name} (#{post.comments.count} comments)"
+end
+```
+
+**Note:** Quo's `includes` is an alias for `preload` (not ActiveRecord's `includes` which uses eager loading). Both preload associations without joining.
+
+## Testing Helpers
+
+### Minitest
+
+```ruby
+include Quo::Minitest::Helpers
+
+# Basic usage
+fake_query(MyQuery, results: [item1, item2]) do
+  result = MyQuery.new.results.to_a
+  assert_equal [item1, item2], result
+end
+
+# With pagination metadata
+fake_query(MyQuery, results: [item1, item2], total_count: 100, page_count: 2) do
+  results = MyQuery.new.results
+  assert_equal 100, results.total_count  # Total across all pages
+  assert_equal 2, results.page_count     # Items on current page
+end
+```
+
+### RSpec
+
+```ruby
+include Quo::Rspec::Helpers
+
+# Basic usage
+fake_query(MyQuery, results: [item1, item2]) do
+  result = MyQuery.new.results.to_a
+  expect(result).to eq([item1, item2])
+end
+
+# With specific argument expectations
+fake_query(MyQuery, with: {role: "admin"}, results: [admin1, admin2]) do
+  result = MyQuery.new(role: "admin").results.to_a
+  expect(result).to eq([admin1, admin2])
+end
+
+# With pagination metadata
+fake_query(MyQuery, results: [item1, item2], total_count: 100, page_count: 2) do
+  results = MyQuery.new.results
+  expect(results.total_count).to eq(100)  # Total across all pages
+  expect(results.page_count).to eq(2)     # Items on current page
+end
+```

data/website/_docs/get-started.md

@@ -0,0 +1,289 @@
+---
+title: Core API
+nav_order: 2
+---
+
+# Quo Core API
+
+This section covers the core functionality of Quo, including:
+
+- Creating query objects
+- Working with relations and collections
+- Type-safe properties
+- Pagination
+- Query composition
+- Result transformation
+- Fluent API methods
+
+# Configuration
+
+Quo provides several configuration options to customize its behavior.
+
+Create an initializer to configure Quo:
+
+```ruby
+# config/initializers/quo.rb
+module Quo
+  # Set custom base classes for your queries
+  self.relation_backed_query_base_class = "ApplicationQuery"
+  self.collection_backed_query_base_class = "ApplicationCollectionQuery"
+
+  # Configure pagination defaults
+  self.default_page_size = 25  # Default: 20
+  self.max_page_size = 100     # Default: 200
+end
+```
+
+
+## Custom Base Classes
+
+You can define your own base classes for queries to add application-specific functionality:
+
+```ruby
+# app/queries/application_query.rb
+class ApplicationQuery < Quo::RelationBackedQuery
+  # Add common scopes or methods using the fluent API
+
+  def with_status(status)
+    with(where: {status: status})
+  end
+end
+
+# app/queries/application_collection_query.rb
+class ApplicationCollectionQuery < Quo::CollectionBackedQuery
+  # Add common collection processing
+end
+```
+
+Now all your queries can inherit from these custom base classes:
+
+```ruby
+class UsersQuery < ApplicationQuery
+  def query
+    User.all
+  end
+end
+
+# Use the custom methods
+UsersQuery.new.with_status("active").results
+```
+
+## Project Organization
+
+Suggested directory structure:
+
+```
+app/
+  queries/
+    application_query.rb
+    application_collection_query.rb
+    users/
+      active_users_query.rb
+      by_role_query.rb
+    posts/
+      published_posts_query.rb
+      recent_posts_query.rb
+```
+
+This organization keeps your query objects well-organized and easy to find.
+
+
+# Usage Examples
+
+This page provides real-world examples of using Quo in your Rails application.
+
+## Basic Query Object
+
+```ruby
+class ActiveUsersQuery < Quo::RelationBackedQuery
+  def query
+    User.where(active: true)
+  end
+end
+
+# Usage
+active_users = ActiveUsersQuery.new.results.to_a
+```
+
+## Query with Properties
+
+```ruby
+class UsersByRoleQuery < Quo::RelationBackedQuery
+  prop :role, String
+  prop :active_only, _Boolean, default: -> { true }
+
+  def query
+    scope = User.where(role: role)
+    scope = scope.where(active: true) if active_only
+    scope
+  end
+end
+
+# Usage
+admins = UsersByRoleQuery.new(role: "admin").results
+all_moderators = UsersByRoleQuery.new(role: "moderator", active_only: false).results
+```
+
+## Pagination
+
+```ruby
+class PostsQuery < Quo::RelationBackedQuery
+  prop :published_only, _Boolean, default: -> { true }
+
+  def query
+    scope = Post.order(created_at: :desc)
+    scope = scope.where(published: true) if published_only
+    scope
+  end
+end
+
+# Usage with pagination
+page1 = PostsQuery.new(page: 1, page_size: 20).results
+page2 = PostsQuery.new(page: 2, page_size: 20).results
+
+# Navigate between pages
+query = PostsQuery.new(page: 1, page_size: 20)
+next_query = query.next_page_query
+prev_query = query.previous_page_query
+```
+
+## Query Composition
+
+```ruby
+class PublishedPostsQuery < Quo::RelationBackedQuery
+  def query
+    Post.where(published: true)
+  end
+end
+
+class FeaturedPostsQuery < Quo::RelationBackedQuery
+  def query
+    Post.where(featured: true)
+  end
+end
+
+# Compose queries
+published_and_featured = PublishedPostsQuery.new + FeaturedPostsQuery.new
+results = published_and_featured.results
+```
+
+## Composition with Joins
+
+```ruby
+class PostsByAuthorQuery < Quo::RelationBackedQuery
+  prop :author_name, String
+
+  def query
+    Author.where("name LIKE ?", "%#{author_name}%")
+  end
+end
+
+class PublishedPostsQuery < Quo::RelationBackedQuery
+  def query
+    Post.where(published: true)
+  end
+end
+
+# Compose with explicit joins
+posts = PublishedPostsQuery.new
+  .merge(PostsByAuthorQuery.new(author_name: "John"), joins: :author)
+  .results
+```
+
+## Result Transformation
+
+```ruby
+class UserPresenter
+  attr_reader :user, :position
+
+  def initialize(user, position: nil)
+    @user = user
+    @position = position
+  end
+
+  def formatted_name
+    prefix = position ? "#{position + 1}. " : ""
+    "#{prefix}#{user.first_name} #{user.last_name}"
+  end
+end
+
+# Apply transformation
+query = ActiveUsersQuery.new
+  .transform { |user| UserPresenter.new(user) }
+
+# With index parameter
+query = ActiveUsersQuery.new
+  .transform { |user, index| UserPresenter.new(user, position: index) }
+
+query.results.each do |presenter|
+  puts presenter.formatted_name
+end
+```
+
+## Collection-Backed Queries
+
+```ruby
+class TopRatedItemsQuery < Quo::CollectionBackedQuery
+  prop :minimum_rating, _Float(0..5.0), default: -> { 4.0 }
+
+  def collection
+    # Maybe from a cache or external API
+    cached_items = Rails.cache.fetch("all_items") { Item.all.to_a }
+    cached_items.select { |item| item.rating >= minimum_rating }
+  end
+end
+
+# Usage
+top_items = TopRatedItemsQuery.new(minimum_rating: 4.5).results
+```
+
+## Fluent API Methods
+
+For detailed information on the fluent API methods (where, order, includes, limit, etc.), see the [API Reference](/api/).
+
+```ruby
+query = PostsQuery.new
+  .where(category: "Technology")
+  .order(published_at: :desc)
+  .includes(:author, :comments)
+  .limit(10)
+
+results = query.results
+```
+
+## Testing with Helpers
+
+### Minitest
+
+```ruby
+class UserQueryTest < ActiveSupport::TestCase
+  include Quo::Minitest::Helpers
+
+  test "returns active users" do
+    users = [User.new(name: "Alice"), User.new(name: "Bob")]
+
+    fake_query(ActiveUsersQuery, results: users) do
+      result = ActiveUsersQuery.new.results.to_a
+      assert_equal users, result
+    end
+  end
+end
+```
+
+### RSpec
+
+```ruby
+RSpec.describe ActiveUsersQuery do
+  include Quo::Rspec::Helpers
+
+  it "returns active users" do
+    users = [User.new(name: "Alice"), User.new(name: "Bob")]
+
+    fake_query(ActiveUsersQuery, results: users) do
+      result = ActiveUsersQuery.new.results.to_a
+      expect(result).to eq(users)
+    end
+  end
+end
+```
+

data/website/index.md

@@ -0,0 +1,141 @@
+---
+layout: home
+title: Introduction
+permalink: /
+
+hero:
+  name: Quo
+  text: Query Objects for ActiveRecord & Collections
+  tagline: Composable, testable, and reusable query objects for Ruby on Rails.
+  image:
+    src: /assets/quo.png
+    alt: Quo
+    width: 280
+    height: 280
+  actions:
+    - text: Get Started
+      link: /get-started/
+      theme: brand
+    - text: API Reference
+      link: /api/
+      theme: alt
+    - text: View on GitHub
+      link: https://github.com/stevegeek/quo
+      theme: alt
+
+features:
+  - title: Organize complex queries
+    details: Encapsulate query logic in dedicated, testable classes with a clean, fluent API.
+  - title: Composable
+    details: Combine multiple query objects using the `+` operator at both the instance and class level.
+  - title: Type-safe
+    details: Built on the Literal gem for typed properties with validation.
+  - title: Pagination built-in
+    details: Automatic pagination for both database and collection queries.
+  - title: Flexible
+    details: Works with ActiveRecord relations and plain Ruby collections.
+  - title: Fluent API
+    details: Chain methods just like ActiveRecord.
+---
+
+## What is Quo?
+
+`quo` is a Ruby gem that helps you organize database and collection queries into reusable, composable, and testable objects with a clean, fluent API.
+
+## 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
+
+# Compose queries
+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)
+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
+```
+
+## Getting Started
+
+Explore the documentation to learn more:
+
+- [Getting Started Guide](/get-started/) - Configuration, examples, and usage patterns
+- [API Reference](/api/) - Detailed API documentation
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "quo"
+```
+
+Then execute:
+
+```
+$ bundle install
+```
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.2+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/stevegeek/quo](https://github.com/stevegeek/quo).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Inspiration
+
+This implementation is inspired by the [Rectify](https://github.com/andypike/rectify) gem by Andy Pike. Thanks for the inspiration!
+
+**Key differences to Quo:**
+- Much broader scope—bundles forms, presenters, commands, AND queries where Quo focuses only on queries
+- No longer actively maintained
+- Uses Wisper pub/sub pattern for commands; Quo has simpler return values
+- Lacks the type-safety emphasis that Quo provides
+- Query composition with `|` operator directly inspired Quo's composable design
+
+**Quo as an alternative?**
+
+Quo can be seen as a successor to Rectify's query object concepts.