batchagg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b6918b95a0a1d2b8989a596c2f1bcdc5652bf82e8f20fa39ff247ed3d61f52e
+  data.tar.gz: 58df5d2bac16759d9803855dcfaab1c41c952887b0a00a4058bf5ce83af4b6be
+SHA512:
+  metadata.gz: 49a3bea438ae260b9331381bf566726133cfa3b8e2c9a081d5bd3e6afaa62bee9a7893bc0722d18b1c4b7f00cc0590a7c1fdd5c8d0f7fc1ec7c98c8ae480aee8
+  data.tar.gz: b6fecaf5afde6c779b7cc20d37ed73b0e0ff03900fa01e52fff14b3317a53c88913596ad7f5f876cfbba3686bb52cd1f42b3b9cfb42c166f5a8e99f824c0a078

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,64 @@
+plugins:
+- rubocop-rake
+- rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at [INSERT CONTACT
+METHOD]. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JT A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 JT Archie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# BatchAgg
+
+BatchAgg is a Ruby gem for efficiently performing multiple database aggregations
+on ActiveRecord models in a single query. It helps eliminate N+1 query problems
+when calculating counts, sums, averages, and other aggregates across
+associations.
+
+## Purpose
+
+BatchAgg addresses the common issue of needing multiple aggregation values for a
+collection of records without making repeated database queries. It uses
+correlated subqueries to fetch all aggregations in a single efficient database
+call, improving application performance.
+
+## Installation
+
+```ruby
+gem 'batchagg'
+```
+
+## Usage
+
+### Example 1: Aggregations for a single user
+
+```ruby
+include BatchAgg::DSL
+
+# Define the aggregations you need
+user_stats = aggregate(User) do
+  count(:total_posts, &:posts)
+  count(:published_posts) { |user| user.posts.where(status: 'published') }
+  sum(:total_views, :views, &:posts)
+  avg(:avg_rating, :rating, &:posts)
+end
+
+# Get aggregations for a specific user
+user = User.find(1)
+stats = user_stats.only(user)
+
+puts "Total posts: #{stats[user.id].total_posts}"
+puts "Published posts: #{stats[user.id].published_posts}"
+puts "Total views: #{stats[user.id].total_views}"
+puts "Average rating: #{stats[user.id].avg_rating}"
+```
+
+### Example 2: Aggregations for multiple users
+
+```ruby
+include BatchAgg::DSL
+
+# Define the aggregations you need
+user_stats = aggregate(User) do
+  count(:total_posts, &:posts)
+  count(:comments_received) { |user| user.posts.joins(:comments) }
+  string_agg(:post_titles, :title, delimiter: ', ', &:posts)
+  max(:highest_rating, :rating, &:posts)
+end
+
+# Get aggregations for all active users
+active_users = User.where(active: true)
+stats = user_stats.from(active_users)
+
+# Use the aggregated data
+active_users.each do |user|
+  user_stat = stats[user.id]
+  puts "User #{user.name} has #{user_stat.total_posts} posts"
+  puts "Most recent post titles: #{user_stat.post_titles}"
+  puts "Highest rating: #{user_stat.highest_rating}"
+end
+```
+
+## Supported Aggregation Types
+
+- `count`: Count of records
+- `count_distinct`: Count of distinct values for a column
+- `sum`: Sum of a column
+- `avg`: Average of a column
+- `min`: Minimum value of a column
+- `max`: Maximum value of a column
+- `string_agg`: Concatenation of values (GROUP_CONCAT)
+
+You can also use the `_expression` variants of these methods for custom SQL
+expressions.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can
+also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/[USERNAME]/batchagg. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to
+the
+[code of conduct](https://github.com/[USERNAME]/batchagg/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Batchagg project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/[USERNAME]/batchagg/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/batchagg/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BatchAgg
+  VERSION = "0.1.0"
+end

data/lib/batchagg.rb

@@ -0,0 +1,736 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module BatchAgg
+  # Represents a single aggregate function definition
+  class AggregateDefinition
+    attr_reader :name, :type, :block, :column, :expression, :options
+
+    def initialize(name, type, block, column = nil, expression = nil, options = nil)
+      @name = name
+      @type = type
+      @block = block
+      @column = column
+      @expression = expression
+      @options = options
+    end
+
+    def column_based?
+      type == :column
+    end
+
+    def computed?
+      type == :computed
+    end
+
+    def block?
+      !block.nil?
+    end
+  end
+
+  # Handles association traversal for correlated subqueries
+  class AssociationResolver
+    def initialize(base_model_class, outer_table_alias)
+      @base_model_class = base_model_class
+      @outer_table_alias = outer_table_alias
+    end
+
+    def resolve_association(association_name)
+      reflection = find_association_reflection(association_name)
+      target_class = reflection.klass
+      correlation_condition = build_correlation_condition(reflection)
+
+      target_class.where(correlation_condition)
+    end
+
+    def association?(association_name)
+      @base_model_class.reflect_on_association(association_name).present?
+    end
+
+    private
+
+    def find_association_reflection(association_name)
+      reflection = @base_model_class.reflect_on_association(association_name)
+      raise NoMethodError, "Association '#{association_name}' not found" unless reflection
+
+      reflection
+    end
+
+    def build_correlation_condition(reflection)
+      if reflection.through_reflection
+        build_has_many_through_condition(reflection)
+      elsif belongs_to_association?(reflection)
+        build_belongs_to_condition(reflection)
+      else # has_many or has_one (direct)
+        build_has_many_condition(reflection)
+      end
+    end
+
+    def belongs_to_association?(reflection)
+      reflection.macro == :belongs_to
+    end
+
+    def build_belongs_to_condition(reflection)
+      target_table = reflection.klass.arel_table
+      foreign_key_column = @outer_table_alias[reflection.foreign_key]
+      primary_key_column = target_table[reflection.association_primary_key]
+
+      primary_key_column.eq(foreign_key_column)
+    end
+
+    def build_has_many_condition(reflection)
+      target_table = reflection.klass.arel_table
+      foreign_key_column = target_table[reflection.foreign_key]
+      primary_key_column = @outer_table_alias[reflection.active_record_primary_key]
+
+      foreign_key_column.eq(primary_key_column)
+    end
+
+    def build_has_many_through_condition(reflection)
+      through_reflection = reflection.through_reflection
+      source_reflection = reflection.source_reflection
+
+      final_target_table = reflection.klass.arel_table
+      through_table = through_reflection.klass.arel_table
+
+      # Condition 1: Links the through_table to the final_target_table
+      # Based on source_reflection (e.g., Appointment.belongs_to :patient)
+      cond1_arel = if source_reflection.macro == :belongs_to
+                     through_table[source_reflection.foreign_key].eq(final_target_table[source_reflection.association_primary_key])
+                   else # :has_many, :has_one
+                     final_target_table[source_reflection.foreign_key].eq(through_table[source_reflection.active_record_primary_key])
+                   end
+
+      # Condition 2: Links the through_table to the @outer_table_alias (base model)
+      # Based on through_reflection (e.g., Physician.has_many :appointments)
+      cond2_arel = if through_reflection.macro == :belongs_to
+                     @outer_table_alias[through_reflection.foreign_key].eq(through_table[through_reflection.association_primary_key])
+                   else # :has_many, :has_one
+                     through_table[through_reflection.foreign_key].eq(@outer_table_alias[through_reflection.active_record_primary_key])
+                   end
+
+      subquery = through_table.project(Arel.sql("1"))
+                              .where(cond1_arel.and(cond2_arel))
+      subquery.exists
+    end
+  end
+
+  # Provides method_missing interface for association access in aggregate blocks
+  class CorrelatedRelationBuilder
+    def initialize(base_model_class, outer_table_alias)
+      @association_resolver = AssociationResolver.new(base_model_class, outer_table_alias)
+    end
+
+    def method_missing(association_name, *args, &block_arg)
+      validate_method_call(association_name, args, block_arg)
+      @association_resolver.resolve_association(association_name)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @association_resolver.association?(method_name) || super
+    end
+
+    private
+
+    def validate_method_call(association_name, args, block_arg)
+      return unless args.any? || block_arg
+
+      raise ArgumentError,
+            "Unexpected arguments or block for association '#{association_name}' in aggregate definition."
+    end
+  end
+
+  # Provides access to outer table attributes in aggregate blocks
+  class OuterTableAttributeAccessor
+    def initialize(outer_table_alias, base_model_class)
+      @outer_table_alias = outer_table_alias
+      @base_model_class = base_model_class
+    end
+
+    def method_missing(method_name, *args, &block_arg)
+      return super unless valid_attribute_access?(method_name, args, block_arg)
+
+      @outer_table_alias[method_name]
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      column?(method_name) || super
+    end
+
+    private
+
+    def valid_attribute_access?(method_name, args, block_arg)
+      args.empty? && block_arg.nil? && column?(method_name)
+    end
+
+    def column?(method_name)
+      @base_model_class.columns_hash.key?(method_name.to_s)
+    end
+  end
+
+  # Handles building SQL projections for column aggregates
+  class ColumnProjectionBuilder
+    def initialize(outer_table_alias, base_model_class)
+      @outer_table_alias = outer_table_alias
+      @attribute_accessor = OuterTableAttributeAccessor.new(outer_table_alias, base_model_class)
+    end
+
+    def build_projection(aggregate_def, correlation_builder)
+      if aggregate_def.block?
+        build_block_based_projection(aggregate_def, correlation_builder)
+      else
+        build_direct_attribute_projection(aggregate_def)
+      end
+    end
+
+    private
+
+    def build_direct_attribute_projection(aggregate_def)
+      @outer_table_alias[aggregate_def.column].as(aggregate_def.name.to_s)
+    end
+
+    def build_block_based_projection(aggregate_def, correlation_builder)
+      if (aliased_attribute_projection = try_aliased_attribute(aggregate_def))
+        aliased_attribute_projection
+      else
+        build_subquery_projection(aggregate_def, correlation_builder)
+      end
+    end
+
+    def try_aliased_attribute(aggregate_def)
+      value = aggregate_def.block.call(@attribute_accessor)
+      return nil unless arel_attribute_or_literal?(value)
+
+      value.as(aggregate_def.name.to_s)
+    rescue NoMethodError, ArgumentError
+      nil
+    end
+
+    def arel_attribute_or_literal?(value)
+      value.is_a?(Arel::Attributes::Attribute) || value.is_a?(Arel::Nodes::SqlLiteral)
+    end
+
+    def build_subquery_projection(aggregate_def, correlation_builder)
+      relation = aggregate_def.block.call(correlation_builder)
+      validate_subquery_relation(relation, aggregate_def.name)
+
+      subquery_sql = relation.to_sql
+      Arel.sql("(#{subquery_sql})").as(aggregate_def.name.to_s)
+    rescue StandardError => e
+      raise ArgumentError,
+            "Block for column aggregate '#{aggregate_def.name}' failed. " \
+            "Not a valid aliased attribute or subquery. Error: #{e.message}"
+    end
+
+    def validate_subquery_relation(relation, aggregate_name)
+      return if relation.is_a?(ActiveRecord::Relation)
+
+      raise ArgumentError,
+            "Block for column subquery '#{aggregate_name}' must return an ActiveRecord::Relation. " \
+            "Got: #{relation.class}"
+    end
+  end
+
+  # Builds SQL for aggregate functions (count, sum, etc.)
+  class AggregateSubqueryBuilder
+    def build_subquery_sql(relation, aggregate_def)
+      base_query = relation.except(:select)
+
+      case aggregate_def.type
+      when :count
+        build_count_query(base_query)
+      when :count_expression
+        build_count_expression_query(base_query, aggregate_def.expression)
+      when :count_distinct
+        build_count_distinct_query(base_query, aggregate_def.column)
+      when :count_distinct_expression
+        build_count_distinct_expression_query(base_query, aggregate_def.expression)
+      when :sum
+        build_sum_query(base_query, aggregate_def.column)
+      when :sum_expression
+        build_sum_expression_query(base_query, aggregate_def.expression)
+      when :avg
+        build_avg_query(base_query, aggregate_def.column)
+      when :avg_expression
+        build_avg_expression_query(base_query, aggregate_def.expression)
+      when :min
+        build_min_query(base_query, aggregate_def.column)
+      when :min_expression
+        build_min_expression_query(base_query, aggregate_def.expression)
+      when :max
+        build_max_query(base_query, aggregate_def.column)
+      when :max_expression
+        build_max_expression_query(base_query, aggregate_def.expression)
+      when :string_agg
+        build_string_agg_query(base_query, aggregate_def.column, aggregate_def.options)
+      when :string_agg_expression
+        build_string_agg_expression_query(base_query, aggregate_def.expression, aggregate_def.options)
+      else
+        raise ArgumentError, "Unsupported aggregate type: #{aggregate_def.type}"
+      end
+    end
+
+    private
+
+    def build_count_query(base_query)
+      base_query.select(Arel.star.count).to_sql
+    end
+
+    def build_count_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COUNT(#{expression})")).to_sql
+    end
+
+    def build_count_distinct_query(base_query, column)
+      table = base_query.model.arel_table
+      base_query.select(table[column].count(true)).to_sql
+    end
+
+    def build_count_distinct_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COUNT(DISTINCT #{expression})")).to_sql
+    end
+
+    def build_sum_query(base_query, column)
+      table = base_query.model.arel_table
+      sum_agg = table[column].sum
+      coalesced_sum = Arel::Nodes::NamedFunction.new("COALESCE", [sum_agg, Arel::Nodes.build_quoted(0)])
+      base_query.select(coalesced_sum).to_sql
+    end
+
+    def build_sum_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COALESCE(SUM(#{expression}), 0)")).to_sql
+    end
+
+    def build_avg_query(base_query, column)
+      table = base_query.model.arel_table
+      avg_agg = table[column].average
+      coalesced_avg = Arel::Nodes::NamedFunction.new("COALESCE", [avg_agg, Arel::Nodes.build_quoted(0.0)])
+      base_query.select(coalesced_avg).to_sql
+    end
+
+    def build_avg_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COALESCE(AVG(#{expression}), 0.0)")).to_sql
+    end
+
+    def build_min_query(base_query, column)
+      table = base_query.model.arel_table
+      min_agg = table[column].minimum
+      coalesced_min = Arel::Nodes::NamedFunction.new("COALESCE", [min_agg, Arel::Nodes.build_quoted(0)])
+      base_query.select(coalesced_min).to_sql
+    end
+
+    def build_min_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COALESCE(MIN(#{expression}), 0)")).to_sql
+    end
+
+    def build_max_query(base_query, column)
+      table = base_query.model.arel_table
+      max_agg = table[column].maximum
+      coalesced_max = Arel::Nodes::NamedFunction.new("COALESCE", [max_agg, Arel::Nodes.build_quoted(0)])
+      base_query.select(coalesced_max).to_sql
+    end
+
+    def build_max_expression_query(base_query, expression)
+      base_query.select(Arel.sql("COALESCE(MAX(#{expression}), 0)")).to_sql
+    end
+
+    def build_string_agg_query(base_query, column, options)
+      table = base_query.model.arel_table
+      delimiter = options&.dig(:delimiter)
+
+      args = [table[column]]
+      args << Arel::Nodes.build_quoted(delimiter) if delimiter
+
+      base_query.select(Arel::Nodes::NamedFunction.new("GROUP_CONCAT", args)).to_sql
+    end
+
+    def build_string_agg_expression_query(base_query, expression, options)
+      delimiter = options&.dig(:delimiter)
+
+      args = [Arel.sql(expression)]
+      args << Arel::Nodes.build_quoted(delimiter) if delimiter
+
+      base_query.select(Arel::Nodes::NamedFunction.new("GROUP_CONCAT", args)).to_sql
+    end
+  end
+
+  # Handles applying WHERE conditions from scope to outer table alias
+  class ScopeConditionApplier
+    def initialize(base_model, outer_table_alias)
+      @base_model = base_model
+      @outer_table_alias = outer_table_alias
+    end
+
+    def apply_conditions_to_query(arel_query, scope)
+      processed_columns = apply_simple_where_conditions(arel_query, scope)
+      apply_arel_where_conditions(arel_query, scope, processed_columns)
+    end
+
+    private
+
+    def apply_simple_where_conditions(arel_query, scope)
+      processed_columns = []
+
+      return processed_columns unless scope.respond_to?(:where_values_hash)
+      return processed_columns unless scope.where_values_hash.is_a?(Hash)
+
+      scope.where_values_hash.each do |column_name, value|
+        column_name_str = column_name.to_s
+
+        if model_column?(column_name_str)
+          arel_query.where(@outer_table_alias[column_name.to_sym].eq(value))
+          processed_columns << column_name_str
+        end
+      end
+
+      processed_columns
+    end
+
+    def apply_arel_where_conditions(arel_query, scope, processed_columns)
+      where_clauses = extract_where_clauses(scope)
+
+      where_clauses.each do |constraint|
+        next unless simple_table_constraint?(constraint, processed_columns)
+
+        apply_constraint_to_query(arel_query, constraint)
+      end
+    end
+
+    def extract_where_clauses(scope)
+      scope.arel.ast.cores.flat_map(&:wheres)
+    end
+
+    def simple_table_constraint?(constraint, processed_columns)
+      return false unless constraint.left.is_a?(Arel::Attributes::Attribute)
+      return false unless constraint.left.relation.name == @base_model.table_name
+      return false if processed_columns.include?(constraint.left.name.to_s)
+
+      true
+    end
+
+    def apply_constraint_to_query(arel_query, constraint)
+      if constraint.is_a?(Arel::Nodes::Equality)
+        apply_equality_constraint(arel_query, constraint)
+      elsif constraint.is_a?(Arel::Nodes::In)
+        apply_in_constraint(arel_query, constraint)
+      end
+    end
+
+    def apply_equality_constraint(arel_query, constraint)
+      column_name = constraint.left.name
+      value = constraint.right
+      arel_query.where(@outer_table_alias[column_name].eq(value))
+    end
+
+    def apply_in_constraint(arel_query, constraint)
+      column_name = constraint.left.name
+      values = extract_in_clause_values(constraint.right)
+      arel_query.where(@outer_table_alias[column_name].in(values))
+    end
+
+    def extract_in_clause_values(right_operand)
+      return right_operand unless right_operand.is_a?(Array)
+
+      right_operand.map do |value|
+        value.is_a?(Arel::Nodes::BindParam) ? value.value.value_before_type_cast : value
+      end
+    end
+
+    def model_column?(column_name)
+      @base_model.columns_hash.key?(column_name)
+    end
+  end
+
+  # Main query builder that orchestrates the SQL generation
+  class QueryBuilder
+    def initialize(base_model)
+      @base_model = base_model
+      @subquery_builder = AggregateSubqueryBuilder.new
+    end
+
+    def build_query_for_scope(scope, aggregates)
+      outer_table_alias = create_outer_table_alias
+      builders = create_helper_builders(outer_table_alias)
+
+      arel_query = create_base_query(scope, outer_table_alias)
+      # Filter out computed aggregates before building SQL projections
+      sql_aggregates = aggregates.reject(&:computed?)
+      add_projections_to_query(arel_query, sql_aggregates, builders, outer_table_alias)
+      apply_scope_conditions(arel_query, scope, outer_table_alias)
+
+      arel_query
+    end
+
+    private
+
+    def create_outer_table_alias
+      @base_model.arel_table.alias("batchagg_outer_#{@base_model.table_name}")
+    end
+
+    def create_helper_builders(outer_table_alias)
+      {
+        correlation: CorrelatedRelationBuilder.new(@base_model, outer_table_alias),
+        column_projection: ColumnProjectionBuilder.new(outer_table_alias, @base_model)
+      }
+    end
+
+    def create_base_query(scope, outer_table_alias)
+      arel_query = Arel::SelectManager.new(scope.klass.connection)
+      arel_query.from(outer_table_alias)
+
+      primary_key_projection = outer_table_alias[@base_model.primary_key].as(@base_model.primary_key.to_s)
+      arel_query.project(primary_key_projection)
+
+      arel_query
+    end
+
+    def add_projections_to_query(arel_query, aggregates, builders, _outer_table_alias)
+      aggregates.each do |aggregate_def|
+        # At this point, aggregate_def should not be a computed? one due to filtering above
+        projection = build_projection_for_aggregate(aggregate_def, builders)
+        arel_query.project(projection)
+      end
+    end
+
+    def build_projection_for_aggregate(aggregate_def, builders)
+      if aggregate_def.column_based?
+        builders[:column_projection].build_projection(aggregate_def, builders[:correlation])
+      else
+        build_aggregate_function_projection(aggregate_def, builders[:correlation])
+      end
+    end
+
+    def build_aggregate_function_projection(aggregate_def, correlation_builder)
+      correlated_relation = aggregate_def.block.call(correlation_builder)
+      subquery_sql = @subquery_builder.build_subquery_sql(correlated_relation, aggregate_def)
+      Arel.sql("(#{subquery_sql})").as(aggregate_def.name.to_s)
+    end
+
+    def apply_scope_conditions(arel_query, scope, outer_table_alias)
+      condition_applier = ScopeConditionApplier.new(@base_model, outer_table_alias)
+      condition_applier.apply_conditions_to_query(arel_query, scope)
+    end
+  end
+
+  # Handles type casting of primary key values for hash keys
+  class PrimaryKeyTypeConverter
+    def self.cast_for_hash_key(id_value, model_class)
+      primary_key_column = find_primary_key_column(model_class)
+      type_converter = create_type_converter(primary_key_column)
+      type_converter.deserialize(id_value)
+    end
+
+    def self.find_primary_key_column(model_class)
+      model_class.columns_hash[model_class.primary_key]
+    end
+
+    def self.create_type_converter(primary_key_column)
+      ActiveRecord::Type.lookup(
+        primary_key_column.type,
+        limit: primary_key_column.limit,
+        precision: primary_key_column.precision,
+        scale: primary_key_column.scale
+      )
+    end
+  end
+
+  # Represents aggregate results for a single record
+  class AggregateResultForRecord
+    def initialize(row_data, all_aggregate_definitions)
+      @data = symbolize_keys(row_data)
+      @all_aggregate_definitions = all_aggregate_definitions
+      @computed_cache = {}
+
+      sql_aggregate_definitions = @all_aggregate_definitions.reject(&:computed?)
+      define_sql_aggregate_methods(sql_aggregate_definitions)
+
+      computed_aggregate_definitions = @all_aggregate_definitions.select(&:computed?)
+      define_computed_aggregate_methods(computed_aggregate_definitions)
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+
+    def define_sql_aggregate_methods(sql_aggregate_definitions)
+      sql_aggregate_definitions.each do |aggregate_def|
+        define_singleton_method(aggregate_def.name) do
+          @data[aggregate_def.name]
+        end
+      end
+    end
+
+    def define_computed_aggregate_methods(computed_aggregate_definitions)
+      computed_aggregate_definitions.each do |aggregate_def|
+        define_singleton_method(aggregate_def.name) do
+          return @computed_cache[aggregate_def.name] if @computed_cache.key?(aggregate_def.name)
+
+          value = instance_exec(self, &aggregate_def.block)
+          @computed_cache[aggregate_def.name] = value
+          value
+        end
+      end
+    end
+  end
+
+  # Orchestrates query execution and result processing
+  class AggregateResultProcessor
+    def initialize(aggregates, base_model)
+      @aggregates = aggregates
+      @base_model = base_model
+      @query_builder = QueryBuilder.new(base_model)
+    end
+
+    def process_single_record(record)
+      scope = create_single_record_scope(record)
+      process_scope(scope)
+    end
+
+    def process_scope(scope)
+      query_results = execute_query(scope)
+      convert_results_to_hash(query_results, scope.klass)
+    end
+
+    private
+
+    def create_single_record_scope(record)
+      @base_model.where(@base_model.primary_key => record.id)
+    end
+
+    def execute_query(scope)
+      query_arel = @query_builder.build_query_for_scope(scope, @aggregates)
+      scope.klass.connection.select_all(query_arel.to_sql).to_a
+    end
+
+    def convert_results_to_hash(query_results, model_class)
+      query_results.each_with_object({}) do |row_hash, result_hash|
+        record_id = extract_and_cast_record_id(row_hash, model_class)
+        result_hash[record_id] = AggregateResultForRecord.new(row_hash, @aggregates)
+      end
+    end
+
+    def extract_and_cast_record_id(row_hash, model_class)
+      raw_id = row_hash[@base_model.primary_key.to_s]
+      PrimaryKeyTypeConverter.cast_for_hash_key(raw_id, model_class)
+    end
+  end
+
+  # Main class that provides the public API for aggregate results
+  class AggregateResultClass
+    def initialize(aggregates, base_model)
+      @processor = AggregateResultProcessor.new(aggregates, base_model)
+    end
+
+    def only(record)
+      @processor.process_single_record(record)
+    end
+
+    def from(scope)
+      @processor.process_scope(scope)
+    end
+  end
+
+  # Builder for creating aggregate definitions using DSL methods
+  class AggregateDefinitionCollector
+    def initialize
+      @aggregates = []
+    end
+
+    def column(name, &block)
+      add_aggregate(:column, name, block, column: name)
+    end
+
+    def count(name, &block)
+      add_aggregate(:count, name, block)
+    end
+
+    def count_distinct(name, column, &block)
+      add_aggregate(:count_distinct, name, block, column: column)
+    end
+
+    def count_expression(name, expression, &block)
+      add_aggregate(:count_expression, name, block, expression: expression)
+    end
+
+    def count_distinct_expression(name, expression, &block)
+      add_aggregate(:count_distinct_expression, name, block, expression: expression)
+    end
+
+    def sum(name, column, &block)
+      add_aggregate(:sum, name, block, column: column)
+    end
+
+    def sum_expression(name, expression, &block)
+      add_aggregate(:sum_expression, name, block, expression: expression)
+    end
+
+    def avg(name, column, &block)
+      add_aggregate(:avg, name, block, column: column)
+    end
+
+    def avg_expression(name, expression, &block)
+      add_aggregate(:avg_expression, name, block, expression: expression)
+    end
+
+    def min(name, column, &block)
+      add_aggregate(:min, name, block, column: column)
+    end
+
+    def min_expression(name, expression, &block)
+      add_aggregate(:min_expression, name, block, expression: expression)
+    end
+
+    def max(name, column, &block)
+      add_aggregate(:max, name, block, column: column)
+    end
+
+    def max_expression(name, expression, &block)
+      add_aggregate(:max_expression, name, block, expression: expression)
+    end
+
+    def string_agg(name, column, delimiter: nil, &block)
+      add_aggregate(:string_agg, name, block, column: column, options: { delimiter: delimiter })
+    end
+
+    def string_agg_expression(name, expression, delimiter: nil, &block)
+      add_aggregate(:string_agg_expression, name, block, expression: expression, options: { delimiter: delimiter })
+    end
+
+    def computed(name, &block)
+      add_aggregate(:computed, name, block)
+    end
+
+    attr_reader :aggregates
+
+    private
+
+    def add_aggregate(type, name, block, column: nil, expression: nil, options: nil)
+      @aggregates << AggregateDefinition.new(name, type, block, column, expression, options)
+    end
+  end
+
+  # Main builder that coordinates the DSL and creates the result class
+  class AggregateBuilder
+    def initialize(base_model)
+      @base_model = base_model
+    end
+
+    def build_class(&)
+      collector = AggregateDefinitionCollector.new
+      collector.instance_eval(&)
+      aggregates = collector.aggregates
+
+      AggregateResultClass.new(aggregates, @base_model)
+    end
+  end
+
+  # Public DSL module
+  module DSL
+    def aggregate(base_model, &)
+      builder = BatchAgg::AggregateBuilder.new(base_model)
+      builder.build_class(&)
+    end
+  end
+end

data/sig/batchagg.rbs

@@ -0,0 +1,6 @@
+module Batchagg
+  VERSION: String
+  module DSL
+    def aggregate: (untyped base_model) { () -> void } -> AggregateResultClass
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: batchagg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JT Archie
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: BatchAgg eliminates N+1 query problems when calculating counts, sums,
+  averages, and other aggregates across associations by using correlated subqueries
+  to fetch all aggregations in a single efficient database call.
+email:
+- jtarchie@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/batchagg.rb
+- lib/batchagg/version.rb
+- sig/batchagg.rbs
+homepage: https://github.com/jtarchie/batchagg.
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jtarchie/batchagg.
+  source_code_uri: https://github.com/jtarchie/batchagg.
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Efficiently perform multiple database aggregations on ActiveRecord models
+  in a single query
+test_files: []