active_reporting 0.6.1 → 1.0.0

data/lib/active_reporting/configuration.rb

@@ -2,22 +2,64 @@
 
 module ActiveReporting
   module Configuration
-    class << self
-      # Determines if ransack is available for use in the gem
-      #
-      # @return [Boolean]
-      attr_accessor :ransack_available
-    end
+    # The default label used by all dimensions if not set otherwise
+    #
+    # Default value is `:name`
+    #
+    # @return [Symbol]
+    mattr_reader :default_dimension_label, default: :name
+
+    # The default measure for all fact models
+    #
+    # Default value is `:value`
+    #
+    # @return [Symbol]
+    mattr_reader :default_measure, default: :value
+
+    # Tells if unknown dimension filters should always fallback to ransack
+    #
+    # Default value is `false`
+    #
+    # @return [Boolean]
+    mattr_reader :ransack_fallback, default: false
+
+    # Returns the name of the constant used to lookup prebuilt `ActiveReporting::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`
+    #
+    # @return [String]
+    mattr_reader :metric_lookup_class, default: '::Metric'
 
     def self.config
       yield self
     end
 
-    # The default label used by all dimensions if not set otherwise
+    # `mattr_reader` stores values in class variables, so the custom writers below set them directly.
+    # Configuration is never included into other classes, so class variable sharing is not a concern.
+    # rubocop:disable Style/ClassVars
+
+    # Determines if ransack is available for use in the gem. Ransack is loaded the first time this is
+    # called, so it does not matter whether it is required before or after ActiveReporting.
     #
-    # Default value is `:name`
-    def self.default_dimension_label
-      @default_dimension_label ||= :name
+    # @return [Boolean]
+    def self.ransack_available
+      return @@ransack_available if defined?(@@ransack_available)
+
+      @@ransack_available = begin
+        require 'ransack'
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    # Overrides ransack detection
+    #
+    # @param available [Boolean]
+    def self.ransack_available=(available)
+      @@ransack_available = available
     end
 
     # Sets the default dimension label to be used by all dimensions
@@ -25,58 +67,34 @@ module ActiveReporting
     # @param dimension_label [String, Symbol]
     # @return [Symbol]
     def self.default_dimension_label=(dimension_label)
-      @default_dimension_label = dimension_label.to_sym
+      @@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
+    # Sets the default measure 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
+      @@default_measure = measure.to_sym
     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
+      raise RansackNotAvailable if fallback && !ransack_available
+
+      @@ransack_fallback = fallback
     end
 
-    # Sets the name of the constant used to lookup prebuilt `Reporting::Metric`
+    # Sets the name of the constant used to lookup prebuilt `ActiveReporting::Metric`
     # objects by name.
     #
-    # @param klass_name [String]
+    # @param klass_name [String, Symbol, Class]
     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'
+      @@metric_lookup_class = "::#{klass_name.to_s.camelize.delete_prefix('::')}"
     end
+    # rubocop:enable Style/ClassVars
   end
 end

