appquery 0.5.0 → 0.6.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ca8349f2df1ddf7e2248314238dd72ff5623d2924f1265f385cb1dfde8b274d
-  data.tar.gz: 12440ed32a10ca28acd01df89175906e2ed2f77105905ed44f905bc54def4c5d
+  metadata.gz: 6f00b1819f60c555c6400c5843dd4682e27be590a967593eeaaabb3cca267789
+  data.tar.gz: 9539d6caab140091640ffc7174745921a296005d58bc545c99c7492cdb1356be
 SHA512:
-  metadata.gz: 8154cfbf83c7327cc6bdfbe501430007fb4ed9a5ecfb65f6d751358e3721ca853b9d4655968955147fa2e3aa4ea898db9f71bd3da19647e4e550d2887121daab
-  data.tar.gz: a51fc511fa7b5da2bf03c4d63910abb1bb980b95fc300bf188a8749e726e965d781d14d28ffa3240dbca515c7d2bb0f5e83041eae61bb6ea7e815a1f7a13d19f
+  metadata.gz: fc7edf38ce15320b3bb58acc67460f7431e44f521be1b2a7dec6bd57cadbe8ba3c7c3570f8125bed6429e44a2e7c5f48ffbc64402f8bb5c00a2d6654d9350796
+  data.tar.gz: 01b227941d0aa8065c7d787ee7af22a1f6251860473a5fb11130965fd073f1dfdffb4f0cb3ce1569fa4be80728982f6f122efd9d85766c9ca245f19b1bbb5925

data/CHANGELOG.md

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

data/README.md

@@ -27,7 +27,7 @@ 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})
+AppQuery("SELECT metadata FROM products").select_all(cast: {metadata: :json})
 
 # Inspect/mock CTEs for testing
 query.prepend_cte("sales AS (SELECT * FROM mock_data)")
@@ -73,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"}
@@ -85,26 +85,28 @@ The prompt indicates what adapter the example uses:
 [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
+[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
 ## Cast values are used by default:
-[postgresql]> AppQuery(%{select date('now')}).select_first
+[postgresql]> AppQuery(%{select date('now')}).select_one
 => {"today" => Sat, 10 May 2025}
 ## compare ActiveRecord
-[postgresql]> ActiveRecord::Base.connection.select_first(%{select date('now') as today})
+[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}
 
 
@@ -114,13 +116,13 @@ 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 * from articles where id < 2}).to_a
+[postgresql]> q.select_all(%{select * from articles where id::integer < 2}).entries
 
 ## query the end-result (available via the placeholder ':_')
 [postgresql]> q.select_one(%{select * from :_ limit 1})
@@ -273,8 +275,8 @@ AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article")
       ...]
 
 # 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 * FROM tags_by_article", cast: types)
+cast = {tags: :json}
+AppQuery[:recent_articles].select_all("SELECT * FROM tags_by_article", cast:)
 
 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)

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

data/lib/app_query/mappable.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module AppQuery
+  # Maps query results to Ruby objects (e.g., Data classes, Structs).
+  #
+  # By default, looks for an `Item` constant in the query class.
+  # Use `map_to` to specify a different class.
+  #
+  # @example With default Item class
+  #   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"
+  #
+  # @example With explicit map_to
+  #   class ArticlesQuery < ApplicationQuery
+  #     include AppQuery::Mappable
+  #     map_to :article
+  #
+  #     class Article < Data.define(:title, :url)
+  #     end
+  #   end
+  #
+  # @example Skip mapping with raw
+  #   articles = ArticlesQuery.new.raw.entries
+  #   articles.first  # => {"title" => "Hello", "url" => "..."}
+  module Mappable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def map_to(name = nil)
+        name ? @map_to = name : @map_to
+      end
+    end
+
+    def raw
+      @raw = true
+      self
+    end
+
+    def select_all
+      map_result(super)
+    end
+
+    def select_one
+      map_one(super)
+    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))
+    end
+
+    def resolve_map_klass
+      case (name = self.class.map_to)
+      when Symbol
+        self.class.const_get(name.to_s.classify)
+      when Class
+        name
+      when nil
+        self.class.const_get(:Item) if self.class.const_defined?(:Item)
+      end
+    end
+  end
+end

