rollup_engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd7fb01c9476db83d64067639000119055f3780bdb32cc8e3eeeed3133597aa9
+  data.tar.gz: 8c41a6577ae4fcaf573662fdbc3dc4aca6dc4005c6f6617f8c86c3d0a298153b
+SHA512:
+  metadata.gz: f4746be9f68a87b3dc5fd16a9887da4d01ef8e57a1671cc10546e400a118abe1207fe8d102683afe2a8ded39447b628221d2ddeaf22a7c7c7f5de852f3ed378e
+  data.tar.gz: e48e39aef77e91b4fde1a1a967ce71badff3cc28912a8ae6fc509bdf1012b256471e90b71e1e73bfc95f9d7b9e5acf6556e4d07fdcfa0a1382490a6529924c11

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold: mountable `RollupEngine` Rails engine (source-agnostic; no event
+  source dependency).

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright tylercschneider
+
+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,64 @@
+# RollupEngine
+
+A **source-agnostic aggregation engine**. Feed it facts — rows with dimensions and
+measurable values — and it turns them into numbers: declared **measures**, rolled up
+by **time grain** and **dimension**, recomputed idempotently.
+
+RollupEngine depends on no particular data source. It doesn't know about events, an outbox,
+or any specific producer — anything that can hand it facts can use it. (In the
+EventEngine stack, an adapter feeds `event_engine-store` events in as facts; but
+that adapter lives elsewhere, not here.)
+
+## Installation
+
+```ruby
+gem "rollup_engine"
+```
+
+```bash
+$ bundle
+```
+
+## Status
+
+Early development. The first rollup works — `RollupEngine::Rollup.count` / `.sum` aggregate
+facts by **time grain** and optional **dimensions**:
+
+```ruby
+RollupEngine::Rollup.count(facts, grain: :day, time: :occurred_at)
+RollupEngine::Rollup.sum(facts, :amount, grain: :day, time: :occurred_at, by: [:channel])
+```
+
+Declare named **measures** once and compute by name:
+
+```ruby
+RollupEngine.register_measure(:revenue, aggregation: :sum, field: :amount)
+RollupEngine::Rollup.compute(facts, measure: :revenue, grain: :day, time: :occurred_at)
+```
+
+Persist rollups idempotently into the `rollup_engine_datapoints` table:
+
+```ruby
+RollupEngine.recompute(:revenue, facts, grain: :day, time: :occurred_at, by: [:channel])
+# upserts one RollupEngine::Datapoint per (measure, grain, period_start, dimensions);
+# re-running updates values in place — no duplicates.
+```
+
+`time`, `field`, and dimensions accept a **method symbol or a callable**, so facts
+with nested data roll up without a wrapper — e.g. an event's JSON `payload`:
+
+```ruby
+RollupEngine.recompute(:revenue, stored_events,
+  grain: :day,
+  time:  :occurred_at,
+  field: ->(e) { e.payload["amount"] },
+  by:    [ ->(e) { e.payload["channel"] } ])
+```
+
+This is what lets `event_engine-store` events feed `rollup_engine` without coupling the two.
+
+Next: a recompute job + window scoping, then sketches/cohorts.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+task test: "app:test"
+task default: :test

data/app/assets/stylesheets/rollup_engine/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/rollup_engine/application_controller.rb

@@ -0,0 +1,4 @@
+module RollupEngine
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/rollup_engine/application_helper.rb

@@ -0,0 +1,4 @@
+module RollupEngine
+  module ApplicationHelper
+  end
+end

data/app/jobs/rollup_engine/application_job.rb

@@ -0,0 +1,4 @@
+module RollupEngine
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rollup_engine/application_mailer.rb

@@ -0,0 +1,6 @@
+module RollupEngine
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/rollup_engine/application_record.rb

@@ -0,0 +1,5 @@
+module RollupEngine
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/rollup_engine/datapoint.rb

