quo 1.0.0.beta1 → 2.0.0

data/claude-skill/references/PAGINATION.md

@@ -0,0 +1,396 @@
+# Pagination Reference
+
+> **Targets Quo `~> 2.0`.**
+
+Quo provides built-in pagination for both `RelationBackedQuery` and
+`CollectionBackedQuery`. Pagination is consistent across query types and
+integrates with composition and transformers without surprise.
+
+## Page parameters
+
+Every Quo query accepts two pagination kwargs:
+
+```ruby
+query = CommentsByAuthorQuery.new(
+  author_id: 1,
+  page: 2,        # 1-indexed
+  page_size: 25
+)
+results = query.results
+```
+
+### Defaults
+
+`page` has no default — it stays `nil` unless you pass it, and a query
+with `nil` page is unpaginated. `page_size` defaults to
+`Quo.default_page_size` (20).
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1)
+query.page       # => nil
+query.page_size  # => 20 (or whatever Quo.default_page_size is)
+query.paged?     # => false
+```
+
+You can configure the default page size globally:
+
+```ruby
+# config/initializers/quo.rb
+Quo.default_page_size = 25
+```
+
+There's also a hard cap (`Quo.max_page_size`, default 200) that protects
+against runaway page sizes from untrusted input.
+
+### Checking pagination status
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1)
+query.paged?  # => true
+
+unpaginated = CommentsByAuthorQuery.new(author_id: 1, page: nil)
+unpaginated.paged?  # => false
+```
+
+## Working with results
+
+### Counts
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 2, page_size: 25)
+results = query.results
+
+results.count       # total across all pages
+results.page_count  # rows in current page
+```
+
+### Existence
+
+```ruby
+results.empty?
+results.exists?
+```
+
+### Iteration
+
+Standard `Enumerable` works:
+
+```ruby
+results.each { |c| ... }
+results.map(&:body)
+results.select { |c| c.read? }
+results.first
+results.last
+```
+
+## Page navigation
+
+`#next_page_query` / `#previous_page_query` return new query objects;
+they don't mutate. They require a non-nil `page` — calling them on an
+unpaginated query raises `NoMethodError` (it computes `page + 1` on
+`nil`). If you might be on an unpaginated query, use `.copy(page: 2)`
+instead.
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 25)
+
+next_query = query.next_page_query
+next_query.page  # => 2
+
+prev_query = query.copy(page: 5).previous_page_query
+prev_query.page  # => 4
+```
+
+### Jumping to a specific page
+
+`#copy` lets you change any prop, including `page`:
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 25)
+page_5 = query.copy(page: 5)
+```
+
+### Offset
+
+Calculated from page and page_size:
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 3, page_size: 25)
+query.offset  # => 50  (page 3 starts at row 51, 0-indexed offset 50)
+```
+
+### Total page count
+
+There's no built-in `total_pages` — derive it from `results.count`:
+
+```ruby
+results = query.results
+total_pages = (results.count.to_f / query.page_size).ceil
+```
+
+### "Has next page?"
+
+```ruby
+def has_next_page?(query)
+  query.results.count > query.page * query.page_size
+end
+
+def has_previous_page?(query)
+  query.page > 1
+end
+```
+
+## Unpaginated access
+
+### Disable pagination explicitly
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: nil)
+query.paged?  # => false
+all = query.results.to_a
+```
+
+### Unwrap
+
+`#unwrap` returns the underlying relation/collection with paging applied
+if `paged?`. `#unwrap_unpaginated` gives you the full thing regardless.
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 2, page_size: 25)
+
+paginated_rel    = query.unwrap                # AR::Relation w/ LIMIT 25 OFFSET 25
+unpaginated_rel  = query.unwrap_unpaginated    # AR::Relation, no LIMIT/OFFSET
+```
+
+For collections you get the array slice or the full array.
+
+### Use cases for unpaginated
+
+- Exporting all rows to CSV
+- Aggregating across all rows
+- Caching the full materialised result
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1)
+
+CSV.generate do |csv|
+  query.unwrap_unpaginated.find_each(batch_size: 1_000) do |comment|
+    csv << [comment.id, comment.body]
+  end
+end
+```
+
+For very large result sets, use `find_each` (or `find_in_batches`)
+on the AR relation rather than materialising.
+
+## Pagination + composition
+
+### Composed queries inherit pagination as a coupled pair
+
+Pagination inherits *as a unit* — whichever operand has a non-nil
+`page` contributes both its `page` and its `page_size`. An operand
+with only `page_size` set is *not* paginated (every Quo::Query has a
+default `page_size`), so its `page_size` doesn't propagate.
+
+```ruby
+base = CommentsByAuthorQuery.new(author_id: 1, page: 2, page_size: 25)
+filter = UnreadCommentsQuery.new
+
+composed = base + filter
+composed.page       # => 2
+composed.page_size  # => 25
+composed.paged?     # => true
+```
+
+### Right wins when both operands are paginated
+
+```ruby
+left  = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 10)
+right = UnreadCommentsQuery.new(page: 3, page_size: 50)
+
+composed = left + right
+composed.page       # => 3
+composed.page_size  # => 50
+```
+
+If neither operand is paginated, the composed isn't either:
+
+```ruby
+left  = CommentsByAuthorQuery.new(author_id: 1, page_size: 10)  # no page set
+right = UnreadCommentsQuery.new(page_size: 20)                  # no page set
+
+composed = left + right
+composed.paged?     # => false
+composed.page       # => nil
+composed.page_size  # => 20 (the default — neither operand's page_size propagates without a page)
+```
+
+### Setting pagination after composition
+
+In practice, set pagination on the outermost composition, not on
+operands:
+
+```ruby
+composed = CommentsByAuthorQuery.new(author_id: 1) + UnreadCommentsQuery.new
+paginated = composed.copy(page: 1, page_size: 50)
+paginated.results
+```
+
+## Pagination + transformers
+
+Transformers carry through pagination unchanged.
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 25)
+  .transform { |c| CommentPresenter.new(c) }
+
+results = query.results
+results.first         # => CommentPresenter
+results.page_count    # => 25
+results.count         # => total across all pages
+
+next_results = query.next_page_query.results
+next_results.first    # => CommentPresenter (transformer preserved)
+```
+
+## Controller patterns
+
+### Basic pagination
+
+```ruby
+class CommentsController < ApplicationController
+  def index
+    @query = CommentsByAuthorQuery.new(
+      author_id: params[:author_id],
+      page: params[:page] || 1,
+      page_size: 25
+    )
+    @comments = @query.results
+  end
+end
+```
+
+### Caps on user-supplied page size
+
+```ruby
+def safe_page_size
+  raw = params[:per_page]&.to_i || 20
+  [raw, 100].min
+end
+```
+
+(Quo enforces its own `max_page_size` cap globally — this gives you a
+per-endpoint cap on top.)
+
+### Pagination metadata for an API response
+
+```ruby
+def index
+  query = CommentsByAuthorQuery.new(
+    author_id: current_user.id,
+    page: params[:page] || 1,
+    page_size: safe_page_size
+  )
+  results = query.results
+
+  render json: {
+    data: results.map { |c| {id: c.id, body: c.body} },
+    meta: {
+      current_page: query.page,
+      per_page: query.page_size,
+      total_count: results.count,
+      total_pages: (results.count.to_f / query.page_size).ceil,
+      has_next: results.count > query.page * query.page_size,
+      has_prev: query.page > 1,
+    },
+  }
+end
+```
+
+## Performance notes
+
+### RelationBackedQuery is efficient
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 25)
+query.results
+# SELECT comments.* FROM comments JOIN posts ... LIMIT 25 OFFSET 0
+# Only 25 rows materialised.
+```
+
+A separate count query is issued when you call `results.count`.
+
+### CollectionBackedQuery loads everything
+
+In-memory pagination slices an already-fully-materialised collection.
+That's appropriate for small/cached data, not for large datasets.
+
+### Avoid N+1 in a paginated query
+
+Eager-load associations the page will use:
+
+```ruby
+class CommentsByAuthorQuery < Quo::RelationBackedQuery
+  prop :author_id, Integer
+
+  def query
+    Comment
+      .joins(:post)
+      .includes(:post)                  # avoid N+1 on `comment.post`
+      .where(posts: {author_id: author_id})
+  end
+end
+```
+
+### Batch processing
+
+For full-dataset processing, skip pagination and use AR's batch API on
+the unpaginated relation:
+
+```ruby
+CommentsByAuthorQuery.new(author_id: 1)
+  .unwrap_unpaginated
+  .find_each(batch_size: 1_000) do |comment|
+    ProcessCommentJob.perform_later(comment.id)
+  end
+```
+
+## Testing pagination
+
+```ruby
+class CommentsByAuthorQueryPaginationTest < ActiveSupport::TestCase
+  setup do
+    @author = Author.create!(name: "Ada")
+    @post = Post.create!(title: "Hi", author: @author)
+    75.times { |i| Comment.create!(post: @post, body: "c#{i}") }
+  end
+
+  test "paginates correctly" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id, page: 1, page_size: 25)
+    results = query.results
+
+    assert_equal 25, results.page_count
+    assert_equal 75, results.count
+    assert query.paged?
+  end
+
+  test "next_page_query returns next page" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id, page: 1, page_size: 25)
+    assert_equal 2, query.next_page_query.page
+  end
+
+  test "previous_page_query returns previous page" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id, page: 3, page_size: 25)
+    assert_equal 2, query.previous_page_query.page
+  end
+
+  test "unpaginated returns everything" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id, page: nil)
+    results = query.results
+
+    assert_equal 75, results.count
+    assert_equal 75, results.page_count
+    refute query.paged?
+  end
+end
+```

