activerecord-summarize 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e87406ae4f6c3aeec411824af98bb21b12457815f24e09f446ed8576bfc1352
-  data.tar.gz: 266e9065f9e49e458fa427d3a82c55eae82eafd983c27a5c8729125c2c75eb57
+  metadata.gz: f469f566e328d4cc697d23295d95c477f6eb66c5d9246874b36bc59b5fbdcac0
+  data.tar.gz: 7a7315482f217384462c869796531e1ea27511ba1787f435aec1eed754601506
 SHA512:
-  metadata.gz: b515f889c18886602e6a695982ad755bdbb44b38ec93a1422cc92fb0ae9da612e3a7f2854d12c07864bedde52134f121823da201a8f52383564643ca2a7b8e84
-  data.tar.gz: e67437ac8503938c9f6f671fcf7c952aed1998efb045ff6a05a7d2a16e2c50ed7d79519f93b8a0d196cbf7d9d1bd9c23673e51487f7be8de3554cb27dde264fc
+  metadata.gz: 66a61050cec2736eed06d01b5889f85259e0625daa530376fb840f02cb93a041483f335bda4614d2925b9b4d1ae22f811d8fa5d005dad82d559bd1a5d64f0bb5
+  data.tar.gz: b3f3e98e768a019f4c2a32c06d61fb84a50fcbc9f6866df35c1c254ee7d8feb2fd300a286a33cefd6407d12f8e67353348e7e600290ccfb2ae192e9dffd9fd9b

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.5.1] - 2023-08-16
+
+- **BUGFIX:** Starting with version 7.0.5, the behavior of ActiveRecord's `pluck` changed: when you pluck multiple values with the same aggregate function (e.g., `sum`), in PostgreSQL, the data type of the last such value is now applied to all such values, though they used to be inferred correctly. Our solution is to add an explicit alias to each result column.
+
+## [0.5.0] - 2023-05-14
+
+- **FEATURE:** Your `summarize` blocks won't need to accept the proc second argument as often, because `ChainableResult` methods will also resolve their arguments. E.g., `query.summarize {|q| @mult = q.sum(:a) * q.sum(:b) }` now works, where previously you would have needed to write `query.summarize {|q,with| @mult = with[q.sum(:a),q.sum(:b)] {|a,b| a * b } }`.
+
+- **IMPROVEMENT:** The conventional name of the proc provided as an optional second argument to `summarize` blocks is now `with_resolved` instead of `with`. Interactively teaching `activerecord-summarize` to some people showed that this was an improvement in clarity. The local name of the proc has always been under your control (it's your block!), so this doesn't affect anything besides documentation and tests, but if for some reason you accessed the proc at its internal name of `ChainableResult::WITH`, that will still work, too, even though we now refer to it as `ChainableResult::WITH_RESOLVED`.
+
 ## [0.4.0] - 2023-02-27
 
 - **FEATURE:** Support for top-level .group(:belongs_to_association), returning hash with models as keys.

data/Gemfile

@@ -9,5 +9,6 @@ gem "rake", "~> 13.0"
 gem "minitest", "~> 5.0"
 gem "standard", "~> 1.3"
 
-gem "activerecord", "7.0.3"
-gem "sqlite3", "1.4.2"
+gem "activerecord", "7.0.7"
+gem "sqlite3", "1.6.3"
+gem "pg", "~> 1.5"

data/Gemfile.lock

@@ -1,68 +1,86 @@
 PATH
   remote: .
   specs:
-    activerecord-summarize (0.4.0)
+    activerecord-summarize (0.5.1)
       activerecord (>= 5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.0.3)
-      activesupport (= 7.0.3)
-    activerecord (7.0.3)
-      activemodel (= 7.0.3)
-      activesupport (= 7.0.3)
-    activesupport (7.0.3)
+    activemodel (7.0.7)
+      activesupport (= 7.0.7)
+    activerecord (7.0.7)
+      activemodel (= 7.0.7)
+      activesupport (= 7.0.7)
+    activesupport (7.0.7)
       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.10)
