activerecord-summarize 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f4063a016e57d85371ba91aa751c223c5830f29bf46a7f693c00af2b808fb48
+  data.tar.gz: c63ee2b1ed0e2c7e39f71125f759a4f933cd56281c414b0e694f8f46511b18f4
+SHA512:
+  metadata.gz: 3252c9e8bc8eb0e5ca6eef4b3a089d68f5f67f17d42824f5478b02181f7a618a9feee961c9636f1b696acc6661975580ab75aef8c9edcc6a08b480eae11ae188
+  data.tar.gz: 062a2d2557969c0ae4fefd6e656dcd5bb8b4981e0b71899a726025fd3c6ef081e085c8c87729c85555cdd3999f58f8daf323f1a2f6b00f59f71b5de6f8a3a78c

data/.standard.yml

@@ -0,0 +1,5 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+# ignore:
+#   - 'lib/**/*':
+#     - Layout/DotPosition

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [0.2.1] - 2022-02-17
+
+- Initial public release
+- Wrap existing groups of related `ActiveRecord` calculations in a `summarize` block for an instant 2-5x speedup
+  - Supports combining all `.count` and `.sum` called on [descendants of] the summarizing relation in a `summarize` block
+  - Supports separate `.where`, `.group`, and custom scopes for any or all calculations in a `summarize` block
+  - Calculation methods return placeholder objects that will be replaced with the true calculation result at the end of the block.
+  - Supports chaining almost any method on the placeholder calculation results
+    - Some methods of `Object` that I haven't tried yet or that are injected into `Object` by other gems may not work, as they won't trigger `method_missing`.
+  - Transparently replaces calculation placeholders that have been saved to local variables in the block's scope or instance variables of the block's execution context
+  - Supports `pure: true` option to skip the step of looking outside the block return value for placeholders
+  - Supports `noop: true` option to disable all `summarize` functionality and just return the original relation
+    - `noop: true` and `noop: false` (default) produce the same final results, just `noop: false` is usually faster
+- Build even more complex queries by using `summarize` on a relation that already has `.group` applied.
+  - Results are grouped just like a standard `.group(*expressions).count`, but instead of single numbers, the values are whatever set of calculations you return from the block, including further `.group(*more).calculate(:sum|:count,*args)` calculations, in whatever `Array` or `Hash` shape you arrange them.
+  - N.b., `pure: true` is implied and required in this mode, and `noop: true` is not possible, since ActiveRecord has no way to do this in the general case without `summarize`.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in activerecord-summarize.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "standard", "~> 1.3"

data/Gemfile.lock

