hotstepper 0.1.0

data/lib/hotstepper/monadic/coercion.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Monadic
+    module Coercion
+      include Dry::Monads[:maybe, :result, :validated]
+
+      # @api private
+      NO_ARG = Object.new.freeze
+
+      # @param [Object] input
+      # @param [:maybe, :result, :validated] mode
+      # @return [Dry::Monads::Maybe, Dry::Monads::Result, Dry::Monads::Validated]
+      def call(input, mode:)
+        case mode
+        in :maybe
+          coerce_to_maybe(input)
+        in :result
+          coerce_to_result(input)
+        in :validated
+          coerce_to_validated(input)
+        else
+          # :nocov:
+          raise ArgumentError, "invalid mode #{mode.inspect}"
+          # :nocov:
+        end
+      end
+
+      # @param [Object] input
+      # @yieldreturn [Object] the value to be converted to a monad (if necessary)
+      # @return [Dry::Monads::Maybe, Dry::Monads::Result, Dry::Monads::Validated]
+      def enforce(input = NO_ARG, mode:)
+        if input.equal?(NO_ARG)
+          # :nocov:
+          raise ArgumentError, "no argument given and no block provided" unless block_given?
+          # :nocov:
+
+          return call(yield, mode:)
+        end
+
+        call(input, mode:)
+      end
+
+      def to_maybe(input = NO_ARG, &) = enforce(input, mode: :maybe, &)
+
+      def to_result(input = NO_ARG, &) = enforce(input, mode: :result, &)
+
+      def to_validated(input = NO_ARG, &) = enforce(input, mode: :validated, &)
+
+      private
+
+      # @param [Object] input
+      # @return [Dry::Monads::Maybe]
+      def coerce_to_maybe(input)
+        return input if input.kind_of?(Dry::Monads::Maybe)
+
+        input.to_monad.then do |monad|
+          return monad if monad.kind_of?(Dry::Monads::Maybe)
+
+          return coerce_to_maybe(monad) if monad != input
+        end if input.respond_to?(:to_monad)
+
+        input.to_maybe.then do |maybe|
+          return maybe if maybe.kind_of?(Dry::Monads::Maybe)
+        end if input.respond_to?(:to_maybe)
+
+        Maybe(input)
+      end
+
+      # @param [Object] input
+      # @return [Dry::Monads::Result]
+      def coerce_to_result(input)
+        return input if input.kind_of?(Dry::Monads::Result)
+
+        input.to_monad.then do |monad|
+          return monad if monad.kind_of?(Dry::Monads::Result)
+          return coerce_to_result(monad) if monad != input
+        end if input.respond_to?(:to_monad)
+
+        input.to_result.then do |result|
+          return result if result.kind_of?(Dry::Monads::Result)
+        end if input.respond_to?(:to_result)
+
+        Success input
+      end
+
+      # @param [Object] input
+      # @return [Dry::Monads::Validated]
+      def coerce_to_validated(input)
+        return input if input.kind_of?(Dry::Monads::Validated)
+
+        # Treat Nones as Invalids when coercing to Validated, since Validated doesn't have a concept of None.
+        return Invalid(:none) if input.kind_of?(Dry::Monads::Maybe) && input.none?
+
+        # Treat Somes as Valids when coercing to Validated, since Validated doesn't have a concept of Some.
+        return Valid(input.value!) if input.kind_of?(Dry::Monads::Maybe) && input.some?
+
+        input.to_monad.then do |monad|
+          return monad if monad.kind_of?(Dry::Monads::Validated)
+          return coerce_to_validated(monad) if monad != input
+        end if input.respond_to?(:to_monad)
+
+        input.to_validated.then do |validated|
+          return validated if validated.kind_of?(Dry::Monads::Validated)
+        end if input.respond_to?(:to_validated)
+
+        Valid(input)
+      end
+    end
+  end
+end

