appquery 0.8.0.rc3 → 0.9.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dacb58820ea6f11ec37fa1e73f7aeb9eec507d92b4e302cd8134f2c768abeba
-  data.tar.gz: d371f97ca509a6c9dde67f2aec9edc67a7690b00081a5d596003608ae4958748
+  metadata.gz: de70b2690d884b36f8d29f8a2e76c7edefba25ca9f9fcc9785e70389c35f3aa0
+  data.tar.gz: 3c81f2fb6dd4679a86a99df91485df234ccfd449c6de0cb5317c6ca8f8e5751b
 SHA512:
-  metadata.gz: bd8b8d0c01fdf4e9434cfe85218d6b772d839b263ae7c91f667fa2eb7aaedba48825bcace882028ed80b6cda8ff241c0fbae4764ca1cc067d3f320d95c5e81b8
-  data.tar.gz: 11ee7b651b2fa20e2f40935e674d190681159a2fecf716741ca6392fabde3b7ed2a3e1e1b29b86344215db58b80f9765ba98ea81ec93c3e31022e2859b96f7bc
+  metadata.gz: e2a0d5f7c2a320426cf292e4f5afdcbe8ca9d499eca85cb8139d7c44d0dc2498443fc70853bc274c6c912e9753ee7a176ad552d9e4f6fe0d0f1adc4d2ad00bba
+  data.tar.gz: 7a038760466d79804b06e64ba18d6161a2070fe728b2ec529a1dbd62c04729866b8af6def94f9dafcec7965d060710c46bbe3e874b6cb67df2e32413a4a62cc1

data/.worktree.yml.example

@@ -0,0 +1,40 @@
+# Worktree configuration for bonchi.
+# See https://github.com/eval/bonchi
+
+# Minimum bonchi version required.
+# min_version: 0.6.0
+
+# Files to copy from the main worktree before setup.
+copy:
+  - mise.toml
+  - mise.local.toml
+  - _irbrc
+  - bin/worktree-dev
+
+# Files to symlink from the main worktree (useful for large directories).
+# link:
+#   - node_modules
+
+# Env var names to allocate unique ports for (from global pool).
+# ports:
+#   - PORT
+
+# Regex replacements in copied files. Env vars ($VAR) are expanded.
+# Short form:
+# replace:
+#   .env.local:
+#     - "^PORT=.*": "PORT=$PORT"
+# Full form (with optional missing: warn, default: halt):
+# replace:
+#   .env.local:
+#     - match: "^PORT=.*"
+#       with: "PORT=$PORT"
+#       missing: warn
+
+# Commands to run before the setup command (port env vars are available).
+pre_setup:
+  - mise trust
+  - bin/setup
+
+# The setup command to run (default: bin/setup).
+setup: bin/worktree-dev

data/.yardopts

@@ -5,7 +5,7 @@
 --no-private
 --output-dir doc
 --exclude tmp/
---exclude spec/
+--exclude ^spec/
 --exclude examples/
 --exclude gemfiles/
 lib/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,96 @@
 ## [Unreleased]
 
