appquery 0.4.0 → 0.6.0.alpha

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/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.6.0.alpha"
 end