inquery 1.0.11 → 1.1.0

data/lib/inquery/query/chainable.rb

@@ -1,25 +1,66 @@
 module Inquery
+  # Chainable query class for queries that input and output ActiveRecord relations.
+  #
+  # Use this class when you want to build queries that can be chained together
+  # or used as ActiveRecord scopes. The query receives a relation, transforms
+  # it, and returns a new relation.
+  #
+  # Example:
+  #   class FetchActive < Inquery::Query::Chainable
+  #     relation class: 'User'
+  #
+  #     def call
+  #       relation.where(active: true)
+  #     end
+  #   end
+  #
+  #   User.all.then { |rel| FetchActive.run(rel) }
+  #   # Or as a scope:
+  #   class User < ActiveRecord::Base
+  #     scope :active, FetchActive
+  #   end
   class Query::Chainable < Query
     include Inquery::Mixins::RelationValidation
 
-    # Allows using this class as an AR scope.
+    # Instantiates the query and executes it, allowing use as an AR scope.
+    #
+    # This enables chainable queries to be used directly as ActiveRecord scopes:
+    #   scope :active, FetchActive
+    #
+    # @param args [Array] Arguments passed to initialize (relation and/or params)
+    # @return [ActiveRecord::Relation] The transformed relation
     def self.call(*args)
       return new(*args).call
     end
 
-    def call(*args)
-      fail args.inspect
-    end
-
+    # The input ActiveRecord relation that will be transformed by this query.
+    #
+    # @return [ActiveRecord::Relation]
     attr_reader :relation
 
+    # Initializes a chainable query with a relation and optional parameters.
+    #
+    # Supports multiple call signatures:
+    #   new()                    - Uses default relation from 'relation' DSL
+    #   new(relation)            - Uses provided relation
+    #   new(params)              - Uses default relation with params
+    #   new(relation, params)    - Uses provided relation and params
+    #
+    # @param args [Array] Variable arguments for relation and/or params
+    # @raise [Inquery::Exceptions::UnknownCallSignature] for invalid arguments
+    # @raise [Inquery::Exceptions::InvalidRelation] if relation validation fails
     def initialize(*args)
       relation, params = parse_init_args(*args)
       @relation = validate_relation!(relation)
       super(params)
     end
 
-    # Override the connection method to (re-)use the connection of the relation
+    # Returns the database connection from the relation.
+    #
+    # This ensures that the query uses the same connection as the input
+    # relation, which is important for connection pooling and transactions.
+    #
+    # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
     def connection
       @relation.connection
     end
@@ -27,32 +68,33 @@ module Inquery
     private
 
     def parse_init_args(*args)
-      # new(relation)
-      if (args[0].is_a?(ActiveRecord::Relation) || args[0].class < ActiveRecord::Base) && args[1].nil?
-        relation = args[0]
-        params = {}
+      first_arg = args[0]
+      second_arg = args[1]
+
+      # new() - no arguments
+      return [nil, {}] if args.empty?
 
-      # new(params)
-      elsif args[0].is_a?(Hash) && args[1].nil?
-        relation = nil
-        params = args[0]
+      # new(relation) or new(params)
+      if second_arg.nil?
+        if relation_like?(first_arg)
+          return [first_arg, {}]
+        elsif first_arg.is_a?(Hash)
+          return [nil, first_arg]
+        end
+      end
 
       # new(relation, params)
-      elsif (args[0].is_a?(ActiveRecord::Relation) || args[0].class < ActiveRecord::Base) && args[1].is_a?(Hash)
-        relation = args[0]
-        params = args[1]
-
-      # new()
-      elsif args.empty?
-        relation = nil
-        params = {}
-
-      # Unknown
-      else
-        fail Inquery::Exceptions::UnknownCallSignature, "Unknown call signature for the query constructor: #{args.collect(&:class)}."
+      if relation_like?(first_arg) && second_arg.is_a?(Hash)
+        return [first_arg, second_arg]
       end
 
-      return relation, params
+      # Unknown signature
+      fail Inquery::Exceptions::UnknownCallSignature,
+           "Unknown call signature for the query constructor: #{args.collect(&:class)}."
+    end
+
+    def relation_like?(obj)
+      obj.is_a?(ActiveRecord::Relation) || (obj.class < ActiveRecord::Base)
     end
   end
 end

data/lib/inquery/query.rb

@@ -1,24 +1,54 @@
 module Inquery
