active_reporting 0.0.1 → 0.1.0

data/Rakefile

@@ -1,10 +1,10 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/active_reporting.gemspec

@@ -4,22 +4,29 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'active_reporting/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "active_reporting"
+  spec.name          = 'active_reporting'
   spec.version       = ActiveReporting::VERSION
-  spec.authors       = ["Tony Drake"]
-  spec.email         = ["t27duck@gmail.com"]
+  spec.authors       = ['Tony Drake']
+  spec.email         = ['t27duck@gmail.com']
 
-  spec.summary       = %q{OLAP-like functionality that works with ActiveRecord}
-  # spec.description   = %q{Write a longer description or delete this line.}
-  spec.homepage      = "https://github.com/t27duck/active_reporting"
-  spec.license       = "MIT"
+  spec.summary       = 'Add relational OLAP-like functionality for ActiveRecord'
+  # spec.description   = 'TODO: Write a longer description or delete this line.'
+  spec.homepage      = 'https://github.com/t27duck/active_reporting'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_dependency 'activerecord', '>= 4.2.0'
+  spec.add_dependency 'activesupport', '>= 4.2.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'ransack'
+  spec.add_development_dependency 'sqlite3'
 end

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "active_reporting"
+require 'bundler/setup'
+require 'active_reporting'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "active_reporting"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/gemfiles/4.0.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "activerecord", "~> 4.0.0"
+
+gemspec :path=>"../"

data/gemfiles/5.0.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "activerecord", "~> 5.0.0"
+
+gemspec :path=>"../"

data/lib/active_reporting.rb

@@ -1,5 +1,42 @@
-require "active_reporting/version"
+require 'active_record'
+require 'active_reporting/active_record_adaptor'
+require 'active_reporting/configuration'
+require 'active_reporting/dimension'
+require 'active_reporting/dimension_filter'
+require 'active_reporting/metric'
+require 'active_reporting/fact_model'
+require 'active_reporting/report'
+require 'active_reporting/reporting_dimension'
+require 'active_reporting/version'
+
+begin
+  require 'ransack'
+  ActiveReporting::Configuration.ransack_available = true
+rescue
+  ActiveReporting::Configuration.ransack_available = false
+end
+
+ActiveRecord::Base.extend(ActiveReporting::ActiveRecordAdaptor)
 
 module ActiveReporting
-  # Your code goes here...
+  def self.fetch_metric(name)
+    klass = Configuration.metric_lookup_class
+    unless defined?(klass.constantize)
+      raise BadMetricLookupClass,
+        "#{klass} not defined. Please define a class responsible for looking up a metric by name." +
+        " You may define your own class and set it with `ActiveReporting::Configuration.metric_lookup_class=`."
+    end
+    unless klass.constantize.respond_to?(:lookup)
+      raise BadMetricLookupClass, "#{klass} needs to define a class method called 'lookup'"
+    end
+    klass.constantize.lookup(name)
+  end
+
+  BadMetricLookupClass    = Class.new(StandardError)
+  InvalidDimensionLabel   = Class.new(StandardError)
+  RansackNotAvailable     = Class.new(StandardError)
+  UnknownAggregate        = Class.new(StandardError)
+  UnknownDimension        = Class.new(StandardError)
+  UnknownDimensionFilter  = Class.new(StandardError)
+  UnknownMetric           = Class.new(StandardError)
 end

data/lib/active_reporting/active_record_adaptor.rb

@@ -0,0 +1,21 @@
+module ActiveReporting
+  # This is included into every class that inherits from ActiveRecord::Base
+  module ActiveRecordAdaptor
+    # Returns the ActiveReporting::FactModel related to the model.
+    #
+    # If one is not explictily defined, a constant will be created which
+    # inherits from ActiveReporting::Factmodel named [MyModel]FactModel
+    #
+    # @return [ActiveReporting::FactModel]
+    def fact_model
+      const_name = "#{name}FactModel"
+      @fact_model ||= begin
+                        const_name.constantize
+                      rescue NameError
+                        const = Object.const_set(const_name, Class.new(ActiveReporting::FactModel))
+                        const.use_model self
+                        const
+                      end
+    end
+  end
+end

data/lib/active_reporting/configuration.rb

