appquery 0.1.0 → 0.3.0

data/lib/app_query.rb

@@ -1,8 +1,350 @@
 # frozen_string_literal: true
 
 require_relative "app_query/version"
+require_relative "app_query/tokenizer"
+require "active_record"
 
 module AppQuery
   class Error < StandardError; end
-  # Your code goes here...
+
+  class UnrenderedQueryError < StandardError; end
+
+  Configuration = Struct.new(:query_path)
+
+  def self.configuration
+    @configuration ||= AppQuery::Configuration.new
+  end
+
+  def self.configure
+    yield configuration if block_given?
+  end
+
+  def self.reset_configuration!
+    configure do |config|
+      config.query_path = "app/queries"
+    end
+  end
+  reset_configuration!
+
+  # Examples:
+  #   AppQuery[:invoices] # looks for invoices.sql
+  #   AppQuery["reports/weekly"]
+  #   AppQuery["invoices.sql.erb"]
+  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
+    Q.new(full_path.read, name: "AppQuery #{query_name}", filename: full_path.to_s, **opts)
+  end
+
+  class Result < ActiveRecord::Result
+    attr_accessor :cast
+    alias_method :cast?, :cast
+
+    def initialize(columns, rows, overrides = nil, cast: false)
+      super(columns, rows, overrides)
+      @cast = cast
+      # Rails v6.1: prevent mutate on frozen object on #first
+      @hash_rows = [] if columns.empty?
+    end
+
+    def column(name = nil)
+      return [] if empty?
+      unless name.nil? || includes_column?(name)
+        raise ArgumentError, "Unknown column #{name.inspect}. Should be one of #{columns.inspect}."
+      end
+      ix = name.nil? ? 0 : columns.index(name)
+      rows.map { _1[ix] }
+    end
+
+    def size
+      count
+    end
+
+    def self.from_ar_result(r, cast = nil)
+      if r.empty?
+        EMPTY
+      else
+        cast &&= case cast
+        when Array
+          r.columns.zip(cast).to_h
+        when Hash
+          cast
+        else
+          {}
+        end
+        if !cast || (cast.empty? && r.column_types.empty?)
+          # nothing to cast
+          new(r.columns, r.rows, r.column_types)
+        else
+          overrides = (r.column_types || {}).merge(cast)
+          rows = r.cast_values(overrides)
+          # One column is special :( ;(
+          # > ActiveRecord::Base.connection.select_all("select array[1,2]").rows
+          # => [["{1,2}"]]
+          # > ActiveRecord::Base.connection.select_all("select array[1,2]").cast_values
+          # => [[1, 2]]
+          rows = rows.zip if r.columns.one?
+          new(r.columns, rows, overrides, cast: true)
+        end
+      end
+    end
+
+    empty_array = [].freeze
+    EMPTY_HASH = {}.freeze
+    private_constant :EMPTY_HASH
+
+    EMPTY = new(empty_array, empty_array, EMPTY_HASH).freeze
+    private_constant :EMPTY
+  end
+
+  class Q
+    attr_reader :name, :sql, :binds, :cast
+
+    def initialize(sql, name: nil, filename: nil, binds: [], cast: true)
+      @sql = sql
+      @name = name
+      @filename = filename
+      @binds = binds
+      @cast = cast
+    end
+
+    def deep_dup
+      super.send(:reset!)
+    end
+
+    def reset!
+      (instance_variables - %i[@sql @filename @name @binds @cast]).each do
+        instance_variable_set(_1, nil)
+      end
+      self
+    end
+    private :reset!
+
+    def render(vars)
+      vars ||= {}
+      with_sql(to_erb.result(render_helper(vars).get_binding))
+    end
+
+    def to_erb
+      ERB.new(sql, trim_mode: "-").tap { _1.location = [@filename, 0] if @filename }
+    end
+    private :to_erb
+
+    def render_helper(vars)
+      Module.new do
+        extend self
+
+        vars.each do |k, v|
+          define_method(k) { v }
+          instance_variable_set(:"@#{k}", v)
+        end
+
+        # Examples
+        #   <%= order_by({year: :desc, month: :desc}) %>
+        #   #=> ORDER BY year DESC, month DESC
+        #
+        # Using variable:
+        #   <%= order_by(ordering) %>
+        # NOTE Raises when ordering not provided or when blank.
+        #
+        # Make it optional:
+        #   <%= @ordering.presence && order_by(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(", ")
+        end
+
+        def get_binding
+          binding
+        end
+      end
+    end
+    private :render_helper
+
+    def select_all(binds: [], select: nil, cast: self.cast)
+      binds = binds.presence || @binds
+      with_select(select).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.select_all(sql, name).then do |result|
+            Result.from_ar_result(result, cast)
+          end
+        else
+          ActiveRecord::Base.connection.select_all(aq.to_s, name, binds).then do |result|
+            Result.from_ar_result(result, cast)
+          end
+        end
+      end
+    rescue NameError => e
+      # Prevent any subclasses, e.g. NoMethodError
+      raise e unless e.instance_of?(NameError)
+      raise UnrenderedQueryError, "Query is ERB. Use #render before select-ing."
+    end
+
+    def select_one(binds: [], select: nil, cast: self.cast)
+      select_all(binds:, select:, cast:).first
+    end
+
+    def select_value(binds: [], select: nil, cast: self.cast)
+      select_one(binds:, select:, cast:)&.values&.first
+    end
+
+    def tokens
+      @tokens ||= tokenizer.run
+    end
+
+    def tokenizer
+      @tokenizer ||= Tokenizer.new(to_s)
+    end
+
+    def cte_names
+      tokens.filter { _1[:t] == "CTE_IDENTIFIER" }.map { _1[:v] }
+    end
+
+    def with_binds(binds)
+      deep_dup.tap do
+        _1.instance_variable_set(:@binds, binds)
+      end
+    end
+
+    def with_cast(cast)
+      deep_dup.tap do
+        _1.instance_variable_set(:@cast, cast)
+      end
+    end
+
+    def with_sql(sql)
+      deep_dup.tap do
+        _1.instance_variable_set(:@sql, sql)
+      end
+    end
+
+    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]
+          acc << v
+        end.join)
+      else
+        append_cte("_ as (\n  #{select}\n)").with_select(sql)
+      end
+    end
+
+    def select
+      tokens.find { _1[:t] == "SELECT" }&.[](:v)
+    end
+
+    def recursive?
+      !!tokens.find { _1[:t] == "RECURSIVE" }
+    end
+
+    # example:
+    #  AppQuery("select 1").prepend_cte("foo as(select 1)")
+    def prepend_cte(cte)
+      # early raise when cte is not valid sql
+      to_append = Tokenizer.tokenize(cte, state: :lex_prepend_cte).then do |tokens|
+        recursive? ? tokens.reject { _1[:t] == "RECURSIVE" } : tokens
+      end
+
+      if cte_names.none?
+        with_sql("WITH #{cte}\n#{self}")
+      else
+        split_at_type = recursive? ? "RECURSIVE" : "WITH"
+        with_sql(tokens.map do |token|
+          if token[:t] == split_at_type
+            token[:v] + to_append.map { _1[:v] }.join
+          else
+            token[:v]
+          end
+        end.join)
+      end
+    end
+
+    # example:
+    #  AppQuery("select 1").append_cte("foo as(select 1)")
+    def append_cte(cte)
+      # early raise when cte is not valid sql
+      add_recursive, to_append = Tokenizer.tokenize(cte, state: :lex_append_cte).then do |tokens|
+        [!recursive? && tokens.find { _1[:t] == "RECURSIVE" },
+          tokens.reject { _1[:t] == "RECURSIVE" }]
+      end
+
+      if cte_names.none?
+        with_sql("WITH #{cte}\n#{self}")
+      else
+        nof_ctes = cte_names.size
+
+        with_sql(tokens.map do |token|
+          nof_ctes -= 1 if token[:t] == "CTE_SELECT"
+
+          if nof_ctes.zero?
+            nof_ctes -= 1
+            token[:v] + to_append.map { _1[:v] }.join
+          elsif token[:t] == "WITH" && add_recursive
+            token[:v] + add_recursive[:v]
+          else
+            token[:v]
+          end
+        end.join)
+      end
+    end
+
+    # Replaces an existing cte.
+    # Raises `ArgumentError` when cte does not exist.
+    def replace_cte(cte)
+      add_recursive, to_append = Tokenizer.tokenize(cte, state: :lex_recursive_cte).then do |tokens|
+        [!recursive? && tokens.find { _1[:t] == "RECURSIVE" },
+          tokens.reject { _1[:t] == "RECURSIVE" }]
+      end
+
+      cte_name = to_append.find { _1[:t] == "CTE_IDENTIFIER" }&.[](:v)
+      unless cte_names.include?(cte_name)
+        raise ArgumentError, "Unknown cte #{cte_name.inspect}. Options: #{cte_names}."
+      end
+      cte_ix = cte_names.index(cte_name)
+
+      return self unless cte_ix
+
+      cte_found = false
+
+      with_sql(tokens.map do |token|
+        if cte_found ||= token[:t] == "CTE_IDENTIFIER" && token[:v] == cte_name
+          unless (cte_found = (token[:t] != "CTE_SELECT"))
+            next to_append.map { _1[:v] }.join
+          end
+
+          next
+        elsif token[:t] == "WITH" && add_recursive
+          token[:v] + add_recursive[:v]
+        else
+          token[:v]
+        end
+      end.join)
+    end
+
+    def to_s
+      @sql
+    end
+  end
 end
+
+def AppQuery(...)
+  AppQuery::Q.new(...)
+end
+
+begin
+  require "rspec"
+rescue LoadError
+end
+
+require_relative "app_query/rspec" if Object.const_defined? :RSpec
+
+require "app_query/base" if defined?(ActiveRecord::Base)

data/lib/appquery.rb

@@ -0,0 +1 @@
+require "app_query"

data/lib/rails/generators/query/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates a new query-file and invokes your template
+    engine and test framework generators.
+
+Example:
+    `bin/rails generate query reports/weekly`
+
+    creates an SQL file and test:
+        Query:  app/queries/reports/weekly.sql
+        Spec:   spec/queries/reports/weekly_query_spec.rb

data/lib/rails/generators/query/query_generator.rb

@@ -0,0 +1,20 @@
+module Rails
+  module Generators
+    class QueryGenerator < NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_query_file
+        template "query.sql",
+          File.join(AppQuery.configuration.query_path, class_path, "#{file_name}.sql")
+
+        # in_root do
+        #  if behavior == :invoke && !File.exist?(application_mailbox_file_name)
+        #    template "application_mailbox.rb", application_mailbox_file_name
+        #  end
+        # end
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/rails/generators/query/templates/query.sql.tt

@@ -0,0 +1,14 @@
+-- Instantiate this query with AppQuery[<%= (class_path << file_name).join("/").inspect %>]
+
+WITH
+  articles(article_id, article_title) AS (
+    VALUES (1, 'Some title'),
+           (2, 'Another article')
+  ),
+  authors(author_id, author_name) AS (
+    VALUES (1, 'Some Author'),
+           (2, 'Another Author')
+  )
+
+SELECT *
+FROM artciles

data/lib/rails/generators/rspec/query_generator.rb

@@ -0,0 +1,20 @@
+module Rspec
+  module Generators
+    class QueryGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_test_file
+        template "query_spec.rb",
+          File.join("spec/queries", class_path, "#{file_name}_query_spec.rb")
+      end
+
+      hide!
+
+      private
+
+      def query_path
+        AppQuery.configuration.query_path
+      end
+    end
+  end
+end

data/lib/rails/generators/rspec/templates/query_spec.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "AppQuery <%= (class_path << file_name).join("/") %>", type: :query, default_binds: nil do
+  describe "CTE articles" do
+    specify do
+      expect(select_all(select: "select * from :cte").cast_entries).to \
+        include(a_hash_including("article_id" => 1))
+    end
+  end
+end

data/mise.local.toml.example

@@ -0,0 +1,5 @@
+[env]
+# used for tests
+PG_DATABASE_URL="postgres://localhost:5432/some_db
+# used from console
+DATABASE_URL="postgres://localhost:5432/some_db

data/mise.toml

@@ -0,0 +1,6 @@
+[tools]
+ruby = "3.4"
+
+[env]
+_.path = ["bin"]
+PROJECT_ROOT = "{{config_root}}"

data/sig/appquery.rbs

@@ -1,4 +1,4 @@
-module Appquery
+module AppQuery
   VERSION: String
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end

metadata

@@ -1,40 +1,66 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gert Goet
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-14 00:00:00.000000000 Z
-dependencies: []
-description: |
-  A query like `AppQuery[:some_query]` is read from app/queries/some_query.sql.
-
-  Querying a CTE used in this query:
-  `query.replace_select("select * from some_cte").select_all`
-
-  Query the end-result:
-  `query.as_cte(select: "select COUNT(*) from app_query").select_all`
-
-  Spec-helpers and generators included.
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "Improving introspection and testability of raw SQL queries in Rails\nThis
+  gem improves introspection and testability of raw SQL queries in Rails by:\n- ...providing
+  a separate query-folder and easy instantiation  \n  A query like `AppQuery[:some_query]`
+  is read from app/queries/some_query.sql.\n\n- ...providing options for rewriting
+  a query:\n\n  Query a CTE by replacing the select:\n  query.select_all(select: \"select
+  * from some_cte\").entries\n\n  ...similarly, query the end result (i.e. CTE `_`):\n
+  \ query.select_all(select: \"select count(*) from _\").entries\n\n- ...providing
+  (custom) casting:  \n  AppQuery(\"select array[1,2]\").select_value(cast: true)\n\n
+  \ custom deserializers:\n  AppQuery(\"select '1' id\").select_all(cast: {\"id\"
+  => ActiveRecord::Type::Integer.new}).entries\n\n- ...providing spec-helpers and
+  generators\n"
 email:
 - gert@thinkcreate.dk
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".envrc"
 - ".rspec"
 - ".standard.yml"
+- Appraisals
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/app_query.rb
+- lib/app_query/base.rb
+- lib/app_query/rspec.rb
+- lib/app_query/rspec/helpers.rb
+- lib/app_query/tokenizer.rb
 - lib/app_query/version.rb
+- lib/appquery.rb
+- lib/rails/generators/query/USAGE
+- lib/rails/generators/query/query_generator.rb
+- lib/rails/generators/query/templates/query.sql.tt
+- lib/rails/generators/rspec/query_generator.rb
+- lib/rails/generators/rspec/templates/query_spec.rb.tt
+- mise.local.toml.example
+- mise.toml
 - sig/appquery.rbs
 homepage: https://github.com/eval/appquery
 licenses:
@@ -43,7 +69,6 @@ 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
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -51,16 +76,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
-summary: Make working with raw SQL queries convenient by improving their introspection
-  and testability.
+summary: "raw SQL \U0001F966, cooked \U0001F372 or: make working with raw SQL queries
+  in Rails convenient by improving their introspection and testability."
 test_files: []

data/.envrc

@@ -1 +0,0 @@
-PATH_add bin