+  # Base query class that encapsulates database queries in reusable classes.
+  #
+  # Subclasses must implement the 'call' method to define the query logic.
+  # Optionally, override 'process' to transform the query results.
+  #
+  # Example:
+  #   class FetchActiveUsers < Inquery::Query
+  #     def call
+  #       User.where(active: true)
+  #     end
+  #   end
+  #
+  #   FetchActiveUsers.run # => Returns active users
   class Query
     include Mixins::SchemaValidation
     include Mixins::RawSqlUtils
 
     attr_reader :params
 
-    # Instantiates the query class using the given arguments
-    # and runs `call` and `process` on it.
+    # Instantiates the query class with the given params and executes both
+    # 'call' and 'process' methods.
+    #
+    # This is the primary way to execute queries. It runs the query logic
+    # defined in 'call' and then passes the results through 'process' for
+    # any post-processing.
+    #
+    # @param args [Hash] Parameters to pass to the query
+    # @return [Object] The processed query results
+    # @raise [Schemacop::Exceptions::ValidationError] if params don't match schema
     def self.run(*args)
       new(*args).run
     end
 
-    # Instantiates the query class using the given arguments
-    # and runs `call` on it.
+    # Instantiates the query class with the given params and executes only
+    # the 'call' method, skipping post-processing.
+    #
+    # @param args [Hash] Parameters to pass to the query
+    # @return [Object] The raw query results
+    # @raise [Schemacop::Exceptions::ValidationError] if params don't match schema
     def self.call(*args)
       new(*args).call
     end
 
-    # Instantiates the query class and validates the given params hash (if there
-    # was a validation schema specified).
+    # Initializes a new query instance with the given parameters.
+    #
+    # If a schema is defined using 'schema' or 'schema3', the params will be
+    # validated against it before the query is executed.
+    #
+    # @param params [Hash] Parameters for the query
+    # @raise [Schemacop::Exceptions::ValidationError] if params don't match schema
     def initialize(params = {})
       @params = params
 
@@ -27,29 +57,52 @@ module Inquery
       end
     end
 
-    # Runs both `call` and `process`.
+    # Executes the query by calling 'call' and then 'process'.
+    #
+    # @return [Object] The processed query results
     def run
       process(call)
     end
 
-    # Override this method to perform the actual query.
+    # Override this method in subclasses to define the query logic.
+    #
+    # @return [Object] Query results (typically an ActiveRecord::Relation)
+    # @raise [NotImplementedError] if not overridden in subclass
     def call
       fail NotImplementedError
     end
 
-    # Override this method to perform an optional result postprocessing.
+    # Override this method in subclasses to transform the query results.
+    #
+    # By default, returns the results unchanged. Common uses include
+    # converting to JSON, counting records, or extracting specific fields.
+    #
+    # @param results [Object] The results from the 'call' method
+    # @return [Object] The processed results
     def process(results)
       results
     end
 
-    # Returns a copy of the query's params, wrapped in an OpenStruct object for
-    # easyer access.
+    # Returns the query params wrapped in a MethodAccessibleHash for
+    # convenient access using dot notation.
+    #
+    # Example:
+    #   schema3 { str! :name }
+    #   def call
+    #     User.where(name: osparams.name) # Access via dot notation
+    #   end
+    #
+    # @return [MethodAccessibleHash] Params with method access
     def osparams
-      @osparams ||= OpenStruct.new(params)
+      @osparams ||= MethodAccessibleHash.new(params)
     end
 
-    # Provides a connection to the database. May be overridden if a different
-    # connection is desired. Defaults to `ActiveRecord::Base.connection`.
+    # Returns the database connection to use for this query.
+    #
+    # Override this method if you need to use a different connection than
+    # the default ActiveRecord connection.
+    #
+    # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
     def connection
       ActiveRecord::Base.connection
     end

data/lib/inquery.rb

@@ -9,9 +9,11 @@ module Inquery
 end
 
 require 'uri'
+require 'logger'
 require 'schemacop'
 
 require 'inquery/exceptions'
+require 'inquery/method_accessible_hash'
 require 'inquery/mixins/schema_validation'
 require 'inquery/mixins/relation_validation'
 require 'inquery/mixins/raw_sql_utils'

data/test/inquery/error_handling_test.rb