data/lib/active_reporting/datetime_drill.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ActiveReporting
+  # Builds the SQL used to drill a datetime column to a given level of a datetime hierarchy
+  module DatetimeDrill
+    # Adapters that support datetime drills, keyed by the adapter class to look for in the connection's
+    # ancestry. Matching on ancestry covers adapters built on top of these, e.g. PostGIS and Trilogy.
+    ADAPTERS = {
+      'ActiveRecord::ConnectionAdapters::PostgreSQLAdapter' => :postgresql,
+      'ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter' => :mysql,
+      'ActiveRecord::ConnectionAdapters::SQLite3Adapter' => :sqlite
+    }.freeze
+
+    module_function
+
+    # The datetime drill flavor for a connection, or nil if datetime drills are not supported for it
+    #
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+    # @return [Symbol, nil] :postgresql, :mysql, or :sqlite
+    def adapter_for(connection)
+      connection.class.ancestors.filter_map { |ancestor| ADAPTERS[ancestor.name] }.first
+    end
+
+    # @param adapter [Symbol] as returned by `adapter_for`
+    # @param drill [Symbol, String] one of `ReportingDimension::DATETIME_HIERARCHIES`
+    # @param column [String] the quoted column to drill
+    # @return [String] SQL fragment
+    def fragment(adapter, drill, column)
+      public_send(adapter, drill, column)
+    end
+
+    def postgresql(drill, column)
+      case drill.to_sym
+      when :date
+        "DATE(#{column})"
+      else
+        "DATE_TRUNC('#{drill}', #{column})"
+      end
+    end
+
+    # Mirrors Postgres' `date_trunc`, returning the truncated value as a DATETIME. Values are built from
+    # formatted strings because casting to a lower fractional precision rounds instead of truncating.
+    def mysql(drill, column)
+      year = "YEAR(#{column})"
+      sql = case drill.to_sym
+            when :microseconds then return column
+            when :milliseconds
+              return "CAST(LEFT(DATE_FORMAT(#{column}, '%Y-%m-%d %H:%i:%s.%f'), 23) AS DATETIME(3))"
+            when :second then "DATE_FORMAT(#{column}, '%Y-%m-%d %H:%i:%s')"
+            when :minute then "DATE_FORMAT(#{column}, '%Y-%m-%d %H:%i:00')"
+            when :hour then "DATE_FORMAT(#{column}, '%Y-%m-%d %H:00:00')"
+            when :day then "DATE_FORMAT(#{column}, '%Y-%m-%d 00:00:00')"
+            when :week then "DATE_SUB(DATE(#{column}), INTERVAL WEEKDAY(#{column}) DAY)"
+            when :month then "DATE_FORMAT(#{column}, '%Y-%m-01 00:00:00')"
+            when :quarter then "MAKEDATE(#{year}, 1) + INTERVAL (QUARTER(#{column}) - 1) QUARTER"
+            when :year then "MAKEDATE(#{year}, 1)"
+            when :decade then "MAKEDATE(#{year} DIV 10 * 10, 1)"
+            when :century then "MAKEDATE((#{year} - 1) DIV 100 * 100 + 1, 1)"
+            when :millennium then "MAKEDATE((#{year} - 1) DIV 1000 * 1000 + 1, 1)"
+            when :date then return "DATE(#{column})"
+            end
+      "CAST(#{sql} AS DATETIME)"
+    end
+
+    # Mirrors Postgres' `date_trunc`, returning the truncated datetime as 'YYYY-MM-DD HH:MM:SS' text
+    def sqlite(drill, column)
+      year = "CAST(STRFTIME('%Y', #{column}) AS INTEGER)"
+      case drill.to_sym
+      when :microseconds then column
+      # STRFTIME's %f rounds to the nearest millisecond, so truncate the stored fraction directly
+      when :milliseconds then "STRFTIME('%Y-%m-%d %H:%M:%S', #{column}) || SUBSTR(#{column} || '.000', 20, 4)"
+      when :second then "STRFTIME('%Y-%m-%d %H:%M:%S', #{column})"
+      when :minute then "STRFTIME('%Y-%m-%d %H:%M:00', #{column})"
+      when :hour then "STRFTIME('%Y-%m-%d %H:00:00', #{column})"
+      when :day then "STRFTIME('%Y-%m-%d 00:00:00', #{column})"
+      when :week then "STRFTIME('%Y-%m-%d 00:00:00', #{column}, '-6 days', 'weekday 1')"
+      when :month then "STRFTIME('%Y-%m-01 00:00:00', #{column})"
+      when :quarter
+        "PRINTF('%04d-%02d-01 00:00:00', #{year}, (CAST(STRFTIME('%m', #{column}) AS INTEGER) - 1) / 3 * 3 + 1)"
+      when :year then "STRFTIME('%Y-01-01 00:00:00', #{column})"
+      when :decade then "PRINTF('%04d-01-01 00:00:00', #{year} / 10 * 10)"
+      when :century then "PRINTF('%04d-01-01 00:00:00', (#{year} - 1) / 100 * 100 + 1)"
+      when :millennium then "PRINTF('%04d-01-01 00:00:00', (#{year} - 1) / 1000 * 1000 + 1)"
+      when :date then "DATE(#{column})"
+      end
+    end
+  end
+end

