appquery 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e96dbd6cf521caaee6d919ee3dd7fc796bb92f48ef3e135271b8b82408fb6bcc
-  data.tar.gz: 0c2250d2a62773ae26ff79469ea6b7e0a63ac246f2824518495a0f4f2ef2b13c
+  metadata.gz: 0ca8349f2df1ddf7e2248314238dd72ff5623d2924f1265f385cb1dfde8b274d
+  data.tar.gz: 12440ed32a10ca28acd01df89175906e2ed2f77105905ed44f905bc54def4c5d
 SHA512:
-  metadata.gz: 14e0146910530087f2c56478e5c507a74ad9b6ccfea81a5c52e46fe24c07f4ef232db86056e1b97c7b7ed9ac976543b8e9c0ac4fcfcc90805aa9d668b426e061
-  data.tar.gz: 21e8afa59badf98018ba334960b3a6f301511a84305ea4941627f9d9dce3a1b24a23e52201c2a14f0a8912efbdaf9da1742b010acc364ceb72560a7910cab8e2
+  metadata.gz: 8154cfbf83c7327cc6bdfbe501430007fb4ed9a5ecfb65f6d751358e3721ca853b9d4655968955147fa2e3aa4ea898db9f71bd3da19647e4e550d2887121daab
+  data.tar.gz: a51fc511fa7b5da2bf03c4d63910abb1bb980b95fc300bf188a8749e726e965d781d14d28ffa3240dbca515c7d2bb0f5e83041eae61bb6ea7e815a1f7a13d19f

data/.irbrc

@@ -17,4 +17,13 @@ IRB.conf[:PROMPT][:APPQUERY] = {
   PROMPT_C: "#{db_indicator}appquery* ",
   RETURN: "=> %s\n"
 }
+
+# copy from history easier as prompt is not repeated across lines
+IRB.conf[:PROMPT][:CLEAN] = {
+  PROMPT_I: ">> ",
+  PROMPT_S: "   ",      # same width as ">> "
+  PROMPT_C: "   ",
+  PROMPT_N: "   ",
+  RETURN: "=> %s\n"
+}
 IRB.conf[:PROMPT_MODE] = :APPQUERY

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-12-21
+
+### 💥 Breaking Changes
+
+- 🔄 **`select:` keyword argument removed** — use positional argument instead
+  ```ruby
+  # before
+  query.select_all(select: "SELECT * FROM :_")
+  # after
+  query.select_all("SELECT * FROM :_")
+  ```
+
+### ✨ Features
+
+- 🍾 **Add paginate ERB-helper**
+  ```ruby
+  SELECT * FROM articles
+    <%= paginate(page: 1, per_page: 15) %>
+  # SELECT * FROM articles LIMIT 15 OFFSET 0
+  ```
+- 🧰 **Resolve query without extension**  
+  `AppQuery[:weekly_sales]` loads `weekly_sales.sql` or `weekly_sales.sql.erb`.
+- 🔗 **Nested result queries** via `with_select` — chain transformations using `:_` placeholder to reference the previous result
+  ```ruby
+  active_users = AppQuery("SELECT * FROM users").with_select("SELECT * FROM :_ WHERE active")
+  active_users.count("SELECT * FROM :_ WHERE admin")
+  ```
+- 🚀 **New methods**: `#column`, `#ids`, `#count`, `#entries` — efficient shortcuts that only fetch what you need
+  ```ruby
+  query.column(:email)  # SELECT email only
+  query.ids             # SELECT id only
+  query.count           # SELECT COUNT(*) only
+  query.entries         # shorthand for select_all.entries
+  ```
+
+### 🐛 Fixes
+
+- 🔧 Fix leading whitespace in `prepend_cte` causing parse errors
+- 🔧 Fix binds being reset when no placeholders found
+- ⚡ `select_one` now uses `LIMIT 1` for better performance
+
+### 📚 Documentation
+
+- 📖 Revised README with cleaner intro and examples
+- 🏠 Added example Rails app in `examples/demo`
+
 ## [0.4.0] - 2025-12-15
 
 ### features

data/README.md

