has_helpers 5.0.2

data/lib/has_helpers/flattener/base.rb

@@ -0,0 +1,428 @@
+# typed: false
+# frozen_string_literal: true
+
+module Flattener
+  class Base
+    include ActiveModel::Model
+    attr_writer :include_for # TODO: better name; Used to determine what associations to include, defined in initializer
+    # e.g. :dw, :api, :importers
+
+    EXCLUDE_COLUMNS = ["delta", "express_add", "photo_updated_at", "photo_file_name", "photo_content_type", "photo_file_size"]
+    CONSTANT_COLUMNS = ["abbreviation", "id", "name"]
+
+    def associations
+      @associations ||= self.class.associations.select { |a| (a.for.to_a & include_for).present? }.map(&:dup)
+    end
+
+    def add(*names, **options, &block)
+      names.each do |name|
+        association = associations.detect { |a| a.ar_association.name == name }
+        associations << association = self.class.find_association(name).dup unless association
+        association.update(**options, for: Flattener::Base.default_for.keys)
+        association.flattener = Flattener.for(association.klass).new.tap { |f| f.instance_eval(&block) } if block.present?
+      end
+    end
+
+    # HACK Does this really belong inside of the flattener?
+    def add_column(name, sql_type, **options)
+      sql_column = Flattener::Column.build_sql_column(name, sql_type)
+      model_columns << Flattener::Column.new(sql_column: sql_column, klass: self.class.model_klass, association: self.class.find_column_association(sql_column.name), **options)
+    end
+
+    def remove(*args)
+      args.each do |name|
+        association = associations.detect { |a| a.ar_association_name == name }
+        associations.delete(association) if association
+      end
+    end
+
+    def join(name, **options, &block)
+      if add(name, always_include: true, merge_into_parent: true, **options, &block)
+        # rubocop:disable Rails/SkipsModelValidations
+        update_column(name.to_s.foreign_key, alias_name: :id)
+        update_column(self.class.model_klass.primary_key, alias_name: :link_id)
+        # rubocop:enable Rails/SkipsModelValidations
+      end
+    end
+
+    def columns
+      @columns ||= model_columns.
+        lazy.
+        select { |c| include_columns.blank? || include_columns.include?(c.name.to_sym) }.
+        reject { |c| exclude_columns.include?(c.name.to_sym) } # FIXME: It seems inconsistent to return string column names (from .columns) yet require symbol names for excluded columns. *
+    end
+
+    def include_for
+      @include_for ||= Flattener::Base.default_for.keys
+    end
+
+    def include_columns(*column_names)
+      (@include_columns ||= []).tap do |include_columns|
+        include_columns.concat column_names if column_names
+      end
+    end
+
+    def exclude_columns(*column_names)
+      (@exclude_columns ||= []).tap do |exclude_columns|
+        exclude_columns.concat column_names if column_names
+      end
+    end
+
+    def update_column(name, **options)
+      raise ArgumentError, "nil is not a valid column" if name.nil?
+      begin
+        columns.detect { |column| column.name.to_s == name.to_s }.update(options)
+      rescue NoMethodError
+        raise "No column `#{name}` on #{self.class.name}" if ::HasUtils::Env.development?
+      end
+    end
+
+    def flatten(depth = 1)
+      Flattener::Resource.new(flattener: self).flatten(depth)
+    end
+
+    def belongs_to(*args)
+      singleton_class.belongs_to(*args)
+    end
+
+    private
+
+    def model_columns
+      @model_columns ||= self.class.columns.to_a.
+        map(&:dup)
+    end
+
+    class << self
+      attr_writer :associations, :columns, :model_klass, :default_for
+      attr_accessor :is_pivot
+      attr_reader :pivot_columns, :pivot_associations, :pivot_count
+
+      def model_klass
+        @model_klass ||= begin
+                           klass = singleton_class? ? superclass : self # Singleton classes are not named, but in this case we really want the name of its superclass.
+                           klass.name.gsub("Flatteners::", "").constantize
+                         end
+      end
+
+      def associations
+        model_associations.reject(&:removed)
+      end
+
+      # HACK Does this really belong inside of the flattener?
+      def belongs_to(name, scope = nil, **options)
+        ar_association = ::ActiveRecord::Associations::Builder::BelongsTo.create_reflection(model_klass, name, scope, options)
+        Flattener::Association.new(ar_association).tap do |association|
+          model_associations << association
+          add_column ar_association.foreign_key, "integer"
+        end
+      end
+
+      # HACK Does this really belong inside of the flattener?
+      def has_many(name, scope = nil, **options)
+        ar_association = ::ActiveRecord::Associations::Builder::HasMany.create_reflection(model_klass, name, scope, options)
+        Flattener::Association.new(ar_association).tap do |association|
+          model_associations << association
+        end
+      end
+
+      # Defines the pivot for the current flattener.
+      # HACK: See notes for belongs_to *
+      #=== Options
+      # +:count+    The number of pivots (sets of fields) to generate. Defaults to 1.
+      # +:expand_on+  Collection or proc returning the names on which to expand. A proc may accept one argument which is the class of the parent flattener.
+      # +:is_lookup+  Set this to true if the pivot table requires a look-up.
+      #=== Examples
+      #   pivot!(count: 3)
+      #   pivot!(count: 5, expand_on: %w[home office other])
+      #   pivot!(
+      #     count: 5,
+      #     expand_on: -> (klass) { HasContactInfo::AddressLocation.scoped_to(klass)::ALL.map(&:name) }
+      #   )
+      #   pivot!(count: 5, is_lookup: true)
+      def pivot!(
+        count: 1,
+        expand_on: nil,
+        expand_over: [],
+        excluded: [/id\z/, "created_at"],
+        included: [], # Overrides excluded values
+        is_lookup: nil,
+        &block
+      )
+        self.is_pivot = true
+        @pivot_count = count
+        @pivot_expand_on = expand_on
+        @pivot_is_lookup = is_lookup
+
+        if block
+          # FIXME: This is too hacky. We need to find an alternative way to define pivots *
+          # Get a clone of the current flattener for use in evaluating the
+          # given block. This allow the pivot associations and columns to be
+          # determined while preserving the columns and associtions on the
+          # non-pivoted flattener.
+          instance = clone
+          if @model_associations.present?
+            instance.instance_eval do
+              @model_associations = @model_associations.map(&:clone)
+            end
+          end
+          instance.model_klass = model_klass # model_klass may otherwise fail since the instance class has no name.
+        else
+          instance = self
+        end
+
+        ## Determine which associations to use for the pivot
+        # Remove associations except for constants (default behavior, perhaps there is something better)
+        instance.remove(
+          *(associations.reject(&:is_constant?)).map(&:name)
+        )
+        # Eval the block after removing associations so that changes
+        # made in the block remain in effect.
+        instance.instance_eval(&block) if block
+        @pivot_associations = instance.associations.dup
+
+        # Determine the pivot columns
+        @pivot_columns = instance.columns.lazy.
+          reject { |col| excluded.any? { |ex| ex.match(col.name) } }.
+          to_a # Must force to an array to avoid an infinite loop when adding columns and otherwise incorrect results.
+
+        # Remove columns
+        exclude_columns(
+          *@pivot_columns.lazy.
+            reject do |col|
+            # Do not exclude any columns which have been explicitly included.
+            included.any? { |inc| inc.match(col.name) }
+          end.
+            map(&:name).
+            map(&:to_sym)
+        )
+
+        @pivot_columns.concat(
+          instance.send(:model_columns).
+            select do |col|
+            included.any? { |inc| inc.match(col.name) }
+          end.
+            to_a
+        )
+
+        # Add expansions
+        expansions = Array(expand_over)
+        expansions << nil if expansions.none? # Add a blank entry which provides a value to iterate over.
+
+        expansions.each do |expansion|
+          expansion = "#{ expansion.underscore }_" if expansion
+          (1..count).each do |idx|
+            # add expanded columns
+            @pivot_columns.each do |col|
+              add_column("#{ expansion }#{ col.name.to_sym }_#{ idx }", col.sql_type)
+            end
+
+            # add expanded associations
+            @pivot_associations.each do |assoc|
+              add_column("#{ expansion }#{ assoc.foreign_key }_#{ idx }", "integer")
+              add_column("#{ expansion }#{ assoc.foreign_key.to_s.remove(/_id\z/) }_#{ idx }", "character varying")
+            end
+          end
+        end
+      end
+
+      # If the current flattener is a pivot then this method returns a class
+      # which generates only the pivots attributes and associations. Otherwise,
+      # it returns the current flattener class.
+      def pivot_or_self
+        if is_pivot
+          # Return a duplicate of the current flattener class with the
+          # pivot additions mixed in.
+          self.dup.tap do |klass|
+            klass.prepend(::Flattener::Pivot)
+            klass.is_lookup = @pivot_is_lookup
+          end
+        else
+          self
+        end
+      end
+
+      alias is_pivot? is_pivot
+
+      def pivot_expand_on(klass = nil)
+        if @pivot_expand_on.respond_to?(:call)
+          @pivot_expand_on.call(*klass)
+        else
+          Array(@pivot_expand_on)
+        end
+      end
+
+      def columns
+        @columns ||= model_columns.
+          lazy.
+          select { |sql_column| include_column?(sql_column) }
+      end
+
+      def exclude_columns(*column_names)
+        (@exclude_columns ||= []).tap do |exclude_columns|
+          exclude_columns.concat column_names if column_names
+        end
+      end
+
+      def default_for
+        @default_for ||= {}
+      end
+
+      def include_column?(column)
+        EXCLUDE_COLUMNS.exclude?(column.name) && exclude_columns.exclude?(column.name.to_sym) && (!is_constant?(model_klass) || bypass_constant_column_removals? || CONSTANT_COLUMNS.include?(column.name))
+      end
+
+      # When including HasHelpers::Constant to a class this removes all columns
+      # that are not from the constants relation. This will bypass that validation if true including other columns
+      def bypass_constant_column_removals?(bypass = false)
+        @bypass_constant_column_removals ||= bypass
+      end
+
+      def is_constant?(klass = model_klass)
+        klass.include?(HasHelpers::Constant)
+      end
+
+      def model_associations
+        @model_associations ||= model_klass.reflect_on_all_associations.map { |a| Flattener::Association.new(a) }
+      end
+
+      def model_columns
+        @model_columns ||= begin
+                             # Flatteners are loaded before running migrations
+                             # Only load columns if the table exists
+                             connection = ::ActiveRecord::Base.connection
+                             table_name = model_klass.table_name
+
+                             model_klass_columns =
+                               if connection.table_exists?(table_name) || connection.view_exists?(table_name)
+                                 model_klass.columns
+                               else
+                                 []
+                               end
+                             model_klass_columns.map { |sql_column| Flattener::Column.new(sql_column: sql_column, klass: model_klass, association: find_column_association(sql_column.name)) }
+                           end
+      end
+    end
+
+    # rubocop:disable Lint/IneffectiveAccessModifier
+    def self.flatten(trait: nil)
+      new.tap do |flattener|
+        flattener.instance_eval(&traits[trait]) if traits[trait]
+      end.flatten
+    end
+
+    # Add/update an association to to be included when using a flattener.
+    #
+    # Examples
+    #
+    #  Flattener.for(Advisor).add :bank_accounts, for: [:dw, api]
+    #  the 'for:' argument will default to all of the options available
+    #
+    #  class Flatteners::Advisor < Flattener::Base
+    #     add :errors_and_omissions
+    #  end
+    #
+    def self.add(*args, **options, &block)
+      args.each do |name|
+        if (association = find_association(name))
+          association.update(**options, for: ::Flattener::Base.default_for.lazy.map { |k| k.first }, removed: false)
+          association.flattener = Flattener.for(association.klass).new.tap { |f| f.instance_eval(&block) } if block.present?
+        end
+      end
+    end
+
+    # Add a custom column to the flattener
+    #
+    # Example
+    #
+    #  Flattener.for(Advisor).add_column :amount, "numeric(20,5)"
+    #  Flattener.for(Advisor).add_column :name, "text"
+    #
+    # HACK Does this really belong inside of the flattener?
+    def self.add_column(name, sql_type, **options)
+      sql_column = Flattener::Column.build_sql_column(name, sql_type)
+      model_columns << Flattener::Column.new(sql_column: sql_column, klass: model_klass, association: find_column_association(sql_column.name), **options)
+    end
+
+    # Remove a association(s) from use by the flattener
+    #
+    # Example
+    #
+    #  Flattener.for(Advisor).remove :bank_accounts, :errors_and_omissions
+    #
+    def self.remove(*args)
+      args.each do |name|
+        if (association = find_association(name))
+          association.remove
+        end
+      end
+    end
+
+    # Adds/updates an association, usually on a join table, aliases the foreign
+    # key of the added association to :id, and aliases the primary key to :link_id.
+    #
+    # This is for the benefit of the end user not having to understand the database
+    # relationships
+    #
+    # Example
+    #
+    #  class Flatteners::BankAccountOwner < Flattener::Base
+    #    alias :bank_account
+    #    join :bank_account
+    #  end
+    #
+    #  # In this example, the end result of flattening will produce:
+    #  # - :bank_account_owner aliased to :bank_account
+    #  # - an attribute `bank_account_id`, which is the bank_account_owner's :bank_account_id
+    #  # - an attribue  `bank_account_link_id`, which is the bank_account_owner's :id
+    #
+    def self.join(name, **options, &block)
+      if add(name, always_include: true, merge_into_parent: true, **options, &block)
+        # rubocop:disable Rails/SkipsModelValidations
+        update_column(name.to_s.foreign_key, alias_name: :id)
+        update_column(model_klass.primary_key, alias_name: :link_id)
+        # rubocop:enable Rails/SkipsModelValidations
+      end
+    end
+
+    # Traits allow you to name groups of flattener settings inside of a block.
+    #
+    # Example
+    #
+    #  class Flatteners::Advisor < Flattener::Base
+    #    trait :dw do
+    #      exclude_columns :organization_id
+    #      remove :adjustments
+    #    end
+    #  end
+    #
+    #  Flattener.for(Advisor).flatten(trait: :dw)
+    #
+    def self.trait(trait_name, &block)
+      traits[trait_name] = block
+    end
+
+    def self.update_column(name, **options)
+      raise ArgumentError, "nil is not a valid column" if name.nil?
+      begin
+        columns.detect { |column| column.name.to_s == name.to_s }.update(options)
+      rescue NoMethodError
+        raise "No column `#{name}` on #{self.name}" if ::HasUtils::Env.development?
+      end
+    end
+
+    def self.find_association(name)
+      model_associations.detect { |a| a.ar_association_name == name }
+    end
+
+    def self.find_column_association(foreign_key)
+      model_associations.detect { |a| a.macro != :has_many && a.ar_association.foreign_key.to_s == foreign_key.to_s }
+    end
+
+    def self.traits
+      @traits ||= {}
+    end
+
+    private_class_method :traits
+    # rubocop:enable Lint/IneffectiveAccessModifier
+  end
+end

