hotstepper 0.1.0

data/lib/hotstepper/engine.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  class Engine < ::Rails::Engine
+    initializer "hotstepper.i18n" do
+      ActiveSupport.on_load(:i18n) do
+        I18n.backend.eager_load!
+
+        [Dry::Schema, Dry::Validation::Contract].each do |lib|
+          lib.config.messages.backend = :i18n
+          lib.config.messages.load_paths << Hotstepper::Engine.root.join("config", "locales", "custom-predicates.en.yml").realpath
+          lib.config.messages.load_paths << Rails.root.join("config", "locales", "en.yml").realpath
+        end
+      end
+    end
+
+    initializer "hotstepper.models" do
+      ActiveSupport.on_load(:active_record) do
+        extend Hotstepper::ArelExt::Helpers
+
+        include Hotstepper::Models::Model
+      end
+
+      if defined?(ApplicationRecord)
+        Hotstepper.config.db.connection_class = ApplicationRecord
+      end
+    end
+
+    # Wire up the `Hotstepper::Common` infrastructure.
+    initializer "hotstepper.operation_integration" do
+      config.to_prepare do
+        Hotstepper.configure do |config|
+          config.common.container = Dry::Rails::Railtie.container
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/association_helpers.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # Helpers for defining certain types of associations.
+    module AssociationHelpers
+      extend ActiveSupport::Concern
+
+      include Hotstepper::Models::LookupHelpers
+
+      module ClassMethods
+        # @param [Symbol] name
+        # @param [Class] model_klass
+        # @return [Boolean] whether the association with the given name
+        def associated_against?(name, model_klass)
+          has_association_for?(name) { _1.klass == model_klass }
+        end
+
+        # Delegate a scope to an association.
+        #
+        # * For `has_many` associations, it will use a subquery to filter
+        #   the parent model by the associated records matching the delegated scope.
+        #   This avoids the cartesian issue with joining against many child records.
+        # * For `has_one` and `belongs_to` associations, it will use an `INNER JOIN`
+        #   and merge the delegated scope directly.
+        # @param [Symbol] name
+        # @param [Symbol] association_name
+        # @param [Symbol] target_name
+        # @return [void]
+        def delegate_scope!(name, association_name, target_name: name)
+          scope_definition = ->(*args, **kwargs) do
+            association = reflect_on_association(association_name)
+
+            delegated = association.klass.public_send(target_name, *args, **kwargs)
+
+            if association.has_one? || association.belongs_to?
+              joins(association_name).merge(delegated)
+            else
+              where(id: delegated.select(association.foreign_key))
+            end
+          end
+
+          scope name, scope_definition
+        end
+
+        # @see #delegate_scope!
+        # @param [<Symbol>] names the names of the scopes to delegate
+        # @param [Symbol] to the association to delegate to
+        # @return [void]
+        def delegate_scopes!(*names, to:)
+          # :nocov:
+          names.each do |scope|
+            delegate_scope! name, to
+          end
+          # :nocov:
+        end
+
+        # @param [Symbol] name
+        # @param [Symbol] association_name
+        # @param [Symbol] scope_name
+        # @return [void]
+        def delegate_lookup!(name, association_name, scope_name: :"lookup_by_#{name}")
+          delegate_scope! scope_name, association_name
+        end
+
+        # @see #delegate_lookup!
+        # @param [<Symbol>] names the names of the lookups to delegate
+        # @param [Symbol] to the association to delegate to
+        # @return [void]
+        def delegate_lookups!(*names, to:)
+          names.each do |name|
+            delegate_lookup! name, to
+          end
+        end
+
+        # Define a read-only `belongs_to` association
+        #
+        # @note This is more of a semantic association type in order to avoid the need
+        #   to declare what to do with dependents or inverse associations when they
+        #   are not necessary.
+        # @param [Symbol] name
+        # @param [<Object>] args
+        # @param [{ Symbol => Object }] kwargs
+        # @yield Set up the belongs_to association
+        # @yieldreturn [void]
+        # @!macro [attach] belongs_to_readonly
+        #   @!parse ruby
+        #     # @note This association is read-only (likely against a database view).
+        #     belongs_to $1, -> { readonly }, ${2--1}
+        def belongs_to_readonly(name, *args, **kwargs, &)
+          belongs_to(name, *args, **kwargs, &)
+        end
+
+        # @param [Symbol] association_name
+        # @yieldreturn [Boolean]
+        # @return [Boolean] whether the model has an association with the given name
+        def has_association_for?(association_name)
+          assoc = reflect_on_association(association_name)
+
+          return false if assoc.blank?
+
+          block_given? ? yield(assoc) : true
+        end
+
+        # Define a read-only `has_many` association.
+        #
+        # @note This is more of a semantic association type in order to avoid the need
+        #   to declare what to do with dependents or inverse associations when they
+        #   are not necessary.
+        # @param [Symbol] name
+        # @param [<Object>] args
+        # @param [{ Symbol => Object }] kwargs
+        # @yield Set up the has_many association
+        # @yieldreturn [void]
+        # @!macro [attach] has_many_readonly
+        #   @!parse ruby
+        #     # @note This association is read-only (likely against a database view).
+        #     has_many $1, -> { readonly }, ${2--1}
+        def has_many_readonly(name, *args, **kwargs, &)
+          has_many(name, *args, **kwargs, &)
+        end
+
+        # Define a read-only `has_one` association.
+        #
+        # @note This is more of a semantic association type in order to avoid the need
+        #   to declare what to do with dependents or inverse associations when they
+        #   are not necessary.
+        # @param [Symbol] name
+        # @param [<Object>] args
+        # @param [{ Symbol => Object }] kwargs
+        # @yield Set up the has_one association
+        # @yieldreturn [void]
+        # @!macro [attach] has_one_readonly
+        #   @!parse ruby
+        #     # @note This association is read-only (likely against a database view).
+        #     has_one $1, -> { readonly }, ${2--1}
+        def has_one_readonly(name, *args, **kwargs, &) = has_one(name, *args, **kwargs, &)
+      end
+    end
+  end
+end

