Add error hierarchy tests and implement eager loading in QueryBuilder

Author: eliasjpr

spec/core/error_hierarchy_spec.cr

@@ -0,0 +1,127 @@
+require "../spec_helper"
+
+describe "Error Hierarchy" do
+  describe "CQL::Error base class" do
+    it "is the base class for all CQL errors" do
+      # CQL::Error should inherit from Exception
+      error = CQL::Error.new("test")
+      error.is_a?(Exception).should be_true
+    end
+  end
+
+  describe "Schema errors" do
+    it "Schema::Error inherits from CQL::Error" do
+      error = CQL::Schema::Error.new("test")
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "Schema::InvalidURIError inherits from Schema::Error and CQL::Error" do
+      error = CQL::Schema::InvalidURIError.new("test")
+      error.is_a?(CQL::Schema::Error).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "Schema::VersionConflictError inherits from Schema::Error and CQL::Error" do
+      error = CQL::Schema::VersionConflictError.new("test")
+      error.is_a?(CQL::Schema::Error).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "Schema::ConnectionError inherits from Schema::Error and CQL::Error" do
+      error = CQL::Schema::ConnectionError.new("test")
+      error.is_a?(CQL::Schema::Error).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+  end
+
+  describe "SchemaDump errors" do
+    it "SchemaDump::Error inherits from CQL::Error" do
+      error = CQL::SchemaDump::Error.new("test")
+      error.is_a?(CQL::Error).should be_true
+    end
+  end
+
+  describe "Migrator errors" do
+    it "Migrator::Error inherits from CQL::Error" do
+      error = CQL::Migrator::Error.new("test")
+      error.is_a?(CQL::Error).should be_true
+    end
+  end
+
+  describe "Relation errors" do
+    it "RelationError inherits from CQL::Error" do
+      error = CQL::ActiveRecord::Relations::BaseRelation::RelationError.new("test")
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "AssociationNotFound inherits from RelationError and CQL::Error" do
+      error = CQL::ActiveRecord::Relations::BaseRelation::AssociationNotFound.new("test")
+      error.is_a?(CQL::ActiveRecord::Relations::BaseRelation::RelationError).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "InvalidAssociation inherits from RelationError and CQL::Error" do
+      error = CQL::ActiveRecord::Relations::BaseRelation::InvalidAssociation.new("test")
+      error.is_a?(CQL::ActiveRecord::Relations::BaseRelation::RelationError).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+
+    it "UnsavedRecord inherits from RelationError and CQL::Error" do
+      error = CQL::ActiveRecord::Relations::BaseRelation::UnsavedRecord.new("test")
+      error.is_a?(CQL::ActiveRecord::Relations::BaseRelation::RelationError).should be_true
+      error.is_a?(CQL::Error).should be_true
+    end
+  end
+
+  describe "unified error handling" do
+    it "rescue CQL::Error catches Schema::InvalidURIError" do
+      rescued = false
+      begin
+        raise CQL::Schema::InvalidURIError.new("test")
+      rescue CQL::Error
+        rescued = true
+      end
+      rescued.should be_true
+    end
+
+    it "rescue CQL::Error catches SchemaDump::Error" do
+      rescued = false
+      begin
+        raise CQL::SchemaDump::Error.new("test")
+      rescue CQL::Error
+        rescued = true
+      end
+      rescued.should be_true
+    end
+
+    it "rescue CQL::Error catches Migrator::Error" do
+      rescued = false
+      begin
+        raise CQL::Migrator::Error.new("test")
+      rescue CQL::Error
+        rescued = true
+      end
+      rescued.should be_true
+    end
+
+    it "rescue CQL::Error catches RelationError" do
+      rescued = false
+      begin
+        raise CQL::ActiveRecord::Relations::BaseRelation::RelationError.new("test")
+      rescue CQL::Error
+        rescued = true
+      end
+      rescued.should be_true
+    end
+
+    it "rescue CQL::Error catches AssociationNotFound" do
+      rescued = false
+      begin
+        raise CQL::ActiveRecord::Relations::BaseRelation::AssociationNotFound.new("test")
+      rescue CQL::Error
+        rescued = true
+      end
+      rescued.should be_true
+    end
+  end
+end

spec/patterns/active_record/preload_spec.cr