@@ -3,63 +3,40 @@
 [![Gem Version](https://badge.fury.io/rb/appquery.svg)](https://badge.fury.io/rb/appquery)
 [![API Docs](https://img.shields.io/badge/API_Docs-YARD-blue.svg)](https://eval.github.io/appquery/)
 
-A Rubygem :gem: that makes working with raw SQL queries in Rails projects convenient.  
-Specifically it provides:
-- **...a dedicated folder for queries**  
-  e.g. `app/queries/reports/weekly.sql` is instantiated via `AppQuery["reports/weekly"]`.
-
-- **...ERB templating**  
-  Simple ERB templating with helper-functions:
-  ```sql
-  -- app/queries/contracts.sql.erb
-  SELECT * FROM contracts
-  <%= order_by(order) %>
-  ```
-  ```ruby
-  AppQuery["contracts.sql.erb"].render(order: {year: :desc, month: :desc}).select_all
-  ```
-- **...positional and named binds**  
-  Intuitive binds:
-  ```ruby
-  AppQuery(<<~SQL).select_value(binds: {interval: '1 day'})
-    select now() - (:interval)::interval as some_date
-  SQL
-  AppQuery(<<~SQL).select_all(binds: [2.day.ago, Time.now, '5 minutes']).column("series")
-    select generate_series($1::timestamp, $2::timestamp, $3::interval) as series
-  SQL
-  ```
-- **...casting**  
-  Automatic and custom casting:
-  ```ruby
-  AppQuery(%{select array[1,2]}).select_value #=> [1,2]
-  cast = {"data" => ActiveRecord::Type::Json.new}
-  AppQuery(%{select '{"a": 1}' as data}).select_value(cast:)
-  ```
-- **...helpers to rewrite a query for introspection during development and testing**  
-  See what a CTE yields: `query.select_all(select: "SELECT * FROM some_cte")`.  
-  Query the end result: `query.select_one(select: "SELECT COUNT(*) FROM _ WHERE ...")`.  
-  Append/prepend CTEs:
-  ```ruby
-  query.prepend_cte(<<~CTE)
-    articles(id, title) AS (
-      VALUES(1, 'Some title'),
-            (2, 'Another article'))
-  CTE
-  ```
-- **...rspec generators and helpers**  
-  ```ruby
-  RSpec.describe "AppQuery reports/weekly", type: :query do
-    describe "CTE some_cte" do
-      # see what this CTE yields
-      expect(described_query.select_all(select: "select * from some_cte")).to \
-        include(a_hash_including("id" => 1))
-  
-      # shorter: the query and CTE are derived from the describe-descriptions so this suffices:
-      expect(select_all).to include ...
-  ```
+A Ruby gem for working with raw SQL in Rails. Store queries in `app/queries/`, execute them with proper type casting, and filter/transform results using CTEs.
+
+```ruby
+# Load and execute
+week = AppQuery[:weekly_sales].with_binds(week: 1, year: 2025)
+week.entries
+#=> [{"week" => 2025-01-13, "category" => "Electronics", "revenue" => 12500, "target_met" => true}, ...]
+
+# Filter results (query wraps in CTE, :_ references it)
+week.count("SELECT * FROM :_ WHERE NOT target_met")
+#=> 3
+
+# Extract a column efficiently (only fetches that column)
+week.column(:category)
+#=> ["Electronics", "Clothing", "Home & Garden"]
+
+# Named binds with defaults
+AppQuery[:weekly_sales].select_all(binds: {min_revenue: 5000})
+
+# ERB templating
+AppQuery("SELECT * FROM contracts <%= order_by(ordering) %>")
+  .render(ordering: {year: :desc}).select_all
+
+# Custom type casting
+AppQuery("SELECT metadata FROM products").select_all(cast: {"metadata" => ActiveRecord::Type::Json.new})
+
+# Inspect/mock CTEs for testing
+query.prepend_cte("sales AS (SELECT * FROM mock_data)")
+```
+
+**Highlights**: query files with generator · `select_all`/`select_one`/`select_value`/`count`/`column`/`ids` · query transformation via CTEs · immutable (derive new queries from existing) · named binds · ERB helpers (`order_by`, `paginate`, `values`, `bind`) · automatic + custom type casting · RSpec integration
 
 > [!IMPORTANT]  
-> **Status**: alpha. API might change. See the CHANGELOG for breaking changes when upgrading.
+> **Status**: alpha. API might change. See [the CHANGELOG](./CHANGELOG.md) for breaking changes when upgrading.
 >
 
 ## Rationale
@@ -104,14 +81,23 @@ The prompt indicates what adapter the example uses:
 => "2025-05-10"
 
 # binds
-# positional binds
-[postgresql]> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
-# named binds
+## named binds
 [postgresql]> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
 
+## not all binds need to be provided (ie they are nil by default) - so defaults can be added in SQL:
+[postgresql]> AppQuery(<<~SQL).select_all(binds: {ts1: 2.day.ago, ts2: Time.now}).column("series")
+  SELECT
+    generate_series(:ts1::timestamp, COALESCE(:ts2, :ts2::timestamp, COALESCE(:interval, '5 minutes')::interval)
+    AS series
+SQL
+
 # casting
-[postgresql]> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
-=> [{"today" => Sat, 10 May 2025}]
+## Cast values are used by default:
+[postgresql]> AppQuery(%{select date('now')}).select_first
+=> {"today" => Sat, 10 May 2025}
+## compare ActiveRecord
+[postgresql]> ActiveRecord::Base.connection.select_first(%{select date('now') as today})
+=> {"today" => "2025-12-20"}
 
 ## SQLite doesn't have a notion of dates or timestamp's so casting won't do anything:
 [sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: true)
@@ -134,10 +120,12 @@ casts = {"today" => ActiveRecord::Type::Date.new}
 SQL
 
 ## query the articles-CTE
-[postgresql]> q.select_all(select: %{select * from articles where id < 2}).to_a
+[postgresql]> q.select_all(%{select * from articles where id < 2}).to_a
 
-## query the end-result (available as the CTE named '_')
-[postgresql]> q.select_one(select: %{select * from _ limit 1})
+## query the end-result (available via the placeholder ':_')
+[postgresql]> q.select_one(%{select * from :_ limit 1})
+### shorthand for that
+[postgresql]> q.first
 
 ## ERB templating
 # Extract a query from q that can be sorted dynamically:
@@ -164,7 +152,7 @@ SQL
 ### ...in a Rails project
 
 > [!NOTE]
-> The included [example Rails app](./examples/ror) contains all data and queries described below.
+> The included [example Rails app](./examples/demo) contains all data and queries described below.
 
 Create a query:  
 ```bash
@@ -174,15 +162,15 @@ rails g query recent_articles
 Have some SQL (for SQLite, in this example):
 ```sql
 -- app/queries/recent_articles.sql
-WITH settings(default_min_published_on) as (
-  values(datetime('now', '-6 months'))
+WITH settings(min_published_on) as (
+  values(COALESCE(:since, datetime('now', '-6 months')))
 ),
 
 recent_articles(article_id, article_title, article_published_on, article_url) AS (
   SELECT id, title, published_on, url
   FROM articles
   RIGHT JOIN settings
-  WHERE published_on > COALESCE(?1, settings.default_min_published_on)
+  WHERE published_on > settings.min_published_on
 ),
 
 tags_by_article(article_id, tags) AS (
@@ -201,7 +189,7 @@ JOIN tags_by_article USING(article_id),
 WHERE EXISTS (
   SELECT 1
   FROM json_each(tags)
-  WHERE json_each.value LIKE ?2 OR ?2 IS NULL
+  WHERE json_each.value LIKE :tag OR :tag IS NULL
 )
 GROUP BY recent_articles.article_id
 ORDER BY recent_articles.article_published_on
@@ -248,28 +236,31 @@ AppQuery[:recent_articles].select_all.entries
 ...
 ]
 
-# we can provide a different cut off date via binds^1:
-AppQuery[:recent_articles].select_all(binds: [1.month.ago]).entries
+# we can provide a different cut off date via binds:
+AppQuery[:recent_articles].select_all(binds: {since: 1.month.ago}).entries
 
-1) note that SQLite can deal with unbound parameters, i.e. when no binds are provided it assumes null for
-  $1 and $2 (which our query can deal with).
-  For Postgres you would always need to provide 2 values, e.g. `binds: [nil, nil]`.
+# NOTE: by default the binds get initialized with nil, e.g. for this example {since: nil, tag: nil}
+# This prevents you from having to provide all binds every time. Default values are put in the SQL (via COALESCE).
 ```
 
-We can also dig deeper by query-ing the result, i.e. the CTE `_`:
+We can also dig deeper by query-ing the result, i.e. the CTE `:_`:
 
 ```ruby
-AppQuery[:recent_articles].select_one(select: "select count(*) as cnt from _")
+AppQuery[:recent_articles].select_one("select count(*) as cnt from :_")
 # => {"cnt" => 13}
 
 # For these kind of aggregate queries, we're only interested in the value:
-AppQuery[:recent_articles].select_value(select: "select count(*) from _")
+AppQuery[:recent_articles].select_value("select count(*) from :_")
 # => 13
+
+# but there's also the shorthand #count (which takes a sub-select):
+AppQuery[:recent_articles].count #=> 13
+AppQuery[:recent_articles].count(binds: {since: 0}) #=> 275
 ```
 
 Use `AppQuery#with_select` to get a new AppQuery-instance with the rewritten SQL:
 ```ruby
-puts AppQuery[:recent_articles].with_select("select * from _")
+puts AppQuery[:recent_articles].with_select("select id from :_")
 ```
 
 
@@ -277,15 +268,15 @@ puts AppQuery[:recent_articles].with_select("select * from _")
 
 You can select from a CTE similarly:
 ```ruby
-AppQuery[:recent_articles].select_all(select: "SELECT * FROM tags_by_article")
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article")
 # => [{"article_id"=>1, "tags"=>"[\"release:pre\",\"release:patch\",\"release:1x\"]"},
       ...]
 
 # NOTE how the tags are json strings. Casting allows us to turn these into proper arrays^1:
 types = {"tags" => ActiveRecord::Type::Json.new}
-AppQuery[:recent_articles].select_all(select: "SELECT * FROM tags_by_article", cast: types)
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article", cast: types)
 
-1) PostgreSQL, unlike SQLite, has json and array types. Just casting suffices:
+1) unlike SQLite, PostgreSQL has json and array types. Just casting suffices:
 AppQuery("select json_build_object('a', 1, 'b', true)").select_one(cast: true)
 # => {"json_build_object"=>{"a"=>1, "b"=>true}}
 ```
@@ -294,7 +285,7 @@ Using the methods `(prepend|append|replace)_cte`, we can rewrite the query beyon
 
 ```ruby
 AppQuery[:recent_articles].replace_cte(<<~SQL).select_all.entries
-settings(default_min_published_on) as (
+settings(min_published_on) as (
   values(datetime('now', '-12 months'))
 )
 SQL
@@ -306,10 +297,10 @@ You could even mock existing tables (using PostgreSQL):
 sample_articles = [{id: 1, title: "Some title", published_on: 3.months.ago},
                    {id: 2, title: "Another title", published_on: 1.months.ago}]
 # show the provided cutoff date works
-AppQuery[:recent_articles].prepend_cte(<<-CTE).select_all(binds: [6.weeks.ago, nil, JSON[sample_articles]).entries
-  articles AS (
-    SELECT * from json_to_recordset($3) AS x(id int, title text, published_on timestamp)
-  )
+AppQuery[:recent_articles].prepend_cte(<<-CTE).select_all(binds: {since: 6.weeks.ago, articles: JSON[sample_articles]}).entries
+articles AS (
+  SELECT * from json_to_recordset(:articles) AS x(id int, title text, published_on timestamp)
+)
 CTE
 ```
 
@@ -329,7 +320,7 @@ require "rails_helper"
 RSpec.describe "AppQuery reports/weekly", type: :query, default_binds: [] do
   describe "CTE articles" do
     specify do
-      expect(described_query.select_all(select: "select * from :cte")).to \
+      expect(described_query.select_all("select * from :cte")).to \
         include(a_hash_including("article_id" => 1))
 
       # short version: query, cte and select are all implied from descriptions
@@ -347,7 +338,6 @@ There's some sugar:
   When doing `select_all`, you can rewrite the `SELECT` of the query by passing `select`. There's no need to use the full name of the CTE as the spec-description contains the name (i.e. "articles" in "CTE articles").
 - default_binds  
   The `binds`-value used when not explicitly provided.  
-  E.g. given a query with a where-clause `WHERE published_at > COALESCE($1::timestamp, NOW() - '3 month'::interval)`, when setting `defaults_binds: [nil]` then `select_all` works like `select_all(binds: [nil])`.
 
 ## API Documentation
 

data/lib/app_query/render_helpers.rb

@@ -155,32 +155,70 @@ module AppQuery
     #   order_by(year: :desc, month: :desc)
     #   #=> "ORDER BY year DESC, month DESC"
     #
-    # @example Mixed directions
-    #   order_by(published_on: :desc, title: :asc)
-    #   #=> "ORDER BY published_on DESC, title ASC"
-    #
     # @example Column without direction (uses database default)
     #   order_by(id: nil)
     #   #=> "ORDER BY id"
     #
+    # @example SQL literal
+    #   order_by("RANDOM()")
+    #   #=> "ORDER BY RANDOM()"
+    #
     # @example In an ERB template with a variable
     #   SELECT * FROM articles
     #   <%= order_by(ordering) %>
     #
     # @example Making it optional (when ordering may not be provided)
-    #   <%= @ordering.presence && order_by(ordering) %>
+    #   <%= @order.presence && order_by(ordering) %>
     #
     # @example With default fallback
-    #   <%= order_by(@order || {id: :desc}) %>
+    #   <%= order_by(@order.presence || {id: :desc}) %>
     #
     # @raise [ArgumentError] if hash is blank (nil, empty, or not present)
     #
     # @note The hash must not be blank. Use conditional ERB for optional ordering.
-    def order_by(hash)
-      raise ArgumentError, "Provide columns to sort by, e.g. order_by(id: :asc)  (got #{hash.inspect})." unless hash.present?
-      "ORDER BY " + hash.map do |k, v|
-        v.nil? ? k : [k, v.upcase].join(" ")
-      end.join(", ")
+    def order_by(order)
+      usage = <<~USAGE
+        Provide columns to sort by, e.g. order_by(id: :asc), or SQL-literal, e.g. order_by("RANDOM()")  (got #{order.inspect}).
+      USAGE
+      raise ArgumentError, usage unless order.present?
+
+      case order
+      when String then "ORDER BY #{order}"
+      when Hash
+        "ORDER BY " + order.map do |k, v|
+          v.nil? ? k : [k, v.upcase].join(" ")
+        end.join(", ")
+      else
+        raise ArgumentError, usage
+      end
+    end
+
+    # Generates a LIMIT/OFFSET clause for pagination.
+    #
+    # @param page [Integer] the page number (1-indexed)
+    # @param per_page [Integer] the number of items per page
+    # @return [String] the LIMIT/OFFSET clause
+    #
+    # @example Basic pagination
+    #   paginate(page: 1, per_page: 25)
+    #   #=> "LIMIT 25 OFFSET 0"
+    #
+    # @example Second page
+    #   paginate(page: 2, per_page: 25)
+    #   #=> "LIMIT 25 OFFSET 25"
+    #
+    # @example In an ERB template
+    #   SELECT * FROM articles
+    #   ORDER BY created_at DESC
+    #   <%= paginate(page: page, per_page: per_page) %>
+    #
+    # @raise [ArgumentError] if page or per_page is not a positive integer
+    def paginate(page:, per_page:)
+      raise ArgumentError, "page must be a positive integer (got #{page.inspect})" unless page.is_a?(Integer) && page > 0
+      raise ArgumentError, "per_page must be a positive integer (got #{per_page.inspect})" unless per_page.is_a?(Integer) && per_page > 0
+
+      offset = (page - 1) * per_page
+      "LIMIT #{per_page} OFFSET #{offset}"
     end
 
     private

data/lib/app_query/rspec/helpers.rb

@@ -5,6 +5,10 @@ module AppQuery
         self.class.default_binds
       end
 
+      def default_vars
+        self.class.default_vars
+      end
+
       def expand_select(s)
         s.gsub(":cte", cte_name)
       end
@@ -24,7 +28,7 @@ module AppQuery
       def described_query(select: nil)
         select ||= "SELECT * FROM :cte" if cte_name
         select &&= expand_select(select) if cte_name
-        self.class.described_query.with_select(select)
+        self.class.described_query.render(default_vars).with_select(select)
       end
 
       def cte_name
@@ -72,6 +76,10 @@ module AppQuery
           metadatas.find { _1[:default_binds] }&.[](:default_binds) || []
         end
 
+        def default_vars
+          metadatas.find { _1[:default_vars] }&.[](:default_vars) || {}
+        end
+
         def included(klass)
           super
           # Inject classmethods into the group.

data/lib/app_query/tokenizer.rb

@@ -95,8 +95,9 @@ module AppQuery
       if eos?
         emit_token "COMMA", v: ","
         emit_token "WHITESPACE", v: "\n"
+      elsif match?(/\s/)
+        push_return :lex_prepend_cte, :lex_whitespace
       else
-        # emit_token "WHITESPACE", v: " "
         push_return :lex_prepend_cte, :lex_recursive_cte
       end
     end

data/lib/app_query/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AppQuery
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/app_query.rb

@@ -72,21 +72,44 @@ module AppQuery
 
   # Loads a query from a file in the configured query path.
   #
+  # When no extension is provided, tries `.sql` first, then `.sql.erb`.
+  # Raises an error if both files exist (ambiguous).
+  #
   # @param query_name [String, Symbol] the query name or path (without extension)
   # @param opts [Hash] additional options passed to {Q#initialize}
   # @return [Q] a new query object loaded from the file
   #
-  # @example Load a simple query
+  # @example Load a .sql file
   #   AppQuery[:invoices]  # loads app/queries/invoices.sql
   #
+  # @example Load a .sql.erb file (when .sql doesn't exist)
+  #   AppQuery[:dynamic_report]  # loads app/queries/dynamic_report.sql.erb
+  #
   # @example Load from a subdirectory
   #   AppQuery["reports/weekly"]  # loads app/queries/reports/weekly.sql
   #
   # @example Load with explicit extension
   #   AppQuery["invoices.sql.erb"]  # loads app/queries/invoices.sql.erb
+  #
+  # @raise [Error] if both `.sql` and `.sql.erb` files exist for the same name
   def self.[](query_name, **opts)
-    filename = File.extname(query_name.to_s).empty? ? "#{query_name}.sql" : query_name.to_s
-    full_path = (Pathname.new(configuration.query_path) / filename).expand_path
+    base = Pathname.new(configuration.query_path) / query_name.to_s
+
+    full_path = if File.extname(query_name.to_s).empty?
+      sql_path = base.sub_ext(".sql").expand_path
+      erb_path = base.sub_ext(".sql.erb").expand_path
+      sql_exists = sql_path.exist?
+      erb_exists = erb_path.exist?
+
+      if sql_exists && erb_exists
+        raise Error, "Ambiguous query name #{query_name.inspect}: both #{sql_path} and #{erb_path} exist"
+      end
+
+      sql_exists ? sql_path : erb_path
+    else
+      base.expand_path
+    end
+
     Q.new(full_path.read, name: "AppQuery #{query_name}", filename: full_path.to_s, **opts)
   end
 
@@ -186,14 +209,14 @@ module AppQuery
     # @return [String] the SQL string
     # @return [Array, Hash] bind parameters
     # @return [Boolean, Hash, Array] casting configuration
-    attr_reader :name, :sql, :binds, :cast
+    attr_reader :sql, :name, :filename, :binds, :cast
 
     # Creates a new query object.
     #
     # @param sql [String] the SQL query string (may contain ERB)
     # @param name [String, nil] optional name for logging
     # @param filename [String, nil] optional filename for ERB error reporting
-    # @param binds [Array, Hash] bind parameters for the query
+    # @param binds [Hash, nil] bind parameters for the query
     # @param cast [Boolean, Hash, Array] type casting configuration
     #
     # @example Simple query
@@ -201,28 +224,38 @@ 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)
+    def initialize(sql, name: nil, filename: nil, binds: {}, cast: true, cte_depth: 0)
       @sql = sql
       @name = name
       @filename = filename
       @binds = binds
       @cast = cast
+      @cte_depth = cte_depth
+      @binds = binds_with_defaults(sql, binds)
     end
 
-    # @private
-    def deep_dup
-      super.send(:reset!)
+    attr_reader :cte_depth
+
+    def to_arel
+      if binds.presence
+        Arel::Nodes::BoundSqlLiteral.new sql, [], binds
+      else
+        # TODO: add retryable? available from >=7.1
+        Arel::Nodes::SqlLiteral.new(sql)
+      end
     end
-    private :deep_dup
 
-    # @private
-    def reset!
-      (instance_variables - %i[@sql @filename @name @binds @cast]).each do
-        instance_variable_set(_1, nil)
+    private def binds_with_defaults(sql, binds)
+      if (named_binds = sql.scan(/:(?<!::)([a-zA-Z]\w*)/).flatten.map(&:to_sym).uniq.presence)
+        named_binds.zip(Array.new(named_binds.count)).to_h.merge(binds.to_h)
+      else
+        binds.to_h
       end
-      self
     end
-    private :reset!
+
+    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:)
+    end
 
     # @!group Rendering
 
@@ -267,12 +300,7 @@ module AppQuery
       sql = to_erb.result(helper.get_binding)
       collected = helper.collected_binds
 
-      with_sql(sql).tap do |q|
-        # Merge collected binds with existing binds (convert array to hash if needed)
-        existing = @binds.is_a?(Hash) ? @binds : {}
-        new_binds = existing.merge(collected)
-        q.instance_variable_set(:@binds, new_binds) if new_binds.any?
-      end
+      with_sql(sql).add_binds(**collected)
     end
 
     def to_erb
@@ -306,15 +334,12 @@ module AppQuery
 
     # Executes the query and returns all matching rows.
     #
-    # @param binds [Array, Hash, nil] bind parameters (positional or named)
     # @param select [String, nil] override the SELECT clause
+    # @param binds [Hash, nil] bind parameters to add
     # @param cast [Boolean, Hash, Array] type casting configuration
     # @return [Result] the query results with optional type casting
     #
-    # @example Simple query with positional binds
-    #   AppQuery("SELECT * FROM users WHERE id = $1").select_all(binds: [1])
-    #
-    # @example Named binds
+    # @example (Named) binds
     #   AppQuery("SELECT * FROM users WHERE id = :id").select_all(binds: {id: 1})
     #
     # @example With type casting
@@ -325,37 +350,17 @@ module AppQuery
     #   AppQuery("SELECT * FROM users").select_all(select: "COUNT(*)")
     #
     # @raise [UnrenderedQueryError] if the query contains unrendered ERB
-    # @raise [ArgumentError] if mixing positional binds with collected named binds
     #
     # TODO: have aliases for common casts: select_all(cast: {"today" => :date})
-    def select_all(binds: nil, select: nil, cast: self.cast)
-      with_select(select).render({}).then do |aq|
-        # Support both positional (array) and named (hash) binds
-        if binds.is_a?(Array)
-          if @binds.is_a?(Hash) && @binds.any?
-            raise ArgumentError, "Cannot use positional binds (Array) when query has collected named binds from values()/bind() helpers. Use named binds (Hash) instead."
-          end
-          # Positional binds using $1, $2, etc.
-          ActiveRecord::Base.connection.select_all(aq.to_s, name, binds).then do |result|
-            Result.from_ar_result(result, cast)
-          end
+    def select_all(s = nil, binds: {}, cast: self.cast)
+      add_binds(**binds).with_select(s).render({}).then do |aq|
+        sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+          aq.to_arel
         else
-          # Named binds - merge collected binds with explicitly passed binds
-          merged_binds = (@binds.is_a?(Hash) ? @binds : {}).merge(binds || {})
-          if merged_binds.any?
-            sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
-              Arel.sql(aq.to_s, **merged_binds)
-            else
-              ActiveRecord::Base.sanitize_sql_array([aq.to_s, **merged_binds])
-            end
-            ActiveRecord::Base.connection.select_all(sql, name).then do |result|
-              Result.from_ar_result(result, cast)
-            end
-          else
-            ActiveRecord::Base.connection.select_all(aq.to_s, name).then do |result|
-              Result.from_ar_result(result, cast)
-            end
-          end
+          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)
         end
       end
     rescue NameError => e
@@ -366,23 +371,24 @@ module AppQuery
 
     # Executes the query and returns the first row.
     #
-    # @param binds [Array, Hash, nil] bind parameters (positional or named)
+    # @param binds [Hash, nil] bind parameters to add
     # @param select [String, nil] override the SELECT clause
     # @param cast [Boolean, Hash, Array] type casting configuration
     # @return [Hash, nil] the first row as a hash, or nil if no results
     #
     # @example
-    #   AppQuery("SELECT * FROM users WHERE id = $1").select_one(binds: [1])
+    #   AppQuery("SELECT * FROM users WHERE id = :id").select_one(binds: {id: 1})
     #   # => {"id" => 1, "name" => "Alice"}
     #
     # @see #select_all
-    def select_one(binds: nil, select: nil, cast: self.cast)
-      select_all(binds:, select:, cast:).first
+    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
 
     # Executes the query and returns the first value of the first row.
     #
-    # @param binds [Array, Hash, nil] bind parameters (positional or named)
+    # @param binds [Hash, nil] named bind parameters
     # @param select [String, nil] override the SELECT clause
     # @param cast [Boolean, Hash, Array] type casting configuration
     # @return [Object, nil] the first value, or nil if no results
@@ -392,13 +398,94 @@ module AppQuery
     #   # => 42
     #
     # @see #select_one
-    def select_value(binds: nil, select: nil, cast: self.cast)
-      select_one(binds:, select:, cast:)&.values&.first
+    def select_value(s = nil, binds: {}, cast: self.cast)
+      select_one(s, binds:, cast:)&.values&.first
+    end
+
+    # Returns the count of rows from the query.
+    #
+    # Wraps the query in a CTE and selects only the count, which is more
+    # efficient than fetching all rows via `select_all.count`.
+    #
+    # @param s [String, nil] optional SELECT to apply before counting
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Integer] the count of rows
+    #
+    # @example Simple count
+    #   AppQuery("SELECT * FROM users").count
+    #   # => 42
+    #
+    # @example Count with filtering
+    #   AppQuery("SELECT * FROM users")
+    #     .with_select("SELECT * FROM :_ WHERE active")
+    #     .count
+    #   # => 10
+    def count(s = nil, binds: {})
+      with_select(s).select_all("SELECT COUNT(*) c FROM :_", binds:).column("c").first
+    end
+
+    # Returns an array of values for a single column.
+    #
+    # Wraps the query in a CTE and selects only the specified column, which is
+    # more efficient than fetching all columns via `select_all.column(name)`.
+    # The column name is safely quoted, making this method safe for user input.
+    #
+    # @param c [String, Symbol] the column name to extract
+    # @param s [String, nil] optional SELECT to apply before extracting
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Array] the column values
+    #
+    # @example Extract a single column
+    #   AppQuery("SELECT id, name FROM users").column(:name)
+    #   # => ["Alice", "Bob", "Charlie"]
+    #
+    # @example With additional filtering
+    #   AppQuery("SELECT * FROM users").column(:email, "SELECT * FROM :_ WHERE active")
+    #   # => ["alice@example.com", "bob@example.com"]
+    def column(c, s = nil, binds: {})
+      quoted_column = ActiveRecord::Base.connection.quote_column_name(c)
+      with_select(s).select_all("SELECT #{quoted_column} AS column FROM :_", binds:).column("column")
+    end
+
+    # Returns an array of id values from the query.
+    #
+    # Convenience method equivalent to `column(:id)`. More efficient than
+    # fetching all columns via `select_all.column("id")`.
+    #
+    # @param s [String, nil] optional SELECT to apply before extracting
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Array] the id values
+    #
+    # @example Get all user IDs
+    #   AppQuery("SELECT * FROM users").ids
+    #   # => [1, 2, 3]
+    #
+    # @example With filtering
+    #   AppQuery("SELECT * FROM users").ids("SELECT * FROM :_ WHERE active")
+    #   # => [1, 3]
+    def ids(s = nil, binds: {})
+      column(:id, s, binds:)
+    end
+
+    # Executes the query and returns results as an Array of Hashes.
+    #
+    # Shorthand for `select_all(...).entries`. Accepts the same arguments as
+    # {#select_all}.
+    #
+    # @return [Array<Hash>] the query results as an array
+    #
+    # @example
+    #   AppQuery("SELECT * FROM users").entries
+    #   # => [{"id" => 1, "name" => "Alice"}, {"id" => 2, "name" => "Bob"}]
+    #
+    # @see #select_all
+    def entries(...)
+      select_all(...).entries
     end
 
     # Executes an INSERT query.
     #
