hquery 1.0.0

data/test.md

@@ -0,0 +1,1466 @@
+
+# File: ./context_test.rb
+
+require_relative 'test_helper'
+
+module Hq
+  class TestDefinitionContext < Minitest::Test
+    def setup
+      @context = DefinitionContext.new(:test_model, 'data')
+    end
+
+    def test_from_array_with_valid_array
+      @context.from_array([{ id: 1, name: 'Test' }, { id: 2, name: 'Another' }])
+      assert_equal 2, @context.loaded_data.size
+      assert @context.loaded_data.all?(&:frozen?)
+    end
+
+    def test_from_array_with_non_array
+      error = assert_raises(DataFileError) { @context.from_array('not an array') }
+      assert_match /expects an Array of hashes, but got String/, error.message
+    end
+
+    def test_from_array_with_non_hash_item
+      error = assert_raises(DataFileError) { @context.from_array(['not a hash']) }
+      assert_match /array item 1 should be a Hash, but got String/, error.message
+    end
+
+    def test_scope_definition
+      @context.scope({ test_scope: -> { self } })
+      assert @context.scopes.key?(:test_scope)
+    end
+
+    def test_scope_non_callable
+      assert_raises(Hq::ScopeError) { @context.scope({ test_scope: 'not callable' }) }
+    end
+
+    def test_load_with_files
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'file1.rb'), "{ id: 1, title: 'First' }")
+        File.write(File.join(dir, 'file2.rb'), "{ id: 2, title: 'Second' }")
+        
+        context = DefinitionContext.new(:test, dir)
+        context.load('*.rb')
+        
+        assert_equal 2, context.loaded_data.size
+        assert_equal({ id: 1, title: 'First' }, context.loaded_data[0])
+        assert_equal({ id: 2, title: 'Second' }, context.loaded_data[1])
+        assert context.loaded_data.all?(&:frozen?)
+      end
+    end
+
+    def test_load_no_files
+      Dir.mktmpdir do |dir|
+        context = DefinitionContext.new(:test, dir)
+        error = assert_raises(Hq::DataFileError) { context.load('*.rb') }
+        assert_match /No files found matching pattern/, error.message
+      end
+    end
+
+    def test_load_non_hash
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'invalid.rb'), "'string'")
+        context = DefinitionContext.new(:test, dir)
+        error = assert_raises(DataFileError) { context.load('*.rb') }
+        assert_match /should return a Hash, but returned String/, error.message
+      end
+    end
+
+    def test_load_syntax_error
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'invalid.rb'), "{ id: 1,, }")
+        context = DefinitionContext.new(:test, dir)
+        error = assert_raises(DataFileError) { context.load('*.rb') }
+        assert_match /has a syntax error/, error.message
+      end
+    end
+
+    def test_load_generic_error
+      Dir.mktmpdir do |dir|
+        File.write(File.join(dir, 'error.rb'), "raise 'boom'")
+        context = DefinitionContext.new(:test, dir)
+        error = assert_raises(DataFileError) { context.load('*.rb') }
+        assert_match /couldn't be loaded:\nboom/, error.message
+      end
+    end
+  end
+end
+
+
+# File: ./data_test.rb
+
+require_relative 'test_helper'
+module Hq  
+class TestHqData < Minitest::Test
+  def setup
+    Hq.reload  # Clear collections before each test
+    # Reset data path to default
+    Hq.configure(data_path: 'data')
+  end
+
+  def teardown
+    Hq.reload  # Clean up after each test
+  end
+
+  def test_configure
+    Hq.configure(data_path: 'custom_data')
+    assert_equal 'custom_data', Hq.instance_variable_get(:@data_path)
+  end
+
+  def test_define_and_query
+    Hq.define :test_model do
+      from_array([{ id: 1 }])
+    end
+    assert_instance_of Query, Hq.query(:test_model)
+  end
+
+  def test_undefined_model_raises
+    error = assert_raises(RuntimeError) { Hq.query(:undefined) }
+    assert_equal "Collection undefined not defined. Use Hq.define :undefined to define it.", error.message
+  end
+
+  def test_reload
+    Hq.define :test_model do
+      from_array([])
+    end
+    Hq.reload
+    assert_empty Hq.defined_models
+  end
+
+  def test_defined_models
+    Hq.define :model1 do
+      from_array([])
+    end
+    Hq.define :model2 do
+      from_array([])
+    end
+    assert_equal [:model1, :model2], Hq.defined_models.sort
+  end
+
+  def test_global_helper
+    Hq.define :test_model do
+      from_array([{ id: 1 }])
+    end
+    
+    # Test the global hq() helper method
+    assert_instance_of Query, hq(:test_model)
+  end
+end
+
+
+
+
+
+
+
+
+
+class TestPagination < Minitest::Test
+  def setup
+    Hq.reload
+    # Create a collection with 23 items for thorough pagination testing
+    Hq.define :paginated_posts do
+      from_array((1..23).map do |i|
+        { 
+          id: i, 
+          title: "Post #{i}", 
+          content: "Content for post #{i}",
+          priority: i % 3,  # 0, 1, 2, 0, 1, 2, ...
+          published: i <= 20 # First 20 are published
+        }
+      end)
+
+      scope({
+        published: -> { where(published: true) },
+        by_priority: ->(p) { where(priority: p) }
+      })
+
+      item({
+        slug: -> { "post-#{self[:id]}" },
+        excerpt: -> { "#{self[:content][0..20]}..." }
+      })
+    end
+    @query = Hq.query(:paginated_posts)
+  end
+
+  def teardown
+    Hq.reload
+  end
+
+  def test_basic_pagination
+    pages = @query.paginate(per_page: 5)
+    
+    # Should have 5 pages (23 items / 5 per page = 4.6, rounded up to 5)
+    assert_equal 5, pages.length
+    
+    # Test first page
+    first_page = pages.first
+    assert_instance_of Hq::Page, first_page
+    assert_equal 5, first_page.items.size
+    assert_equal 1, first_page.current_page
+    assert_equal 5, first_page.total_pages
+    assert_equal 23, first_page.total_items
+    assert_nil first_page.prev_page
+    assert_equal 2, first_page.next_page
+    assert first_page.is_first_page
+    refute first_page.is_last_page
+    
+    # Test middle page
+    middle_page = pages[2] # Page 3
+    assert_equal 5, middle_page.items.size
+    assert_equal 3, middle_page.current_page
+    assert_equal 2, middle_page.prev_page
+    assert_equal 4, middle_page.next_page
+    refute middle_page.is_first_page
+    refute middle_page.is_last_page
+    
+    # Test last page (should have only 3 items: 21, 22, 23)
+    last_page = pages.last
+    assert_equal 3, last_page.items.size
+    assert_equal 5, last_page.current_page
+    assert_equal 4, last_page.prev_page
+    assert_nil last_page.next_page
+    refute last_page.is_first_page
+    assert last_page.is_last_page
+  end
+
+  def test_pagination_with_chaining
+    # Test pagination with where conditions
+    published_pages = @query.published.paginate(per_page: 8)
+    
+    # Should have 3 pages (20 published items / 8 per page = 2.5, rounded up to 3)
+    assert_equal 3, published_pages.length
+    assert_equal 20, published_pages.first.total_items
+    
+    # Debug the descending order issue
+    ordered_query = @query.order(:id, desc: true)
+    
+    ordered_pages = ordered_query.paginate(per_page: 6)
+    first_page_items = ordered_pages.first.items
+    expected_ids = [23, 22, 21, 20, 19, 18]
+    assert_equal expected_ids, first_page_items.map { |item| item[:id] }
+    
+    # Test pagination with scopes
+    priority_pages = @query.by_priority(1).paginate(per_page: 3)
+    # Priority 1 items: 1, 4, 7, 10, 13, 16, 19, 22 (8 items total)
+    assert_equal 3, priority_pages.length  # 8 items / 3 per page = 2.67, rounded up to 3
+    assert_equal 8, priority_pages.first.total_items
+  end
+
+  def test_single_page_collection
+    # Apply limit first, then paginate the limited results
+    limited_query = @query.limit(5)
+    small_pages = limited_query.paginate(per_page: 10)
+    
+    assert_equal 1, small_pages.length
+    page = small_pages.first
+    assert_equal 5, page.items.size
+    assert_equal 1, page.current_page
+    assert_equal 1, page.total_pages
+    assert_equal 5, page.total_items
+    assert_nil page.prev_page
+    assert_nil page.next_page
+    assert page.is_first_page
+    assert page.is_last_page
+  end
+
+  def test_empty_collection_pagination
+    empty_pages = @query.where(id: 999).paginate(per_page: 5)
+    
+    assert_equal 1, empty_pages.length
+    page = empty_pages.first
+    assert_equal [], page.items
+    assert_equal 1, page.current_page
+    assert_equal 1, page.total_pages
+    assert_equal 0, page.total_items
+  end
+
+  def test_pagination_error_handling
+    # Test with invalid per_page values
+    error = assert_raises(ArgumentError) { @query.paginate(per_page: 0) }
+    assert_match /per_page must be positive/, error.message
+    
+    error = assert_raises(ArgumentError) { @query.paginate(per_page: -5) }
+    assert_match /per_page must be positive/, error.message
+  end
+
+  def test_page_object_methods
+    pages = @query.paginate(per_page: 7)
+    page = pages[1] # Second page
+    
+    # Test item methods work on paginated items
+    first_item = page.items.first
+    assert_equal "post-#{first_item[:id]}", first_item.slug
+    assert_match /Content for post \d+\.\.\./, first_item.excerpt
+    
+    # Test posts alias
+    assert_equal page.items, page.posts
+    
+    # Test to_h method
+    page_hash = page.to_h
+    expected_keys = [:items, :current_page, :total_pages, :total_items, 
+                    :prev_page, :next_page, :is_first_page, :is_last_page]
+    assert_equal expected_keys.sort, page_hash.keys.sort
+    assert_equal page.current_page, page_hash[:current_page]
+    assert_equal page.total_items, page_hash[:total_items]
+    assert_equal page.is_first_page, page_hash[:is_first_page]
+  end
+
+  def test_pagination_maintains_order
+    # Test that pagination preserves ordering - but our implementation only supports single field sorting
+    ordered_pages = @query.order(:id).paginate(per_page: 6)
+    
+    all_items = []
+    ordered_pages.each { |page| all_items.concat(page.items) }
+    
+    # Should maintain ID ordering across pages (1,2,3,4,5,6,7,8,9,10...)
+    ids = all_items.map { |item| item[:id] }
+    assert_equal (1..23).to_a, ids
+  end
+
+  def test_pagination_edge_cases
+    # Test with per_page exactly equal to total items
+    exact_pages = @query.limit(10).paginate(per_page: 10)
+    assert_equal 1, exact_pages.length
+    assert_equal 10, exact_pages.first.items.size
+    
+    # Test with per_page larger than total items - limit to 3 items first
+    limited_query = @query.limit(3)
+    large_pages = limited_query.paginate(per_page: 10)
+    assert_equal 1, large_pages.length
+    assert_equal 3, large_pages.first.items.size
+    assert_equal 3, large_pages.first.total_items  # Total should also be 3
+    
+    # Test with per_page = 1 (maximum pages) - limit to 5 items first
+    limited_query_5 = @query.limit(5)
+    single_pages = limited_query_5.paginate(per_page: 1)
+    assert_equal 5, single_pages.length
+    assert_equal 5, single_pages.first.total_items  # Total should be 5
+    single_pages.each_with_index do |page, index|
+      assert_equal 1, page.items.size
+      assert_equal index + 1, page.current_page
+      assert_equal 5, page.total_pages
+    end
+  end
+end
+
+end
+
+
+# File: ./edge_test.rb
+
+require_relative 'test_helper'
+class TestEdgeCases < Minitest::Test
+  def setup
+    Hq.reload
+  end
+
+  def teardown
+    Hq.reload
+  end
+
+  def test_empty_collections
+    Hq.define :empty do
+      from_array([])
+    end
+
+    query = Hq.query(:empty)
+    assert_equal 0, query.size
+    assert_equal [], query.to_a
+    assert_nil query.first
+    assert_nil query.last
+    assert_equal [], query.where(id: 1).to_a
+    assert_equal [], query.order(:id).to_a
+    assert_equal [], query.limit(5).to_a
+    assert_equal [], query.offset(2).to_a
+  end
+
+  def test_single_item_collection
+    Hq.define :single do
+      from_array([{ id: 1, title: 'Only One' }])
+    end
+
+    query = Hq.query(:single)
+    assert_equal 1, query.count
+    assert_equal 1, query.first[:id]
+    assert_equal 1, query.last[:id]
+    assert_equal [1], query.all.map { |item| item[:id] }
+  end
+
+  def test_collections_with_duplicate_data
+    Hq.define :duplicates do
+      from_array([
+        { id: 1, name: 'John' },
+        { id: 2, name: 'John' },
+        { id: 3, name: 'John' }
+      ])
+    end
+
+    query = Hq.query(:duplicates)
+    johns = query.where(name: 'John')
+    assert_equal 3, johns.size
+    assert_equal [1, 2, 3], johns.map { |item| item[:id] }.sort
+  end
+
+  def test_collections_with_all_nils
+    Hq.define :nils do
+      from_array([
+        { id: 1, value: nil },
+        { id: 2, value: nil },
+        { id: 3, value: nil }
+      ])
+    end
+
+    query = Hq.query(:nils)
+    results = query.where(value: { exists: false })
+    assert_equal 3, results.size
+
+    results = query.where(value: { empty: true })
+    assert_equal 3, results.size
+  end
+
+  def test_large_offset_and_limit
+    Hq.define :numbers do
+      from_array((1..100).map { |n| { id: n, value: n * 2 } })
+    end
+
+    query = Hq.query(:numbers)
+    
+    # Test large offset beyond collection size
+    results = query.offset(200)
+    assert_equal [], results.to_a
+
+    # Test large limit on small remaining items
+    results = query.offset(95).limit(10)
+    assert_equal 5, results.size # Only 5 items left after offset 95
+
+    # Test zero limit
+    results = query.limit(0)
+    assert_equal [], results.to_a
+
+    # Test negative offset (should be treated as 0)
+    results = query.offset(-5).limit(3)
+    assert_equal 3, results.size
+  end
+
+  def test_complex_chaining_with_no_results
+    Hq.define :complex do
+      from_array([
+        { id: 1, category: 'A', published: true, views: 100 },
+        { id: 2, category: 'B', published: false, views: 200 }
+      ])
+    end
+
+    query = Hq.query(:complex)
+    
+    # Chain filters that result in no matches
+    results = query.where(category: 'A').where(published: false)
+    assert_equal [], results.to_a
+
+    results = query.where(views: { greater_than: 300 })
+    assert_equal [], results.to_a
+
+    results = query.where(id: [10, 20, 30])
+    assert_equal [], results.to_a
+  end
+
+  def test_scope_with_parameters_edge_cases
+    Hq.define :parameterized do
+      from_array([
+        { id: 1, score: 85 },
+        { id: 2, score: 92 },
+        { id: 3, score: 78 },
+        { id: 4, score: 95 }
+      ])
+
+      scope({
+        by_score: ->(min_score) { where(score: { greater_than_or_equal: min_score }) },
+        top_n: ->(n) { order(:score, desc: true).limit(n) },
+        score_range: ->(min, max) { where(score: { from: min, to: max }) }
+      })
+    end
+
+    query = Hq.query(:parameterized)
+    
+    results = query.by_score(100)
+    assert_equal [], results.to_a
+
+    results = query.by_score(0)
+    assert_equal 4, results.size
+
+    results = query.top_n(0)
+    assert_equal [], results.to_a
+
+    results = query.score_range(90, 100)
+    assert_equal [2, 4].sort, results.map { |item| item[:id] }.sort # <-- Corrected
+  end
+
+def test_method_name_conflicts
+  Hq.define :conflicts do
+    from_array([{ id: 1, hash: 'test_hash', class: 'test_class' }])
+  end
+
+  query = Hq.query(:conflicts)
+  item = query.first
+
+  # Access conflicting keys via [] - they should NOT have method access
+  assert_equal 'test_hash', item[:hash]
+  assert_equal 'test_class', item[:class]
+
+  # Check that conflicting keys do NOT respond to method calls
+  # These should be FALSE because we skip defining methods for conflicting keys
+  assert item.respond_to?(:hash)   # Should be false - we don't define this method
+  assert item.respond_to?(:class)  # Should be false - we don't define this method
+
+  # Check built-in methods still work
+  assert item.object_id.is_a?(Integer)
+  assert item.hash.is_a?(Integer)    # Built-in hash method works
+  assert_equal Hq::InstanceWrapper, item.class # Built-in class method works
+
+  # Verify we can't access the hash values as methods (should raise NoMethodError)
+  # But since respond_to? returns false, we don't need to test this
+end
+
+
+
+  def test_ordering_with_mixed_types
+    # Test ordering when values are of different types (should handle gracefully)
+    Hq.define :mixed do
+      from_array([
+        { id: 1, value: 'string' },
+        { id: 2, value: 42 },
+        { id: 3, value: nil },
+        { id: 4, value: Date.new(2024, 1, 1) }
+      ])
+    end
+
+    query = Hq.query(:mixed)
+    
+    # Should not raise an error, even with mixed types
+    results = query.order(:value)
+    assert_equal 4, results.size
+    
+    # nil should be at the end
+    assert_equal 3, results.last[:id]
+  end
+end
+
+
+# File: ./instance_test.rb
+
+require_relative 'test_helper'
+
+module Hq
+  class TestInstanceWrapper < Minitest::Test
+    def setup
+      @hash = { id: 1, title: 'Test', content: 'Long content here for testing purpose', views: 100, published_at: Date.new(2024, 1, 1) }.freeze
+      
+      Hq.present :test_model do
+        def excerpt(words = 2)
+          self[:content].split.take(words).join(' ') + '...'
+        end
+        
+        def title_upper
+          self[:title].upcase
+        end
+        
+        def formatted_date
+          self[:published_at]&.strftime("%B %d, %Y")
+        end
+        
+        def view_category
+          self[:views] && self[:views] > 150 ? 'popular' : 'standard'
+        end
+        
+        def word_count
+          self[:content].split.size
+        end
+        
+        def summary(max_words = 10)
+          words = self[:content].split.take(max_words)
+          "#{words.join(' ')}#{words.size >= max_words ? '...' : ''}"
+        end
+      end
+      
+      @wrapper = Hq::InstanceWrapper.new(@hash, :test_model)
+    end
+    
+    def teardown
+      Hq.reload
+    end
+
+    def test_dot_notation_access_for_hash_keys
+      assert_equal @hash[:id], @wrapper.id
+      assert_equal @hash[:title], @wrapper.title
+      assert_equal @hash[:content], @wrapper.content
+      assert_equal @hash[:views], @wrapper.views
+      assert_equal @hash[:published_at], @wrapper.published_at
+      assert @wrapper.respond_to?(:id)
+      assert @wrapper.respond_to?(:title)
+      refute @wrapper.respond_to?(:some_random_method_that_does_not_exist)
+    end
+
+    def test_dot_notation_access_for_presenter_methods
+      assert_equal 'Long content...', @wrapper.excerpt
+      assert_equal 'Long...', @wrapper.excerpt(1)
+      assert_equal 'TEST', @wrapper.title_upper
+      assert @wrapper.respond_to?(:excerpt)
+      assert @wrapper.respond_to?(:title_upper)
+    end
+
+    def test_hash_access
+      assert_equal 1, @wrapper[:id]
+      assert_equal 'Test', @wrapper[:title]
+      assert_equal 'Test', @wrapper['title']
+      assert_equal 100, @wrapper[:views]
+      assert_nil @wrapper[:non_existent]
+    end
+
+    def test_symbol_string_key_normalization
+      assert_equal 'Test', @wrapper[:title]
+      assert_equal 'Test', @wrapper['title']
+      assert_equal 1, @wrapper[:id]
+      assert_equal 1, @wrapper['id']
+    end
+
+    def test_immutability
+      error = assert_raises(RuntimeError) { @wrapper[:id] = 2 }
+      assert_match /immutable/, error.message
+      error = assert_raises(RuntimeError) { @wrapper['title'] = 'New Title' }
+      assert_match /immutable/, error.message
+    end
+
+    def test_presenter_methods
+      assert_equal 'Long content...', @wrapper.excerpt
+      assert_equal 'Long...', @wrapper.excerpt(1)
+      assert_equal 'Long content here...', @wrapper.excerpt(3)
+      assert_equal 'TEST', @wrapper.title_upper
+      assert_equal 'January 01, 2024', @wrapper.formatted_date
+      assert_equal 'standard', @wrapper.view_category
+      assert_equal 6, @wrapper.word_count
+    end
+
+    def test_presenter_methods_with_parameters
+      assert_equal 'Long content...', @wrapper.excerpt(2)
+      assert_equal 'Long content here for...', @wrapper.excerpt(4)
+      assert_equal 'Long content here for testing...', @wrapper.summary(5)
+      assert_equal 'Long content here for testing purpose', @wrapper.summary(10)
+    end
+
+    def test_memoization
+      result1 = @wrapper.excerpt
+      result2 = @wrapper.excerpt
+      assert_equal result1, result2
+      assert_equal 'Long content...', result1
+      result3 = @wrapper.excerpt(1)
+      assert_equal 'Long...', result3
+      refute_equal result1, result3
+      result4 = @wrapper.excerpt(1)
+      assert_equal result3, result4
+      date1 = @wrapper.formatted_date
+      date2 = @wrapper.formatted_date
+      assert_equal date1, date2
+      assert_equal 'January 01, 2024', date1
+    end
+
+    def test_presenter_method_with_nil_handling
+      nil_hash = { id: 1, title: nil, content: nil, published_at: nil }.freeze
+      
+      Hq.present :nil_test_model do
+        def safe_title
+          self[:title] || 'Untitled'
+        end
+        
+        def safe_date
+          self[:published_at]&.strftime("%Y-%m-%d") || 'No date'
+        end
+        
+        def content_length
+          (self[:content] || '').length
+        end
+      end
+      
+      wrapper = InstanceWrapper.new(nil_hash, :nil_test_model)
+      assert_equal 'Untitled', wrapper.safe_title
+      assert_equal 'No date', wrapper.safe_date
+      assert_equal 0, wrapper.content_length
+    end
+
+    def test_presenter_method_error
+      Hq.present :error_test_model do
+        def bad
+          raise 'boom'
+        end
+        
+        def another_bad
+          undefined_method_call
+        end
+      end
+      
+      wrapper = Hq::InstanceWrapper.new(@hash, :error_test_model)
+      error = assert_raises(Hq::ItemMethodError) { wrapper.bad }
+      assert_match /Error executing presenter method :bad.*boom/, error.message
+      error = assert_raises(Hq::ItemMethodError) { wrapper.another_bad }
+      assert_match /Error executing presenter method :another_bad/, error.message
+    end
+
+    def test_hash_methods
+      expected_keys = [:id, :title, :content, :views, :published_at]
+      assert_equal expected_keys.sort, @wrapper.to_h.keys.sort
+      assert_equal @hash.values.size, @wrapper.to_h.values.size
+      assert_equal @hash, @wrapper.to_h
+      assert_equal @hash, @wrapper.to_hash
+    end
+
+    def test_method_missing_for_hash
+      assert_equal 1, @wrapper[:id]
+      assert_equal 'Test', @wrapper[:title]
+      assert_equal 5, @wrapper.to_h.size
+      assert @wrapper.respond_to?(:id)
+      assert_equal 1, @wrapper.id
+      assert @wrapper.to_h.has_key?(:id)
+      assert @wrapper.to_h.has_key?(:title)
+      refute @wrapper.to_h.has_key?(:non_existent)
+      assert @wrapper.to_h.include?(:id)
+      assert_equal @hash.length, @wrapper.to_h.length
+      assert_equal false, @wrapper.to_h.empty?
+      assert @wrapper.respond_to?(:to_h)
+      assert @wrapper.respond_to?(:[])
+    end
+
+    def test_respond_to_for_dynamic_methods
+      assert @wrapper.respond_to?(:id)
+      assert @wrapper.respond_to?(:title)
+      assert @wrapper.respond_to?(:excerpt)
+      assert @wrapper.respond_to?(:title_upper)
+      assert @wrapper.respond_to?(:formatted_date)
+      refute @wrapper.to_h.has_key?(:non_existent)
+      assert @wrapper.respond_to?(:class)
+      assert @wrapper.respond_to?(:object_id)
+      assert @wrapper.respond_to?(:to_h)
+      refute @wrapper.respond_to?(:keys)
+      refute @wrapper.respond_to?(:values)
+      refute @wrapper.respond_to?(:size)
+    end
+
+    def test_inspect
+      assert_match /#<Hq::Instance {.*}>/, @wrapper.inspect
+      assert_match /id.*1/, @wrapper.inspect
+      assert_match /title.*"Test"/, @wrapper.inspect
+    end
+
+    def test_complex_presenter_methods
+      complex_hash = { 
+        tags: ['ruby', 'web', 'programming'], 
+        metadata: { author: 'John', category: 'tech' },
+        scores: [85, 90, 78, 92]
+      }.freeze
+      
+      Hq.present :complex_test_model do
+        def tag_list
+          self[:tags].join(', ')
+        end
+        
+        def author_name
+          self[:metadata][:author]
+        end
+        
+        def average_score
+          self[:scores].sum.to_f / self[:scores].length
+        end
+        
+        def top_score
+          self[:scores].max
+        end
+        
+        def tag_count
+          self[:tags].length
+        end
+      end
+      
+      wrapper = InstanceWrapper.new(complex_hash, :complex_test_model)
+      assert_equal 'ruby, web, programming', wrapper.tag_list
+      assert_equal 'John', wrapper.author_name
+      assert_equal 86.25, wrapper.average_score
+      assert_equal 92, wrapper.top_score
+      assert_equal 3, wrapper.tag_count
+    end
+  end
+end
+
+
+# File: ./paginate_test.rb
+
+require_relative 'test_helper'
+
+class TestPagination < Minitest::Test
+  def setup
+    Hq.reload
+    Hq.define :paginated_posts do
+      from_array((1..23).map do |i|
+        { 
+          id: i, 
+          title: "Post #{i}", 
+          content: "Content for post #{i}",
+          priority: i % 3,
+          published: i <= 20
+        }
+      end)
+
+      scope({
+        published: -> { where(published: true) },
+        by_priority: ->(p) { where(priority: p) }
+      })
+    end
+    
+    Hq.present :paginated_posts do
+      def slug
+        "post-#{self[:id]}"
+      end
+      
+      def excerpt
+        "#{self[:content][0..20]}..."
+      end
+    end
+    
+    @query = Hq.query(:paginated_posts)
+  end
+
+  def teardown
+    Hq.reload
+  end
+
+  def test_basic_pagination
+    pages = @query.paginate(per_page: 5)
+    
+    assert_equal 5, pages.length
+    
+    first_page = pages.first
+    assert_instance_of Hq::Page, first_page
+    assert_equal 5, first_page.items.size
+    assert_equal 1, first_page.current_page
+    assert_equal 5, first_page.total_pages
+    assert_equal 23, first_page.total_items
+    assert_nil first_page.prev_page
+    assert_equal 2, first_page.next_page
+    assert first_page.is_first_page
+    refute first_page.is_last_page
+    
+    middle_page = pages[2]
+    assert_equal 5, middle_page.items.size
+    assert_equal 3, middle_page.current_page
+    assert_equal 2, middle_page.prev_page
+    assert_equal 4, middle_page.next_page
+    refute middle_page.is_first_page
+    refute middle_page.is_last_page
+    
+    last_page = pages.last
+    assert_equal 3, last_page.items.size
+    assert_equal 5, last_page.current_page
+    assert_equal 4, last_page.prev_page
+    assert_nil last_page.next_page
+    refute last_page.is_first_page
+    assert last_page.is_last_page
+  end
+
+  def test_pagination_with_chaining
+    published_pages = @query.published.paginate(per_page: 8)
+    
+    assert_equal 3, published_pages.length
+    assert_equal 20, published_pages.first.total_items
+    
+    ordered_query = @query.order(:id, desc: true)
+    
+    ordered_pages = ordered_query.paginate(per_page: 6)
+    first_page_items = ordered_pages.first.items
+    expected_ids = [23, 22, 21, 20, 19, 18]
+    assert_equal expected_ids, first_page_items.map { |item| item[:id] }
+    
+    priority_pages = @query.by_priority(1).paginate(per_page: 3)
+    assert_equal 3, priority_pages.length
+    assert_equal 8, priority_pages.first.total_items
+  end
+
+  def test_single_page_collection
+    limited_query = @query.limit(5)
+    small_pages = limited_query.paginate(per_page: 10)
+    
+    assert_equal 1, small_pages.length
+    page = small_pages.first
+    assert_equal 5, page.items.size
+    assert_equal 1, page.current_page
+    assert_equal 1, page.total_pages
+    assert_equal 5, page.total_items
+    assert_nil page.prev_page
+    assert_nil page.next_page
+    assert page.is_first_page
+    assert page.is_last_page
+  end
+
+  def test_empty_collection_pagination
+    empty_pages = @query.where(id: 999).paginate(per_page: 5)
+    
+    assert_equal 1, empty_pages.length
+    page = empty_pages.first
+    assert_equal [], page.items
+    assert_equal 1, page.current_page
+    assert_equal 1, page.total_pages
+    assert_equal 0, page.total_items
+  end
+
+  def test_pagination_error_handling
+    error = assert_raises(ArgumentError) { @query.paginate(per_page: 0) }
+    assert_match /per_page must be positive/, error.message
+    
+    error = assert_raises(ArgumentError) { @query.paginate(per_page: -5) }
+    assert_match /per_page must be positive/, error.message
+  end
+
+  def test_page_object_methods
+    pages = @query.paginate(per_page: 7)
+    page = pages[1]
+    
+    first_item = page.items.first
+    assert_equal "post-#{first_item[:id]}", first_item.slug
+    assert_match /Content for post \d+\.\.\./, first_item.excerpt
+    
+    assert_equal page.items, page.posts
+    
+    page_hash = page.to_h
+    expected_keys = [:items, :current_page, :total_pages, :total_items, 
+                    :prev_page, :next_page, :is_first_page, :is_last_page]
+    assert_equal expected_keys.sort, page_hash.keys.sort
+    assert_equal page.current_page, page_hash[:current_page]
+    assert_equal page.total_items, page_hash[:total_items]
+    assert_equal page.is_first_page, page_hash[:is_first_page]
+  end
+
+  def test_pagination_maintains_order
+    ordered_pages = @query.order(:id).paginate(per_page: 6)
+    
+    all_items = []
+    ordered_pages.each { |page| all_items.concat(page.items) }
+    
+    ids = all_items.map { |item| item[:id] }
+    assert_equal (1..23).to_a, ids
+  end
+
+  def test_pagination_edge_cases
+    exact_pages = @query.limit(10).paginate(per_page: 10)
+    assert_equal 1, exact_pages.length
+    assert_equal 10, exact_pages.first.items.size
+    
+    limited_query = @query.limit(3)
+    large_pages = limited_query.paginate(per_page: 10)
+    assert_equal 1, large_pages.length
+    assert_equal 3, large_pages.first.items.size
+    assert_equal 3, large_pages.first.total_items
+    
+    limited_query_5 = @query.limit(5)
+    single_pages = limited_query_5.paginate(per_page: 1)
+    assert_equal 5, single_pages.length
+    assert_equal 5, single_pages.first.total_items
+    single_pages.each_with_index do |page, index|
+      assert_equal 1, page.items.size
+      assert_equal index + 1, page.current_page
+      assert_equal 5, page.total_pages
+    end
+  end
+end
+
+
+# File: ./query_test.rb
+
+require_relative 'test_helper'
+
+module Hq
+  class TestQuery < Minitest::Test
+    def setup
+      Hq.reload
+      Hq.define :posts do
+        from_array([
+          { id: 1, title: 'Post 1', published_at: Date.new(2024, 1, 1), featured: true, tags: ['ruby', 'web'], views: 100 },
+          { id: 2, title: 'Post 2', published_at: Date.new(2024, 2, 1), featured: false, tags: ['tools'], views: 200 },
+          { id: 3, title: 'Post 3', published_at: Date.new(2023, 12, 1), featured: true, tags: ['ruby'], views: 150 },
+          { id: 4, title: nil, published_at: nil, featured: nil, tags: [], views: nil }
+        ])
+
+        scope({
+          featured: -> { where(featured: true) },
+          recent: ->(n=2) { order(:published_at, desc: true).limit(n) },
+          tagged: ->(tag) { where(tags: { contains: tag }) }
+        })
+      end
+      
+      Hq.present :posts do
+        def title_upper
+          self[:title]&.upcase
+        end
+        
+        def view_category
+          self[:views] && self[:views] > 150 ? 'popular' : 'standard'
+        end
+      end
+      
+      @query = Hq.query(:posts)
+    end
+
+    def teardown
+      Hq.reload
+    end
+
+    def test_all
+      assert_equal 4, @query.all.size
+      assert @query.all.all? { |item| item.is_a?(InstanceWrapper) }
+    end
+
+    def test_first_and_last
+      assert_equal 1, @query.first[:id]
+      assert_equal 4, @query.last[:id]
+    end
+
+    def test_count
+      assert_equal 4, @query.count
+    end
+
+    def test_find_by
+      post = @query.find_by(id: 2)
+      assert_equal 'Post 2', post[:title]
+    end
+
+    def test_where_equality
+      query = @query.where(featured: true) 
+      assert_equal [1, 3], query.map { |p| p[:id] }.sort
+    end
+
+    def test_where_hash_conditions
+      results = @query.where(title: { contains: 'Post' })
+      assert_equal 3, results.size
+
+      results = @query.where(published_at: { greater_than: Date.new(2024, 1, 1) })
+      assert_equal [2], results.map { |p| p[:id] }
+
+      results = @query.where(published_at: { less_than: Date.new(2024, 1, 1) })
+      assert_equal [3], results.map { |p| p[:id] }
+
+      results = @query.where(published_at: { greater_than_or_equal: Date.new(2024, 1, 1) })
+      assert_equal [1, 2], results.map { |p| p[:id] }.sort
+
+      results = @query.where(published_at: { less_than_or_equal: Date.new(2024, 1, 1) })
+      assert_equal [1, 3], results.map { |p| p[:id] }.sort
+
+      results = @query.where(published_at: { from: Date.new(2024, 1, 1), to: Date.new(2024, 2, 1) })
+      assert_equal [1, 2], results.map { |p| p[:id] }.sort
+
+      results = @query.where(published_at: { from: Date.new(2024, 1, 1) })
+      assert_equal [1, 2], results.map { |p| p[:id] }.sort
+
+      results = @query.where(published_at: { to: Date.new(2024, 1, 1) })
+      assert_equal [1, 3], results.map { |p| p[:id] }.sort
+
+      results = @query.where(id: { in: [1, 3] })
+      assert_equal [1, 3], results.map { |p| p[:id] }.sort
+
+      results = @query.where(id: { not_in: [1, 3] })
+      assert_equal [2, 4], results.map { |p| p[:id] }.sort
+
+      results = @query.where(featured: { not: true })
+
+      results = @query.where(tags: { empty: true })
+      assert_equal [4], results.map { |p| p[:id] }
+
+      results = @query.where(tags: { empty: false })
+      assert_equal [1, 2, 3], results.map { |p| p[:id] }.sort
+
+      results = @query.where(title: { exists: true })
+      assert_equal 3, results.size
+
+      results = @query.where(title: { exists: false })
+      assert_equal [4], results.map { |p| p[:id] }
+
+      results = @query.where(title: { starts_with: 'Post' })
+      assert_equal 3, results.size
+
+      results = @query.where(title: { ends_with: '1' })
+      assert_equal [1], results.map { |p| p[:id] }
+    end
+
+    def test_where_array
+      results = @query.where(id: [1, 3])
+      assert_equal [1, 3], results.map { |p| p[:id] }.sort
+    end
+
+    def test_where_range
+      results = @query.where(published_at: Date.new(2024, 1, 1)..Date.new(2024, 12, 31))
+      assert_equal [1, 2], results.map { |p| p[:id] }.sort
+    end
+
+    def test_order_asc
+      results = @query.order(:published_at)
+      expected_order = [3, 1, 2, 4]
+      assert_equal expected_order, results.map { |p| p[:id] }
+    end
+
+    def test_order_desc
+      results = @query.order(:published_at, desc: true)
+      expected_order = [2, 1, 3, 4]
+      assert_equal expected_order, results.map { |p| p[:id] }
+    end
+
+    def test_limit_and_offset
+      results = @query.order(:id).limit(2)
+      assert_equal [1, 2], results.map { |p| p[:id] }
+
+      results = @query.order(:id).offset(2).limit(1)
+      assert_equal [3], results.map { |p| p[:id] }
+
+      results = @query.order(:id).offset(1).limit(2)
+      assert_equal [2, 3], results.map { |p| p[:id] }
+
+      results = @query.order(:id).offset(10)
+      assert_equal [], results.map { |p| p[:id] }
+    end
+
+    def test_chained_queries
+      results = @query.where(featured: true).order(:published_at, desc: true).limit(1)
+      assert_equal [1], results.map { |p| p[:id] }
+
+      results = @query.where(views: { greater_than: 120 }).where(featured: true)
+      assert_equal [3], results.map { |p| p[:id] }
+    end
+
+    def test_scopes
+      featured = @query.featured.all
+      assert_equal [1, 3], featured.map { |p| p[:id] }.sort
+
+      recent = @query.recent.all
+      assert_equal [2, 1], recent.map { |p| p[:id] }
+
+      recent_3 = @query.recent(3)
+      assert_equal [2, 1, 3], recent_3.map { |p| p[:id] }
+
+      tagged = @query.tagged('ruby')
+      assert_equal [1, 3], tagged.map { |p| p[:id] }.sort
+
+      featured_ruby = @query.featured.tagged('ruby')
+      assert_equal [1, 3], featured_ruby.map { |p| p[:id] }.sort
+    end
+    def test_scope_error_handling
+      Hq.define :error_model do
+        from_array([])
+        scope({ bad: -> { raise 'boom' } })
+      end
+      query = Hq.query(:error_model)
+      error = assert_raises(Hq::ScopeError) { query.bad }
+      assert_match /Error in scope :bad for model :error_model/, error.message
+    end
+
+    def test_enumerable
+      assert_equal 4, @query.size
+      
+      titles = @query.select { |p| p[:title] }.map { |p| p[:title] }
+      assert_equal ['Post 1', 'Post 2', 'Post 3'], titles.sort
+
+      featured_ids = @query.select { |p| p[:featured] }.map { |p| p[:id] }
+      assert_equal [1, 3], featured_ids.sort
+
+      assert @query.any? { |p| p[:featured] }
+      assert @query.all? { |p| p[:id].is_a?(Integer) }
+    end
+
+    def test_symbol_normalization_in_conditions
+      results = @query.where(title: { contains: 'Post' })
+      assert_equal 3, results.size
+
+      results = @query.where('id' => 1, :featured => true)
+      assert_equal [1], results.map { |p| p[:id] }
+    end
+
+    def test_complex_conditions
+      results = @query.where(featured: false)
+      assert_equal [2], results.map { |p| p[:id] }
+
+      results = @query.where(featured: nil)
+      assert_equal [4], results.map { |p| p[:id] }
+
+      results = @query.where(tags: ['ruby', 'web'])
+      assert_equal [1], results.map { |p| p[:id] }
+      
+      results = @query.where(tags: ['tools'])
+      assert_equal [2], results.map { |p| p[:id] }
+    end
+    
+    def test_or_where_hash
+      results = @query.where(featured: true).or_where(views: { greater_than: 150 })
+      assert_equal [1, 2, 3], results.map { |p| p.id }.sort
+    end
+
+    def test_or_where_block
+      results = @query.where { |q| q.where(id: 1).where(featured: false) }
+                     .or_where { |q| q.where(views: { greater_than_or_equal: 200 }) }
+
+      assert_equal [2], results.map { |p| p.id }
+    end
+
+    def test_where_block_for_grouping
+      results = @query.where(featured: true).where do |q|
+        q.where(views: { less_than: 120 }).or_where(tags: { contains: 'ruby' })
+      end
+      assert_equal [1, 3], results.map { |p| p.id }.sort
+    end
+
+    def test_negation_with_where_not_hash
+      results = @query.where(featured: { not: true })
+      assert_equal [2, 4], results.map { |p| p.id }.sort
+    end
+
+    def test_negation_with_or_where_not_hash
+      results = @query.where(featured: true).or_where(title: { not: 'Post 2' })
+      assert_equal [1, 3, 4], results.map { |p| p.id }.sort
+    end
+
+    def test_complex_and_or_not
+      results = @query.where { |q| q.where(featured: true).where(views: { less_than_or_equal: 150 }) }
+                     .or_where { |q| q.where(tags: { contains: 'web' }).where(views: { less_than: 150 }) }
+      
+      assert_equal [1, 3], results.map { |p| p.id }.sort
+    end
+  end
+end
+
+
+# File: ./relations_test.rb
+
+require_relative 'test_helper'
+
+class TestRelations < Minitest::Test
+  def setup
+    Hq.reload
+
+    Hq.define :authors do
+      from_array([
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+        { id: 3, name: 'Charlie' }
+      ])
+      has_many :posts
+      has_one :profile
+    end
+
+    Hq.define :posts do
+      from_array([
+        { id: 101, title: 'Intro to Hq', author_id: 1, published: true, content: '...' },
+        { id: 102, title: 'Advanced Ruby', author_id: 1, published: false, content: '...' },
+        { id: 103, title: 'Web Development', author_id: 2, published: true, content: '...' },
+        { id: 104, title: 'Orphaned Post', author_id: nil, published: true, content: '...' }
+      ])
+      belongs_to :author
+      has_many :post_tags
+      has_many :tags, through: :post_tags
+    end
+
+    Hq.define :profiles do
+      from_array([
+        { id: 201, bio: 'Ruby Developer', author_id: 1 },
+        { id: 202, bio: 'Web Enthusiast', author_id: 2 }
+      ])
+      belongs_to :author
+    end
+
+    Hq.define :tags do
+      from_array([
+        { id: 301, name: 'ruby' },
+        { id: 302, name: 'web' },
+        { id: 303, name: 'performance' }
+      ])
+      has_many :post_tags
+      has_many :posts, through: :post_tags
+    end
+
+    Hq.define :post_tags do
+      from_array([
+        { id: 401, post_id: 101, tag_id: 301 },
+        { id: 402, post_id: 101, tag_id: 302 },
+        { id: 403, post_id: 102, tag_id: 301 },
+        { id: 404, post_id: 103, tag_id: 302 }
+      ])
+      belongs_to :post
+      belongs_to :tag
+    end
+
+    Hq.define :users do
+      from_array([ { user_pk: 501, username: 'admin' } ])
+      has_many :articles, class_name: :articles, foreign_key: :creator_id, owner_key: :user_pk
+    end
+
+    Hq.define :articles do
+      from_array([
+        { id: 601, title: 'User Article', creator_id: 501 }
+      ])
+      belongs_to :creator, class_name: :users, foreign_key: :creator_id, primary_key: :user_pk
+    end
+  end
+
+  def teardown
+    Hq.reload
+  end
+
+  def test_belongs_to_finds_parent
+    post = hq(:posts).find_by(id: 101)
+    author = post.author
+
+    assert_instance_of Hq::InstanceWrapper, author
+    assert_equal 1, author.id
+    assert_equal 'Alice', author.name
+    assert post.respond_to?(:author)
+  end
+
+  def test_belongs_to_returns_nil_if_fk_nil
+    post = hq(:posts).find_by(id: 104)
+    assert_nil post.author
+  end
+
+  def test_belongs_to_returns_nil_if_parent_missing
+    post = Hq::InstanceWrapper.new({ id: 105, title: 'Missing Author Post', author_id: 999 }, :posts)
+    author = post.author
+    assert_nil author
+  end
+
+  def test_belongs_to_with_custom_keys
+    article = hq(:articles).find_by(id: 601)
+    creator = article.creator
+
+    assert_instance_of Hq::InstanceWrapper, creator
+    assert_equal 'admin', creator.username
+    assert article.respond_to?(:creator)
+  end
+
+  def test_has_many_returns_query
+    alice = hq(:authors).find_by(id: 1)
+    posts_query = alice.posts
+
+    assert_instance_of Hq::Query, posts_query
+    assert alice.respond_to?(:posts)
+  end
+
+  def test_has_many_retrieves_children
+    alice = hq(:authors).find_by(id: 1)
+    posts = alice.posts.order(:id)
+
+    assert_equal 2, posts.size
+    assert_equal [101, 102], posts.map { |p| p.id }
+    assert_equal ['Intro to Hq', 'Advanced Ruby'], posts.map { |p| p.title }
+  end
+
+  def test_has_many_allows_chaining
+    alice = hq(:authors).find_by(id: 1)
+    published_posts = alice.posts.where(published: true)
+
+    assert_equal 1, published_posts.size
+    assert_equal 101, published_posts.first.id
+  end
+
+  def test_has_many_returns_empty_query_if_no_children
+    charlie = hq(:authors).find_by(id: 3)
+    posts_query = charlie.posts
+
+    assert_instance_of Hq::Query, posts_query
+    assert_equal 0, posts_query.size
+    assert_equal [], posts_query.to_a
+  end
+
+  def test_has_many_with_custom_keys
+    user = hq(:users).first
+    articles_query = user.articles
+
+    assert_instance_of Hq::Query, articles_query
+    assert_equal 1, articles_query.size
+    assert_equal 601, articles_query.first.id
+    assert user.respond_to?(:articles)
+  end
+
+  def test_has_one_finds_child
+    alice = hq(:authors).find_by(id: 1)
+    profile = alice.profile
+
+    assert_instance_of Hq::InstanceWrapper, profile
+    assert_equal 201, profile.id
+    assert_equal 'Ruby Developer', profile.bio
+    assert alice.respond_to?(:profile)
+  end
+
+  def test_has_one_returns_nil_if_no_child
+    charlie = hq(:authors).find_by(id: 3)
+    profile = charlie.profile
+
+    assert_nil profile
+  end
+
+  def test_has_many_through_returns_query
+    post = hq(:posts).find_by(id: 101)
+    tags_query = post.tags
+
+    assert_instance_of Hq::Query, tags_query
+    assert post.respond_to?(:tags)
+  end
+
+  def test_has_many_through_retrieves_targets
+    post = hq(:posts).find_by(id: 101)
+    tags = post.tags.order(:id)
+
+    assert_equal 2, tags.size
+    assert_equal [301, 302], tags.map { |t| t.id }
+    assert_equal ['ruby', 'web'], tags.map { |t| t.name }
+  end
+
+  def test_has_many_through_allows_chaining
+    post = hq(:posts).find_by(id: 101)
+    ruby_tag = post.tags.where(name: 'ruby')
+
+    assert_equal 1, ruby_tag.size
+    assert_equal 301, ruby_tag.first.id
+  end
+
+  def test_has_many_through_returns_empty_query_if_no_targets
+    post = hq(:posts).find_by(id: 104)
+    tags_query = post.tags
+
+    assert_instance_of Hq::Query, tags_query
+    assert_equal 0, tags_query.size
+    assert_equal [], tags_query.to_a
+  end
+
+  def test_has_many_through_inverse
+    tag = hq(:tags).find_by(id: 301)
+    posts_query = tag.posts
+
+    assert_instance_of Hq::Query, posts_query
+    assert tag.respond_to?(:posts)
+
+    posts = posts_query.order(:id)
+    assert_equal 2, posts.size
+    assert_equal [101, 102], posts.map { |p| p.id }
+  end
+end
+
+
+# File: ./run_all.rb
+
+require_relative "relations_test"
+require_relative "query_test"
+require_relative "context_test"
+require_relative "instance_test"
+require_relative "edge_test"
+require_relative "paginate_test"
+require_relative "data_test"
+
+
+# File: ./test_helper.rb
+
+require 'minitest/autorun'
+require 'minitest/pride'
+require_relative '../lib/hq'
+require 'date'
+require 'tmpdir'  # For temporary file tests
+require 'fileutils'
+