data/lib/hotstepper/monadic/decorators.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Monadic
+    # A concern that should be `extend`ed on classes to define monadic operations
+    # on them. It is used to DRY up the definition of `!` methods for monadic
+    # operations, matchers, and validatators.
+    module Decorators
+      ON_VALID_RESULT = proc {}
+
+      private_constant :ON_VALID_RESULT
+
+      # @param [Symbol] method_name
+      # @param [Class] with a Dry::Matcher class
+      # @return [void]
+      def monadic_matcher!(method_name, with: Dry::Matcher::ResultMatcher)
+        include Dry::Matcher.for(method_name, with:)
+
+        monadic_operation!(method_name)
+      end
+
+      # @param [Symbol] method_name
+      # @return [void]
+      def monadic_operation!(method_name)
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{method_name}!(...)
+            #{method_name}(...).value!.then do |result|
+              Dry::Monads::Unit == result ? nil : result
+            end
+          end
+        RUBY
+      end
+
+      # @param [Symbol] method_name
+      # @return [void]
+      def monadic_validator!(method_name)
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{method_name}!(...)
+            enumerate_reasons = ->(reasons) do
+              reasons.to_a.each do |reason|
+                yield reason if block_given?
+              end
+            end
+
+            #{method_name}(...).either(
+              ON_VALID_RESULT,
+              enumerate_reasons
+            )
+          end
+        RUBY
+      end
+
+      class << self
+        # @return [void]
+        def included(base)
+          raise "This module is meant to be extended, not included"
+        end
+      end
+    end
+  end
+end

data/lib/hotstepper/monadic/do_for.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Monadic
+    # A module that gives you a `do_for!` decorator
+    module DoFor
+      # @param [Symbol] name
+      # @return [Symbol]
+      def do_for!(name)
+        include Dry::Monads::Do.for name
+
+        # If this is being called as a decorator, the method is already defined and dry-monad's
+        # method watcher won't fire. We trigger it manually.
+        if method_defined?(name) || protected_method_defined?(name) || private_method_defined?(name)
+          __send__(:method_added, name)
+        end
+
+        name
+      end
+    end
+  end
+end

data/lib/hotstepper/monadic.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Monadic helpers for service objects.
+  module Monadic
+    extend Hotstepper::Monadic::Coercion
+  end
+end

data/lib/hotstepper/operation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # @abstract
+  #
+  # A base class for defining an operation that takes its args
+  # and provides them to a specific service.
+  #
+  # The operation is automatically set up to support dry-matcher result matching.
+  #
+  # It allows services to be dependency-injected with dry-rails / dry-system.
+  class Operation
+    extend Dry::Core::ClassAttributes
+
+    defines :service_klass, type: Hotstepper::Support::Types::ServiceClass
+
+    service_klass Hotstepper::Support::NullService
+
+    # @return [Object] whatever the service class' call method returns,
+    #   which is often a `Dry::Monads::Result` of some kind.
+    def call(...) = self.class.service_klass.new(...).call
+
+    class << self
+      # @api private
+      # @return [void]
+      def set_up_matcher!
+        include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+      end
+
+      # @param [Class] klass
+      # @param [Boolean] with_matcher whether to set up `Dry::Matcher::ResultMatcher`
+      #   for fluent handling of the service's result.
+      # @return [void]
+      def wraps_service!(klass, with_matcher: false)
+        service_klass klass
+
+        set_up_matcher! if with_matcher
+      end
+    end
+  end
+end

data/lib/hotstepper/patterns.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Patterns
+    # @return [Regexp]
+    EMAIL = URI::MailTo::EMAIL_REGEXP
+
+    # @return [Regexp]
+    GlobalID = URI::DEFAULT_PARSER.make_regexp("gid")
+
+    # @return [Regexp]
+    HTTP = URI::DEFAULT_PARSER.make_regexp(/https?/)
+
+    # @return [Regexp]
+    HTTPS = URI::DEFAULT_PARSER.make_regexp("https")
+
+    # @return [Regexp]
+    STEP_NAME = /\A[a-zA-Z_]\w+[a-z0-9]*\z/
+  end
+end