data/lib/hotstepper/models/checks_before_destruction.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # A concern to determine if a given model has any populated associations
+    # with a dependent option set to `:restrict_with_error` or `:restrict_with_exception`.
+    #
+    # It is used for easy validation in destroy mutations.
+    module ChecksBeforeDestruction
+      extend ActiveSupport::Concern
+
+      RESTRICTS_WITH = /\Arestrict_with/
+
+      # @param [Symbol] name
+      def has_existing_association?(name) = association(name).scope.exists?
+
+      def has_protected_dependents? = protected_dependents.any?
+
+      def protected_dependents
+        self.class.protected_associations.each_with_object([]) do |assoc, names|
+          names << assoc.name if has_existing_association?(assoc.name)
+        end
+      end
+
+      module ClassMethods
+        # @return [<ActiveRecord::Reflection::HasManyReflection>]
+        def protected_associations
+          @protected_associations ||= reflect_on_all_associations.select do |assoc|
+            RESTRICTS_WITH.match? assoc.options[:dependent]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/id_quoting.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    module IdQuoting
+      extend ActiveSupport::Concern
+
+      # Quote the model's primary key if it is persisted and a single string.
+      #
+      # @return [String, nil]
+      def quoted_id
+        self.class.connection.quote id if persisted? && (id.kind_of?(String) || id.kind_of?(Integer))
+      end
+
+      module ClassMethods
+        # @return [<String>]
+        def quoted_ids
+          ids.map { |id| connection.quote id }
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/lazy_ordering.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    module LazyOrdering
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # @param [Symbol] column
+        # @return [ActiveRecord::Relation]
+        def lazily_order(column, raw_direction = :asc)
+          base = lazy_order_scope_for column
+
+          expr = lazy_order_expr_for(column, raw_direction:)
+
+          base.order(expr)
+        end
+
+        def lazy_order_column_for(column)
+          method_name = :"#{column}_order_column"
+
+          if respond_to?(method_name)
+            public_send(method_name)
+          else
+            column
+          end.then { |expr| arel_attrify(expr) }
+        end
+
+        def lazy_order_expr_for(column, raw_direction: "asc")
+          direction = Hotstepper::Support::Types::SimpleSortDirection[raw_direction]
+
+          method_name = :"#{column}_order_expression"
+
+          if respond_to?(method_name)
+            public_send(method_name, direction:)
+          else
+            attr = lazy_order_column_for column
+
+            attr.public_send(direction)
+          end
+        end
+
+        # @param [Symbol] column
+        # @return [ActiveRecord::Relation]
+        def lazy_order_scope_for(column)
+          scope_name = :"prepare_order_for_#{column}"
+
+          if respond_to?(scope_name)
+            all.public_send(scope_name)
+          else
+            all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/limit_to_one.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    module LimitToOne
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # @raise [ActiveRecord::RecordNotFound]
+        # @raise [LimitToOne::TooManyMatches]
+        # @return [ApplicationRecord]
+        def only_one!
+          found_count = limit(2).count
+
+          raise TooManyMatches, "too many matches for scope" if found_count > 1
+
+          first!
+        end
+
+        # @raise [LimitToOne::TooManyMatches]
+        # @return [ApplicationRecord]
+        def only_one_or_initialize
+          found_count = limit(2).count
+
+          raise TooManyMatches, "too many matches for scope" if found_count > 1
+
+          first_or_initialize
+        end
+      end
+
+      # @api private
+      class TooManyMatches < StandardError; end
+    end
+  end
+end