data/lib/has_helpers/flattener/column/types.rb

@@ -0,0 +1,71 @@
+# typed: false
+# frozen_string_literal: true
+
+module Flattener
+  class Column
+    # FIXME: This can probably be moved elsewhere *
+    module Types
+      # Normalized data types
+      ALL = [
+        STRING = :string,
+        CURRENCY = :currency,
+        PERCENT = :percent,
+        DATE = :date,
+        DATETIME = :datetime,
+        BOOLEAN = :boolean,
+        TEXT = :text,
+        INTEGER = :integer,
+        DECIMAL = :decimal,
+        FLOAT = :float,
+        JSON = :json,
+        ARRAY = :array,
+        UUID = :uuid,
+        INTERVAL = :interval
+      ]
+
+      #=== Params
+      # +raw_sql_type+: The description of the SQL type, e.g. "boolean", "date", "character varying(63)", "timestamp without time zone"
+      def self.sql_type_to_type(raw_sql_type)
+        sql_type = raw_sql_type.to_s.downcase # Some mild normalization to allow a broader domain range.
+        type =
+          if sql_type =~ /character varying/ || sql_type == "string" || sql_type == "import_key"
+            STRING
+          elsif /\A(?:numeric|decimal)(?:\((?<precision>\d+),(?<scale>\d+)\))?\z/ =~ sql_type
+            # FIXME: This handles numeric (no scale and precision) to work around the current state of the DW. This should be removed once all numeric columns have scale and precision set. *
+            # elsif /\A(numeric|decimal)\((?<precision>\d+),(?<scale>\d+)\)\z/ =~ sql_type
+            if (precision == "7" && scale == "2") || # App small $
+               (precision == "12" && scale == "2") || # App large $
+               (precision == "20" && scale == "5") # DW $
+              CURRENCY
+            elsif precision == "6" && scale == "3" || precision == "9" && scale == "6"
+              PERCENT
+            else
+              DECIMAL
+            end
+          elsif sql_type == "date"
+            DATE
+          elsif sql_type =~ /timestamp/ || sql_type == "datetime" || sql_type == "past_or_present_date"
+            DATETIME
+          elsif sql_type == "boolean" || sql_type == "bi_state_boolean"
+            BOOLEAN
+          elsif sql_type == "text"
+            TEXT
+          elsif sql_type == "integer" || sql_type == "bigint"
+            INTEGER
+          elsif sql_type == "double precision"
+            FLOAT
+          elsif sql_type == "json" || sql_type == "jsonb"
+            JSON
+          elsif sql_type == "array"
+            ARRAY
+          elsif sql_type == "uuid"
+            UUID
+          elsif sql_type == "interval"
+            INTERVAL
+          end
+
+        type || raise(::ArgumentError, "No type matches SQL type '#{ raw_sql_type }'")
+      end
+    end
+  end
+end

