appquery 0.8.0.rc3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dacb58820ea6f11ec37fa1e73f7aeb9eec507d92b4e302cd8134f2c768abeba
-  data.tar.gz: d371f97ca509a6c9dde67f2aec9edc67a7690b00081a5d596003608ae4958748
+  metadata.gz: 631dc9e88f2e84a72e51c4f03843aedc1a187c18a410fc4c8b519800c24c5ab2
+  data.tar.gz: 3f006856e51702d2483598b94647e63f00fd9989d67851e6bf31dcbc2497165f
 SHA512:
-  metadata.gz: bd8b8d0c01fdf4e9434cfe85218d6b772d839b263ae7c91f667fa2eb7aaedba48825bcace882028ed80b6cda8ff241c0fbae4764ca1cc067d3f320d95c5e81b8
-  data.tar.gz: 11ee7b651b2fa20e2f40935e674d190681159a2fecf716741ca6392fabde3b7ed2a3e1e1b29b86344215db58b80f9765ba98ea81ec93c3e31022e2859b96f7bc
+  metadata.gz: 6fe8f0822ea850a912a03eceec3e6cc7db6b4df52ce7734a67dc0bf242983720867b98dc63e37afce4ff6bd2daba600170a7eb1e90c85c97978b7e959fe7f70e
+  data.tar.gz: 9617c613888fd722b258d0d956bb0cd92dabbd9d4b4a1f1cb04a38aa37b69b2e7d2b0cc25fd306923f94cc9953aa36634171a7b7ecd95698d884118eb09c50ee

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,76 @@
 ## [Unreleased]
 
+## 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,26 @@ 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.
+
 ## API Documentation
 
 See the [YARD documentation](https://eval.github.io/appquery/) for the full API reference.
@@ -289,6 +317,9 @@ 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.

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/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.8.0"
 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,8 +152,7 @@ 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
 
   class Result < ActiveRecord::Result
@@ -147,8 +166,30 @@ module AppQuery
       @hash_rows = [] if columns.empty?
     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
@@ -453,6 +494,26 @@ module AppQuery
     end
     alias_method :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.
     #
     # @param n [Integer] the number of rows to return
@@ -471,6 +532,30 @@ 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)
+      with_select(s).select_all(
+        "SELECT * FROM :_ LIMIT #{n.to_i} OFFSET GREATEST((SELECT COUNT(*) FROM :_) - #{n.to_i}, 0)",
+        binds:, cast:
+      ).entries
+    end
+
     # Executes the query and returns the first value of the first row.
     #
     # @param binds [Hash, nil] named bind parameters
@@ -568,8 +653,9 @@ module AppQuery
     #   AppQuery("SELECT * FROM products").column(:category, unique: true)
     #   # => ["Electronics", "Clothing", "Home"]
     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")
+      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 +667,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 +847,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 +1080,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 +1212,16 @@ 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
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.8.0.rc3
+  version: 0.8.0
 platform: ruby
 authors:
 - Gert Goet
@@ -52,6 +52,7 @@ files:
 - Appraisals
 - CHANGELOG.md
 - LICENSE.txt
+- Procfile.yard
 - README.md
 - Rakefile
 - assets/banner-dark.svg