-    # @param binds [Array, Hash] bind parameters for the query
+    # @param binds [Hash, nil] bind parameters for the query
     # @param returning [String, nil] columns to return (Rails 7.1+ only)
     # @return [Integer, Object] the inserted ID or returning value
     #
@@ -419,30 +506,22 @@ module AppQuery
     #
     # @raise [UnrenderedQueryError] if the query contains unrendered ERB
     # @raise [ArgumentError] if returning is used with Rails < 7.1
-    def insert(binds: [], returning: nil)
+    def insert(binds: {}, returning: nil)
       # ActiveRecord::Base.connection.insert(sql, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds, returning: nil)
       if returning && ActiveRecord::VERSION::STRING.to_f < 7.1
         raise ArgumentError, "The 'returning' option requires Rails 7.1+. Current version: #{ActiveRecord::VERSION::STRING}"
       end
 
-      binds = binds.presence || @binds
-      render({}).then do |aq|
-        if binds.is_a?(Hash)
-          sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
-            Arel.sql(aq.to_s, **binds)
-          else
-            ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
-          end
-          if ActiveRecord::VERSION::STRING.to_f >= 7.1
-            ActiveRecord::Base.connection.insert(sql, name, returning:)
-          else
-            ActiveRecord::Base.connection.insert(sql, name)
-          end
-        elsif ActiveRecord::VERSION::STRING.to_f >= 7.1
-          # pk is the less flexible returning
-          ActiveRecord::Base.connection.insert(aq.to_s, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds, returning:)
+      with_binds(**binds).render({}).then do |aq|
+        sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+          aq.to_arel
+        else
+          ActiveRecord::Base.sanitize_sql_array([aq.to_s, **aq.binds])
+        end
+        if ActiveRecord::VERSION::STRING.to_f >= 7.1
+          ActiveRecord::Base.connection.insert(sql, name, returning:)
         else