@@ -0,0 +1,65 @@
+PATH
+  remote: .
+  specs:
+    activerecord-summarize (0.2.1)
+      activerecord (>= 5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.2.2)
+      activesupport (= 7.0.2.2)
+    activerecord (7.0.2.2)
+      activemodel (= 7.0.2.2)
+      activesupport (= 7.0.2.2)
+    activesupport (7.0.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    concurrent-ruby (1.1.9)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    minitest (5.15.0)
+    parallel (1.21.0)
+    parser (3.1.1.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.2.1)
+    rexml (3.2.5)
+    rubocop (1.25.1)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.13.2)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.11.0)
+    standard (1.7.2)
+      rubocop (= 1.25.1)
+      rubocop-performance (= 1.13.2)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  activerecord-summarize!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  standard (~> 1.3)
+
+BUNDLED WITH
+   2.3.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Joshua Paine
+
+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,177 @@
+# ActiveRecord::Summarize
+
+## Why `summarize`?
+
+1. Make existing groups of related `ActiveRecord` calculations twice as fast (or more) with minimal code alteration. It's like a `go_faster` block.
+
+2. For more complex reporting requirements, including nested `.group` calls, use `summarize` for fast, legible code that you just couldn't have written before without unacceptable performance or lengthy custom SQL and data-wrangling.
+
+## Installation
+
+Add this line to your Rails application's Gemfile:
+
+```ruby
+gem 'activerecord-summarize'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+#### Suppose your controller method looks like this:
+
+```ruby
+purchases = Purchase.complete
+promotions = purchases.where.not(promotion_id: nil)
+@promotion_sales = promotions.count
+@promotion_revenue = promotions.sum(:amount)
+@by_region = purchases.group(:region_id).count
+```
+
+#### Make it this instead:
+
+```ruby
+Purchase.complete.summarize do |purchases|
+  promotions = purchases.where.not(promotion_id: nil)
+  @promotion_sales = promotions.count
+  @promotion_revenue = promotions.sum(:amount)
+  @by_region = purchases.group(:region_id).count
+end
+```
+#### ...and you'll have exactly the same instance variables set, but only one SQL query will have been executed.
+
+You can run as many calculations in a `summarize` block as it makes sense to run, so long as they all chain to the relation on which you called `summarize`. They can use different, possibly-overlapping subsets of the original relation, i.e., they can have their own `where` clauses and even `group`. The final result of each will be exactly as it would have been if you had run each query independently, but only one query will actually be issued to the database.
+
+### Limitations & details
+
+The only restriction is that each of the queries must be structurally compatible with the parent relation, in the same sense as is required for `relation.or(other)`. So if you wanted to display the region's name, you'd need to group by a sub-select (ew) or do the join at the top level:
+
+```ruby
+Purchase.complete.left_joins(:region).summarize do |purchases|
+  promotions = purchases.where.not(promotion_id: nil)
+  @promotion_sales = promotions.count
+  @promotion_revenue = promotions.sum(:amount)
+  @by_region = purchases.group("regions.name").count
+end
+```
+
+Until the `summarize` block ends, the return value of your calculations are `ChainableResult::Future` instances, a bit like a Promise with a more convenient API. You can call any method you like on a `ChainableResult`, and you'll get back another `ChainableResult`, and they'll all turn out alright in the end—provided you called methods that would have worked if you had run that calculation without `summarize`. OTOH, using a `ChainableResult` as an argument to another method generally will not work.
+
+```ruby
+Purchase.last_quarter.complete.summarize do |purchases|
+  @sales = purchases.sum(:amount)
+  # x * y is syntactic sugar for x.*(y), so this will work:
+  @vc_projection = @sales * 3
+  # And this won't:
+  @vc_projection = 3 * @sales
+end
+```
+
+If, within a `summarize` block, you want to combine data from more than one `ChainableResult`, you must use the otherwise-optional second argument yielded to the block, a `proc` I like to name `with`. Pass it all the results you want to combine and a block that combines them and returns the new result:
+
+```ruby
+Purchase.complete.left_joins(:promotion).summarize do |purchases, with|
+  @all_revenue = purchases.sum(:amount)
+  promotions = purchases.where.not(promotions: {id: nil})
+  @promotion_sales = promotions.count
+  @promotion_discounts = promotions.sum("promotions.discount_amount")
+  @avg_discount = with[@promotion_sales, @promotion_discounts] do |sales, discounts|
+    sales.zero? ? 0 : discounts / sales
+  end
+end
+```
+
+Treat a `with` block as a pure function: i.e., return the value you care about, and don't set or change any other state within the block. Behavior in any other case is undefined.
+
+## Escape hatch
+
+The query generated by `summarize` is often much faster than equivalent queries written without it, but for few-query cases where each query is well-served by its own index, `summarize` could possibly be slower.
+
+By design, every operation performed with `summarize` is correct and corresponds to normal `ActiveRecord` behavior, and any operations that can't be done correctly this way or aren't yet will raise exceptions. But only imperfect humans have worked on this gem, so you might also wonder if `summarize` is producing correct results.
+
+Fortunately, you can easily check both with `summarize(noop: true)`, which causes `summarize` to yield the original relation it was called on and a trivial `with` proc. The block will be executed as though `summarize` were not involved, with each calculation executing separately and immediately returning numbers or hashes.
+
+If you do find any case where you get different results with `summarize(noop: true)`, I'd be grateful if you filed an issue.
+
+## How
+
+`ActiveRecord::Relation#summarize` yields a lightly-modified copy of the relation that intercepts all calls to `sum` or `count` which, instead of a number or hash, return a `ChainableResult::Future`. A `ChainableResult` accepts any method called on it, returning a new `ChainableResult` that will evaluate to the result of running the method on the eventual result of its parent.
+
+At the end of the `summarize` block:
+
+1. All the calculations are combined into a single query.
+2. The results of the query are collected into the same shapes they would have if they had been called independently. E.g., a bare `.count` returns a number, but `.group(*expressions).count` returns a hash with single value (one group expression) or array (two-plus expressions) keys.
+3. Any `ChainableResult` in the return value of the block (usually a single `ChainableResult` or an `Array` or `Hash` with `ChainableResult` values) is replaced with its resolved value.
+4. Any `ChainableResult` in the local scope of the block (i.e., `block.binding`) or an instance variable of the block context (i.e., `block.binding.receiver`) is replaced with its resolved value.
+
+N.b., if you are using `summarize` in a more functional style and will return all values you care about, you can let `summarize` know to skip step 4 by invoking it with `summarize(pure: true)`.
+
+When the parent relation already has `.group` applied, `pure: true` is implied and step 4 does not take place.
+
+## Power usage with `group`
+
+Build even more complex queries by using `summarize` on a relation that already has `.group` applied. Results are grouped just like a standard `.group(*expressions).count`, but instead of single numbers, the values are whatever set of calculations you return from the block, including further `.group(*more).calculate(:sum|:count,*args)` calculations, in whatever `Array` or `Hash` shape you arrange them. For example:
+
+```ruby
+puts Purchase.last_year.complete.group(:region_id).summarize do |purchases,with|
+  total = purchases.count
+  by_quarter = purchases.group(CREATED_TO_YEAR_SQL, CREATED_TO_QUARTER_SQL).count.sort.to_h
+  target = with[total / 4, by_quarter.values.max] {|avg_q, best_q| [avg_q * 1.25, best_q].max.round }
+  {last_year: total, quarters: by_quarter, unit_target: target}
+end
+# Output:
+# {
+#   1 => {
+#     last_year: 2717316,
+#     quarters: {
+#       [2021, 1] => 634057,
+#       [2021, 2] => 590012,
+#       [2021, 3] => 659010,
+#       [2021, 4] => 834237
+#     },
+#     unit_target: 849161
+#   },
+#   2 => { ... },
+#   3 => { ... }
+# }
+```
+
+The ActiveRecord API has no direct analog for this, so `noop: true` is not allowed when `summarize` is called on a grouped relation.
+
+When the relation already has `group` applied, for correct results, `summarize` requires that the block mutate no state and return all values you care about: functional purity, no side effects. `ChainableResult` values referenced by instance variables or local variables not returned from the block won't be evaluated. I.e., `pure: true` is implied and `pure: false` is not allowed. To see why:
+
+```ruby
+# A trivial example:
+Purchase.complete.group(:region_id).summarize {|purchases| purchases.sum(:amount) }
+
+# ...is exactly equivalent to:
+Purchase.complete.group(:region_id).sum(:amount)
+
+# But if there were three regions, what should the value of @target be in this case?
+region_targets = Purchase.last_quarter.complete.group(:region_id).summarize do |purchases|
+  @target = purchases.sum(:amount) * 1.25
+end
+```
+
+As a rubyist, that last example looks like the block will be evaluated for each group, so `@target` should keep whatever value it got the last time the block was run. However:
+
+1. This is not often useful.
+2. The block is not actually linearly evaluated for each group.
+
+Instead the block is evaluated once to determine what calculations need to be run, the query is built and evaluated, and then, for each group of the parent relation, the return value of the block is evaluated with respect to just those rows belonging to the group. In practice this is quite powerful and makes a pleasant, legible API for complex reporting.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. 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/midnightmonster/activerecord-summarize.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]
+task full: %i[test standard:fix]