data/lib/has_helpers/flattener/column.rb

@@ -0,0 +1,97 @@
+# typed: true
+# frozen_string_literal: true
+
+require "has_helpers/flattener/column/types"
+
+module Flattener
+  class Column
+    include ActiveModel::Model
+
+    attr_accessor :association, :sql_column, :klass, :alias_name, :reject_if
+    attr_writer :type, :expand_on, :partial_type_id
+    TIMESTAMP_COLUMNS = ["created_at", "updated_at"]
+
+    delegate :sql_type, :name, to: :sql_column
+
+    def update(args)
+      args.each do |k, v|
+        send("#{k}=", v)
+      end
+    end
+
+    delegate :table_name, to: :klass
+
+    def is_primary_key?
+      klass.primary_key == name
+    end
+
+    def is_timestamp?
+      TIMESTAMP_COLUMNS.include? name
+    end
+
+    def is_percent?
+      sql_column.cast_type.scale == 4
+    end
+
+    def is_currency?
+      sql_column.cast_type.scale == 2 || sql_column.cast_type.scale == 5
+    end
+
+    # Returns the column's expansions
+    #
+    # == Example
+    # array of strings (default expansion column is `type`)::
+    #   `update_column :override, expand_on: ["Approved", "Submitted"]`
+    # array of hashes::
+    #   `update_column :amount, expand_on: [{value: "Single", column_name: "product_option"}, {value: "Target", column_name: "product_option"}]`
+    # proc::
+    #   `update_column :amount, expand_on: proc { ProductType.all.map(&:name) }
+    #
+    # @return [Array] Array of expansion hashes
+    def expand_on
+      return @expand_on if @expand_on_memoized
+      @expand_on_memoized = true
+      @expand_on = @expand_on.call if @expand_on.is_a?(Proc)
+      @expand_on = Array(@expand_on).map do |expansion|
+        expansion.is_a?(Hash) ? expansion : { value: expansion, column_name: "type" }
+      end
+    end
+
+    def description
+      @description ||= ActiveRecord::Base.connection.execute(<<-SQL).values[0][0]
+        SELECT d.description
+        FROM pg_attribute a
+                 LEFT JOIN pg_description d
+                           ON a.attrelid = d.objoid AND a.attnum = d.objsubid
+        WHERE a.attrelid = '#{table_name}'::regclass
+          AND a.attnum > 0
+          AND NOT a.attisdropped
+          AND a.attname = '#{name}';
+              SQL
+    end
+
+    def partial_type_id
+      if @partial_type_id.is_a?(Proc)
+        @partial_type_id.call
+      else
+        @partial_type_id
+      end
+    end
+
+    def type
+      @type ||= ::Flattener::Column::Types.sql_type_to_type(sql_type)
+    end
+
+    def self.build_sql_column(name, sql_type)
+      cast_type =
+        ActiveRecord::Base.connection.send(:lookup_cast_type, sql_type) ||
+        ActiveRecord::Type.lookup(sql_type.to_s.sub(/\(.+\)\z/, "").to_sym)
+
+      OpenStruct.new(
+        name: name.to_s,
+        sql_type: sql_type,
+        cast_type: cast_type
+      )
+    end
+  end
+end