-          ActiveRecord::Base.connection.insert(aq.to_s, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds)
+          ActiveRecord::Base.connection.insert(sql, name)
         end
       end
     rescue NameError => e
@@ -453,7 +532,7 @@ module AppQuery
 
     # Executes an UPDATE query.
     #
-    # @param binds [Array, Hash] bind parameters for the query
+    # @param binds [Hash, nil] bind parameters for the query
     # @return [Integer] the number of affected rows
     #
     # @example With named binds
@@ -465,19 +544,14 @@ module AppQuery
     #     .update(binds: ["New Title", 1])
     #
     # @raise [UnrenderedQueryError] if the query contains unrendered ERB
-    def update(binds: [])
-      binds = binds.presence || @binds
-      render({}).then do |aq|
-        if binds.is_a?(Hash)
-          sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
-            Arel.sql(aq.to_s, **binds)
-          else
-            ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
-          end
-          ActiveRecord::Base.connection.update(sql, name)
+    def update(binds: {})
+      with_binds(**binds).render({}).then do |aq|
+        sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+          aq.to_arel
         else
-          ActiveRecord::Base.connection.update(aq.to_s, name, binds)
+          ActiveRecord::Base.sanitize_sql_array([aq.to_s, **aq.binds])
         end
+        ActiveRecord::Base.connection.update(sql, name)
       end
     rescue NameError => e
       raise e unless e.instance_of?(NameError)
