counterwise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf86231a128b10c3db267b181bec88ba90bc1cfc07039629a425254cc7d3c612
+  data.tar.gz: 27bc3b7c1140653a2588e48c960c551bdb1a455dee92eb5c276c3e0c9eb55891
+SHA512:
+  metadata.gz: 9f549a07032d2492cc0d4470ebd1e7a5de736f4dceeca90c883b29fb85d60920fc9274c5e0c822f4e07e27768817ccbbe1b9746c2d29e197fa7af1d7f69272f0
+  data.tar.gz: a777ea9f55d06e37e1ecb35af9a0526f9fa7cd51304f8549bb821b0f527020a78fd843c11d31f5110e08e015c43a8856c1f0456571c13ccfad4f13ed81b91eff

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Jamie Lawrence
+
+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,313 @@
+# Counter
+
+[![Tests](https://github.com/podia/counter/actions/workflows/ruby.yml/badge.svg)](https://github.com/podia/counter/actions/workflows/ruby.yml)
+
+Counting and aggregation library for Rails.
+
+- [Counter](#counter)
+  - [Main concepts](#main-concepts)
+  - [Defining a counter](#defining-a-counter)
+  - [Accessing counter values](#accessing-counter-values)
+  - [Anonymous counters](#anonymous-counters)
+  - [Defining a conditional counter](#defining-a-conditional-counter)
+  - [Aggregating a value (e.g. sum of order revenue)](#aggregating-a-value-eg-sum-of-order-revenue)
+  - [Recalculating a counter](#recalculating-a-counter)
+  - [Reset a counter](#reset-a-counter)
+  - [Verify a counter](#verify-a-counter)
+  - [Hooks](#hooks)
+  - [TODO](#todo)
+  - [Usage](#usage)
+  - [Installation](#installation)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+By the time you need Rails counter_caches you probably have other needs too. You probably want to sum column values and you probably have enough throughput that updating a single column value will cause lock contention problems too.
+
+Counter is different from other solutions like [Rails counter caches](https://api.rubyonrails.org/classes/ActiveRecord/CounterCache/ClassMethods.html) and [counter_culture](https://github.com/magnusvk/counter_culture):
+
+- Counters are objects. This makes it possible for them to have an API that allows you to define them, reset, and recalculate them. The definition of a counter is seperate from the value
+- Counters are persisted as a ActiveRecord models (_not_ a column of an existing model)
+- Incrementing counters can be safely performed in a background job via a change event/deferred reconciliation pattern
+- Avoids lock-contention found in other solutions. By storing the value in another object we reduce the contention on the main e.g. User instance. This is only a small improvement though. By using the background change event pattern, we can batch perform the updates reducing the number of processes requiring a lock.
+- Counters can also perform aggregation (e.g. sum of column values instead of counting rows)
+
+
+## Main concepts
+
+![](docs/data_model.png)
+
+`Counter::Definition` defines what the counter is, what model it's connected to, what association it counts, how the count is performed etc. You create a subclass of `Counter::Definition` and call a few class methods to configure it. The definition is available through `counter.definition` for any counter value…
+
+`Counter::Value` is the value of a counter. So, for example, a User might have many Posts, so a User would have a `counters` association containing a `Counter::Value` for the number of posts. Counters can be accessed via their name `user.posts_counter` or via the `find_counter` method on the association, e.g. `user.counters.find_counter PostCounter`
+
+`Counter::Change` is a temporary record that records a change to a counter. Instead of updating a counter directly, which requires obtaining a lock on it to perform it safely and atomically, a new `Change` event is inserted into the table. On regular intervals, the `Counter::Value` is updated by incrementing the value by the sum of all outstanding changes. This requires much less frequent locks at the expense of eventual consistency.
+
+For example, you might have many background jobs running concurrently, inserting hundreds/thousands of rows. The would not need to fight for a lock to update the counter and would only need to insert Counter::Change rows. The counter would then be updated, in a single operation, by summing all the persisted change values.
+
+Basically updating a counter value requires this SQL:
+
+```sql
+UPDATE counter_values
+-- Update the counter with the sum of pending changes
+SET value = value + changes.sum
+FROM (
+  -- Find the pending changes for the counter
+  SELECT sum(value) as sum
+  FROM counter_changes
+  WHERE counter_id = 100
+) as changes
+WHERE id = 100
+```
+
+Or even reconcile all pending counters in a single statement:
+
+```sql
+UPDATE counter_values
+SET value = value + changes.sum
+FROM (
+  SELECT sum(value)
+  FROM counter_changes
+  GROUP BY counter_id
+) as changes
+WHERE counters.id = counter_id
+```
+
+## Defining a counter
+
+Counters are defined in a seperate class using a small DSL.
+
+Given a `Store` with many `Order`s, it would be defined as…
+
+```ruby
+class OrderCounter < Counter::Definition
+  count :orders
+end
+
+class Store < ApplicationRecord
+  include Counter::Counters
+
+  has_many :orders
+  counter OrderCounter
+end
+```
+
+First we define the counter class itself using `count` to specify the association we're counting, then "attach" it to the parent Store model.
+
+By default, the counter will be available as `<association>_counter`, e.g. `store.orders_counter`. To customise this, pass a `as` parameter:
+
+```ruby
+class OrderCounter < Counter::Definition
+  include Counter::Counters
+  count :orders, as: :total_orders
+end
+
+store.total_orders
+```
+
+The counter's value with be stored as a `Counter::Value` with the name prefixed by the model name. e.g. `store_total_orders`
+
+## Accessing counter values
+
+Since counters are represented as objects, you need to call `value` on them to retrieve the count.
+
+```ruby
+store.total_orders        #=> Counter::Value
+store.total_orders.value  #=> 200
+```
+
+## Anonymous counters
+
+Most counters are associated with a model instance and association. These counters are automatically incremented when the associated collection changes  but sometimes you just need a global counter that you can increment.
+
+```ruby
+class GlobalOrderCounter < Counter::Definition
+  global :my_custom_counter_name
+end
+
+GlobalOrderCounter.counter.value #=> 5
+GlobalOrderCounter.counter.increment! #=> 6
+```
+
+## Defining a conditional counter
+
+Consider this model that we'd like to count but we don't want to count all products, just the premium ones with a price >= 1000
+
+```ruby
+class Product < ApplicationRecord
+  include Counter::Counters
+  include Counter::Changable
+
+  belongs_to :user
+
+  scope :premium, -> { where("price >= 1000") }
+
+  def premium?
+    price >= 1000
+  end
+end
+```
+
+Here's the counter to do that:
+
+```ruby
+class PremiumProductCounter < Counter::Definition
+  # Define the association we're counting
+  count :premium_products
+
+  on :create do
+    increment_if ->(product) { product.premium? }
+  end
+
+  on :delete do
+    decrement_if ->(product) { product.premium? }
+  end
+
+  on :update do
+    increment_if ->(product) {
+      product.has_changed? :price, from: ->(price) { price < 1000 }, to: ->(price) { price >= 1000 }
+    }
+
+    decrement_if ->(product) {
+      product.has_changed? :price, from: ->(price) { price >= 1000 }, to: ->(price) { price < 1000 }
+    }
+  end
+end
+```
+
+There is a lot going on here!
+
+First, we define the counter on a scoped association. This ensures that when we call `counter.recalc()` we will count using the association's SQL.
+
+We also define several conditions that operate on the instance level, i.e. when we create/update/delete an instance. On `create` and `delete` we define a block to determine if the counter should be updated. In this case, we only increment the counter when a premium product is created, and only decrement it when a premium product is deleted.
+
+`update` is more complex because there are two scenarios: either a product has been updated to make it premium or  downgrade from premium to some other state. On update, we increment the counter if the price has gone above 1000; and decrement is the price has now gone below 1000.
+
+We use the `has_changed?` helper to query the ActiveRecord `previous_changes` hash and check what has changed. You can specify either Procs or values for `from`/`to`. If you only specify a `from` value, `to` will default to "any value" (Counter::Any.instance)
+
+Conditional counters work best with a single attribute. If the counter is conditional on e.g. confirmed and subscribed, the update tracking logic becomes very complex especially if the values are both updated at the same time. The solution to this is hopefully Rails generated columns in 7.1 so you can store a "subscribed_and_confirmed" column and check the value of that instead. Rails dirty tracking will need to work with generated columns though; see [this PR](https://github.com/rails/rails/pull/48628).
+
+## Aggregating a value (e.g. sum of order revenue)
+
+Given an ActiveRecord model `Order`, we can count a storefront's revenue like so
+
+```ruby
+class Store < ApplicationRecord
+  include Counter::Counters
+
+  counter OrderRevenue
+end
+```
+
+Define the counter like so
+
+```ruby
+class OrderRevenue < Counter::Definition
+  count :orders
+  sum :total_price
+end
+```
+
+and access it like
+
+```ruby
+  store.orders.create total_price: 100
+  store.orders.create total_price: 100
+  store.order_revenue.value #=> 200
+```
+
+## Recalculating a counter
+
+Counters have a habit of drifting over time, particularly if ActiveRecords hooks aren't run (e.g. with a pure SQL data migration) so you need a method of re-counting the metric. Counters make this easy because they are objects in their own right.
+
+You could refresh a store's revenue stats with:
+
+```ruby
+store.order_revenue.recalc!
+```
+
+this would use the definition of the counter, including any option to sum a column. In the case of conditional counters, they are expected to be attached to an association which matched the conditions so the recalculated count remains accurate.
+
+## Reset a counter
+
+You can also reset a counter by calling `reset`. Since counters are ActiveRecord objects, you could also reset them using
+
+```ruby
+store.order_revenue.reset
+Counter::Value.update value: 0
+```
+
+## Verify a counter
+
+You might like to check if a counter is correct
+
+```ruby
+store.product_revenue.correct? #=> false
+```
+
+This will re-count / re-calculate the value and compare it to the current one. If you wish to also update the value when it's not correct, use `correct!`:
+
+```ruby
+store.product_revenue #=>200
+store.product_revenue.reset!
+store.product_revenue #=>0
+store.product_revenue.correct? #=> false
+store.product_revenue.correct! #=> false
+store.product_revenue #=>200
+```
+
+## Hooks
+
+You can add an `after_change` hook to your counter definition to perform some action when the counter is updated. For example, you might want to send a notification when a counter reaches a certain value.
+
+```ruby
+class OrderRevenueCounter < Counter::Definition
+  count :orders, as: :order_revenue
+  sum :price
+
+  after_change :send_congratulations_email
+
+  def send_congratulations_email counter, from, to
+    return unless from < 1000 && to >= 1000
+    send_email "Congratulations! You've made #{to} dollars!"
+  end
+end
+```
+
+---
+
+## TODO
+
+See the asociated project in Github but roughly I'm thinking:
+- Hierarchical counters. For example, a Site sends many Newsletters and each Newsletter results in many EmailMessages. Each EmailMessage can be marked as spam. How do you create counters for how many spam emails were sent at the Newsletter level and the Site level?
+- Time-based counters for analytics. Instead of a User having one OrderRevenue counter, they would have an OrderRevenue counter for each day. These counters would then be used to produce a chart of their product revenue over the month. Not sure if these are just special counters or something else entirely? Do they use the same ActiveRecord model?
+- Can we support floating point values? Sounds useful but don't have a use case for it right now. Would they need to be a different ActiveRecord table?
+- In a similar vein of supporting different value types, can we support HLL values? Instead of increment an integer we add the items hash to a HyperLogLog so we can count unique items. An example would be counting site visits in a time-based daily counter, then combine the daily counts and still obtain an estimated number of monthly _unique_ visits. Again, not sure if this is the same ActiveRecord model or something different.
+- Actually start running this in production for basic use cases
+
+## Usage
+No one has used this in production yet.
+
+You probably shouldn't right now unless you're the sort of person that checks if something is poisonous by licking it.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'counter'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Install the model migrations:
+```bash
+$ rails counter:install:migrations
+```
+
+## Contributing
+Contribution directions go here.
+
+## 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,18 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/counters_controller.rb

@@ -0,0 +1,17 @@
+# A stupid little controller showing how easy you can build generic "counter" functionality
+# when they're represented as a model
+class CountersController < ApplicationController
+  # Reset a counter to 0
+  def destroy
+    Counter::Value.find(params[:id]).reset!
+
+    redirect_back fallback_location: "/"
+  end
+
+  # Recalculate a counter
+  def update
+    Counter::Value.find(params[:id]).recalc!
+
+    redirect_back fallback_location: "/"
+  end
+end

data/app/jobs/counter/reconciliation_job.rb

@@ -0,0 +1,12 @@
+class Counter::ReconciliationJob
+  # include Sidekiq::Worker
+
+  def perform counter_id
+    counter = Counter::Value.find(counter_id)
+    changes = Counter::Change.where(counter: counter).pending
+    changes.with_lock do
+      counter.increment! changes.sum(increment)
+      changes.update_all processed: Time.now
+    end
+  end
+end

data/app/models/concerns/counter/Xhierarchical.rb

@@ -0,0 +1,23 @@
+module Counter::Xhierarchical
+  extend ActiveSupport::Concern
+
+  ########################################################## Support hierarchy of counters
+  # e.g. a open counter for an email > a newsletter > a drip_campaign > a site
+  def counters_to_update
+    [self] + dependant_counters.flat_map { |c| c.counters_to_update }
+  end
+
+  # Override this to add other counters
+  def dependant_counters
+    []
+  end
+
+  def perform_update! increment
+    Counter.increment_all! counters_to_update, by: increment
+  end
+
+  # In a single SQL transaction, increment the counters
+  def self.increment_all! counters, by: 1
+    Counter.lock.where(id: counters).update_all! "value = value + ?, updated_at: NOW()", by
+  end
+end

data/app/models/concerns/counter/changable.rb

@@ -0,0 +1,42 @@
+module Counter::Changable
+  extend ActiveSupport::Concern
+
+  included do
+    def has_changed? attribute, from: Counter::Any, to: Counter::Any
+      from = Counter::Any.instance if from == Counter::Any
+      to = Counter::Any.instance if to == Counter::Any
+
+      return false unless previous_changes.key?(attribute)
+
+      old_value, new_value = previous_changes[attribute]
+
+      # Return true on Counter::any changes
+      return true if from.instance_of?(Counter::Any) && to.instance_of?(Counter::Any)
+
+      from_condition = case from
+      when Counter::Any then true
+      when Proc then from.call(old_value)
+      else
+        from == old_value
+      end
+
+      to_condition = case to
+      when Counter::Any then true
+      when Proc then to.call(new_value)
+      else
+        to == new_value
+      end
+
+      # # Return false if nothing changed
+      # return false if old_value == new_value
+
+      # # Check if the value change from <something>
+      # return new_value == to if from.instance_of?(Any)
+      # # Check if the value change to <something>
+      # return old_value == from if to.instance_of?(Any)
+
+      # Check if the value change from <something> to <something>
+      from_condition && to_condition
+    end
+  end
+end

data/app/models/concerns/counter/conditional.rb

@@ -0,0 +1,32 @@
+module Counter::Conditional
+  extend ActiveSupport::Concern
+
+  included do
+    def increment? item, on
+      accept_item? item, on, increment: true
+    end
+
+    def decrement? item, on
+      accept_item? item, on, increment: false
+    end
+
+    def accept_item? item, on, increment: true
+      return true unless definition.conditional?
+
+      conditions = definition.conditions[on]
+      return true unless conditions
+
+      conditions.any? do |conditions|
+        if increment
+          conditions.increment_conditions.any? do |condition|
+            condition.call(item)
+          end
+        else
+          conditions.decrement_conditions.any? do |condition|
+            condition.call(item)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/counter/definable.rb

@@ -0,0 +1,17 @@
+# Fetch the definition for a counter
+# counter.definition # => Counter::Definition
+module Counter::Definable
+  extend ActiveSupport::Concern
+
+  included do
+    # Fetch the definition for this counter
+    def definition
+      if parent.nil?
+        # We don't have a parent, so we're a global counter
+        Counter::Definition.find_definition name
+      else
+        parent.class.counter_configs.find { |c| c.record_name == name }
+      end
+    end
+  end
+end

data/app/models/concerns/counter/hooks.rb

@@ -0,0 +1,17 @@
+# Allow hooks to be defined on the counter
+module Counter::Hooks
+  extend ActiveSupport::Concern
+
+  included do
+    after_save :call_counter_hooks
+
+    def call_counter_hooks
+      return unless previous_changes["value"]
+
+      from, to = previous_changes["value"]
+      definition.counter_hooks.each do |hook|
+        definition.send(hook, self, from, to)
+      end
+    end
+  end
+end

data/app/models/concerns/counter/increment.rb

@@ -0,0 +1,48 @@
+module Counter::Increment
+  extend ActiveSupport::Concern
+
+  included do
+    def increment! by: 1
+      perform_update! by
+    end
+
+    def decrement! by: 1
+      perform_update!(-by)
+    end
+
+    def perform_update! increment
+      return if increment.zero?
+
+      with_lock do
+        update! value: value + increment
+      end
+    end
+
+    def add_item item
+      return unless increment?(item, :create)
+
+      increment! by: increment_from_item(item)
+    end
+
+    def remove_item item
+      return unless decrement?(item, :delete)
+
+      decrement! by: increment_from_item(item)
+    end
+
+    def update_item item
+      if increment?(item, :update)
+        increment! by: increment_from_item(item)
+      end
+
+      if decrement?(item, :update)
+        decrement! by: increment_from_item(item)
+      end
+    end
+
+    # How much should we increment the counter
+    def increment_from_item item
+      1
+    end
+  end
+end

data/app/models/concerns/counter/recalculatable.rb

@@ -0,0 +1,24 @@
+module Counter::Recalculatable
+  extend ActiveSupport::Concern
+
+  ####################################################### Support for regenerating the counters
+  def recalc!
+    with_lock do
+      new_value = definition.sum? ? sum_by_sql : count_by_sql
+      update! value: new_value
+    end
+  end
+
+  def count_by_sql
+    recalc_scope.count
+  end
+
+  def sum_by_sql
+    recalc_scope.sum(definition.column_to_count)
+  end
+
+  # use this scope when recalculating the value
+  def recalc_scope
+    parent.association(definition.association_name).scope
+  end
+end

data/app/models/concerns/counter/reset.rb

@@ -0,0 +1,11 @@
+module Counter::Reset
+  extend ActiveSupport::Concern
+
+  included do
+    def reset!
+      with_lock do
+        update! value: 0
+      end
+    end
+  end
+end

data/app/models/concerns/counter/sidekiq_reconciliation.rb

@@ -0,0 +1,60 @@
+module Counter::SidekiqReconciliation
+  extend ActiveSupport::Concern
+
+  ########################################################## Support for background reconciliation
+  def add_item item
+    record_counter_change
+    enqueue_reconcilitation_job
+  end
+
+  def update_item item
+    record_counter_change amount: 1
+    enqueue_reconcilitation_job
+  end
+
+  def remove_item item
+    record_counter_change amount: -1
+    enqueue_reconcilitation_job
+  end
+
+  private
+
+  def record_counter_change amount: 1
+    Counter::Change.create! counter: self, increment: amount
+  end
+
+  # Enqueue a Sidekiq job
+  def enqueue_reconcilitation_job
+    Counter::ReconciliationJob.perform_now id
+  end
+
+  def filter_item item, on
+    filtered_items = []
+    filters = @@count_filters[:create] || []
+    filters.all? do |filter|
+      case filter.class
+      when Symbol
+        send filter, items
+      when Proc
+        instance_exec items, filter
+      end
+    end
+  end
+
+  def has_changed? attribute, from: Any.new, to: Any.new
+    old_value, new_value = previous_changes[attribute]
+    # Return true if the attribute changed at all
+    return true if from.instance_of?(Any) && to.instance_of?(Any)
+
+    return new_value == to if from.instance_of?(Any)
+    return old_value == from if to.instance_of?(Any)
+
+    old_value == from && new_value == to
+  end
+
+  class Any
+    include Singleton
+    def initialize
+    end
+  end
+end

data/app/models/concerns/counter/summable.rb

@@ -0,0 +1,15 @@
+# count_using :price
+# count_using ->{ revenue * priority }
+# This lets you keep running totals of revenue etc rather than just a count of the orders
+module Counter::Summable
+  extend ActiveSupport::Concern
+
+  included do
+    # Replace Increment#increment_from_item
+    def increment_from_item item
+      return item.send definition.column_to_count if definition.sum?
+
+      1
+    end
+  end
+end

data/app/models/concerns/counter/verifyable.rb

@@ -0,0 +1,14 @@
+module Counter::Verifyable
+  extend ActiveSupport::Concern
+
+  def correct?
+    count_by_sql == value
+  end
+
+  def correct!
+    requires_recalculation = !correct?
+    recalc! if requires_recalculation
+
+    !requires_recalculation
+  end
+end

data/app/models/counter/change.rb

@@ -0,0 +1,23 @@
+# == Schema Information
+#
+# Table name: counter_changes
+#
+#  id               :integer          not null, primary key
+#  counter_value_id :integer          indexed
+#  amount           :integer
+#  processed_at     :datetime         indexed
+#  created_at       :datetime         not null
+#  updated_at       :datetime         not null
+#
+class Counter::Change < ApplicationRecord
+  def self.table_name_prefix
+    "counter_"
+  end
+
+  belongs_to :counter, class_name: "Counter::Value"
+  validates_numericality_of :amount
+
+  scope :pending, -> { where(reconciled_at: nil) }
+  scope :reconciled, -> { where.not(reconciled_at: nil) }
+  scope :purgable, -> { reconciled.where(processed_at: 7.days.ago..) }
+end

data/app/models/counter/value.rb

@@ -0,0 +1,47 @@
+# == Schema Information
+#
+# Table name: counter_values
+#
+#  id          :integer          not null, primary key
+#  type        :string           indexed
+#  name        :string           indexed
+#  value       :integer          default(0)
+#  parent_type :string           indexed => [parent_id]
+#  parent_id   :integer          indexed => [parent_type]
+#  created_at  :datetime         not null
+#  updated_at  :datetime         not null
+#
+class Counter::Value < ApplicationRecord
+  def self.table_name_prefix
+    "counter_"
+  end
+
+  belongs_to :parent, polymorphic: true, optional: true
+
+  validates_numericality_of :value
+
+  def self.find_counter counter
+    counter_name = if counter.is_a?(String) || counter.is_a?(Symbol)
+      counter.to_s
+    elsif counter.is_a?(Class) && counter.ancestors.include?(Counter::Definition)
+      definition = counter.instance
+      raise "Unable to find counter #{definition.name} via Counter::Value.find_counter. Use must use #{definition.model}#find_counter}" unless definition.global?
+
+      counter.instance.record_name
+    else
+      counter.to_s
+    end
+
+    find_or_initialize_by name: counter_name
+  end
+
+  include Counter::Definable
+  include Counter::Hooks
+  include Counter::Increment
+  include Counter::Reset
+  include Counter::Recalculatable
+  include Counter::Verifyable
+  include Counter::Summable
+  include Counter::Conditional
+  # include Counter::Hierarchical
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  resources :counters, only: [:update, :destroy]
+end

data/db/migrate/20210705154113_create_counter_values.rb

@@ -0,0 +1,11 @@
+class CreateCounterValues < ActiveRecord::Migration[6.1]
+  def change
+    create_table :counter_values do |t|
+      t.string :name, index: true
+      t.integer :value, default: 0
+      t.references :parent, polymorphic: true
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20210709211056_create_counter_changes.rb

@@ -0,0 +1,11 @@
+class CreateCounterChanges < ActiveRecord::Migration[6.1]
+  def change
+    create_table :counter_changes do |t|
+      t.references :counter_value, foreign_key: true
+      t.integer :amount
+      t.timestamp :processed_at, index: true
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20210731224504_add_unique_index_to_counter_values.rb

@@ -0,0 +1,6 @@
+class AddUniqueIndexToCounterValues < ActiveRecord::Migration[6.1]
+  def change
+    add_index :counter_values, [:parent_type, :parent_id, :name],
+      unique: true, name: "unique_counter_values"
+  end
+end

data/lib/counter/any.rb

@@ -0,0 +1,6 @@
+# Simple class to represent any value in the filters
+require "singleton"
+
+class Counter::Any
+  include Singleton
+end

data/lib/counter/conditions.rb

@@ -0,0 +1,16 @@
+class Counter::Conditions
+  attr_accessor :increment_conditions, :decrement_conditions
+
+  def initialize
+    @increment_conditions = []
+    @decrement_conditions = []
+  end
+
+  def increment_if block
+    increment_conditions << block
+  end
+
+  def decrement_if block
+    decrement_conditions << block
+  end
+end

data/lib/counter/definition.rb

@@ -0,0 +1,128 @@
+# Example usage…
+#
+# class ProductCounter
+#   include Counter::Definition
+#   # This specifies the association we're counting
+#   count :products
+#   sum :price   # optional
+#   filters: {   # optional
+#     create: ->(product) { product.premium? }
+#     update: ->(product) { product.has_changed? :premium, to: :true }
+#     delete: ->(product) { product.premium? }
+#   }
+# end
+class Counter::Definition
+  include Singleton
+
+  # Attributes set by Counters#counter integration:
+  attr_accessor :association_name
+  # Set the model we're attached to (set by Counters#counter)
+  attr_accessor :model
+  # Set the thing we're counting (set by Counters#counter)
+  attr_accessor :countable_model
+  # Set the inverse association (i.e., from the products to the user)
+  attr_accessor :inverse_association
+  # When using sum, set the column we're summing
+  attr_accessor :column_to_count
+  # Test if we should count items using conditions
+  attr_writer :conditions
+  attr_writer :conditional
+  # Set the name of the counter (used as the method name)
+  attr_accessor :method_name
+  attr_accessor :name
+  # An array of all global counters
+  attr_writer :global_counters
+  # An array of Proc to run when the counter changes
+  attr_writer :counter_hooks
+  # An array of all global counters
+  attr_writer :global_counters
+
+  def sum?
+    column_to_count.present?
+  end
+
+  def global?
+    model.nil? && association_name.nil?
+  end
+
+  def conditional?
+    @conditional
+  end
+
+  # for global counter instances to find their definition
+  def self.find_definition name
+    Counter::Definition.instance.global_counters.find { |c| c.name == name }
+  end
+
+  # Access the counter value for global counters
+  def self.counter
+    raise "Unable to find counter instances via #{name}#counter. Use must use #{instance.model}#find_counter or #{instance.model}##{instance.counter_name}" unless instance.global?
+
+    Counter::Value.find_counter self
+  end
+
+  # What we record in Counter::Value#name
+  def record_name
+    return name if global?
+    "#{model.name.underscore}-#{association_name}"
+  end
+
+  def conditions
+    @conditions ||= {}
+    @conditions
+  end
+
+  def global_counters
+    @global_counters ||= []
+    @global_counters
+  end
+
+  def counter_hooks
+    @counter_hooks ||= []
+    @counter_hooks
+  end
+
+  def global_counters
+    @global_counters ||= []
+    @global_counters
+  end
+
+  # Set the association we're counting
+  def self.count association_name, as: "#{association_name}_counter"
+    instance.association_name = association_name
+    instance.name = as.to_s
+    # How the counter can be accessed e.g. counter.products_counter
+    instance.method_name = as.to_s
+  end
+
+  def self.global name = nil
+    name ||= name.underscore
+    instance.name = name.to_s
+    Counter::Definition.instance.global_counters << instance
+  end
+
+  # Get the name of the association we're counting
+  def self.association_name
+    instance.association_name
+  end
+
+  # Set the column we're summing. Leave blank to count the number of items
+  def self.sum column_name
+    instance.column_to_count = column_name
+  end
+
+  # Define a conditional filter
+  def self.on action, &block
+    instance.conditional = true
+
+    conditions = Counter::Conditions.new
+    conditions.instance_eval(&block)
+
+    instance.conditions[action] ||= []
+    instance.conditions[action] << conditions
+  end
+
+  def self.after_change block
+    instance.counter_hooks << block
+  end
+end

data/lib/counter/engine.rb

@@ -0,0 +1,5 @@
+module Counter
+  class Engine < ::Rails::Engine
+    isolate_namespace Counter
+  end
+end

data/lib/counter/error.rb

@@ -0,0 +1,2 @@
+class Counter::Error < StandardError
+end

data/lib/counter/integration/countable.rb

@@ -0,0 +1,48 @@
+module Counter::Countable
+  extend ActiveSupport::Concern
+
+  included do
+    # Install the Rails callbacks if required
+    after_create do
+      each_counter_to_update do |counter|
+        counter.add_item self
+      end
+    end
+
+    after_update do
+      each_counter_to_update do |counter|
+        counter.update_item self
+      end
+    end
+
+    after_destroy do
+      each_counter_to_update do |counter|
+        counter.remove_item self
+      end
+    end
+
+    # Iterate over each counter that needs to be updated for this model
+    # expects a block that takes a counter as an argument
+    def each_counter_to_update
+      # For each definition, find or create the counter on the parent
+      self.class.counted_by.each do |counter_definition|
+        parent_model = association(counter_definition.inverse_association)
+          .target
+        next unless parent_model
+        counter = parent_model.counters.find_or_create_counter!(counter_definition)
+        yield counter if counter
+      end
+    end
+  end
+
+  class_methods do
+    def counted_by
+      @counted_by
+    end
+
+    def add_counted_by config
+      @counted_by ||= []
+      @counted_by << config
+    end
+  end
+end

data/lib/counter/integration/counters.rb

@@ -0,0 +1,94 @@
+# This should be included in the model that has the counter
+# e.g.
+# class User < ApplicationModel
+#   include Counter::Counters
+#   has_many products
+#   counter ProductCounter
+# end
+
+require "counter/definition"
+
+module Counter::Counters
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :counters, dependent: :destroy, class_name: "Counter::Value", as: :parent do
+      # user.counters.find_counter ProductCounter
+      def find_counter counter
+        counter_name = if counter.is_a?(String) || counter.is_a?(Symbol)
+          counter.to_s
+        elsif counter.is_a?(Class) && counter.ancestors.include?(Counter::Definition)
+          counter.instance.record_name
+        else
+          counter.to_s
+        end
+
+        find_by name: counter_name
+      end
+
+      # user.counters.find_counter ProductCounter
+      def find_or_create_counter! counter
+        counter_name = if counter.is_a?(String) || counter.is_a?(Symbol)
+          counter.to_s
+        elsif counter.is_a?(Counter::Definition)
+          counter.record_name
+        elsif counter.is_a?(Class) && counter.ancestors.include?(Counter::Definition)
+          counter.instance.record_name
+        else
+          counter.to_s
+        end
+
+        Counter::Value.find_or_initialize_by(parent: proxy_association.owner, name: counter_name)
+      end
+    end
+
+    # could even be a default scope??
+    scope :with_counters, -> { includes(:counters) }
+  end
+
+  class_methods do
+    # counter ProductCounter
+    # counter PremiumProductCounter, FreeProductCounter
+    def counter *counter_definitions
+      @counter_configs ||= []
+
+      counter_definitions = Array.wrap(counter_definitions)
+      counter_definitions.each do |definition_class|
+        definition = definition_class.instance
+        association_name = definition.association_name
+
+        # Find the association on this model
+        association_reflection = reflect_on_association(association_name)
+        # Find the association classes
+        association_class = association_reflection.class_name.constantize
+        inverse_association = association_reflection.inverse_of
+
+        raise Counter::Error.new("#{association_name} must have an inverse_of specified to be used in #{definition_class.name}") if inverse_association.nil?
+
+        # Add the after_commit hook to the association's class
+        association_class.include Counter::Countable
+        # association_class.include Counter::Changed
+
+        # Update the definition with the association class and inverse association
+        # gathered from the reflection
+        definition.model = self
+        definition.inverse_association = inverse_association.name
+        definition.countable_model = association_class
+
+        define_method definition.method_name do
+          counters.find_or_create_counter!(definition)
+        end
+
+        # Provide the Countable class with details about where it's counted
+
+        @counter_configs << definition
+        association_class.add_counted_by definition
+      end
+    end
+
+    # Returns a list of Counter::Definitions
+    def counter_configs
+      @counter_configs || []
+    end
+  end
+end

data/lib/counter/railtie.rb

@@ -0,0 +1,4 @@
+module Counter
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/counter/version.rb

@@ -0,0 +1,3 @@
+module Counter
+  VERSION = "0.1.0"
+end

data/lib/counter.rb

@@ -0,0 +1,12 @@
+require "counter/version"
+require "counter/engine"
+require "counter/railtie"
+require "counter/integration/counters"
+require "counter/integration/countable"
+require "counter/any"
+require "counter/conditions"
+require "counter/error"
+
+module Counter
+  # Your code goes here...
+end

data/lib/tasks/counter_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :counter do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: counterwise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jamie Lawrence
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-07-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: standard
+  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: Counting and aggregation library for Rails.
+email:
+- jamie@ideasasylum.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/counter_manifest.js
+- app/controllers/counters_controller.rb
+- app/jobs/counter/reconciliation_job.rb
+- app/models/concerns/counter/Xhierarchical.rb
+- app/models/concerns/counter/changable.rb
+- app/models/concerns/counter/conditional.rb
+- app/models/concerns/counter/definable.rb
+- app/models/concerns/counter/hooks.rb
+- app/models/concerns/counter/increment.rb
+- app/models/concerns/counter/recalculatable.rb
+- app/models/concerns/counter/reset.rb
+- app/models/concerns/counter/sidekiq_reconciliation.rb
+- app/models/concerns/counter/summable.rb
+- app/models/concerns/counter/verifyable.rb
+- app/models/counter/change.rb
+- app/models/counter/value.rb
+- config/routes.rb
+- db/migrate/20210705154113_create_counter_values.rb
+- db/migrate/20210709211056_create_counter_changes.rb
+- db/migrate/20210731224504_add_unique_index_to_counter_values.rb
+- lib/counter.rb
+- lib/counter/any.rb
+- lib/counter/conditions.rb
+- lib/counter/definition.rb
+- lib/counter/engine.rb
+- lib/counter/error.rb
+- lib/counter/integration/countable.rb
+- lib/counter/integration/counters.rb
+- lib/counter/railtie.rb
+- lib/counter/version.rb
+- lib/tasks/counter_tasks.rake
+homepage: https://github.com/podia/counter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/podia/counter
+  source_code_uri: https://github.com/podia/counter
+  changelog_uri: https://github.com/podia/counter/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Counters and the counting counters that count them
+test_files: []