+### 💥 Breaking Changes
+
+- ⚠️ **`AppQuery::Mappable` extension API changed.**  
+  Row-level middleware now appends a transformer to the underlying `Q`'s `row_builder` pipeline via an overridden `#query`, instead of overriding `select_all`/`select_one`. The previous pattern of overriding those two methods will silently do nothing on row-returning paths it didn't cover (`entries`, `first`, `last`, `take`, `with_select(non_nil).first`, …). Any custom middleware that overrode `select_all`/`select_one` should migrate to:
+  ```ruby
+  def query
+    @query ||= super.tap { |q| q.row_builder << method(:build_row) }
+  end
+  ```
+- ⚠️ **`Q#column` now raises `ArgumentError` for unknown columns.**  
+  Previously, on SQLite, `q.column(:typo)` silently returned a row per record containing the *string* `"typo"` (the SQLite "double-quoted strings are identifiers OR string literals" quirk masked the missing column). It now pre-validates against `column_names` and raises with the available column list — consistently across SQLite and PostgreSQL.
+
+### ✨ Features
+
+- 🧩 **`AppQuery::RowBuilder`** — composable pipeline of row transformers exposed as `Q#row_builder`. Append with `q.row_builder << callable`; transformers run in registration order. Multiple row-level middlewares stack cleanly in `include` order. The pipeline is applied everywhere `Q` exposes rows (`entries`, `first`, `last`, `take`, `take_last`, `with_select(...).first`, …) and is independently copied across `deep_dup` so chained queries don't mutate their parent.
+- 🎯 **`Mappable` is now one method.** Maps everywhere — including `entries`, `last`, `take(n)`, `with_select("…").first` paths that previously slipped through. `raw` bypass still works.
+- 🐛 **`Q#column` typo protection** — see breaking-change note above.
+- 🐛 **Comments inside CTE selects** no longer break tokenization; the whole `(SELECT … -- foo … )` is preserved as a single `CTE_SELECT` token.
+- Publishing gem requires MFA
+
+## 0.8.0
+
+**Releasedate**: 14-1-2026  
+**Rubygems**: https://rubygems.org/gems/appquery/versions/0.8.0  
+
+### 💥 Breaking Changes
+
+- ⚠️ **RSpec helpers refactored**  
+  Query under test is expected to be a class, `select_*` are no longer separate helpers:
+  ```ruby
+    expect(described_query.first).to \
+      include("id" => be_a(Integer), ...)
+    expect(described_query.entries).to include(a_hash_including("item_code" => "123456"))
+  ```
+
+### ✨ Features
+
+- 📤 **`copy_to`** — efficient PostgreSQL COPY export to CSV/text/binary
+  ```ruby
+  # Return as string
+  csv = AppQuery[:users].copy_to
+
+  # Write to file
+  AppQuery[:users].copy_to(dest: "export.csv")
+
+  # Stream to IO (e.g., Rails response)
+  query.copy_to(dest: response.stream)
+  ```
+
+- 🎯 **`cte(:name)`** — focus a query on a specific CTE for testing or inspection
+  ```ruby
+  query = AppQuery("WITH active AS (...), admins AS (...) SELECT ...")
+  query.cte(:active).entries   # select from the active CTE
+  query.cte(:admins).count     # count rows in admins CTE
+  ```
+
+- 🗃️ **`AppQuery.table(:name)`** — quick query from a table
+  ```ruby
+  AppQuery.table(:products).count
+  AppQuery.table(:users).take(5)
+  ```
+
+- 🔢 **`take(n)` / `take_last(n)`** — fetch first or last n rows
+  ```ruby
+  query.take(5)       # first 5 rows
+  query.take_last(5)  # last 5 rows
+  ```
+
+- ⏮️ **`last`** — fetch the last row (counterpart to `first`)
+  ```ruby
+  query.last  # => {"id" => 42, "name" => "Zoe"}
+  ```
+
+- 📋 **`column_names`** — get column names without fetching rows
+  ```ruby
+  query.column_names  # => ["id", "name", "email"]
+  ```
+
+- 🦄 **`unique:` keyword for `Q#column`** — return distinct values
+  ```ruby
+  query.column(:status, unique: true)  # => ["active", "pending"]
+  ```
+
+- 🏗️ **Overhauled generators** — moved to `AppQuery::` namespace
+  ```bash
+  rails g app_query:example # annotated example query
+  rails g app_query:query Products
+  rails g query Products  # hidden alias
+  rails g query --help    # details
+  ```
+
 ## 0.7.0
 
 **Releasedate**: 8-1-2026  

data/Procfile.yard

@@ -0,0 +1,4 @@
+# YARD development server with auto-rebuild
+# Usage: bin/yard-dev
+web: ruby -run -ehttpd doc -p8809
+watch: find lib README.md -name '*.rb' -o -name '*.md' | entr -s 'bundle exec yard doc'

data/README.md

@@ -87,6 +87,8 @@ That introduces new problems: the not-so-intuitive `select_all`/`select_one`/`se
 - Easy inspection and testing—especially for CTE-based queries
 - Clean parameterization via named binds and ERB
 
+Read [this blog post](https://www.gertgoet.com/appquery.html) for additional context and an overview.
+
 ## Installation
 
 ```bash
@@ -117,6 +119,31 @@ AppQuery[:weekly_sales].select_all(binds: {week: 1, year: 2025})
 #=> [{"week" => 1, "category" => "Electronics", "revenue" => 12500}, ...]
 ```
 
+Even better:
+
+Use the query-class and define binds, vars, casts, middleware etc.
+
+```ruby
+class WeeklySalesQuery < ApplicationQuery
+  include AppQuery::Paginatable
+  per_page 25
+
+  bind :week
+  bind :year, default: 2026
+
+  cast metadata: :json
+
+  # add factory methods for specific purposes
+  def self.build(page: 1, week:, year: 2026)
+    new(week:, year:).paginate(page:)
+  end
+end
+
+WeeklySalesQuery.build(week: 1).entries
+```
+
+Read more about the query-class in [the API docs](https://eval.github.io/appquery/AppQuery/BaseQuery.html).
+
 ## Usage
 
 > [!NOTE]
@@ -243,25 +270,135 @@ File.open("users.csv.gz", "wb") do |f|
 end
 ```
 