@@ -486,7 +560,7 @@ module AppQuery
 
     # Executes a DELETE query.
     #
-    # @param binds [Array, Hash] bind parameters for the query
+    # @param binds [Hash, nil] bind parameters for the query
     # @return [Integer] the number of deleted rows
     #
     # @example With named binds
@@ -496,19 +570,14 @@ module AppQuery
     #   AppQuery("DELETE FROM videos WHERE id = $1").delete(binds: [1])
     #
     # @raise [UnrenderedQueryError] if the query contains unrendered ERB
-    def delete(binds: [])
-      binds = binds.presence || @binds
-      render({}).then do |aq|
-        if binds.is_a?(Hash)
-          sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
-            Arel.sql(aq.to_s, **binds)
-          else
-            ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
-          end
-          ActiveRecord::Base.connection.delete(sql, name)
+    def delete(binds: {})
+      with_binds(**binds).render({}).then do |aq|
+        sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+          aq.to_arel
         else
-          ActiveRecord::Base.connection.delete(aq.to_s, name, binds)
+          ActiveRecord::Base.sanitize_sql_array([aq.to_s, **aq.binds])
         end
+        ActiveRecord::Base.connection.delete(sql, name)
       end
     rescue NameError => e
       raise e unless e.instance_of?(NameError)