data/lib/app_query/paginatable.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module AppQuery
+  # Adds pagination support to query classes.
+  #
+  # Provides two modes:
+  # - **With count**: Full pagination with page numbers (uses COUNT query)
+  # - **Without count**: Simple prev/next for large datasets (uses limit+1 trick)
+  #
+  # Compatible with Kaminari view helpers.
+  #
+  # @example Basic usage
+  #   class ApplicationQuery < AppQuery::BaseQuery
+  #     include AppQuery::Paginatable
+  #     per_page 50
+  #   end
+  #
+  #   class ArticlesQuery < ApplicationQuery
+  #     per_page 10
+  #   end
+  #
+  #   # With count (full pagination)
+  #   articles = ArticlesQuery.new.paginate(page: 1).entries
+  #   articles.total_pages  # => 5
+  #   articles.current_page # => 1
+  #
+  #   # Without count (large datasets)
+  #   articles = ArticlesQuery.new.paginate(page: 1, without_count: true).entries
+  #   articles.next_page    # => 2 (or nil if last page)
+  module Paginatable
+    extend ActiveSupport::Concern
+
+    # Kaminari-compatible wrapper for paginated results.
+    class PaginatedResult
+      include Enumerable
+
+      delegate :each, :size, :[], :empty?, :first, :last, to: :@records
+
+      def initialize(records, page:, per_page:, total_count: nil, has_next: nil)
+        @records = records
+        @page = page
+        @per_page = per_page
+        @total_count = total_count
+        @has_next = has_next
+      end
+
+      def current_page = @page
+
+      def limit_value = @per_page
+
+      def prev_page = (@page > 1) ? @page - 1 : nil
+
+      def first_page? = @page == 1
+
+      def total_count
+        @total_count || raise("total_count not available in without_count mode")
+      end
+
+      def total_pages
+        return nil unless @total_count
+        (@total_count.to_f / @per_page).ceil
+      end
+
+      def next_page
+        if @total_count
+          (@page < total_pages) ? @page + 1 : nil
+        else
+          @has_next ? @page + 1 : nil
+        end
+      end
+
+      def last_page?
+        if @total_count
+          @page >= total_pages
+        else
+          !@has_next
+        end
+      end
+
+      def out_of_range?
+        empty? && @page > 1
+      end
+
+      def transform!
+        @records = @records.map { |r| yield(r) }
+        self
+      end
+    end
+
+    included do
+      var :page, default: nil
+      var :per_page, default: -> { self.class.per_page }
+    end
+
+    class_methods do
+      def per_page(value = nil)
+        if value.nil?
+          return @per_page if defined?(@per_page)
+          superclass.respond_to?(:per_page) ? superclass.per_page : 25
+        else
+          @per_page = value
+        end
+      end
+    end
+
+    def paginate(page: 1, per_page: self.class.per_page, without_count: false)
+      @page = page
+      @per_page = per_page
+      @without_count = without_count
+      self
+    end
+
+    def entries
+      @_entries ||= build_paginated_result(super)
+    end
+
+    def total_count
+      @_total_count ||= unpaginated_query.count
+    end
+
+    def unpaginated_query
+      base_query
+        .render(**render_vars.except(:page, :per_page))
+        .with_binds(**bind_vars)
+    end
+
+    private
+
+    def build_paginated_result(entries)
+      return entries unless @page # No pagination requested
+
+      if @without_count
+        has_next = entries.size > @per_page
+        records = has_next ? entries.first(@per_page) : entries
+        PaginatedResult.new(records, page: @page, per_page: @per_page, has_next: has_next)
+      else
+        PaginatedResult.new(entries, page: @page, per_page: @per_page, total_count: total_count)
+      end
+    end
+
+    def render_vars
+      vars = super
+      # Fetch one extra row in without_count mode to detect if there's more
+      if @without_count && vars[:per_page]
+        vars = vars.merge(per_page: vars[:per_page] + 1)
+      end
+      vars
+    end
+  end
+end