@@ -0,0 +1,56 @@
+require "./spec_helper"
+
+describe "Eager Loading / Preload" do
+  describe "QueryBuilder#preload" do
+    it "returns a new QueryBuilder with preload specs" do
+      builder = TestUser.query.preload(:posts)
+      builder.should be_a(CQL::ActiveRecord::Queryable::QueryBuilder(TestUser))
+    end
+
+    it "chains with where conditions" do
+      builder = TestUser.where(age: 25).preload(:posts)
+      builder.should be_a(CQL::ActiveRecord::Queryable::QueryBuilder(TestUser))
+    end
+
+    it "allows multiple associations to be preloaded" do
+      builder = TestUser.preload(:posts, :profile)
+      builder.should be_a(CQL::ActiveRecord::Queryable::QueryBuilder(TestUser))
+    end
+  end
+
+  describe "Queryable.preload" do
+    it "provides class-level preload method" do
+      builder = TestUser.preload(:posts)
+      builder.should be_a(CQL::ActiveRecord::Queryable::QueryBuilder(TestUser))
+    end
+  end
+
+  describe "Collection#_inject_preloaded" do
+    it "exposes _inject_preloaded method" do
+      # Create the collection manually with dummy values
+      collection = CQL::ActiveRecord::Relations::Collection(Post, Int32).new(
+        key: :user_id,
+        id: 1,
+        auto_load: false
+      )
+
+      # The collection should not be loaded initially
+      collection.loaded?.should be_false
+
+      # Inject empty array (no DB access needed)
+      preloaded_posts = [] of Post
+      collection._inject_preloaded(preloaded_posts)
+
+      # Now the collection should be loaded
+      collection.loaded?.should be_true
+      collection.size.should eq(0)
+    end
+  end
+
+  describe "has_many preload methods" do
+    it "generates _preload_<name> class method" do
+      # Test that the class method exists
+      TestUser.responds_to?(:_preload_posts).should be_true
+    end
+  end
+end

src/active_record/query_builder.cr

@@ -8,13 +8,18 @@ module CQL
       class QueryBuilder(T)
         @query : CQL::Query
         @model_class : T.class
+        @preload_specs : Array(Symbol) = [] of Symbol
 
         # Initialize a new QueryBuilder with the given query
         # - **@param** query [CQL::Query] The underlying query object
         # - **@param** model_class [T.class] The model class
         def initialize(@query : CQL::Query, @model_class : T.class = T)
         end
 
+        # Initialize with preload specs (used internally for cloning)
+        protected def initialize(@query : CQL::Query, @model_class : T.class, @preload_specs : Array(Symbol))
+        end
+
         # Get the model class
         def model_class : T.class
           @model_class
@@ -48,7 +53,7 @@ module CQL
         # Clone the current QueryBuilder and apply modifications
         # - **@return** [QueryBuilder(T)] A new query builder instance
         private def clone_builder : QueryBuilder(T)
-          QueryBuilder(T).new(@query.clone, @model_class)
+          QueryBuilder(T).new(@query.clone, @model_class, @preload_specs.dup)
         end
 
         # Add columns to select
@@ -266,12 +271,64 @@ module CQL
           QueryBuilder(T).new(merged_query, @model_class)
         end
 
+        # Add associations to preload (eager load) to avoid N+1 queries.
+        # Preloaded associations are fetched in separate batch queries after
+        # the main query executes, then injected into the parent records.
+        # - **@param** associations [Symbol*] The association names to preload
+        # - **@return** [QueryBuilder(T)] A new query builder with preload configured
+        #
+        # **Example**
+        # ```
+        # User.preload(:posts).all                     # Preload single association
+        # User.preload(:posts, :comments).all          # Preload multiple associations
+        # User.where(active: true).preload(:posts).all # Chain with where
+        # ```
+        def preload(*associations : Symbol) : QueryBuilder(T)
+          builder = clone_builder
+          associations.each { |assoc| builder.@preload_specs << assoc }
+          builder
+        end
+
         # Execute the query and return all results
+        # When preloads are configured, automatically applies them to the results.
         # - **@return** [Array(T)] Array of model instances
-        def all(as as_kind = T)
+        def all : Array(T)
+          records = @query.all(T)
+          apply_preloads(records) if @preload_specs.any?
+          records
+        end
+
+        # Execute the query and return all results as a custom type
+        # Note: Preloading is not applied when using a custom type.
+        # - **@param** as_kind [Class] The type to deserialize results as
+        # - **@return** [Array] Array of instances of the specified type
+        def all(as as_kind)
           @query.all(as_kind)
         end
 
+        # Apply preloads to the fetched records
+        private def apply_preloads(records : Array(T)) : Nil
+          return if records.empty?
+
+          # Collect parent IDs for batch loading
+          parent_ids = records.compact_map(&.id)
+          return if parent_ids.empty?
+
+          # For each association to preload, call the class method generated by has_many
+          @preload_specs.each do |assoc_name|
+            {% begin %}
+              case assoc_name
+              {% for method in @type.type_vars[0].class.methods %}
+                {% if method.name.starts_with?("_preload_") %}
+                  when {{method.name.stringify.gsub(/^_preload_/, "").id.symbolize}}
+                    T.{{method.name}}(records, parent_ids)
+                {% end %}
+              {% end %}
+              end
+            {% end %}
+          end
+        end
+
         # Execute the query and return the first result
         # - **@return** [T?] First model instance or nil
         def first(as as_kind = T)