@@ -547,16 +616,29 @@ module AppQuery
 
     # Returns a new query with different bind parameters.
     #
-    # @param binds [Array, Hash] the new bind parameters
-    # @return [Q] a new query object with the specified binds
+    # @param binds [Hash, nil] the bind parameters
+    # @return [Q] a new query object with the binds replaced
     #
     # @example
-    #   query = AppQuery("SELECT * FROM users WHERE id = :id")
-    #   query.with_binds(id: 1).select_one
-    def with_binds(binds)
-      deep_dup.tap do
-        _1.instance_variable_set(:@binds, binds)
-      end
+    #   query = AppQuery("SELECT :foo, :bar", binds: {foo: 1})
+    #   query.with_binds(bar: 2).binds
+    #   # => {foo: nil, bar: 2}
+    def with_binds(**binds)
+      deep_dup(binds:)
+    end
+    alias_method :replace_binds, :with_binds
+
+    # Returns a new query with binds added.
+    #
+    # @param binds [Hash, nil] the bind parameters to add
+    # @return [Q] a new query object with the added binds
+    #
+    # @example
+    #   query = AppQuery("SELECT :foo, :bar", binds: {foo: 1})
+    #   query.add_binds(bar: 2).binds
+    #   # => {foo: 1, bar: 2}
+    def add_binds(**binds)
+      deep_dup(binds: self.binds.merge(binds))
     end
 
     # Returns a new query with different cast settings.