data/activerecord-summarize.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/activerecord/summarize/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activerecord-summarize"
+  spec.version = ActiveRecord::Summarize::VERSION
+  spec.authors = ["Joshua Paine"]
+  spec.email = ["joshua@letterblock.com"]
+
+  spec.summary = "Run many .count and/or .sum queries in a single efficient query with minimal code changes, even with different .group and only-partly-overlapping .where filters. Nearly-free speedups for mature Rails apps."
+  spec.description = "Just wrap your existing code in `@relation.summarize do |relation| ... end` and run your queries against relation instead of @relation."
+  spec.homepage = "https://letterblock.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/midnightmonster/activerecord-summarize"
+  spec.metadata["changelog_uri"] = "https://github.com/midnightmonster/activerecord-summarize/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_runtime_dependency "activerecord", ">= 5.0"
+  spec.add_development_dependency "rake"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "activerecord/summarize"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/activerecord/summarize/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Summarize
+    VERSION = "0.2.1"
+  end
+end

data/lib/activerecord/summarize.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative "summarize/version"
+require_relative "../chainable_result"
+
+module ActiveRecord::Summarize
+  class Unsummarizable < StandardError; end
+
+  class Summarize
+    attr_reader :current_result_row, :pure, :noop, :from_where
+    alias_method :pure?, :pure
+    alias_method :noop?, :noop
+
+    # noop: true
+    #   causes `summarize` simply to yield the original relation and a trivial,
+    #   synchronous `with` proc. It is meant as a convenient way to test/prove
+    #   the correctness of `summarize` and to compare performance of the single
+    #   combined query vs the original individual queries.
+    #   N.b., if `relation` already has a grouping applied, there is no direct
+    #   ActiveRecord translation for what `summarize` does, so noop: true is
+    #   impossible and raises an exception.
+    # pure: true
+    #   lets `summarize` know that you're not mutating state within the block,
+    #   so it doesn't need to go spelunking in the block binding for
+    #   ChainableResults. See `if !pure?` section below.
+    #   N.b., if `relation` already has a grouping applied, pure: true is
+    #   implied and pure: false throws an exception, as the impure behavior
+    #   would be non-obvious and of doubtful value.
+    def initialize(relation, pure: nil, noop: false)
+      @relation = relation
+      @noop = noop
+      has_base_groups = relation.group_values.any?
+      raise Unsummarizable, "`summarize` must be pure when called on a grouped relation" if pure == false && has_base_groups
+      raise ArgumentError, "`summarize(noop: true)` is impossible on a grouped relation" if noop && has_base_groups
+      @pure = has_base_groups || !!pure
+      @calculations = []
+    end
+
+    def process(&block)
+      # For noop, just yield the original relation and a transparent `with` proc.
+      return yield(@relation, ->(*results, &block) { [*results].then(&block) }) if noop?
+      # Within the block, the relation and its future clones intercept calls to
+      # `count` and `sum`, registering them and returning a ChainableResult via
+      # summarize.add_calculation.
+      future_block_result = ChainableResult.wrap(yield(
+        @relation.unscope(:group).tap do |r|
+          r.instance_variable_set(:@summarize, self)
+          class << r
+            include InstanceMethods
+          end
+        end,
+        ChainableResult::WITH
+      ))
+      ChainableResult.with_cache(!pure?) do
+        # `resolve` builds the single query that answers all collected calculations,
+        # executes it, and aggregates the results by the values of
+        # `@relation.group_values``. In the common case of no `@relation.group_values`,
+        # the result is just `{[]=>[*final_value_for_each_calculation]}`
+        result = resolve.transform_values! do |row|
+          # Each row (in the common case, only one) is used to resolve any
+          # ChainableResults returned by the block. These may be a one-to-one mapping,
+          # or the block return may have combined some results via `with` or chained
+          # additional methods on results, etc..
+          @current_result_row = row
+          future_block_result.value
+        end.then do |result|
+          # Change ungrouped result from `{[]=>v}` to `v` and grouped-by-one-column
+          # result from `{[k1]=>v1,[k2]=>v2,...}` to `{k1=>v1,k2=>v2,...}`.
+          # (Those are both probably more common than multiple-column base grouping.)
+          case @relation.group_values.size
+          when 0 then result.values.first
+          when 1 then result.transform_keys! { |k| k.first }
+          else result
+          end
+        end
+        if !pure?
+          # Check block scope's local vars and block's self's instance vars for
+          # any ChainableResult, and replace it with its resolved value.
+          #
+          # Also check the values of any of those vars that are Hashes, since IME
+          # it's not rare to assign counts to hashes, and it is rare to have giant
+          # hashes that would be particularly wasteful to traverse. Do not do the
+          # same for Arrays, since IME pushing counts to arrays is rare, and large
+          # arrays, e.g., of many eagerly-fetched ActiveRecord objects, are not
+          # rare in controllers.
+          #
+          # Preconditions:
+          # - @current_result_row is still set to the single result row
+          # - we are within a ChainableResult.with_cache(true) block
+          block_binding = block.binding
+          block_self = block_binding.receiver
+          block_binding.local_variables.each do |k|
+            v = block_binding.local_variable_get(k)
+            next block_binding.local_variable_set(k, v.value) if v.is_a?(ChainableResult)
+            lightly_touch_impure_hash(v) if v.is_a?(Hash)
+          end
+          block_self.instance_variables.each do |k|
+            v = block_self.instance_variable_get(k)
+            next block_self.instance_variable_set(k, v.value) if v.is_a?(ChainableResult)
+            lightly_touch_impure_hash(v) if v.is_a?(Hash)
+          end
+        end
+        @current_result_row = nil
+        result
+      end
+    end
+
+    def add_calculation(relation, operation, column_name)
+      merge_from_where!(relation)
+      calculation = CalculationResult.new(relation, operation, column_name)
+      index = @calculations.size
+      @calculations << calculation
+      ChainableResult.wrap(calculation) { current_result_row[index] }
+    end
+
+    def resolve
+      # Build & execute query
+      groups = all_groups
+      # MariaDB, SQLite, and Postgres all support `GROUP BY 1, 2, 3`-style syntax,
+      # where the numbers are 1-indexed references to SELECT values. It makes these
+      # generated queries much shorter and more readable, and it avoids the
+      # ambiguity of using aliases (for GROUP BY, they can get clobbered by columns
+      # from underlying tables) even where those are supported. But in case we find
+      # a database that doesn't support numeric references, the fully-explicit
+      # grouping code is commented out below.
+      #
+      # grouped_query = groups.any? ? from_where.group(*groups) : from_where
+      grouped_query = groups.any? ? from_where.group(*1..groups.size) : from_where
+      data = grouped_query.pluck(*groups, *value_selects)
+
+      # Aggregate & assign results
+      group_idx = groups.each_with_index.to_h
+      starting_values, reducers = @calculations.each_with_index.map do |f, i|
+        value_column = groups.size + i
+        group_columns = f.relation.group_values.map { |k| group_idx[k] }
+        case group_columns.size
+        when 0 then [
+          0,
+          ->(memo, row) { memo + row[value_column] }
+        ]
+        when 1 then [
+          Hash.new(0), # Default 0 makes the reducer much cleaner, but we have to clean it up later
+          ->(memo, row) {
+            memo[row[group_columns[0]]] += row[value_column] unless row[value_column].zero?
+            memo
+          }
+        ]
+        else [
+          Hash.new(0),
+          ->(memo, row) {
+            memo[group_columns.map { |i| row[i] }] += row[value_column] unless row[value_column].zero?
+            memo
+          }
+        ]
+        end
+      end.transpose # For an array of pairs, `transpose` is the reverse of `zip`
+      cols = (0...reducers.size)
+      base_group_columns = (0...base_groups.size)
+      data
+        .group_by { |row| row[base_group_columns] }
+        .tap { |h| h[[]] = [] if h.empty? && base_groups.size.zero? }
+        .transform_values! do |rows|
+          values = starting_values.map(&:dup) # map(&:dup) since some are hashes and we don't want to mutate starting_values
+          rows.each do |row|
+            cols.each do |i|
+              values[i] = reducers[i].call(values[i], row)
+            end
+          end
+          # Set any hash's default back to nil, since callers will expect a normal hash
+          values.each { |v| v.default = nil if v.is_a? Hash }
+        end
+    end
+
+    private
+
+    def compatible_base
+      @compatible_base ||= @relation.except(:select, :group)
+    end
+
+    def merge_from_where!(other)
+      other_from_where = other.except(:select, :group)
+      incompatible_values = compatible_base.send(:structurally_incompatible_values_for, other_from_where)
+      unless incompatible_values.empty?
+        raise Unsummarizable, "Within a `summarize` block, each calculation must be structurally compatible. Incompatible values: #{incompatible_values}"
+      end
+      # Logical OR the criteria of all calculations. Most often this is equivalent
+      # to `compatible_base`, since usually one is a total or grouped count without
+      # additional `where` criteria, but that needn't necessarily be so.
+      @from_where = if @from_where.nil?
+        other_from_where
+      else
+        @from_where.or(other_from_where)
+      end
+    end
+
+    def base_groups
+      @relation.group_values.dup
+    end
+
+    def all_groups
+      # keep all base groups, even if they did something silly like group by
+      # the same key twice, but otherwise don't repeat any groups
+      groups = base_groups
+      groups_set = Set.new(groups)
+      @calculations.map { |f| f.relation.group_values }.flatten.each do |k|
+        next if groups_set.include? k
+        groups_set << k
+        groups << k
+      end
+      groups
+    end
+
+    def value_selects
+      @calculations.map { |f| f.select_value(@relation) }
+    end
+
+    def lightly_touch_impure_hash(h)
+      h.each do |k, v|
+        h[k] = v.value if v.is_a? ChainableResult
+      end
+    end
+  end
+
+  class CalculationResult
+    attr_reader :relation, :method, :column
+
+    def initialize(relation, method, column)
+      @relation = relation
+      @method = method
+      @column = column
+    end
+
+    def select_value(base_relation)
+      where = relation.where_clause - base_relation.where_clause
+      for_select = column
+      for_select = Arel::Nodes::Case.new(where.ast, unmatch_value).when(true, for_select) unless where.empty?
+      function.new([for_select]).tap { |f| f.distinct = relation.distinct_value }
+    end
+
+    def unmatch_value
+      case method
+      when "sum" then 0
+      when "count" then nil
+      else raise "Unknown calculation method"
+      end
+    end
+
+    def function
+      case method
+      when "sum" then Arel::Nodes::Sum
+      when "count" then Arel::Nodes::Count
+      else raise "Unknown calculation method"
+      end
+    end
+  end
+
+  module RelationMethods
+    def summarize(**opts, &block)
+      raise Unsummarizable, "Cannot summarize within a summarize block" if @summarize
+      ActiveRecord::Summarize::Summarize.new(self, **opts).process(&block)
+    end
+  end
+
+  module InstanceMethods
+    private
+
+    def perform_calculation(operation, column_name)
+      case operation = operation.to_s.downcase
+      when "count", "sum"
+        column_name = :id if [nil, "*", :all].include? column_name
+        @summarize.add_calculation(self, operation, aggregate_column(column_name))
+      else super
+      end
+    end
+  end
+end
+
+class ActiveRecord::Base
+  class << self
+    def summarize(**opts, &block)
+      ActiveRecord::Summarize::Summarize.new(all, **opts).process(&block)
+    end
+  end
+end
+
+class ActiveRecord::Relation
+  include ActiveRecord::Summarize::RelationMethods
+end