-    i18n (1.10.0)
+    concurrent-ruby (1.2.2)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    minitest (5.15.0)
-    parallel (1.21.0)
-    parser (3.1.1.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    lint_roller (1.1.0)
+    minitest (5.19.0)
+    parallel (1.23.0)
+    parser (3.2.2.3)
       ast (~> 2.4.1)
+      racc
+    pg (1.5.3)
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.2.1)
-    rexml (3.2.5)
-    rubocop (1.25.1)
+    regexp_parser (2.8.1)
+    rexml (3.2.6)
+    rubocop (1.52.1)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.2.2.3)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.15.1, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 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)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.29.0)
+      parser (>= 3.2.1.0)
+    rubocop-performance (1.18.0)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    ruby-progressbar (1.11.0)
-    sqlite3 (1.4.2)
-    standard (1.7.2)
-      rubocop (= 1.25.1)
-      rubocop-performance (= 1.13.2)
-    tzinfo (2.0.4)
+    ruby-progressbar (1.13.0)
+    sqlite3 (1.6.3-arm64-darwin)
+    sqlite3 (1.6.3-x86_64-linux)
+    standard (1.30.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.52.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.1.0)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.1.2)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.18.0)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.1.0)
+    unicode-display_width (2.4.2)
 
 PLATFORMS
   arm64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
-  activerecord (= 7.0.3)
+  activerecord (= 7.0.7)
   activerecord-summarize!
   minitest (~> 5.0)
+  pg (~> 1.5)
   rake (~> 13.0)
-  sqlite3 (= 1.4.2)
+  sqlite3 (= 1.6.3)
   standard (~> 1.3)
 
 BUNDLED WITH
-   2.3.3
+   2.4.13

data/README.md

@@ -59,7 +59,7 @@ Purchase.complete.left_joins(:region).summarize do |purchases|
 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.
+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 a method of a non-`ChainableResult` generally will not work.
 
 ```ruby
 Purchase.last_quarter.complete.summarize do |purchases|
@@ -68,24 +68,28 @@ Purchase.last_quarter.complete.summarize do |purchases|
   @vc_projection = @sales * 3
   # And this won't:
   @vc_projection = 3 * @sales
+  # But this will work since v0.5.0...
+  @units_sold = purchases.sum(:units)
+  # ...because methods of `ChainableResult` now resolve their argument(s)
+  @avg_unit_price = @sales / @units_sold
 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:
+If, within a `summarize` block, you want to combine data from more than one `ChainableResult`, you may need to use the otherwise-optional second argument yielded to the block, a `proc` I like to name `with_resolved`. 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|
+Purchase.complete.left_joins(:promotion).summarize do |purchases, with_resolved|
   @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|
+  @avg_discount = with_resolved[@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.
+Treat a `with_resolved` 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
 
@@ -93,7 +97,7 @@ The query generated by `summarize` is often much faster than equivalent queries
 
 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.
+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_resolved` 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.
 
@@ -117,10 +121,10 @@ When the parent relation already has `.group` applied, `pure: true` is implied a
 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|
+puts Purchase.last_year.complete.group(:region_id).summarize do |purchases,with_resolved|
   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 }
+  target = with_resolved[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:
@@ -150,13 +154,13 @@ When the relation already has `group` applied, for correct results, `summarize`
 
 ```ruby
 # A trivial example:
-Purchase.complete.group(:region_id).summarize {|purchases| purchases.sum(:amount) }
+Purchase.complete.group(:region).summarize {|purchases| purchases.sum(:amount) }
 
 # ...is exactly equivalent to:
-Purchase.complete.group(:region_id).sum(:amount)
+Purchase.complete.group(:region).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|
+region_targets = Purchase.last_quarter.complete.group(:region).summarize do |purchases|
   @target = purchases.sum(:amount) * 1.25
 end
 ```
@@ -170,7 +174,9 @@ Instead the block is evaluated once to determine what calculations need to be ru
 
 ## 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.
+Run `bin/setup` to install dependencies. If you don't have PostgreSQL installed, comment out the `pg` line in `Gemfile` first. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Tests and `bin/console` support SQLite and PostgreSQL: (un)comment the appropriate lines at the top of `test/test_data.rb` to choose. In the future, we'll have a nicer solution. If you want to use PostgreSQL, run `CREATE DATABASE summarize_test;` as your default user.
 
 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).
 

data/docs/use_case_moderator_dashboard.md

@@ -69,19 +69,19 @@ def dashboard
   # If you forget, `daily_posts.popular.count` will raise `Unsummarizable` with a helpful message.
   all_posts = Post.where(subreddit: @subreddits.select(:id)).where(created_at: 30.days.ago..)
                   .left_joins(:popularity_threshold_setting).order(:created_at)
-  @subreddit_stats = all_posts.group(:subreddit_id).summarize do |posts, with|
+  @subreddit_stats = all_posts.group(:subreddit_id).summarize do |posts, with_resolved|
     daily_posts = posts.group("posts.created_at::date")
     dow_not_burried = posts.where(karma: 0..).group("EXTRACT(DOW FROM posts.created_at)")
     {
       posts_created: posts.count,
       buried_posts: posts.where(karma: ...0).count,
-      daily_popular_rate: with[
+      daily_popular_rate: with_resolved[
           daily_posts.popular.count,
           daily_posts.count
         ] do |popular, total|
           total.map { |date, count| [date, (popular[date]||0).to_f / count] }.to_h
         end,
-      dow_avg_comments: with[
+      dow_avg_comments: with_resolved[
           dow_not_buried.sum(:comments_count),
           dow_not_buried.count
         ] do |comments, posts|
@@ -94,4 +94,4 @@ end
 
 Since `summarize` runs a single query that visits each relevant `posts` row just once, adding additional calculations is pretty close to free.
 
-Even with the mental overhead of needing to join outside the block and use `with` to combine calculations (see [README](../README.md) for details), I think this is still easy to read, write, and reason about, and it beats the heck out of walls of SQL. What do you think?
+Even with the mental overhead of needing to join outside the block and use `with_resolved` to combine calculations (see [README](../README.md) for details), I think this is still easy to read, write, and reason about, and it beats the heck out of walls of SQL. What do you think?

data/lib/activerecord/summarize/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRecord
   module Summarize
-    VERSION = "0.4.0"
+    VERSION = "0.5.1"
   end
 end

data/lib/activerecord/summarize.rb

@@ -48,8 +48,8 @@ module ActiveRecord::Summarize
     end
 
     def process(&block)
-      # For noop, just yield the original relation and a transparent `with` proc.
-      return yield(@relation, ChainableResult::SYNC_WITH) if noop?
+      # For noop, just yield the original relation and a transparent `with_resolved` proc.
+      return yield(@relation, ChainableResult::SYNC_WITH_RESOLVED) 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.
@@ -60,7 +60,7 @@ module ActiveRecord::Summarize
             include InstanceMethods
           end
         end,
-        ChainableResult::WITH
+        ChainableResult::WITH_RESOLVED
       ))
       ChainableResult.with_cache(!pure?) do
         # `resolve` builds the single query that answers all collected calculations,
@@ -240,7 +240,10 @@ module ActiveRecord::Summarize
     end
 
     def value_selects
-      @calculations.map { |f| f.select_value(@relation) }
+      @calculations.each_with_index.map do |f, i|
+        f.select_value(@relation)
+          .as("_v#{i}") # In Postgres with certain Rails versions, alias is needed to disambiguate result column names for type information
+      end
     end
 
     def lightly_touch_impure_hash(h)

data/lib/chainable_result.rb

@@ -12,9 +12,19 @@ class ChainableResult
     if use_cache?
       return @value if @cached
       @cached = true
-      @value = resolve_source.send(@method, *@args, **@opts, &@block)
+      @value = resolve_source.send(
+        @method,
+        *@args.map(&RESOLVE_ITEM),
+        **@opts.transform_values(&RESOLVE_ITEM),
+        &@block
+      )
     else
-      resolve_source.send(@method, *@args, **@opts, &@block)
+      resolve_source.send(
+        @method,
+        *@args.map(&RESOLVE_ITEM),
+        **@opts.transform_values(&RESOLVE_ITEM),
+        &@block
+      )
     end
   end
 
@@ -78,16 +88,17 @@ class ChainableResult
   end
 
   def self.with(*results, &block)
-    ChainableResult.wrap(results.size == 1 ? results.first : results, :then, &block)
+    ChainableResult.wrap((results.size == 1) ? results.first : results, :then, &block)
   end
 
   def self.sync_with(*results, &block)
     # Non-time-traveling, synchronous version of `with` for testing
-    (results.size == 1 ? results.first : results).then(&block)
+    ((results.size == 1) ? results.first : results).then(&block)
   end
 
-  WITH = method(:with)
-  SYNC_WITH = method(:sync_with)
+  # Shorter names are deprecated
+  WITH_RESOLVED = WITH = method(:with)
+  SYNC_WITH_RESOLVED = SYNC_WITH = method(:sync_with)
 
   def self.resolve_item(item)
     case item

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-summarize
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Joshua Paine
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-27 00:00:00.000000000 Z
+date: 2023-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Run many .count and/or .sum queries in a single efficient query with minimal