data/lib/active_reporting/dimension.rb

@@ -5,14 +5,14 @@ module ActiveReporting
     TYPES = { degenerate: :degenerate, standard: :standard }.freeze
     attr_reader :name
 
-    # @param model [ActiveRecord::Base]
+    # @param fact_model [ActiveReporting::FactModel]
     # @param name [Symbol]
     def initialize(fact_model, name:)
       @fact_model = fact_model
       @name       = name.to_s
     end
 
-    # Determins the type of the dimension
+    # Determines the type of the dimension
     #
     # A dimension type is either:
     #
@@ -34,18 +34,20 @@ module ActiveReporting
     #
     # @return [Boolean]
     def hierarchical?
-      @hierarchical ||= !klass.fact_model.hierarchical_levels.empty?
+      return @hierarchical if defined?(@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]
+    # @return [Class]
     def klass
       @klass ||= association ? association.klass : model
     end
 
-    # Returns the fact model's dimension
+    # Returns the fact model's ActiveRecord model
     #
     # @return [ActiveRecord::Base]
     def model
@@ -56,7 +58,9 @@ module ActiveReporting
     #
     # @return [ActiveRecord::Reflection]
     def association
-      @association ||= model.reflect_on_association(@name)
+      return @association if defined?(@association)
+
+      @association = model.reflect_on_association(@name)
     end
   end
 end

data/lib/active_reporting/fact_model.rb

@@ -7,7 +7,7 @@ module ActiveReporting
       attr_writer :measure
     end
 
-    # Explicitly sets which ActiveRecord model to to link to this fact model.
+    # Explicitly sets which ActiveRecord model 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
@@ -27,7 +27,7 @@ module ActiveReporting
                else
                  model
                end
-      @model.instance_variable_set('@fact_model', self)
+      FactModelRegistry.register(@model, self)
       @model
     end
 
@@ -104,7 +104,7 @@ module ActiveReporting
       @dimension_label_callbacks ||= {}
     end
 
-    # Sets a call back for a given dimension label. The returned value of
+    # Sets a callback 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.
     #