@@ -0,0 +1,28 @@
+require "json"
+
+module RollupEngine
+  class Datapoint < ApplicationRecord
+    self.table_name = "rollup_engine_datapoints"
+
+    scope :in_period, ->(range) { where(period_start: range) }
+
+    before_validation :assign_dimensions_key
+
+    # A canonical, order-independent string for a dimensions hash, used to match
+    # and uniquely index rows. Avoids relying on JSON column equality, which
+    # Postgres's `json` type does not support.
+    def self.dimensions_key_for(dimensions)
+      (dimensions || {}).to_a.sort.to_h.to_json
+    end
+
+    def self.series(measure, range)
+      where(measure: measure.to_s).in_period(range).group(:period_start).order(:period_start).sum(:value).to_a
+    end
+
+    private
+
+    def assign_dimensions_key
+      self.dimensions_key = self.class.dimensions_key_for(dimensions)
+    end
+  end
+end

data/app/views/layouts/rollup_engine/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>RollupEngine</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "rollup_engine/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,2 @@
+RollupEngine::Engine.routes.draw do
+end

data/db/migrate/20260605000001_create_tally_datapoints.rb

@@ -0,0 +1,17 @@
+class CreateTallyDatapoints < ActiveRecord::Migration[8.1]
+  def change
+    create_table :tally_datapoints do |t|
+      t.string :measure, null: false
+      t.string :grain, null: false
+      t.datetime :period_start, null: false
+      t.json :dimensions, null: false, default: {}
+      t.decimal :value, null: false
+      t.datetime :recomputed_at
+
+      t.timestamps
+    end
+
+    add_index :tally_datapoints, [ :measure, :grain, :period_start ],
+      name: "index_tally_datapoints_on_measure_grain_period"
+  end
+end

data/db/migrate/20260605160001_add_dimensions_key_to_tally_datapoints.rb

@@ -0,0 +1,9 @@
+class AddDimensionsKeyToTallyDatapoints < ActiveRecord::Migration[8.1]
+  def change
+    add_column :tally_datapoints, :dimensions_key, :string, null: false, default: ""
+
+    remove_index :tally_datapoints, name: "index_tally_datapoints_on_measure_grain_period"
+    add_index :tally_datapoints, %i[measure grain period_start dimensions_key],
+      unique: true, name: "index_tally_datapoints_unique"
+  end
+end

data/db/migrate/20260921120000_rename_tally_tables_to_rollup_engine.rb

@@ -0,0 +1,8 @@
+class RenameTallyTablesToRollupEngine < ActiveRecord::Migration[8.1]
+  def change
+    rename_table :tally_datapoints, :rollup_engine_datapoints
+    rename_index :rollup_engine_datapoints,
+      "index_tally_datapoints_unique",
+      "index_rollup_engine_datapoints_unique"
+  end
+end

data/lib/rollup_engine/engine.rb

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

data/lib/rollup_engine/measure.rb

@@ -0,0 +1,3 @@
+module RollupEngine
+  Measure = Struct.new(:name, :aggregation, :field, keyword_init: true)
+end

data/lib/rollup_engine/recompute.rb

@@ -0,0 +1,25 @@
+module RollupEngine
+  module Recompute
+    def self.call(measure_name, facts, grain:, time:, by: [])
+      result = Rollup.compute(facts, measure: measure_name, grain: grain, time: time, by: by)
+
+      result.each do |key, value|
+        period_start, dimensions = decompose(key, by)
+        datapoint = Datapoint.find_or_initialize_by(
+          measure: measure_name.to_s,
+          grain: grain.to_s,
+          period_start: period_start,
+          dimensions_key: Datapoint.dimensions_key_for(dimensions)
+        )
+        datapoint.update!(dimensions: dimensions, value: value, recomputed_at: Time.current)
+      end
+    end
+
+    def self.decompose(key, by)
+      return [ key, {} ] if by.empty?
+
+      period_start, *dimension_values = key
+      [ period_start, by.map(&:to_s).zip(dimension_values).to_h ]
+    end
+  end
+end

data/lib/rollup_engine/rollup.rb