@@ -568,9 +650,7 @@ module AppQuery
     #   query = AppQuery("SELECT created_at FROM users")
     #   query.with_cast(false).select_all  # disable casting
     def with_cast(cast)
-      deep_dup.tap do
-        _1.instance_variable_set(:@cast, cast)
-      end
+      deep_dup(cast:)
     end
 
     # Returns a new query with different SQL.
@@ -578,31 +658,48 @@ module AppQuery
     # @param sql [String] the new SQL string
     # @return [Q] a new query object with the specified SQL
     def with_sql(sql)
-      deep_dup.tap do
-        _1.instance_variable_set(:@sql, sql)
-      end
+      deep_dup(sql:)
     end
 
     # Returns a new query with a modified SELECT statement.
     #
-    # If the query has a CTE named `"_"`, replaces the SELECT statement.
-    # Otherwise, wraps the original query in a `"_"` CTE and uses the new SELECT.
+    # Wraps the current SELECT in a numbered CTE and applies the new SELECT.
+    # CTEs are named `_`, `_1`, `_2`, etc. Use `:_` in the new SELECT to
+    # reference the previous result.
     #
     # @param sql [String, nil] the new SELECT statement (nil returns self)
     # @return [Q] a new query object with the modified SELECT
     #
-    # @example
-    #   AppQuery("SELECT id, name FROM users").with_select("SELECT COUNT(*) FROM _")
-    #   # => "WITH _ AS (\n  SELECT id, name FROM users\n)\nSELECT COUNT(*) FROM _"
+    # @example Single transformation
+    #   AppQuery("SELECT * FROM users").with_select("SELECT COUNT(*) FROM :_")
+    #   # => "WITH _ AS (\n  SELECT * FROM users\n)\nSELECT COUNT(*) FROM _"
+    #
+    # @example Chained transformations
+    #   AppQuery("SELECT * FROM users")
+    #     .with_select("SELECT * FROM :_ WHERE active")
+    #     .with_select("SELECT COUNT(*) FROM :_")
+    #   # => WITH _ AS (SELECT * FROM users),
+    #   #         _1 AS (SELECT * FROM _ WHERE active)
+    #   #    SELECT COUNT(*) FROM _1
     def with_select(sql)
       return self if sql.nil?