@@ -0,0 +1,80 @@
+module ActiveReporting
+  module Configuration
+    class << self
+      # Determines if ransack is available for use in the gem
+      #
+      # @return [Boolean]
+      attr_accessor :ransack_available
+    end
+
+    def self.config
+      yield self
+    end
+
+    # The default label used by all dimensions if not set otherwise
+    #
+    # Default value is `:name`
+    def self.default_dimension_label
+      @default_dimension_label ||= :name
+    end
+
+    # Sets the default dimension label to be used by all dimensions
+    #
+    # @param dimension_label [String, Symbol]
+    # @return [Symbol]
+    def self.default_dimension_label=(dimension_label)
+      @default_dimension_label = dimension_label.to_sym
+    end
+
+    # The default measture for all fact models
+    #
+    # Default value is `:value``
+    def self.default_measure
+      @default_measure ||= :value
+    end
+
+    # Sets the default measture to be used by all fact models
+    #
+    # @param measure [String, Symbol]
+    # @return [Symbol]
+    def self.default_measure=(measure)
+      @default_measure = measure.to_sym
+    end
+
+    # Tells if unkown dimension filters should always fallback to ransack
+    #
+    # Default value is `false`
+    #
+    # @return [Boolean]
+    def self.ransack_fallback
+      @ransack_fallback ||= false
+    end
+
+    # Sets the flag to always fallback to ransack for unknown dimension filters
+    # @param fallback [Boolean]
+    # @return [Boolean]
+    def self.ransack_fallback=(fallback)
+      raise RansackNotAvailable unless ransack_available
+      @ransack_fallback = fallback
+    end
+
+    # Sets the name of the constant used to lookup prebuilt `Reporting::Metric`
+    # objects by name.
+    #
+    # @param klass_name [String]
+    def self.metric_lookup_class=(klass_name)
+      @metric_lookup_class = "::#{klass_name.to_s.classify}"
+    end
+
+    # Sets the name of the constant used to lookup prebuilt `Reporting::Metric`
+    # objects by name. The constant should define a class method called `#lookup`
+    # which can take a string or symbol of the metric name.
+    #
+    # Default value is ::Metric
+    #
+    # @returns [String]
+    def self.metric_lookup_class
+      @metric_lookup_class ||= '::Metric'
+    end
+  end
+end

data/lib/active_reporting/dimension.rb

@@ -0,0 +1,59 @@
+module ActiveReporting
+  class Dimension
+    attr_reader :name
+
+    # @param model [ActiveRecord::Base]
+    # @param name [Symbol]
+    def initialize(fact_model, name:)
+      @fact_model = fact_model
+      @name       = name.to_s
+    end
+
+    # Determins the type of the dimension
+    #
+    # A dimension type is either:
+    #
+    # * standard - The dimension is a relation to the fact model's model
+    # * degenerate - The dimension is the model's attribute
+    #
+    # @return [Symbol]
+    def type
+      @type ||= if model.column_names.include?(@name)
+                  :degenerate
+                elsif association
+                  :standard
+                else
+                  raise UnknownDimension, "Dimension '#{@name}' not found on fact model '#{@fact_model}'"
+                end
+    end
+
+    # Tells if the dimension is hierarchical
+    #
+    # @return [Boolean]
+    def hierarchical?
+      @hierarchical ||= !klass.fact_model.hierarchical_levels.empty?
+    end
+
+    # Returns either the model of the dimension's association or the model
+    # itself if the dimension lives on the fact model
+    #
+    # @return [Boolean]
+    def klass
+      @klass ||= association ? association.klass : model
+    end
+
+    # Returns the fact model's dimension
+    #
+    # @return [ActiveRecord::Base]
+    def model
+      @model ||= @fact_model.model
+    end
+
+    # Returns the reflected association of the fact model to dimension name
+    #
+    # @return [ActiveRecord::Reflection]
+    def association
+      @association_info ||= model.reflect_on_association(@name)
+    end
+  end
+end

data/lib/active_reporting/dimension_filter.rb

@@ -0,0 +1,30 @@
+module ActiveReporting
+  class DimensionFilter
+    attr_reader :type, :body
+
+    # Factory for creating a new DimensionFilter
+    #
+    # Determines the type based on if passed in a callable object or a symbol
+    #
+    # @param name (Symbol)
+    # @param lambda_or_type (Symbol, Lambda)
+    # @return (ActiveReporting::DimensionFilter) a new instance of a dimension filter
+    def self.build(name, lambda_or_type)
+      body = nil
+      type = lambda_or_type
+
+      if lambda_or_type.respond_to?(:call)
+        body = lambda_or_type
+        type = :lambda
+      end
+
+      new(name, type, body)
+    end
+
+    def initialize(name, type = :scope, body = nil)
+      @name = name.to_sym
+      @type = type.to_sym
+      @body = body
+    end
+  end
+end

data/lib/active_reporting/fact_model.rb