data/lib/hotstepper/models/lookup_helpers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    module LookupHelpers
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def define_simple_lookup!(column_name, scope_name: :"lookup_by_#{column_name}")
+          scope scope_name, ->(input) { where(column_name => input) }
+        end
+
+        def define_simple_lookups!(*columns)
+          columns.each do |column_name|
+            define_simple_lookup! column_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/materialized_view.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # A concern for a materialized view-backed model.
+    #
+    # @see Hotstepper::Models::View
+    # @note It is intended to integrate with the Scenic gem.
+    module MaterializedView
+      extend ActiveSupport::Concern
+
+      include Hotstepper::Models::View
+
+      included do
+        extend Dry::Core::ClassAttributes
+
+        defines :refreshes_concurrently, type: Hotstepper::Support::Types::Bool
+
+        refreshes_concurrently true
+      end
+
+      module ClassMethods
+        # Checks whether the materialized view has been populated with data.
+        def populated? = Scenic.database.populated?(table_name)
+
+        # @return [void]
+        def refresh!(concurrently: refreshes_concurrently, cascade: false)
+          Scenic.database.refresh_materialized_view(table_name, concurrently:, cascade:)
+        end
+
+        # @api private
+        # @return [void]
+        def refreshes_concurrently!
+          refreshes_concurrently true
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/model.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # A concern that is included on `ActiveRecord::Base` models.
+    module Model
+      extend ActiveSupport::Concern
+
+      include AssociationHelpers
+      include ChecksBeforeDestruction
+      include IdQuoting
+      include LazyOrdering
+      include LimitToOne
+      include LookupHelpers
+      include Querying
+      include WhereMatches
+      include Hotstepper::Common::CallsOperation
+
+      included do
+        extend Hotstepper::ArelExt::Helpers
+        extend Hotstepper::Monadic::Decorators
+      end
+
+      module ClassMethods
+        # @api private
+        # @note Only used for tests
+        def default_factory
+          # :nocov:
+          model_name.i18n_key
+          # :nocov:
+        end
+
+        # @return [void]
+        def with_timestamp_scopes!
+          include TimestampScopes
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/models/querying.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # Generic querying helpers that don't fit in elsewhere.
+    module Querying
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Sometimes we need to get a count on something that has aggregations,
+        # `DISTINCT ON`, etc. This should handle most cases.
+        # @param [Boolean] strip_order
+        # @return [Integer]
+        def count_from_subquery(strip_order: false)
+          subquery = all
+
+          subquery = subquery.reorder(nil) if strip_order
+
+          unscoped.from(subquery).count
+        end
+
+        # @param [<ApplicationRecord>] records
+        # @return [ActiveRecord::Relation<ApplicationRecord>]
+        def limited_to(*records)
+          flattened = records.flatten
+
+          return all if flattened.blank?
+
+          id = flattened.filter_map do |record|
+            case record
+            when self then record.id
+            when ::Hotstepper::Support::Types::UUID, Hotstepper::Support::Types::Integer then record
+            end
+          end.uniq
+
+          id.blank? ? none : where(id:)
+        end
+
+        # @param [Integer, nil] number of records to return, or nil to return a single record
+        # @return [ApplicationRecord, ActiveRecord::Relation<ApplicationRecord>, nil]
+        def sample(num = nil)
+          randomized = reorder(Arel.sql("RANDOM()"))
+
+          if num.is_a?(Integer) && num >= 1
+            randomized.limit(num)
+          else
+            randomized.first
+          end
+        end
+
+        alias scoped_sample sample
+      end
+    end
+  end
+end

data/lib/hotstepper/models/timestamp_scopes.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # @note Not automatically included in {Hotstepper::Models::Model},
+    #   since not all models will have timestamps.
+    module TimestampScopes
+      extend ActiveSupport::Concern
+
+      included do
+        scope :in_recent_order, -> { order(created_at: :desc) }
+        scope :in_oldest_order, -> { order(created_at: :asc) }
+        scope :most_recently_updated, -> { order(updated_at: :desc) }
+        scope :least_recently_updated, -> { order(updated_at: :asc) }
+      end
+
+      module ClassMethods
+        # @return [ApplicationRecord, nil]
+        def latest = in_recent_order.first
+
+        # @return [ApplicationRecord, nil]
+        def oldest = in_oldest_order.first
+      end
+    end
+  end
+end

data/lib/hotstepper/models/view.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # A concern for a view-backed model.
+    #
+    # @see Hotstepper::Models::MaterializedView
+    module View
+      extend ActiveSupport::Concern
+
+      def readonly? = true
+    end
+  end
+end

data/lib/hotstepper/models/where_matches.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Models
+    # A concern for building `LIKE` / `ILIKE` queries.
+    module WhereMatches
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def where_matches(_wildcard: false, _escape: true, _case_sensitive: false, _or: false, **pairs)
+          counter = 0
+
+          pairs.reduce(all) do |scope, (column, value)|
+            counter += 1
+
+            next scope if value.blank?
+
+            conditions = arel_or_expressions value do |actual_value|
+              needle = wrap_like_value_in_wildcard(actual_value, _wildcard, escape: _escape)
+
+              arel_table[column].matches(needle, nil, _case_sensitive)
+            end
+
+            if _or && counter > 1
+              scope.or(scope.unscoped.where(conditions))
+            else
+              scope.where conditions
+            end
+          end
+        end
+
+        def where_like(_wildcard: :both, **pairs)
+          where_matches(**pairs, _wildcard:)
+        end
+
+        def where_contains(**pairs)
+          where_matches _wildcard: :both, **pairs
+        end
+
+        def where_begins_like(**pairs)
+          where_matches _wildcard: :end, **pairs
+        end
+
+        def where_ends_like(**pairs)
+          where_matches _wildcard: :start, **pairs
+        end
+
+        private
+
+        def wrap_like_value_in_wildcard(value, wildcard_type = :both, escape: true)
+          needle = escape ? value.to_s.gsub(?%, "\\%").gsub(?_, "\\_") : value
+
+          case wildcard_type
+          when :start
+            "%#{needle}"
+          when :end
+            "#{needle}%"
+          when :both
+            "%#{needle}%"
+          else
+            needle.to_s
+          end
+        end
+      end
+    end
+  end
+end