data/lib/hotstepper/query_building.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # Methods for working directly with SQL queries in operations and services.
+  #
+  # To use this module, include it in your ruby class and then call the `sql_*` methods
+  # to execute SQL queries.
+  # * The `compile_*` methods can be used to build SQL query strings
+  #   from template strings
+  # * The `with_*` methods can be used to conditionally format SQL templates based
+  #   on the presence of their inputs
+  module QueryBuilding
+    extend ActiveSupport::Concern
+
+    included do
+      include Dry::Monads[:result]
+
+      delegate :quote_column_name, to: :connection
+    end
+
+    # @param [<String>] parts
+    # @return [void]
+    def sql_select!(*parts)
+      ApplicationRecord.uncached do
+        connection.exec_query compile_query(*parts)
+      end
+    end
+
+    alias sql_exec! sql_select!
+
+    # @param [<String>] parts
+    # @return [void]
+    def sql_insert!(*parts)
+      # We use exec_query instead of exec_insert,
+      # because we want control over RETURNING
+      connection.exec_query compile_query(*parts)
+    ensure
+      clear_query_cache!
+    end
+
+    # @param [<String>] parts
+    # @return [Integer]
+    def sql_update!(*parts)
+      connection.exec_update compile_query(*parts)
+    ensure
+      clear_query_cache!
+    end
+
+    # @param [<String>] parts
+    # @return [Integer]
+    def sql_delete!(*parts)
+      connection.exec_delete compile_query(*parts)
+    ensure
+      clear_query_cache!
+    end
+
+    # @param [Symbol] table_name
+    # @return [Arel::Table]
+    def arel_table_for(table_name) = Arel::Table.new(table_name)
+
+    # @api private
+    # @return [ActiveRecord::ConnectionAdapters::PostgreSQLAdapter]
+    def connection = Hotstepper.config.db.connection_class.connection
+
+    # Join components of a query with the separator value in `join_with`.
+    #
+    # @param [<String>] parts
+    # @param [String] join_with
+    # @param [Boolean] prefix
+    # @return [String]
+    def compile_query(*parts, join_with: " ", prefix_with: join_with, prefix: false)
+      compiled = parts.flatten.compact_blank.join(join_with).strip
+
+      return compiled unless prefix && compiled.present?
+
+      "#{prefix_with.presence || join_with}#{compiled}"
+    end
+
+    # Join components of a query with ` AND `.
+    #
+    # @param [<String>] parts
+    # @param [Boolean] prefix
+    # @return [String]
+    def compile_and(*parts, prefix: false, **options) = compile_query(*parts, **options, join_with: " AND ", prefix:)
+
+    # Join components of a query with ` OR `.
+    #
+    # @param [<String>] parts
+    # @param [Boolean] prefix
+    # @return [String]
+    def compile_or(*parts, prefix: false, **options) = compile_query(*parts, **options, join_with: " OR ", prefix:)
+
+    # Provide the quoted model id as a formatting argument
+    # to the `template`.
+    #
+    # @param [ApplicationRecord] model
+    # @param [String] template
+    # @return [String]
+    def with_quoted_id_for(model, template)
+      return "" if model.blank? || model.new_record? || model.destroyed?
+
+      with_sql_template template, model.quoted_id
+    end
+
+    # @param [#to_s] prefix
+    # @param [<String>, String] id_or_ids
+    # @param [#to_s] column
+    # @return [String]
+    def with_quoted_id_or_ids_on(prefix, id_or_ids, column: :id)
+      case id_or_ids
+      when ::Hotstepper::Support::Types::UUIDList
+        arel_table_for(prefix)[column].in(id_or_ids).to_sql
+      when ::Hotstepper::Support::Types::UUID
+        arel_table_for(prefix)[column].eq(id_or_ids).to_sql
+      else
+        ""
+      end
+    end
+
+    # @param [String] template
+    # @param [<Object>] values format values for `String#%`
+    # @return [String]
+    def with_sql_template(template, *values)
+      formatted = template % values
+
+      cleanup_query formatted
+    end
+
+    private
+
+    # @param [String] sql
+    # @return [String]
+    def cleanup_query(sql)
+      sql.strip_heredoc.squish
+    end
+
+    # @return [void]
+    def clear_query_cache!
+      connection.clear_query_cache
+    end
+  end
+end

data/lib/hotstepper/service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # @abstract
+  class Service
+    extend ActiveModel::Callbacks
+    extend Dry::Core::ClassAttributes
+    extend Hotstepper::Monadic::DoFor
+
+    include Dry::Core::Constants
+    include Dry::Monads[:result, :maybe, :try]
+
+    include Hotstepper::Common::CallsOperation
+
+    defines :step_mapping, type: Hotstepper::Steps::Step::Map
+
+    step_mapping EMPTY_HASH
+
+    do_for! :call
+
+    define_model_callbacks :execute
+
+    # @return [Symbol]
+    attr_reader :current_step
+
+    def call
+      # :nocov:
+      raise NotImplementedError, "Subclasses of Hotstepper::Service must implement #call"
+      # :nocov:
+    end
+
+    # @api private
+    def inspect
+      # :nocov:
+      "#<#{self.class}>"
+      # :nocov:
+    end
+
+    # @api private
+    # @return [void]
+    def __run_step__(step_name)
+      @current_step = step_name
+
+      run_callbacks step_name do
+        Hotstepper::Monadic.to_result do
+          __send__(step_name)
+        end
+      end
+    ensure
+      @current_step = nil
+    end
+
+    class << self
+      # @param [Class] subclass
+      # @return [void]
+      def inherited(subclass)
+        super
+
+        subclass.include Dry::Monads::Do.for(:call)
+      end
+
+      # Defines a step on this service.
+      # @param [Symbol] name
+      # @return [Symbol]
+      # @!macro [attach] step!
+      #   @!method $1
+      #     The actual business logic of the step method.
+      #     @return [Dry::Monads::Result]
+      #   @!method $1!
+      #     A wrapper around {$1} that ensures its retval is monadic, runs callbacks,
+      #     and sets the current step.
+      #     @return [Dry::Monads::Result]
+      def step!(name)
+        step = Hotstepper::Steps::Step.new(name:)
+
+        new_mapping = step_mapping.merge(step.name => step).freeze
+
+        step_mapping new_mapping
+
+        include step.implementation
+      end
+    end
+  end
+end