@@ -0,0 +1,170 @@
+module ActiveReporting
+  class FactModel
+    class << self
+      attr_reader :dimensions, :dimension_filters
+      attr_writer :measure
+    end
+
+    # Explicitly sets which ActiveRecord model to to link to this fact model.
+    #
+    # @note You should only need to set this if the name of your fact model does not
+    #   follow the pattern of [MyModel]FactModel
+    #
+    # @param model [String, Symbol, Class]
+    # @return [Class] the ActiveRecord model
+    #
+    # @example
+    #   class PostFactModel < ActiveReporting::FactModel
+    #     use_model :post
+    #     use_model Post
+    #     use_model 'post'
+    #   end
+    def self.use_model(model)
+      @model = if model.is_a?(String) || model.is_a?(Symbol)
+                 model.to_s.classify.constantize
+               else
+                 model
+               end
+      @model.instance_variable_set('@fact_model', self)
+      @model
+    end
+
+    # Returns the ActiveRecord model linked to the FactModel.
+    #
+    # If not already set, FactModel assumes the model is based off of the name of the class
+    #
+    # @example
+    #   class PostFactModel < ActiveReporting::FactModel
+    #   end
+    #
+    #   PostFactModel.model
+    #   => Post
+    #
+    # @return [Class] the ActiveRecord model
+    def self.model
+      @model ||= name.gsub(/FactModel\z/, '').constantize
+    end
+
+    # The default measure used when this fact model is reported on
+    #
+    # @return [Symbol]
+    def self.measure
+      @measure ||= Configuration.default_measure
+    end
+
+    # The (in order) hierarchical levels of the fact model when used as
+    # a dimension.
+    #
+    # @return [Array]
+    def self.hierarchical_levels
+      @hierarchical_levels ||= []
+    end
+
+    # Specifies an in order array of columns which describes a series of
+    # columns that may be used as dimensions in a hierarchy.
+    #
+    # For example, a fact model of tablets may have a hierarchy of
+    # name -> manufacturer -> operating system.
+    #
+    # @param levels (Array) An array of symbols or strings of columns
+    def self.dimension_hierarchy(levels)
+      @hierarchical_levels = Array(levels).map(&:to_sym)
+    end
+
+    # When this fact model is used as a dimension, this is the label it will
+    # use by default
+    #
+    # @return [Symbol]
+    def self.default_dimension_label(label)
+      @dimension_label = label.to_sym
+    end
+
+    # Returns the dimension label used when this fact model is used as a dimension
+    #
+    # @return [Symbol]
+    def self.dimension_label
+      @dimension_label || Configuration.default_dimension_label
+    end
+
+    # Declares a dimension for this fact model
+    #
+    # @param name [String, Symbol] The name of the dimension
+    def self.dimension(name)
+      @dimensions ||= {}
+      @dimensions[name.to_sym] = Dimension.new(self, name: name)
+    end
+
+    # Returns a hash of dimension label to callback mappings
+    #
+    # @return [Hash]
+    def self.dimension_label_callbacks
+      @dimension_label_callbacks ||= {}
+    end
+
+    # Sets a call back for a given dimension label. The returned value of
+    # the callable body will be used as the label value when used in a report.
+    # The label's raw database value is passed to the callback.
+    #
+    # @param column [Symbol, String]
+    # @param body [Lambda]
+    def self.dimension_label_callback(column, body)
+      @dimension_label_callbacks ||= {}
+      raise ArgumentError, "Dimension label callback body must be a callable object" unless body.respond_to?(:call)
+      @dimension_label_callbacks[column.to_sym] = body
+    end
+
+    # Declares a dimension filter for this fact model
+    #
+    # @param name [Stirng, Symbol] The name of the dimension filter
+    # @param lambda_or_type [Symbol, Lambda]
+    #
+    # @note If not provided, the type of the dimension filter will be a scope.
+    #   Meaning the ActiveReporting is assuming there's a scope on the fact
+    #   model's model named the same. You may pass in `:ransack` to say this
+    #   dimension filter is a ransack search term. Finally, you may pass in
+    #   a callable object similar to defining a scope on ActiveRecord
+    #
+    # @example
+    #   class PostFactModel < ActiveReporting::FactModel
+    #     # Assumes there's an `active` scope on the model
+    #     dimension_filter :active
+    #
+    #     # Uses the ransack search term `joined_at_gte`
+    #     dimension_filter :joined_at_gte, :ransack
+    #
+    #     # Implements a dimension filter like an ActiveRecord scope
+    #     dimension_filter :some_filter, ->(input) { where(foo: input) }
+    #   end
+    def self.dimension_filter(name, lambda_or_type = :scope)
+      @dimension_filters ||= {}
+      @dimension_filters[name.to_sym] = DimensionFilter.build(name, lambda_or_type)
+    end
+
+    # Invoke this method to make all dimension filters fallback to use ransack
+    # if they are not defined as scopes on the model
+    def self.use_ransack_for_unknown_dimension_filters
+      raise RansackNotAvailable, 'Ransack not available. Please include it in your Gemfile.' unless ransack_available
+      @ransack_fallback = true
+    end
+
+    # Tells if unknown dimension filters fallback to use ransack
+    #
+    # @return [Boolean]
+    def self.ransack_fallback
+      @ransack_fallback || Configuration.ransack_fallback
+    end
+    private_class_method :ransack_fallback
+
+    # Finds a dimension filter defined on a fact model given a name
+    #
+    # @param name [Symbol]
+    # @return [ActiveReporting::DimensionFilter]
+    def self.find_dimension_filter(name)
+      @dimension_filters ||= {}
+      dm = @dimension_filters[name.to_sym]
+      return dm if dm.present?
+      return @dimension_filters[name.to_sym] = DimensionFilter.build(self, name, :ransack) if ransack_fallback
+      raise UnknownDimensionFilter, "Dimension filter '#{name}' not found on fact model '#{self.name}'"
+    end
+  end
+end