src/active_record/queryable.cr

@@ -152,6 +152,21 @@ module CQL
           query.distinct
         end
 
+        # Create a QueryBuilder with associations to preload (eager load).
+        # Preloading fetches associated records in batch queries to avoid N+1 queries.
+        # - **@param** associations [Symbol*] The association names to preload
+        # - **@return** [QueryBuilder(T)] The query builder instance with preload configured
+        #
+        # **Example**
+        # ```
+        # User.preload(:posts).all           # Preload single association
+        # User.preload(:posts, :comments).all # Preload multiple associations
+        # User.where(active: true).preload(:posts).all # Chain with where
+        # ```
+        def self.preload(*associations : Symbol)
+          query.preload(*associations)
+        end
+
         # Execute automatic inner join
         # - **@param** table_or_alias [Symbol | Hash] The table or alias mapping
         # - **@return** [QueryBuilder(T)] The query builder instance

src/active_record/relations/base_relation.cr

@@ -4,7 +4,7 @@ module CQL::ActiveRecord::Relations
   # type safety, and shared behaviors across different association types.
   module BaseRelation
     # Common exception types for relation operations
-    class RelationError < Exception; end
+    class RelationError < CQL::Error; end
 
     class AssociationNotFound < RelationError; end
 

src/active_record/relations/collection.cr

@@ -143,6 +143,16 @@ module CQL::ActiveRecord::Relations
       reload unless @loaded
     end
 
+    # Inject preloaded records without database query
+    # Used by eager loading/preload to set association data that was
+    # loaded in a batch query to avoid N+1 queries.
+    # - **param** : records (Array(Target)) - The preloaded records
+    # - **return** : Nil
+    def _inject_preloaded(records : Array(Target)) : Nil
+      @records = records
+      @loaded = true
+    end
+
     # Returns a list of primary keys for the associated records
     # - **return** : Array(Pk)
     #

src/active_record/relations/has_many.cr

@@ -81,6 +81,53 @@ module CQL::ActiveRecord::Relations
         @{{name.id}} = nil
       end
 
+      # Inject preloaded records into the association without database query.
+      # Used by eager loading/preload to avoid N+1 queries.
+      # - **param** : records (Array({{type.id}})) - The preloaded records for this association
+      # - **return** : Nil
+      def _set_preloaded_{{name.id}}(records : Array({{type.id}})) : Nil
+        parent_id = safe_id(self, Pk)
+
+        @{{name.id}} = CQL::ActiveRecord::Relations::Collection({{type.id}}, Pk).new(
+          key: {{fk}},
+          id: parent_id,
+          cascade: ({{dependent}} == :destroy || {{dependent}} == :delete_all),
+          dependent: {{dependent}},
+          auto_load: false
+        )
+        @{{name.id}}.not_nil!._inject_preloaded(records)
+      end
+
+      # Class method to preload this association for a collection of parent records.
+      # Executes a single query to fetch all related records and distributes them.
+      # - **param** : records (Array(self)) - The parent records
+      # - **param** : parent_ids (Array) - The parent IDs
+      # - **return** : Nil
+      def self._preload_{{name.id}}(records : Array(self), parent_ids : Array) : Nil
+        return if records.empty? || parent_ids.empty?
+
+        # Fetch all related records in one query
+        related_records = {{type.id}}.where({ {{fk}} => parent_ids }).all
+
+        # Group related records by foreign key
+        grouped = {} of Pk => Array({{type.id}})
+        related_records.each do |record|
+          fk_value = record.{{fk.id}}
+          next if fk_value.nil?
+          key = fk_value.as(Pk)
+          grouped[key] ||= [] of {{type.id}}
+          grouped[key] << record
+        end
+
+        # Inject preloaded records into each parent
+        records.each do |parent|
+          parent_id = parent.id
+          next if parent_id.nil?
+          related = grouped[parent_id.as(Pk)]? || [] of {{type.id}}
+          parent._set_preloaded_{{name.id}}(related)
+        end
+      end
+
       # Handle dependent associations when parent is destroyed
       def handle_{{name.id}}_dependency
         return unless @{{name.id}} # Only process if association was accessed

src/migrations.cr

@@ -489,6 +489,6 @@ module CQL
       repo.delete_by(name: migration.name, version: migration.version)
     end
 
-    class Error < Exception; end
+    class Error < CQL::Error; end
   end
 end