data/claude-skill/references/QUERY_TYPES.md

@@ -0,0 +1,297 @@
+# Query Types Reference
+
+> **Targets Quo `~> 2.0`.**
+
+Quo provides two primary query types:
+
+- **`Quo::RelationBackedQuery`** — wraps an `ActiveRecord::Relation`
+- **`Quo::CollectionBackedQuery`** — wraps any `Enumerable`
+
+Both share the same outer surface: typed properties via `prop`,
+pagination, composition with `+`, transformers, and a `Quo::Results`
+return value from `#results`.
+
+## RelationBackedQuery
+
+### When to use
+
+For database queries — anything you'd write in ActiveRecord. This is the
+common case.
+
+### Structure
+
+Subclass and implement `#query`. The method must return an
+`ActiveRecord::Relation` (not a materialised array).
+
+```ruby
+class CommentsByAuthorQuery < Quo::RelationBackedQuery
+  prop :author_id, Integer
+  prop :since, _Nilable(Time)
+  prop :limit, Integer, default: -> { 50 }
+
+  def query
+    scope = Comment
+      .joins(:post)
+      .where(posts: {author_id: author_id})
+      .order(created_at: :desc)
+    scope = scope.where("comments.created_at > ?", since) if since
+    scope.limit(limit)
+  end
+end
+
+query = CommentsByAuthorQuery.new(author_id: 1, since: 1.day.ago, page: 1, page_size: 25)
+results = query.results
+results.each { |comment| puts comment.body }
+```
+
+### `#query` must return a Relation
+
+```ruby
+# Right
+def query
+  Comment.where(read: false).order(:created_at)
+end
+
+# Wrong — array, not relation
+def query
+  Comment.where(read: false).to_a
+end
+```
+
+`#query` is allowed to return another `Quo::Query` instance — Quo will
+unwrap it. That makes it natural to compose inside a query class:
+
+```ruby
+class PopularRecentCommentsQuery < Quo::RelationBackedQuery
+  prop :since, Time, default: -> { 1.day.ago }
+
+  def query
+    UnreadCommentsQuery.new + RecentCommentsQuery.new(since: since)
+  end
+end
+```
+
+### Lazy evaluation
+
+Construction never hits the database. The query runs when you ask for
+results.
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1)
+# No SQL yet.
+
+query.results.each { |c| ... }
+# SQL runs here.
+```
+
+### Utility methods
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1)
+
+query.to_sql              # => SQL string
+query.unwrap_unpaginated  # => ActiveRecord::Relation (no LIMIT/OFFSET)
+query.unwrap              # => ActiveRecord::Relation (with paging applied if any)
+
+query.relation?           # => true
+query.collection?         # => false
+```
+
+## CollectionBackedQuery
+
+### When to use
+
+For in-memory enumerables — cached data, API responses, pre-loaded
+arrays. Avoid for large datasets you'd be loading from the database
+anyway; use `RelationBackedQuery` and let the database do the work.
+
+### Structure
+
+Subclass and implement `#collection`. The method must return an
+`Enumerable` (typically an Array).
+
+```ruby
+class TopRatedCommentsQuery < Quo::CollectionBackedQuery
+  prop :comments, _Array(Comment)
+  prop :max_spam_score, Float, default: -> { 0.5 }
+
+  def collection
+    comments
+      .select { |c| c.spam_score && c.spam_score < max_spam_score }
+      .sort_by { |c| c.spam_score || 0 }
+  end
+end
+
+query = TopRatedCommentsQuery.new(comments: Comment.all.to_a, max_spam_score: 0.3)
+query.results.each { |c| puts c.body }
+```
+
+### `#collection` must return Enumerable
+
+```ruby
+# Right — Array
+def collection
+  items.select { |i| i.active? }
+end
+
+# Right — Set
+def collection
+  Set.new(items)
+end
+
+# Wrong — single item
+def collection
+  items.first
+end
+```
+
+### Pagination happens in memory
+
+```ruby
+query = TopRatedCommentsQuery.new(comments: huge_array, page: 2, page_size: 10)
+query.results
+# All `huge_array` lives in memory; pagination slices it.
+```
+
+For large data sets, prefer a `RelationBackedQuery` so the database can
+limit before returning rows.
+
+### Utility methods
+
+```ruby
+query = TopRatedCommentsQuery.new(comments: comments)
+
+query.unwrap_unpaginated  # => Array (full)
+query.unwrap              # => Array (paginated slice if paged?)
+
+query.relation?           # => false
+query.collection?         # => true
+```
+
+## Converting between types
+
+`#to_collection` materialises a `RelationBackedQuery` into a
+`CollectionBackedQuery`. Useful for caching the materialised array.
+
+```ruby
+relation_query = CommentsByAuthorQuery.new(author_id: 1)
+collection_query = relation_query.to_collection
+
+collection_query.relation?    # => false
+collection_query.collection?  # => true
+```
+
+A common cache pattern:
+
+```ruby
+class CachedRecentCommentsQuery < Quo::CollectionBackedQuery
+  prop :author_id, Integer
+  prop :ttl, ActiveSupport::Duration, default: -> { 5.minutes }
+
+  def collection
+    Rails.cache.fetch("comments:author:#{author_id}", expires_in: ttl) do
+      CommentsByAuthorQuery.new(author_id: author_id).results.to_a
+    end
+  end
+end
+```
+
+## Property types reference
+
+Quo uses [Literal](https://github.com/joeldrapper/literal) for type
+validation. Literal's helper methods on Quo classes are prefixed with
+underscore (e.g. `_Nilable`, `_Array`, `_Union`, `_Boolean`).
+
+### Primitives
+
+```ruby
+prop :name, String
+prop :count, Integer
+prop :price, Float
+prop :enabled, _Boolean    # NB: _Boolean, not Boolean
+prop :data, Hash
+prop :items, Array
+```
+
+### Custom classes
+
+```ruby
+prop :author, Author
+prop :post, Post
+prop :comment, Comment
+```
+
+### Arrays
+
+```ruby
+prop :tags, _Array(String)
+prop :ids, _Array(Integer)
+prop :authors, _Array(Author)
+```
+
+### Nilable
+
+```ruby
+prop :since, _Nilable(Time)
+prop :status, _Nilable(String)
+```
+
+### Unions
+
+```ruby
+prop :id_or_slug, _Union(String, Integer)
+```
+
+### Defaults
+
+```ruby
+# Use a lambda for any non-frozen default — avoids shared mutable state.
+prop :tags, _Array(String), default: -> { [] }
+prop :since, Time, default: -> { 1.day.ago }
+prop :page_size, Integer, default: -> { 20 }
+
+# Frozen literals are also OK:
+prop :status, String, default: "pending".freeze
+```
+
+### Boolean caveat
+
+Use `_Boolean` (Literal helper), not bare `Boolean`:
+
+```ruby
+prop :enabled, _Boolean             # right
+prop :enabled, Boolean              # wrong — there's no top-level Boolean class
+```
+
+## Property validation
+
+Properties validate at construction. Wrong types and missing required
+values raise `Literal::TypeError`.
+
+```ruby
+class StrictQuery < Quo::RelationBackedQuery
+  prop :author_id, Integer
+  prop :limit, Integer, default: -> { 50 }
+end
+
+StrictQuery.new(author_id: 1)              # OK
+StrictQuery.new(author_id: "1")            # raises — wrong type
+StrictQuery.new(limit: 10)                 # raises — missing :author_id
+```
+
+## Method requirements summary
+
+| Type | Implement | Returns |
+|---|---|---|
+| `Quo::RelationBackedQuery` | `#query` | `ActiveRecord::Relation` (or another `Quo::Query`) |
+| `Quo::CollectionBackedQuery` | `#collection` | `Enumerable` |
+
+## Choosing between types
+
+| Use case | Pick |
+|---|---|
+| Database query that pages and filters | `RelationBackedQuery` |
+| Need raw SQL access (`#to_sql`) | `RelationBackedQuery` |
+| Cached array, API response, in-memory filter | `CollectionBackedQuery` |
+| Caching the result of a relation query | `RelationBackedQuery` → `to_collection` |
+| Composing with `.where`/`.joins`/`.order` | `RelationBackedQuery` |