active_reporting 0.6.2 → 1.0.0

data/lib/active_reporting/reporting_dimension.rb

@@ -4,13 +4,17 @@ require 'forwardable'
 module ActiveReporting
   class ReportingDimension
     extend Forwardable
-    SUPPORTED_DBS = %w[PostgreSQL PostGIS Mysql2].freeze
+
     # Values for the Postgres `date_trunc` method.
-    # See https://www.postgresql.org/docs/10/static/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC
+    # See https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC
     DATETIME_HIERARCHIES = %i[microseconds milliseconds second minute hour day week month quarter year decade
                               century millennium date].freeze
+    # Column types a datetime drill can be used on. PostgreSQL reports `timestamp with time zone` columns as
+    # `timestamptz`, and `timestamp without time zone` columns as `timestamp` when its `datetime_type` is
+    # `:timestamptz`.
+    DATETIME_DRILL_COLUMN_TYPES = %i[datetime timestamp timestamptz date].freeze
     JOIN_METHODS = { joins: :joins, left_outer_joins: :left_outer_joins }.freeze
-    attr_reader :join_method, :label
+    attr_reader :join_method, :label, :label_name
 
     def_delegators :@dimension, :name, :type, :klass, :association, :model, :hierarchical?
 
@@ -19,15 +23,17 @@ module ActiveReporting
         dimension_name, options = dim.is_a?(Hash) ? Array(dim).flatten : [dim, nil]
         found_dimension = fact_model.dimensions[dimension_name.to_sym]
 
-        raise(UnknownDimension, "Dimension '#{dimension_name}' not found on fact model '#{fact_model}'") if found_dimension.nil?
+        if found_dimension.nil?
+          raise(UnknownDimension,
+                "Dimension '#{dimension_name}' not found on fact model '#{fact_model}'")
+        end
 
-        # Ambiguous behavior with string option for degenerate and standard dimension
-        if !options.is_a?(Hash) && found_dimension.type == Dimension::TYPES[:degenerate]
-          ActiveSupport::Deprecation.warn <<~EOS
-            direct use of implict hierarchies is deprecated and will be removed in future versions. \
-            Please use `:datetime_drill` option instead.
-          EOS
-          options = { datetime_drill: options }
+        # The `{ created_at: :month }` shorthand for datetime drills was removed in 0.7.0
+        if options && !options.is_a?(Hash) && found_dimension.type == Dimension::TYPES[:degenerate]
+          raise InvalidDimensionLabel,
+                "'#{dimension_name}' is not hierarchical. For a datetime drill, use " \
+                "`{ #{dimension_name}: { datetime_drill: :#{options} } }` " \
+                "instead of `{ #{dimension_name}: :#{options} }`"
         end
         new(found_dimension, **label_config(options))
       end
@@ -39,9 +45,7 @@ module ActiveReporting
     #
     # @param [Symbol|Hash] options
     def self.label_config(options)
