appquery 0.4.0 → 0.6.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e96dbd6cf521caaee6d919ee3dd7fc796bb92f48ef3e135271b8b82408fb6bcc
-  data.tar.gz: 0c2250d2a62773ae26ff79469ea6b7e0a63ac246f2824518495a0f4f2ef2b13c
+  metadata.gz: 6f00b1819f60c555c6400c5843dd4682e27be590a967593eeaaabb3cca267789
+  data.tar.gz: 9539d6caab140091640ffc7174745921a296005d58bc545c99c7492cdb1356be
 SHA512:
-  metadata.gz: 14e0146910530087f2c56478e5c507a74ad9b6ccfea81a5c52e46fe24c07f4ef232db86056e1b97c7b7ed9ac976543b8e9c0ac4fcfcc90805aa9d668b426e061
-  data.tar.gz: 21e8afa59badf98018ba334960b3a6f301511a84305ea4941627f9d9dce3a1b24a23e52201c2a14f0a8912efbdaf9da1742b010acc364ceb72560a7910cab8e2
+  metadata.gz: fc7edf38ce15320b3bb58acc67460f7431e44f521be1b2a7dec6bd57cadbe8ba3c7c3570f8125bed6429e44a2e7c5f48ffbc64402f8bb5c00a2d6654d9350796
+  data.tar.gz: 01b227941d0aa8065c7d787ee7af22a1f6251860473a5fb11130965fd073f1dfdffb4f0cb3ce1569fa4be80728982f6f122efd9d85766c9ca245f19b1bbb5925

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,128 @@
 ## [Unreleased]
 