data/lib/app_query/version.rb

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

data/lib/app_query.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "app_query/version"
+require_relative "app_query/base_query"
+require_relative "app_query/paginatable"
+require_relative "app_query/mappable"
 require_relative "app_query/tokenizer"
 require_relative "app_query/render_helpers"
 require "active_record"
@@ -22,7 +25,7 @@ require "active_record"
 #   end
 #
 # @example CTE manipulation
-#   AppQuery(<<~SQL).select_all(select: "select * from articles where id = 1")
+#   AppQuery(<<~SQL).select_all("select * from articles where id = 1")
 #     WITH articles AS(...)
 #     SELECT * FROM articles
 #     ORDER BY id
@@ -137,6 +140,48 @@ module AppQuery
       count
     end
 
+    private
+
+    # Override to provide indifferent access (string or symbol keys).
+    def hash_rows
+      @hash_rows ||= rows.map do |row|
+        columns.zip(row).to_h.with_indifferent_access
+      end
+    end
+
+    public
+
+    # Transforms each record in-place using the provided block.
+    #
+    # @yield [Hash] each record as a hash with indifferent access
+    # @yieldreturn [Hash] the transformed record
+    # @return [self] the result object for chaining
+    #
+    # @example Add a computed field
+    #   result = AppQuery[:users].select_all
+    #   result.transform! { |r| r.merge("full_name" => "#{r['first']} #{r['last']}") }
+    def transform!
+      @hash_rows = hash_rows.map { |r| yield(r) } unless empty?
+      self
+    end
+
+    # Resolves a cast type value, converting symbols to ActiveRecord types.
+    #
+    # @param value [Symbol, Object] the cast type (symbol shorthand or type instance)
+    # @return [Object] the resolved type instance
+    #
+    # @example
+    #   resolve_cast_type(:date)  #=> ActiveRecord::Type::Date instance
+    #   resolve_cast_type(ActiveRecord::Type::Json.new)  #=> returns as-is
+    def self.resolve_cast_type(value)
+      case value
+      when Symbol
+        ActiveRecord::Type.lookup(value)
+      else
+        value
+      end
+    end
+
     def self.from_ar_result(r, cast = nil)
       if r.empty?
         EMPTY
@@ -145,7 +190,7 @@ module AppQuery
         when Array
           r.columns.zip(cast).to_h
         when Hash
-          cast
+          cast.transform_keys(&:to_s).transform_values { |v| resolve_cast_type(v) }
         else
           {}
         end
@@ -342,16 +387,18 @@ module AppQuery
     # @example (Named) binds
     #   AppQuery("SELECT * FROM users WHERE id = :id").select_all(binds: {id: 1})
     #
-    # @example With type casting
-    #   AppQuery("SELECT created_at FROM users")
-    #     .select_all(cast: {created_at: ActiveRecord::Type::DateTime.new})
+    # @example With type casting (shorthand)
+    #   AppQuery("SELECT published_on FROM articles")
+    #     .select_all(cast: {"published_on" => :date})
+    #
+    # @example With type casting (explicit)
+    #   AppQuery("SELECT metadata FROM products")
+    #     .select_all(cast: {"metadata" => ActiveRecord::Type::Json.new})
     #
     # @example Override SELECT clause
-    #   AppQuery("SELECT * FROM users").select_all(select: "COUNT(*)")
+    #   AppQuery("SELECT * FROM users").select_all("COUNT(*)")
     #
     # @raise [UnrenderedQueryError] if the query contains unrendered ERB
-    #
-    # TODO: have aliases for common casts: select_all(cast: {"today" => :date})
     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
@@ -424,6 +471,41 @@ module AppQuery
       with_select(s).select_all("SELECT COUNT(*) c FROM :_", binds:).column("c").first
     end
 