data/lib/has_helpers/flattener/pivot.rb

@@ -0,0 +1,49 @@
+# typed: false
+# frozen_string_literal: true
+
+require "delegate"
+
+# Turns a Flattener class into a pivoted Flattener class.
+# It is recommended that you use this with duplicates of the
+# original flattener class.
+#
+#=== Examples
+#   flattener_klass = Flattener.for(Phone).dup
+#   flattener_klass.prepend(Flattener::Pivot)
+module Flattener
+  module Pivot
+    def self.prepended(klass)
+      klass.singleton_class.prepend(ClassMethods)
+
+      class << klass
+        attr_accessor :is_lookup
+      end
+    end
+
+    module SingletonClassMethods
+      delegate :associations, to: :class
+
+      delegate :columns, to: :class
+    end
+
+    module ClassMethods
+      def new
+        super.tap do |instance|
+          instance.singleton_class.prepend(SingletonClassMethods)
+        end
+      end
+
+      def associations
+        pivot_associations
+      end
+
+      def columns
+        pivot_columns
+      end
+
+      def is_lookup?
+        !!is_lookup
+      end
+    end
+  end
+end

data/lib/has_helpers/flattener/reset.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+module Flattener
+  # When included this module removes the dependencies of Flattener::Base on the
+  # table underlying the model class by essentially wiping the slate and starting
+  # from an empty set of columns and associations. Think of it as the equivalent
+  # of reset.css for flatteners. This is useful for cases where data warehouse
+  # table does not correspond very directly to a transactional table or model.
+  #
+  # Include this module into a flattener class:
+  #
+  #   class MyFlattener < Flattener::Base
+  #     include Flattener::Reset
+  #     # Yay, columns and associations are empty and ready to be configured!
+  #     # ...
+  #   end
+  module Reset
+    def self.included(klass)
+      klass.singleton_class.prepend(ClassInstanceMethods)
+    end
+
+    module ClassInstanceMethods
+      def model_associations
+        @model_associations ||= []
+      end
+
+      def model_columns
+        @model_columns ||= []
+      end
+    end
+  end
+end