periodic_calculations 0.0.1

data/.gitignore

@@ -0,0 +1,9 @@
+pkg/*
+Gemfile.lock
+*.gem
+.bundle
+nbproject/*
+bin
+.rspec
+.rbenv-version
+coverage/

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,120 @@
+PATH
+  remote: .
+  specs:
+    periodic_calculations (0.0.1)
+      rails (>= 3.2)
+      railties
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (4.0.1)
+      actionpack (= 4.0.1)
+      mail (~> 2.5.4)
+    actionpack (4.0.1)
+      activesupport (= 4.0.1)
+      builder (~> 3.1.0)
+      erubis (~> 2.7.0)
+      rack (~> 1.5.2)
+      rack-test (~> 0.6.2)
+    activemodel (4.0.1)
+      activesupport (= 4.0.1)
+      builder (~> 3.1.0)
+    activerecord (4.0.1)
+      activemodel (= 4.0.1)
+      activerecord-deprecated_finders (~> 1.0.2)
+      activesupport (= 4.0.1)
+      arel (~> 4.0.0)
+    activerecord-deprecated_finders (1.0.3)
+    activesupport (4.0.1)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    arel (4.0.1)
+    atomic (1.1.14)
+    builder (3.1.4)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    diff-lcs (1.2.5)
+    docile (1.1.1)
+    erubis (2.7.0)
+    hike (1.2.3)
+    i18n (0.6.5)
+    mail (2.5.4)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.25.1)
+    minitest (4.7.5)
+    multi_json (1.8.2)
+    pg (0.15.1)
+    polyglot (0.3.3)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rails (4.0.1)
+      actionmailer (= 4.0.1)
+      actionpack (= 4.0.1)
+      activerecord (= 4.0.1)
+      activesupport (= 4.0.1)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.0.1)
+      sprockets-rails (~> 2.0.0)
+    railties (4.0.1)
+      actionpack (= 4.0.1)
+      activesupport (= 4.0.1)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.1.0)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    rspec-rails (2.14.0)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    sprockets (2.10.1)
+      hike (~> 1.2)
+      multi_json (~> 1.0)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sprockets-rails (2.0.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      sprockets (~> 2.8)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    thread_safe (0.1.3)
+      atomic
+    tilt (1.4.1)
+    tins (0.13.1)
+    treetop (1.4.15)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  periodic_calculations!
+  pg
+  rspec-rails

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Pol Miro
+
+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,8 @@
+# PeriodicCalculations
+
+[![Build Status](https://travis-ci.org/polmiro/periodic_calculations.png)](https://travis-ci.org/polmiro/periodic_calculations)
+[![Code Climate](https://codeclimate.com/github/polmiro/periodic_calculations.png)](https://codeclimate.com/github/polmiro/periodic_calculations)
+[![Coverage Status](https://coveralls.io/repos/polmiro/periodic_calculations/badge.png)](https://coveralls.io/r/polmiro/periodic_calculations)
+[![Gem Version](https://badge.fury.io/rb/periodic_calculations.png)](http://badge.fury.io/rb/periodic_calculations)
+
+Periodic Calculations gem allows you to retrieve periodic results of aggregates that can be accumulated over time with PostgreSQL.

data/Rakefile

@@ -0,0 +1,24 @@
+#!/usr/bin/env rake
+require 'bundler/setup'
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PeriodicCalculations'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+task :default => :spec
+RSpec::Core::RakeTask.new
+

data/lib/periodic_calculations/base.rb

@@ -0,0 +1,36 @@
+module PeriodicCalculations
+  module Base
+    extend ActiveSupport::Concern
+
+    # TODO:
+    #  * Rails 4 compatible only right now (scoped vs all)
+
+    module ClassMethods
+      def periodic_count(*args)
+        periodic_calculation(:count, *args)
+      end
+
+      def periodic_maximum(*args)
+        periodic_calculation(:max, *args)
+      end
+
+      def periodic_minimum(*args)
+        periodic_calculation(:min, *args)
+      end
+
+      def periodic_sum(*args)
+        periodic_calculation(:sum, *args)
+      end
+
+      def periodic_average(*args)
+        periodic_calculation(:avg, *args)
+      end
+
+      def periodic_calculation(operation, column_name, window_start, window_end, options = {})
+        query_options = QueryOptions.new(operation, column_name, window_start, window_end, options)
+        query = Query.new(all, query_options)
+        LazyQuery.new(query)
+      end
+    end
+  end
+end

data/lib/periodic_calculations/engine.rb

@@ -0,0 +1,5 @@
+module PeriodicCalculations
+  class Engine < ::Rails::Engine
+    ActiveRecord::Base.send(:include, PeriodicCalculations::Base)
+  end
+end

data/lib/periodic_calculations/lazy_query.rb

@@ -0,0 +1,36 @@
+module PeriodicCalculations
+  class LazyQuery
+    def initialize(query)
+      @query = query
+      @executed = false
+      @result = nil
+    end
+
+    def method_missing(method_name, *args, &block)
+      if method_name == :to_sql
+        @query.to_sql
+      else
+        lazy_result.send(method_name, *args, &block)
+      end
+    end
+
+    def respond_to?(method_name, include_private = false)
+      method_name == :to_sql || super || lazy_result.respond_to?(method_name)
+    end
+
+    def result
+      lazy_result
+    end
+
+    private
+
+    def lazy_result
+      if @executed
+        @result
+      else
+        @executed = true
+        @result = @query.execute
+      end
+    end
+  end
+end

data/lib/periodic_calculations/query.rb

@@ -0,0 +1,136 @@
+module PeriodicCalculations
+  class Query
+    INTERVAL_UNIT = [:day, :week, :month, :year]
+
+    # TODO:
+    #  * prepared statement?
+
+    # Builds a periodic operation query with PostgresSQL window functions
+    #
+    # @param relation [ActiveRecord::Relation] Object to build query from
+    # @param query_options [QueryOptions]
+    # @return [Array<Array>] for each period the time of the interval and the count of it
+    def initialize(relation, query_options)
+      @relation = relation
+      @target_column = query_options.target_column
+      @timestamp_column = query_options.timestamp_column
+      @operation = query_options.operation.upcase
+      @window_function = query_options.cumulative ? "ORDER" : "PARTITION"
+      @binds = {
+        :unit     => query_options.interval_unit,
+        :interval => "1 #{query_options.interval_unit.upcase}",
+        :start    => query_options.window_start,
+        :end      => query_options.window_end,
+        :offset   => "#{query_options.timezone_offset} seconds"
+      }
+    end
+
+    def execute
+      ActiveRecord::Base.connection_pool.with_connection do |connection|
+        connection.execute(sanitized_sql).map do |elem|
+          [Date.parse(elem["frame"]).to_time, elem["result"].to_i]
+        end
+      end
+    end
+
+    def to_sql
+      sanitized_sql
+    end
+
+    private
+
+    def sanitized_sql
+      ActiveRecord::Base.send(:sanitize_sql_array, [Arel.sql(sql), @binds])
+    end
+
+    def sql
+      # How are timezones managed?
+      # * Take into account the timezone offset throughout the search,
+      #   so that the periods are correctly grouped.
+      # * Restore the timezone at the very end to return the date in UTC
+      #   being consistent with the Rails convention
+
+      # What does it do?
+      # 1. group currently selected rows by the interval
+      # 2. trim out unneeded rows if query is not cumulative
+      # 3. make a union to add possible missing time points
+      # 4. iterate over a window function that can cumulate the previous counters if needed
+      # 5. trim out rows outside the time window
+      #    Cannot be done before in the same query because window function iterates after the
+      #    where/group by/having clauses (could be improved for non cumulative queries)
+
+      <<-SQL
+        WITH
+          -- generate series within window
+          -- (with shifted timezones utc_date -> zone_date)
+          grid AS (
+            SELECT  date_trunc(:unit, serie) AS frame,
+                    NULL::integer            AS result
+            FROM    generate_series(
+                      :start::timestamp + INTERVAL :offset,
+                      :end::timestamp + INTERVAL :offset,
+                      :interval
+                    )                                 AS serie
+          )
+
+          -- preprocess results grouping by interval
+          -- (with shifted timezones utc_date -> zone_date)
+          , preprocessed_results AS (
+            #{relation_sql}
+          )
+
+          -- running window function calculate results and fill up gaps
+          , results AS (
+            SELECT  DISTINCT frame,
+                    #{@operation}(result) OVER (#{@window_function} BY frame) AS result
+            FROM (
+              SELECT frame, result FROM preprocessed_results
+              UNION ALL
+              SELECT frame, result FROM grid
+            ) AS fulfilled_gaps
+          )
+
+        -- cut out values outside window
+        -- (with shifted timezones utc_date -> zone_date)
+        SELECT    frame,
+                  result
+        FROM      results
+        WHERE     frame BETWEEN
+                    date_trunc(:unit, :start::timestamp + INTERVAL :offset)
+                    AND
+                    date_trunc(:unit, :end::timestamp + INTERVAL :offset)
+        ORDER BY  frame ASC
+      SQL
+    end
+
+    def relation_sql
+      # select frames an results
+      relation_query = @relation
+        .select(<<-SQL)
+          date_trunc(:unit, #{@relation.table_name}.#{@timestamp_column} + INTERVAL :offset) AS frame,
+          #{@operation}(#{@target_column}) AS result
+        SQL
+
+      # optimize selection if not cumulative query
+      if @window_function == "PARTITION"
+        relation_query = relation_query.where(<<-SQL)
+          date_trunc(:unit, #{@relation.table_name}.#{@timestamp_column} + INTERVAL :offset) BETWEEN
+            date_trunc(:unit, :start::timestamp + INTERVAL :offset)
+            AND
+            date_trunc(:unit, :end::timestamp + INTERVAL :offset)
+        SQL
+      end
+
+      # group results by frames
+      relation_query = relation_query.group(<<-SQL)
+        date_trunc(:unit, #{@relation.table_name}.#{@timestamp_column} + INTERVAL :offset)
+      SQL
+
+      relation_query.to_sql
+    end
+
+  end
+
+end
+
+ActiveRecord::Base.extend PeriodicCalculations

data/lib/periodic_calculations/query_options.rb

@@ -0,0 +1,61 @@
+module PeriodicCalculations
+  class QueryOptions
+    OPERATION = [:count, :max, :min, :sum, :avg]
+    INTERVAL_UNIT = [:day, :week, :month, :year]
+
+    attr_reader :operation,
+                :target_column,
+                :timestamp_column,
+                :window_start,
+                :window_end,
+                :interval_unit,
+                :cumulative,
+                :timezone_offset
+
+    def initialize(operation, column_name, window_start, window_end, options = {})
+      @operation = operation
+      @target_column = column_name
+      @timestamp_column = options[:timestamp_column] || :created_at
+      @window_start = window_start
+      @window_end = window_end
+      @interval_unit = options[:interval_unit] || :day
+      @cumulative = !!options[:cumulative]
+      @timezone_offset = Time.now.in_time_zone.utc_offset
+
+      validate!
+    end
+
+    private
+
+    def validate!
+      validate_operation!
+      validate_target_column!
+      validate_window!
+      validate_interval_unit!
+    end
+
+    def validate_operation!
+      unless OPERATION.include?(@operation)
+        raise ArgumentError.new("Invalid operation")
+      end
+    end
+
+    def validate_target_column!
+      unless @target_column.present?
+        raise ArgumentError.new("Target column name must be present")
+      end
+    end
+
+    def validate_window!
+      unless window_start.is_a?(Time) && window_end.is_a?(Time)
+        raise ArgumentError.new("Invalid Time window")
+      end
+    end
+
+    def validate_interval_unit!
+      unless INTERVAL_UNIT.include?(@interval_unit)
+        raise ArgumentError.new("Invalid interval unit")
+      end
+    end
+  end
+end

data/lib/periodic_calculations/version.rb

@@ -0,0 +1,3 @@
+module PeriodicCalculations
+  VERSION = "0.0.1"
+end

data/lib/periodic_calculations.rb

@@ -0,0 +1,11 @@
+require 'rails'
+require 'active_record'
+
+module PeriodicCalculations
+  require "periodic_calculations/version"
+  require "periodic_calculations/base"
+  require "periodic_calculations/query"
+  require "periodic_calculations/query_options"
+  require "periodic_calculations/lazy_query"
+  require "periodic_calculations/engine"
+end

data/periodic_calculations.gemspec

@@ -0,0 +1,28 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "periodic_calculations/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = "periodic_calculations"
+  s.version     = PeriodicCalculations::VERSION
+  s.authors     = ["Pol"]
+  s.email       = ["polmiro@gmail.com"]
+  s.homepage    = "https://github.com/polmiro/periodic_calculations"
+  s.summary     = "Retrieve periodic stats in periods of time"
+  s.description = "Periodic Calculations gem allows you to retrieve periodic results of aggregates that can be accumulated over time with PostgreSQL."
+  s.license     = 'MIT'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "rails", ">= 3.2"
+  s.add_dependency "railties"
+
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "pg"
+  s.add_development_dependency "coveralls"
+end

data/spec/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/spec/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/spec/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,13 @@
+/*
+ * 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 vendor/assets/stylesheets of plugins, if any, 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 top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end

data/spec/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/spec/dummy/app/models/activity.rb

@@ -0,0 +1,2 @@
+class Activity < ActiveRecord::Base
+end

data/spec/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag    "application", media: "all", "data-turbolinks-track" => true %>
+  <%= javascript_include_tag "application", "data-turbolinks-track" => true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/spec/dummy/config/application.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../boot', __FILE__)
+
+require 'rails/all'
+
+Bundler.require(*Rails.groups)
+require "periodic_calculations"
+
+module Dummy
+  class Application < Rails::Application
+    # Settings in config/environments/* take precedence over those specified here.
+    # Application configuration should go into files in config/initializers
+    # -- all .rb files in that directory are automatically loaded.
+
+    # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone.
+    # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC.
+    # config.time_zone = 'Central Time (US & Canada)'
+
+    # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+    # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
+    # config.i18n.default_locale = :de
+  end
+end
+

data/spec/dummy/config/boot.rb

@@ -0,0 +1,5 @@
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../../../Gemfile', __FILE__)
+
+require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
+$LOAD_PATH.unshift File.expand_path('../../../../lib', __FILE__)

data/spec/dummy/config/database.yml

@@ -0,0 +1,20 @@
+development:
+  adapter: postgresql
+  encoding: utf8
+  database: periodic_calculations_development
+  pool: 5
+  host: 127.0.0.1
+  username: rewardli_su
+  password:
+  timeout: 5000
+
+test:
+  adapter: postgresql
+  encoding: utf8
+  database: periodic_calculations_test
+  pool: 5
+  host: 127.0.0.1
+  username: rewardli_su
+  password:
+  timeout: 5000
+