inquery 1.0.10 → 1.1.0

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

@@ -1,10 +1,19 @@
 module Inquery
+  mattr_accessor :default_schema_version
+  self.default_schema_version = 2
+
+  # Setup method that should be called in a dedicated initializer.
+  def self.setup
+    yield self
+  end
 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

data/test/inquery/query_test.rb

@@ -43,5 +43,91 @@ module Inquery
       result = Queries::Group::FetchAsJson.run
       assert_equal Group.all.to_json, result
     end
+
+    def test_query_with_optional_params
+      query_class = Class.new(Inquery::Query) do
+        schema3 do
+          str! :name
+          int? :age
+        end
+
+        def call
+          User.where(name: osparams.name)
+        end
+      end
+
+      # With both params
+      result = query_class.run(name: 'Alice', age: 30)
+      assert_kind_of ActiveRecord::Relation, result
+
+      # With only required param
+      result = query_class.run(name: 'Alice')
+      assert_kind_of ActiveRecord::Relation, result
+    end
+
+    def test_query_without_schema
+      query_class = Class.new(Inquery::Query) do
+        def call
+          User.all
+        end
+      end
+
+      result = query_class.run
+      assert_equal User.all, result
+    end
+
+    def test_query_with_empty_result
+      query_class = Class.new(Inquery::Query) do
+        def call
+          User.where('1=0')
+        end
+      end
+
+      result = query_class.run
+      assert_empty result.to_a
+    end
+
+    def test_query_returns_nil
+      query_class = Class.new(Inquery::Query) do
+        def call
+          nil
+        end
+      end
+
+      result = query_class.run
+      assert_nil result
+    end
+
+    def test_query_with_process_method
+      query_class = Class.new(Inquery::Query) do
+        def call
+          User.all
+        end
+
+        def process(results)
+          results.count
+        end
+      end
+
+      result = query_class.run
+      assert_equal 3, result
+    end
+
+    def test_osparams_returns_method_accessible_hash
+      query_class = Class.new(Inquery::Query) do
+        schema3 do
+          str! :name
+        end
+
+        def call
+          osparams
+        end
+      end
+
+      result = query_class.run(name: 'Alice')
+      assert_kind_of Inquery::MethodAccessibleHash, result
+      assert_equal 'Alice', result.name
+      assert_equal 'Alice', result[:name]
+    end
   end
 end

data/test/test_helper.rb

@@ -1,3 +1,14 @@
+begin
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter '/test/'
+    add_filter '/vendor/'
+  end
+rescue LoadError
+  # SimpleCov not available, skip coverage reporting
+end
+
+require 'logger'
 require 'active_record'
 require 'minitest/autorun'
 require 'inquery'