@@ -113,12 +113,13 @@ module ActiveReporting
     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 name [String, 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.
@@ -127,6 +128,10 @@ module ActiveReporting
     #   dimension filter is a ransack search term. Finally, you may pass in
     #   a callable object similar to defining a scope on ActiveRecord
     #
+    # @note A report applies a scope, or a lambda without parameters, for `true` and leaves it out for
+    #   `false`. A lambda with parameters is always passed the report's value. See "Dimension filter values"
+    #   in the README.
+    #
     # @example
     #   class PostFactModel < ActiveReporting::FactModel
     #     # Assumes there's an `active` scope on the model
@@ -149,6 +154,7 @@ module ActiveReporting
       unless Configuration.ransack_available
         raise RansackNotAvailable, 'Ransack not available. Please include it in your Gemfile.'
       end
+
       @ransack_fallback = true
     end
 
@@ -156,7 +162,6 @@ module ActiveReporting
     #
     # @return [Boolean]
     def self.ransack_fallback
-      @ransack_fallback ||= false
       @ransack_fallback || Configuration.ransack_fallback
     end
     private_class_method :ransack_fallback
@@ -166,11 +171,11 @@ module ActiveReporting
     # @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(name, :ransack) if ransack_fallback
-      raise UnknownDimensionFilter, "Dimension filter '#{name}' not found on fact model '#{self.name}'"
+      dimension_filter = @dimension_filters&.fetch(name.to_sym, nil)
+      return dimension_filter if dimension_filter
+      return DimensionFilter.build(name, :ransack) if ransack_fallback
+
+      raise UnknownDimensionFilter, "Dimension filter '#{name}' not found on fact model '#{self}'"
     end
   end
 end

data/lib/active_reporting/fact_model_registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+
+module ActiveReporting
+  # Maps ActiveRecord models to their fact models.
+  #
+  # Lookups are cached here instead of on the model classes so the cache can be cleared when Rails
+  # reloads code (see ActiveReporting::Railtie). Otherwise a model could keep returning a fact model
+  # from before the reload, or a fact model could keep pointing to a model from before the reload.
+  module FactModelRegistry
+    @fact_models = Concurrent::Map.new
+
+    class << self
+      # Returns the fact model for an ActiveRecord model: the `[MyModel]FactModel` class if one is
+      # defined, otherwise a generated fact model linked to the model.
+      #
+      # @param model [Class] an ActiveRecord model
+      # @return [Class] an ActiveReporting::FactModel subclass
+      def fetch(model)
+        @fact_models.fetch_or_store(model) { "#{model.name}FactModel".safe_constantize || generate(model) }
+      end
+
+      # Links an ActiveRecord model to a fact model
+      #
+      # @param model [Class] an ActiveRecord model
+      # @param fact_model [Class] an ActiveReporting::FactModel subclass
+      def register(model, fact_model)
+        @fact_models[model] = fact_model
+      end
+
+      # Forgets all looked up and registered fact models
+      def clear
+        @fact_models.clear
+      end
+
+      private
+
+      # Generated fact models are not assigned to a constant, so they never outlive a code reload or
+      # stop a `[MyModel]FactModel` defined later from being autoloaded.
+      def generate(model)
+        label = "#{model.name}FactModel (generated)"
+        Class.new(FactModel) do
+          define_singleton_method(:to_s) { label }
+          define_singleton_method(:inspect) { label }
+          self.model = model
+        end
+      end
+    end
+  end
+end

data/lib/active_reporting/metric.rb

@@ -6,8 +6,10 @@ module ActiveReporting
 
   class Metric
     extend Forwardable
+
     def_delegators :@fact_model, :model
-    attr_reader :fact_model, :name, :dimensions, :dimension_filter, :aggregate, :metric_filter, :order_by_dimension
+    attr_reader :fact_model, :name, :dimensions, :dimension_filter, :aggregate
+    attr_reader :metric_filter, :order_by_dimension, :measure
 
     def initialize(
       name,
@@ -16,15 +18,17 @@ module ActiveReporting
       dimensions: [],
       dimension_filter: {},
       metric_filter: {},
-      order_by_dimension: {}
+      order_by_dimension: {},
+      measure: nil
     )
       @name               = name.to_sym
       @fact_model         = fact_model
       @dimension_filter   = dimension_filter
-      @aggregate          = determin_aggregate(aggregate.to_sym)
-      @metric_filter      = metric_filter
+      @aggregate          = validate_aggregate(aggregate.to_sym)
+      @metric_filter      = Report.normalize_metric_filter(metric_filter)
       @dimensions         = ReportingDimension.build_from_dimensions(@fact_model, Array(dimensions))
       @order_by_dimension = order_by_dimension
+      @measure            = measure
       check_dimension_filter
     end
 
@@ -38,14 +42,15 @@ module ActiveReporting
     private ####################################################################
 
     def check_dimension_filter
-      @dimension_filter.each do |name, _|
+      @dimension_filter.each_key do |name|
         @fact_model.find_dimension_filter(name)
       end
     end
 
-    def determin_aggregate(agg)
+    def validate_aggregate(agg)
       raise UnknownAggregate, "Unknown aggregate '#{agg}'" unless AGGREGATES.include?(agg)
-      @aggregate = agg
+
+      agg
     end
   end
 end

data/lib/active_reporting/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveReporting
+  class Railtie < Rails::Railtie
+    initializer 'active_reporting.clear_fact_models_on_reload' do |app|
+      app.reloader.before_class_unload { ActiveReporting::FactModelRegistry.clear }
+    end
+  end
+end