+### ✨ Features
+
+- 🏗️ **`AppQuery::BaseQuery`** — structured query objects with explicit parameter declaration
+  ```ruby
+  class ArticlesQuery < AppQuery::BaseQuery
+    bind :author_id
+    bind :status, default: nil
+    var :order_by, default: "created_at DESC"
+    cast published_at: :datetime
+  end
+
+  ArticlesQuery.new(author_id: 1).entries
+  ArticlesQuery.new(author_id: 1, status: "draft").first
+  ```
+  Benefits over `AppQuery[:my_query]`:
+  - Explicit `bind` and `var` declarations with defaults
+  - Unknown parameter validation (catches typos)
+  - Self-documenting: `ArticlesQuery.binds`, `ArticlesQuery.vars`
+  - Middleware support via concerns
+
+- 📄 **`AppQuery::Paginatable`** — pagination middleware (Kaminari-compatible)
+  ```ruby
+  class ApplicationQuery < AppQuery::BaseQuery
+    include AppQuery::Paginatable
+    per_page 25
+  end
+
+  # With count (full pagination)
+  articles = ArticlesQuery.new.paginate(page: 1).entries
+  articles.total_pages  # => 5
+
+  # Without count (large datasets, uses limit+1 trick)
+  articles = ArticlesQuery.new.paginate(page: 1, without_count: true).entries
+  articles.next_page    # => 2 or nil
+  ```
+
+- 🗺️ **`AppQuery::Mappable`** — map results to Ruby objects
+  ```ruby
+  class ArticlesQuery < ApplicationQuery
+    include AppQuery::Mappable
+
+    class Item < Data.define(:title, :url, :published_on)
+    end
+  end
+
+  articles = ArticlesQuery.new.entries
+  articles.first.title  # => "Hello World"
+  articles.first.class  # => ArticlesQuery::Item
+
+  # Skip mapping
+  ArticlesQuery.new.raw.entries.first  # => {"title" => "Hello", ...}
+  ```
+
+- 🔄 **`Result#transform!`** — transform result records in-place
+  ```ruby
+  result = AppQuery[:users].select_all
+  result.transform! { |row| row.merge("full_name" => "#{row['first']} #{row['last']}") }
+  ```
+
+- Add `any?`, `none?` - efficient ways to see if there's any results for a query.
+- 🎯 **Cast type shorthands** — use symbols instead of explicit type classes
+  ```ruby
+  query.select_all(cast: {"published_on" => :date})
+  # instead of
+  query.select_all(cast: {"published_on" => ActiveRecord::Type::Date.new})
+  ```
+  Supports all ActiveRecord types including adapter-specific ones (`:uuid`, `:jsonb`, etc.).
+- 🔑 **Indifferent access** — for rows and cast keys
+  ```ruby
+  row = query.select_one
+  row["name"]  # works
+  row[:name]   # also works
+
+  # cast keys can be symbols too
+  query.select_all(cast: {published_on: :date})
+  ```  
+
+## [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: :json})
+
+# 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
@@ -96,7 +73,7 @@ The prompt indicates what adapter the example uses:
 
 ```ruby
 # showing select_(all|one|value)
-[postgresql]> AppQuery(%{select date('now') as today}).select_all.to_a
+[postgresql]> AppQuery(%{select date('now') as today}).select_all.entries
 => [{"today" => "2025-05-10"}]
 [postgresql]> AppQuery(%{select date('now') as today}).select_one
 => {"today" => "2025-05-10"}
@@ -104,21 +81,32 @@ 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.days.ago, ts2: Time.now, interval: '1 hour'}).column("series")
+    SELECT generate_series(
+      :ts1::timestamp,
+      :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_one
+=> {"today" => Sat, 10 May 2025}
+## compare ActiveRecord
+[postgresql]> ActiveRecord::Base.connection.select_one(%{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)
 => {"today" => "2025-05-12"}
 ## Providing per-column-casts fixes this:
-casts = {"today" => ActiveRecord::Type::Date.new}
-[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: casts)
+cast = {today: :date}
+[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast:)
 => {"today" => Mon, 12 May 2025}
 
 
@@ -128,16 +116,18 @@ casts = {"today" => ActiveRecord::Type::Date.new}
   [2, "Let's learn SQL", 1.month.ago.to_date],
   [3, "Another article", 2.weeks.ago.to_date]
 ]
-[postgresql]> q = AppQuery(<<~SQL, cast: {"published_on" => ActiveRecord::Type::Date.new}).render(articles:)
+[postgresql]> q = AppQuery(<<~SQL, cast: {published_on: :date}).render(articles:)
   WITH articles(id,title,published_on) AS (<%= values(articles) %>)
   select * from articles order by id DESC
 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::integer < 2}).entries
 
-## 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 +154,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 +164,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 +191,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 +238,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 +270,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)
+cast = {tags: :json}
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article", cast:)
 
-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 +287,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 +299,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 +322,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 +340,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/Rakefile

@@ -8,3 +8,13 @@ RSpec::Core::RakeTask.new(:spec)
 require "standard/rake"
 
 task default: %i[spec standard]
+
+# version.rb is written at CI which prevents guard_clean from passing.
+# Redefine guard_clean to make it a noop.
+if ENV["CI"]
+  Rake::Task["release:guard_clean"].clear
+  task "release:guard_clean"
+
+  Rake::Task["release:source_control_push"].clear
+  task "release:source_control_push"
+end

data/lib/app_query/base_query.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute" # class_attribute
+require "active_support/core_ext/module/delegation" # delegate
+
+module AppQuery
+  # Base class for query objects that wrap SQL files.
+  #
+  # BaseQuery provides a structured way to work with SQL queries compared to
+  # using `AppQuery[:my_query]` directly.
+  #
+  # ## Benefits over AppQuery[:my_query]
+  #
+  # ### 1. Explicit parameter declaration
+  # Declare required binds and vars upfront with defaults:
+  #
+  #   class ArticlesQuery < AppQuery::BaseQuery
+  #     bind :author_id              # required
+  #     bind :status, default: nil   # optional
+  #     var :order_by, default: "created_at DESC"
+  #   end
+  #
+  # ### 2. Unknown parameter validation
+  # Raises ArgumentError for typos or unknown parameters:
+  #
+  #   ArticlesQuery.new(athor_id: 1)  # => ArgumentError: Unknown param(s): athor_id
+  #
+  # ### 3. Self-documenting queries
+  # Query classes show exactly what parameters are available:
+  #
+  #   ArticlesQuery.binds  # => {author_id: {default: nil}, status: {default: nil}}
+  #   ArticlesQuery.vars   # => {order_by: {default: "created_at DESC"}}
+  #
+  # ### 4. Middleware support
+  # Include concerns to add functionality:
+  #
+  #   class ApplicationQuery < AppQuery::BaseQuery
+  #     include AppQuery::Paginatable
+  #     include AppQuery::Mappable
+  #   end
+  #
+  # ### 5. Casts
+  # Define casts for columns:
+  #
+  #   class ApplicationQuery < AppQuery::BaseQuery
+  #     cast metadata: :json
+  #   end
+  #
+  # ## Parameter types
+  #
+  # - **bind**: SQL bind parameters (safe from injection, used in WHERE clauses)
+  # - **var**: ERB template variables (for dynamic SQL generation like ORDER BY)
+  #
+  # ## Naming convention
+  #
+  # Query class name maps to SQL file:
+  # - `ArticlesQuery` -> `articles.sql.erb`
+  # - `Reports::MonthlyQuery` -> `reports/monthly.sql.erb`
+  #
+  # ## Example
+  #
+  #   # app/queries/articles.sql.erb
+  #   SELECT * FROM articles
+  #   WHERE author_id = :author_id
+  #   <% if @status %>AND status = :status<% end %>
+  #   ORDER BY <%= @order_by %>
+  #
+  #   # app/queries/articles_query.rb
+  #   class ArticlesQuery < AppQuery::BaseQuery
+  #     bind :author_id
+  #     bind :status, default: nil
+  #     var :order_by, default: "created_at DESC"
+  #     cast published_at: :datetime
+  #   end
+  #
+  #   # Usage
+  #   ArticlesQuery.new(author_id: 1).entries
+  #   ArticlesQuery.new(author_id: 1, status: "draft", order_by: "title").first
+  #
+  class BaseQuery
+    class_attribute :_binds, default: {}
+    class_attribute :_vars, default: {}
+    class_attribute :_casts, default: {}
+
+    class << self
+      # Declares a bind parameter for the query.
+      #
+      # Bind parameters are passed to the database driver and are safe from
+      # SQL injection. Use for values in WHERE, HAVING, etc.
+      #
+      # @param name [Symbol] parameter name (used as :name in SQL)
+      # @param default [Object, Proc] default value (Proc is evaluated at instantiation)
+      #
+      # @example
+      #   bind :user_id
+      #   bind :status, default: "active"
+      #   bind :since, default: -> { 1.week.ago }
+      def bind(name, default: nil)
+        self._binds = _binds.merge(name => {default:})
+        attr_reader name
+      end
+
+      # Declares a template variable for the query.
+      #
+      # Vars are available in ERB as both local variables and instance variables
+      # (@var). Use for dynamic SQL generation (ORDER BY, column selection, etc.)
+      #
+      # @param name [Symbol] variable name
+      # @param default [Object, Proc] default value (Proc is evaluated at instantiation)
+      #
+      # @example
+      #   var :order_by, default: "created_at DESC"
+      #   var :columns, default: "*"
+      def var(name, default: nil)
+        self._vars = _vars.merge(name => {default:})
+        attr_reader name
+      end
+
+      # Sets type casting for result columns.
+      #
+      # @param casts [Hash{Symbol => Symbol}] column name to type mapping
+      # @return [Hash] current cast configuration when called without arguments
+      #
+      # @example
+      #   cast published_at: :datetime, metadata: :json
+      def cast(casts = nil)
+        return _casts if casts.nil?
+        self._casts = casts
+      end
+
+      # @return [Hash] declared bind parameters with their options
+      def binds = _binds
+
+      # @return [Hash] declared template variables with their options
+      def vars = _vars
+    end
+
+    def initialize(**params)
+      all_known = self.class.binds.keys + self.class.vars.keys
+      unknown = params.keys - all_known
+      raise ArgumentError, "Unknown param(s): #{unknown.join(", ")}" if unknown.any?
+
+      self.class.binds.merge(self.class.vars).each do |name, options|
+        value = params.fetch(name) {
+          default = options[:default]
+          default.is_a?(Proc) ? instance_exec(&default) : default
+        }
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
+
+    delegate :select_all, :select_one, :count, :to_s, :column, :first, :ids, to: :query
+
+    def entries
+      select_all
+    end
+
+    def query
+      @query ||= base_query
+        .render(**render_vars)
+        .with_binds(**bind_vars)
+    end
+
+    def base_query
+      AppQuery[query_name, cast: self.class.cast]
+    end
+
+    private
+
+    def query_name
+      self.class.name.underscore.sub(/_query$/, "")
+    end
+
+    def render_vars
+      self.class.vars.keys.to_h { [_1, send(_1)] }
+    end
+
+    def bind_vars
+      self.class.binds.keys.to_h { [_1, send(_1)] }
+    end
+  end
+end