@@ -0,0 +1,42 @@
+module RollupEngine
+  module Rollup
+    def self.compute(facts, measure:, grain:, time:, by: [])
+      definition = RollupEngine.measure(measure)
+
+      case definition.aggregation
+      when :count then count(facts, grain: grain, time: time, by: by)
+      when :sum then sum(facts, definition.field, grain: grain, time: time, by: by)
+      else raise ArgumentError, "Unknown aggregation: #{definition.aggregation.inspect}"
+      end
+    end
+
+    def self.count(facts, grain:, time:, by: [])
+      grouped(facts, grain, time, by).transform_values(&:size)
+    end
+
+    def self.sum(facts, field, grain:, time:, by: [])
+      grouped(facts, grain, time, by).transform_values do |group|
+        group.sum { |fact| extract(fact, field) }
+      end
+    end
+
+    def self.grouped(facts, grain, time, by)
+      facts.group_by { |fact| key(fact, grain, time, by) }
+    end
+
+    def self.key(fact, grain, time, by)
+      bucket = bucket(extract(fact, time), grain)
+      return bucket if by.empty?
+
+      [ bucket, *by.map { |dimension| extract(fact, dimension) } ]
+    end
+
+    def self.extract(fact, accessor)
+      accessor.respond_to?(:call) ? accessor.call(fact) : fact.public_send(accessor)
+    end
+
+    def self.bucket(moment, grain)
+      moment.public_send("beginning_of_#{grain}")
+    end
+  end
+end

data/lib/rollup_engine/version.rb

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

data/lib/rollup_engine.rb

@@ -0,0 +1,29 @@
+require "rollup_engine/version"
+require "rollup_engine/engine"
+require "rollup_engine/measure"
+require "rollup_engine/rollup"
+require "rollup_engine/recompute"
+
+module RollupEngine
+  class << self
+    def measures
+      @measures ||= {}
+    end
+
+    def recompute(measure_name, facts, grain:, time:, by: [])
+      Recompute.call(measure_name, facts, grain: grain, time: time, by: by)
+    end
+
+    def register_measure(name, aggregation:, field: nil)
+      measures[name] = Measure.new(name: name, aggregation: aggregation, field: field)
+    end
+
+    def measure(name)
+      measures.fetch(name)
+    end
+
+    def reset_measures!
+      measures.clear
+    end
+  end
+end

data/lib/tasks/rollup_engine_tasks.rake

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

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: rollup_engine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Turn facts into numbers. RollupEngine declares measures, rolls them up
+  by time grain and dimension, and recomputes idempotently. Source-agnostic — feed
+  it any facts (dimensions + measures); it does not depend on any particular event
+  source.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/rollup_engine/application.css
+- app/controllers/rollup_engine/application_controller.rb
+- app/helpers/rollup_engine/application_helper.rb
+- app/jobs/rollup_engine/application_job.rb
+- app/mailers/rollup_engine/application_mailer.rb
+- app/models/rollup_engine/application_record.rb
+- app/models/rollup_engine/datapoint.rb
+- app/views/layouts/rollup_engine/application.html.erb
+- config/routes.rb
+- db/migrate/20260605000001_create_tally_datapoints.rb
+- db/migrate/20260605160001_add_dimensions_key_to_tally_datapoints.rb
+- db/migrate/20260921120000_rename_tally_tables_to_rollup_engine.rb
+- lib/rollup_engine.rb
+- lib/rollup_engine/engine.rb
+- lib/rollup_engine/measure.rb
+- lib/rollup_engine/recompute.rb
+- lib/rollup_engine/rollup.rb
+- lib/rollup_engine/version.rb
+- lib/tasks/rollup_engine_tasks.rake
+homepage: https://github.com/DYB-Development/rollup_engine
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/DYB-Development/rollup_engine
+  source_code_uri: https://github.com/DYB-Development/rollup_engine
+  changelog_uri: https://github.com/DYB-Development/rollup_engine/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/rollup_engine/issues
+  documentation_uri: https://github.com/DYB-Development/rollup_engine#readme
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Source-agnostic aggregation engine: measures, rollups, sketches'
+test_files: []