@@ -0,0 +1,117 @@
+require 'test_helper'
+
+module Inquery
+  class ErrorHandlingTest < Minitest::Test
+    include TestHelper
+
+    def setup
+      self.class.setup_db
+      self.class.setup_base_data
+    end
+
+    def test_query_without_call_method_raises_not_implemented_error
+      query_class = Class.new(Inquery::Query)
+
+      assert_raises(NotImplementedError) do
+        query_class.run
+      end
+    end
+
+    def test_chainable_query_without_call_method_raises_not_implemented_error
+      query_class = Class.new(Inquery::Query::Chainable) do
+        relation class: 'User'
+      end
+
+      assert_raises(NotImplementedError) do
+        query_class.run(User.all)
+      end
+    end
+
+    def test_invalid_relation_class_raises_error
+      assert_raises(NameError) do
+        Class.new(Inquery::Query::Chainable) do
+          relation class: 'NonExistentClass'
+
+          def call
+            relation
+          end
+        end.run
+      end
+    end
+
+    def test_invalid_relation_type_raises_error
+      query_class = Class.new(Inquery::Query::Chainable) do
+        relation class: 'User'
+
+        def call
+          relation
+        end
+      end
+
+      assert_raises(Inquery::Exceptions::UnknownCallSignature) do
+        query_class.run('not a relation')
+      end
+    end
+
+    def test_schema_validation_failure_with_missing_required_param
+      query_class = Class.new(Inquery::Query) do
+        schema3 do
+          str! :name
+          int! :age
+        end
+
+        def call
+          User.all
+        end
+      end
+
+      assert_raises(Schemacop::Exceptions::ValidationError) do
+        query_class.run(name: 'Alice')
+      end
+    end
+
+    def test_schema_validation_failure_with_wrong_type
+      query_class = Class.new(Inquery::Query) do
+        schema3 do
+          int! :age
+        end
+
+        def call
+          User.all
+        end
+      end
+
+      assert_raises(Schemacop::Exceptions::ValidationError) do
+        query_class.run(age: 'not a number')
+      end
+    end
+
+    def test_invalid_relation_field_count
+      query_class = Class.new(Inquery::Query::Chainable) do
+        relation fields: 1
+
+        def call
+          relation
+        end
+      end
+
+      # Passing a relation with more than 1 field should raise an error
+      assert_raises(Inquery::Exceptions::InvalidRelation) do
+        query_class.run(User.select(:id, :name))
+      end
+    end
+
+    def test_unknown_call_signature_raises_error
+      query_class = Class.new(Inquery::Query::Chainable) do
+        def call
+          relation
+        end
+      end
+
+      # Passing invalid arguments should raise UnknownCallSignature
+      assert_raises(Inquery::Exceptions::UnknownCallSignature) do
+        query_class.new(123, 456, 789)
+      end
+    end
+  end
+end

data/test/inquery/method_accessible_hash_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+module Inquery
+  class MethodAccessibleHashTest < Minitest::Test
+    def test_new
+      hash = MethodAccessibleHash.new(name: 'John Smith', age: 70, 'pension' => 300)
+
+      assert_equal 'John Smith', hash.name
+      assert_equal 70,           hash.age
+      assert_equal 300,          hash.pension
+    end
+
+    def test_new_no_arguments
+      assert_equal '{}', MethodAccessibleHash.new.to_s
+    end
+
+    def test_to_h
+      assert MethodAccessibleHash.new.merge(foo: :bar).to_h.instance_of?(::Hash)
+    end
+
+    def test_getter
+      hash = MethodAccessibleHash.new.merge(foo: :bar, bar: :baz)
+      assert_equal :bar, hash.foo
+      assert_equal :baz, hash.bar
+    end
+
+    def test_setter
+      hash = MethodAccessibleHash.new.merge(foo: :bar)
+      assert_equal :bar, hash.foo
+
+      hash.foo = :x
+      hash.bar = :y
+
+      assert_equal :x, hash.foo
+      assert_equal :y, hash.bar
+    end
+
+    def test_reference
+      hash = MethodAccessibleHash.new
+      hash.foo = 42
+      assert_equal 42, hash[:foo]
+      assert_equal 42, hash.foo
+    end
+
+    def test_comparison
+      assert_equal({ foo: :bar }, MethodAccessibleHash.new(foo: :bar))
+      refute_equal({ foo: :bar, bar: :baz }, MethodAccessibleHash.new(foo: :bar))
+    end
+
+    def test_frozen
+      hash = MethodAccessibleHash.new(name: 'John Smith', age: 70, pension: 300).freeze
+
+      assert_equal 70, hash.age
+      assert_equal 300, hash.pension
+      assert_equal 'John Smith', hash.name
+
+      assert_raises RuntimeError do
+        hash.age = 42
+      end
+
+      assert_raises RuntimeError do
+        hash.foo = 42
+      end
+
+      clone = hash.clone
+      assert clone.frozen?
+      assert_equal 70, clone.age
+
+      assert_raises RuntimeError do
+        clone.age = 42
+      end
+
+      assert_raises RuntimeError do
+        clone.foo = 42
+      end
+
+      duplicate = hash.dup
+      refute duplicate.frozen?
+
+      assert_equal 70, duplicate.age
+      assert_equal 300, duplicate.pension
+      assert_equal 'John Smith', duplicate.name
+    end
+  end
+end

data/test/inquery/mixins/raw_sql_utils_test.rb

@@ -0,0 +1,67 @@
+require 'test_helper'
+
+module Inquery
+  module Mixins
+    class RawSqlUtilsTest < Minitest::Test
+      include TestHelper
+
+      def setup
+        self.class.setup_db
+        self.class.setup_base_data
+      end
+
+      # Test query class
+      class TestQuery < Inquery::Query
+        def call
+          # Intentionally empty
+        end
+      end
+
+      def test_san_sanitizes_sql_with_variables
+        query = TestQuery.new
+        result = query.san('SELECT * FROM users WHERE id = ?', 1)
+
+        assert_kind_of String, result
+        assert_includes result, 'SELECT * FROM users WHERE id = 1'
+      end
+
+      def test_san_handles_multiple_variables
+        query = TestQuery.new
+        result = query.san('SELECT * FROM users WHERE name = ? AND id = ?', 'Alice', 1)
+
+        assert_kind_of String, result
+        assert_includes result, 'SELECT * FROM users WHERE'
+        assert_includes result, 'Alice'
+        assert_includes result, '1'
+      end
+
+      def test_san_handles_special_characters
+        query = TestQuery.new
+        result = query.san('SELECT * FROM users WHERE name = ?', "O'Brien")
+
+        assert_kind_of String, result
+        # ActiveRecord escapes quotes using SQL standard (doubled quotes)
+        assert_includes result, "O''Brien"
+      end
+
+      def test_exec_query_executes_sql
+        query = TestQuery.new
+        sql = query.san('SELECT * FROM users WHERE id = ?', 1)
+        result = query.exec_query(sql)
+
+        assert_kind_of ActiveRecord::Result, result
+        assert_equal 1, result.length
+        assert_equal 1, result.first['id']
+      end
+
+      def test_exec_query_returns_multiple_rows
+        query = TestQuery.new
+        sql = 'SELECT * FROM users ORDER BY id'
+        result = query.exec_query(sql)
+
+        assert_kind_of ActiveRecord::Result, result
+        assert_operator result.length, :>, 1
+      end
+    end
+  end
+end

data/test/inquery/query/chainable_test.rb

@@ -62,6 +62,84 @@ module Inquery
         result = Queries::Group::FilterWithColor.run(Group.where('id > 2'), color: 'green')
         assert_equal Group.find([3]), result.to_a
       end
+
+      def test_call_not_implemented_error
+        # Create an anonymous chainable query class that doesn't override call
+        query_class = Class.new(Inquery::Query::Chainable) do
+          relation class: 'Group'
+        end
+
+        # Should raise NotImplementedError when call is not overridden
+        assert_raises(NotImplementedError) do
+          query_class.run(Group.all)
+        end
+      end
+
+      def test_chainable_with_default_relation
+        query_class = Class.new(Inquery::Query::Chainable) do
+          relation class: 'Group'
+
+          def call
+            relation.where(color: 'red')
+          end
+        end
+
+        # Should use default relation when no relation is passed
+        result = query_class.run
+        assert_equal Group.find([1]), result.to_a
+      end
+
+      def test_chainable_with_params_only
+        result = Queries::Group::FilterWithColor.run(color: 'red')
+        assert_equal Group.find([1]), result.to_a
+      end
+
+      def test_chainable_with_empty_relation
+        query_class = Class.new(Inquery::Query::Chainable) do
+          relation class: 'Group'
+
+          def call
+            relation.where(color: 'blue')
+          end
+        end
+
+        result = query_class.run(Group.where('1=0'))
+        assert_empty result.to_a
+      end
+
+      def test_chainable_with_different_call_signatures
+        query_class = Class.new(Inquery::Query::Chainable) do
+          relation class: 'Group'
+          schema3 do
+            str? :color
+          end
+
+          def call
+            if osparams.color
+              relation.where(color: osparams.color)
+            else
+              relation
+            end
+          end
+        end
+
+        # Test with relation and params
+        result1 = query_class.run(Group.all, color: 'red')
+        assert_equal Group.find([1]), result1.to_a
+
+        # Test with params only
+        result2 = query_class.run(color: 'green')
+        assert_equal Group.find([2, 3]), result2.to_a
+
+        # Test with relation only (should return all)
+        result3 = query_class.run(Group.where('id > 1'))
+        assert_equal Group.find([2, 3]), result3.to_a
+      end
+
+      def test_relation_returns_active_record_relation
+        result = Queries::Group::FetchRed.run
+        assert_kind_of ActiveRecord::Relation, result
+      end
     end
   end
 end