data/lib/chainable_result.rb

@@ -0,0 +1,111 @@
+class ChainableResult
+  def initialize(source, method = nil, args = [], opts = {}, &block)
+    @source = source
+    @method = method || (block ? :then : :itself)
+    @args = args
+    @opts = opts
+    @block = block
+    @cached = false
+  end
+
+  def value
+    if use_cache?
+      return @value if @cached
+      @cached = true
+      @value = resolve_source.send(@method, *@args, **@opts, &@block)
+    else
+      resolve_source.send(@method, *@args, **@opts, &@block)
+    end
+  end
+
+  def to_json(**opts)
+    ChainableResult::Future.new(self, :to_json, [], opts)
+  end
+
+  def then(&block)
+    ChainableResult::Future.new(self, :then, &block)
+  end
+
+  def yield_self(&block)
+    ChainableResult::Future.new(self, :yield_self, &block)
+  end
+
+  def tap(&block)
+    ChainableResult::Future.new(self, :tap, &block)
+  end
+
+  def method_missing(method, *args, **opts, &block)
+    ChainableResult::Future.new(self, method, args, opts, &block)
+  end
+
+  def respond_to_missing?(method_name, include_private = false)
+    true
+  end
+
+  class Future < self
+    def resolve_source
+      @source.value
+    end
+  end
+
+  class Array < self
+    def resolve_source
+      @source.map(&RESOLVE_ITEM)
+    end
+  end
+
+  class Hash < self
+    def resolve_source
+      @source.transform_values(&RESOLVE_ITEM)
+    end
+  end
+
+  class Other < self
+    def resolve_source
+      @source
+    end
+  end
+
+  def self.wrap(v, method = nil, *args, **opts, &block)
+    method ||= block ? :then : :itself
+    klass = case v
+    when ChainableResult then return v # don't wrap, exit early
+    when ::Array then ChainableResult::Array
+    when ::Hash then ChainableResult::Hash
+    else ChainableResult::Other
+    end
+    klass.new(v, method, args, opts, &block)
+  end
+
+  def self.with(*results, &block)
+    ChainableResult.wrap(results.size == 1 ? results.first : results, :then, &block)
+  end
+
+  WITH = method(:with)
+
+  def self.resolve_item(item)
+    case item
+    when ChainableResult then item.value
+    when ::Array then ChainableResult::Array.new(item).value
+    when ::Hash then ChainableResult::Hash.new(item).value
+    else item
+    end
+  end
+
+  RESOLVE_ITEM = method(:resolve_item)
+  CACHE_MODE_KEY = :"ChainableResult::USE_CACHE"
+
+  def self.with_cache(mode = true)
+    prev = Thread.current[CACHE_MODE_KEY]
+    Thread.current[CACHE_MODE_KEY] = mode
+    result = yield
+    Thread.current[CACHE_MODE_KEY] = prev
+    result
+  end
+
+  private
+
+  def use_cache?
+    !!Thread.current[CACHE_MODE_KEY]
+  end
+end

data/sig/activerecord/summarize.rbs

@@ -0,0 +1,6 @@
+module ActiveRecord
+  module Summarize
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-summarize
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Joshua Paine
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Just wrap your existing code in `@relation.summarize do |relation| ...
+  end` and run your queries against relation instead of @relation.
+email:
+- joshua@letterblock.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- activerecord-summarize.gemspec
+- bin/console
+- bin/setup
+- lib/activerecord/summarize.rb
+- lib/activerecord/summarize/version.rb
+- lib/chainable_result.rb
+- sig/activerecord/summarize.rbs
+homepage: https://letterblock.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://letterblock.com
+  source_code_uri: https://github.com/midnightmonster/activerecord-summarize
+  changelog_uri: https://github.com/midnightmonster/activerecord-summarize/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Run many .count and/or .sum queries in a single efficient query with minimal
+  code changes, even with different .group and only-partly-overlapping .where filters.
+  Nearly-free speedups for mature Rails apps.
+test_files: []