appquery 0.8.0 → 0.9.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 631dc9e88f2e84a72e51c4f03843aedc1a187c18a410fc4c8b519800c24c5ab2
-  data.tar.gz: 3f006856e51702d2483598b94647e63f00fd9989d67851e6bf31dcbc2497165f
+  metadata.gz: de70b2690d884b36f8d29f8a2e76c7edefba25ca9f9fcc9785e70389c35f3aa0
+  data.tar.gz: 3c81f2fb6dd4679a86a99df91485df234ccfd449c6de0cb5317c6ca8f8e5751b
 SHA512:
-  metadata.gz: 6fe8f0822ea850a912a03eceec3e6cc7db6b4df52ce7734a67dc0bf242983720867b98dc63e37afce4ff6bd2daba600170a7eb1e90c85c97978b7e959fe7f70e
-  data.tar.gz: 9617c613888fd722b258d0d956bb0cd92dabbd9d4b4a1f1cb04a38aa37b69b2e7d2b0cc25fd306923f94cc9953aa36634171a7b7ecd95698d884118eb09c50ee
+  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/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [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  

data/README.md

@@ -290,6 +290,115 @@ 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.
@@ -322,7 +431,8 @@ rake spec
 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/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"
+  VERSION = "0.9.0.rc1"
 end

data/lib/app_query.rb

@@ -155,17 +155,62 @@ module AppQuery
     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
@@ -204,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
 
@@ -243,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
@@ -257,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)
@@ -267,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
@@ -317,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)
@@ -330,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
 
@@ -359,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
@@ -468,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
@@ -492,7 +551,8 @@ 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.
     #
@@ -550,8 +610,9 @@ module AppQuery
     #
     # @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 GREATEST((SELECT COUNT(*) FROM :_) - #{n.to_i}, 0)",
+        "SELECT * FROM :_ LIMIT #{n.to_i} OFFSET #{offset_expr}",
         binds:, cast:
       ).entries
     end
@@ -652,7 +713,16 @@ 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)
+      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")
@@ -1222,6 +1292,16 @@ module AppQuery
     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
+  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"
@@ -94,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