+See [the method docs](https://eval.github.io/appquery/AppQuery/Q.html#copy_to-instance_method) for more (Rails) examples.
+
 ### RSpec Integration
 
 Generated spec files include helpers:
 
 ```ruby
 # spec/queries/reports/weekly_query_spec.rb
-RSpec.describe "AppQuery reports/weekly", type: :query, default_binds: [] do
+RSpec.describe Reports::WeeklyQuery, type: :query, binds: {since: 3.weeks.ago} do
   describe "CTE articles" do
     specify do
-      expect(described_query.select_all("SELECT * FROM :cte")).to \
+      expect(described_query.entries).to \
         include(a_hash_including("article_id" => 1))
-
-      # Short version: query, cte and select are implied from descriptions
-      expect(select_all).to include(a_hash_including("article_id" => 1))
     end
   end
 end
 ```
 
+See [the API docs](https://eval.github.io/appquery/AppQuery/RSpec/Helpers.html) for more RSpec examples.
+
+### Writing a Middleware
+
+A `BaseQuery` middleware is a `Module` you `include` into a query class. There are three layers to extend at, depending on *where* you want to act. The three compose cleanly on the same query class.
+
+| You want to… | Layer | How |
+|---|---|---|
+| change/decorate each row | **row-level** | append to `q.row_builder` |
+| filter, wrap, cap, paginate, cache the collection | **result-level** | override `#entries` (or `#first`, `#last`, …) |
+| change the SQL/binds before it runs | **query-level** | override `#query`, return a different `Q` |
+
+#### Row-level (the `row_builder` pipeline)
+
+`Q#row_builder` is a composable pipeline of callables that each receive a row Hash and return whatever should replace it — a Hash, a `Data`, a Struct, your own model.
+
+```ruby
+module Stamping
+  extend ActiveSupport::Concern
+
+  def query
+    @query ||= super.tap { |q| q.row_builder << ->(row) { row.merge("stamped_at" => Time.now) } }
+  end
+end
+
+class ArticlesQuery < ApplicationQuery
+  include Stamping
+end
+
+ArticlesQuery.new.first         # => {"id" => 1, ..., "stamped_at" => 2026-...}
+ArticlesQuery.new.entries.first # same — every row-returning path flows through row_builder
+```
+
+The pipeline propagates through `with_select(non_nil)`, `add_binds`, `with_binds`, `with_cast`, `with_sql`, and CTE focusing (`#cte`), so chained calls keep the same mapping. Each child gets an independent copy — mutating it doesn't affect the parent.
+
+**Stacking row-level middlewares.** Transformers run in **`include` order** — earliest `include` first, latest `include` last. With
+
+```ruby
+class MyQuery < ApplicationQuery
+  include Stamping            # runs first — its row goes into…
+  include AppQuery::Mappable  # …which sees the stamped hash and builds an Item
+end
+```
+
+`Stamping`'s lambda runs first, then `Mappable.build_row` consumes the already-stamped hash. ⚠️ Once a transformer returns a non-Hash (e.g. a `Data`), downstream transformers see that object — so a hash-merging transformer placed *after* `Mappable` would fail. Order the chain accordingly.
+
+**Doesn't fit row_builder:** filtering ("drop rows the viewer can't see") and collapsing rows. Both act on the collection, not a single row — use the result-level layer instead.
+
+#### Result-level (wrap a row-returning method)
+
+When you want to act on the whole collection — wrap, cap, cache, filter, paginate — override the row-returning method and call `super`. `super` returns rows that have *already* been through `row_builder`, so this composes with row-level middleware without thinking.
+
+`Paginatable` is the canonical example (wraps `#entries` in a `PaginatedResult`). Some others:
+
+```ruby
+module Caching
+  # memoise the whole result on the instance
+  def entries = @_entries ||= super
+  def first   = @_first   ||= super
+end
+
+module ScopedToTenant
+  def entries = super.select { |r| r["tenant_id"] == Current.tenant.id }
+end
+
+module Capped
+  CapResult = Data.define(:records, :hit_cap?) do
+    include Enumerable
+    def each(&b) = records.each(&b)
+  end
+
+  def entries
+    rows = super
+    CapResult.new(records: rows.first(self.class.cap), hit_cap?: rows.size > self.class.cap)
+  end
+end
+```
+
+#### Query-level (rewrite SQL/binds before execution)
+
+When you want to change what the database actually sees — tenant scoping, soft-delete filtering, default ordering — override `#query` and return a transformed `Q`. Use `with_select` / `with_binds` / `add_binds` etc.; they propagate the `row_builder` pipeline via `deep_dup`, so row-level middleware keeps working.
+
+```ruby
+module TenantScoped
+  def query
+    @query ||= super.add_binds(tenant_id: Current.tenant.id)
+  end
+end
+
+module HidesDeleted
+  def query
+    @query ||= super.with_select("SELECT * FROM :_ WHERE deleted_at IS NULL")
+  end
+end
+```
+
+#### Putting it together
+
+All three layers can sit on one class:
+
+```ruby
+class ArticlesQuery < ApplicationQuery
+  include HidesDeleted            # query-level: rewrites SQL
+  include Stamping                # row-level:   adds "stamped_at"
+  include AppQuery::Mappable      # row-level:   builds Item (must come after row-mutating middleware)
+  include AppQuery::Paginatable   # result-level: wraps entries
+end
+```
+
+Pipeline at run time, top to bottom: SQL is rewritten to filter `deleted_at IS NULL` → DB returns rows → each row gets `stamped_at` → each row becomes an `Item` → the array of Items is wrapped in a `PaginatedResult`.
+
 ## API Documentation
 
 See the [YARD documentation](https://eval.github.io/appquery/) for the full API reference.
@@ -289,9 +426,13 @@ bin/run rails_head console
 
 # Run tests
 rake spec
+
+# YARD with reload (requires entr and overmind/foreman)
+bin/yard-dev
 ```
 
-Using [mise](https://mise.jdx.dev/) for env-vars is recommended.
+Using [mise](https://mise.jdx.dev/) for env-vars is recommended.  
+Using [bonchi](https://rubygems.org/gems/bonchi) allows for agentic working via git worktrees. See `.worktree.yml.example` for a config.
 
 ### Releasing
 

data/lib/app_query/base_query.rb

@@ -154,7 +154,8 @@ module AppQuery
       end
     end
 
-    delegate :cte, :entries, :with_select, :select_all, :select_one, :count, :to_s, :column, :first, :ids, :copy_to, to: :query
+    delegate :cte, :entries, :with_select, :select_all, :select_one, :count, :to_s,
+      :column, :first, :last, :take, :take_last, :ids, :copy_to, to: :query
 
     def query
       @query ||= base_query

data/lib/app_query/mappable.rb

@@ -66,31 +66,20 @@ module AppQuery
       self
     end
 
-    def select_all
-      map_result(super)
-    end
-
-    def select_one
-      map_one(super)
+    # Append our transform to the underlying Q's RowBuilder pipeline so every
+    # row-returning path (entries, first, last, take, with_select(...).first,
+    # …) sees mapped rows. Stacks with other row-level middlewares in
+    # include-order — earlier `include`s run first.
+    def query
+      @query ||= super.tap { |q| q.row_builder << method(:build_row) }
     end
 
     private
 
-    def map_result(result)
-      return result if @raw
-      return result unless (klass = resolve_map_klass)
-
-      attrs = klass.members
-      result.transform! { |row| klass.new(**row.symbolize_keys.slice(*attrs)) }
-    end
-
-    def map_one(result)
-      return result if @raw
-      return result unless (klass = resolve_map_klass)
-      return result unless result
-
-      attrs = klass.members
-      klass.new(**result.symbolize_keys.slice(*attrs))
+    def build_row(row)
+      return row if @raw
+      return row unless (klass = resolve_map_klass)
+      klass.new(**row.symbolize_keys.slice(*klass.members))
     end
 
     def resolve_map_klass

data/lib/app_query/rspec/helpers.rb

@@ -31,7 +31,17 @@ module AppQuery
     #   RSpec.describe ProductsQuery, type: :query do
     #     describe "as admin", vars: {admin: true} do
     #       it "returns all products" do
-    #         expect(described_query.entries.size).to eq(3)
+    #         expect(described_query.count).to eq(3)
+    #       end
+    #     end
+    #   end
+    #
+    # @example SQL logging for debugging
+    #   RSpec.describe ProductsQuery, type: :query do
+    #     describe "debugging", log: true do
+    #       it "logs SQL to stdout" do
+    #         # SQL queries will be printed to the console
+    #         described_query.entries
     #       end
     #     end
     #   end

data/lib/app_query/rspec.rb

@@ -1,6 +1,26 @@
-require_relative "rspec/helpers"
+module AppQuery
+  # RSpec integration for testing query classes.
+  #
+  # Provides helpers for testing queries, including CTE isolation,
+  # bind/var metadata, and SQL logging.
+  #
+  # @example Setup in spec/rails_helper.rb
+  #   require "app_query/rspec"
+  #
+  # @example Basic query spec
+  #   RSpec.describe ProductsQuery, type: :query do
+  #     it "returns products" do
+  #       expect(described_query.entries).to be_present
+  #     end
+  #   end
+  #
+  # @see AppQuery::RSpec::Helpers
+  module RSpec
+    autoload :Helpers, "app_query/rspec/helpers"
+  end
+end
 
-RSpec.configure do |config|
+::RSpec.configure do |config|
   config.include AppQuery::RSpec::Helpers, type: :query
 
   # Enable SQL logging with `log: true` metadata

data/lib/app_query/tokenizer.rb

@@ -257,9 +257,15 @@ module AppQuery
 
       level = 1
       loop do
-        read_until(/\)|\(|'/)
+        read_until(%r{\)|\(|'|--|/\*})
         if eos?
           err "CTE select ended prematurely"
+        elsif match?("--")
+          read_until(/\n/)
+        elsif match?(%r{/\*})
+          read_until(%r{\*/})
+          err "CTE select ended prematurely" if eos?
+          read_char 2
         elsif match?(/'/)
           # Skip string literal (handle escaped quotes '')
           read_char

data/lib/app_query/version.rb

@@ -3,5 +3,5 @@
 module AppQuery
   # This should just contain the .dev of the upcoming version.
   # When doing the actual release, CI will write the tag here before pushing the gem.
-  VERSION = "0.8.0.rc3"
+  VERSION = "0.9.0.rc1"
 end

data/lib/app_query.rb

@@ -73,6 +73,26 @@ module AppQuery
   end
   reset_configuration!
 
+  # @!group Quoting Helpers
+
+  # Quotes a table name for safe use in SQL.
+  #
+  # @param name [String, Symbol] the table name
+  # @return [String] the quoted table name
+  def self.quote_table(name)
+    ActiveRecord::Base.connection.quote_table_name(name)
+  end
+
+  # Quotes a column name for safe use in SQL.
+  #
+  # @param name [String, Symbol] the column name
+  # @return [String] the quoted column name
+  def self.quote_column(name)
+    ActiveRecord::Base.connection.quote_column_name(name)
+  end
+
+  # @!endgroup
+
   # Loads a query from a file in the configured query path.
   #
   # When no extension is provided, tries `.sql` first, then `.sql.erb`.
@@ -132,23 +152,89 @@ module AppQuery
   #   AppQuery.table(:users, binds: {active: true})
   #     .select_all("SELECT * FROM :_ WHERE active = :active")
   def self.table(name, **opts)
-    quoted = ActiveRecord::Base.connection.quote_table_name(name)
-    Q.new("SELECT * FROM #{quoted}", name: "AppQuery.table(#{name})", **opts)
+    Q.new("SELECT * FROM #{quote_table(name)}", name: "AppQuery.table(#{name})", **opts)
+  end
+
+  # Composable pipeline of row transformers.
+  #
+  # Appended via `<<` and applied in registration order — earliest pushed
+  # runs first, latest pushed runs last (so its return value is what callers
+  # see). An empty pipeline is a no-op.
+  #
+  # @example
+  #   rb = AppQuery::RowBuilder.new
+  #   rb << ->(row) { row.merge("a" => 1) }
+  #   rb << ->(row) { row.merge("b" => 2) }
+  #   rb.call({})  # => {"a" => 1, "b" => 2}
+  class RowBuilder
+    def initialize(procs = [])
+      @procs = procs
+    end
+
+    # Append a transformer. Returns self so `q.row_builder << proc` reads
+    # naturally and `<<=` also works.
+    def <<(callable)
+      @procs << callable
+      self
+    end
+
+    def call(row)
+      @procs.reduce(row) { |acc, p| p.call(acc) }
+    end
+
+    def empty? = @procs.empty?
+
+    def size = @procs.size
+
+    # Independent copy — used by Q#deep_dup so chained queries don't share
+    # the parent's pipeline.
+    def dup
+      self.class.new(@procs.dup)
+    end
   end
 
   class Result < ActiveRecord::Result
-    attr_accessor :cast
+    attr_accessor :cast, :row_builder
     alias_method :cast?, :cast
 
-    def initialize(columns, rows, overrides = nil, cast: false)
+    def initialize(columns, rows, overrides = nil, cast: false, row_builder: nil)
       super(columns, rows, overrides)
       @cast = cast
+      @row_builder = row_builder
       # Rails v6.1: prevent mutate on frozen object on #first
       @hash_rows = [] if columns.empty?
     end
 
+    # AR::Result#first reads @hash_rows directly when not yet memoized,
+    # bypassing our hash_rows override. Force it through.
+    def first
+      hash_rows.first
+    end
+
+    # Returns an array of values for a single column.
+    #
+    # @note If you only need a single column, prefer {Q#column} which selects
+    #   only that column from the database, avoiding fetching all columns.
+    #
+    # @param name [String, Symbol, nil] the column name (nil returns first column)
+    # @param unique [Boolean] whether to return only unique values
+    # @return [Array] the column values
+    # @raise [ArgumentError] if the column doesn't exist
+    #
+    # @example Get values by column name
+    #   result.column(:name)        # => ["Alice", "Bob"]
+    #   result.column("name")       # => ["Alice", "Bob"]
+    #
+    # @example Get first column (no name)
+    #   result.column               # => [1, 2, 3]
+    #
+    # @example Get unique values
+    #   result.column(:status, unique: true)  # => ["active", "pending"]
+    #
+    # @see Q#column
     def column(name = nil, unique: false)
       return [] if empty?
+      name = name&.to_s
       unless name.nil? || includes_column?(name)
         raise ArgumentError, "Unknown column #{name.inspect}. Should be one of #{columns.inspect}."
       end
@@ -163,9 +249,13 @@ module AppQuery
     private
 
     # Override to provide indifferent access (string or symbol keys).
+    # Applies the RowBuilder pipeline lazily so callers see built rows
+    # everywhere (first, last, each, entries, to_a, [] …). An empty/absent
+    # builder is a no-op.
     def hash_rows
       @hash_rows ||= rows.map do |row|
-        columns.zip(row).to_h.with_indifferent_access
+        hash = columns.zip(row).to_h.with_indifferent_access
+        row_builder ? row_builder.call(hash) : hash
       end
     end
 
@@ -202,9 +292,9 @@ module AppQuery
       end
     end
 
-    def self.from_ar_result(r, cast = nil)
+    def self.from_ar_result(r, cast = nil, row_builder: nil)
       if r.empty?
-        r.columns.empty? ? EMPTY : new(r.columns, [], r.column_types)
+        r.columns.empty? ? EMPTY : new(r.columns, [], r.column_types, row_builder:)
       else
         cast &&= case cast
         when Array
@@ -216,7 +306,7 @@ module AppQuery
         end
         if !cast || (cast.empty? && r.column_types.empty?)
           # nothing to cast
-          new(r.columns, r.rows, r.column_types)
+          new(r.columns, r.rows, r.column_types, row_builder:)
         else
           overrides = (r.column_types || {}).merge(cast)
           rows = r.cast_values(overrides)
@@ -226,7 +316,7 @@ module AppQuery
           # > ActiveRecord::Base.connection.select_all("select array[1,2]").cast_values
           # => [[1, 2]]
           rows = rows.zip if r.columns.one?
-          new(r.columns, rows, overrides, cast: true)
+          new(r.columns, rows, overrides, cast: true, row_builder:)
         end
       end
     end
@@ -276,6 +366,15 @@ module AppQuery
     # @return [Boolean, Hash, Array] casting configuration
     attr_reader :sql, :name, :filename, :binds, :cast
 
+    # Middleware extension point. The {RowBuilder} is a composable pipeline:
+    # middlewares append transformers with `q.row_builder << ->(row) { … }`
+    # and the result is applied to every row everywhere Q exposes rows
+    # (entries, first, last, take, take_last, with_select(...).first, …).
+    # Propagated through {#deep_dup} (with an independent copy) so chained
+    # queries inherit the pipeline but don't mutate the parent's.
+    # @return [RowBuilder]
+    attr_accessor :row_builder
+
     # Creates a new query object.
     #
     # @param sql [String] the SQL query string (may contain ERB)
@@ -289,13 +388,14 @@ module AppQuery
     #
     # @example With ERB and binds
     #   Q.new("SELECT * FROM users WHERE id = :id", binds: {id: 1})
-    def initialize(sql, name: nil, filename: nil, binds: {}, cast: true, cte_depth: 0)
+    def initialize(sql, name: nil, filename: nil, binds: {}, cast: true, cte_depth: 0, row_builder: nil)
       @sql = sql
       @name = name
       @filename = filename
       @binds = binds
       @cast = cast
       @cte_depth = cte_depth
+      @row_builder = row_builder || RowBuilder.new
       @binds = binds_with_defaults(sql, binds)
     end
 
@@ -318,8 +418,8 @@ module AppQuery
       end
     end
 
-    def deep_dup(sql: self.sql, name: self.name, filename: self.filename, binds: self.binds.dup, cast: self.cast, cte_depth: self.cte_depth)
-      self.class.new(sql, name:, filename:, binds:, cast:, cte_depth:)
+    def deep_dup(sql: self.sql, name: self.name, filename: self.filename, binds: self.binds.dup, cast: self.cast, cte_depth: self.cte_depth, row_builder: self.row_builder.dup)
+      self.class.new(sql, name:, filename:, binds:, cast:, cte_depth:, row_builder:)
     end
 
     # @!group Rendering
@@ -427,7 +527,7 @@ module AppQuery
           ActiveRecord::Base.sanitize_sql_array([aq.to_s, aq.binds])
         end
         ActiveRecord::Base.connection.select_all(sql, aq.name).then do |result|
-          Result.from_ar_result(result, cast)
+          Result.from_ar_result(result, cast, row_builder: aq.row_builder)
         end
       end
     rescue NameError => e
@@ -451,7 +551,28 @@ module AppQuery
     def select_one(s = nil, binds: {}, cast: self.cast)
       with_select(s).select_all("SELECT * FROM :_ LIMIT 1", binds:, cast:).first
     end
-    alias_method :first, :select_one
+
+    def first(...) = select_one(...)
+
+    # Executes the query and returns the last row.
+    #
+    # Uses OFFSET to skip to the last row without changing the query order.
+    # Note: This requires counting all rows first, so it's less efficient
+    # than {#first} for large result sets.
+    #
+    # @param s [String, nil] optional SELECT to apply before fetching
+    # @param binds [Hash, nil] bind parameters to add
+    # @param cast [Boolean, Hash, Array] type casting configuration
+    # @return [Hash, nil] the last row as a hash, or nil if no results
+    #
+    # @example
+    #   AppQuery("SELECT * FROM users ORDER BY created_at").last
+    #   # => {"id" => 42, "name" => "Zoe"}
+    #
+    # @see #first
+    def last(s = nil, binds: {}, cast: self.cast)
+      take_last(1, s, binds:, cast:).first
+    end
 
     # Executes the query and returns the first n rows.
     #
@@ -471,6 +592,31 @@ module AppQuery
     end
     alias_method :limit, :take
 
+    # Executes the query and returns the last n rows.
+    #
+    # Uses OFFSET to skip to the last n rows without changing the query order.
+    # Note: This requires counting all rows first, so it's less efficient
+    # than {#take} for large result sets.
+    #
+    # @param n [Integer] the number of rows to return
+    # @param s [String, nil] optional SELECT to apply before taking
+    # @param binds [Hash, nil] bind parameters to add
+    # @param cast [Boolean, Hash, Array] type casting configuration
+    # @return [Array<Hash>] the last n rows as an array of hashes
+    #
+    # @example
+    #   AppQuery("SELECT * FROM users ORDER BY created_at").take_last(5)
+    #   # => [{"id" => 38, ...}, {"id" => 39, ...}, ...]
+    #
+    # @see #last
+    def take_last(n, s = nil, binds: {}, cast: self.cast)
+      offset_expr = greatest("(SELECT COUNT(*) FROM :_) - #{n.to_i}", "0")
+      with_select(s).select_all(
+        "SELECT * FROM :_ LIMIT #{n.to_i} OFFSET #{offset_expr}",
+        binds:, cast:
+      ).entries
+    end
+
     # Executes the query and returns the first value of the first row.
     #
     # @param binds [Hash, nil] named bind parameters
@@ -567,9 +713,19 @@ module AppQuery
     # @example Extract unique values
     #   AppQuery("SELECT * FROM products").column(:category, unique: true)
     #   # => ["Electronics", "Clothing", "Home"]
+    #
+    # @raise [ArgumentError] if the column doesn't exist in the (optionally
+    #   selected) query. Pre-validating catches typos consistently across
+    #   databases — e.g. without this, SQLite's "double-quoted strings"
+    #   quirk would silently return rows of the column-name as a string.
     def column(c, s = nil, binds: {}, unique: false)
-      quoted_column = ActiveRecord::Base.connection.quote_column_name(c)
-      with_select(s).select_all("SELECT #{unique ? "DISTINCT" : ""} #{quoted_column} AS column FROM :_", binds:).column("column")
+      available = column_names(s, binds:)
+      unless available.include?(c.to_s)
+        raise ArgumentError, "Unknown column #{c.inspect}. Available: #{available.inspect}."
+      end
+      quoted = quote_column(c)
+      select_expr = unique ? "DISTINCT #{quoted}" : quoted
+      with_select(s).select_all("SELECT #{select_expr} AS column FROM :_", binds:).column("column")
     end
 
     # Returns the column names from the query without fetching any rows.
@@ -581,13 +737,13 @@ module AppQuery
     # @return [Array<String>] the column names
     #
     # @example Get column names
-    #   AppQuery("SELECT id, name, email FROM users").columns
+    #   AppQuery("SELECT id, name, email FROM users").column_names
     #   # => ["id", "name", "email"]
     #
     # @example From a CTE
-    #   AppQuery("WITH t(a, b) AS (VALUES (1, 2)) SELECT * FROM t").columns
+    #   AppQuery("WITH t(a, b) AS (VALUES (1, 2)) SELECT * FROM t").column_names
     #   # => ["a", "b"]
-    def columns(s = nil, binds: {})
+    def column_names(s = nil, binds: {})
       with_select(s).select_all("SELECT * FROM :_ LIMIT 0", binds:).columns
     end
 
@@ -761,6 +917,9 @@ module AppQuery
     #      end
     #    end
     #
+    # @example Rails runner
+    #   bin/rails runner "puts Export::ProductsQuery.new.copy_to" > tmp/products.csv
+    #
     # @raise [AppQuery::Error] if adapter is not PostgreSQL
     def copy_to(s = nil, format: :csv, header: true, delimiter: nil, dest: nil, binds: {})
       raw_conn = ActiveRecord::Base.connection.raw_connection
@@ -991,8 +1150,7 @@ module AppQuery
       unless cte_names.include?(name)
         raise ArgumentError, "Unknown CTE #{name.inspect}. Available: #{cte_names.inspect}"
       end
-      quoted = ActiveRecord::Base.connection.quote_table_name(name)
-      with_select("SELECT * FROM #{quoted}")
+      with_select("SELECT * FROM #{quote_table(name)}")
     end
 
     # Prepends a CTE to the beginning of the WITH clause.
@@ -1124,6 +1282,26 @@ module AppQuery
     def to_s
       @sql
     end
+
+    private
+
+    def quote_table(name)
+      AppQuery.quote_table(name)
+    end
+
+    def quote_column(name)
+      AppQuery.quote_column(name)
+    end
+
+    # Returns SQL for max(a, b) that works across adapters.
+    # PostgreSQL uses GREATEST, SQLite uses MAX for scalar comparison.
+    def greatest(a, b)
+      if /sqlite/i.match?(ActiveRecord::Base.connection.adapter_name)
+        "MAX(#{a}, #{b})"
+      else
+        "GREATEST(#{a}, #{b})"
+      end
+    end
   end
 end
 

data/mise.local.toml.example

@@ -1,5 +1,5 @@
 [env]
 # used for tests
-PG_DATABASE_URL="postgres://localhost:5432/some_db
+SPEC_DATABASE_URL="postgres://localhost:5432/some_db"
 # used from console
-DATABASE_URL="postgres://localhost:5432/some_db
+CONSOLE_DATABASE_URL="postgres://localhost:5432/some_db"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.8.0.rc3
+  version: 0.9.0.rc1
 platform: ruby
 authors:
 - Gert Goet
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -43,6 +57,7 @@ files:
 - ".irbrc"
 - ".rspec"
 - ".standard.yml"
+- ".worktree.yml.example"
 - ".yard/templates/default/fulldoc/html/css/dark.css"
 - ".yard/templates/default/fulldoc/html/js/app.js"
 - ".yard/templates/default/fulldoc/html/setup.rb"
@@ -52,6 +67,7 @@ files:
 - Appraisals
 - CHANGELOG.md
 - LICENSE.txt
+- Procfile.yard
 - README.md
 - Rakefile
 - assets/banner-dark.svg
@@ -93,6 +109,7 @@ metadata:
   homepage_uri: https://github.com/eval/appquery
   source_code_uri: https://github.com/eval/appquery
   changelog_uri: https://github.com/eval/appquery/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib