activerecord-summarize 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e87406ae4f6c3aeec411824af98bb21b12457815f24e09f446ed8576bfc1352
-  data.tar.gz: 266e9065f9e49e458fa427d3a82c55eae82eafd983c27a5c8729125c2c75eb57
+  metadata.gz: d3349ef226e79ac7b8182798fbe3f0966a94bd29a5ec31202fe14c74e681bc68
+  data.tar.gz: f257baecb4562c791d0d7648f45ec2549e1ae6faff2cfcd386d95a5e68fb233a
 SHA512:
-  metadata.gz: b515f889c18886602e6a695982ad755bdbb44b38ec93a1422cc92fb0ae9da612e3a7f2854d12c07864bedde52134f121823da201a8f52383564643ca2a7b8e84
-  data.tar.gz: e67437ac8503938c9f6f671fcf7c952aed1998efb045ff6a05a7d2a16e2c50ed7d79519f93b8a0d196cbf7d9d1bd9c23673e51487f7be8de3554cb27dde264fc
+  metadata.gz: fdf0dece89a7d1db578414a1682adb956e8a973c7d575b7d589d0645ef906bdba2f9d849a1833fd1cc10a7b6f1e105c2c36b54532624005d67d8501e1e03aa13
+  data.tar.gz: a21a8e232e86706283954d4690b99c824c80b3521337c2dba10dc3f415f295844670f6d0c4ac94d7a0a8fa58c5fe408a07a64b3d31b65f20086a1d6920409382

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activerecord-summarize (0.4.0)
+    activerecord-summarize (0.5.0)
       activerecord (>= 5.0)
 
 GEM
@@ -65,4 +65,4 @@ DEPENDENCIES
   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
 ```

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.0"
   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,

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
 
@@ -86,8 +96,9 @@ class ChainableResult
     (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.0
 platform: ruby
 authors:
 - Joshua Paine
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-27 00:00:00.000000000 Z
+date: 2023-05-20 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