quo 1.0.0.beta2 → 2.0.0

data/claude-skill/references/TRANSFORMERS.md

@@ -0,0 +1,282 @@
+# Result Transformers Reference
+
+> **Targets Quo `~> 2.0`.**
+
+Transformers apply a function to each row as it comes out of a query.
+Common uses: wrapping rows in presenter/serializer objects, converting
+to DTOs, or applying view-specific logic without modifying the
+underlying query.
+
+## Attaching a transformer
+
+`#transform` takes a block and returns a new query that wraps each row
+through the block.
+
+```ruby
+class CommentsByAuthorQuery < Quo::RelationBackedQuery
+  prop :author_id, Integer
+  def query
+    Comment.joins(:post).where(posts: {author_id: author_id})
+  end
+end
+
+query = CommentsByAuthorQuery.new(author_id: 1)
+  .transform { |comment| CommentPresenter.new(comment) }
+
+query.results.each do |presenter|
+  puts presenter.formatted_body
+end
+```
+
+### Inspecting
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1)
+query.transform?  # => false
+
+with_transform = query.transform { |c| CommentPresenter.new(c) }
+with_transform.transform?  # => true
+```
+
+## Patterns
+
+### Presenter wrapping
+
+A typical view-layer transformer:
+
+```ruby
+class CommentPresenter
+  def initialize(comment, viewer: nil)
+    @comment = comment
+    @viewer = viewer
+  end
+
+  def formatted_body
+    @comment.body.gsub(/\b(http\S+)/, '<a href="\1">\1</a>').html_safe
+  end
+
+  def status_badge
+    @comment.read? ? "✓ read" : "● unread"
+  end
+end
+
+query = CommentsByAuthorQuery.new(author_id: current_user.id)
+  .transform { |c| CommentPresenter.new(c, viewer: current_user) }
+
+query.results.each do |presenter|
+  puts "#{presenter.status_badge} #{presenter.formatted_body}"
+end
+```
+
+### Serialization for API responses
+
+```ruby
+class CommentSerializer
+  def initialize(comment, include_post: false)
+    @comment = comment
+    @include_post = include_post
+  end
+
+  def as_json
+    base = {id: @comment.id, body: @comment.body, read: @comment.read}
+    base[:post] = {id: @comment.post.id, title: @comment.post.title} if @include_post
+    base
+  end
+end
+
+query = CommentsByAuthorQuery.new(author_id: params[:author_id])
+  .transform { |c| CommentSerializer.new(c, include_post: true) }
+
+render json: {data: query.results.map(&:as_json)}
+```
+
+### DTO conversion
+
+```ruby
+CommentDTO = Data.define(:id, :body, :read_at)
+
+query = CommentsByAuthorQuery.new(author_id: 1)
+  .transform { |c| CommentDTO.new(id: c.id, body: c.body, read_at: c.updated_at) }
+
+query.results.to_a  # => [CommentDTO, CommentDTO, ...]
+```
+
+### Capturing context in the transformer block
+
+The block closes over its surrounding scope, so context flows in
+naturally:
+
+```ruby
+viewer = current_user
+locale = I18n.locale
+
+query = CommentsByAuthorQuery.new(author_id: 1)
+  .transform { |c| CommentPresenter.new(c, viewer: viewer, locale: locale) }
+```
+
+This works because the block is captured at `transform` time and applied
+later when results are read.
+
+## Transformers + pagination
+
+Transformers operate on the materialised page; counts are unaffected.
+
+```ruby
+query = CommentsByAuthorQuery.new(author_id: 1, page: 1, page_size: 25)
+  .transform { |c| CommentPresenter.new(c) }
+
+results = query.results
+results.first        # => CommentPresenter
+results.count        # => total comments (unwrapped count)
+results.page_count   # => 25 presenters in current page
+```
+
+Page navigation preserves the transformer:
+
+```ruby
+next_query = query.next_page_query
+next_query.transform?  # => true
+next_query.results.first  # => CommentPresenter
+```
+
+## Transformers + composition
+
+### Compose, then transform
+
+The natural order: build the query first, transform last.
+
+```ruby
+base   = AllCommentsQuery.new
+filter = UnreadCommentsQuery.new
+(base + filter).transform { |c| CommentPresenter.new(c) }.results
+```
+
+### Transform, then compose
+
+The transformer carries through composition.
+
+```ruby
+transformed = AllCommentsQuery.new.transform { |c| CommentPresenter.new(c) }
+filtered    = transformed + UnreadCommentsQuery.new
+filtered.results.first  # => CommentPresenter
+```
+
+### Multiple `transform` calls
+
+The most recent one wins. Quo doesn't pipeline transformers — each
+`#transform` replaces any prior one.
+
+```ruby
+query = AllCommentsQuery.new
+  .transform { |c| CommentPresenter.new(c) }
+  .transform { |c| CommentSerializer.new(c) }
+
+query.results.first  # => CommentSerializer (the last transformer)
+```
+
+If you want a pipeline, compose the work inside a single block:
+
+```ruby
+query = AllCommentsQuery.new.transform { |c|
+  CommentSerializer.new(CommentPresenter.new(c))
+}
+```
+
+## Method delegation
+
+`Quo::Results` delegates `Enumerable` methods to the underlying
+collection, applying the transformer on each yielded row.
+
+```ruby
+results = CommentsByAuthorQuery.new(author_id: 1)
+  .transform { |c| CommentPresenter.new(c) }
+  .results
+
+results.map(&:formatted_body)
+results.select { |p| p.status_badge.include?("unread") }
+results.group_by(&:status_badge)
+results.first
+```
+
+These all return transformed rows. `#count`, `#page_count`, `#empty?`,
+and `#exists?` work on the underlying data — they aren't transformed.
+
+## Performance considerations
+
+### Lazy
+
+Transformers run when results are read, not when `#transform` is called.
+
+```ruby
+query = AllCommentsQuery.new.transform { |c|
+  puts "transforming #{c.id}"
+  CommentPresenter.new(c)
+}
+# Nothing prints yet.
+
+query.results.each { |p| ... }
+# Now "transforming N" prints for each row.
+```
+
+### Keep transformers cheap
+
+A transformer that does heavy work per row will dominate query time.
+Prefer a lightweight wrapper that defers expensive work to method
+calls.
+
+```ruby
+# Heavy — runs for every row, even if you only need .id
+.transform { |c| HeavyPresenter.new(c).tap(&:precompute_everything!) }
+
+# Light — defers work until needed
+.transform { |c| LazyPresenter.new(c) }
+```
+
+### Memoize inside the wrapper
+
+If a presenter computes something expensive per call, memoize:
+
+```ruby
+class CommentPresenter
+  def initialize(comment); @comment = comment; end
+
+  def author_display
+    @author_display ||= @comment.post.author.name.titleize
+  end
+end
+```
+
+## Testing transformers
+
+```ruby
+class CommentsByAuthorQueryTransformerTest < ActiveSupport::TestCase
+  setup do
+    @author = Author.create!(name: "Ada")
+    @post = Post.create!(title: "Hi", author: @author)
+    Comment.create!(post: @post, body: "first")
+  end
+
+  test "wraps each row in a presenter" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id)
+      .transform { |c| CommentPresenter.new(c) }
+
+    assert_instance_of CommentPresenter, query.results.first
+  end
+
+  test "transformer applies to all enumerable methods" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id)
+      .transform { |c| CommentPresenter.new(c) }
+
+    bodies = query.results.map(&:formatted_body)
+    assert_equal 1, bodies.size
+  end
+
+  test "#transform? reports true after transform" do
+    query = CommentsByAuthorQuery.new(author_id: @author.id)
+    refute query.transform?
+
+    transformed = query.transform { |c| CommentPresenter.new(c) }
+    assert transformed.transform?
+  end
+end
+```