-      unless options.is_a?(Hash)
-        return { label: options }
-      end
+      return { label: options } unless options.is_a?(Hash)
 
       {
         label: options[:field],
@@ -75,7 +79,7 @@ module ActiveReporting
     # @return [Array]
     def select_statement(with_identifier: true)
       ss = ["#{label_fragment} AS #{label_fragment_alias}"]
-      ss << "#{identifier_fragment} AS #{identifier_fragment_alias}" if with_identifier && type == Dimension::TYPES[:standard]
+      ss << "#{identifier_fragment} AS #{identifier_fragment_alias}" if with_identifier && identifiable?
       ss
     end
 
@@ -84,7 +88,7 @@ module ActiveReporting
     # @return [Array]
     def group_by_statement(with_identifier: true)
       group = [label_fragment]
-      group << identifier_fragment if with_identifier && type == Dimension::TYPES[:standard]
+      group << identifier_fragment if with_identifier && identifiable?
       group
     end
 
@@ -93,36 +97,52 @@ module ActiveReporting
     # @return [String]
     def order_by_statement(direction:)
       direction = direction.to_s.upcase
-      raise "Ording direction should be 'asc' or 'desc'" unless %w[ASC DESC].include?(direction)
+      unless %w[ASC DESC].include?(direction)
+        raise InvalidOrderDirection,
+              "Ordering direction for #{name} should be 'asc' or 'desc', got '#{direction.downcase}'"
+      end
+
       "#{label_fragment} #{direction}"
     end
 
+    # Tells if the dimension's identifier is included in queries when the report asks for identifiers.
+    #
+    # Only a standard dimension labeled by its default label has one row per record. Grouping a dimension
+    # drilled to a hierarchy level or datetime by its identifier as well would split each roll-up back into one
+    # row per record.
+    #
+    # @return [Boolean]
+    def identifiable?
+      type == Dimension::TYPES[:standard] && @datetime_drill.nil? && @label == dimension_fact_model.dimension_label
+    end
+
     # Looks up the dimension label callback for the label
     #
     # @return [Lambda, NilClass]
     def label_callback
-      klass.fact_model.dimension_label_callbacks[@label]
+      klass.fact_model.dimension_label_callbacks[@label.to_sym]
     end
 
     private ####################################################################
 
     def determine_label_field(label_field)
-      @label = if label_field.present? && validate_hierarchical_label(label_field)
-                 type == Dimension::TYPES[:degenerate] ? name : label_field.to_sym
-               elsif type == Dimension::TYPES[:degenerate]
+      validate_hierarchical_label(label_field) if label_field.present?
+
+      @label = if type == Dimension::TYPES[:degenerate]
                  name
+               elsif label_field.present?
+                 label_field.to_sym
                else
                  dimension_fact_model.dimension_label || Configuration.default_dimension_label
                end
     end
 
     def determine_label_name(label_name)
-
       if label_name
         @label_name = label_name
       else
         @label_name = name
-        @label_name += "_#{@label}" if (type == Dimension::TYPES[:standard] && @label != :name)
+        @label_name += "_#{@label}" if type == Dimension::TYPES[:standard] && @label != :name
         @label_name += "_#{@datetime_drill}" if @datetime_drill
       end
       @label_name
@@ -130,6 +150,7 @@ module ActiveReporting
 
     def determine_datetime_drill(datetime_drill)
       return unless datetime_drill
+
       validate_supported_database_for_datetime_hierarchies
       validate_against_datetime_hierarchies(datetime_drill)
       validate_label_is_datetime
@@ -147,18 +168,19 @@ module ActiveReporting
     end
 
     def validate_hierarchical_label(hierarchical_label)
-      validate_dimension_is_hierachical(hierarchical_label)
+      validate_dimension_is_hierarchical(hierarchical_label)
       validate_against_fact_model_properties(hierarchical_label)
-      true
     end
 
-    def validate_dimension_is_hierachical(hierarchical_label)
+    def validate_dimension_is_hierarchical(hierarchical_label)
       return if hierarchical?
+
       raise InvalidDimensionLabel, "#{name} must be hierarchical to use label #{hierarchical_label}"
     end
 
     def validate_supported_database_for_datetime_hierarchies
-      return if SUPPORTED_DBS.include?(model.connection.adapter_name)
+      return if datetime_drill_adapter
+
       raise InvalidDimensionLabel,
             "Cannot utilize datetime grouping for #{name}; " \
             "database #{model.connection.adapter_name} is not supported"
@@ -166,67 +188,26 @@ module ActiveReporting
 
     def validate_against_datetime_hierarchies(hierarchical_label)
       return if DATETIME_HIERARCHIES.include?(hierarchical_label.to_sym)
+
       raise InvalidDimensionLabel, "#{hierarchical_label} is not a valid datetime grouping label in #{name}"
     end
 
     def validate_label_is_datetime
-      return if dimension_fact_model.model.column_for_attribute(@label).type == :datetime
-      raise InvalidDimensionLabel, "'#{@label}' is not a datetime column"
+      return if DATETIME_DRILL_COLUMN_TYPES.include?(dimension_fact_model.model.column_for_attribute(@label).type)
+
+      raise InvalidDimensionLabel, "'#{@label}' is not a datetime or date column"
     end
 
     def validate_against_fact_model_properties(hierarchical_label)
       return if dimension_fact_model.hierarchical_levels.include?(hierarchical_label.to_sym)
-      raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
-    end
 
-    def datetime_drill_label_fragment(column)
-      if model.connection.adapter_name == "Mysql2"
-        datetime_drill_mysql(column)
-      else # Postgress
-        datetime_drill_postgress(column)
-      end
+      raise InvalidDimensionLabel, "#{hierarchical_label} is not a hierarchical label in #{name}"
     end
 
-    def datetime_drill_postgress(column)
-      case @datetime_drill.to_sym
-      when :date
-        "DATE('#{column}')"
-      else
-        "DATE_TRUNC('#{@datetime_drill}', #{column})"
-      end
-    end
+    def datetime_drill_adapter
+      return @datetime_drill_adapter if defined?(@datetime_drill_adapter)
 
-    def datetime_drill_mysql(column)
-      case @datetime_drill.to_sym
-      when :microseconds
-        "MICROSECOND(#{column})"
-      when :milliseconds
-        "MICROSECOND(#{column}) DIV 1000"
-      when :second
-        "SECOND(#{column})"
-      when :minute
-        "MINUTE(#{column})"
-      when :hour
-        "HOUR(#{column})"
-      when :day
-        "DAY(#{column})"
-      when :week
-        "WEEKDAY(#{column})"
-      when :month
-        "MONTH(#{column})"
-      when :quarter
-        "QUARTER(#{column})"
-      when :year
-        "YEAR(#{column})"
-      when :decade
-        "YEAR(#{column}) DIV 10"
-      when :century
-        "YEAR(#{column}) DIV 100"
-      when :millennium
-        "YEAR(#{column}) DIV 1000"
-      when :date
-        "DATE(#{column})"
-      end
+      @datetime_drill_adapter = DatetimeDrill.adapter_for(model.connection)
     end
 
     def identifier_fragment
@@ -234,17 +215,17 @@ module ActiveReporting
     end
 
     def identifier_fragment_alias
-      "#{model.connection.quote_column_name("#{name}_identifier")}"
+      model.connection.quote_column_name("#{name}_identifier").to_s
     end
 
     def label_fragment
       fragment = "#{klass.quoted_table_name}.#{model.connection.quote_column_name(@label)}"
-      fragment = datetime_drill_label_fragment(fragment) if @datetime_drill
+      fragment = DatetimeDrill.fragment(datetime_drill_adapter, @datetime_drill, fragment) if @datetime_drill
       fragment
     end
 
     def label_fragment_alias
-      "#{model.connection.quote_column_name(@label_name)}"
+      model.connection.quote_column_name(@label_name).to_s
     end
 
     def dimension_fact_model

data/lib/active_reporting/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveReporting
-  VERSION = '0.6.2'
+  VERSION = '1.0.0'
 end

data/lib/active_reporting.rb

@@ -3,43 +3,63 @@
 require 'active_record'
 require 'active_reporting/active_record_adaptor'
 require 'active_reporting/configuration'
+require 'active_reporting/datetime_drill'
 require 'active_reporting/dimension'
 require 'active_reporting/dimension_filter'
 require 'active_reporting/metric'
 require 'active_reporting/fact_model'
+require 'active_reporting/fact_model_registry'
 require 'active_reporting/report'
 require 'active_reporting/reporting_dimension'
 require 'active_reporting/version'
+require 'active_reporting/railtie' if defined?(Rails::Railtie)
 
-begin
-  require 'ransack'
-  ActiveReporting::Configuration.ransack_available = true
-rescue LoadError, StandardError
-  ActiveReporting::Configuration.ransack_available = false
-end
-
-ActiveRecord::Base.extend(ActiveReporting::ActiveRecordAdaptor)
+ActiveSupport.on_load(:active_record) { extend ActiveReporting::ActiveRecordAdaptor }
 
 module ActiveReporting
   def self.fetch_metric(name)
-    klass = Configuration.metric_lookup_class
-    unless defined?(klass.constantize)
+    klass_name = Configuration.metric_lookup_class
+    klass = klass_name.safe_constantize
+    if klass.nil?
       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=`.'
+            "#{klass_name} 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'"
+    unless klass.respond_to?(:lookup)
+      raise BadMetricLookupClass, "#{klass_name} needs to define a class method called 'lookup'"
     end
-    klass.constantize.lookup(name)
+
+    klass.lookup(name)
+  end
+
+  class BadMetricLookupClass < StandardError
+  end
+
+  class InvalidDimensionLabel < StandardError
+  end
+
+  # Subclasses RuntimeError, which was raised for invalid directions before this class existed
+  class InvalidOrderDirection < RuntimeError
+  end
+
+  class RansackNotAvailable < StandardError
   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)
-  UnknownJoinMethod       = Class.new(StandardError)
+  class UnknownAggregate < StandardError
+  end
+
+  class UnknownDimension < StandardError
+  end
+
+  class UnknownDimensionFilter < StandardError
+  end
+
+  class UnknownMetric < StandardError
+  end
+
+  class UnknownMetricFilterOperator < StandardError
+  end
+
+  class UnknownJoinMethod < StandardError
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_reporting
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Tony Drake
-autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2024-03-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,161 +15,61 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  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'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: mysql2
-  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'
-- !ruby/object:Gem::Dependency
-  name: pg
-  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'
-- !ruby/object:Gem::Dependency
-  name: rake
-  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'
-- !ruby/object:Gem::Dependency
-  name: ransack
-  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'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  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: 
+        version: '8.0'
+description: ActiveReporting implements ROLAP (Relational Online Analytical Processing)
+  concepts such as fact models, dimensions, and metrics on top of ActiveRecord, providing
+  a DSL for describing reports and analytics on your data.
 email:
 - t27duck@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/dependabot.yml"
-- ".github/workflows/tests.yml"
-- ".gitignore"
-- ".rubocop.yml"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- active_reporting.gemspec
-- bin/console
-- bin/setup
 - lib/active_reporting.rb
 - lib/active_reporting/active_record_adaptor.rb
 - lib/active_reporting/configuration.rb
+- lib/active_reporting/datetime_drill.rb
 - lib/active_reporting/dimension.rb
 - lib/active_reporting/dimension_filter.rb
 - lib/active_reporting/fact_model.rb
+- lib/active_reporting/fact_model_registry.rb
 - lib/active_reporting/metric.rb
+- lib/active_reporting/railtie.rb
 - lib/active_reporting/report.rb
 - lib/active_reporting/reporting_dimension.rb
 - lib/active_reporting/version.rb
 homepage: https://github.com/t27duck/active_reporting
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  bug_tracker_uri: https://github.com/t27duck/active_reporting/issues
+  changelog_uri: https://github.com/t27duck/active_reporting/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/t27duck/active_reporting
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -178,15 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Add relational OLAP-like functionality for ActiveRecord
 test_files: []

data/.github/dependabot.yml

@@ -1,11 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"