dry-operation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e5b39cd9624408d00958a649070927f493af015cd79d64815edeae30e2b82993
+  data.tar.gz: 9d12151f5a48051502dc88a7c7152819dd7a7baed354088c414f4e698e7ef28a
+SHA512:
+  metadata.gz: c57e54507bcf2f601a2f172a125da654f788b5481aa8d4b60e3025129cc6c88c270853947998ebf997fdae4f52833f6a06288115be9c3bd1678a34f4bc52f86f
+  data.tar.gz: 5baa6f1508f60b8bf64b3ea8409caec2fc58707e153373fbcecbd0dec6b2bcc8dc9e280d641d84501dbe52145c0be3237018fa99f05be958626aecdbf718081e

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2024 dry-rb team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,14 @@
+[gem]: https://rubygems.org/gems/dry-operation
+[actions]: https://github.com/dry-rb/dry-operation/actions
+
+# dry-operation [![Gem Version](https://badge.fury.io/rb/dry-operation.svg)][gem] [![Continuous Integration](https://github.com/dry-rb/dry-operation/actions/workflows/ci.yml/badge.svg)][actions]
+
+## Links
+
+* [User documentation](https://dry-rb.org/gems/dry-operation)
+* [API documentation](http://rubydoc.info/gems/dry-operation)
+* [Forum](https://discourse.dry-rb.org)
+
+## License
+
+See [`LICENSE`](LICENSE).

data/dry-operation.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.prepend(lib) unless $LOAD_PATH.include?(lib)
+require "dry/operation/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "dry-operation"
+  spec.version = Dry::Operation::VERSION
+  spec.authors = ["dry-rb team"]
+  spec.email = ["gems@dry-rb.org"]
+  spec.homepage = "https://dry-rb.org/gems/dry-operation"
+  spec.summary = "A domain specific language for composable business transaction workflows."
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/dry-rb/dry-operation/issues",
+    "changelog_uri" => "https://github.com/dry-rb/dry-operation/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://dry-rb.org/gems/dry-operation",
+    "funding_uri" => "https://github.com/sponsors/hanami",
+    "label" => "dry-operation",
+    "source_code_uri" => "https://github.com/dry-rb/dry-operation"
+  }
+
+  spec.required_ruby_version = ">= 3.1.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+  spec.add_dependency "dry-monads", "~> 1.6"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

data/lib/dry/operation/class_context/prepend_manager.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "dry/operation/errors"
+
+module Dry
+  class Operation
+    module ClassContext
+      # @api private
+      class PrependManager
+        def initialize(klass:, methods_to_prepend:, prepended_methods: [])
+          @klass = klass
+          @methods_to_prepend = methods_to_prepend
+          @prepended_methods = prepended_methods
+        end
+
+        def register(*methods)
+          ensure_pristine
+
+          already_defined_methods = methods & @klass.instance_methods(false)
+          if already_defined_methods.any?
+            raise MethodsToPrependAlreadyDefinedError.new(methods: already_defined_methods)
+          else
+            @methods_to_prepend = methods
+          end
+        end
+
+        def void
+          ensure_pristine
+
+          @methods_to_prepend = []
+        end
+
+        def call(method:)
+          return self unless @methods_to_prepend.include?(method)
+
+          @klass.include(StepsMethodPrepender.new(method: method))
+          @prepended_methods += [method]
+        end
+
+        def for_subclass(subclass)
+          self.class.new(
+            klass: subclass,
+            methods_to_prepend: @methods_to_prepend.dup,
+            prepended_methods: []
+          )
+        end
+
+        private
+
+        def ensure_pristine
+          return if @prepended_methods.empty?
+
+          raise PrependConfigurationError.new(methods: @prepended_methods)
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/class_context/steps_method_prepender.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "dry/operation/errors"
+
+module Dry
+  class Operation
+    module ClassContext
+      # @api private
+      class StepsMethodPrepender < Module
+        FAILURE_HOOK_METHOD_NAME = :on_failure
+
+        RESULT_HANDLER = lambda do |instance, method, result|
+          return if result.success? ||
+                    !(instance.methods + instance.private_methods).include?(
+                      FAILURE_HOOK_METHOD_NAME
+                    )
+
+          failure_hook = instance.method(FAILURE_HOOK_METHOD_NAME)
+          case failure_hook.arity
+          when 1
+            failure_hook.(result.failure)
+          when 2
+            failure_hook.(result.failure, method)
+          else
+            raise FailureHookArityError.new(hook: failure_hook)
+          end
+        end
+
+        def initialize(method:, result_handler: RESULT_HANDLER)
+          super()
+          @method = method
+          @result_handler = result_handler
+        end
+
+        def included(klass)
+          klass.prepend(mod)
+        end
+
+        private
+
+        def mod
+          @module ||= Module.new.tap do |mod|
+            module_exec(@result_handler) do |result_handler|
+              mod.define_method(@method) do |*args, **kwargs, &block|
+                steps do
+                  super(*args, **kwargs, &block)
+                end.tap do |result|
+                  result_handler.(self, __method__, result)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/class_context.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Dry
+  class Operation
+    # {Dry::Operation} class context
+    module ClassContext
+      # Default methods to be prepended unless changed via {.operate_on}
+      DEFAULT_METHODS_TO_PREPEND = [:call].freeze
+
+      # Configures the instance methods to be prepended
+      #
+      # The given methods will be prepended with a wrapper that calls {#steps}
+      # before calling the original method.
+      #
+      # This method must be called before defining any of the methods to be
+      # prepended or before prepending any other method.
+      #
+      # @param methods [Array<Symbol>] methods to prepend
+      # @raise [MethodsToPrependAlreadyDefinedError] if any of the methods have
+      #  already been defined in self
+      # @raise [PrependConfigurationError] if there's already a prepended method
+      def operate_on(*methods)
+        @_prepend_manager.register(*methods)
+      end
+
+      # Skips prepending any method
+      #
+      # This method must be called before any method is prepended.
+      #
+      # @raise [PrependConfigurationError] if there's already a prepended method
+      def skip_prepending
+        @_prepend_manager.void
+      end
+
+      # @api private
+      def inherited(klass)
+        super
+        if klass.superclass == Dry::Operation
+          ClassContext.directly_inherited(klass)
+        else
+          ClassContext.indirectly_inherited(klass)
+        end
+      end
+
+      # @api private
+      def self.directly_inherited(klass)
+        klass.extend(MethodAddedHook)
+        klass.instance_variable_set(
+          :@_prepend_manager,
+          PrependManager.new(klass: klass, methods_to_prepend: DEFAULT_METHODS_TO_PREPEND)
+        )
+      end
+
+      # @api private
+      def self.indirectly_inherited(klass)
+        klass.instance_variable_set(
+          :@_prepend_manager,
+          klass.superclass.instance_variable_get(:@_prepend_manager).for_subclass(klass)
+        )
+      end
+
+      # @api private
+      module MethodAddedHook
+        def method_added(method)
+          super
+
+          @_prepend_manager.call(method: method)
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Dry
+  class Operation
+    class Error < ::StandardError; end
+
+    # Methods to prepend have already been defined
+    class MethodsToPrependAlreadyDefinedError < Error
+      def initialize(methods:)
+        super <<~MSG
+          '.operate_on' must be called before the given methods are defined.
+          The following methods have already been defined: #{methods.join(", ")}
+        MSG
+      end
+    end
+
+    # Configuring prepending after a method has already been prepended
+    class PrependConfigurationError < Error
+      def initialize(methods:)
+        super <<~MSG
+          '.operate_on' and '.skip_prepending' can't be called after any methods\
+          in the class have already been prepended.
+          The following methods have already been prepended: #{methods.join(", ")}
+        MSG
+      end
+    end
+
+    # Missing dependency required by an extension
+    class MissingDependencyError < Error
+      def initialize(gem:, extension:)
+        super <<~MSG
+          To use the #{extension} extension, you first need to install the \
+          #{gem} gem. Please, add it to your Gemfile and run bundle install
+        MSG
+      end
+    end
+
+    class InvalidStepResultError < Error
+      def initialize(result:)
+        super <<~MSG
+          Your step must return `Success(..)` or `Failure(..)`, \
+          from `Dry::Monads::Result`. Instead, it was `#{result.inspect}`.
+        MSG
+      end
+    end
+
+    # An error related to an extension
+    class ExtensionError < ::StandardError; end
+
+    # Defined failure hook has wrong arity
+    class FailureHookArityError < ::StandardError
+      def initialize(hook:)
+        super <<~MSG
+          ##{hook.name} must accept 1 (failure) or 2 (failure, method name) \
+          arguments, but its arity is #{hook.arity}
+        MSG
+      end
+    end
+  end
+end

data/lib/dry/operation/extensions/active_record.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+begin
+  require "active_record"
+rescue LoadError
+  raise Dry::Operation::MissingDependencyError.new(gem: "activerecord", extension: "ActiveRecord")
+end
+
+module Dry
+  class Operation
+    module Extensions
+      # Add ActiveRecord transaction support to operations
+      #
+      # When this extension is included, you can use a `#transaction` method
+      # to wrap the desired steps in an ActiveRecord transaction. If any of the steps
+      # returns a `Dry::Monads::Result::Failure`, the transaction will be rolled
+      # back and, as usual, the rest of the flow will be skipped.
+      #
+      # ```ruby
+      # require "dry/operation/extensions/active_record"
+      #
+      # class MyOperation < Dry::Operation
+      #   include Dry::Operation::Extensions::ActiveRecord
+      #
+      #   def call(input)
+      #     attrs = step validate(input)
+      #     user = transaction do
+      #       new_user = step persist(attrs)
+      #       step assign_initial_role(new_user)
+      #       new_user
+      #     end
+      #     step notify(user)
+      #     user
+      #   end
+      #
+      #   # ...
+      # end
+      # ```
+      #
+      # By default, the `ActiveRecord::Base` class will be used to initiate the transaction.
+      # You can change this when including the extension:
+      #
+      # ```ruby
+      # include Dry::Operation::Extensions::ActiveRecord[User]
+      # ```
+      #
+      # Or you can change it at runtime:
+      #
+      # ```ruby
+      # user = transaction(user) do
+      #   # ...
+      # end
+      # ```
+      #
+      # This is useful when you use multiple databases with ActiveRecord.
+      #
+      # The extension can be initiated with default options for the transaction.
+      # It will be applied to all transactions:
+      #
+      # ```ruby
+      # include Dry::Operation::Extensions::ActiveRecord[requires_new: true]
+      # ```
+      #
+      # You can override these options at runtime:
+      #
+      # ```ruby
+      # transaction(requires_new: false) do
+      #   # ...
+      # end
+      #
+      # WARNING: Be aware that the `:requires_new` option is not yet supported.
+      #
+      # @see https://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html
+      # @see https://guides.rubyonrails.org/active_record_multiple_databases.html
+      module ActiveRecord
+        DEFAULT_CONNECTION = ::ActiveRecord::Base
+
+        def self.included(klass)
+          klass.include(self[])
+        end
+
+        # Include the extension providing a custom class/object to initialize the transaction
+        # and default options.
+        #
+        # @param connection [ActiveRecord::Base, #transaction] the class/object to use
+        # @param options [Hash] additional options for the ActiveRecord transaction
+        def self.[](connection = DEFAULT_CONNECTION, **options)
+          Builder.new(connection, **options)
+        end
+
+        # @api private
+        class Builder < Module
+          def initialize(connection, **options)
+            super()
+            @connection = connection
+            @options = options
+          end
+
+          def included(klass)
+            class_exec(@connection, @options) do |default_connection, options|
+              # @!method transaction(connection = ActiveRecord::Base, **options, &steps)
+              #   Wrap the given steps in an ActiveRecord transaction.
+              #
+              #   If any of the steps returns a `Dry::Monads::Result::Failure`, the
+              #   transaction will be rolled back and `:halt` will be thrown with the
+              #   failure as its value.
+              #
+              #   @param connection [#transaction] The class/object to use
+              #   @param options [Hash] Additional options for the ActiveRecord transaction
+              #   @yieldreturn [Object] the result of the block
+              #   @see Dry::Operation#steps
+              #   @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/DatabaseStatements.html#method-i-transaction
+              klass.define_method(:transaction) do |connection = default_connection, **opts, &steps|
+                intercepting_failure do
+                  result = nil
+                  connection.transaction(**options.merge(opts)) do
+                    intercepting_failure(->(failure) {
+                                           result = failure
+                                           raise ::ActiveRecord::Rollback
+                                         }) do
+                      result = steps.()
+                    end
+                  end
+                  result
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/extensions/rom.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+begin
+  require "rom-sql"
+rescue LoadError
+  raise Dry::Operation::MissingDependencyError.new(gem: "rom-sql", extension: "ROM")
+end
+
+module Dry
+  class Operation
+    module Extensions
+      # Add rom transaction support to operations
+      #
+      # When this extension is included, you can use a `#transaction` method
+      # to wrap the desired steps in a rom transaction. If any of the steps
+      # returns a `Dry::Monads::Result::Failure`, the transaction will be rolled
+      # back and, as usual, the rest of the flow will be skipped.
+      #
+      # The extension expects the including class to give access to the rom
+      # container via a `#rom` method.
+      #
+      # ```ruby
+      # require "dry/operation/extensions/rom"
+      #
+      # class MyOperation < Dry::Operation
+      #   include Dry::Operation::Extensions::ROM
+      #
+      #   attr_reader :rom
+      #
+      #   def initialize(rom:)
+      #     @rom = rom
+      #   end
+      #
+      #   def call(input)
+      #     attrs = step validate(input)
+      #     user = transaction do
+      #       new_user = step persist(attrs)
+      #       step assign_initial_role(new_user)
+      #       new_user
+      #     end
+      #     step notify(user)
+      #     user
+      #   end
+      #
+      #   # ...
+      # end
+      # ```
+      #
+      # By default, the `:default` gateway will be used. You can change this
+      # when including the extension:
+      #
+      # ```ruby
+      # include Dry::Operation::Extensions::ROM[gateway: :my_gateway]
+      # ```
+      #
+      # Or you can change it at runtime:
+      #
+      # ```ruby
+      # user = transaction(gateway: :my_gateway) do
+      #  # ...
+      # end
+      # ```
+      #
+      # @see https://rom-rb.org
+      module ROM
+        DEFAULT_GATEWAY = :default
+
+        # @!method transaction(gateway: DEFAULT_GATEWAY, &steps)
+        #  Wrap the given steps in a rom transaction.
+        #
+        #  If any of the steps returns a `Dry::Monads::Result::Failure`, the
+        #  transaction will be rolled back and `:halt` will be thrown with the
+        #  failure as its value.
+        #
+        #  @yieldreturn [Object] the result of the block
+        #  @raise [Dry::Operation::ExtensionError] if the including
+        #    class doesn't define a `#rom` method.
+        #  @see Dry::Operation#steps
+
+        def self.included(klass)
+          klass.include(self[])
+        end
+
+        # Include the extension providing a custom gateway
+        #
+        # @param gateway [Symbol] the rom gateway to use
+        def self.[](gateway: DEFAULT_GATEWAY)
+          Builder.new(gateway: gateway)
+        end
+
+        # @api private
+        class Builder < Module
+          def initialize(gateway:)
+            super()
+            @gateway = gateway
+          end
+
+          def included(klass)
+            class_exec(@gateway) do |default_gateway|
+              klass.define_method(:transaction) do |gateway: default_gateway, &steps|
+                raise Dry::Operation::ExtensionError, <<~MSG unless respond_to?(:rom)
+                  When using the ROM extension, you need to define a #rom method \
+                  that returns the ROM container
+                MSG
+
+                intercepting_failure do
+                  result = nil
+                  rom.gateways[gateway].transaction do |t|
+                    intercepting_failure(->(failure) {
+                                           result = failure
+                                           t.rollback!
+                                         }) do
+                      result = steps.()
+                    end
+                  end
+                  result
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/extensions/sequel.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+begin
+  require "sequel"
+rescue LoadError
+  raise Dry::Operation::MissingDependencyError.new(gem: "sequel", extension: "Sequel")
+end
+
+module Dry
+  class Operation
+    module Extensions
+      # Add Sequel transaction support to operations
+      #
+      # When this extension is included, you can use a `#transaction` method
+      # to wrap the desired steps in a Sequel transaction. If any of the steps
+      # returns a `Dry::Monads::Result::Failure`, the transaction will be rolled
+      # back and, as usual, the rest of the flow will be skipped.
+      #
+      # The extension expects the including class to give access to the Sequel
+      # database object via a `#db` method.
+      #
+      # ```ruby
+      # class MyOperation < Dry::Operation
+      #   include Dry::Operation::Extensions::Sequel
+      #
+      #   attr_reader :db
+      #
+      #   def initialize(db:)
+      #     @db = db
+      #   end
+      #
+      #   def call(input)
+      #     attrs = step validate(input)
+      #     user = transaction do
+      #       new_user = step persist(attrs)
+      #       step assign_initial_role(new_user)
+      #       new_user
+      #     end
+      #     step notify(user)
+      #     user
+      #   end
+      #
+      #   # ...
+      # end
+      # ```
+      #
+      # By default, no options are passed to the Sequel transaction. You can
+      # change this when including the extension:
+      #
+      # ```ruby
+      # include Dry::Operation::Extensions::Sequel[isolation: :serializable]
+      # ```
+      #
+      # Or you can change it at runtime:
+      #
+      # ```ruby
+      # transaction(isolation: :serializable) do
+      #   # ...
+      # end
+      # ```
+      #
+      # WARNING: Be aware that the `:savepoint` option is not yet supported.
+      #
+      # @see http://sequel.jeremyevans.net/rdoc/files/doc/transactions_rdoc.html
+      module Sequel
+        def self.included(klass)
+          klass.include(self[])
+        end
+
+        # Include the extension providing default options for the transaction.
+        #
+        # @param options [Hash] additional options for the Sequel transaction
+        def self.[](options = {})
+          Builder.new(**options)
+        end
+
+        # @api private
+        class Builder < Module
+          def initialize(**options)
+            super()
+            @options = options
+          end
+
+          def included(klass)
+            class_exec(@options) do |default_options|
+              klass.define_method(:transaction) do |**opts, &steps|
+                raise Dry::Operation::ExtensionError, <<~MSG unless respond_to?(:db)
+                  When using the Sequel extension, you need to define a #db method \
+                  that returns the Sequel database object
+                MSG
+
+                intercepting_failure do
+                  result = nil
+                  db.transaction(**default_options.merge(opts)) do
+                    intercepting_failure(->(failure) {
+                      result = failure
+                      raise ::Sequel::Rollback
+                    }) do
+                      result = steps.()
+                    end
+                  end
+                  result
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/operation/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Dry
+  class Operation
+    VERSION = "1.0.0"
+  end
+end

data/lib/dry/operation.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "dry/monads"
+require "dry/operation/errors"
+
+module Dry
+  # DSL for chaining operations that can fail
+  #
+  # {Dry::Operation} is a thin DSL wrapping dry-monads that allows you to chain
+  # operations by focusing on the happy path and short-circuiting on failure.
+  #
+  # The canonical way of using it is to subclass {Dry::Operation} and define
+  # your flow in the `#call` method. Individual operations can be called with
+  # {#step}. They need to return either a success or a failure result.
+  # Successful results will be automatically unwrapped, while a failure will
+  # stop further execution of the method.
+  #
+  # ```ruby
+  # class MyOperation < Dry::Operation
+  #   def call(input)
+  #     attrs = step validate(input)
+  #     user = step persist(attrs)
+  #     step notify(user)
+  #     user
+  #   end
+  #
+  #   def validate(input)
+  #    # Dry::Monads::Result::Success or Dry::Monads::Result::Failure
+  #   end
+  #
+  #   def persist(attrs)
+  #    # Dry::Monads::Result::Success or Dry::Monads::Result::Failure
+  #   end
+  #
+  #   def notify(user)
+  #    # Dry::Monads::Result::Success or Dry::Monads::Result::Failure
+  #   end
+  # end
+  #
+  # include Dry::Monads[:result]
+  #
+  # case MyOperation.new.call(input)
+  # in Success(user)
+  #   puts "User #{user.name} created"
+  # in Failure[:invalid_input, validation_errors]
+  #   puts "Invalid input: #{validation_errors}"
+  # in Failure(:database_error)
+  #   puts "Database error"
+  # in Failure(:email_error)
+  #   puts "Email error"
+  # end
+  # ```
+  #
+  # Under the hood, the `#call` method is decorated to allow skipping the rest
+  # of its execution when a failure is encountered. You can choose to use another
+  # method with {ClassContext#operate_on} (which also accepts a list of methods):
+  #
+  # ```ruby
+  # class MyOperation < Dry::Operation
+  #   operate_on :run # or operate_on :run, :call
+  #
+  #   def run(input)
+  #     attrs = step validate(input)
+  #     user = step persist(attrs)
+  #     step notify(user)
+  #     user
+  #   end
+  #
+  #   # ...
+  # end
+  # ```
+  #
+  # As you can see, the aforementioned behavior allows you to write your flow
+  # in a linear fashion. Failures are mostly handled locally by each individual
+  # operation. However, you can also define a global failure handler by defining
+  # an `#on_failure` method. It will be called with the wrapped failure value
+  # and, in the case of accepting a second argument, the name of the method that
+  # defined the flow:
+  #
+  # ```ruby
+  # class MyOperation < Dry::Operation
+  #   def call(input)
+  #     attrs = step validate(input)
+  #     user = step persist(attrs)
+  #     step notify(user)
+  #     user
+  #   end
+  #
+  #   def on_failure(user) # or def on_failure(failure_value, method_name)
+  #     log_failure(user)
+  #   end
+  # end
+  # ```
+  #
+  # You can opt out altogether of this behavior via {ClassContext#skip_prepending}. If so,
+  # you manually need to wrap your flow within the {#steps} method and manually
+  # handle global failures.
+  #
+  # ```ruby
+  # class MyOperation < Dry::Operation
+  #   skip_prepending
+  #
+  #   def call(input)
+  #     steps do
+  #       attrs = step validate(input)
+  #       user = step persist(attrs)
+  #       step notify(user)
+  #       user
+  #     end.tap do |result|
+  #       log_failure(result.failure) if result.failure?
+  #     end
+  #   end
+  #
+  #   # ...
+  # end
+  # ```
+  #
+  # The behavior configured by {ClassContext#operate_on} and {ClassContext#skip_prepending} is
+  # inherited by subclasses.
+  #
+  # Some extensions are available under the `Dry::Operation::Extensions`
+  # namespace, providing additional functionality that can be included in your
+  # operation classes.
+  class Operation
+    def self.loader
+      @loader ||= Zeitwerk::Loader.new.tap do |loader|
+        root = File.expand_path "..", __dir__
+        loader.inflector = Zeitwerk::GemInflector.new("#{root}/dry/operation.rb")
+        loader.tag = "dry-operation"
+        loader.push_dir root
+        loader.ignore(
+          "#{root}/dry/operation/errors.rb",
+          "#{root}/dry/operation/extensions/*.rb"
+        )
+        loader.inflector.inflect("rom" => "ROM")
+      end
+    end
+    loader.setup
+
+    FAILURE_TAG = :halt
+    private_constant :FAILURE_TAG
+
+    extend ClassContext
+    include Dry::Monads::Result::Mixin
+
+    # Wraps block's return value in a {Dry::Monads::Result::Success}
+    #
+    # Catches `:halt` and returns it
+    #
+    # @yieldreturn [Object]
+    # @return [Dry::Monads::Result::Success]
+    # @see #step
+    def steps(&block)
+      catching_failure { Success(block.call) }
+    end
+
+    # Unwraps a {Dry::Monads::Result::Success}
+    #
+    # Throws `:halt` with a {Dry::Monads::Result::Failure} on failure.
+    #
+    # @param result [Dry::Monads::Result]
+    # @return [Object] wrapped value
+    # @see #steps
+    def step(result)
+      if result.is_a?(Dry::Monads::Result)
+        result.value_or { throw_failure(result) }
+      else
+        raise InvalidStepResultError.new(result: result)
+      end
+    end
+
+    # Invokes a callable in case of block's failure
+    #
+    # This method is useful when you want to perform some side-effect when a
+    # failure is encountered. It's meant to be used within the {#steps} block
+    # commonly wrapping a sub-set of {#step} calls.
+    #
+    # @param handler [#call] a callable that will be called with the encountered failure.
+    #   By default, it throws `FAILURE_TAG` with the failure.
+    # @yieldreturn [Object]
+    # @return [Object] the block's return value when it's not a failure or the handler's
+    #   return value when the block returns a failure
+    def intercepting_failure(handler = method(:throw_failure), &block)
+      output = catching_failure(&block)
+
+      case output
+      when Failure
+        handler.(output)
+      else
+        output
+      end
+    end
+
+    # Throws `:halt` with a failure
+    #
+    # @param failure [Dry::Monads::Result::Failure]
+    def throw_failure(failure)
+      throw FAILURE_TAG, failure
+    end
+
+    private
+
+    def catching_failure(&block)
+      catch(FAILURE_TAG, &block)
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: dry-operation
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- dry-rb team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description:
+email:
+- gems@dry-rb.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- dry-operation.gemspec
+- lib/dry/operation.rb
+- lib/dry/operation/class_context.rb
+- lib/dry/operation/class_context/prepend_manager.rb
+- lib/dry/operation/class_context/steps_method_prepender.rb
+- lib/dry/operation/errors.rb
+- lib/dry/operation/extensions/active_record.rb
+- lib/dry/operation/extensions/rom.rb
+- lib/dry/operation/extensions/sequel.rb
+- lib/dry/operation/version.rb
+homepage: https://dry-rb.org/gems/dry-operation
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/dry-rb/dry-operation/issues
+  changelog_uri: https://github.com/dry-rb/dry-operation/blob/main/CHANGELOG.md
+  documentation_uri: https://dry-rb.org/gems/dry-operation
+  funding_uri: https://github.com/sponsors/hanami
+  label: dry-operation
+  source_code_uri: https://github.com/dry-rb/dry-operation
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A domain specific language for composable business transaction workflows.
+test_files: []