data/lib/hotstepper/steps/abstract_module.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Steps
+    # @api private
+    # @abstract
+    class AbstractModule < Module
+      include Dry::Initializer[undefined: false].define -> do
+        param :step, Hotstepper::Steps::Step::Type
+      end
+
+      delegate :name, to: :step, prefix: true
+
+      def inspect
+        # :nocov:
+        "#{self.class}[#{step_name.inspect}]"
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/hotstepper/steps/implementation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Steps
+    # @api private
+    class Implementation < AbstractModule
+      def initialize(...)
+        super
+
+        @wrapper = Hotstepper::Steps::Wrapper.new(step)
+        @watcher = Hotstepper::Steps::Watcher.new(step)
+
+        define_methods!
+      end
+
+      def included(base)
+        super
+
+        base.include Dry::Monads::Do.for(step_name)
+        base.define_model_callbacks step_name
+        base.extend @watcher
+        base.prepend @wrapper
+      end
+
+      private
+
+      # @return [void]
+      def define_methods!
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{step_name} = Dry::Monads.Success()
+
+        def #{step_name}!
+          __run_step__(#{step_name.inspect})
+        end
+        RUBY
+      end
+    end
+  end
+end

data/lib/hotstepper/steps/step.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Steps
+    # A step is a single unit of work in a service. It is defined as a method on the service.
+    #
+    # @api private
+    class Step < Hotstepper::Struct
+      include Dry::Core::Equalizer.new(:name)
+      include Hotstepper::Typing
+
+      map_type!(key: Hotstepper::Support::Types::Symbol)
+
+      attribute :name, Hotstepper::Support::Types::StepName
+
+      # @return [Hotstepper::Steps::Implementation]
+      attr_reader :implementation
+
+      def initialize(...)
+        super
+
+        @implementation = Hotstepper::Steps::Implementation.new(self)
+      end
+    end
+  end
+end

data/lib/hotstepper/steps/watcher.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Steps
+    # A module that is included into the step class to apply the `Dry::Monads::Do`
+    # mixin onto it whenever the class is subclassed.
+    #
+    # @api private
+    class Watcher < Hotstepper::Steps::AbstractModule
+      def initialize(...)
+        super
+
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def inherited(subclass)
+          super
+
+          subclass.do_for! #{step_name.inspect}
+        end
+        RUBY
+      end
+    end
+  end
+end

data/lib/hotstepper/steps/wrapper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  module Steps
+    # A module that is prepended into the step class to watch for overrides
+    #
+    # @api private
+    class Wrapper < Hotstepper::Steps::AbstractModule
+      def prepended(base)
+        super
+
+        Dry::Monads::Do.wrap_method(self, step_name, :public)
+      end
+    end
+  end
+end

data/lib/hotstepper/struct.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hotstepper
+  # An opinionated dry-struct implementation that accepts stringified keys,
+  # and will apply defaults when explicitly passed `nil`
+  # on keys where applicable.
+  #
+  # @abstract
+  # @see https://dry-rb.org/gems/dry-struct/main/
+  class Struct < Dry::Struct
+    transform_keys(&:to_sym)
+
+    transform_types do |type|
+      if type.default?
+        type.constructor do |value|
+          value.nil? ? Dry::Types::Undefined : value
+        end
+      else
+        type
+      end
+    end
+
+    # @param [Array<Symbol, String>] keys
+    def slice(*keys)
+      keys.flatten.index_with { public_send _1 }
+    end
+
+    alias deconstruct_keys slice
+  end
+end