+    # Returns whether any rows exist in the query result.
+    #
+    # Uses `EXISTS` which stops at the first matching row, making it more
+    # efficient than `count > 0` for large result sets.
+    #
+    # @param s [String, nil] optional SELECT to apply before checking
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Boolean] true if at least one row exists
+    #
+    # @example Check if query has results
+    #   AppQuery("SELECT * FROM users").any?
+    #   # => true
+    #
+    # @example Check with filtering
+    #   AppQuery("SELECT * FROM users").any?("SELECT * FROM :_ WHERE admin")
+    #   # => false
+    def any?(s = nil, binds: {})
+      with_select(s).select_all("SELECT EXISTS(SELECT 1 FROM :_) e", binds:).column("e").first
+    end
+
+    # Returns whether no rows exist in the query result.
+    #
+    # Inverse of {#any?}. Uses `EXISTS` for efficiency.
+    #
+    # @param s [String, nil] optional SELECT to apply before checking
+    # @param binds [Hash, nil] bind parameters to add
+    # @return [Boolean] true if no rows exist
+    #
+    # @example Check if query is empty
+    #   AppQuery("SELECT * FROM users WHERE admin").none?
+    #   # => true
+    def none?(s = nil, binds: {})
+      !any?(s, binds:)
+    end
+
     # Returns an array of values for a single column.
     #
     # Wraps the query in a CTE and selects only the specified column, which is

data/rakelib/gem.rake

@@ -1,25 +1,25 @@
 namespace :gem do
-  task "write_version", [:version] do |_task, args|
-    if args[:version]
-      version = args[:version].split("=").last
-      version_file = File.expand_path("../../lib/app_query/version.rb", __FILE__)
+  # task "write_version", [:version] do |_task, args|
+  #   if args[:version]
+  #     version = args[:version].split("=").last
+  #     version_file = File.expand_path("../../lib/app_query/version.rb", __FILE__)
+  #
+  #     system(<<~CMD, exception: true)
+  #       ruby -pi -e 'gsub(/VERSION = ".*"/, %{VERSION = "#{version}"})' #{version_file}
+  #     CMD
+  #     Bundler.ui.confirm "Version #{version} written to #{version_file}."
+  #   else
+  #     Bundler.ui.warn "No version provided, keeping version.rb as is."
+  #   end
+  # end
 
-      system(<<~CMD, exception: true)
-        ruby -pi -e 'gsub(/VERSION = ".*"/, %{VERSION = "#{version}"})' #{version_file}
-      CMD
-      Bundler.ui.confirm "Version #{version} written to #{version_file}."
-    else
-      Bundler.ui.warn "No version provided, keeping version.rb as is."
-    end
-  end
-
-  desc "Build [version]"
-  task "build", [:version] => %w[write_version] do
-    Rake::Task["build"].invoke
-  end
-
-  desc "Build and push [version] to rubygems"
-  task "release", [:version] => %w[build] do
-    Rake::Task["release:rubygem_push"].invoke
-  end
+  # desc "Build [version]"
+  # task "build", [:version] => %w[write_version] do
+  #   Rake::Task["build"].invoke
+  # end
+  #
+  # desc "Build and push [version] to rubygems"
+  # task "release", [:version] => %w[build] do
+  #   Rake::Task["release:rubygem_push"].invoke
+  # end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0.alpha
 platform: ruby
 authors:
 - Gert Goet
@@ -51,6 +51,9 @@ files:
 - Rakefile
 - lib/app_query.rb
 - lib/app_query/base.rb
+- lib/app_query/base_query.rb
+- lib/app_query/mappable.rb
+- lib/app_query/paginatable.rb
 - lib/app_query/render_helpers.rb
 - lib/app_query/rspec.rb
 - lib/app_query/rspec/helpers.rb
@@ -88,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.6.7
 specification_version: 4
 summary: "raw SQL \U0001F966, cooked \U0001F372 or: make working with raw SQL queries
   in Rails convenient by improving their introspection and testability."