data/context/01-core-architecture.md

@@ -0,0 +1,247 @@
+# Quo Core Architecture
+
+This document provides a technical deep-dive into Quo's architecture, explaining how the gem is structured and how its components work together to provide composable query objects.
+
+## Foundation: Literal Framework
+
+Quo is built on top of the [Literal](https://github.com/joeldrapper/literal) gem, leveraging its type-safe property system. Every query object inherits from `Literal::Struct`, providing:
+
+- Type-checked properties with defaults
+- Immutable struct-like behavior
+- Built-in validation and coercion
+
+## Core Class Hierarchy
+
+```
+Literal::Struct
+    └── Quo::Query (abstract base)
+        ├── Quo::RelationBackedQuery
+        │   └── Application-specific query classes
+        └── Quo::CollectionBackedQuery
+            └── Application-specific query classes
+```
+
+### Quo::Query
+
+The abstract base class that defines the core interface for all query objects:
+
+```ruby
+class Query < Literal::Struct
+  include Literal::Types
+  
+  # Core properties for pagination
+  prop :page, _Nilable(Integer), &COERCE_TO_INT
+  prop :page_size, _Nilable(Integer), default: -> { Quo.default_page_size || 20 }, &COERCE_TO_INT
+  
+  # Abstract methods that subclasses must implement
+  def query
+    raise NotImplementedError
+  end
+  
+  # Key instance methods
+  def copy(**overrides)
+  def merge(right, joins: nil)  # aliased as +
+  def transform(&block)
+  def results
+end
+```
+
+Key responsibilities:
+- Defines pagination interface (page, page_size)
+- Provides composition capabilities via `merge`/`+`
+- Supports result transformation via `transform`
+- Enforces contract through abstract methods
+
+### Quo::RelationBackedQuery
+
+Specializes Query for ActiveRecord relations:
+
+```ruby
+class RelationBackedQuery < Query
+  prop :_specification, _Nilable(Quo::RelationBackedQuerySpecification)
+  
+  def query
+    # Returns ActiveRecord::Relation
+  end
+  
+  def results
+    Quo::RelationResults.new(self, transformer: transformer)
+  end
+  
+  # Fluent API via method_missing
+  def method_missing(method_name, *args, **kwargs, &block)
+    # Delegates to RelationBackedQuerySpecification
+  end
+end
+```
+
+Key features:
+- Wraps ActiveRecord relations
+- Uses `RelationBackedQuerySpecification` to store query options
+- Provides fluent API matching ActiveRecord's interface
+- Returns `RelationResults` for execution
+
+### Quo::CollectionBackedQuery
+
+Specializes Query for enumerable collections:
+
+```ruby
+class CollectionBackedQuery < Query
+  prop :total_count, _Nilable(Integer), reader: false
+  
+  def collection
+    # Returns Enumerable
+  end
+  
+  def query
+    collection  # Default implementation
+  end
+  
+  def results
+    Quo::CollectionResults.new(self, transformer: transformer, total_count: @total_count)
+  end
+end
+```
+
+Key features:
+- Wraps any Enumerable collection
+- Supports explicit total_count for pagination
+- Can include `Quo::Preloadable` for association preloading
+- Returns `CollectionResults` for execution
+
+## Query Specification Pattern
+
+The `RelationBackedQuerySpecification` class implements the Specification pattern to encapsulate query-building logic:
+
+```ruby
+class RelationBackedQuerySpecification
+  attr_reader :options
+  
+  def initialize(options = {})
+    @options = options
+  end
+  
+  def merge(new_options)
+    self.class.new(options.merge(new_options))
+  end
+  
+  def apply_to(relation)
+    # Applies all stored options to the relation
+    rel = relation
+    rel = rel.where(options[:where]) if options[:where]
+    rel = rel.order(options[:order]) if options[:order]
+    # ... etc
+    rel
+  end
+  
+  # Fluent methods that return new specifications
+  def where(conditions)
+    merge(where: conditions)
+  end
+  
+  def order(order_clause)
+    merge(order: order_clause)
+  end
+  # ... etc
+end
+```
+
+This separation allows:
+- Immutable query building
+- Deferred execution
+- Easy composition of query options
+- Testability without database access
+
+## Results Architecture
+
+The Results classes provide a consistent interface for working with query results:
+
+```
+Quo::Results (abstract)
+    ├── Quo::RelationResults
+    └── Quo::CollectionResults
+```
+
+### Results Base Class
+
+```ruby
+class Results
+  def initialize(query, transformer: nil, **options)
+    @query = query
+    @transformer = transformer
+    @configured_query = query.unwrap
+  end
+  
+  # Core counting methods
+  def count        # Total count ignoring pagination
+  def page_count   # Count on current page
+  def exists?
+  def empty?
+  
+  # Enumerable methods with transformation
+  def each(&block)
+  def map(&block)
+  def first
+  def last
+  
+  # Delegation with transformation support
+  def method_missing(method, *args, **kwargs, &block)
+    # Applies transformer when delegating to underlying collection
+  end
+end
+```
+
+### RelationResults
+
+Specializes Results for ActiveRecord relations:
+- Delegates to the underlying ActiveRecord::Relation
+- Provides ActiveRecord-specific methods (find, find_by, where)
+- Handles count efficiently via SQL
+- Supports chaining (returns new Results objects)
+
+### CollectionResults
+
+Specializes Results for enumerable collections:
+- Delegates to the underlying Enumerable
+- Handles pagination via array slicing
+- Supports explicit total_count
+- Works with any Ruby collection
+
+## Configuration System
+
+Quo provides module-level configuration via `mattr_accessor`:
+
+```ruby
+module Quo
+  mattr_accessor :relation_backed_query_base_class, default: "Quo::RelationBackedQuery"
+  mattr_accessor :collection_backed_query_base_class, default: "Quo::CollectionBackedQuery"
+  mattr_accessor :max_page_size, default: 200
+  mattr_accessor :default_page_size, default: 20
+end
+```
+
+This allows applications to:
+- Define custom base classes with shared behavior
+- Set application-wide pagination defaults
+- Enforce maximum page sizes for security
+
+## Autoloading Strategy
+
+Quo uses Rails' autoloading for lazy loading of components
+
+## Engine Integration
+
+For Rails applications, Quo provides an Engine:
+
+```ruby
+module Quo
+  class Engine < ::Rails::Engine
+    isolate_namespace Quo
+  end
+end
+```
+
+This enables:
+- Proper Rails integration
+- Rake task loading
+- Future extensibility for Rails-specific features