-      if cte_names.include?("_")
-        with_sql(tokens.each_with_object([]) do |token, acc|
-          v = (token[:t] == "SELECT") ? sql : token[:v]
+
+      # First CTE is "_", then "_1", "_2", etc.
+      current_cte = (cte_depth == 0) ? "_" : "_#{cte_depth}"
+
+      # Replace :_ with the current CTE name
+      processed_sql = sql.gsub(/:_\b/, current_cte)
+
+      # Wrap current SELECT in numbered CTE
+      new_cte = "#{current_cte} AS (\n  #{select}\n)"
+
+      append_cte(new_cte).then do |q|
+        # Replace the SELECT token with processed_sql and increment depth
+        new_sql = q.tokens.each_with_object([]) do |token, acc|
+          v = (token[:t] == "SELECT") ? processed_sql : token[:v]
           acc << v
-        end.join)
-      else
-        append_cte("_ as (\n  #{select}\n)").with_select(sql)
+        end.join
+        q.deep_dup(sql: new_sql, cte_depth: cte_depth + 1)
       end
     end
 

data/mise.toml

@@ -3,4 +3,4 @@ ruby = "3.4"
 
 [env]
 _.path = ["bin"]
-PROJECT_ROOT = "{{config_root}}"
+PROJECT_ROOT = "{{config_root}}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Gert Goet
@@ -73,7 +73,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/eval/appquery
   source_code_uri: https://github.com/eval/appquery
-  changelog_uri: https://github.com/eval/gem-try/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/eval/appquery/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib